REST API - Create a ticket

Last modified on 2022/11/08 13:22
Contents

POST  /requests

  • It supports the creation of a single ticket per call.

Notes

   Open url.png  See Service Manager REST API Conventions.

  • You must supply a table in JSON format in the body of the HTTP request.
  • If successful, an HTTP status code 201 is returned and a URL link (HREF) to the created resource is provided.
  • From the version 2022 - Build 2022.1.109.0.03  An HTTP status code 406 is returned when the recipient of the ticket does not exist in the Service Manager database or if the recipient does not belong to one of the REST user's domains.
CommonNotes_JSONandFields

JSON Format / Field Format:

  • The field names are those of the Service Manager.data model.

example  available_field_1

  • To update a field, respect the following JSON format: "field_name":"value".
  • JSON object names, including those representing Service Manager database fields, are not case sensitive.

example  field_name, Field_Name and FIELD_NAME are equivalent

List of parameters / fields

Mandatory parameters

You must use at least one of the JSON objects below in the body of the HTTP request.

Notes:

  • The subject can be specified with catalog_guid (use in preference) or catalog_code.
  • If catalog_guid is wrong, the process stops without reading catalog_code.
     
Parameter Type Description / Example
catalog_guid string Identifier for the subject of the ticket
catalog_code string Code for the subject of the ticket

Optional parameters

None

Optional fields

  • Minimum version: Oxygen 2.1.2 - Build 2018.1.183.0  In addition to the fields provided by EasyVista, you can also assign values to the fields which you have added to the Service Manager database. These are fields with the prefix e_.
             example  e_field_name_xyz
  • You can only use the following fields from the SD_REQUEST table in the body of the HTTP request below.
     
Minimum version Parameter Type Description / Example
assetid, assettag, asset_name string Identifier / Tag / Asset name
  • The objects are processed in this priority order by the search algorithm.
ci_id, ci_asset_tag, ci_name string CI Identifier / Asset tag of the CI / CI name
  • The objects are processed in this priority order by the search algorithm.
department_id, department_code string Identifier / Department code of the requestor
  • The objects are processed in this priority order by the search algorithm.
description string Description of the object
Autumn 2020 - Build 2020.2.122.2 impact_id integer Impact of the object
external_reference string Identifier of the object attributed by an external application.
location_id, location_code string Identifier / Location code of the requestor
  • The objects are processed in this priority order by the search algorithm.
origin string Identifier of the origine (Examples: Phone, Email)
parentrequest string Identifier of the related request (parent request) attachede to the object
phone string Phone number of the requestor
recipient_id, recipient_identification, recipient_mail, recipient_name string Identifier / Employee number / Email address / Name of the recipient
  • The objects are processed in this priority order by the search algorithm.
requestor_identification, requestor_mail, requestor_name string Employee number / Email address / Name of the requestor
  • The objects are processed in this priority order by the search algorithm.
severity_id integer Identifier of the severity level
submit_date string Creation date of the object
  • By default, current date (now).
Oxygen 2.1.2 - Build 2018.1.183.0 title string Title of the ticket
urgency_id integer Identifier of the urgency level

Description of the actions carried out

1. A ticket is created (record in the SD_REQUEST table).

  • submit_date = now
  • If recipient_id is passed as a parameter:
    • location_id = location_id of the recipient_id
    • department_id = department_id of the recipient_id
    • requestor_phone = phone of the recipient_id
    • rfc_number ==> Get NewIncidentNumber
    • max_resolution_date_ut ==> calculateMaxResolution(SLA_id to be retrieved)
    • first_call_resolution ==> 0
    • status_id = Key status_id the GUID of which is {6e554fc1-1a5d-47e4-b303-cd98a8767aec} [12 - in general In progress]
  • If parentRequest is specified:
    • parentRequest_id specified (linked request)

2. A CALL action is created in the AM_ACTION table associated with the ticket.

  • request_id = request_id of the ticket which has just been created
  • doneBy_id = requestor_id of the ticket which has just been created
  • creation_date_ut = start_date_ut = end_date_ut = SD_REQUEST.submit_date
  • action_type_id = 7
  • AM_ACTION.contact_id = SD_REQUEST.requestor_id

3. The workflow associated with the ticket is started.

  • The workflow_id is recovered following the same mechanism as the SLA_id (managed overloads and tree structures).

HTTP status codes for the method

StatusHeader

Note: A Timeout error code will be returned if the server does not respond to the REST Web service request within a given time (by default 60 seconds).

Code Error Description
Status201
201 Created Request processed successfully and an item created.
Status401
401 Unauthorized Authentication process for accessing the resource is incorrect: Login/Password incorrect, Invalid session, Incorrect Service Manager account.

example

{
 "error": "Invalid Login / Password"
}
Status406
406 Not acceptable Resource not available in a format complying with the Accept headers of the request. Note: The exchange format of the Service Manager REST API is JSON.

or

From the version 2022 - Build 2022.1.109.0.03 Call of the Create a ticket method when the recipient of the ticket does not exist in the Service Manager database or if the recipient does not belong to one of the REST user's domains.
Status500
500 Internal Server Error Generic error message displayed when an unexpected condition is encountered and there is no appropriate message which is more specific.<

example

{
 "error": "An error occured. A text message is returned in the body."
}

Examples

Example of the body of an HTTP request

{
   "requests" :
    [{
     "Catalog_Code" : "46",
     "AssetID" : "",
     "AssetTag" : "",
     "ASSET_NAME" : "",
     "Urgency_ID" : "1",
     "Severity_ID" : "40",
     "External_reference" : "",
     "Phone" : "93-63 - 65-23",
     "Requestor_Identification" : "",
     "Requestor_Mail" : "morley@itassetservices.com",
     "Requestor_Name" : "",
     "Location_ID" : "",
     "Location_Code" : "",
     "Department_ID" : "",
     "Department_Code" : "",
     "Recipient_ID" : "",
     "Recipient_Identification" : "",
     "Recipient_Mail" : "leblanc@itassetservices.com",
     "Recipient_Name" : "",
     "Origin" : "3",
     "Description" : "Request created via REST API",
     "ParentRequest" : "",
     "CI_ID" : "",
     "CI_ASSET_TAG" : "",
     "CI_NAME" : "",
     "SUBMIT_DATE" : ""
    }]
}

Result with a status code 201 returned

{
 "HREF": "https://{your_server}/api/v1/{your_account}/requests/I161019_000003"
}
ConventionsAPI

REST API Conventions

Convention Meaning
Orange Parameters used in an HTTP request string which do not correspond to Service Manager database fields.

example   Method View a list of assets

https://{your_server}/api/v1/{your_account}/assets?max_rows=3&fields=asset_tag
Black and Bold Parameters used in the URL of an HTTP request which correspond to Service Manager database fields.

example   Method View an asset

https://{your_server}/api/v1/{your_account}/assets/{asset_id}
Green Parameters used in the body of an HTTP request which represent JSON object names corresponding to Service Manager database fields; they allow the value of a database field to be assigned or modified.

example   Method Close an incident/request

{  "closed": {  "end_date": "11/20/2016 12:12:12",  }  }
Parameters used in the body of an HTTP request which represent JSON object names not corresponding to Service Manager database fields.

example   Method Reopen an incident/request

{  "restarted": {  "comment": "string (required)"  }  }
Tags :
Powered by XWiki © EasyVista 2022