Integre o Catalyst SD-WAN ao ServiceNow

Introdução

Este documento descreve o processo passo a passo para integrar o Catalyst SD-WAN ao ServiceNow para geração de tíquetes com base em eventos.

Pré-requisitos

Requisitos

A Cisco recomenda:

• Conhecimento da solução Cisco Catalyst SD-WAN.
• Uma conta ativa no ServiceNow com privilégios de administrador.
• O alcance da Internet a partir do gerenciador de SD-WAN transporta a Rede Virtual Privada (VPN).
  • Se o ServiceNow estiver hospedado no local, assegure a conectividade com ele a partir do SD-WAN Manager na VPN 0.

Componentes Utilizados

As informações neste documento são baseadas nestas versões de software e hardware:

• Cisco Catalyst SD-WAN Manager executando a versão 20.15.3.1.
• C8000v executando o Cisco IOS® XE Catalyst SD-WAN versão 17.15.3.

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Diagrama de Rede

Diagrama de conectividade      

Configurações

Tip: Para essa integração, usamos Webhooks do SD-WAN Manager diretamente para o ServiceNow.

Há duas partes nesta configuração:

1. Configurando a API do ServiceNow e deixando-a pronta para aceitar e processar mensagens HTTP POST do Gerenciador SD-WAN. 
2. Configurando o Webhook do Gerenciador de SD-WAN.

Configuração do ServiceNow

Criar uma instância

1. Faça login no portal do ServiceNow para desenvolvedores https://developer.servicenow.com/dev.do usando suas credenciais do ServiceNow.
2. Na página Bem-vindo, clique em "Solicitar sua instância" e escolha qualquer versão (Zurique, Yokohama ou Xanadu). 

Figura -1

Figura -2

3. Aguarde alguns minutos enquanto sua instância fica pronta.

4. Atualize sua página após alguns minutos e crie sua PDI (Personal Developer Instance). 

Figura -3

Criar um Aplicativo

5. Clique em App Engine Studio.

6. Feche a caixa de diálogo de boas-vindas.

7. Clique em Criar aplicativo.

Figura -4

8. Dê um nome a este aplicativo e clique em Continuar.

Figura -5

9. Deixe as funções como padrão e clique em Continuar. 

Figura -6

10. Aguarde alguns minutos para que este aplicativo seja criado.

11. Vá para o painel do aplicativo.

Criar APP

12. Em App Home, clique em "Experimente" para abrir o ServiceNow Studio. 

Figura -7

13. Observe o URL. É algo como PDI-ID.service-now.com.

14. No painel de navegação esquerdo, clique no nome do aplicativo. Nesse caso: ud-vmanage 

Figura -8

15. Clique no ícone (+) e em Criar Arquivo.

Criar arquivo

16. Pesquise e selecione API REST com script. 

Figura -9

17. Clique em Continuar.

18. Crie um novo registro para o Serviço REST com Script. 

1. Inserir nome da API
2. ID da API
3. Clique no ícone de cadeado ACLs padrão:
   1. Clique no botão de pesquisa para selecionar o registro de destino.
   2. Na Pesquisa de controle de acesso, pesquise e clique em "Padrão externo REST com script".

Figura -10

Figura -11

19. Clique em Submeter.

Novo Registro de Serviço REST com Script

20. Crie um novo recurso. 

Figura -12

21. Dê o nome desse novo recurso, selecione o método HTTP como POST. 

Figura -13

22. Na seção de script, crie um javascript para processar o JSON do Gerenciador SD-WAN e crie tickets no ServiceNow.

Exemplo de script:

 (function process(request, response) {
    try {
        var payload = request.body.data;

        gs.info("🚨 vManage Webhook Received: " + JSON.stringify(payload));

        var alertMessage = payload.message || 'No message';
        var alertSeverity = payload.severity || 'medium';
        var deviceId = payload.deviceId || 'Unknown device';

        var inc = new GlideRecord('incident');
        inc.initialize();
        inc.short_description = "vManage Alert: " + alertMessage;
        inc.description = "Device ID: " + deviceId + "\nSeverity: " + alertSeverity + "\n\n" + JSON.stringify(payload);
        inc.urgency = (alertSeverity === 'critical') ? 1 : 2;
        inc.impact = 2;
        inc.insert();

        response.setStatus(201);
        response.setBody({ message: "Webhook received and processed." });

    } catch (err) {
        gs.error("❌ vManage Webhook Error: " + err.message);
        response.setStatus(500);
        response.setBody({ error: "Error processing webhook: " + err.message });
    }
})(request, response);

aviso: Este é um script de exemplo. Valide completamente o script antes de usá-lo no laboratório ou no ambiente de produção.

23. Clique em Enviar.

Novo Registro de Recurso REST com Script

24. Anote o caminho do recurso. Este é o URL que precisamos inserir na configuração Webhook do Gerenciador de SD-WAN.

25. URL do Webhook: https://PDI.service-now.com/Resource_path.

URL de exemplo neste guia de configuração:  https://dev271953.service-now.com/api/x_1831932_ud_vma_0/ud_vm_snow

Configuração do gerenciador SD-WAN

Nesta seção, configuramos o Webhook do Gerenciador de SD-WAN para enviar os alarmes para a API ServiceNow: https://dev271953.service-now.com/api/x_1831932_ud_vma_0/ud_vm_snow

Tip: Para um Gerenciador SD-WAN de vários usuários, aplique a respectiva configuração na exibição de locatário para enviar eventos Webhook para esse locatário. Também é possível aplicar essa configuração na visualização Provedor para receber alarmes de dispositivos de domínio do Provedor.

Webhook SD-WAN

1. Faça login no SD-WAN Manager e navegue para Monitor > Logs > Alarm Notifications.

Figura -14

Notificação de alarme SD-WAN

2. Clique em Adicionar Notificações de Alarme. 

Figura -15

3. Informe os respectivos campos para configurar a notificação de alarme. 

1. Nome da notificação
2. Tipo de alarme
3. Método de entrega: WebHook

1. Escolha um canal para webhook: Personalizado
2. URL do WebHook (API criada na etapa 24 da configuração do ServiceNow):  https://dev271953.service-now.com/api/x_1831932_ud_vma_0/ud_vm_snow
3. Limite do WebHook: 100
4. Deixe o nome de usuário e a senha em branco.

Caution: Deixar os campos de nome de usuário e senha em branco na produção é um risco à segurança. Mova-se com cuidado.

4. Clique em Adicionar Notificação.

Figura -16

Verificar

página de tíquetes do ServiceNow

1. Vamos navegar até a página de tíquetes do ServiceNow.
   1. Para isso, use esta URL para acessar o espaço de trabalho principal do ServiceNow. É o seu PDI.service-now.com/nav_to.do.
      1. Exemplo: https://dev271953.service-now.com/nav_to.do

espaço de trabalho do ServiceNow

2. Clique em Todos e pesquise e clique em Incidentes. 

Figura -17

3. A página Incidente é aberta.

página Incidente

4. No vshell da CLI do Gerenciador de SD-WAN, execute o comando CURL em direção ao ServiceNow: 

     curl -X POST "<your_webhook_url_towards_servicenow>"

Mensagem de êxito:

udutt-krk-dmz-vmanage:~$ curl -X POST "https://dev271953.service-now.com/api/x_1831932_ud_vma_0/ud_vm_snow"
{"result":{"message":"Webhook received and processed."}}

5. Observe um incidente criado no ServiceNow.

Figura -18

Se você notar um erro de autenticação na CURL, como abaixo:

udutt-krk-dmz-vmanage:~$ curl -X POST "https://dev271953.service-now.com/api/x_1831932_ud_vma_0/ud_vm_snow"
{"error":{"message":"User is not authenticated","detail":"Required to provide Auth information"},"status":"failure"}

Etapas para corrigir o erro de autenticação

1. Volte para a página do ServiceNow Studio e acesse seu aplicativo (exemplo: ud-vmanage) no painel de navegação esquerdo e selecione sua API REST com script (exemplo, ud-vm-snow). 

Figura -19

2. Role para baixo até Recursos e clique no recurso (exemplo: alarmes). 

Figura -20

3. Role para baixo até Security e desmarque a autenticação e a autorização da ACL como mostrado abaixo. 

a. Requer autenticação

b. Requer autorização da ACL

c. Clique em Update

Figura -21

4. Execute o comando CURL novamente a partir do vshell do Gerenciador de SD-WAN, que é bem-sucedido desta vez.

Gerando alarmes

5. Agora, gere um alarme no SD-WAN Manager, por exemplo:

a. Desligando uma interface de um Roteador de Borda WAN dentro da sua sobreposição SD-WAN.

b. Limpando as conexões de controle de qualquer gerenciador SD-WAN ou de qualquer roteador de borda WAN.

c. Execução de um salto de porta.

Verifique o site desejado para gerar alarmes durante a configuração do Webhook.

6. Observe os incidentes criados na página ServiceNow. 

Figura -22

Figura -23

Figura -24

Troubleshooting

1. No lado do SD-WAN Manager, verifique o conteúdo de /var/log/nms/vmanage-server.log quanto a erros relacionados às mensagens HTTP POST.

Exemplo de Webhook bem-sucedido:

03-Oct-2025 12:21:05,394 UTC INFO  [] [udutt-krk-vmanage] [DataCollectionManager] (Thread-157) || ******* Requested device 10.1.1.3, Adding to dataCollectionQueue, Sync type DATA_SYNC.
03-Oct-2025 12:21:05,677 UTC INFO  [] [udutt-krk-vmanage] [EventDataCollector] (device-event-processing-2) || Configuration change event from device. Device IP: [10.1.1.3] Device type: [vsmart] User: [admin]
03-Oct-2025 12:21:05,677 UTC INFO  [] [udutt-krk-vmanage] [DataCollectionManager] (Thread-157) || ******* Requested device 10.1.1.3, Adding to dataCollectionQueue, Sync type DATA_SYNC.
03-Oct-2025 12:21:06,745 UTC INFO  [] [udutt-krk-vmanage] [DeviceHistoryConfigurationDAO] (device-config-0) || saveConfigToElasticDataStore entryTime 1761567666745  personality vsmart
03-Oct-2025 12:21:07,192 UTC INFO  [] [udutt-krk-vmanage] [NotificationsConsumer] (pool-59-thread-9) || Response status code after sending webhook: 201
03-Oct-2025 12:21:07,196 UTC INFO  [] [udutt-krk-vmanage] [NotificationsConsumer] (pool-59-thread-1) || Response status code after sending webhook: 201

Exemplo de solicitação de Webhook malsucedida:

03-Oct-2025 12:24:46,949 UTC INFO  [] [udutt-krk-vmanage] [DataCollectionManager] (Thread-157) || ******* Requested device 10.1.1.3, Adding to dataCollectionQueue, Sync type DATA_SYNC.
03-Oct-2025 12:24:48,065 UTC INFO  [] [udutt-krk-vmanage] [DeviceHistoryConfigurationDAO] (device-config-0) || saveConfigToElasticDataStore entryTime 1761567888065  personality vsmart
03-Oct-2025 12:24:48,305 UTC INFO  [] [udutt-krk-vmanage] [NotificationsConsumer] (pool-59-thread-15) || Response status code after sending webhook: 401
03-Oct-2025 12:24:48,305 UTC INFO  [] [udutt-krk-vmanage] [NotificationsConsumer] (pool-59-thread-14) || Response status code after sending webhook: 401

2. Também podemos executar a captura de pacotes para confirmar a integridade da sessão entre o SD-WAN Manager e o ServiceNow.

Captura de pacotes com IP público oculto

Informações Relacionadas

• Solução de problemas do Webhook do Gerenciador de SD-WAN
• Suporte Técnico e Documentação - Cisco Systems