API d’actions de boîte de réception AWA

  • Rversion finale: Yokohama
  • Mis à jour 30 janv. 2025
  • 11 minutes de lecture

    • L’API Actions de boîte de réception AWA fournit des points de terminaison pour accepter ou rejeter un élément de travail au nom d’un agent. Cette API récupère également les raisons de rejet pour les éléments de travail rejetés.

    Cette API nécessite le module d’extension (com.glide.awa) et awa_integration_user Affectation de travail avancée rôle. Pour plus d’informations, consultez Affectation de travail avancée.

    Actions de boîte de réception AWA – GET /awa/inbox/actions/reject_reasons/{channel_id}

    Obtient les motifs de rejet de l’élément de travail pour un canal de service spécifié.

    Format d'URL

    URL versionnée : /api/now/awa/inbox/actions/reject_reasons/{channel_id}

    URL par défaut : /api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_id}

    Remarque :
    Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST basées sur un script, des informations de version supplémentaires sont disponibles sur le formulaire Service REST scripté.

    Paramètres de demande pris en charge

    Tableau 1. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière.

    Type de données : chaîne
    channel_id Sys_id d’un canal de service.

    Type de données : chaîne

    Table : canaux de service [awa_service_channel]
    Tableau 2. Paramètres de requête
    Nom Description
    Néant
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    Néant

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 4. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 5. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 6. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    400 Demande incorrecte. Un type de demande incorrecte ou mal formé a été détecté.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    403 Interdit.
    Raisons possibles :
    • L’utilisateur ne dispose pas du rôle awa_integration_user.
    • La valeur de la propriété glide.awa.enabled n’est pas vraie. Cette propriété est répertoriée dans la table Propriétés système [sys_property] si le module d’extension Affectation de travail avancée (com.glide.awa) est installé. Pour plus d’informations, voir Composants installés avec Affectation de travail avancée.
    404 Enregistrement introuvable. L’ID de canal fourni n’est pas valide.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres du corps de la réponse (JSON ou XML)

    Nom Description
    display_value Affichez la valeur du champ Motif dans la table Motifs du rejet [awa_reject_reason].

    Type de données : chaîne
    order Ordre dans lequel les motifs du rejet sont répertoriés dans la boîte de réception de l’agent.

    Type de données : nombre
    valide Valeur du champ Motif du rejet stocké dans la base de données.

    Type de données : chaîne
    Sys_id Sys_id d’un motif de rejet pour ce canal de service.

    Type de données : chaîne

    Table : Motifs du rejet [awa_reject_reason]

    L’exemple suivant montre comment récupérer les motifs de rejet pour le canal de service de messagerie instantanée.

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

    Corps de réponse affichant les tâches rejetées avec les motifs du rejet.

    {
  "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"
    }
  ]
}

    Actions de boîte de réception AWA : POST /awa/inbox/actions/accept

    Accepte un élément de travail à l’état Acceptation en attente pour le compte d’un agent.

    Format d'URL

    URL versionnée : /api/now/{api_version}/awa/inbox/actions/accept

    URL par défaut : /api/now/awa/inbox/actions/accept

    Remarque :
    Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST basées sur un script, des informations de version supplémentaires sont disponibles sur le formulaire Service REST scripté.

    Paramètres de demande pris en charge

    Tableau 7. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière.

    Type de données : chaîne
    Tableau 8. Paramètres de requête
    Nom Description
    Néant
    Tableau 9. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    agent_id Sys_id de l’agent répertorié.

    Type de données : chaîne

    Table : Utilisateur [sys_user]
    work_item_id Sys_id de l’élément de travail.
    L’élément de travail doit répondre aux critères suivants :
    • L’élément de travail doit être affecté à l’agent spécifié.
    • L’élément de travail doit être dans l’état En attente d’acceptation .

    Type de données : chaîne

    Table : élément de travail AWA [awa_work_item]

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 10. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 11. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 12. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    400 Demande non valide.
    Raisons possibles :
    • ID de l’agent manquant.
    • ID d’élément de travail manquant.
    • L’élément de travail est affecté à un autre agent.
    • L’élément de travail n’est pas dans l’état d’acceptation en attente.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    403 Interdit.
    Raisons possibles :
    • L’utilisateur ne dispose pas du rôle awa_integration_user.
    • La valeur de la propriété glide.awa.enabled n’est pas vraie. Cette propriété est répertoriée dans la table Propriétés système [sys_property] si le module d’extension Affectation de travail avancée (com.glide.awa) est installé. Pour plus d’informations, voir Composants installés avec Affectation de travail avancée.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres du corps de la réponse (JSON ou XML)

    Nom Description
    documentTable Nom de la table répertoriant le document affecté à cet élément de travail.

    Type de données : chaîne
    documentSysId Sys_id de l’enregistrement de document affecté à la tâche.

    Type de données : chaîne

    Table : dans la table identifiée dans le documentTable champ.
    erreur Détails décrivant une erreur rencontrée pendant le processus de demande.

    Type de données : objet

    "error": {
  "detail": "String",
  "message": "String"
}
    erreur.détail Détails de l’erreur rencontrée pendant le processus de demande.
    Valeurs possibles :
    • ID de l’agent manquant : n’était agent_id pas fourni dans le corps de la demande.
    • ID d’élément de travail manquant : n’était work_item_id pas fourni dans le corps de la demande.
    • L’élément de travail est affecté à un autre agent : l’élément de travail spécifié n’est pas affecté à l’agent spécifié.
    • ID d’élément de travail incorrect : l’élément de travail fourni dans le corps de la demande est inexact ou n’existe pas.
    • L’élément de travail n’est pas dans l’état Acceptation en attente : l’élément de travail fourni dans le corps de la demande est dans un état autre que Acceptation en attente.

    Type de données : chaîne
    message.erreur Message pour l’erreur rencontrée pendant le processus de demande. La description est fournie dans la error.detail propriété.

    Type de données : chaîne
    statut Statut d’une demande en échec. Cette propriété n’est incluse dans la réponse qu’en cas d’erreur.

    Valeur valide : échec

    Type de données : chaîne

    Demande cURL

    L’exemple suivant montre comment changer l’état de l’élément de travail d’un agent sélectionné d’Acceptation en attente à Accepté.

    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'

    Le corps de la réponse répertorie le sys_id et la table du document associé à l’élément de travail.

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

    Actions de boîte de réception AWA : PUBLIER /awa/boîte de réception/actions/rejet

    Rejette un élément de travail à l’état Acceptation en attente pour le compte d’un agent. En cas de réussite, le champ Affecté à est vide et la valeur du champ Rejeté est vraie pour l’élément de travail spécifié.

    Format d'URL

    URL versionnée : /api/now/{api_version}/awa/inbox/actions/reject

    URL par défaut : /api/now/awa/inbox/actions/reject

    Remarque :
    Les versions disponibles sont spécifiées dans l’explorateur d’API REST. Pour les API REST basées sur un script, des informations de version supplémentaires sont disponibles sur le formulaire Service REST scripté.

    Paramètres de demande pris en charge

    Tableau 13. Paramètres de chemin d'accès
    Nom Description
    api_version Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière.

    Type de données : chaîne
    Tableau 14. Paramètres de requête
    Nom Description
    Néant
    Tableau 15. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    agent_id Sys_id de l’agent répertorié.

    Type de données : chaîne

    Table : Utilisateur [sys_user]
    reject_reason_id Sys_id d’un motif de rejet pour ce canal de service.

    Type de données : chaîne

    Table : Motifs du rejet [awa_reject_reason]
    work_item_id Sys_id de l’élément de travail.
    L’élément de travail doit répondre aux critères suivants :
    • L’élément de travail doit être affecté à l’agent spécifié.
    • L’élément de travail doit être dans l’état En attente d’acceptation .

    Type de données : chaîne

    Table : élément de travail AWA [awa_work_item]

    En-têtes

    Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.

    Tableau 16. En-têtes de demandes
    En-tête Description
    Accepter Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml.

    Valeur par défaut : application/json
    Tableau 17. En-têtes de réponses
    En-tête Description
    Aucun

    Codes d'état

    Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.

    Tableau 18. Codes d'état
    Code d'état Description
    200 Réussi. La demande a été correctement traitée.
    400 Demande non valide.
    Raisons possibles :
    • ID de l’agent manquant.
    • ID d’élément de travail manquant.
    • ID du motif du rejet manquant.
    • L’élément de travail est affecté à un autre agent.
    • L’élément de travail n’est pas dans l’état d’acceptation en attente.
    401 Non autorisé. Les informations d'identification de l'utilisateur sont incorrectes ou n'ont pas été transmises.
    403 Interdit.
    Raisons possibles :
    • L’utilisateur ne dispose pas du rôle awa_integration_user.
    • La valeur de la propriété glide.awa.enabled n’est pas vraie. Cette propriété est répertoriée dans la table Propriétés système [sys_property] si le module d’extension Affectation de travail avancée (com.glide.awa) est installé. Pour plus d’informations, voir Composants installés avec Affectation de travail avancée.
    404 Introuvable. L’élément demandé est introuvable.
    Raisons possibles :
    • ID d’agent erroné : il n’existe aucun enregistrement pour l’utilisateur spécifié.
    • ID de motif de rejet erroné : il n’existe aucun enregistrement pour le motif de rejet spécifié.
    • ID d’élément de travail incorrect : il n’existe aucun enregistrement pour l’élément de travail spécifié.
    500 Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur.

    Paramètres du corps de la réponse (JSON ou XML)

    Nom Description
    agent_id Sys_id de l’agent répertorié.

    Type de données : chaîne

    Table : Utilisateur [sys_user]
    erreur Détails décrivant une erreur rencontrée pendant le processus de demande.

    Type de données : objet

    "error": {
  "detail": "String",
  "message": "String"
}
    erreur.détail Détails de l’erreur rencontrée pendant le processus de demande.
    Valeurs possibles :
    • ID de l’agent manquant : il agent_id n’était pas fourni dans le corps de la demande.
    • ID d’élément de motif de rejet manquant : n’était reject_reason_id pas fourni dans le corps de la demande.
    • ID d’élément de travail manquant : n’était work_item_id pas fourni dans le corps de la demande.
    • Il n’existe aucun enregistrement pour awa_reject_reason : <reason_sys_id> : le reject_reason_id fourni dans le corps de la demande n’a pas d’enregistrement correspondant dans la table Motifs du rejet [awa_reject_reason].
    • Il n’existe aucun enregistrement pour awa_work_item : <work_item_sys_id> : l’élément work_item_id fourni dans le corps de la demande n’a pas d’enregistrement correspondant dans la table Élément de travail AWA [awa_work_item].
    • Il n’existe aucun enregistrement pour sys_user : <agent_sys_id> : le agent_id fourni dans le corps de la demande n’a pas d’enregistrement correspondant dans la table Utilisateur [sys_user].
    • L’élément de travail n’est pas dans l’état Acceptation en attente : l’élément de travail fourni dans le corps de la demande est dans un état autre que Acceptation en attente.

    Type de données : chaîne
    message.erreur Message pour l’erreur rencontrée pendant le processus de demande. La description est fournie dans la error.detail propriété.

    Type de données : chaîne
    statut Statut d’une demande en échec. Cette propriété n’est incluse dans la réponse qu’en cas d’erreur.

    Valeur valide : échec

    Type de données : chaîne
    reject_reason_id Sys_id d’un motif de rejet pour ce canal de service.

    Type de données : chaîne

    Table : Motifs du rejet [awa_reject_reason]
    work_item_id Sys_id de l’élément de travail.

    Type de données : chaîne

    L’exemple suivant montre comment rejeter un élément de travail affecté avec le motif « ce n’est pas mon domaine d’expertise ».

    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'

    Une sortie réussie affiche le même élément de travail, le même motif de rejet et le même ID d’utilisateur fournis dans le corps de la demande. L’élément de travail spécifié dans la table Élément de travail AWA [awa_work_item] a un champ Affecté à vide et la valeur du champ Rejeté est vrai.

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