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
Site
Protocolo de acesso a objeto
simples (SOAP) 1.1
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:
12 Guia de serviços web
■
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.
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
Descrição
Obter
Recuperar campos especificados de um registro com base no identificador do registro
Listar
Recupera os registros com base nos critérios de pesquisa especificados
Inserir
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
Modificar um registro existente com as informações especificadas
Excluir
Excluir um registro existente com base no identificador do registro
Relacionar
Relaciona um registro de entidade identificado pelo identificador de registro com outra
entidade identificada pelo identificador de registro
Cancelar relação
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
Valor
targetNameSpace
http://www.inteqnet.com
xmlns
http://schemas.xmlsoap.org/wsdl/
xmlns:soap
http://schemas.xmlsoap.org/wsdl/soap/
xmlns:xsd
http://www.w3.org/2001/XMLSchema
xmlns:wsdl
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
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:
Argumento
Description
Credenciais
authorizationToken
Token de autorização de cliente do serviço web
sliceToken
Token de intervalo de cliente do serviço web
username
Nome de usuário cliente do serviço web
userPassword
Senha de usuário cliente do serviço web
Configurações estendidas
responseFormat
Formato de dados de saída do serviço web (JSON, XML e JavaBean)
Resposta a todas as chamadas:
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
Integrantes
Descrição
Resposta de serviço padrão
Capítulo 3: Chamadas de API do serviço web 17
A chamada get
responseStatus
O status da mensagem de saída de uma chamada de serviço web
statusCode
O código de status da resposta do serviço web
statusMessage
Mensagem de status da resposta do serviço web
responseFormat
O formato da mensagem de saída de uma chamada de serviço web
responseText
O texto formatado da mensagem de saída (aplicável aos tipos de formato XML, JSON)
responseBean
A classe de bean de saída específica do serviço (aplicável quando o formato da resposta
for BEAN)
erros
A lista de mensagens de erro que ocorreram durante a chamada de serviço web
warnings
A lista de mensagens de aviso informando o cliente sobre problemas não fatais ou
condições que podem causar problemas
observações
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
Descrição
Identificador de registro
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
Descrição
Pesquisar texto
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
Descrição
Classe do bean
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
Descrição
Identificador de registro
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
Descrição
Identificador de registro
Identificador de registro (ID de linha) de uma entidade à qual outra entidade deve
estar relacionada
Identificador de registro
relacionado
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
Descrição
Identificador de registro
Identificador de registro (ID de linha) de uma entidade cuja relação com outra
entidade deve ser cancelada
Identificador de registro
relacionado
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
Descrição
Dígitos
Especifica o número máximo de dígitos que pode ter um número inteiro
Escala
Para campos duplos, especifica o número máximo de dígitos à direita da vírgula decimal.
Precisão
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:
32 Guia de serviços web
■
Solicitação de serviço
■
Incidente
■
Problema
■
Solicitação de mudança
■
Ticket da tarefa
■
Item de configuração
■
Artigo de conhecimento
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
Descrição
Log de trabalho
O log de trabalho é usado para controlar o trabalho real e o andamento em relação a
uma determinada solicitação de mudança.
Comunicação
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
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 à solicitação de mudança.
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 uma solicitação de mudança. 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 à 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:
34 Guia de serviços web
■
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
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
Descrição
Log de trabalho
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
O item de configuração associado ao ticket de incidentes.
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 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
Descrição
Log de trabalho
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
Solicitação de serviço
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 problema.
Solicitação de serviço
O Nimsoft Service Desk oferece a capacidade de publicar um catálogo de solicitações
comuns a serviços de TI e que não sejam de TI. Os catálogos de serviços aproveitam os
recursos de roteamento, as aprovações, o gerenciamento de nível de serviço e outros
recursos do aplicativo necessários para atender a uma solicitação.
A entidade de solicitação de serviço 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 serviço são tratados
como parte da entidade base.
Quando você executa uma solicitação get em relação à entidade base da solicitação de
serviço, 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 serviço devem ser consultadas, atualizadas
ou excluídas separadamente. Os seguintes tipos de subentidade são suportados como
parte da solicitação de serviço:
Integrante
Descrição
Log de trabalho
O log de trabalho é usado para acompanhar o trabalho real e o andamento em
relação a uma determinada solicitação de serviço.
Comunicação
Todas as comunicações de entrada e de saída relacionadas à solicitação de serviço.
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 à solicitação de serviço.
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 uma solicitação de serviço. A entidade de atividade é somente leitura por
meio da API. A chamada list oferece suporte à atividade.
Capítulo 5: Ocorrências específicas da entidade 39
Grupo de suporte
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 à solicitação de serviço.
Grupo de suporte
O conceito de um grupo de suporte é ter agentes do Service Desk que lidam com o
mesmo tipo de atribuições agrupadas, organizados como grupos de trabalho ou grupo
de suporte mais habilitados, fornecendo um suporte técnico de nível mais alto.
Os contatos no Service Desk são agrupados e atribuídos ou se tornam integrantes de
diferentes grupos de suporte com vários objetivos, como permissão, atribuição,
Notificação, aprovação, etc.
As informações detalhadas de uma ou mais entidades de grupos de suporte podem ser
consultadas por meio da API WS do Service Desk.
Ticket da tarefa
O Service Desk fornece a capacidade de dividir o trabalho relacionado a resolução de
solicitação de serviço/incidente/problema/alteração em componentes individuais que
podem ser atribuídos a vários grupos ou indivíduos diferentes, ao mesmo tempo em
que permite que o ticket original permaneça em propriedade da pessoa que o está
resolvendo.
A entidade de ticket de tarefa 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 tarefa são tratados como parte da
entidade base.
Quando você executa uma solicitação get em relação à entidade base do ticket de
tarefa, 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 tarefa devem ser consultadas, atualizadas ou
excluídas separadamente. Os seguintes tipos de subentidade são suportados como
parte do ticket de tarefa:
Integrante
Descrição
Log de trabalho
O log de trabalho é usado para acompanhar o trabalho real e o andamento em
relação a um determinado ticket de tarefa.
40 Guia de serviços web
Ticket
Comunicação
Todas as comunicações de entrada e de saída relacionadas ao ticket de tarefa.
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 tarefa.
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 tarefa. 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 tarefa.
Ticket
Esta entidade permite o acesso à funcionalidade do Service Desk para todos os tipos de
tickets como uma entidade de ticket genérica. A entidade de ticket 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 são
tratados como parte da entidade base.
Quando você executa uma solicitação get em relação à entidade base do ticket, apenas
os detalhes de base dessa entidade são retornados; no entanto, os detalhes
relacionados às subentidades associadas, como anexos, item de configuração,
conformidade com SLA, etc., não serão retornados.
As subentidades associadas ao ticket devem ser consultadas, atualizadas ou excluídas
separadamente. Os seguintes tipos de subentidade são suportados como parte do
ticket:
Integrante
Descrição
Log de trabalho
O log de trabalho é usado para acompanhar o trabalho real e o andamento em
relação a um determinado ticket.
Capítulo 5: Ocorrências específicas da entidade 41
Lista de valores
Comunicação
Todas as comunicações de entrada e de saída relacionadas ao ticket.
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.
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. 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.
Lista de valores
O Nimsoft Service Desk fornece uma capacidade para ter listas dinâmicas enumeradas
para diferentes tipos de elementos de campo em diferentes domínios funcionais.
A entidade de lista de valores pode ser consultada por meio da API WS do Service Desk.
Os tipos de entidade a seguir atualmente estão usando a lista de valores.
42 Guia de serviços web
■
Solicitação de serviço
■
Incidente
■
Problema
■
Solicitação de mudança
■
Ticket da tarefa
Log de trabalho
Log de trabalho
Logs de trabalho são entradas manuais no ticket, feitas para registrar informações
relevantes ou significativas para o ticket e que não são automaticamente capturadas
pelo Nimsoft Service Desk.
A entidade de log de trabalho pode ser consultada, inserida e atualizada por meio da
API WS do Service Desk.
Os seguintes tipos de entidade são suportados como pais de logs de trabalho:
■
Solicitação de serviço
■
Incidente
■
Problema
■
Solicitação de mudança
■
Ticket da tarefa
Capítulo 5: Ocorrências específicas da entidade 43
Capítulo 6: Apêndice A: Códigos de status
As solicitações de API WS do Service Desk sempre retornam uma resposta padrão. Deve
ser usado um status de resposta para determinar se a solicitação foi bem-sucedida ou
não. A resposta padrão compreende um código de status e uma mensagem de texto de
status associada.
A mensagem de status é uma breve descrição em inglês que pode ser exibida para o
usuário como uma mensagem de status minimamente descritiva. Se você exibir a
mensagem de status, também deverá exibir o código de status.
Os clientes sempre devem reconhecer os códigos de status, não as mensagens de
status. Quando uma solicitação não puder ser concluída com êxito, será retornada uma
mensagem sobre a falha real ou uma mensagem de erro que podem ser ligeiramente
diferentes das mensagens listadas neste apêndice.
Algumas falhas são específicas a determinadas chamadas, enquanto outras são falhas
mais gerais que podem ocorrer em qualquer chamada, como o código de status 100
para uma mensagem de Acesso negado devido a credenciais inválidas.
0xx: código de status de êxito
Mensagem
000
Êxito: a solicitação foi atendida pelo servidor; o serviço retornou resultados
da operação.
001
Êxito: a solicitação foi atendida pelo servidor; nenhum resultado foi
retornado pelo serviço.
1xx: código de status de erro de
autorização
Mensagem
100
Não autorizado: acesso negado devido a credenciais inválidas.
101
Erro de licença: você não tem uma licença apropriada para usar nenhum
serviço.
2xx: código de status de erro de
acesso à operação
Mensagem
200
Erro de invocação: a definição de operação para o serviço solicitado não foi
encontrada.
201
Erro de invocação: a operação do serviço solicitado foi desativada.
3xx: código de status de erro de
pré-processamento da operação
Mensagem
300
Erro de execução: um erro inesperado ocorreu durante a transformação de
dados dos parâmetros da solicitação transmitidos ao chamar o serviço web: {
0} .{ 1} .
Capítulo 6: Apêndice A: Códigos de status 45
Log de trabalho
301
Erro de execução: um erro inesperado ocorreu durante a validação de dados
dos parâmetros da solicitação transmitidos ao chamar o serviço web: { 0} .{
1} .
4xx: código de status de erro de
execução de ponto de
extremidade
Mensagem
400
Erro de execução: ocorreu uma exceção não tratada no ponto de
extremidade do serviço (provedor) durante a execução do serviço solicitado.
401
Erro de execução: alguns erros foram capturados pelo ponto de extremidade
do serviço (provedor) durante a execução do serviço solicitado.
402
Erro de execução: ocorreu um erro inesperado ao processar a resposta do
serviço no formato solicitado.
403
Erro de execução: ocorreu um erro inesperado ao processar o serviço
solicitado.
46 Guia de serviços web
Capítulo 7: Apêndice B: Exemplos de cliente
de serviços web
A API de serviços web do Service Desk se baseia no projeto The Apache Axis2, que é
uma implementação baseada em Java da equação de serviços web de cliente e servidor.
O Axis é essencialmente um mecanismo do SOAP -- uma estrutura para a construção de
processadores de SOAP como clientes, servidores, gateways, etc.
Os exemplos a seguir demonstram a estrutura de desenvolvimento de código de cliente
para consumir serviços web do Service Desk.
As etapas a seguir são necessárias para consumir todos os tipos de serviços web do
Service Desk.
Esta seção contém os seguintes tópicos:
Configurando o ambiente (na página 47)
Gerando o código de cliente do Axis2 usando a ferramenta "wsdl2java" (na página 48)
Sequência de chamada de API comum (na página 49)
Exemplo de cliente da chamada get (na página 49)
Exemplo de cliente da chamada list (na página 52)
Exemplo de cliente da chamada insert (na página 55)
Exemplo de cliente da chamada update (na página 59)
Exemplo de cliente da chamada delete (na página 63)
Configurando o ambiente
Faça download da versão binária do Apache Axis2 e extraia a versão binária
(axis2-1.5.1-bin.zip). Após extrair o arquivo para E:Axis2Client (considerando seu
diretório cliente), você obterá um diretório "E:Axis2Clientaxis2-1.5.1-binaxis2-1.5.1" que
contém a versão binária do mecanismo do Apache Axis2. Agora, defina as variáveis de
ambiente invocando o seguinte código em uma linha de comando:
@set AXIS2_HOME=D:\ java-tools\ axis2-1.5.1
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 47
Gerando o código de cliente do Axis2 usando a ferramenta "wsdl2java"
Gerando o código de cliente do Axis2 usando a ferramenta
"wsdl2java"
Um arquivo WSDL (Web Services Description Language - Linguagen de Descrição de
Serviços Web) descreve um serviço web. A especificação JAX-RPC (Java API for
XML-based Remote Procedure Call) 1.1 define um mapeamento de API Java que
interage com o serviço web.
A especificação de serviços web para a plataforma J2EE (Java 2, Enterprise Edition) 1.1
define descritores de implantação que implantam um serviço web em um ambiente
J2EE. O comando WSDL2Java é executado no arquivo WSDL para criar APIs Java e
modelos de descritor de implantação de acordo com essas especificações.
A sintaxe da linha de comando é:
WSDL2Java [arguments] WSDL-URI
Em uma linha de comando, gere o código de cliente para o serviço web ServiceRequest
emitindo o seguinte comando:
%AXIS2_HOME%\ bin\ WSDL2Java –url
http://nsd-preview.nimsoftondemand.com/webservices/ServiceRequest?wsdl -o
com/infradeskonline/genclient
Onde
48 Guia de serviços web
■
O "-url" é o caminho onde você salvou uma cópia do wsdl para ".wsdl" ou
".xml", ou é o URL onde o WSDL reside.
■
O "-o" é o caminho onde você deseja que os arquivos sejam gravados. Se não
for especificado, os arquivos serão gravados no local do compartimento atual.
■
O comando acima gerará "ServiceRequestStub.java" e
"ServiceRequestCallbackHandler.java" no diretório
"com/infradeskonline/genclient".
Sequência de chamada de API comum
Sequência de chamada de API comum
Para cada chamada, o aplicativo cliente em geral:
Prepara a solicitação definindo os parâmetros de solicitação, se aplicável.
Invoca a chamada, que envia a solicitação com os parâmetros para o serviço web do
Service Desk para processamento.
Recebe a resposta da API.
Gerencia a resposta, processando os dados retornados (para uma invocação
bem-sucedida) ou tratando o erro (para uma falha de invocação).
Exemplo de cliente da chamada get
Desenvolvendo o código para chamar o serviço
A seguir está um exemplo de um programa cliente do Axis que chama a operação
getServiceRequest para consultar um extrato dos detalhes principais (informações
gerais) referentes à solicitação de serviço identificada pelo identificador de ticket
especificado, no formato de saída XML.
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 49
Exemplo de cliente da chamada get
public class ServiceRequestClient
{
public void main (
String [] args)
{
try
{
// Create the request
ServiceRequestStub
srqStub
=
new ServiceRequestStub();
ServiceRequestStub.Credentials
credentials
=
new ServiceRequestStub.Credentials();
ServiceRequestStub.ExtendedSettings
extParams
=
new ServiceRequestStub.ExtendedSettings();
// Initialize Credentials (User Name & User Password / Authorization Token
& Slice Token)
credentials.setUserName (
"wsuser");
credentials.setUserPassword (
"wsuser");
// Initialize Extended Settings such as Response Format (XML, JSON)
extParams.setResponseFormat (
"XML");
// Invoke the GET service
ServiceRequestStub.DefaultServiceResponse serviceResponse =
srqStub.getServiceRequest (credentials, extParams, ticketIdentifier);
// Inspect successful execution of service and retrieve the response text
if (serviceResponse.getResponseStatus ().equals (
"OK"))
{
50 Guia de serviços web
Exemplo de cliente da chamada get
System.out.println(
"XML Response : " + serviceResponse.getResponseText ());
}
// Retrieve the status code, status message and error messages, in
case of failures
else
{
System.out.println(
"Status Code : " + serviceResponse.getStatusCode ());
System.out.println(
"Status Message : " + serviceResponse.getStatusMessage ());
System.out.println(
"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
}
}
catch (Exception e)
{
System.out.println (
"Exception: " + e.getMessage());
}
}
}
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 51
Exemplo de cliente da chamada list
Exemplo de cliente da chamada list
Desenvolvendo o código para chamar o serviço
A seguir está um exemplo de um programa Axis cliente que chama a operação
listServiceRequest para consultar o retorno da lista de todas as solicitações de serviço
em aberto para o usuário conectado e seus grupos que correspondem aos critérios de
pesquisa especificados, no formato de saída JSON.
52 Guia de serviços web
Exemplo de cliente da chamada list
public class ServiceRequestClient
{
public void main (
String [] args)
{
try
{
// Create the request
ServiceRequestStub
srqStub
=
new ServiceRequestStub();
ServiceRequestStub.Credentials
credentials
=
new ServiceRequestStub.Credentials();
ServiceRequestStub.ExtendedSettings
extParams
=
new ServiceRequestStub.ExtendedSettings();
// Initialize Credentials (User Name & User Password / Authorization Token
& Slice Token)
credentials.setUserName (
"wsuser");
credentials.setUserPassword (
"wsuser");
// Initialize Extended Settings such as Response Format (XML, JSON)
extParams.setResponseFormat (
"JSON");
// Invoke the LIST service
ServiceRequestStub.DefaultServiceResponse serviceResponse =
srqStub.listServiceRequest (credentials, extParams, ticketIdentifier);
// Inspect successful execution of service and retrieve the response text
if (serviceResponse.getResponseStatus ().equals (
"OK"))
{
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 53
Exemplo de cliente da chamada list
System.out.println(
"JSON Response : " + serviceResponse.getResponseText ());
}
// Retrieve the status code, status message and error messages, in
case of failures
else
{
System.out.println(
"Status Code : " + serviceResponse.getStatusCode ());
System.out.println(
"Status Message : " + serviceResponse.getStatusMessage ());
System.out.println(
"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
}
}
catch (Exception e)
{
System.out.println (
"Exception: " + e.getMessage());
}
}
}
54 Guia de serviços web
Exemplo de cliente da chamada insert
Exemplo de cliente da chamada insert
Desenvolvendo o código para chamar o serviço
A seguir está um exemplo de um programa Axis cliente que chama a operação
listServiceRequest para criar/registrar um novo ticket de solicitação de serviço com os
detalhes fornecidos.
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 55
Exemplo de cliente da chamada insert
public class ServiceRequestClient
{
public void main (
String [] args)
{
try
{
// Create the request
ServiceRequestStub
srqStub
=
new ServiceRequestStub();
ServiceRequestStub.Credentials
credentials =
new ServiceRequestStub.Credentials();
ServiceRequestStub.ExtendedSettings
extParams
=
new ServiceRequestStub.ExtendedSettings();
ServiceRequestStub.ServiceRequest
srqBean
=
new ServiceRequestStub.ServiceRequest();
// Initialize Credentials (User Name & User Password / Authorization Token
& Slice Token)
credentials.setUserName (
"wsuser");
credentials.setUserPassword (
"wsuser");
// Initialize Extended Settings such as Response Format (XML, JSON)
extParams.setResponseFormat (
"JSON");
// Initialize Service Request Bean with neccessary details
srqBean.setRequester_name (
"Admin, InteQ");
srqBean.setTicket_description (
"Ticket creation via webservice# " +
56 Guia de serviços web
Exemplo de cliente da chamada insert
new Date());
// Invoke the INSERT service
ServiceRequestStub.DefaultServiceResponse serviceResponse =
srqStub.logServiceRequest (credentials, extParams, srqBean);
// Inspect successful execution of service and retrieve the response text
if (serviceResponse.getResponseStatus ().equals (
"OK"))
{
System.out.println(
"JSON Response : " + serviceResponse.getResponseText ());
}
// Retrieve the status code, status message and error messages, in
case of failures
else
{
System.out.println(
"Status Code : " + serviceResponse.getStatusCode ());
System.out.println(
"Status Message : " + serviceResponse.getStatusMessage ());
System.out.println(
"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
}
}
catch (Exception e)
{
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 57
Exemplo de cliente da chamada insert
System.out.println (
"Exception: " + e.getMessage());
}
}
}
58 Guia de serviços web
Exemplo de cliente da chamada update
Exemplo de cliente da chamada update
Desenvolvendo o código para chamar o serviço
A seguir está um exemplo de um programa Axis Client que chama a operação
listServiceRequest para atualizar um ticket de solicitação de serviço existente
identificado por row_id "123" com os detalhes fornecidos.
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 59
Exemplo de cliente da chamada update
public class ServiceRequestClient
{
public void main (
String [] args)
{
try
{
// Create the request
ServiceRequestStub
srqStub
=
new ServiceRequestStub();
ServiceRequestStub.Credentials
credentials =
new ServiceRequestStub.Credentials();
ServiceRequestStub.ExtendedSettings
extParams
=
new ServiceRequestStub.ExtendedSettings();
ServiceRequestStub.ServiceRequest
srqBean
=
new ServiceRequestStub.ServiceRequest();
// Initialize Credentials (User Name & User Password / Authorization Token
& Slice Token)
credentials.setUserName (
"wsuser");
credentials.setUserPassword (
"wsuser");
// Initialize Extended Settings such as Response Format (XML, JSON)
extParams.setResponseFormat (
"JSON");
// Initialize Service Request Bean with neccessary details
srqBean.setRow_id (123);
srqBean.setTicket_description (
"Updated - Ticket creation via webservice# " +
new Date());
// Invoke the UPDATE service
60 Guia de serviços web
Exemplo de cliente da chamada update
ServiceRequestStub.DefaultServiceResponse serviceResponse =
srqStub.logServiceRequest (credentials, extParams, srqBean);
// Inspect successful execution of service and retrieve the response text
if (serviceResponse.getResponseStatus ().equals (
"OK"))
{
System.out.println(
"JSON Response : " + serviceResponse.getResponseText ());
}
// Retrieve the status code, status message and error messages, in
case of failures
else
{
System.out.println(
"Status Code : " + serviceResponse.getStatusCode ());
System.out.println(
"Status Message : " + serviceResponse.getStatusMessage ());
System.out.println(
"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
}
}
catch (Exception e)
{
System.out.println (
"Exception: " + e.getMessage());
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 61
Exemplo de cliente da chamada update
}
}
}
62 Guia de serviços web
Exemplo de cliente da chamada delete
Exemplo de cliente da chamada delete
Desenvolvendo o código para chamar o serviço
A seguir está um exemplo de um programa Axis cliente que chama a operação
deleteAttachment para excluir a entrada de documento de anexo do banco de dados
identificado pelo Row Id# 12.
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 63
Exemplo de cliente da chamada delete
public class AttachmentClient
{
public void main (
String [] args)
{
try
{
// Create the request
AttachmentStub
new AttachmentStub();
AttachmentStub.Credentials
attachmentStub =
credentials
new AttachmentStub.Credentials();
AttachmentStub.ExtendedSettings extParams
=
=
new AttachmentStub.ExtendedSettings();
// Initialize Credentials (User Name & User Password / Authorization Token
& Slice Token)
credentials.setUserName (
"wsuser");
credentials.setUserPassword (
"wsuser");
// Initialize Extended Settings such as Response Format (XML, JSON)
extParams.setResponseFormat (
"JSON");
// Invoke the DELETE service
AttachmentStub.DefaultServiceResponse serviceResponse =
attachmentStub.deleteAttachment (credentials, extParams,
"12");
// Inspect successful execution of service and retrieve the response text
if (serviceResponse.getResponseStatus ().equals (
"OK"))
64 Guia de serviços web
Exemplo de cliente da chamada delete
{
System.out.println(
"JSON Response : " + serviceResponse.getResponseText ());
}
// Retrieve the status code, status message and error messages, in
case of failures
else
{
System.out.println(
"Status Code : " + serviceResponse.getStatusCode ());
System.out.println(
"Status Message : " + serviceResponse.getStatusMessage ());
System.out.println(
"Errors : " + Arrays.asList (serviceResponse.getErrors ()).toString ());
}
}
catch (Exception e)
{
System.out.println (
"Exception: " + e.getMessage());
}
}
}
Capítulo 7: Apêndice B: Exemplos de cliente de serviços web 65