Scripted REST API

REST API Explorer

Em ServiceNow temos o ambiente de testes REST API Explorer que facilita a vida na hora de construir e testar requisições HTTP REST pois não é necessário sair da plataforma.  

À medida que avançamos no entendimento de integrações é comum o uso de ferramentas como o Postman. Nele podemos testar configurações reais como por exemplo as credenciais de acesso na aba Authorization.

Em um projeto recente precisei criar uma API para expor dados de tickets que são criados numa tabela que estende a tabela Case do módulo CSM - Customer Service Management.

Quando um desenvolvedor constrói um Record Producer (RP) para essa tabela, cria diversas variáveis  para atender as necessidades do cliente. 

No momento em que o usuário final acessa um Portal de Serviços e envia esse RP em Produção, as variáveis não ficam armazenadas na tabela que herda da Case mas numa tabela chamada question_answer.

Minha missão era disponibilizar ao time interno de funcionários uma API que recebe o número do ticket e retorna alguns dados da tabela principal e todas as variáveis enviadas pelo usuário final. 

Criando uma Conta de Serviço

Uma coisa comum ao criarmos integrações é que haja uma Conta de Serviço na tabela sys_user contendo os privilégios de acesso estritamente necessários à chamada da API.

Essa conta deve estar marcada como Web server access only de maneira que não seja permitido o login na interface visual.

Com relação às permissões, além das roles rest_service e snc_internal é importante conceder as roles de leitura para a tabela na qual esta conta terá acesso.

Criando a Scripted REST API

Como sugestão de boas práticas, com relação a ACL utilize a "Scripted REST External Default".

Na aba de documentação, preencha os campos informando o objetivo da API.

Criando um Script Include

Para organizar melhor o código, ao invés de codificar tudo dentro da definição REST podemos criar um Script Include (em azul) e o método aonde iremos implementar a lógica (em verde).

var getClasseAzul = Class.create();
getClasseAzul.prototype = {
    initialize: function() {
    },
    getMetodoVerde: function(number) {
        var caseId = number;
        var result = {};
        // Search the record within the Case table
        var grCase = new GlideRecord('sn_customerservice_case');
        if (grCase.get(caseId) || grCase.get('number', caseId)) {
            // Map default fields
            result.number = grCase.getValue('number');
            result.short_description = grCase.getValue('short_description');
            result.state = grCase.getDisplayValue('state');
            result.opened_at = grCase.getValue('opened_at');
            // Search variables within the question_answer table
            result.variables = [];
            var grQA = new GlideRecord('question_answer');
            grQA.addQuery('table_sys_id', grCase.getUniqueValue());
            grQA.orderBy('order');
            grQA.query();
            while (grQA.next()) {
                var questionId = grQA.getValue('question');
                var rawValue = grQA.getValue('value');
                var questionObj = GlideappQuestion.getQuestion(questionId);
                questionObj.setValue(rawValue);
                var variableData = {
                    "question": grQA.question.question_text.toString(),
                    "value": questionObj.getDisplayValue(),
                    "internal_name": grQA.question.name.toString(),
                    "raw_value": rawValue
                };
                result.variables.push(variableData);
            }
            return result;
        } else {
            gs.error('Error: Case not found ', number);
        }
    },
    type: 'getClasseAzul'
};

Testando a chamada via Postman

Por fim, ao fornecer as credenciais de acesso na aba Authorization, agora é possível testar a chamada da API via Postman e conferir o resultado.

Nesse exemplo utilizei o método Basic Authentication e forneci dados de Usuário (User ID e Senha) referentes a Conta de Serviço criada na tabela sys_user.

Obrigado.