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

  • Rversion finale: Washingtondc
  • Mis à jour 1 févr. 2024
  • 11 minutes de lecture

    • 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 du rejet des é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, reportez-vous à Advanced Work Assignment.

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

    Obtient les raisons 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}

    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. 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 répertorié dans la table Canaux de service [awa_service_channel]. (pour en savoir plus, consultez ) ;
    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 une 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 une 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 Advanced Work Assignment (com.glide.awa) est installé. Pour plus d’informations, reportez-vous à la section Composants installés avec Advanced Work Assignment.
    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 de corps de réponse (JSON ou XML)

    Nom Description
    display_value Valeur d’affichage du champ Motif dans la table Raisons du rejet [awa_reject_reason].

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

    Type de données : nombre
    valide Valeur du champ du 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. Les motifs sont répertoriés dans la table Motifs du rejet [awa_reject_reason].

    Type de données : chaîne

    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 de 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 la boîte de réception AWA : POST /awa/inbox/actions/accept

    Accepte un élément de travail à l’état Acceptation en attente au nom 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

    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. 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é dans la table Utilisateur [sys_user].

    Type de données : chaîne
    work_item_id Sys_id de l’élément de travail répertorié dans la table Élément de travail AWA [awa_work_item].
    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 Acceptation en attente .

    Type de données : chaîne

    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 une 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 une 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 de l’é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 Advanced Work Assignment (com.glide.awa) est installé. Pour plus d’informations, reportez-vous à la section Composants installés avec Advanced Work Assignment.
    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 de corps de 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. Situé dans la table nommée dans le documentTable champ.

    Type de données : chaîne
    erreur Détails décrivant une erreur rencontrée au cours du processus de demande.

    Type de données : objet

    "error": {
  "detail": "String",
  "message": "String"
}
    erreur.détail Détails de l’erreur rencontrée au cours du processus de demande.
    Valeurs possibles :
    • ID de l’agent manquant : il n’a agent_id pas été fourni dans le corps de la demande.
    • ID de l’élément de travail manquant : le n’a work_item_id pas été 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 d’erreur Message de l’erreur rencontrée au cours du processus de demande. La description est fournie dans la error.detail propriété.

    Type de données : chaîne
    statut État d’une demande ayant échoué. 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 modifier l’état d’un élément de travail d’un agent sélectionné de 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 réponse répertorie la sys_id et la table du document associé à l’élément de travail.

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

    Actions de la boîte de réception AWA – POST /awa/inbox/actions/reject

    Rejette un élément de travail dans l’état Acceptation en attente au nom d’un agent. En cas de réussite, le champ Affecté à est vide et la valeur du champ Rejeté est définie sur true 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

    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. 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é dans la table Utilisateur [sys_user].

    Type de données : chaîne
    reject_reason_id Sys_id d’un motif de rejet pour ce canal de service. Les motifs sont répertoriés dans la table Motifs du rejet [awa_reject_reason].

    Type de données : chaîne
    work_item_id Sys_id de l’élément de travail répertorié dans la table Élément de travail AWA [awa_work_item].
    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 Acceptation en attente .

    Type de données : chaîne

    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 une 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 une 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 de l’é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 Advanced Work Assignment (com.glide.awa) est installé. Pour plus d’informations, reportez-vous à la section Composants installés avec Advanced Work Assignment.
    404 Introuvable. L'élément demandé est introuvable.
    Raisons possibles :
    • ID d’agent incorrect : il n’existe aucun enregistrement pour l’utilisateur spécifié.
    • ID du motif de rejet incorrect : 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 de corps de réponse (JSON ou XML)

    Nom Description
    agent_id Sys_id de l’agent répertorié dans la table Utilisateur [sys_user].

    Type de données : chaîne
    erreur Détails décrivant une erreur rencontrée au cours du processus de demande.

    Type de données : objet

    "error": {
  "detail": "String",
  "message": "String"
}
    erreur.détail Détails de l’erreur rencontrée au cours du processus de demande.
    Valeurs possibles :
    • ID de l’agent manquant : il n’a agent_id pas été fourni dans le corps de la demande.
    • ID de l’élément du motif de rejet manquant : n’a reject_reason_id pas été fourni dans le corps de la demande.
    • ID de l’élément de travail manquant : le n’a work_item_id pas été fourni dans le corps de la demande.
    • Il n’existe aucun enregistrement pour awa_reject_reason : <reason_sys_id> – Le fourni reject_reason_id dans le corps de la demande n’a pas d’enregistrement correspondant dans la table Raisons du rejet [awa_reject_reason].
    • Il n’existe aucun enregistrement pour awa_work_item : <work_item_sys_id> : l’enregistrement 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> : l’enregistrement 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 d’erreur Message de l’erreur rencontrée au cours du processus de demande. La description est fournie dans la error.detail propriété.

    Type de données : chaîne
    statut État d’une demande ayant échoué. 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. Les motifs sont répertoriés dans la table Motifs du rejet [awa_reject_reason].

    Type de données : chaîne
    work_item_id Sys_id de l’élément de travail répertorié dans la table Élément de travail AWA [awa_work_item].

    Type de données : chaîne

    L’exemple suivant montre comment rejeter un élément de travail affecté avec le motif « 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'

    La sortie réussie affiche le même élément de travail, le même motif du 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 définie sur vrai.

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