API de ações da caixa de entrada do AWA

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

    • A API de ações de caixa de entrada do AWA fornece endpoints para aceitar ou rejeitar um item de trabalho em nome de um agente. Esta API também recupera motivos de rejeição para itens de trabalho rejeitados.

    Esta API requer o plug-in Atribuição avançada de trabalho (com.glide.awa) e a função awa_integration_user. Para obter mais informações, consulte Advanced Work Assignment.

    Ações de caixa de entrada do AWA – GET /awa/inbox/actions/reject_reasons/{channel_id}

    Obtém os motivos de rejeição do item de trabalho para um canal de serviço especificado.

    Formato da URL

    URL com controle de versões: /api/now/awa/inbox/actions/reject_reasons/{channel_id}

    URL padrão: /api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_id}

    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
    channel_id Sys_id de um canal de serviço listado na tabela Canais de serviço [awa_service_channel]. Para obter informações, consulte .
    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
    Nenhum(a)

    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
    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 de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro. Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Advanced Work Assignment (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com o Advanced Work Assignment.
    404 Registro não encontrado. O ID do canal fornecido não é válido.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

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

    Nome Descrição
    display_value Valor de exibição do campo Motivo na tabela Motivos de rejeição [awa_reject_reason].

    Tipo de dados: cadeia de caracteres
    pedido Ordem na qual os motivos da rejeição são listados na caixa de entrada do agente.

    Tipo de dados: número
    valor Valor do campo de motivo da rejeição armazenado no banco de dados.

    Tipo de dados: cadeia de caracteres
    Sys_id Sys_id de um motivo de rejeição para este canal de serviço. Os motivos são listados na tabela Motivos de rejeição [awa_reject_reason].

    Tipo de dados: cadeia de caracteres

    O exemplo a seguir mostra como recuperar motivos de rejeição para o canal de serviço de bate-papo.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject_reasons/27f675e3739713004a905ee515f6a7c3" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    Corpo de resposta exibindo tarefas rejeitadas com motivos para rejeição.

    {
  "result": [
    {
      "order": 2,
      "value": "Not my expertise",
      "display_value": "Not my expertise",
      "sys_id": "31e3fa29b38023002e7b6e5f26a8dc17"
    },
    {
      "order": 1,
      "value": "Busy",
      "display_value": "Busy",
      "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
    }
  ]
}

    Ações de caixa de entrada do AWA – POST /awa/inbox/actions/accept

    Aceita um item de trabalho no estado Aceitação pendente em nome de um agente.

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/awa/inbox/actions/accept

    URL padrão: /api/now/awa/inbox/actions/accept

    Parâmetros de solicitação compatíveis

    Tabela 7. 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 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    agent_id Sys_id do agente listado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    work_item_id Sys_id do item de trabalho listado na tabela Item de trabalho do AWA [awa_work_item].
    O item de trabalho deve atender aos seguintes critérios:
    • O item de trabalho deve ser atribuído ao agente especificado.
    • O item de trabalho deve estar no estado Aceitação pendente.

    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 10. 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 11. 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 12. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação inválida.
    Possíveis motivos:
    • ID do agente ausente.
    • ID do item de trabalho ausente.
    • O item de trabalho está atribuído a um agente diferente.
    • O item de trabalho não está no estado de aceitação pendente.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro. Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Advanced Work Assignment (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com o Advanced Work Assignment.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

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

    Nome Descrição
    documentTable Nome da tabela que lista o documento atribuído a este item de trabalho.

    Tipo de dados: cadeia de caracteres
    documentSysId Sys_id do registro do documento atribuído à tarefa. Localizado na tabela nomeada no campo documentTable.

    Tipo de dados: cadeia de caracteres
    erro Detalhes que descrevem um erro encontrado durante o processo de solicitação.

    Tipo de dados: objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    erro.detalhe Detalhes do erro encontrado durante o processo de solicitação.
    Valores possíveis:
    • ID do agente ausente: agent_id não foi fornecido no corpo da solicitação.
    • ID do item de trabalho ausente: o work_item_id não foi fornecido no corpo da solicitação.
    • O item de trabalho está atribuído a um agente diferente – O item de trabalho especificado não está atribuído ao agente especificado.
    • ID do item de trabalho incorreto - o item de trabalho fornecido no corpo da solicitação é impreciso ou não existe.
    • O item de trabalho não está no estado de aceitação pendente – O item de trabalho fornecido no corpo da solicitação está em um estado diferente de Aceitação pendente.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem do erro encontrado durante o processo de solicitação. A descrição é fornecida na propriedade error.detail.

    Tipo de dados: cadeia de caracteres
    status Status de uma solicitação malsucedida. Esta propriedade só será incluída na resposta se houver um erro.

    Valor válido: falha

    Tipo de dados: cadeia de caracteres

    Solicitação de cURL

    O exemplo a seguir mostra como mudar o estado do item de trabalho de um agente selecionado de Aceitação Pendente para Aceito.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/accept" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
 \"work_item_id\":\"fd69abfc878b01101ae365b83cbb35fe\"
}" \
--user 'username':'password'

    O corpo da resposta lista o sys_id e a tabela do documento relacionado ao item de trabalho.

    {
  "result": {
    "documentSysId": "57af7aec73d423002728660c4cf6a71c",
    "documentTable": "incident"
  }
}

    Ações de caixa de entrada do AWA – POST /awa/inbox/actions/reject

    Rejeita um item de trabalho no estado Aceitação pendente em nome de um agente. Se for bem-sucedido, o campo Atribuído a ficará vazio e o valor do campo Rejeitado será verdadeiro para o item de trabalho especificado.

    Formato da URL

    URL com controle de versão: /api/now/{api_version}/awa/inbox/actions/reject

    URL padrão: /api/now/awa/inbox/actions/reject

    Parâmetros de solicitação compatíveis

    Tabela 13. 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 14. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 15. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    agent_id Sys_id do agente listado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    rejeitar_reason_id Sys_id de um motivo de rejeição para este canal de serviço. Os motivos são listados na tabela Motivos de rejeição [awa_reject_reason].

    Tipo de dados: cadeia de caracteres
    work_item_id Sys_id do item de trabalho listado na tabela Item de trabalho do AWA [awa_work_item].
    O item de trabalho deve atender aos seguintes critérios:
    • O item de trabalho deve ser atribuído ao agente especificado.
    • O item de trabalho deve estar no estado Aceitação pendente.

    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 16. 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 17. 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 18. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Solicitação inválida.
    Possíveis motivos:
    • ID do agente ausente.
    • ID do item de trabalho ausente.
    • ID do motivo de rejeição ausente.
    • O item de trabalho está atribuído a um agente diferente.
    • O item de trabalho não está no estado de aceitação pendente.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido.
    Possíveis motivos:
    • O usuário não tem a função awa_integration_user.
    • O valor da propriedade glide.awa.enabled não é verdadeiro. Esta propriedade será listada na tabela Propriedade do sistema [sys_property] se o plug-in Advanced Work Assignment (com.glide.awa) estiver instalado. Para obter mais informações, consulte Componentes instalados com o Advanced Work Assignment.
    404 Não encontrado. O item solicitado não foi encontrado.
    Possíveis motivos:
    • ID de agente incorreto – Não há registro para o usuário especificado.
    • ID do motivo de rejeição incorreto – não há registro para o motivo de rejeição especificado.
    • ID do item de trabalho incorreto – Não há registro para o item de trabalho especificado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

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

    Nome Descrição
    agent_id Sys_id do agente listado na tabela Usuário [sys_user].

    Tipo de dados: cadeia de caracteres
    erro Detalhes que descrevem um erro encontrado durante o processo de solicitação.

    Tipo de dados: objeto

    "error": {
  "detail": "String",
  "message": "String"
}
    erro.detalhe Detalhes do erro encontrado durante o processo de solicitação.
    Valores possíveis:
    • ID do agente ausente – agent_id não foi fornecido no corpo da solicitação.
    • ID do item do motivo de rejeição ausente – reject_reason_id não foi fornecido no corpo da solicitação.
    • ID do item de trabalho ausente: o work_item_id não foi fornecido no corpo da solicitação.
    • Não há registro para awa_reject_reason : <reason_sys_id> – O reject_reason_id fornecido no corpo da solicitação não tem um registro correspondente na tabela Motivos de rejeição [awa_reject_reason].
    • Não há registro para awa_work_item : <work_item_sys_id> – O work_item_id fornecido no corpo da solicitação não tem um registro correspondente na tabela Item de trabalho do AWA [awa_work_item].
    • Não há registro para sys_user : <agent_sys_id> – O agent_id fornecido no corpo da solicitação não tem um registro correspondente na tabela Usuário [sys_user].
    • O item de trabalho não está no estado de aceitação pendente: o item de trabalho fornecido no corpo da solicitação está em um estado diferente de Aceitação pendente.

    Tipo de dados: cadeia de caracteres
    mensagem.erro Mensagem do erro encontrado durante o processo de solicitação. A descrição é fornecida na propriedade error.detail.

    Tipo de dados: cadeia de caracteres
    status Status de uma solicitação malsucedida. Esta propriedade só será incluída na resposta se houver um erro.

    Valor válido: falha

    Tipo de dados: cadeia de caracteres
    rejeitar_reason_id Sys_id de um motivo de rejeição para este canal de serviço. Os motivos são listados na tabela Motivos de rejeição [awa_reject_reason].

    Tipo de dados: cadeia de caracteres
    work_item_id Sys_id do item de trabalho listado na tabela Item de trabalho do AWA [awa_work_item].

    Tipo de dados: cadeia de caracteres

    O exemplo a seguir mostra como rejeitar um item de trabalho atribuído com o motivo "não é minha especialidade".

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
    \"work_item_id\":\"3ed5df4d87cf01101ae365b83cbb35af\",
    \"reject_reason_id\":\"31e3fa29b38023002e7b6e5f26a8dc17\"
}" \
--user 'username':'password'

    A saída bem-sucedida exibe o mesmo item de trabalho, motivo de rejeição e ID de usuário fornecidos no corpo da solicitação. O item de trabalho especificado na tabela Item de trabalho do AWA [awa_work_item] tem um campo Atribuído a vazio e o valor do campo Rejeitado é verdadeiro.

    {
  "result": {
    "work_item_id": "3ed5df4d87cf01101ae365b83cbb35af",
    "reject_reason_id": "31e3fa29b38023002e7b6e5f26a8dc17",
    "agent_id": "46c9e158a9fe198101d44d0d22cb640d"
  }
}