Guia do desenvolvedor da Open API de tíquete de problema

Use a API de abertura de tíquete de problema para gerenciar informações de tíquete entre sistemas de registro de tíquete externos e a Now Platform. Esta API cria, atualiza e recupera dados das tabelas Caso [sn_customerservice_case] e Incidente [incidente].

Este guia do desenvolvedor fornece informações sobre como estender o API de abertura de tíquete de problema para fazer várias personalizações.

Como estender a API de abertura de tíquete de problema

A API de abertura de tíquete de problema pode ser estendida editando inclusões de script.

Essas inclusões de script só devem ser editadas com uma compreensão das consequências das mudanças.

• TMFTroubleTicketAPIConstants: contém constantes e informações de parâmetro necessárias.
• TMFTroubleTicketAPIUtil: contém funções para lidar com solicitações POST, GET e PATCH.
• TroubleTicketProcessorOOB: contém funções de ajuda que oferecem suporte a funções em TMFTroubleTicketAPIUtil.
• TroubleTicketProcessor: um arquivo de inclusão de script vazio. Use este arquivo para definir as funções que você deseja substituir de TroubleTicketProcessorOOB.

Estenda a API de abertura de tíquete de problema para fazer as seguintes personalizações.

Parâmetros obrigatórios

Para mudar quais parâmetros do corpo da solicitação são necessários ou não, atualize a inclusão de script TMFTroubleTicketAPIConstants. Por padrão, o corpo da solicitação para criar um tíquete (POST) requer os parâmetros description, severitye ticketType. Por padrão, o corpo da solicitação para atualizar um tíquete (PATCH) não tem parâmetros obrigatórios.

• TMFTroubleTicketAPIConstants.TROUBLE_TICKET_CREATION_SCHEMA: define os parâmetros do corpo da solicitação necessários para criar um tíquete.
• TMFTroubleTicketAPIConstants.TROUBLE_TICKET_UPDATE_SCHEMA: define os parâmetros do corpo da solicitação necessários para atualizar um tíquete.

Neste exemplo, os parâmetros description, severity, statuse ticketType são necessários para criar um tíquete.

// 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"
    ]
};

Solicitar validação do corpo

Para executar a validação adicional no corpo da solicitação, substitua as funções TroubleTicketProcessorOOB. TroubleTicketProcessorOOB contém as seis funções auxiliares a seguir que retornam verdadeiro por padrão. Essas funções são chamadas em TMFTroubleTicketAPIUtil.

• verifiqueGetRequestForCase() — Chamado por processGetRequestForCase().
• verifiquePatchRequestForCase() — Chamado por processPatchRequestForCase().
• verifiquePostRequestForCase() — Chamado por processPostRequestForCase().
• verifiqueGetRequestForIncident() — Chamado por processGetRequestForIncident().
• verifiquePatchRequestForIncident() — Chamado por processPatchRequestForIncident().
• verifiquePostRequestForIncident() — Chamado por processPostRequestForIncident().

Se uma função auxiliar retornar falso, ela interromperá a operação de API. Para aplicar a validação personalizada, substitua as funções auxiliares TroubleTicketProcessorOOB criando funções com nomes e parâmetros idênticos em TroubleTicketProcessor. Essas novas funções de TroubleTicketProcessor serão chamadas por TMFTroubleTicketAPIUtil para substituir as funções auxiliares padrão de TroubleTicketProcessorOOB.

Neste exemplo, uma função em TroubleTicketProcessor substitui uma função padrão em TroubleTicketProcessorOOB para executar a validação no atributo 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'
});

Operações REST adicionais

Para criar operações adicionais além das operações GET, PATCH e POST existentes, crie recursos REST de script adicionais para a API Aberta de tíquete de problema. A lógica dos novos recursos REST de script deve ser consistente com as operações existentes. Defina funções para as novas operações em TMFTroubleTicketAPIUtil.

Mapeamento de campo

Ao criar ou atualizar registros, a API mapeia os parâmetros do corpo da solicitação para os campos de registro de caso e incidente. Ao recuperar registros, a API mapeia campos de registro para atributos de objeto de resposta.

TroubleTicketProcessorOOB contém as seguintes funções para mapear um corpo de solicitação PATCH ou POST para um GlideRecord de caso ou incidente.

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

TroubleTicketProcessorOOB contém as funções a seguir para mapear um caso ou incidente GlideRecord para um objeto de resposta JSON para solicitações GET, PATCH ou POST.

• createGetResponseForCase()
• createPatchResponseForCase()
• createPostResponseForCase()
• createGetResponseForIncident()
• createPatchResponseForIncident()
• createPostResponseForIncident()

Personalize mapeamentos de campo para adicionar e recuperar dados para campos adicionais de caso e incidente ou para alterar os mapeamentos padrão dos campos. Para personalizar os mapeamentos de campo, substitua as funções de mapeamento TroubleTicketProcessorOOB criando funções com nomes e parâmetros idênticos em TroubleTicketProcessor. Essas novas funções de TroubleTicketProcessor serão usadas por TMFTroubleTicketAPIUtil para substituir as funções de mapeamento padrão de TroubleTicketProcessorOOB.

Neste exemplo, duas funções em TroubleTicketProcessor substituem as funções padrão em TroubleTicketProcessorOOB para mudar o mapeamento do campo Descrição e adicionar um mapeamento para o campo Contrato.

// 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'
});

Lógica de mapeamento para campos de opção

Os campos Estado, Prioridadee contact_type são campos de opção, em que cada opção é composta por um rótulo e um valor correspondente. Por exemplo, se o campo Estado estiver definido como Novo, o rótulo será Novo e o valor será 1. O mapeamento entre rótulos e valores de opção pode ser alterado substituindo as funções de mapeamento do campo de opção.

TroubleTicketProcessorOOB contém as seguintes funções de mapeamento de campo de opção.

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

Substitua as funções de mapeamento do campo de opção TroubleTicketProcessorOOB criando funções com nomes e parâmetros idênticos em TroubleTicketProcessor. Essas novas funções de TroubleTicketProcessor serão usadas por TMFTroubleTicketAPIUtil para substituir as funções de mapeamento de campo de opção TroubleTicketProcessorOOB padrão.

Neste exemplo, uma função em TroubleTicketProcessor substitui uma função padrão em TroubleTicketProcessorOOB para mudar o mapeamento de seleção do campo Status.

// 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'
});