AWA API de atribuição manual

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

    • A API de atribuição manual do AWA fornece um endpoint para atribuir manualmente itens de trabalho disponíveis aos agentes Atribuição avançada de trabalho (AWA) disponíveis.

    Um item de trabalho é um único trabalho tratado por um agente AWA do início ao fim. Por exemplo, um bate-papo ou um caso é um objeto que pode ser roteado e atribuído a agentes. Para obter mais informações, consulte Advanced Work Assignment.

    Esta API requer o plug-in Atribuição avançada de trabalho (com.glide.awa). Para chamar esta API, você deve ter a função awa_manager ou awa_integration_user.

    Atribuição manual do AWA – POST /now/awa/workitems/{work_item_sys_id}/assignments

    Atribui um item de trabalho disponível a um agente Atribuição avançada de trabalho (AWA) disponível.

    O caso de uso primário para este endpoint é permitir que sistemas de roteamento externo roteiam itens de trabalho. Se Atribuição avançada de trabalho estiver configurado para usar o roteamento externo, os itens de trabalho na fila serão atribuídos usando o roteamento externo e não AWA. Você pode atribuir a tarefa de item de trabalho chamando este endpoint. Para obter mais informações, consulte Usar roteamento externo.

    Formato da URL

    URL com controle de versões: /now/{api_version}/awa/workitems/{sys_id}/assignments

    URL padrão: /now/awa/workitems/{sys_id}/assignments

    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
    work_item_sys_id O sys_id do item de trabalho a ser atribuído a um agente disponível. Localizado na tabela Itens de trabalho [awa_work_item].

    O item de trabalho deve estar não atribuído e no estado Aceitação pendente ou Em fila. Para obter mais informações, consulte Verificar itens de trabalho de tarefa não atribuídos.

    Tipo: 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
    após_tempo_limite_presença Sys_id do estado de presença para o qual o agente alterna se o parâmetro timeout expirar. Localizado na tabela Estado de presença do AWA [awa_presence_state].

    Se o parâmetro timeout não for aprovado, este parâmetro será ignorado.

    Para obter informações adicionais sobre estados de presença, consulte Configure agent presence states.

    Tipo de dados: cadeia de caracteres

    Padrão: "" (cadeia de caracteres vazia)
    agent_sys_id Obrigatório. Sys_id do agente disponível para receber o item de trabalho. Os agentes são usuários com a função awa_agent na tabela Usuário [sys_user].

    Para obter informações sobre como determinar se um agente está disponível, consulte Controles da caixa de entrada do agente.

    Tipo de dados: cadeia de caracteres
    permitido_a_recusar Sinalizador que indica se os agentes têm permissão para rejeitar itens de trabalho. Se este parâmetro for verdadeiro, o cartão da caixa de entrada exibirá os botões Aceitar e Rejeitar no cartão da caixa de entrada.
    Valores válidos (sem distinção entre maiúsculas e minúsculas):
    • verdadeiro/sim/1: o agente pode rejeitar itens de trabalho.
    • falso/não/0: o agente não pode rejeitar itens de trabalho.

    Tipo de dados: booliano

    Padrão: verdadeiro
    opção_exibição Opção de exibição para o cartão e a guia quando um item de trabalho é atribuído automaticamente.

    Este parâmetro só será válido se enable_auto_assign for passado como verdadeiro.

    Valores válidos:
    • card_only: exibe somente o cartão.
    • card_and_tab: exibe o cartão e a guia.

    Tipo de dados: cadeia de caracteres

    Padrão: card_only
    habilitar_atribuição_automática Sinalizador que indica se o item de trabalho deve ser aceito automaticamente ou deve permitir que o agente aceite ou rejeite manualmente o item de trabalho.
    Valores válidos (sem distinção entre maiúsculas e minúsculas):
    • verdadeiro/sim/1: aceitar automaticamente.
    • falso/não/0: permite que o agente aceite ou rejeite manualmente.

    Tipo de dados: booliano

    Padrão: falso
    oferecido_em Tempo de oferta do item de trabalho. O tempo de oferta é usado para calcular o tempo restante que o agente tem para aceitar o item de trabalho na caixa de entrada. Isso ajuda a contabilizar a discrepância entre o momento em que a solicitação de API é processada e quando o sistema de roteamento de terceiros invoca a solicitação de API. Este parâmetro permite que sistemas externos que chamam este endpoint configurem o tempo de oferta do item de trabalho para que ele permaneça em sincronização com o acompanhamento interno do sistema externo do item de trabalho.

    Por exemplo, se o item de trabalho foi oferecido em 11:30:30, o tempo limite é de 30 segundos e a hora atual é 11:30:45, o temporizador de contagem regressiva exibe 00:15 (como em 15 segundos restantes).

    Este valor é armazenado no campo assigned_on no item de trabalho.

    Este parâmetro será ignorado se o parâmetro timeout não for passado.

    Tipo de dados: cadeia de caracteres

    Formato: carimbo de data/hora UTC (aaaa-MM-dd'T'HH:mm:ss.SSS)
    tempo limite Quantidade de tempo que o item de trabalho permanece na caixa de entrada do agente aguardando que o agente aceite a atribuição de trabalho.

    Tipo de dados: número

    Unidade: segundos

    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 de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    404 Não encontrado. O item solicitado não foi encontrado.
    409 Conflito. Não foi possível aprovar a solicitação devido a um erro no item de trabalho ou no sys_id do agente fornecido.
    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
    êxito Sinalizador que indica se a atribuição do item de trabalho manual foi bem-sucedida.
    Valores possíveis:
    • verdadeiro: atribuição de item de trabalho bem-sucedida.
    • falso: atribuição de item de trabalho malsucedida.

    Tipo de dados: booliano
    mensagem Mensagem de resposta confirmando uma atribuição ou exceção bem-sucedida.

    Sucesso: "Atribuição manual solicitada com sucesso."

    Exceções:
    • "<work_item_sys_id> não é um item de trabalho válido" – O sys_id do item de trabalho fornecido não existe.
    • "Solicitante<API_caller_sys_id> não tem a função awa_manager ou awa_integration_user" – O usuário autenticado que faz a solicitação de API deve ter a função awa_manager ou awa_integration_user.
    • "Item de trabalho<work_item_sys_id> não pode ser atribuído" – o item de trabalho fornecido não pode ser atribuído porque está no estado Aceito ou Cancelado. Consulte Verificar itens de trabalho e eventos do AWA.
    • "<agent_sys_id> não é um agente válido" – O agente não tem a função awa_agent.
    • "O item de trabalho já está atribuído a<agent_sys_id> " – O item de trabalho fornecido está atribuído a outro agente.
    • “O agente não está disponível” – O agente não está no estado Disponível no AWA. Consulte Controles da caixa de entrada do agente.
    • "O valor de tempo limite não pode ser negativo" – O valor de tempo limite fornecido não pode ser negativo.
    • "<presence_state_sys_id> não é um estado de presença válido” – O sys_id do estado de presença fornecido não existe na tabela de estado de presença do AWA [awa_presence_state].
    • "Tempo oferecido (<offered_on_timestamp> ) deve estar no seguinte formato: yyyy-MM-dd'T'HH:mm:ss.SSS" – o carimbo de data/hora offered_on fornecido deve estar no formato especificado.
    • "Tempo oferecido (<offered_on_timestamp > ) deve ser anterior à hora atual, caso contrário, o agente terá mais tempo para aceitar o item de trabalho” – O carimbo de data/hora offered_on fornecido não pode ser anterior à hora em que a solicitação é feita.
    • "Carimbo de data/hora após tempo limite (<offered_on_timestamp > ) deve ser posterior à hora atual, caso contrário, o agente não terá tempo para aceitar o item de trabalho" – O carimbo de data/hora após adicionar o valor de tempo limite ao carimbo de data/hora offered_on fornecido deve ser posterior à hora em que a solicitação foi feita.
    • "<display_option> não é uma opção de exibição válida" – O display_option fornecido deve ter um dos seguintes valores: "card_only" ou "card_and_tab"
    • "%s não é um valor booliano válido" – o valor do tipo booliano fornecido deve estar em um dos seguintes formatos boolianos: "sim"/"não", "verdadeiro"/"falso", "1"/"0"

    Tipo de dados: cadeia de caracteres

    Solicitação de cURL

    O exemplo a seguir mostra como atribuir um item de trabalho a um agente do AWA disponível usando somente os parâmetros necessários.

    curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"agent_sys_id\":\"<agent_sys_id>\"}" \
--user 'username':'password'

    O resultado mostra que a tarefa foi atribuída com sucesso ao agente. Você pode verificar os resultados no campo Atribuído a da tabela Itens de trabalho [awa_work_item].

    {
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}

    Solicitação de cURL

    O exemplo a seguir mostra como atribuir um item de trabalho a um agente do AWA disponível, incluindo os parâmetros opcionais.

    curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{
    "agent_sys_id": "46d44a23a9fe19810012d100cca80666",
    "timeout":"10",
    "offered_on":"2024-04-03T23:09:31.000"
  }'
--user 'username':'password'

    O resultado mostra que a tarefa foi atribuída com sucesso ao agente. Você pode verificar os resultados no campo Atribuído a da tabela Itens de trabalho [awa_work_item].

    {
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}