Guide du développeur d’API ouverte pour le ticket d’incident

Utilisez l’API Trouble Ticket Open pour gérer les informations de ticket entre les systèmes de création de tickets externes et le ServiceNow AI Platform. Cette API crée, met à jour et récupère les données des tables Ticket [sn_customerservice_case] et Incident [incident].

Ce guide du développeur fournit des informations sur la façon d’étendre le API ouverte du ticket de problème pour effectuer diverses personnalisations.

Extension de l’API ouverte pour les tickets d’incident

L’API Trouble Ticket Open peut être étendue en modifiant les includes de script.

Ces includes de script ne doivent être modifiés qu’en tenant compte des conséquences des changements.

• TMFTroubleTicketAPIConstants : contient les constantes et les informations sur les paramètres requis.
• TMFTroubleTicketAPIUtil : contient des fonctions pour gérer les demandes POST, GET et PATCH.
• TroubleTicketProcessorOOB : contient des fonctions d’assistance qui prennent en charge les fonctions dans TMFTroubleTicketAPIUtil.
• TroubleTicketProcessor : fichier d’include de script vide. Utilisez ce fichier pour définir toutes les fonctions que vous souhaitez remplacer à partir de TroubleTicketProcessorOOB.

Étendez l’API Ticket de problème ouvert pour effectuer les personnalisations suivantes.

Paramètres requis

Pour modifier les paramètres du corps de la demande requis ou non, mettez à jour l’include de script TMFTroubleTicketAPIConstants. Par défaut, le corps de la demande pour créer un ticket (POST) nécessite les paramètres description, severityet ticketType. Par défaut, le corps de la demande de mise à jour d’un ticket (PATCH) n’a pas de paramètres requis.

• TMFTroubleTicketAPIConstants.TROUBLE_TICKET_CREATION_SCHEMA : définit les paramètres de corps de la demande requis pour créer un ticket.
• TMFTroubleTicketAPIConstants.TROUBLE_TICKET_UPDATE_SCHEMA : définit les paramètres de corps de la demande requis pour mettre à jour un ticket.

Dans cet exemple, les descriptionparamètres , severity, status, et ticketType sont requis pour créer un ticket.

// TMFTroubleTicketAPIConstants
TMFTroubleTicketAPIConstants.TROUBLE_TICKET_CREATION_SCHEMA = {
    "title": "CreateTroubleTicket",
    "type": "object",
    "properties": {
        "description": {
            "type": "string"
        },
        "severity": {
            "type": "string"
        },
        "status": {
            "type": "string"
        },
        "ticketType": {
            "type": "string"
        }
    },
    "required": [
        "description",
        "severity",
        "status",
        "ticketType"
    ]
};

Validation du corps de la demande

Pour effectuer une validation supplémentaire sur le corps de la demande, remplacez les fonctions TroubleTicketProcessorOOB. TroubleTicketProcessorOOB contient les six fonctions d’assistance suivantes qui renvoient la valeur vrai par défaut. Ces fonctions sont appelées dans TMFTroubleTicketAPIUtil.

• verifyGetRequestForCase() : appelé par processGetRequestForCase().
• verifyPatchRequestForCase() : appelé par processPatchRequestForCase().
• verifyPostRequestForCase() : appelé par processPostRequestForCase().
• verifyGetRequestForIncident() : appelé par processGetRequestForIncident().
• verifyPatchRequestForIncident() : appelé par processPatchRequestForIncident().
• verifyPostRequestForIncident() : appelé par processPostRequestForIncident().

Si une fonction d’assistance renvoie la valeur faux, elle arrête l’opération d’API. Pour appliquer la validation personnalisée, remplacez les fonctions d’assistance TroubleTicketProcessorOOB en créant des fonctions avec des noms et des paramètres identiques dans TroubleTicketProcessor. Ces nouvelles fonctions TroubleTicketProcessor seront appelées par TMFTroubleTicketAPIUtil pour remplacer les fonctions d’assistance TroubleTicketProcessorOOB par défaut.

Dans cet exemple, une fonction dans TroubleTicketProcessor remplace une fonction par défaut dans TroubleTicketProcessorOOB pour effectuer une validation sur l’attribut name.

// TroubleTicketProcessor
var TroubleTicketProcessor = Class.create();
TroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {
    // Define overriding functions here
    // Function name and parameters must be identical to the function it overrides

    verifyPostRequestForCase: function(caseObject, apiResponseProcessor){
        // Returning false terminates the POST request
        // Make sure to assign error message and reason
        if (caseObject.name != "Hello world") {
            apiResponseProcessor.setMessage(TMFTroubleTicketAPIConstants.MESSAGES.CASE_CREATION_FAILURE);
            apiResponseProcessor.setReason("No reason needed");
            return false;
        }
    },

    type: 'TroubleTicketProcessor'
});

Opérations REST supplémentaires

Pour créer des opérations supplémentaires au-delà des opérations GET, PATCH et POST existantes, créez des ressources REST scriptées supplémentaires pour l’API ouverte Ticket de problème. La logique des nouvelles ressources REST scriptées doit être cohérente avec les opérations existantes. Définissez des fonctions pour les nouvelles opérations dans TMFTroubleTicketAPIUtil.

Mappage de champs

Lors de la création ou de la mise à jour d’enregistrements, l’API mappe les paramètres du corps de la demande aux champs d’enregistrement de tickets et d’incidents. Lors de la récupération des enregistrements, l’API mappe les champs d’enregistrement aux attributs d’objet de réponse.

TroubleTicketProcessorOOB contient les fonctions suivantes pour mapper le corps d’une demande PATCH ou POST à un GlideRecord de ticket ou d’incident.

• mapPatchRequestToCase()
• mapPostRequestToCase()
• mapPatchRequestToIncident()
• mapPostRequestToIncident()

TroubleTicketProcessorOOB contient les fonctions suivantes pour mapper un ticket ou un incident GlideRecord à un objet de réponse JSON pour les demandes GET, PATCH ou POST.

• createGetResponseForCase (en anglais seulement)
• createPatchResponseForCase()
• createPostResponseForCase()
• createGetResponseForIncident()
• createPatchResponseForIncident()
• createPostResponseForIncident()

Personnalisez les mappages de champs pour ajouter et récupérer des données pour des champs de ticket et d’incident supplémentaires, ou pour modifier les mappages par défaut pour les champs. Pour personnaliser les mappages de champs, remplacez les fonctions de mappage TroubleTicketProcessorOOB en créant des fonctions avec des noms et des paramètres identiques dans TroubleTicketProcessor. Ces nouvelles fonctions TroubleTicketProcessor seront utilisées par TMFTroubleTicketAPIUtil pour remplacer les fonctions de mappage TroubleTicketProcessorOOB par défaut.

Dans cet exemple, deux fonctions dans TroubleTicketProcessor remplacent les fonctions par défaut dans TroubleTicketProcessorOOB pour modifier le mappage du champ Description et ajouter un mappage pour le champ Contrat.

// TroubleTicketProcessor
var TroubleTicketProcessor = Class.create();
TroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {
    // Define overriding functions here
    // Function name and parameters must be identical to the function it overrides

    mapPostRequestToCase: function(caseGr, caseObject){
        // Override default mapping for the Description field
        caseGr.description = "All cases will be created with this description";
        // Add new mapping to the Contract field
        caseGr.contract = caseObject.contract;
     },

    createPostResponseForCase: function(caseGr, caseObject){
        // Override default mapping for the description attribute
        caseObject.description = "This will always be the retrieved description";
        // Add new contract attribute to the response object
        caseObject.contract = caseGr.contract;    
    },

    type: 'TroubleTicketProcessor'
});

Logique de mappage pour les champs de choix

Les champs État, Priorité et contact_type sont des champs de choix dans lesquels chaque choix est composé d’une étiquette et d’une valeur correspondante. Par exemple, si le champ État est défini sur Nouveau, l’étiquette indique Nouveau et la valeur est 1. Le mappage entre les étiquettes de choix et les valeurs peut être modifié en remplaçant les fonctions de mappage du champ de choix.

TroubleTicketProcessorOOB contient les fonctions de mappage de champ de choix suivantes.

• transformCaseSeverity()
• transformCaseChannel()
• transformCaseStatus()
• transformIncidentSeverityToUrgency()
• transformIncidentSeverityToImpact()
• transformIncidentChannel()
• transformIncidentStatus()

Remplacez les fonctions de mappage de champ de choix TroubleTicketProcessorOOB en créant des fonctions avec des noms et des paramètres identiques dans TroubleTicketProcessor. Ces nouvelles fonctions TroubleTicketProcessor seront utilisées par TMFTroubleTicketAPIUtil pour remplacer les fonctions de mappage de champ de choix TroubleTicketProcessorOOB par défaut.

Dans cet exemple, une fonction dans TroubleTicketProcessor remplace une fonction par défaut dans TroubleTicketProcessorOOB pour modifier le mappage de choix pour le champ État .

// TroubleTicketProcessor
var TroubleTicketProcessor = Class.create();
TroubleTicketProcessor.prototype = Object.extendsObject(TroubleTicketProcessorOOB, {
    // Define overriding functions here
    // Function name and parameters must be identical to the function it overrides

    transformCaseStatus: function(status){
        if (status == "Draft")
            return 1;
        else return 10;
    },

    type: 'TroubleTicketProcessor'
});