--- sourceDocument: Referência de API do Xanadu sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/pt-BR/xanadu/api-reference Release : - xanadu ft:locale : - pt-BR ft:publication_title : - Referência de API do Xanadu ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # Guia do desenvolvedor da Open API de tíquete de problema # Guia do desenvolvedor da Open API de tíquete de problema {#ariaid-title1} * Versão de lançamento: Xanadu * * Atualizado 1 de ago. de 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 5 min. de leitura 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](https://servicenow-prod.fluidtopics.net/c0k0XqMVRYi81nQRaV0qyw#trouble-ticket-open-api "A API de abertura de tíquete de problema fornece endpoints para criar, atualizar e recuperar dados das tabelas Caso [sn_customerservice_case] e Incidente [incidente].") para fazer várias personalizações. ## Como estender a API de abertura de tíquete de problema {#ariaid-title2} 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. {#extend-trouble-ticket-api__ul_d5h_lhr_wpb} Estenda a API de abertura de tíquete de problema para fazer as seguintes personalizações. ### Parâmetros obrigatórios {#extend-trouble-ticket-api__section_kcp_rw2_2rb} 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. {#extend-trouble-ticket-api__ul_nsx_yps_wpb} 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 {#extend-trouble-ticket-api__section_byb_ww2_2rb} 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()`. {#extend-trouble-ticket-api__ul_khg_llx_wpb}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 {#extend-trouble-ticket-api__section_x2z_zw2_2rb} Para criar operações adicionais além das operações GET, PATCH e POST existentes, [crie recursos REST de script adicionais](https://servicenow-prod.fluidtopics.net/kDReSwor5NjKYByBThnHJg "Crie um recurso de API REST com script para definir o método HTTP, o script de processamento e para substituir as configurações do serviço primário.") 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 {#extend-trouble-ticket-api__section_oxc_cx2_2rb} 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()` {#extend-trouble-ticket-api__ul_krb_r4x_wpb} 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()` {#extend-trouble-ticket-api__ul_qqk_zfz_wpb} Personalize mapeamentos de campo para adicionar e recuperar dados de 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 {#extend-trouble-ticket-api__section_kdd_gx2_2rb} 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()` {#extend-trouble-ticket-api__ul_jzp_kfz_wpb}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' });