API da Central de automação

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

    • A API Automation Center 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 painel Central de automação.

    Conceitos-chave 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 (por exemplo, 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:
      Os dados de execução sem o robô e o processo associados já capturados em Central de automação não serão exibidos 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 lidar com no máximo 2.000 registros. Este limite não pode ser alterado.
    • Exclusão de eventos: esta API não é compatível com a exclusão de eventos.

    Esta API requer que o plug-in Central de automação esteja 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 da Central de automação de visão geral e execução para medir e monitorar a saída de vários fornecedores de RPA.

    Formato da URL

    URL com controle de versão: /api/sn_ac/{api_version}/automation/rpa

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

    Nota:
    As versões disponíveis são especificadas no Explorador de REST API. Para REST APIs com script, há informações adicionais sobre a versão no formulário 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 a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor 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
    departamentoNome Somente tipos de evento de processo e robô. Nome do departamento ao qual o evento pertence.
    Este valor é armazenado nas seguintes tabelas, dependendo do tipo de evento:
    • process: campo de departamento na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • robô: campo de 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 seguintes tabelas, dependendo do tipo de evento:
    • execução: campo sys_domain na tabela Execução de automação [sn_ac_automation_execution].
    • process: campo sys_domain na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • robô: campo sys_domain na tabela Robô 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 de ambiente na tabela Execução de automação [sn_ac_automation_execution].
    Nota:
    Este valor não é usado pela instância ServiceNow e pode conter qualquer valor exigido por 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 Obrigató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 Obrigatório. Identificador numérico exclusivo do evento associado.
    Este valor é armazenado nas seguintes tabelas, dependendo do tipo de evento:
    • execução: campo automation_execution_id na tabela Execução de automação [sn_ac_automation_execution].
    • process: campo certification_id na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • robô: campo certification_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ô. Obrigatório. Nome do evento.
    Este valor é armazenado nas seguintes tabelas, dependendo do tipo de evento:
    • process: campo de nome na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • robô: campo de nome na tabela Robô 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(a)
    • Média 
    • Baixo(a)
    Este valor é armazenado no campo de 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. Obrigatório. Identificador exclusivo do processo no qual a execução será executada. Este valor está localizado no campo certification_id do registro do processo correspondente na tabela Base Bot Process [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
    ID do robô Somente tipo de evento de execução. Obrigatório. Identificador exclusivo do robô no qual a execução será executada. Este valor está localizado no campo certification_id do registro do robô correspondente na tabela Robô de base [cmdb_ci_base_rpa_robot].

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

    Tipo de dados: cadeia de caracteres
    Fonte Obrigató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 seguintes tabelas, dependendo do tipo de evento:
    • execução: campo de origem na tabela Execução de automação [sn_ac_automation_execution].
    • process: campo de origem na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • robô: 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 o robô (diferencia maiúsculas de minúsculas):
    • Cancelado(a)
    • Concluído
    • Erro
    • Em fila
    • Em Execução
    Padrão: em fila
    Valores possíveis para execução (diferencia maiúsculas de minúsculas):
    • Disponível
    • Ocupado
    • Desconectado
    • Novo(a)
    • Responsivo(a)
    Padrão: novo
    Este valor é armazenado nas seguintes tabelas, dependendo do tipo de evento:
    • execução: campo de estado na tabela Execução de automação [sn_ac_automation_execution].
    • robô: campo robô_state na tabela Robô base [cmdb_ci_base_rpa_robot].

    Tipo de dados: cadeia de caracteres
    status Somente tipo de evento de processo. Obrigatório. Status do processo.
    Valores possíveis (diferencia maiúsculas de minúsculas):
    • Compilação
    • Em manutenção
    • Em uso
    • Retirado
    Este valor é armazenado no campo life_cycle_stage_status na tabela Processo de bot de base [cmdb_ci_base_rpa_process].

    Tipo de dados: cadeia de caracteres
    acionadoPor 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 pela instância ServiceNow e pode conter qualquer valor exigido por sua implementação.

    Tipo de dados: cadeia de caracteres
    tipo Somente tipos de evento de processo e robô. Necessário para o processo, opcional para o robô. Tipo de processamento a ser executado.
    Valores válidos (diferencia maiúsculas de minúsculas):
    • Acompanhado
    • Desacompanhado
    Este valor é armazenado nas seguintes tabelas, dependendo do tipo de evento:
    • process: campo process_type na tabela Processo de bot de base [cmdb_ci_base_rpa_process].
    • robô: campo robô_type na tabela Robô 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 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
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/json ou 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 códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.

    Tabela 6. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Falha. A solicitação foi rejeitada porque há campos obrigatórios ausentes ou porque 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 Vazio 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 somente 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 somente 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 somente 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 eventName definido 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 somente 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 o parâmetro status 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 somente 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 para um robô junto com o eventName definido 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 somente 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 para uma execução junto com o eventName definido 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 somente 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