CA Nimsoft Service Desk Guia de serviços web Outono de 2013
A presente documentação, que inclui os sistemas de ajuda incorporados e os materiais distribuídos eletronicamente (doravante denominada Documentação), destina-se apenas a fins informativos e está sujeita a alterações ou remoção por parte da CA a qualquer momento. Esta Documentação contém informações proprietárias da CA e não pode ser copiada, transferida, reproduzida, divulgada, modificada nem duplicada, parcial ou completamente, sem o prévio consentimento por escrito da CA. Se o Cliente for um usuário licenciado do(s) produto(s) de software referido(s) na Documentação, é permitido que ele imprima ou, de outro modo, disponibilize uma quantidade razoável de cópias da Documentação para uso interno seu e de seus funcionários envolvidos com o software em questão, contanto que todos os avisos de direitos autorais e legendas da CA estejam presentes em cada cópia reproduzida. O direito à impressão ou, de outro modo, à disponibilidade de cópias da Documentação está limitado ao período em que a licença aplicável ao referido software permanecer em pleno vigor e efeito. Em caso de término da licença, por qualquer motivo, fica o usuário responsável por garantir à CA, por escrito, que todas as cópias, parciais ou integrais, da Documentação sejam devolvidas à CA ou destruídas. NA MEDIDA EM QUE PERMITIDO PELA LEI APLICÁVEL, A CA FORNECE ESTA DOCUMENTAÇÃO "NO ESTADO EM QUE SE ENCONTRA", SEM NENHUM TIPO DE GARANTIA, INCLUINDO, ENTRE OUTROS, QUAISQUER GARANTIAS IMPLÍCITAS DE COMERCIABILIDADE, ADEQUAÇÃO A UM DETERMINADO FIM OU NÃO VIOLAÇÃO. EM NENHUMA OCASIÃO, A CA SERÁ RESPONSÁVEL PERANTE O USUÁRIO OU TERCEIROS POR QUAISQUER PERDAS OU DANOS, DIRETOS OU INDIRETOS, RESULTANTES DO USO DA DOCUMENTAÇÃO, INCLUINDO, ENTRE OUTROS, LUCROS CESSANTES, PERDA DE INVESTIMENTO, INTERRUPÇÃO DOS NEGÓCIOS, FUNDO DE COMÉRCIO OU PERDA DE DADOS, MESMO QUE A CA TENHA SIDO EXPRESSAMENTE ADVERTIDA SOBRE A POSSIBILIDADE DE TAIS PERDAS E DANOS. O uso de qualquer software mencionado na Documentação é regido pelo contrato de licença aplicável, e tal contrato não deve ser modificado de nenhum modo pelos termos deste aviso. O fabricante desta Documentação é a CA. Fornecida com Direitos restritos. O uso, duplicação ou divulgação pelo governo dos Estados Unidos está sujeita às restrições descritas no FAR, seções 12.212, 52.227-14 e 52.227-19(c)(1) - (2) e DFARS, seção 252.227-7014(b)(3), conforme aplicável, ou sucessores. Copyright 2010 CA. Todos os direitos reservados. Todas as marcas comerciais, nomes de marcas, marcas de serviço e logotipos aqui mencionados pertencem às suas respectivas empresas.
Entrar em contato com o Suporte técnico Para assistência técnica online e uma lista completa dos locais, principais horários de atendimento e números de telefone, entre em contato com o Suporte técnico pelo endereço http://www.ca.com/worldwide.
Índice Capítulo 1: Introdução 7 Visão geral... 7 Conformidade com os padrões... 7 Plataformas de desenvolvimento... 8 Diretiva de suporte à API... 9 Compatibilidade com versões anteriores... 9 Capítulo 2: Fundamentos da API de serviço web do Service Desk 11 Fundamentos da chamada de API... 11 Características das chamadas de API... 12 Fatores que afetam o acesso aos dados... 12 Tipos de formato de dados de saída do serviço web... 13 Segurança... 13 Tratamento de erros... 13 Entidades suportadas... 14 Operações aceitas... 14 Formato geral da API de serviço web do Nimsoft Service Desk... 15 Implementação de SOAP... 16 Capítulo 3: Chamadas de API do serviço web 17 Requisitos para todas as chamadas... 17 A chamada get... 18 A chamada list... 19 A chamada insert... 19 A chamada update... 21 A chamada delete... 22 A chamada relate... 22 A chamada unrelate... 23 Segurança do campo... 23 Campos numéricos... 24 Capítulo 4: Determinando o tipo de campos padrão 25 Campos enumerados... 26 Campos de data/hora... 27 Campos personalizados... 28 Índice 5
Os campos de ID... 28 Os campos de ID de referência cruzada... 29 Campos de texto longo... 29 Campos ModTimeStamp do sistema... 30 Capítulo 5: Ocorrências específicas da entidade 31 Anexo... 32 Categorização... 33 Solicitação de mudança... 33 Comunicação... 34 Item de configuração... 35 Contato... 35 Pesquisa definida... 35 Incidente... 36 Artigo de conhecimento... 37 Organização... 37 Problema... 38 Solicitação de serviço... 39 Grupo de suporte... 40 Ticket da tarefa... 40 Ticket... 41 Lista de valores... 42 Log de trabalho... 43 Capítulo 6: Apêndice A: Códigos de status 45 Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 47 Configurando o ambiente... 47 Gerando o código de cliente do Axis2 usando a ferramenta "wsdl2java"... 48 Sequência de chamada de API comum... 49 Exemplo de cliente da chamada get... 49 Exemplo de cliente da chamada list... 52 Exemplo de cliente da chamada insert... 55 Exemplo de cliente da chamada update... 59 Exemplo de cliente da chamada delete... 63 6 Guia de serviços web
Capítulo 1: Introdução Esta seção contém os seguintes tópicos: Visão geral (na página 7) Conformidade com os padrões (na página 7) Plataformas de desenvolvimento (na página 8) Diretiva de suporte à API (na página 9) Compatibilidade com versões anteriores (na página 9) Visão geral A documentação da API de serviços web do CA Nimsoft Service Desk fornece as informações necessárias para acessar e usar essa API de serviços web. A API de serviços web atualmente oferece suporte ao protocolo SOAP. A API WS fornece uma maneira programática de interação com a plataforma do Service Desk para acessar e alterar os dados das entidades principais, como tickets, itens de configuração, artigos de conhecimento, etc., que são gerenciados no aplicativo Service Desk. Para usar esse documento, você deve ter uma familiaridade básica com desenvolvimento de software, serviços web e a interface de usuário do Service Desk. Qualquer funcionalidade descrita nesse guia só estará disponível se a sua organização tiver uma licença de acesso aos serviços web. Se você não puder acessar os recursos exibidos neste guia, entre em contato com o suporte do Service Desk. Observação: recomendamos usar o cliente de UI SOAP para fazer interface com os serviços web do CA Nimsoft Service Desk. Consulte o site http://www.soapui.org para obter mais informações sobre como usar o cliente de UI SOAP. Conformidade com os padrões A API WS é implementada para conformidade com as seguintes especificações padrão Nome padrão Protocolo de acesso a objeto simples (SOAP) 1.1 Site http://www.w3.org/tr/2000/note-soap-20000508/ Capítulo 1: Introdução 7
Plataformas de desenvolvimento Web Service Description Language (WSDL) 1.1 http://www.w3.org/tr/2001/note-wsdl-20010315 Plataformas de desenvolvimento A API foi validada para funcionar com os ambientes de desenvolvimento J2EE 1.6 e o Apache Axis2. Neste documento, fornecemos exemplos em Java. Esses exemplos são baseadas no Apache Axis2 1.5.1 e no JDK 1.6. Para obter mais informações sobre o Apache Axis2 1.5, consulte http://axis.apache.org/axis2/java/core/ 8 Guia de serviços web
Diretiva de suporte à API Diretiva de suporte à API Recomendamos que os seus novos aplicativos cliente usem a versão mais recente do arquivo WSDL do Service Desk para aproveitar totalmente os benefícios oferecidos pelos recursos mais aprimorados e pela maior eficiência. Você pode buscar a WSDL mais recente acessando o URL de serviços web do Service Desk. Por exemplo, você pode obter a WSDL de solicitação de serviço indo para este URL: http://{modifiedloginurl}/servicedesk/webservices/servicerequest?wsdl. Nesse exemplo, o {servicedeskcontexturl} é o URL de logon ajustado. Para identificar o URL de logon ajustado para sua instância, considere estes exemplos: Você é um usuário que acessa a instância de produção dos EUA. Normalmente, você faz logon em https://sec.itm.1001.saas.ca/com. Para acessar o WSDL de solicitação de serviço, acesse: https://production.itm1001.saas.ca.com/servicedesk/webservices/servicereques t?wsdl. Você é um usuário que acessa a instância de testes dos EUA. Normalmente, você faz logon em https://sec.staging.itm1001.saas.ca.com. Para acessar o WSDL de solicitação de serviço, acesse: https://staging.itm1001,saas.ca.com/servicedesk/webservices/servicerequest?w sdl. Observação: o URL exato depende da instância que você está acessando. Entre em contato com a equipe de suporte do URL exato ou use o exemplo acima para criar o URL. Cada vez que uma versão mais recente dos Serviços web for liberada, use as seguintes etapas para gerar novamente o código de cliente a partir de um documento WSDL existente: Gerar novamente os stubs do cliente usando o utilitário WSDL2JAVA Atualizar a classe do cliente a partir da versão existente/mais recente do documento WSDL Compilar e executar a classe do cliente Compatibilidade com versões anteriores A Nimsoft não garante que um aplicativo escrito em uma versão da API WS funcionará nas futuras versões da API. Alterações nas assinaturas de método e representações de dados geralmente são necessárias à medida que aprimoramos a API. No entanto, nos esforçamos para manter a API consistente de uma versão para outra, com o mínimo de alterações (se houver) necessárias para portar os aplicativos para as versões mais recentes da API. Capítulo 1: Introdução 9
Capítulo 2: Fundamentos da API de serviço web do Service Desk Esta seção contém os seguintes tópicos: Fundamentos da chamada de API (na página 11) Características das chamadas de API (na página 12) Fatores que afetam o acesso aos dados (na página 12) Tipos de formato de dados de saída do serviço web (na página 13) Segurança (na página 13) Tratamento de erros (na página 13) Entidades suportadas (na página 14) Operações aceitas (na página 14) Formato geral da API de serviço web do Nimsoft Service Desk (na página 15) Implementação de SOAP (na página 16) Fundamentos da chamada de API As chamadas de API representam operações específicas que os aplicativos cliente podem invocar em tempo de execução para executar tarefas como: Consultar dados na sua organização. Adicionar, atualizar e excluir dados. Capítulo 2: Fundamentos da API de serviço web do Service Desk 11
Características das chamadas de API Características das chamadas de API Todas as chamadas de API são: Solicitações e respostas: o aplicativo cliente se prepara e envia uma solicitação ao serviço web do Service Desk por meio da API, o serviço web do Service Desk processa a solicitação e retorna uma resposta, e o aplicativo cliente manipula a resposta. Síncronas: depois que a chamada de API é invocada, o aplicativo cliente espera até receber uma resposta do serviço. As chamadas assíncronas não são suportadas. Confirmadas automaticamente ou revertidas por erro: por padrão, toda operação que grava em um objeto do Service Desk é confirmada automaticamente. Esse procedimento é semelhante à configuração AUTOCOMMIT no SQL. Para as chamadas create(), update() e delete() que tentam gravar em vários registros de um objeto, a operação de gravação de cada registro é tratada como uma transação separada. Por exemplo, se um aplicativo cliente tentar criar duas contas novas, elas serão criadas usando operações de inserção mutuamente exclusivas que serão bem-sucedidas ou falharão individualmente, não como um grupo. Fatores que afetam o acesso aos dados Quanto a API é usada, os seguintes fatores afetam o acesso aos dados da sua organização: A sua organização deve estar ativada para acesso à API WS e o usuário que tentar acessar essa API deverá ter o tipo de licença "Serviço web". Se as permissões configuradas permitem acessar os dados. O aplicativo cliente efetua logon como usuário no serviço web do Service Desk. O perfil associado ao usuário conectado concede ou nega acesso a determinados objetos e campos da sua organização. Quando um aplicativo efetua logon na API, todas as transações são executadas como o usuário que efetua logon. Portanto, para proteger a segurança dos dados, conceda a esse usuário (o usuário conectado) somente as permissões necessárias para executar com êxito todas as chamadas feitas pelo aplicativo. Se uma determinada mudança iria comprometer a integridade referente aos dados do Service Desk da sua organização. Se um determinado campo em um objeto pode ser atualizado ou não. Por exemplo, campos somente leitura não podem ser alterados em chamadas create() ou update(). Regras para que objetos como campos que são configurados na interface do usuário do Service Desk sejam exclusivos ou necessários são automaticamente impostas por meio da API. 12 Guia de serviços web
Tipos de formato de dados de saída do serviço web Tipos de formato de dados de saída do serviço web O CA Nimsoft Service Desk oferece suporte aos seguintes formatos de dados padrão por meio de protocolo HTTP: JSON - http://json.org/ XML - http://en.wikipedia.org/wiki/xml JAVA BEAN - http://en.wikipedia.org/wiki/javabean Segurança Os aplicativos cliente que acessam os dados do Service Desk da sua organização estão sujeitos às mesmas proteções de segurança utilizadas na interface do usuário do Service Desk. Os aplicativos cliente devem efetuar logon usando credenciais válidas para uma organização. O servidor autentica essas credenciais e, se forem válidas, permite o acesso à operação do serviço web. O administrador do Service Desk de uma organização controla a disponibilidade de vários recursos e exibições configurando perfis e atribuindo usuários a eles. Para acessar a API (para emitir chamadas e receber os resultados das chamadas), um usuário deve receber a licença "Serviços web". Os aplicativos cliente podem consultar ou atualizar somente os objetos e campos aos quais seu intervalo de cliente tem acesso por meio do perfil do usuário conectado. Para ter acesso por meio da API ou de um cliente, o usuário deve usar o token de segurança ou fornecer sua ID de logon e senha para efetuar logon. Um token de segurança é uma chave gerada automaticamente a partir do Service Desk. Tratamento de erros As chamadas de API retornam dados de erro que o aplicativo cliente pode usar para identificar e resolver erros em tempo de execução. Se ocorrer um erro durante a maioria das chamadas de API, a API fornecerá os seguintes tipos de tratamento de erros: Para erros resultantes de mensagens formadas incorretamente, falhas de autenticação ou problemas semelhantes, a API retorna uma resposta de serviço padrão, com o código de status adequado e uma mensagem de status descritiva. Para a maioria das chamadas, se o erro ocorrer devido a um problema específico à consulta, a API retornará um erro. Por exemplo, se uma solicitação create() contiver valores a serem atualizados para campos somente leitura. Capítulo 2: Fundamentos da API de serviço web do Service Desk 13
Entidades suportadas Entidades suportadas Você pode usar a API de serviço web do CA Nimsoft Service Desk para acessar e alterar os seguintes tipos de entidades: Anexo Solicitação de mudança Item de configuração Comunicação Contato Pesquisa definida Incidente Artigo de conhecimento Organização Problema Solicitação de serviço Grupo de suporte Ticket de tarefa Ticket Lista de valores Log de trabalho A lista de entidades suportadas poderá ser alterada no futuro. Algumas das entidades podem não ser acessíveis a um usuário em particular, dependendo das permissões da organização e do usuário. Operações aceitas As chamadas de API representam operações específicas que os aplicativos cliente podem invocar em tempo de execução para executar tarefas. Os serviços web do Nimsoft Service Desk oferecem suporte aos tipos de operações a seguir Operação Obter Listar Inserir Descrição Recuperar campos especificados de um registro com base no identificador do registro Recupera os registros com base nos critérios de pesquisa especificados Criar um novo registro com as informações especificadas 14 Guia de serviços web
Formato geral da API de serviço web do Nimsoft Service Desk Atualizar Excluir Relacionar Cancelar relação Modificar um registro existente com as informações especificadas Excluir um registro existente com base no identificador do registro Relaciona um registro de entidade identificado pelo identificador de registro com outra entidade identificada pelo identificador de registro Cancela a relação de um registro de entidade com outra entidade, ambos identificados pelos respectivos identificadores de registro Formato geral da API de serviço web do Nimsoft Service Desk Cada chamada de API é iniciada por uma solicitação de um cliente e tem uma resposta do servidor. As chamadas de API nunca são iniciadas do servidor para o cliente. Cada chamada de API possui um nome de método, que é uma das operações descritas na seção Operações aceitas. A API de serviços web do Nimsoft Service Desk permite codificar as chamadas usando SOAP (Simple Object Access Protocol - Protocolo de acesso a objeto simples) ou XML-RPC, um mecanismo de RPC simples codificado em XML. Capítulo 2: Fundamentos da API de serviço web do Service Desk 15
Implementação de SOAP Implementação de SOAP A API de serviço web do Nimsoft Service Desk permite codificar as chamadas usando SOAP. O SOAP (Simple Object Access Protocol - Protocolo de acesso a objeto simples) é um protocolo com base em XML para troca de informações. Consulte http://www.w3.org/tr/soap/ para obter uma descrição detalhada do SOAP. Todas as operações suportadas estão disponíveis na implementação do SOAP. Consulte a seção Operações aceitas. Cada chamada SOAP deve ser feita para um nome de host de servidor de aplicativo de central de serviços com um nome de servlet webservices/xxxx. Esta seção descreve a especificação de alto nível do SOAP para a API do Service Desk. Consulte a WSDL do Service Desk em http://www.w3.org/tr/soap/ para obter uma especificação mais técnica. Namespaces do SOAP O SOAP usa diferentes namespaces para diferentes elementos e atributos, de acordo com a função dos dados na formatação, manipulação ou codificação da mensagem. Os namespaces refletem a maneira como todas as definições de tipo de dados no SOAP são delegadas para o esquema XML. A API de serviço web do Nimsoft Service Desk usa os namespaces a seguir Namespace targetnamespace xmlns xmlns:soap xmlns:xsd xmlns:wsdl Valor http://www.inteqnet.com http://schemas.xmlsoap.org/wsdl/ http://schemas.xmlsoap.org/wsdl/soap/ http://www.w3.org/2001/xmlschema http://schemas.xmlsoap.org/wsdl/ 16 Guia de serviços web
Capítulo 3: Chamadas de API do serviço web Esta seção contém os seguintes tópicos: Requisitos para todas as chamadas (na página 17) A chamada get (na página 18) A chamada list (na página 19) A chamada insert (na página 19) A chamada update (na página 21) A chamada delete (na página 22) A chamada relate (na página 22) A chamada unrelate (na página 23) Segurança do campo (na página 23) Campos numéricos (na página 24) Requisitos para todas as chamadas Argumento authorizationtoken slicetoken username userpassword responseformat Todas as chamadas de API WS devem estar contidas em uma solicitação HTTP com os cabeçalhos HTTP apropriados. Todas as chamadas de API WS do Service Desk requerem os seguintes argumentos padrão: Description Credenciais Token de autorização de cliente do serviço web Token de intervalo de cliente do serviço web Nome de usuário cliente do serviço web Configurações estendidas Senha de usuário cliente do serviço web Formato de dados de saída do serviço web (JSON, XML e JavaBean) Resposta a todas as chamadas: Integrantes A resposta a todas as chamadas de API WS do Service Desk compreende uma classe de bean padrão de resposta do serviço, independentemente de a solicitação ser bem-sucedida ou não. O bean de obtenção de resposta pode conter os integrantes a seguir Descrição Resposta de serviço padrão Capítulo 3: Chamadas de API do serviço web 17
A chamada get responsestatus statuscode statusmessage responseformat responsetext responsebean erros warnings observações O status da mensagem de saída de uma chamada de serviço web O código de status da resposta do serviço web Mensagem de status da resposta do serviço web O formato da mensagem de saída de uma chamada de serviço web O texto formatado da mensagem de saída (aplicável aos tipos de formato XML, JSON) A classe de bean de saída específica do serviço (aplicável quando o formato da resposta for BEAN) A lista de mensagens de erro que ocorreram durante a chamada de serviço web A lista de mensagens de aviso informando o cliente sobre problemas não fatais ou condições que podem causar problemas A lista de mensagens informativas para transmitir informações ou melhorar o diagnóstico A chamada get A chamada get é usada para recuperar um conjunto predefinido de valores de campo de uma entidade com base no identificador de registro. A solicitação get Além dos argumentos normais de ID de logon e senha, a chamada get também requer o seguinte: Membros Identificador de registro Descrição Identificador de registro (ID de linha) da entidade A resposta de get A resposta padrão do serviço para todas as chamadas de API conterá o registro no formato de saída solicitado para uma chamada get. 18 Guia de serviços web
A chamada list A chamada list A chamada list é usada para recuperar registros (entidades) com base nos critérios de pesquisa especificados. A solicitação list: além dos argumentos normais de ID de logon e senha, a chamada list também requer o seguinte: Membros Pesquisar texto Descrição Valor do texto de pesquisa a ser procurado no conjunto de campos identificados para uma entidade A resposta de list A resposta padrão do serviço para todas as chamadas de API conterá o conjunto de registros correspondentes aos critérios de pesquisa no formato de saída solicitado para uma chamada list. A chamada insert A chamada insert é usada para criar um novo registro (entidade) de um tipo específico com os valores especificados. A solicitação insert: além dos argumentos normais de ID de logon e senha, a chamada insert também requer o seguinte: Membros Classe do bean Descrição Classe de java bean (tipo de dados complexo) específica da entidade, que contém valores para os campos que devem ser definidos ao criar a nova entidade Capítulo 3: Chamadas de API do serviço web 19
A chamada insert Durante uma inserção, não é necessário especificar todos os campos desse tipo de entidade. A maioria dos campos é opcional, exceto aqueles marcados como obrigatórios na resposta de descrição, indicados pelo atributo anulável com o valor booleano 0. Os campos não especificados são definidos como em branco ou com valores padrão. Os campos muito longos são truncados. Se você enviar valores de campo não reconhecidos na solicitação insert, a API WS do Service Desk rejeitará a chamada e enviará o código de status 300 'Rejeitando o valor fornecido para o elemento dos dados de entrada "{ 0}" devido a uma falha de correlação, pois o processo de transformação dos dados não pôde resolver o elemento dos dados de entrada fornecidos no formato nativo'. A API aplica uma definição estrita dos valores de campo não reconhecidos, de modo que todos os campos da chamada precisem ser válidos para o usuário da operação. Por exemplo: A API rejeita chamadas que especificam um valor para um campo personalizado que tenha sido excluído ou removido do acesso de um usuário. A API rejeita chamadas que especificam campos somente leitura. Para alguns tipos de entidades, se você tentar inserir um novo registro que já existe, a API não insere um novo registro. A resposta de insert A resposta padrão do serviço para todas as chamadas de API conterá o identificador de registro (ID de linha) de um registro que está sendo inserido no formato de saída solicitado para uma chamada insert. 20 Guia de serviços web
A chamada update A chamada update A chamada update é usada para modificar um registro (entidade) existente identificado pelo identificador de registro com valores especificados. A solicitação update Além dos argumentos normais de ID de logon e senha, a chamada update também requer o seguinte: Integrante: classe do bean Descrição: classe de java bean (tipo de dados complexo) específica da entidade, que contém valores para os campos que devem ser atualizados, durante a atualização de uma entidade existente identificada pelo identificador de registro. Durante uma atualização, não é necessário especificar todos os campos desse tipo de entidade. Você deve transmitir os valores para os campos que deseja atualizar durante a chamada. Os campos não especificados serão mantidos intactos. Os campos muito longos são truncados. Se você enviar valores de campo não reconhecidos na solicitação update, a API WS do Service Desk rejeitará a chamada e enviará o código de status 300 com uma mensagem de status associada que exibe 'Rejeitando o valor fornecido para o elemento dos dados de entrada "{ 0}" devido a uma falha de correlação, pois o processo de transformação dos dados não pôde resolver o elemento dos dados de entrada fornecidos no formato nativo'. A API aplica uma definição estrita dos valores de campo não reconhecidos, de modo que todos os campos da chamada precisem ser válidos para o usuário da operação. Por exemplo: a API rejeita chamadas que especificam um valor para um campo personalizado que tenha sido excluído ou removido do acesso de um usuário. A API rejeita chamadas que especificam campos somente leitura. A resposta de update: a resposta padrão do serviço para todas as chamadas de API conterá o identificador de registro (ID de linha) de um registro que está sendo atualizado no formato de saída solicitado para uma chamada update. Observação: é possível limpar os campos de texto que não são obrigatórios, inserindo ##NULL##. No entanto, se você digitar ##NULL## em um campo obrigatório, você irá receber a mensagem padrão informando que o campo é obrigatório. Quando um usuário tenta atualizar o ticket, ele recebe uma mensagem de erro para os campos Organização do solicitante, Local do solicitante, Endereço do solicitante, Solicitado para a organização, Solicitado para o local, Solicitado para o endereço e Caso pai, informando que eles são campos somente leitura. Capítulo 3: Chamadas de API do serviço web 21
A chamada delete A chamada delete A chamada delete é usada para excluir um registro (entidade) existente identificado pelo identificador de registro. A solicitação delete: além dos argumentos normais de ID de logon e senha, a chamada delete também requer o seguinte: Membros Identificador de registro Descrição Identificador de registro (ID de linha) de um registro A resposta de delete A resposta padrão do serviço para todas as chamadas de API conterá o identificador de registro (ID de linha) de um registro que está sendo excluído no formato de saída solicitado para uma chamada delete. A chamada relate A chamada relate é usada para relacionar uma entidade (registro) com outra entidade identificada pelos seus respectivos identificadores de registro. A solicitação relate: além dos argumentos normais de ID de logon e senha, a chamada relate também requer o seguinte: Membros Identificador de registro Identificador de registro relacionado Descrição Identificador de registro (ID de linha) de uma entidade à qual outra entidade deve estar relacionada Identificador de registro (ID de linha) de uma entidade que deve ser relacionada a outra entidade A resposta de relate A resposta padrão do serviço para todas as chamadas de API pode conter o identificador de registro (ID de linha) de um registro que está sendo inserido na tabela de relacionamentos no formato de saída solicitado para uma chamada relate. 22 Guia de serviços web
A chamada unrelate A chamada unrelate A chamada unrelate é usada para cancelar a relação de um registro de entidade com outra entidade identificada pelos seus respectivos identificadores de registro. A solicitação unrelate: além dos argumentos normais de ID de logon e senha, a chamada unrelate também requer o seguinte: Membros Identificador de registro Identificador de registro relacionado Descrição Identificador de registro (ID de linha) de uma entidade cuja relação com outra entidade deve ser cancelada Identificador de registro (ID de linha) de uma entidade cuja relação com outra entidade deve ser cancelada A resposta de unrelate: a resposta padrão do serviço para todas as chamadas de API pode conter o identificador de registro (ID de linha) de um registro que está sendo inserido na tabela de relacionamentos no formato de saída solicitado para uma chamada relate. Segurança do campo A API WS do Service Desk impõe o modelo de segurança de campo que está configurado na interface do usuário do Service Desk. Nessa interface, certos campos podem ser marcados como somente leitura ou podem estar ocultos em layouts de página. Para um usuário específico, a API pode acessar apenas os campos que são acessíveis a esse usuário em seu layout de página atribuído. As seguintes restrições se aplicam: A API pode consultar campos somente leitura, mas não pode inserir ou atualizar esses campos para esse usuário. A API não pode consultar, inserir ou atualizar os campos marcados como ocultos para esse usuário. Com a API WS do Service Desk, os campos ocultos não são visíveis para nenhum usuário, mesmo aqueles que possuem privilégios totais. Esse comportamento é consistente com o funcionamento do aplicativo. Capítulo 3: Chamadas de API do serviço web 23
Campos numéricos Campos numéricos Os campos numéricos incluem os campos do tipo número inteiro e duplo. Os campos padrão predefinidos são do tipo número inteiro ou duplo, de acordo com os critérios explicados na seção Determinando o tipo de campos padrão. Todos os campos numéricos personalizados são tratados como tipo duplo. Os campos numéricos devem ser transferidos como tipo i4 ou duplo, conforme apropriado, com exceção de que é possível definir um campo numérico como nulo definindo-o com um valor de sequência de caracteres em branco. O tipo de é indicado na resposta de descrição de uma entidade. O tipo deve ser respeitado em todas as futuras chamadas que se referirem a esse campo, inclusive nas chamadas insert e update. O tipo do campo também é retornado pela chamada query. Os limites do campo numérico são impostos quando os registros são inseridos ou atualizados. Os limites são indicados na resposta de descrição pelo atributo dígitos para um campo de número inteiro ou pelos atributos escala e precisão para um campo duplo. Membros Dígitos Escala Precisão Descrição Especifica o número máximo de dígitos que pode ter um número inteiro Para campos duplos, especifica o número máximo de dígitos à direita da vírgula decimal. Para campos duplos, especifica o número total de dígitos, incluindo aqueles à esquerda e à direita da vírgula decimal. O número máximo de dígitos à esquerda da vírgula decimal é igual à precisão menos escala. Na interface do usuário do Service Desk, a precisão é definida de forma diferente; é o número máximo de dígitos permitidos à esquerda da vírgula decimal. Os limites dos campos numéricos são impostos quando os dados são inseridos ou atualizados. No entanto, a API WS do Service Desk pode retornar dados que não atendam a essas restrições. 24 Guia de serviços web
Capítulo 4: Determinando o tipo de campos padrão O servidor determina se um campo numérico padrão predefinido deve ser tratado como um tipo XML-RPC duplo ou como um tipo XML-RPC i4. Normalmente, o servidor opta por usar tipo i4 quando a escala é zero e tipo duplo quando a escala é maior que zero. O tipo i4 em XMLRPC é limitado a um número inteiro de quatro bytes, portanto, ele não pode manipular a ampla gama de valores inteiros que são suportados pelos campos de número inteiro do Service Desk. Por isso, o servidor indica um tipo duplo para os campos numéricos com uma escala maior que zero, ou com uma precisão maior que nove. No entanto, não haverá nenhuma perda de precisão para valores inteiros muito grandes (com mais de 15 ou 16 dígitos) que são transferidos por meio da API WS do Service Desk. Os clientes não devem codificar essa lógica por conta própria, mas devem usar o tipo especificado na resposta de descrição. A decisão sobre quando usar o tipo duplo ou i4 pode mudar no futuro, mas qualquer mudança será refletida na resposta de descrição. Esta seção contém os seguintes tópicos: Campos enumerados (na página 26) Campos de data/hora (na página 27) Campos personalizados (na página 28) Os campos de ID (na página 28) Os campos de ID de referência cruzada (na página 29) Campos de texto longo (na página 29) Campos ModTimeStamp do sistema (na página 30) Capítulo 4: Determinando o tipo de campos padrão 25
Campos enumerados Campos enumerados Na API WS do Service Desk, os campos enumerados são aqueles restritos a uma lista de valores definida. Eles são indicados na resposta de descrição com um valor booleano 1 para o integrante restrito da subestrutura de campos. Os valores permitidos para um campo enumerado são especificados na matriz de valores da subestrutura de exibição da resposta de descrição. Observe que o integrante valores está presente em qualquer campo da lista de opções, e os campos da lista de opções que não possuem o integrante restrito são de consulta. A API WS do Service Desk impõe a lista de valores para os campos da lista de opções durante a inserção ou atualização. A chamada query sempre retorna o valor, não o rótulo. O rótulo correspondente de um valor na resposta de descrição deve ser usado durante a exibição do valor para o usuário em qualquer interface de usuário. 26 Guia de serviços web
Campos de data/hora Campos de data/hora Todos os campos de data/hora são transferidos por meio da API WS do Service Desk usando o tipo XML-RPC datetime.iso8601 ou o tipo SOAP datetime. No entanto, o Service Desk possui duas maneiras diferentes de manipular datas e horas internamente. Em alguns casos, você pode controlá-las de forma idêntica, mas, em outros casos, pode precisar tratá-las de maneira diferente. Campos comuns de data/hora Os campos comuns de data/hora são armazenados como número de segundos após a meia-noite do dia 1º de janeiro de 1970 GMT. Eles são automaticamente convertidos no fuso horário GMT/UTC. Não é necessário converter o seu carimbo de data e hora no valor do fuso horário GMT/UTC. Exemplos de campos comuns de data/hora incluem todos os campos de data de criação e os campos de data de início e data de término. Campos somente de data: Alguns campos no Service Desk são somente de data. A parte da hora de um campo somente de data não é relevante e é sempre definida como meia-noite no fuso horário GMT/UTC. Os campos somente de data são transferidos na API como tipos datetime para SOAP e como tipos datetime.iso8601 para chamadas XML-RPC, desde que o XMLRPC não tenha um tipo somente de data. Você deve manipular os valores do campo somente de data de forma diferente dos valores comuns de data/hora: Você deve ignorar qualquer parte de hora. Você sempre deve enviar uma parte de hora de todos os zeros. O Service Desk aceita valores somente de data que tenham uma parte de hora diferente de zero, mas a parte de hora é sempre truncada para zero. Você não deve alterar nenhum dos valores somente de data para responder pelas mudanças de fuso horário, pois a parte da hora não é relevante. Capítulo 4: Determinando o tipo de campos padrão 27
Campos personalizados Campos personalizados Na interface de usuário do Service Desk, as organizações podem estabelecer um número definido de campos personalizados para diferentes entidades. Na maioria das vezes, os clientes da API WS do Service Desk não precisam saber se um campo é padrão ou personalizado para a organização. Os campos personalizados possuem uma ID de campo exclusiva em vez de um nome legível em inglês. Essa ID de campo exclusiva sempre tem o prefixo cf_ em todas as chamadas. Ao fazer solicitações, você também deve usar como prefixo em todas as IDs de campos personalizados a sequência de caracteres cf_. Essa restrição não se aplica à implementação de XML-RPC da API WS do Service Desk. Observe que todos os campos numéricos personalizados são tratados como tipo inteiro. Os campos de ID O campo de ID é criado automaticamente na inserção e não pode mudar durante o tempo de vida do registro, mesmo que o registro seja excluído e tenha sua exclusão cancelada. Cada valor de ID tem a garantia de ser globalmente exclusivo. A ID de um registro é a melhor maneira de identificá-lo exclusivamente. Ao inserir ou atualizar registros, a API aceita uma ID de número inteiro. 28 Guia de serviços web
Os campos de ID de referência cruzada Os campos de ID de referência cruzada Muitas entidades possuem campos de ID de referência cruzada, que são semelhantes aos campos de chave estrangeira em uma tabela de banco de dados. Em alguns casos, uma entidade pode se referir a outra entidade do mesmo tipo seu. Por exemplo, os tickets possuem um link pai que pode apontar para outro ticket. Você também pode consultar cada entidade de referência cruzada. Quando você consulta um campo de ID de referência cruzada, ele retorna uma ID de entidade do tipo adequado. É possível então consultar essa ID para obter informações adicionais sobre a entidade usando a ID do campo de ID dessa consulta. O valor do campo de ID de referência cruzada é um registro válido na sua organização ou um valor vazio, que indica uma referência vazia. O valor do campo de ID de referência cruzada, se não estiver vazio, tem a garantia de ser uma entidade na sua organização. No entanto, não há garantia de que seja possível consultar essa entidade. Os usuários de uma organização que recebem os privilégios (permissões) necessários para acessar a operação de consulta nessa entidade sempre podem consultá-la. Outros usuários pertencentes à mesma organização podem ter restrições para exibir ou editar a entidade referenciada. A especificação de um valor para um campo de ID de referência cruzada ao inserir ou atualizar um registro também possui limitações. O valor deve ser uma entidade válida do tipo adequado, e o usuário deve ter o acesso apropriado a essa entidade. Campos de texto longo Várias entidades possuem campos de texto longo (256 bytes, 4.000 bytes, etc.) que podem conter dados que se estendem por várias linhas. É possível limpar os campos de texto que não são obrigatórios inserindo ##NULL##. No entanto, se você digitar ##NULL## em um campo obrigatório, você irá receber a mensagem padrão informando que o campo é obrigatório. Capítulo 4: Determinando o tipo de campos padrão 29
Campos ModTimeStamp do sistema Campos ModTimeStamp do sistema A maioria das entidades possui um campo systemmodstamp padrão que contém um carimbo de data e hora de quando o registro foi alterado pela última vez. Esse campo é mantido automaticamente; você não pode inserir, atualizar ou excluir o campo. 30 Guia de serviços web
Capítulo 5: Ocorrências específicas da entidade A maioria das entidades é totalmente explicada pelos seus metadados, mas algumas características específicas da entidade garantem uma explicação adicional. Consulte a API cliente de serviços web para obter uma lista de todos os campos específicos da entidade disponíveis na API WS do Service Desk. Esta seção contém os seguintes tópicos: Anexo (na página 32) Categorização (na página 33) Solicitação de mudança (na página 33) Comunicação (na página 34) Item de configuração (na página 35) Contato (na página 35) Pesquisa definida (na página 35) Incidente (na página 36) Artigo de conhecimento (na página 37) Organização (na página 37) Problema (na página 38) Solicitação de serviço (na página 39) Grupo de suporte (na página 40) Ticket da tarefa (na página 40) Ticket (na página 41) Lista de valores (na página 42) Log de trabalho (na página 43) Capítulo 5: Ocorrências específicas da entidade 31
Anexo Anexo Anexos são arquivos que os usuários carregaram e anexaram a uma entidade pai. As chamadas insert, get e delete oferecem suporte a anexos. A API WS do Service Desk envia e recebe os dados de anexo de arquivo binário codificados como um tipo de dados base64. Antes de inserir, os clientes devem codificar os dados do anexo binário como base64. Ao receber uma resposta da API, os clientes devem decodificar o base64 para binário. A chamada insert restringe os anexos a um tamanho máximo de 3 MB por padrão. As restrições de tamanho máximo de um anexo podem ser configuradas com a modificação do parâmetro de configuração de intervalo MAX_ATTACHMENT_SIZE. Os anexos podem ser consultados, baixados carregados, relacionados a uma entidade pai e excluídos por meio da API WS do Service Desk. Os seguintes tipos de entidade são suportados como pais de anexos: Solicitação de serviço Incidente Problema Solicitação de mudança Ticket da tarefa Item de configuração Artigo de conhecimento 32 Guia de serviços web
Categorização Categorização O Nimsoft Service Desk oferece níveis de categorização para classificação avançada e fornece até quatro níveis de classificação para tickets, itens de configuração, artigos de conhecimento, etc., usando uma taxonomia de Classe, Categoria, Tipo e Item. Os seguintes tipos de entidades podem ser classificados usando a taxonomia CCTI: Solicitação de serviço Incidente Problema Solicitação de mudança Ticket da tarefa Item de configuração Artigo de conhecimento Solicitação de mudança O Nimsoft Service Desk inclui um módulo de mudança baseado em ITIL que permite à central de ajuda avaliar, priorizar, planejar, testar e implementar as solicitações de mudança em toda a organização. A entidade de solicitações de mudança que inclui as entidades filho/subentidades associadas, pode ser consultada, inserida e atualizada por meio da API WS do Service Desk. Os campos personalizados associados a uma solicitação de mudança são tratados como parte da entidade base. Quando você executa uma solicitação get em relação à entidade base da solicitação de mudança, apenas os detalhes de base dessa entidade são retornados; no entanto, os detalhes relacionados às subentidades associadas, como anexos, item de configuração, conformidades com SLA, etc., não serão retornados. As subentidades associadas à solicitação de mudança devem ser consultadas, atualizadas ou excluídas separadamente. Os seguintes tipos de subentidade são suportados como parte da solicitação de mudança: Integrante Log de trabalho Comunicação Descrição O log de trabalho é usado para controlar o trabalho real e o andamento em relação a uma determinada solicitação de mudança. Todas as comunicações de entrada e de saída relacionadas à solicitação de mudança. Capítulo 5: Ocorrências específicas da entidade 33
Comunicação Anexo Item de configuração Tickets relacionados Atividade Conformidade com SLA Anexos são arquivos que os usuários carregaram e anexaram a uma entidade pai. O item de configuração associado à solicitação de mudança. Os tickets relacionados descrevem os relacionamentos estabelecidos entre várias dependências de tickets, entre vários tickets, ao trabalhar com as solicitações de suporte. Tickets "Mestre" e "Subtickets" possuem um relacionamento hierárquico em que os tickets "Relacionados" são exibidos no mesmo nível. A entidade de atividade contém informações históricas sobre as alterações que foram feitas em uma solicitação de mudança. A entidade de atividade é somente leitura por meio da API. A chamada list oferece suporte à atividade. Fornece dados de conformidade com SLA em tempo real para determinar o status da concretização das metas do SLA aplicáveis à solicitação de mudança. Comunicação O Nimsoft Service Desk permite que você e a sua equipe se comuniquem com os clientes internos e externos por meio de envios pela web, email e telefone. O gerenciamento de comunicações no Nimsoft Service Desk fornece um modo muito consistente e profissional de sistema de mensagens do Service Desk para os usuários finais e clientes. As comunicações podem ser consultadas e relacionadas a uma entidade pai por meio da API WS do Service Desk. Os seguintes tipos de entidade são suportados como pais de comunicações: Solicitação de serviço Incidente Problema Solicitação de mudança Ticket da tarefa Comentários sobre o serviço Programação de tarefas 34 Guia de serviços web
Item de configuração Item de configuração O CMDB (Configuration Management Database - BDGC, Base de Dados do Gerenciamento da Configuração) no Nimsoft Service Desk é considerado como a base do suporte do serviço de TI, fornecendo uma visão centralizada dos dados de TI, que são essenciais para a entrega de um serviço consistente, confiável, eficaz e eficiente para os clientes corporativos. A entidade de item de configuração pode ser consultada, inserida e atualizada por meio da API WS do Service Desk. As operações para as entidades filho/subentidades associadas atualmente não são implementadas e poderão ser fornecidas em uma versão futura. As operações para consultar ou atualizar campos personalizados associados a um item de configuração também não são suportadas. Contato O Nimsoft Service Desk gerencia e controla os contatos - usuários finais que enviarão tickets solicitando suporte técnico ou funcionários/agentes que estiverem tomando decisões e resolvendo problemas dos usuários finais. As informações detalhadas de uma ou mais entidades de contato podem ser consultadas por meio da API WS do Service Desk. Pesquisa definida As informações previsíveis repetidamente necessárias podem ser atendidas com pesquisas definidas. O administrador do Nimsoft Service Desk pode predefinir os critérios de pesquisa para que os agentes do Service Desk possam obter os mais úteis resultados de pesquisa. Os direitos de acesso à pesquisa predefinida podem ser definidos para vários grupos/funções/indivíduos. A entidade de pesquisa definida pode ser consultada e executada por meio da API WS do Service Desk, desde que o usuário tenha privilégios de acesso em uma determinada pesquisa predefinida. Capítulo 5: Ocorrências específicas da entidade 35
Incidente Incidente O Nimsoft Service Desk inclui um módulo de gerenciamento de incidentes com base na ITIL, com fluxos de trabalho pré-empacotados, o que permitirá a você identificar, registrar, priorizar, categorizar e acompanhar os incidentes relatados à central de ajuda. A entidade de ticket de incidentes que inclui as entidades filho/subentidades associadas, pode ser consultada, inserida e atualizada por meio da API WS do Service Desk. Os campos personalizados associados a um ticket de incidentes são tratados como parte da entidade base. Quando você executa uma solicitação get em relação à entidade base do ticket de incidentes, apenas os detalhes de base dessa entidade são retornados; no entanto, os detalhes relacionados às subentidades associadas, como anexos, item de configuração, conformidades com SLA, etc., não serão retornados. As subentidades associadas ao ticket de incidentes devem ser consultadas, atualizadas ou excluídas separadamente. Os seguintes tipos de subentidade são suportados como parte do ticket de incidentes: Integrante Log de trabalho Descrição O log de trabalho é usado para acompanhar o trabalho real e o andamento em relação a um determinado ticket de incidentes. Comunicação Todas as comunicações de entrada e de saída relacionadas ao ticket de incidentes. Anexo Anexos são arquivos que os usuários carregaram e anexaram a uma entidade pai. Item de configuração Tickets relacionados Atividade O item de configuração associado ao ticket de incidentes. Os tickets relacionados descrevem os relacionamentos estabelecidos entre várias dependências de tickets, entre vários tickets, ao trabalhar com as solicitações de suporte. Tickets "Mestre" e "Subtickets" possuem um relacionamento hierárquico em que os tickets "Relacionados" são exibidos no mesmo nível. A entidade de atividade contém informações históricas sobre as alterações que foram feitas em um ticket de incidentes. A entidade de atividade é somente leitura por meio da API. A chamada list oferece suporte à atividade. Conformidade com SLA Fornece dados de conformidade com SLA em tempo real para determinar o status da concretização das metas do SLA aplicáveis ao ticket de incidentes. 36 Guia de serviços web
Artigo de conhecimento Artigo de conhecimento O módulo de gerenciamento de conhecimento do Nimsoft Service Desk melhora a qualidade da tomada de decisões pela equipe e a gerência garantindo que informações confiáveis e seguras estejam disponíveis para resolver as ocorrências do serviço. Ele também fornece um meio de os usuários finais explorarem e solucionarem problemas por conta própria antes de solicitar a ajuda da equipe de suporte. A entidade de artigo de conhecimento pode ser consultada, inserida e atualizada por meio da API WS do Service Desk. As operações para acessar ou atualizar as entidades filho/subentidades associadas atualmente não são implementadas e poderão ser fornecidas em uma versão futura. Organização As entidades de organização são usadas para capturar informações da empresa para elas mesmas e para seus clientes, provedores de serviços, fornecedores, fabricantes, etc. em uma estrutura hierárquica de três níveis (organização/site/local). Cada organização pode ter subunidades em níveis inferiores, como sites e locais em um site. A entidade de organização pode ser consultada por meio da API WS do Service Desk. Capítulo 5: Ocorrências específicas da entidade 37
Problema Problema O Nimsoft Service Desk inclui um módulo de gerenciamento de problemas com base em ITIL para ajudar a identificar a causa subjacente de ocorrências de serviço e implementar de forma efetiva a ação corretiva para evitar recorrências e eliminar o impacto dessas ocorrências nos negócios. A entidade de ticket de problema que inclui as entidades filho/subentidades associadas, pode ser consultada, inserida e atualizada por meio da API WS do Service Desk. Os campos personalizados associados a um ticket de problema são tratados como parte da entidade base. Quando você executa uma solicitação get em relação à entidade base do ticket de problema, apenas os detalhes de base dessa entidade são retornados; no entanto, os detalhes relacionados às subentidades associadas, como anexos, item de configuração, conformidades com SLA, etc., não serão retornados. As subentidades associadas ao ticket de problema devem ser consultadas, atualizadas ou excluídas separadamente. Os seguintes tipos de subentidade são suportados como parte do ticket de problema: Integrante Log de trabalho Descrição O log de trabalho é usado para acompanhar o trabalho real e o andamento em relação a um determinado ticket de problema. Comunicação Todas as comunicações de entrada e de saída relacionadas ao ticket de problema. Anexo Anexos são arquivos que os usuários carregaram e anexaram a uma entidade pai. Item de configuração O item de configuração associado ao ticket de problema. Tickets relacionados Os tickets relacionados descrevem os relacionamentos estabelecidos entre várias dependências de tickets, entre vários tickets, ao trabalhar com as solicitações de suporte. Tickets "Mestre" e "Subtickets" possuem um relacionamento hierárquico em que os tickets "Relacionados" são exibidos no mesmo nível. Atividade A entidade de atividade contém informações históricas sobre as alterações que foram feitas em um ticket de problema. A entidade de atividade é somente leitura por meio da API. A chamada list oferece suporte à atividade. 38 Guia de serviços web