{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":397,"path":"api-reference/developer-guides/trouble-ticket_dev-guide.md","title":"Trouble Ticket Open API Developer Guide","bundle":null,"doc_type":null,"release":"australia","body":"\n# Trouble Ticket Open API Developer Guide\n\nUse the Trouble Ticket Open API to manage ticket information between external ticketing systems and the ServiceNow AI Platform. This API creates, updates, and retrieves data from the Case \\[sn\\_customerservice\\_case\\] and Incident \\[incident\\] tables.\n\nThis developer guide provides information on how to extend the [Trouble Ticket Open API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/trouble-ticket-open-api.md) to make various customizations.\n\n## Extending the Trouble Ticket Open API\n\nThe Trouble Ticket Open API can be extended by editing script includes.\n\nThese script includes should only be edited with an understanding of the consequences of the changes.\n\n-   `TMFTroubleTicketAPIConstants`: Contains constants and required parameter information.\n-   `TMFTroubleTicketAPIUtil`: Contains functions to handle POST, GET, and PATCH requests.\n-   `TroubleTicketProcessorOOB`: Contains helper functions that support functions in TMFTroubleTicketAPIUtil.\n-   `TroubleTicketProcessor`: An empty script include file. Use this file to define any functions that you want to override from TroubleTicketProcessorOOB.\n\nExtend the Trouble Ticket Open API to make the following customizations.\n\n### Required parameters\n\nTo change which request body parameters are required or not required, update the TMFTroubleTicketAPIConstants script include. By default, the request body to create a ticket \\(POST\\) requires the parameters **description**, **severity**, and **ticketType**. By default, the request body to update a ticket \\(PATCH\\) doesn't have required parameters.\n\n-   `TMFTroubleTicketAPIConstants.TROUBLE_TICKET_CREATION_SCHEMA`: Sets the required request body parameters to create a ticket.\n-   `TMFTroubleTicketAPIConstants.TROUBLE_TICKET_UPDATE_SCHEMA`: Sets the required request body parameters to update a ticket.\n\nIn this example, the **description**, **severity**, **status**, and **ticketType** parameters are required to create a ticket.\n\n```\n// TMFTroubleTicketAPIConstants\nTMFTroubleTicketAPIConstants.TROUBLE_TICKET_CREATION_SCHEMA = {\n    \"title\": \"CreateTroubleTicket\",\n    \"type\": \"object\",\n    \"properties\": {\n        \"description\": {\n            \"type\": \"string\"\n        },\n        \"severity\": {\n            \"type\": \"string\"\n        },\n        \"status\": {\n            \"type\": \"string\"\n        },\n        \"ticketType\": {\n            \"type\": \"string\"\n        }\n    },\n    \"required\": [\n        \"description\",\n        \"severity\",\n        \"status\",\n        \"ticketType\"\n    ]\n};\n```\n\n### Request body validation\n\nTo perform additional validation on the request body, override TroubleTicketProcessorOOB functions. TroubleTicketProcessorOOB contains the following six helper functions that return `true` by default. These functions are called in TMFTroubleTicketAPIUtil.\n\n-   `verifyGetRequestForCase()` - Called by `processGetRequestForCase()`.\n-   `verifyPatchRequestForCase()` - Called by `processPatchRequestForCase()`.\n-   `verifyPostRequestForCase()` - Called by `processPostRequestForCase()`.\n-   `verifyGetRequestForIncident()` - Called by `processGetRequestForIncident()`.\n-   `verifyPatchRequestForIncident()` - Called by `processPatchRequestForIncident()`.\n-   `verifyPostRequestForIncident()` - Called by `processPostRequestForIncident()`.\n\nIf a helper function returns `false`, it stops the API operation. To apply custom validation, override TroubleTicketProcessorOOB helper functions by creating functions with identical names and parameters in TroubleTicketProcessor. These new TroubleTicketProcessor functions will be called by TMFTroubleTicketAPIUtil to replace the default TroubleTicketProcessorOOB helper functions.\n\nIn this example, a function in TroubleTicketProcessor overrides a default function in TroubleTicketProcessorOOB to perform validation on the name attribute.\n\n```\n// TroubleTicketProcessor\nvar TroubleTicketProcessor = Class.create();\nTroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {\n    // Define overriding functions here\n    // Function name and parameters must be identical to the function it overrides\n\n    verifyPostRequestForCase: function(caseObject, apiResponseProcessor){\n        // Returning false terminates the POST request\n        // Make sure to assign error message and reason\n        if (caseObject.name != \"Hello world\") {\n            apiResponseProcessor.setMessage(TMFTroubleTicketAPIConstants.MESSAGES.CASE_CREATION_FAILURE);\n            apiResponseProcessor.setReason(\"No reason needed\");\n            return false;\n        }\n    },\n\n    type: 'TroubleTicketProcessor'\n});\n\n```\n\n### Additional REST operations\n\nTo create additional operations beyond the existing GET, PATCH, and POST operations, [create additional scripted REST resources](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/t_CreateAScriptedRESTAPIResource.md) for the Trouble Ticket Open API. The logic of the new scripted REST resources should be consistent with the existing operations. Define functions for the new operations in TMFTroubleTicketAPIUtil.\n\n### Field mapping\n\nWhen creating or updating records, the API maps request body parameters to case and incident record fields. When retrieving records, the API maps record fields to response object attributes.\n\nTroubleTicketProcessorOOB contains the following functions to map a PATCH or POST request body to a case or incident GlideRecord.\n\n-   `mapPatchRequestToCase()`\n-   `mapPostRequestToCase()`\n-   `mapPatchRequestToIncident()`\n-   `mapPostRequestToIncident()`\n\nTroubleTicketProcessorOOB contains the following functions to map a case or incident GlideRecord to a JSON response object for GET, PATCH, or POST requests.\n\n-   `createGetResponseForCase()`\n-   `createPatchResponseForCase()`\n-   `createPostResponseForCase()`\n-   `createGetResponseForIncident()`\n-   `createPatchResponseForIncident()`\n-   `createPostResponseForIncident()`\n\nCustomize field mappings to add and retrieve data for additional case and incident fields, or to change the default mappings for fields. To customize the field mappings, override TroubleTicketProcessorOOB mapping functions by creating functions with identical names and parameters in TroubleTicketProcessor. These new TroubleTicketProcessor functions will be used by TMFTroubleTicketAPIUtil to replace the default TroubleTicketProcessorOOB mapping functions.\n\nIn this example, two functions in TroubleTicketProcessor override the default functions in TroubleTicketProcessorOOB to change the Description field mapping and add a mapping for the Contract field.\n\n```\n// TroubleTicketProcessor\nvar TroubleTicketProcessor = Class.create();\nTroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {\n    // Define overriding functions here\n    // Function name and parameters must be identical to the function it overrides\n\n    mapPostRequestToCase: function(caseGr, caseObject){\n        // Override default mapping for the Description field\n        caseGr.description = \"All cases will be created with this description\";\n        // Add new mapping to the Contract field\n        caseGr.contract = caseObject.contract;\n     },\n\n    createPostResponseForCase: function(caseGr, caseObject){\n        // Override default mapping for the description attribute\n        caseObject.description = \"This will always be the retrieved description\";\n        // Add new contract attribute to the response object\n        caseObject.contract = caseGr.contract;    \n    },\n\n    type: 'TroubleTicketProcessor'\n});\n\n```\n\n### Mapping logic for choice fields\n\nThe **State**, **Priority**, and **contact\\_type** fields are choice fields, where each choice is composed of a label and a corresponding value. For example, if the **State** field is set to **New**, the label is **New** and the value is **1**. The mapping between choice labels and values can be changed by overriding the choice field mapping functions.\n\nTroubleTicketProcessorOOB contains the following choice field mapping functions.\n\n-   `transformCaseSeverity()`\n-   `transformCaseChannel()`\n-   `transformCaseStatus()`\n-   `transformIncidentSeverityToUrgency()`\n-   `transformIncidentSeverityToImpact()`\n-   `transformIncidentChannel()`\n-   `transformIncidentStatus()`\n\nOverride TroubleTicketProcessorOOB choice field mapping functions by creating functions with identical names and parameters in TroubleTicketProcessor. These new TroubleTicketProcessor functions will be used by TMFTroubleTicketAPIUtil to replace the default TroubleTicketProcessorOOB choice field mapping functions.\n\nIn this example, a function in TroubleTicketProcessor overrides a default function in TroubleTicketProcessorOOB to change the choice mapping for the **Status** field.\n\n```\n// TroubleTicketProcessor\nvar TroubleTicketProcessor = Class.create();\nTroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {\n    // Define overriding functions here\n    // Function name and parameters must be identical to the function it overrides\n\n    transformCaseStatus: function(status){\n        if (status == \"Draft\")\n            return 1;\n        else return 10;\n    },\n\n    type: 'TroubleTicketProcessor'\n});\n\n```\n\n"}}