REST API - Close a ticket

Last modified on 2023/07/06 16:13
Contents

PUT  /requests/{rfc_number}

  • The associated workflow is stopped.
  • Any further modification is impossible.

Notes

       Open url.png  See Service Manager REST API Conventions

  • If successful, an HTTP status code 201 is returned and a URL link (HREF) to the modified resource is supplied.
     
  • You must supply a table in JSON format in the body of the HTTP request.
  • You must use a closed object whose value is a set of JSON objects (name/value pairs).
  • If no value is specified, the default meta-status Closed (Status_GUID: C3D9DFA7-7A21-46C2-B3A3-8BC50C9FF4F3) is applied.
  • To apply a status other than the meta-status Closed, you can use the object called Status_GUID for the value of the closed object, with the number (code) of the Status_GUID you want to apply as the value.
          example   Application of Solved status ==>  Status_GUID: DC97DD1D-0F35-4153-B0E1-0F2E0155365D
  • You must provide a valid status number (code).
  • The closing date of the ticket must always be equal to the current date, i.e. the date on which the method was used.
  • You can specify a different closing date for open actions that are associated with the ticket and the anticipated closing date using the end_date object.
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 the parameter below in the URL.
 

Parameter Type Description / Example
rfc_number string Ticket number

Optional parameters

You can use the JSON objects detailed below in the HTTP request string.
 

Parameter Type Description / Example
catalog_guid string Identifier of the topic of the ticket. Required if the ticket needs to be requalified before closing: used to specify the sd_catalog_id parameter.
comment string Comment explaining the closing of the ticket.
delete_actions boolean Used to indicate the measures to be taken for ongoing actions in the ticket.
  • True: Delete the actions
  • False (by default): Do not delete the actions
end_date string Closing date of open actions associated with the ticket and the anticipated closure action. By default, the current date (now). Note: The closing date of the ticket is always the current date, i.e. the date on which the method was called. It cannot be modified.
status_guid string Identifier (GUID) of the final status of the ticket. By default, Closed status.

Description of the actions carried out

1. The workflow of the ticket is interrupted.

  • workflowstop function, with rfc_number passed as a parameter
  • action_id is not necessary as the internal localworkflowStop function only requires a request_id which is found from the rfc_number

2. The status of the ticket is modified.

  • New status = Status_GUID passed as a parameter

3. The unfinished actions associated with the ticket are deleted.

  • end_date_ut = NULL if and only if delete_actions = True

4. An anticipated closing action associated with the ticket is inserted.

  • start_date_ut and end_date_ut = closing date passed as a parameter or now if no parameter
  • doneBy_id = logged-on user or doneBy passed as a parameter
  • action_type = (GUID = 79f03131-1d69-4f7b-8b63-547add64a157)

HTTP status codes for the method

StatusHeader

   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 successfully processed and element created.
Status401
401 Unauthorized Incorrect authentication process for accessing the resource: Incorrect login/password, invalid session, incorrect Service Manager account.

example

{
 "error": "Invalid Login / Password"
}
Status404
404 Not found Resource not found: Incorrect URI, missing resource, incorrect communication with the server, rfc_number not found.

example

{
 "error": "Resource not found"
}
Status405
405 Method not allowed Unauthorized request method, i.e. it is not supported or not appropriate for the resource.

example

{
 "error": "Invalid input parameter"
}

Examples

Examples of the body of an HTTP request

  • No value specified for the Status_GUID field ==> application of the meta-status Closed:
{
 "closed": {
   "end_date": "11/20/2016 12:12:12",
   "catalog_GUID": "0F05FE8E-E487-4449-888E-2A7C066EC205",
   "delete_actions": 1,
   "comment": "Closed via REST API"
  }
}
  • For the Solved status, of the meta-status Closed:
{
 "closed": {
   "status_GUID": "DC97DD1D-0F35-4153-B0E1-0F2E0155365D",
   "end_date": "11/20/2016 12:12:12",
   "catalog_GUID": "0F05FE8E-E487-4449-888E-2A7C066EC205",
   "delete_actions": 1,
   "comment": "Closed via REST API"
  }
}

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