API contracts for ITSM Integration

API to create a ticket.

HTTP POST

Request JSON - {"connectionDetails":{},"ticketJSON":{}, "ticketFields":[],"itsmTimeZoneOffset":""}

Response JSON - {"statusCode":"", "statusMessage":"", "ticketDetails":{}}

Request Fields

• connectionDetails - JSON field that will contain key/value pairs for connecting to ITSM as given in project configuration. The values for these fields will be base64 encoded. It will also contain the version of the ITSM being used in the key itsmVersion [this is not encoded].

• ticketJSON – JSON field which will contain the field names and values as per ticket template definition.

• ticketFields - the list of fields to be retrieved from the ITSM tool after update is done. The field names that can come here are given in appendix. Any of the field names in the appendix may be requested and the API should provide it in the 'results' field in response. If the field does not make sense to the ITSM, send an empty value back. It is essential that all the field names in this list are present the 'results' field in response. sysId will be one of those inputs. The sysId returned from the API will be used as the input for update api call later [Even if the ITSM does not have a field called sysId, the unique identifier which would be used to update the ticket should be set in this]

• itsmTimeZoneOffset - A string value which contains the UTC offset of the timezone configured in project configuration. This can be used by the API to convert all time stamp values to UTC. ITOps needs all values in UTC.

Response Fields

• statusCode - string field. 200 indicates success and any other code indicates failure.

• statusMessage - A string field that conatins a user-friendly message

• ticketDetails - JSON field which should contain key value pairs where keys are the field names in ticketFields in request. All fields in ticketFields should be present in this.

 

API to update a ticket

 

HTTP POST

Request JSON: {"sysId":"", "connectionDetails":{}, "ticketFields":[],"ticketJSON":{}, "itsmTimeZoneOffset":""}

Response JSON: {"statusCode":"", "statusMessage":"", "ticketDetails":{}}

Request Fields

• sysId - string field which will have the sysId saved in Elastic Search

• connectionDetails - JSON field that will contain key/value pairs for connecting to ITSM as given in project configuration. The values for these fields will be base64 encoded. It will also contain the version of the ITSM being used in the key itsmVersion [this is not encoded].

• ticketFields - the list of fields to be retrieved from the ITSM tool after update is done. The field names that can come here are given in appendix. Any of the field names in the appendix may be requested and the API should provide it in the 'results' field in response. If the field does not make sense to the ITSM, send an empty value back. It is essential that all the field names in this list are present the 'results' field in response.

• ticketJSON – JSON field which will contain the key/value pairs based on the ticket fields to be updated in the ITSM. Unlike the create API, the keys passed here will be generic and not specific to ITSM [any field mentioned in the appendix can come here]. The wrapper should map the fields in ticketJSON to the actual field used in ITSM.

• itsmTimeZoneOffset - A string value which contains the UTC offset of the timezone configured in project configuration. This can be used by the API to convert all time stamp values to UTC. ITOps needs all values in UTC.

Response Fields

• statusCode - string field. 200 indicates success and any other code indicates failure.

• statusMessage - A string field that contains a user-friendly message

• ticketDetails - JSON field which should contain key value pairs where keys are the field names in ticketFields in request. All fields in ticketFields should be present in this

 

API to fetch the details of a ticket

HTTP GET

Request JSON: {"ticketNumber":"", "connectionDetails":{},"ticketFields":[],"itsmTimeZoneOffset":""}

Response JSON : {"statusCode":"","statusMessage":"", "ticketDetails":{}}

Request Fields

• ticketNumber - string field which will have the ticketNumber saved in Elastic Search

• connectionDetails - JSON field that will contain key/value pairs for connecting to ITSM as given in project configuration. The values for these fields will be base64 encoded. It will also contain the version of the ITSM being used in the key itsmVersion [this is not encoded].

• ticketFields - the list of fields to be retrieved from the ITSM tool. The field names that can come here are given in appendix. Any of the field names in the appendix may be requested and the API should provide it in the 'results' field in response. If the field does not make sense to the ITSM, send an empty value back. It is essential that all the field names in this list are present the 'results' field in response.

• itsmTimeZoneOffset - A string value which contains the UTC offset of the timezone configured in project configuration. This can be used by the API to convert all time stamp values to UTC. ITOps needs all values in UTC.

Response Fields

• statusCode - string field. 200 indicates success and any other code indicates failure.

• statusMessage - A string field that contains a user-friendly message

• ticketDetails - JSON field which should contain key value pairs where keys are the field names in ticketFields in request. All fields in ticketFields should be present in this.

 

Note: The headers for the 3 APIs will all the headers used by SmartOps APIs. Authorization via Smartops keycloak needs to be done in the APIs. Authorization using offline token and authorization token should be supported.

Appendix

Fields that can come up in ticketFields

1. ticketNumber – string

2. ticketStatus - string

3. ticketPriority - string

4. ticketBusinessDuration - string that contains a numeric value with gives the ticketBusinessDuration in seconds

5. ticketBusinessTimeLeft - string that contains a numeric value with gives the ticketBusinessTimeLeft in seconds

6. sysId - string

7. assignedTo - string

8. assignedGroup - string

9. shortDescription - string

10. longDescription - string

11. category - string

12. subCategory - string

13. callerId - string

14. urgency - string

15. ticketSeverity - string

16. comments - list of objects where each object is of the form - {"commentBy": "","commentTime": "", "comment":""}

17. workNotes - list of objects where each object is of the form - {"workNoteBy": "","workNoteTime": "", "workNote":""}

18. closureNotes - list of objects where each object is of the form - {"closureNoteBy": "","closureNoteTime": "", "closureNote":""}

19. createdTime - UTC date time string in format YYYY-MM-DDTHH:mm:ss.ffffff

20. updatedTime - UTC date time string in format YYYY-MM-DDTHH:mm:ss.ffffff

21. resolvedTime - UTC date time string in format YYYY-MM-DDTHH:mm:ss.ffffff

22. createdBy - string

23. updatedBy - string

24. resolvedBy - string

25. closedBy - string

Note: commentTime, workNoteTime and closureNoteTime are also UTC date time strings in format YYYY-MM-DDTHH:mm:ss.ffffff