API de envolvimento proativo

  • Versão de lançamento: Xanadu
  • Atualizado 1 de ago. de 2024
  • 5 min. de leitura

    • A API de envolvimento proativo fornece um endpoint para criar problemas de experiência digital.

    Esta API está disponível como uma REST API com script personalizado. Ele requer o plug-in Envolvimento proativo (proactive-engagement) e a função sn_pren.experience_issue_create. Esta API pertence ao namespace sn_pren.

    Use a API de envolvimento proativo para criar um problema de experiência quando um problema for detectado na instância de um usuário. O problema de experiência criado gera engajamento com o usuário e o ajuda a resolver o problema por conta própria.

    Para usar esta API, certifique-se de que as seguintes tabelas estejam preenchidas com registros:

    • Modelo de registro do problema [sn_pren_issue_registry_template]
    • Registro de problema [sn_pren_issue_registry]
    • Resolução [sn_pren_resolution]
    • Conteúdo da notificação [sn_pren_notification_content]
    • Provedor [sn_pren_provider]

    Para obter mais informações, consulte Proactive Engagement.

    Envolvimento proativo - CREATE /api/sn_pren/self_remediation/experience_issue/create

    Cria um problema de experiência quando um problema é detectado no endpoint do usuário. Atualiza a tabela Problemas de experiência [sn_pren_experience_issue].

    Formato da URL

    URL padrão: /api/sn_pren/self_remediation/experience_issue/create

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    Nenhum(a)
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    endpoint Obrigatório. Um objeto que contém o item de configuração (IC) e informações do usuário usadas para detectar detalhes do problema.
    Nota:
    Todos os parâmetros neste objeto são opcionais. Você deve passar pelo menos um parâmetro no objeto para identificar o usuário ou dispositivo."

    Tipo de dados: objeto

    "endpoint": {
    "CI": "String",
    "email": "String",
    "user_id": "String",
    "user_name": "String"
  }
    endpoint.IC Sys_id do dispositivo de IC no qual o problema foi detectado. Localizado na tabela Computador [cmdb_ci_computer].

    Tipo de dados: cadeia de caracteres
    endpoint.e-mail Endereço de e-mail do usuário para o qual o problema foi detectado.

    Tipo de dados: cadeia de caracteres
    endpoint.user_id Sys_id do usuário para o qual o problema foi detectado. Localizado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    endpoint.user_name Nome de usuário do usuário para o qual o problema foi detectado. Localizado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    experience_id Opcional. O ID definido pelo usuário a ser atribuído ao problema criado. Um ID será gerado automaticamente se este parâmetro não for especificado.

    Tipo de dados: número
    input_parameters Opcional. Parâmetros a serem passados para a ação que será executada no dispositivo. Os parâmetros de entrada enviados são passados para a ação corretiva de resolução configurada, como um subfluxo, ação de fluxo ou ação de IC.

    Tipo de dados: objeto

    "input_parameters": {
    "process_id": "String"
  }
    input_parameters.process_id Opcional. O sys_id do processo a ser encerrado ou reiniciado.

    Tipo de dados: cadeia de caracteres
    detalhes_investigativos Opcional. Detalhes que podem ser úteis para uma investigação manual se a resolução da Eficácia do uso de energia (PUE) falhar. Os detalhes da investigação são copiados para o incidente que é criado como fallback quando a resolução de PUE falha.

    Tipo de dados: objeto

    "investigative_details": {
    "cpu_usage": "String",
    "processes_running": "String",
    "available_memory": "String"
  }
    detalhes_investigativos.cpu_usage Quanto de uso da CPU é usado no dispositivo.

    Tipo de dados: número (analisado como uma cadeia de caracteres)
    detalhes_de_investigação.processos_em execução Quantos processos estão em execução no dispositivo.

    Tipo de dados: número (analisado como uma cadeia de caracteres)
    detalhes_investigativos.memória_disponível Memória disponível no dispositivo.

    Tipo de dados: número (analisado como uma cadeia de caracteres)
    problem_code Obrigatório. Código do problema a ser associado ao problema. O código do problema deve estar disponível e implantado na instância. Localizado na tabela Registro de problemas [sn_pren_issue_registry]. A API retornará um erro se um problema vazio ou inválido for fornecido.

    Tipo de dados: cadeia de caracteres
    provedor Obrigatório. O código exclusivo do provedor. Este código deve corresponder ao campo sn_pren_providerprovider_code na tabela [] na instância.

    Tipo de dados: cadeia de caracteres

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Código de status Descrição
    200 Um problema de experiência foi criado com sucesso.
    400 Solicitação inválida. Forneça detalhes do endpoint.

    Um objeto endpoint vazio foi enviado na solicitação.
    400 Código de problema inválido. Forneça um código de problema válido.

    Um issue_code vazio foi enviado na solicitação.
    400 Provedor inválido. Forneça um provedor válido.

    Um provedor vazio foi enviado na solicitação.
    400 Código de problema ou provedor inválido. Forneça detalhes válidos.

    Não foi possível detectar o problema na instância. Verifique os detalhes de issue_code e provider.
    400 O código do problema não tem uma resolução adequada.

    Uma resolução válida não está configurada na estrutura de PUE para o problema identificado.
    400 Não foi possível resolver o usuário a partir dos detalhes do endpoint. Forneça detalhes válidos.

    Este erro será retornado se o ID da estrutura de PUE não puder identificar o usuário a partir dos detalhes do endpoint fornecidos.
    400 Um problema de experiência está sendo resolvido com o código de problema fornecido para o usuário especificado.

    O problema de experiência especificado está em andamento ou em estado aberto.
    400 O problema de experiência existente com determinado experience_id ainda está em execução ou está encerrado.

    Este erro ocorre quando um problema de experiência está em um cenário de encadeamento. Por exemplo, se uma nova chave issue_code for enviada com uma experience_idexistente, e o problema de experiência anterior estiver em execução ou em estado fechado.

    O problema de experiência com este experience_id deve estar no estado action_wait para enviar um novo problem_code com o experience_id anterior.
    400 Ocorreu um erro ao criar o problema de experiência.

    Isso indica um erro técnico.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    experienceId O ID de experiência do problema de experiência criado. Gerado a partir do parâmetro de solicitação experience_id. O problema de experiência é criado na tabela Problemas de experiência [sn_pren_experience_issue].

    Se experience_id não for passado, o ID resultante será sempre o sys_id do registro criado.

    Solicitação de cURL

    O exemplo a seguir cria um problema de experiência para o usuário Abel Tuter. O código do problema no corpo permite que o envolvimento proativo identifique a resolução a partir do modelo de registro de problemas e interaja com o usuário final por meio do Virtual Agent para ajudá-lo a resolver o problema por conta própria.

    curl  "http://instance.servicenow.com//api/sn_srf/self_remediation/experience_issue/create" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data “{
  "endpoint": {
    "CI": "d049b28e936aa1106f98f6db5cba10d5",
    "user_id": "62826bf03710200044e0bfc8bcbe5df1",
    "user_name": "abel.tuter",
    "email": ""
  },
  "issue_code": "100",
  "provider": "sn",
  "experience_id": "09ed4830f393739df33",
  "input_parameters": {
    "process_id": "10644"
  },
  "investigative_details": {
    "cpu usage": "78%",
    "processes running": "35",
    "available memory": "23%"
  }
}”\

    O corpo da resposta retorna o ID da experiência, indicando que a criação do problema foi bem-sucedida.

    { 
  "result": { 
    "experience_id": “09ed4830f393739df33”
  } 
}