API do Automation Center

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 12 min. de leitura

    • A API Automation Center permite criar e atualizar processos, robôs e trabalhos de execução.

    Usando esta API, você pode definir automações de ponta a ponta para tarefas repetitivas e, em seguida, gerenciar e monitorar essas tarefas.

    Esta API permite que você crie os seguintes tipos de eventos em sua instância ServiceNow :
    • Robôs: agentes de software que executam um processo de bot. Os robôs de RPA podem ser executados assistidos ou autônomos.
    • Processo: instância de um RPA em um robô específico. Ele é responsável pela execução de trabalhos. Para identificar exclusivamente um processo, você deve especificar o ID do processo e o ID do robô.
    • Execução: tarefa específica a ser executada em um processo de robô, como copiar informações de um recurso e copiá-las para outro, como ao copiar informações de e-mails para uma planilha.
    Por exemplo, você pode usar essa API para definir as entidades necessárias para fazer login na aplicação, copiar e colar informações, mover documentos e arquivos e extrair conteúdo de e-mails, PDFs e formulários.

    Normalmente, você deve criar um robô primeiro e, em seguida, todos os processos associados a esse robô, mas isso não é imposto pela API. No entanto, você deve criar o robô e o processo antes de tentar executar qualquer trabalho para eles ou a solicitação de trabalho falhará.

    Nota:
    • Você não pode excluir um evento usando esta API. Por padrão, os eventos são removidos automaticamente de uma instância após 14 dias.
    • Você pode passar no máximo 2.000 registros por chamada. Este valor não pode ser modificado.

    Esta API requer que o plug-in Automation Center esteja ativo e requer que o usuário tenha a função sn_as.automation_technical_user ou sn_ac.automation_admin.

    Automation Center - POST /sn_ac/automation/rpa

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

    Esses eventos fornecem automação de processo. Eles aparecem nos painéis Visão geral e Execução do Automation Center para medir e monitorar a saída de vários fornecedores de RPA.

    Formato de URL

    URL com controle de versões: /api/sn_ac/{api_version}/automation/rpa

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

    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. 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
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    NomeDepartamento 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:
    • processo: campo de departamento na tabela Processo de bot 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].
    • processo: campo sys_domain na tabela Processo de bot 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 um 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 pela sua implementação.

    Tipo de dados: cadeia de caracteres
    errorMessage Somente tipo de evento de execução. Nome do log da mensagem 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 Base Bot Process [cmdb_ci_base_rpa_process].
    • robô: campo certification_id na tabela Base Robot [cmdb_ci_base_rpa_robot].

    Tipo de dados: 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:
    • processo: campo de nome na tabela Processo de bot 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 possíveis (diferencia maiúsculas de minúsculas):
    • Crítico
    • Alto 
    • Média 
    • Baixo
    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].

    Esse valor é armazenado no campo de automação da 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 Base Robot [cmdb_ci_base_rpa_robot].

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

    Tipo de dados: cadeia de caracteres
    origem Obrigatório. Origem à qual o evento pertence, como "servicenow_rpa". Este valor está localizado no campo internal_name da tabela Origem de automação [sn_ac_automation_source].
    Esse 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].
    • processo: campo de origem na tabela Processo de bot base [cmdb_ci_base_rpa_process].
    • robô: campo de origem na tabela Robô 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].

    Formato: AAAA-MM-DD HH:MM:SS

    Tipo de dados: cadeia de caracteres
    state Somente tipos de evento de robô e execução. Estado do evento associado.
    Valores possíveis para o robô (diferencia maiúsculas de minúsculas):
    • Cancelado
    • 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
    • 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ô_estado 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):
    • Criar
    • Em manutenção
    • Em uso
    • Desativado
    Este valor é armazenado no campo life_cycle_stage_status na tabela Base Bot Process [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 pela 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 possíveis (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 Base Bot Process [cmdb_ci_base_rpa_process].
    • robô: campo robô_tipo 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

    Códigos de status

    Os códigos de status a seguir 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 da REST API.

    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 à ausência de campos obrigatórios ou à solicitação por conter 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>": [
      "<field_in_err_or_missing>": "String"
    ]
  }
  "reason": "String"
}
    Por exemplo, se os registros 1, 2 e 3 não tiverem um campo obrigatório, será retornada uma mensagem semelhante à seguinte:
    {
  "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 de 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