Help Desk e chamados

Um alerta por e-mail avisa uma pessoa. Um chamado entra na fila da equipe que resolve, com número, prazo e histórico. O CMS abre esse chamado sozinho quando um alerta dispara, na ferramenta de atendimento que a empresa já usa — e também deixa qualquer pessoa autorizada abrir um a partir de uma mensagem com erro, já preenchido com o contexto da integração.

O CMS só abre o chamado. Ele não comenta, não fecha e não lê o chamado de volta: o ciclo de vida pertence à ferramenta de atendimento. O número do chamado fica guardado no CMS, junto da mensagem que o abriu.

Como as peças se encaixam

São três cadastros, feitos nesta ordem:

1. A ferramenta — em Configurações › Parâmetros › Help Desk. Ativar cria tudo o que o envio precisa: a Aplicação da ferramenta, a Interface, a Entrega, o Transformador e a Credencial.
2. O destino — em Config. de Integração › Configuração ITSM. É o para quem dentro da ferramenta: o grupo de atendimento, a categoria, a urgência. Uma mesma ferramenta costuma ter vários destinos, um por área.
3. O alerta — em Alertas, o campo Abrir chamado em escolhe os destinos de cada configuração de alerta.

Por baixo, abrir um chamado é entregar uma mensagem: o CMS monta o corpo, coloca na Entrega da ferramenta e a mensagem segue o caminho de qualquer outra — tentativas, log, tela de Mensagens. Não existe um conector especial por ferramenta, e é por isso que a mensagem do chamado aparece em Mensagens como prova de que ele saiu.

Ferramentas suportadas

Cada ferramenta traz, no popup de ativação, os pré-requisitos do lado dela — a role itil no ServiceNow, a API ligada no GLPI, o API token no lugar da senha no Jira. Vale ler antes de preencher: a maior parte das falhas de primeira configuração está ali.

1. Ativar a ferramenta

Configurações › Parâmetros › aba Help Desk.

O botão Ativar abre o catálogo. Cada ferramenta aparece com uma descrição do que ela abre, e ao escolher uma o popup pede:

O bloco O que a ativação cria mostra, antes de confirmar, a Interface e a Entrega que vão existir. A escolha entre Canal e Fila vale a atenção:

• Canal (recomendado): um chamado recusado pela ferramenta não segura os seguintes. Chamados não têm ordem entre si, então é o comportamento certo na maioria dos casos.
• Fila: um chamado por vez, na ordem de chegada. Se um for recusado, os seguintes esperam até alguém destravar a Interface — justo no momento em que a ferramenta está com problema.

Os nomes criados são em inglês e derivam da sigla: a Interface GLPI_TICKET, a Entrega GLPI_TICKET_OPEN, o Transformador “GLPI GLPI - ticket body” e a Credencial “GLPI — CMS integration”. Nomes em inglês são o padrão para tudo o que a ativação grava; os textos das telas continuam no idioma de cada usuário.

A mesma ferramenta pode ser ativada mais de uma vez — um GLPI de produção e um de homologação, por exemplo. Cada ativação é uma Aplicação própria, com a sua sigla, e por isso os seus próprios nomes (GLPIQA_TICKET, GLPIQA_TICKET_OPEN). Se algum dos nomes já existir, a ativação recusa e diz qual: ela nunca reaproveita a Interface ou a Entrega de outra ativação.

A Interface e a Entrega vêm do pack da ferramenta, e só a ativação instala esse pack. Os packs de abertura de chamado não aparecem no assistente de packs das Aplicações: instalados numa Aplicação da fábrica, virariam uma Entrega de chamado solta, sem Destino e fora deste catálogo.

SAP PM

O SAP PM é diferente das outras ferramentas: ele não cria Aplicação. A ativação pede a Aplicação SAP onde as notas serão abertas — o combo só lista Aplicações do tipo SAP RFC/BAPI —, e essa escolha pode ser trocada depois, na edição. Também dá para ativar o SAP PM mais de uma vez, uma por Aplicação SAP.

No lugar de “O que a ativação cria”, a tela mostra a Entrega que abre a nota naquela Aplicação: a Entrega SAP RFC que chama BAPI_ALM_NOTIF_CREATE, encontrada pela função (a sigla pode ser qualquer uma). O pack SAP PM traz essa Entrega pronta. Para a nota existir de verdade, três coisas precisam estar nela:

1. BAPI_ALM_NOTIF_SAVE em “Chamar em seguida, na mesma sessão”. A BAPI de criar só guarda a nota na memória da sessão RFC; sem a gravação na mesma sessão, a nota some quando a conexão fecha. Ver chamadas seguintes.
2. Commit ligado — o BAPI_TRANSACTION_COMMIT, na mesma sessão.
3. O agendador da Interface ligado, em Agendadores. Desligado, a nota entra na fila e fica parada, e o “Abrir chamado” mostra “aguardando” para sempre.

A ativação e o Testar conexão conferem as três e dizem o que falta — a ativação recusa enquanto faltar alguma.

A grade

Nas ações da linha ficam Detalhes (Aplicação, Interface, Entrega e Credencial criadas), o Modelo de corpo — verde quando a ferramenta já tem um registrado — e a edição, onde mora o Testar conexão.

Desativar uma ferramenta só impede chamados novos. Destinos, Interface, Entrega e o histórico de chamados continuam intactos, e reativar devolve tudo como estava.

Testar conexão

O botão, na edição da ferramenta, faz uma leitura de verdade nela — sem abrir chamado — com a Credencial da Entrega. O resultado tem três estados:

• Verde: a ferramenta aceitou a credencial e a leitura.
• Vermelho: com o motivo. 401 é usuário ou senha recusados; 403 é credencial aceita sem a permissão que a abertura exige, e a tela diz qual (a role itil no ServiceNow, o acesso à API no perfil do GLPI).
• Aviso: a ferramenta não tem, no CMS, uma leitura que confirme a credencial (é o caso do InvGate). O teste passa com a nota “não conferida” — o primeiro chamado é que confirma.

No SAP PM o teste é outro: confere a Entrega de abrir nota, a gravação na mesma sessão, o commit e o agendador da Interface — ver SAP PM.

Modelo de corpo

Cada ferramenta tem um modelo de corpo: o JSON (ou XML) do chamado no formato que aquela API espera, com os campos do alerta no lugar dos valores. Ele é editado aqui, com o painel de campos ao lado do editor, e tem dois papéis:

• É o ponto de partida de todo destino novo desta ferramenta — menos no SAP PM, em que o corpo nasce dos campos da Definição de Entrega.
• É o corpo enviado por um destino que não tem corpo próprio.

O editor abre com um exemplo da ferramenta só como ponto de partida — Usar o modelo original da ferramenta o restaura. O exemplo nunca é enviado sozinho: sem modelo salvo e sem corpo no destino, o chamado não sai, e o histórico registra a falha.

2. Configurar o destino — /ticket-destinations

Config. de Integração › Configuração ITSM.

Um destino responde para onde, dentro da ferramenta, o chamado vai. O caso típico é o mesmo GLPI com um destino para a Manutenção Elétrica e outro para a TI — mudam o grupo, a categoria e a urgência.

A grade agrupa os destinos pela ferramenta: o cabeçalho de cada grupo traz o Help Desk, o selo de conexão (que abre os detalhes) e quantas configurações ele tem. Cada linha é uma configuração, em uma linha só:

A seta no começo da linha abre o detalhe: cada Aplicação com a conexão, os motivos dela, se usa o corpo padrão ou um corpo próprio e quando abriu o último chamado. É ali que se responde “o MES abre chamado por qual motivo?” — a coluna da linha junta os motivos de todas as Aplicações e não diz qual é de qual.

Os filtros de Aplicação, Interface, Definição e Motivo valem por Aplicação: “MES + Aplicação Offline” só mostra o destino se o próprio MES abrir chamado por Offline. Com um deles ativo, as linhas já abrem com o detalhe, e as Aplicações fora do filtro aparecem esmaecidas no fim — o destino continua servindo a elas, e quem vai mexer nele precisa ver isso. A busca por texto também acha o motivo pelo nome (“offline”).

Na coluna de ações ficam Chamados abertos, editar e excluir.

O formulário

Ferramenta, Nome e Entrega são obrigatórios, e o erro aparece no próprio campo. Salvar não fecha o formulário: a tela confirma que salvou e pergunta se você quer continuar editando ou fechar.

O corpo. Um destino novo abre com o modelo da aba Help Desk. Ao editar um destino, o editor mostra o corpo que foi salvo — o modelo só volta pelo botão Usar o modelo da aba Help Desk, que pede confirmação quando já há texto no editor. Nada é gravado até Salvar.

No SAP PM a base é outra. A nota não passa por Transformador: a Entrega recebe o JSON com os campos de entrada dela (descricao, equipamento, localInstalacao, prioridade…). Por isso o corpo abre com os campos da Definição de Entrega escolhida e acompanha a troca de Definição — uma Aplicação SAP tem várias Entregas, cada uma com os seus campos. Preencha os valores com os campos do alerta; o botão Usar os campos da Definição de Entrega os traz de volta. Um modelo registrado na aba Help Desk continua disponível pelo botão dele.

Corpo por Aplicação

O mesmo destino costuma servir várias Aplicações, e nem sempre o corpo é igual — o equipamento do SAP PM, o CI do ServiceNow. Acima do editor ficam as abas Padrão e uma por Aplicação: o corpo de uma Aplicação vale para os alertas dela, e as demais usam o Padrão. No combo de nova aba, as Aplicações que já usam o destino vêm primeiro.

Na aba de uma Aplicação, o painel ao lado mostra também as Variáveis daquela Aplicação, além dos campos do alerta. Apagar a aba volta a Aplicação para o Padrão.

Clicar num campo do painel ao lado escreve o {{campo}} onde está o cursor. O painel tem a mesma altura do editor e rola por dentro quando há muitas variáveis.

Três regras valem para o corpo:

• Escreva os campos dentro das aspas: "name": "{{alertaMensagem}}". O valor entra escapado para o formato da Entrega (JSON ou XML) — uma aspa ou quebra de linha na mensagem do alerta não quebra o chamado.
• JSON é conferido ao salvar, com os campos trocados por um valor neutro. Uma vírgula sobrando aparece agora, e não no primeiro chamado.
• Variáveis valem nos valores: {{SNOW_GRUPO}} de uma Variável Global, ou de uma Variável de Aplicação com o mesmo nome, resolvida contra a Aplicação que disparou o alerta. É assim que o mesmo destino leva o CI certo para cada Aplicação.

Um corpo mínimo para o GLPI:

{
  "input": {
    "name": "{{alertaMensagem}}",
    "content": "{{alertaDetalhe}}\n\nAplicação: {{aplicacao}} | Tipo: {{alertaTipo}}\nErro: {{alertaErro}}",
    "urgency": 4,
    "type": 1
  }
}

Os campos do corpo

O Transformador opcional

Sem Transformador, o corpo sai como está — é o caminho normal. O Transformador serve quando o chamado precisa de regra: urgência conforme o tipo de alerta, grupo conforme o texto do erro. Ele recebe o corpo já com os campos resolvidos e devolve o corpo final.

O combo lista os Transformadores Globais e os escopados nesta Entrega. O da própria Entrega (instalado pelo pack da ferramenta) vem primeiro, e espera outro formato: os campos do contrato (titulo, descricao, urgencia…), não o JSON da ferramenta. Ao escolhê-lo, a tela diz quais campos ele espera e oferece Usar o formato de entrada deste Transformador, que reescreve o corpo nesse formato — com confirmação, como o botão do modelo. Transformadores de outras ferramentas de chamado não aparecem.

Chamados abertos

O ícone de histórico abre os últimos 50 chamados do destino, em grade paginada, com busca pelo número do chamado. Cada linha traz data, número, origem (o alerta, ou “Abertura manual por” quem abriu) e a situação:

O ícone de mensagem abre o resumo da mensagem, o mesmo popup de Mensagens, com o corpo enviado e a resposta da ferramenta.

3. Ligar o destino ao alerta

Na configuração de alerta, em Alertas, o campo Abrir chamado em lista os destinos, cada um com o ícone, a sigla e a descrição da ferramenta — para ficar claro em qual sistema o chamado vai abrir. Um alerta pode abrir chamado em mais de um destino ao mesmo tempo (um chamado na TI e uma nota no SAP PM, por exemplo).

Para Aplicação Offline aparece também Só abrir chamado após (minutos), com 5 de padrão: o e-mail sai na hora, e o chamado só se a Aplicação continuar fora depois desse tempo. Uma oscilação de rede de segundos não vira chamado na fila do suporte. Zero abre junto com o alerta.

As regras do disparo

• Um chamado por vez. Aberto um chamado para um par (configuração de alerta, destino), o mesmo problema não abre outro. A trava se solta quando o alerta de recuperação chega — Aplicação Online ou Interface Desbloqueada —, e um problema novo depois disso abre chamado novo.
• Condição Atendida é por ocorrência. O alerta de condição já dispara uma vez só por passagem — e, separado por chave, uma vez por equipamento. Por isso ele não usa a trava acima: com ela, a nota do forno 2 esperaria a do forno 1 ser normalizada.
• Recuperação não abre chamado. O alerta de volta só solta a trava; quem fecha o chamado é a equipe, na ferramenta.
• A ferramenta não chama socorro a si mesma. Se o alerta é sobre a própria ferramenta (o ServiceNow caiu), abrir chamado nela não faria sentido: o disparo é registrado como Ignorado, e o aviso sai por e-mail mesmo que a configuração não tenha e-mail marcado.
• Um destino não segura os outros. Se um destino falha, os demais do mesmo alerta abrem normalmente.

Abrir um chamado na hora

Nem todo problema começa num alerta. Quem vê algo errado pode abrir o chamado direto.

A partir da mensagem com erro

Numa mensagem com Erro de Entrega, Erro de Negócio ou Erro de Coleta, o botão Abrir chamado aparece ao lado de PDF, Enviar por e-mail e Reenviar — no popup da mensagem em Mensagens e na tela de detalhe. Ele só aparece para quem tem a Ferramenta Abrir Chamado no perfil e quando existe ao menos um destino ativo. Uma mensagem que é ela mesma um chamado não oferece o botão.

É ali que a abertura manual faz sentido: um formulário em branco qualquer um preenche direto na ferramenta de atendimento; o que o CMS acrescenta é o contexto da integração. Por isso o popup já vem preenchido — e tudo continua editável:

Os campos do destino levam em conta o corpo por Aplicação: trocar a Aplicação troca os campos. O operador só preenche o que o destino deixou em aberto — um valor fixado no corpo não é sobrescrito, e o popup não cria chave nova. É o jeito de abrir uma nota de PM com o equipamento que só quem está na área sabe.

Só aparecem no popup os destinos com Disponível na abertura manual ligado.

Abrir chamado mostra uma confirmação com o resumo antes de enviar. Depois do envio, o popup acompanha a resposta da ferramenta e mostra o número do chamado assim que ele chega — ou o motivo, se a ferramenta recusar. Dali dá para abrir outro ou, com acesso à Configuração ITSM, ver os chamados abertos.

A abertura manual fica fora da trava de um chamado por vez: quem clica quer um chamado agora, e o automático continua podendo abrir o dele depois.

Onde a ferramenta aparece no resto do sistema

A ferramenta ativada é uma Aplicação da categoria Help Desk. Ela aparece onde ajuda a acompanhar o envio, e fica fora de onde só atrapalharia:

Permissões

São três Ferramentas, separadas de propósito — quem abre chamado não precisa poder criar destino, e quem cria destino não precisa poder ativar ferramenta:

A lista de destinos do popup Abrir chamado não depende de o usuário ter a Interface da ferramenta no perfil — um operador não precisa dela. O que se protege ali é a Aplicação citada no chamado: só aparecem as Aplicações que o usuário pode ver.

Problemas comuns