API da Central de automação

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 12 min. de leitura

    • . Central de automação A API fornece endpoints para criar e atualizar dados relacionados a robôs, processos e trabalhos de execução. Ao aproveitar esta API, você pode integrar e refletir detalhes de seus fluxos de trabalho de automação no Central de automaçãopainel.

    Principais conceitos da API:
    • Robôs: Agentes de software que executam processos de bot. Os robôs de RPA podem operar nos modos assistido ou autônomo.
    • Processos: Instâncias de fluxos de trabalho de RPA executadas em um robô específico. Para identificar exclusivamente um processo, o ID do processo e o ID do robô devem ser especificados.
    • Execuções: Tarefas individuais realizadas em um processo, como transferir informações de um recurso para outro (como copiar dados de e-mails para uma planilha).

    Como usar a API:

    Você pode usar a API para enviar dados de ferramentas de RPA de terceiros, incluindo robôs, processos e execuções, para Central de automação.

    Fluxo de trabalho recomendado:
    1. Envie os dados do robô.
    2. Envie os dados do processo vinculados ao robô enviado.
    3. Envie dados de execução que fazem referência ao robô e ao processo correspondentes.
      Nota:
      Dados de execução sem o robô e o processo associados já capturados em Central de automaçãonão aparecerá no painel.
    Informações adicionais:
    • Retenção de eventos: Os eventos criados usando esta API são removidos automaticamente da sua instância após 14 dias (configuração padrão).
    • Limites de registro: Cada chamada de API pode processar no máximo 2 000 registros. Este limite não pode ser alterado.
    • Exclusão de evento: Esta API não oferece suporte à exclusão de eventos.

    Esta API requer Central de automaçãoo plug-in deve estar ativo e requer que o usuário tenha a função sn_as.automation_technical_user ou sn_ac.automation_admin.

    Central de automação - POST /sn_ac/automation/rpa

    Cria eventos de robô, processo e execução.

    Esses eventos fornecem automação de processos. Eles aparecem nos painéis Visão geral e Central de automação de execução para medir e monitorar a saída de vários fornecedores de RPA.

    Formato de URL

    URL com controle de versão: /api/sn_ac/

    URL padrão: /api/sn_ac/v1/automation/rpa

    Nota:
    As versões disponíveis são especificadas em REST API Explorer . Para APIs REST com script, há informações adicionais de versão no Serviço REST com script .

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint para acessar. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: Cadeia de caracteres
    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
    Nome do departamento Somente tipos de evento de processo e robô. Nome do departamento ao qual o evento pertence.
    Este valor é armazenado nas tabelas a seguir, dependendo do tipo de evento:
    • Campo departamento na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • Campo departamento na tabela Robô de base [cmdb_ci_base_rpa_robot].

    Tipo de dados: Cadeia de caracteres
    domainId Sys_id do domínio ao qual o evento pertence.
    Este valor é armazenado nas tabelas a seguir, dependendo do tipo de evento:
    • Execução: Campo sys_domain na tabela Execução de automação [sn_ac_automation_execution].
    • Campo sys_domain na tabela Processo de bot base [cmdb_ci_base_rpa_process].
    • Campo sys_domain na tabela Robô de base [cmdb_ci_base_rpa_robot].

    Tipo de dados: Cadeia de caracteres
    endtime Somente tipo de evento de execução. Hora de término da execução. Este valor é armazenado no campo end_time na tabela Execução de automação [sn_ac_automation_execution].

    FORMATO: AAAA-MM-DD HH:MM:SS

    Tipo de dados: Cadeia de caracteres
    ambiente Somente tipo de evento de execução. Ambiente da execução, como uma URL. Este valor é armazenado no campo Ambiente na tabela Execução de automação [sn_ac_automation_execution].
    Nota:
    Este valor não é usado pelo ServiceNowe podem conter qualquer valor exigido pela sua implementação.

    Tipo de dados: Cadeia de caracteres
    errorMessage Somente tipo de evento de execução. Nome do log de mensagens de erro. Este valor é armazenado no campo de mensagem na tabela Execução de automação [sn_ac_automation_execution].

    Tipo de dados: Cadeia de caracteres
    eventName Necessário. Nome do tipo de evento. Este valor determina o tipo de evento a ser processado.
    Valores válidos (diferencia maiúsculas de minúsculas):
    • execução
    • processo
    • robô

    Tipo de dados: Cadeia de caracteres
    id Necessário. Identificador numérico exclusivo do evento associado.
    Este valor é armazenado nas tabelas a seguir, dependendo do tipo de evento:
    • Execução: Campo Automation_execution_id na tabela Execução de automação [sn_ac_automation_execution].
    • Processo: Campo correlation_id na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • Campo correlation_id na tabela Robô de base [cmdb_ci_base_rpa_robot].

    Tipo de dados: Número (inteiro)
    nome Somente tipos de evento de processo e robô. Necessário. Nome do evento.
    Este valor é armazenado nas tabelas a seguir, dependendo do tipo de evento:
    • Processo: Campo Nome na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • Campo Nome na tabela Robô de base [cmdb_ci_base_rpa_robot].

    Tipo de dados: Cadeia de caracteres
    prioridade Somente tipo de evento de execução. Prioridade da execução.
    Valores válidos (diferencia maiúsculas de minúsculas):
    • Crítico
    • Alto
    • Médio 
    • Baixo(a)
    Este valor é armazenado no campo Prioridade na tabela Execução de automação [sn_ac_automation_execution].

    Tipo de dados: Cadeia de caracteres

    Padrão: Nenhum - Não exibido no painel.
    processId Somente tipo de evento de execução. Necessário. Identificador exclusivo do processo no qual executar a execução. Este valor está localizado no campo correlation_id do registro de processo correspondente na tabela Processo de bot base [cmdb_ci_base_rpa_process].

    Este valor é armazenado no campo de automação na tabela Execução de automação [sn_ac_automation_execution].

    Tipo de dados: Cadeia de caracteres
    RobotId Somente tipo de evento de execução. Necessário. Identificador exclusivo do robô no qual executar a execução. Este valor está localizado no campo correlation_id do registro do robô correspondente na tabela Robô base [cmdb_ci_base_rpa_robot].

    Este valor é armazenado no campo robô na tabela Execução de automação [sn_ac_automation_execution].

    Tipo de dados: Cadeia de caracteres
    origem Necessário. Origem à qual o evento pertence, como "serviceNow_rpa". Este valor está localizado no campo internal_name da tabela Fonte de automação [sn_ac_automation_source].
    Este valor é armazenado nas tabelas a seguir, dependendo do tipo de evento:
    • Execução: Campo de origem na tabela Execução de automação [sn_ac_automation_execution].
    • Processo: Campo de origem na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • Campo de origem na tabela Robô de base [cmdb_ci_base_rpa_robot].

    Tipo de dados: Cadeia de caracteres
    starttime Somente tipo de evento de execução. Hora de início da execução. Este valor é armazenado no campo start_time na tabela Execução de automação [sn_ac_automation_execution].

    Tipo de dados: Cadeia de caracteres

    FORMATO: AAAA-MM-DD HH:MM:SS
    estado Somente tipos de evento de execução e robô. Estado do evento associado.
    Valores válidos para robô (diferencia maiúsculas de minúsculas):
    • Cancelados(as)
    • Concluído
    • Erro
    • Em fila
    • Em execução
    Padrão: Enfileirado
    Valores possíveis para execução (diferencia maiúsculas de minúsculas):
    • Disponível
    • Ocupado
    • Desconectado
    • Novo
    • Responsivo(a)
    Padrão: Novo
    Este valor é armazenado nas tabelas a seguir, dependendo do tipo de evento:
    • Execução: Campo estado na tabela Execução de automação [sn_ac_automation_execution].
    • Robô: Campo robot_state na tabela Robô de base [cmdb_ci_base_rpa_robot].

    Tipo de dados: Cadeia de caracteres
    status Processar somente tipo de evento. Necessário. Status do processo.
    Valores possíveis (diferencia maiúsculas de minúsculas):
    • Construir
    • Em manutenção
    • Em uso
    • Desativado
    Este valor é armazenado no campo life_cycle_stage_status na tabela Processo de bot base [cmdb_ci_base_rpa_process].

    Tipo de dados: Cadeia de caracteres
    TriggeredBy Somente tipo de evento de execução. Origem do gatilho da execução. Este valor é armazenado no campo trigger_by na tabela Execução de automação [sn_ac_automation_execution].
    Nota:
    Este valor não é usado pelo ServiceNowe podem conter qualquer valor exigido pela sua implementação.

    Tipo de dados: Cadeia de caracteres
    tipo Somente tipos de evento de processo e robô. Necessário para processo, opcional para robô. Tipo de processamento a ser executado.
    Valores válidos (diferencia maiúsculas de minúsculas):
    • Acompanhado
    • Desacompanhado
    Este valor é armazenado nas tabelas a seguir, dependendo do tipo de evento:
    • Processo: Campo process_type na tabela Processo de bot base [cmdb_ci_base_rpa_process].
    • Robô: Campo robot_type na tabela Robô de base [cmdb_ci_base_rpa_robot].

    Tipo de dados: Cadeia de caracteres

    Padrão: Autônomo para robô
    versão Somente tipo de evento de robô. Versão do robô.

    Este valor é armazenado no campo de versão na tabela Robô de base [cmdb_ci_base_rpa_robot].

    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 da 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/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

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

    Tabela 6. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Falha. A solicitação foi rejeitada devido a campos obrigatórios ausentes ou a solicitação contém valores inválidos. A mensagem de erro associada descreve o motivo da falha.

    Parâmetros do corpo da resposta

    Nome Descrição
    resultado Se a solicitação for bem-sucedida. Para falha, informações adicionais são fornecidas.

    Tipo de dados: Objeto

    "result": {
  "fields": {
    "<record_number>": [Array]
  }
  "reason": "String"
}
    Por exemplo, se os registros 1, 2 e 3 não tiverem um campo obrigatório, uma mensagem semelhante à seguinte será retornada:
    {
  "result": {
    "fields": {
      "1": [
        "id"
      ],
      "2": [
        "status"
      ],
      "3": [
        "name"
      ]
    },
    "reason": "We are not able to process the data as following records have insufficient data"
  }
}

    Solicitação de curl

    O exemplo de código a seguir mostra como publicar três registros de tipo de evento de robô.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 8001,
    name: "Quotes system Automation Robot",
    state: "Available",
    status: "In Use",
    version: 5.6,
    departmentName: "Customer Support",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8002,
    name: "Invoice Matching Robot",
    state: "Responsive",
    status: "In Maintenance",
    version: 3,
    departmentName: "HR",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  },
  {
    id: 8003,
    name: "Data Reconciliation Robot",
    state: "Busy",
    status: "Retired",
    version: 2,
    departmentName: "Finance",
    type: "Unattended",
    source: "servicenow_rpa",
    eventName: "robot"
  }]
} "\
--user "username":"password"

    Este endpoint retorna apenas um código de status HTTP em caso de sucesso e um código de status HTTP e uma mensagem de erro em caso de falha.

    None

    Solicitação de curl

    O exemplo de código a seguir mostra como publicar três registros de tipo de evento de processo.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 9001,
    name: "RPA Execution Process",
    status: "In Maintenance",
    type: "Attended",
    departmentName: "Customer Support",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9002,
    name: "Customer Onboarding",
    status: "In Use",
    type: "Attended",
    departmentName: "Finance",
    source: "servicenow_rpa",
    eventName: "process"
  },
  {
    id: 9003,
    name: "Data Reconciliation",
    status: "Retired",
    type: "Unattended",
    departmentName: "HR",
    source: "servicenow_rpa",
    eventName: "process"
  }]
}" \
--user "username":"password"

    Este endpoint retorna apenas um código de status HTTP em caso de sucesso e um código de status HTTP e uma mensagem de erro em caso de falha.

    None

    Solicitação de curl

    O exemplo de código a seguir mostra como publicar três registros de tipo de evento de execução.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  records: [{
    id: 7001,
    name: "Customer Onboarding",
    starttime: "2022-03-18 00:49:13",
    endtime: "2022-03-20 00:58:03",
    state: "Running",
    priority: "Critical",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9001,
    robotId: 8001,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7002,
    name: "Data Reconciliation",
    starttime: "2022-04-30 00:19:11",
    endtime: "2022-05-02 00:41:35",
    state: "Error",
    priority: "Low",
    environment: "system",
    triggeredBy: "API",
    processId: 9002,
    robotId: 8002,
    source: "servicenow_rpa",
    eventName: "execution"
  },
  {
    id: 7003,
    name: "Customer Onboarding",
    starttime: "2022-01-22 02:38:53",
    endtime: "2022-01-23 02:50:44",
    state: "Queued",
    priority: "Moderate",
    environment: "system",
    triggeredBy: "Schedule",
    processId: 9003,
    robotId: 8003,
    source: "servicenow_rpa",
    eventName: "execution"
  }]
} "\
--user "username":"password"

    Este endpoint retorna apenas um código de status HTTP em caso de sucesso e um código de status HTTP e uma mensagem de erro em caso de falha.

    None

    Solicitação de curl

    O exemplo de código a seguir mostra como criar ou atualizar um processo. Você cria um processo passando todos os parâmetros obrigatórios para que um processo seja executado junto com o. eventNamedefinido como "processo". Os parâmetros obrigatórios necessários para criar um processo são: id, type, status, namee. source.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9001,
name: "RPA Execution Process",
status: "In Maintenance",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

    Este endpoint retorna apenas um código de status HTTP em caso de sucesso e um código de status HTTP e uma mensagem de erro em caso de falha.

    None

    Solicitação de curl

    O exemplo de código a seguir mostra como publicar um processo. Você pode publicar um processo passando por statusParâmetro definido como "Publicado".

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 9002,
name: "RPA Execution Process",
status: "Published",
type: "Attended",
departmentName: "Customer Support",
source: "servicenow_rpa",
eventName: "process"
}]
} "\
--user "username":"password"

    Este endpoint retorna apenas um código de status HTTP em caso de sucesso e um código de status HTTP e uma mensagem de erro em caso de falha.

    None

    Solicitação de curl

    O exemplo de código a seguir mostra como criar ou atualizar um robô. Você cria um robô passando todos os parâmetros obrigatórios de um robô junto com o. eventNamedefinido como "robô". Os parâmetros obrigatórios necessários para criar um robô são: id, status, namee. source.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 8001,
name: "Quotes system Automation Robot",
state: "Available",
status: "In Use",
version: 5.6,
departmentName: "Customer Support",
type: "Unattended",
source: "servicenow_rpa",
eventName: "robot"
} "\
--user "username":"password"

    Este endpoint retorna apenas um código de status HTTP em caso de sucesso e um código de status HTTP e uma mensagem de erro em caso de falha.

    None

    Solicitação de curl

    O exemplo de código a seguir mostra como criar ou atualizar uma execução. Você cria uma execução passando todos os parâmetros obrigatórios de uma execução junto com o. eventNamedefinido como "execução". Os parâmetros obrigatórios necessários para criar uma execução são: id, processId, robotIde. source.

    curl "https://instance.servicenow.com/api/sn_ac/automation/rpa" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
records: [{
id: 7001,
name: "Customer Onboarding",
starttime: "2022-03-18 00:49:13",
endtime: "2022-03-20 00:58:03",
state: "Running",
priority: "Critical",
environment: "http://acqa.servicenow.com",
triggeredBy: "Schedule",
processId: 9001,
robotId: 8001,
source: "servicenow_rpa",
eventName: "execution",
errorMessage:"Error due to Inactivity"
}]
} "\
--user "username":"password"

    Este endpoint retorna apenas um código de status HTTP em caso de sucesso e um código de status HTTP e uma mensagem de erro em caso de falha.

    None