Interface de API de texto do CA SDM

Este artigo contém os seguintes tópicos:
casm173
Este artigo contém os seguintes tópicos:
Visão geral da API de texto
API de texto
é uma interface que permite usar entradas com base em texto para criar e atualizar objetos no banco de dados do CA SDM, como ocorrências, solicitações, contatos e ativos. Usando a API de texto, é possível atribuir valores à maioria dos campos que estão acessíveis aos usuários.
O CA SDM requer que todas as entradas estejam no formato UTF-8, ou os dados poderão ser corrompidos. O utilitário pdm_unconv permite converter dados de um conjunto de caracteres locais em UTF-8, e de UTF-8 em um conjunto de caracteres locais.
Você pode acessar a API de texto usando as seguintes interfaces:
  • Linha de comando
  • Email
É possível usar os serviços web como uma alternativa à API de texto para integração entre aplicativos.
Interface de linha de comando
Use o comando
pdm_text_cmd
para ativar a interface de linha de comando da API de texto. É possível então especificar certas informações, como a tabela a ser processada e a operação a ser executada, usando parâmetros do comando pdm_text_cmd.
A entrada da API de texto é passada ao comando pdm_text_cmd na forma de um arquivo de entrada ou diretamente do STDIN.
Ao transmitir os parâmetros do prompt de comando, use Ctrl+Z no Windows e Ctrl+D no POSIX.
Você não pode usar aspas simples ou duplas como parâmetros para os comandos bop_cmd e pdm_text_nxd.
Formato de entrada
A entrada para a API de texto é especifica das seguintes formas:
  • Na interface de linha de comando, a entrada é tipicamente especificada em um arquivo de texto passado para o comando
    pdm_text_cmd
    .
  • Na interface de email, a entrada é especificada no texto do email. Você especifica uma expressão comum para localizar os identificadores do objeto de destino.
Você formata a entrada da API de texto da mesma forma, não importa a interface que usar.
O formato básico da entrada é o seguinte:
%keyword=value
ou
%PROPERTY={{property_label}}value
O comportamento normal dos comandos da API de texto tem as seguintes exceções, onde a última ocorrência de dois ou mais comandos conflitantes tem precedência:
  • Quando uma mensagem contém vários objetos ID de ticket válidos que correspondem à sequência de caracteres de filtro da caixa de correio, ou vários comandos da ID de ticket da API de texto, o primeiro encontrado é usado. Além disso, um objeto ID de ticket, que é identificado usando a sequência de caracteres de filtro de caixa de correio, sobrescreve qualquer comando da ID de ticket da API de texto, independentemente de qual aparecer primeiro.
  • Quando uma mensagem contém vários comandos da API de texto de comentário de log, todos os comentários são publicados, apesar de que a ordem em que aparecem no log de atividade do ticket pode variar.
Todos os objetos ID de ticket que correspondem ao filtro, válidos ou não, e os comandos da ID de ticket da API de texto dentro da mensagem, aplicáveis ou não, são comentados antes que a mensagem seja publicada. Os objetos ID de ticket identificados por meio de filtros de regra de caixa de correio aparecem como -((...))-. Sinais de porcentagem à esquerda (%) em comandos da ID de ticket da API de texto são convertidos em dois parênteses de abertura ((, e dois parênteses de fechamento )) seguem-se ao comando. Se o comando da ID de ticket da API de texto aparecer depois de outro comando da API de texto com um comentário de log (%LOG=…), o comando comentado da ID de ticket da API de texto será feito em um comentário de log separado.
O comentário de log é o único comando da API de texto que pode aparecer várias vezes em uma mensagem e ainda assim ter cada ocorrência aplicada. Para qualquer outro comando, a API de texto usa somente a última ocorrência, porque várias ocorrências de outros comandos conflitam entre si. Vários comandos de comentário de log publicam mensagens de comentário de log separadas para o ticket, e não necessariamente em qualquer ordem particular.
Adicionalmente, se um comando da ID de ticket da API de texto aparecer na mensagem, seja no início da mensagem ou entre dois outros comandos da API de texto, ele é convertido em um comentário de log. Se o comando anterior é um comentário de log (%LOG=…) ou descrição de atualização (%DESCRIPTION=…), ele é anexado a aquele comando, em vez de tornar-se um comentário de log separado.
Como a API de texto usa palavras-chave
Você pode usar dois tipos de palavras-chave como entrada para a API de texto.
  • As definições na seção [KEYWORDS] do arquivo
    text_api.cfg
    - Este tipo é um grupo de palavras-chave relacionadas diretamente aos campos das várias tabelas que você pode atualizar. Por exemplo, a maioria dos campos no formulário Issue Detail é definida na seção [KEYWORDS]. Ao usar essas palavras-chave, você pode definir valores para campos no registro que atualizar ou criar. Por exemplo, a seguinte linha define a prioridade da ocorrência como 5:
    %PRIORITY=5
    A seção [KEYWORDS] do arquivo
    text_api.cfg
    lista todas as palavras-chave. É possível definir palavras-chave adicionais (por exemplo, para permitir acesso da API de texto a campos que foram adicionados durante a personalização do esquema de banco de dados).
  • As palavras-chave especiais a seguir são sempre definidas como abaixo, independentemente do conteúdo do arquivo
    text_api.cfg
    :
Palavra-chave
Descrição
ASSET
Usado para anexar um item a um ticket (válido para solicitações, ocorrências e requisições de mudança). O valor especificado é o nome do item, o qual já deve existir. É possível especificar essa palavra-chave várias vezes, pois um ticket pode ter vários itens anexados a ele.
ATTACHMENT
Usada internamente pela interface de email para adicionar anexos de email a um ticket.
DESCRIÇÃO
Especifica o valor a usar para o campo de descrição do ticket. Essa palavra-chave é adotada quando a entrada é enviada à API de texto sem uma palavra-chave explícita. Esta palavra-chave é aplicada automaticamente pelo Mail Eater quando a mensagem não inicia com a palavra-chave, mas contém um artefato ou palavra-chave da ID de ticket.
Você pode alterar o modo como a palavra-chave DESCRIPTION é tratada para atualizações usando a seguinte entrada na seção [OPTIONS] de text_api.cfg:
UPDATE_DESC_IS_LOG
Se essa opção for definida como YES (SIM), o valor será usado para criar um comentário de log. Se o valor for definido como NO (NÃO), o valor substitui o campo existente de descrição.
FROM_EMAILFROM_EMAIL_OVERRIDE
Usados pela interface de email para fazer a correspondência com o campo de Endereço de email no registro de ca_contact. Também é usado como o log_agent para o ticket. Se ambos forem fornecidos, FROM_EMAIL é ignorado.
FROM_EMAIL é definido automaticamente pelo Mail Eater com o endereço do remetente da mensagem.
FROM_PERSID
Usado pela interface de linha de comando para definir o log_agent para uma operação (por exemplo, quando um registro de ca_contact não possui uma ID de usuário). Esta palavra-chave é passada automaticamente por pdm_text_cmd se o parâmetro -p for especificado
.
O valor é combinado com a persistent_id do registro ca_contact.
FROM_USERID
Usado apenas na interface de linha de comando para definir o log_agent para uma operação. Esta palavra-chave é passada automaticamente por
pdm_text_cmd
se o parâmetro -u for especificado. O valor é combinado com a ID de usuário de um contato.
LOG
Usado para criar uma entrada de log (válido para solicitações, requisições de mudança, ocorrências e contatos). Esta palavra-chave é aplicada automaticamente pelo Mail Eater quando a mensagem não inicia com uma palavra-chave, mas contém um artefato ou uma palavra-chave da ID de ticket, ou a palavra-chave DESCRIPTION.
PROPERTY
Usado para definir o valor de uma propriedade (válido apenas para solicitações, requisições de mudança e ocorrências). Diferentemente de outras palavras-chave, que são seguidas por um sinal de igual e um valor, a sintaxe da palavra-chave PROPERTY deve incluir o rótulo de propriedade, como mostrado a seguir:
PROPERTY={{rótulo_propriedade}}valor
Você deve especificar o
rótulo_propriedade
exatamente como aparece no banco de dados.
SEARCH
Usada apenas na interface de linha de comando para fornecer uma lista de palavras-chave para uso em uma consulta para atualizar vários tickets de um ativo. O valor é uma lista de palavras-chave usadas na pesquisa.
Convenções de entrada de palavra-chave
As seguintes convenções aplicam-se à formatação de entrada de palavra-chave:
  • Todas as palavras-chave (incluindo PROPERTY) devem ter um sinal de por cento (%) como prefixo. O sinal de por centro deve estar na posição um da coluna. Se a primeira linha não vazia da entrada não tiver um sinal de por cento no início, %
    DESCRIPTION= ou %LOG=
    é usado como prefixo para os dados recebidos, dependendo de se uma palavra-chave ou um objeto da ID de ticket foi encontrado. Se for definido
    %DESCRIPTION
    , os conteúdos da mensagem até a primeira palavra-chave são postados como uma descrição de ticket. Se for definido
    %LOG
    , os conteúdos da mensagem até a primeira palavra-chave são postados como um comentário de log.
  • Não use espaços entre o sinal de porcentagem e a palavra-chave, nem entre a palavra-chave e o sinal de igual (=).
  • Não inclua valores entre aspas; todos os dados depois do sinal de igual são considerados como o valor.
  • Palavras-chave não diferenciam maiúsculas de minúsculas.
  • Se a entrada incluir palavras-chave duplicadas, a última palavra-chave é usada; caso contrário, a ordem em que você especificou os pares palavra-chave/valor não é importante.
  • Especifique valores de palavra-chave como faria para o campo correspondente na interface da Web. Por exemplo, para especificar um tipo de contato Analista, você usaria
    %CONTACT_TYPE=Analyst
    , embora no banco de dados esse valor esteja armazenado como um número inteiro. A palavra-chave
    CONTACT_TYPE
    é definida em
    text_api.cfg
    , de modo que o valor especificado é convertido para corresponder ao valor armazenado.
    A diferenciação entre maiúsculas e minúsculas no valor depende do seu DBMS subjacente.
  • Você pode distribuir os dados de seqüências de caracteres em várias linhas.
Formatar uma mensagem de email para atualizar um ticket
Um usuário pode formatar uma mensagem de email para criar ou atualizar um ticket.
Para formatar uma mensagem de email para criar ou atualizar um ticket, use os seguintes campos:
  • a
    Especifica o nome da caixa de correio atribuído ao contato do CA SDM configurado para o usuário privilegiado.
  • De
    Especifica a pessoa enviando o email. A pessoa deve ser definida na tabela
    ca_contact
    , a menos que a opção
    Permitir anônimo
    esteja especificada na regra da caixa de correio aplicável.
    O endereço De normalmente é parte da configuração do programa de email, e normalmente não é configurado em uma base por mensagem.
  • Anexos
    Anexa documentos e outros arquivos ao email para enviar anexos à API de texto.
  • Assunto
    Combina palavras-chave em uma sequência de caracteres de filtro de regras da caixa de correio, particularmente ao criar um ticket.
  • Corpo
    Especifique o corpo da mensagem do email usando a API de texto. Você pode especificar a palavra-chave
    ISSUE_ID
    ,
    REQUEST_ID
    ou
    CHANGE_ID
    , dependendo do tipo de ticket para criar ou atualizar um ticket.
Delimitadores de início e final de mensagens de email
Algumas interfaces de email adicionam informações ao começo ou ao final de mensagens de email (por exemplo, codificação MIME) isso pode fazer com que a interface de email não funcione corretamente.Se a sua interface de email adiciona informações, é possível usar os seguintes delimitadores:
start-request
e
end-request
. A interface de email ignora as informações especificadas antes de start-request e depois de end-request.
O Maileater do CA SDM agora oferece suporte a HTML e RTF (Rich Text Format) para emails de entrada.
Exemplo: Use delimitadores start-request e end-request
"start-request" message_body "end-request"
Como a API de texto usa objetos
A API de texto processa o assunto ou corpo de notificações de email. Regras da caixa de correio permitem identificar objetos e valores que a API de texto usa. Por exemplo, é possível definir a regra para incidentes como Incident:{{object_id}}, então encontrar Incident:1234 se traduz para %INCIDENT_ID=1234 para a API de texto. 1234 é o ref_num para o Incidente. Porque o objeto deve ser único em um email e fácil de encontrar, você pode tornar o objeto mais distinto, como %Incident:{{object_id}}%.
Siga a palavra-chave {{object_id}} do objeto com um caractere que não seja uma letra, número, vírgula, barra (/), sinal de mais (+) ou sinal de igual (=), porque esses caracteres podem aparecer em um objeto. Caso contrário, é possível que os caracteres que seguem o objeto sejam mal interpretados como parte do valor do objeto, ou que um caractere no valor do objeto seja mal interpretado como o caractere que segue o valor.
O Mail Eater faz o seguinte:
  1. Encontra o objeto em um email (como Incidente:1234) que mapeia para o ticket adequado ou outro objeto suportado pela API de texto.
  2. Traduz o objeto em um token de API de texto (como %INCIDENT_ID=1234).
  3. O Mail Eater envia a mensagem de destino para a API de texto. A API de texto processa o email, aplica o texto, comandos ou ambos que contém ao ticket adequado e gera um email de resposta automática indicando se a mensagem de email recebida foi aplicada com sucesso. Dependendo das ações realizadas, uma mensagem de email de notificação também é enviada separadamente para indicar certos eventos específicos, como a criação de um ticket.
Como configurar respostas de notificação para atualizar tickets
O daemon da API de texto (pdm_text_nxd) cria e atualiza tickets com informações de interfaces externas, como linha de comando e email. É possível configurar o correio para usar a API de texto de modo que os usuários (contatos) possam atualizar tickets respondendo notificações de email. O texto da resposta é adicionado como uma atividade de comentário de log para o ticket.
Para configurar respostas de notificação para atualizar tickets, faça o seguinte:
  1. Defina o método de notificação que o contato usa para pdm_mail - T
    reply_email_address
    ou pdm_mail - F
    reply_email_address.
    O
    reply_email_address
    especifica o endereço de chegada para a caixa de correio. Quando o contato clica em responder em um email, esse endereço é preenchido a partir do endereço De ou Responder a da mensagem à qual está respondendo.
    -T define o endereço Responder para. -F define o endereço De, usado como o endereço de resposta se um endereço separado não for especificado.
    Alguns programas de correio não honram ou não podem honrar um endereço Responder para.
  2. Criar ou atualizar uma regra da caixa de correio usando uma palavra-chave da API de texto.
    Os objetos definidos pelo usuário nos filtros de regra da caixa de correio substituem as seguintes palavras-chave da API de texto:
Objeto
Palavra-chave da API de texto
Identificador
Incidente
%INCIDENT_ID
Ref_num
Problema
%PROBLEM_ID
Ref_num
Solicitação
%REQUEST_ID
Ref_num
Chg_ref_num
%CHANGE_ID
Chg_ref_num
Ocorrência
%ISSUE_ID
Ref_num
  1. Criar ou atualizar uma frase de notificação que corresponde à regra.
  2. Criar ou atualizar um modelo de mensagem que use a frase notificação.
  3. Atualizar a regra da caixa de correio criada na Etapa 2 para especificar o modelo de mensagem que você criou ou atualizou na Etapa 4.
Após o usuário receber a notificação e respondê-la, as seguintes ações ocorrem:
  1. Quando a sequência de caracteres de filtro é encontrada a palavra-chave da ID de ticket relevante e o valor denotado pelo espaço reservado, se houver, são anexados à mensagem.
  2. Se um objeto da ID de ticket correspondente for encontrado, o ticket correspondente é atualizado com um comentário de log, uma nova descrição ou outros valores, de acordo com o texto, palavras-chave e comandos na mensagem.
  3. Se um objeto da ID de ticket correspondente não for encontrado, é criado um ticket com uma descrição e outros parâmetros de acordo com o texto, palavras-chave e comandos na mensagem.
Exemplo de como configurar uma resposta a uma notificação de incidente
Este exemplo mostra como configurar uma resposta a uma notificação de incidente
Para configurar uma resposta a uma notificação de incidente, faça o seguinte:
  1. Crie uma regra da caixa de correio usando os seguintes campos e valores:
    • Filtro - Corpo contém
    • Sequência de caracteres de filtro -- %Incident:{{object_id}}%
    • Ignorar maiúsculas ou minúsculas - SIM
    • Ação - Atualizar objeto
    • Objeto de ação - Incidente
  2. Criar uma frase de notificação que inclua a regra como segue:
    • Símbolo - Resposta a incidente
    • Código - IncidentReply
    • Ativo -- Ativo
    • Descrição - Comentário que integra a resposta para um Incidente/problema/solicitação.
    • Frase - Para adicionar um comentário a @{call_req_id.type.sym}, apenas responda este email ou inclua a linha abaixo (em uma linha própria):
      %Incident:{call_req_id.ref_num}%
      No texto de resposta automática da regra da caixa de correio, omita o prefixo call_req_id. prefix. Esse prefixo aplica um contexto no qual o texto da regra da caixa de correio já está, e tal mudança de contexto não é válida quando já estiver atuando nesse contexto.
  3. Criar ou atualizar um modelo de mensagem que use a frase notificação como segue:
    • Corpo da mensagem de notificação
      This is a simple notification. @{notification_phrase[IncidentURL1].phrase}
  4. Atualizar a regra da caixa de correio criada na Etapa 1 para especificar o modelo de mensagem criado na Etapa 3, como segue:
    Modelo de mensagem -
    nome da regra da caixa de correio
Como um usuário final atualiza um exemplo de ticket
O seguinte exemplo demonstra como um usuário final (John Smith) responde a uma notificação de email para atualizar um ticket de incidente.
O Corpo ou Assunto do email inclui o identificador de objeto. O local reservado {{object_id}} na sequência de caracteres do filtro denota o identificador de objeto.
  1. Uma notificação é enviada para John Smith e inclui as seguintes instruções:
    In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %Incident:1234%
  2. John Smith responde a notificação como segue:
    This is my response...
  3. O Mail Eater recebe a seguinte versão de texto do email de John Smith:
    This is my response... From: Service Desk Sent: Wednesday, September 18, 2009 10:22 AM To: Smith, John Subject: Simple Notification This is a simple notification. In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %Incident:1234%
  4. O Mail Eater processa regras em ordem e encontra o objeto %Incident:1234%:
    This is my response... From: Service Desk Sent: Wednesday, September 18, 2009 10:22 AM To: Smith, John Subject: Simple Notification This is a simple notification. In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself). %INCIDENT_ID=1234
  5. O Mail Eater adiciona as palavras-chave da API de texto e o valor {{object_id}} para a instrução %INCIDENT_ID= e deixa um marcador onde o valor {{object_id}} foi encontrado. O seguinte texto mostra os dados que são enviados para a API de texto. O texto em negrito mostra valores adicionados pelo Mail Eater.
    %LOG=This is my response...
    From: Service Desk
    Sent: Wednesday, September 18, 2009 10:22 AM
    To: Smith, John
    Subject: Simple Notification
    This is a simple notification.
    In order to add a comment to your incident, just reply to this email or include the line below (on a line by itself).
    %Incident:-((...))-%
    %INCIDENT_ID=1234
  6. A API de texto adiciona um comentário de log para o Incidente 1234.
Métodos de conversão de palavra-chave
Muitas das palavras-chave definida em text_api.cfg têm um método associado para converter o valor especificado a um valor que seja apropriado para armazenamento no banco de dados. Esse recurso permite que os usuários especifiquem valores do mesmo modo que fariam na interface da web, sem ter nenhum conhecimento da implementação subjacente.
O arquivo de configuração possui diversos exemplos desse tipo de definição de palavras-chave, incluindo ISSUE.PRIORITY e CONTACT.CONTACT_TYPE. Caso precise definir palavras-chave adicionais (por exemplo, para permitir que a API de texto acesse campos adicionados ao personalizar o esquema do banco de dados), é possível usar um dos seguintes métodos predefinidos:
Método
Tipo de saída
lookup_actbool
INTEIRO
lookup_asset_by_name
UUID
lookup_asset_by_persid
UUID
lookup_chg_category
SEQUÊNCIA
lookup_chg_status
SEQUÊNCIA
lookup_cnt_by_email
UUID
lookup_cnt_by_last_first_middle
UUID
lookup_cnt_by_logonid
UUID
lookup_cnt_by_persid
UUID
lookup_cnt_meth
INTEIRO
lookup_cnt_type
INTEIRO
lookup_company
UUID
lookup_cr_status
SEQUÊNCIA
lookup_cr_template
SEQUÊNCIA
lookup_domain
INTEIRO
lookup_grc
INTEIRO
lookup_group
UUID
lookup_impact
INTEIRO
lookup_iss_category
SEQUÊNCIA
lookup_iss_status
SEQUÊNCIA
lookup_loc
UUID
lookup_mfr_model
UUID
lookup_nr_family
INTEIRO
lookup_org
UUID
lookup_person_contacting
INTEIRO
lookup_position
INTEIRO
lookup_priority
INTEIRO
lookup_prob_category
SEQUÊNCIA
lookup_product
INTEIRO
lookup_resource_status
INTEIRO
lookup_service_lvl
SEQUÊNCIA
lookup_severity
INTEIRO
lookup_state
INTEIRO
lookup_timezone
SEQUÊNCIA
lookup_type_of_contact
INTEIRO
lookup_urgency
INTEIRO
lookup_workshift
SEQUÊNCIA
Se o valor que você necessita converter não puder utilizar um desses métodos predefinidos, será necessário escrever um método personalizado. O método deve tomar como entrada um valor de SEQÜÊNCIA e retornar um valor (NÚMERO INTEIRO, SEQÜÊNCIA ou UUID) como sua saída. Retorne um valor -1 (ou “-1”) para indicar que o valor não pode ser determinado e, portanto, não foi definido. No caso de UUID, retorne um “(uuid) NULL”.
Por exemplo, é possível desenvolver um método para converter uma ID de usuário em uma referência da tabela ca_contact. O valor de entrada, como Administrador, seria passado ao método, o qual retornaria a ID da tabela ca_contact para a ID de usuário do Administrador.
A maneira em que você define palavras-chave no arquivo de configuração oferece a vantagem de definir vários mapeamentos de palavra-chave ao mesmo campo, incluindo métodos diferentes de conversão, de acordo com o valor sendo especificado. Por exemplo, o destinatário pode ter vários mapeamentos diferentes de palavra-chave para definir como configurar seu valor com base em valores de entrada diferentes. Uma entrada pode ser uma ID de usuário, outra pode ser o sobrenome, nome, segundo nome, e outra ainda pode conter a ID real de ca_contact (por exemplo, 793ED69B4E87A545BD8E911834D829FC). Todas as palavras-chave apontam a métodos de conversão diferentes, exceto a última, que não necessita ser convertida.