Automation Center API

  • Rversion finale: Xanadu
  • Mis à jour 1 août 2024
  • 12 minutes de lecture

    • L’API Automation Center fournit des points de terminaison pour créer et mettre à jour des processus, des robots et des tâches d’exécution.

    À l’aide de cette API, vous pouvez définir des automatisations de bout en bout pour les tâches répétitives, puis gérer et surveiller ces tâches.

    Cette API vous permet de créer les types d’événements suivants au sein de votre ServiceNow instance :
    • Robots : agents logiciels qui exécutent un processus de bot. Les robots RPA peuvent s’exécuter avec ou sans assistance.
    • Processus : instance d’un RPA sur un robot spécifique. Il est responsable de l’exécution des tâches. Pour identifier de façon unique un processus, vous devez spécifier à la fois l’ID du processus et l’ID du robot.
    • Exécution : tâche spécifique à exécuter dans un processus robot, telle que copier des informations d’une ressource et les copier vers une autre, comme lors de la copie d’informations d’e-mails vers une feuille de calcul.
    Par exemple, vous pouvez utiliser cette API pour définir les entités nécessaires pour se connecter à l’application, copier et coller des informations, déplacer des documents et des fichiers et extraire le contenu d’e-mails, de PDF et de formulaires.

    En règle générale, vous devez d’abord créer un robot, puis tous les processus associés à ce robot, mais cela n’est pas appliqué par l’API. Vous devez toutefois créer le robot et le processus avant d’essayer d’exécuter des tâches pour eux, sinon la demande de tâche échouera.

    Remarque :
    • Vous ne pouvez pas supprimer un événement à l’aide de cette API. Par défaut, les événements sont automatiquement supprimés d’une instance au bout de 14 jours.
    • Vous pouvez transmettre un maximum de 2 000 enregistrements par appel. Cette valeur n’est pas modifiable.

    Cette API nécessite que le module d’extension Automation Center soit actif et que l’utilisateur ait le rôle sn_as.automation_technical_user ou sn_ac.automation_admin.

    Automation Center : POST /sn_ac/automatisation/rpa

    Crée des événements de robot, de processus et d’exécution.

    Ces événements permettent l’automatisation des processus. Ils apparaissent dans les tableaux de bord Vue d’ensemble et Exécution d’Automation Center pour mesurer et surveiller les résultats de plusieurs fournisseurs RPA.

    Format d'URL

    URL versionnée : /api/sn_ac/{api_version}/automation/rpa

    URL par défaut : /api/sn_ac/v1/automation/rpa

    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
    Tableau 2. Paramètres de requête
    Nom Description
    Aucun
    Tableau 3. Paramètres de corps de demande (XML ou JSON)
    Nom Description
    departmentName Types d’événements de processus et de robot uniquement. Nom du département auquel l’événement appartient.
    Cette valeur est stockée dans les tables suivantes en fonction du type d’événement :
    • processus : champ département dans la table Processus de bot de base [cmdb_ci_base_rpa_process].
    • robot : champ département de la table Robot de base [cmdb_ci_base_rpa_robot].

    Type de données : chaîne
    domainId Sys_id du domaine auquel l’événement appartient.
    Cette valeur est stockée dans les tables suivantes en fonction du type d’événement :
    • exécution : champ sys_domain dans la table Exécution de l’automatisation [sn_ac_automation_execution].
    • processus : champ sys_domain dans la table Processus de bot de base [cmdb_ci_base_rpa_process].
    • robot : champ sys_domain dans la table Robot de base [cmdb_ci_base_rpa_robot].

    Type de données : chaîne
    endtime Type d’événement d’exécution uniquement. Heure de fin de l’exécution. Cette valeur est stockée dans le champ end_time de la table Exécution de l’automatisation [sn_ac_automation_execution].

    Format : JJ-MM-AAAA HH :MM :SS

    Type de données : chaîne
    environnement Type d’événement d’exécution uniquement. Environnement de l’exécution, tel qu’une URL. Cette valeur est stockée dans le champ Environnement de la table Exécution de l’automatisation [sn_ac_automation_execution].
    Remarque :
    Cette valeur n’est pas utilisée par l’instance ServiceNow et peut contenir n’importe quelle valeur requise par votre implémentation.

    Type de données : chaîne
    errorMessage Type d’événement d’exécution uniquement. Nom du journal des messages d’erreur. Cette valeur est stockée dans le champ Message de la table Exécution de l’automatisation [sn_ac_automation_execution].

    Type de données : chaîne
    eventName Requis. Nom du type d’événement. Cette valeur détermine le type d’événement à traiter.
    Valeurs valides (sensibles à la casse) :
    • exécution
    • Processus
    • robot

    Type de données : chaîne
    id Requis. Identificateur numérique unique de l’événement associé.
    Cette valeur est stockée dans les tables suivantes en fonction du type d’événement :
    • exécution : champ automation_execution_id dans la table Exécution de l’automatisation [sn_ac_automation_execution].
    • processus : champ correlation_id dans la table Processus de bot de base [cmdb_ci_base_rpa_process].
    • robot : champ correlation_id dans la table Robot de base [cmdb_ci_base_rpa_robot].

    Type de données : entier
    nom Types d’événements de processus et de robot uniquement. Obligatoire. Nom de l’événement.
    Cette valeur est stockée dans les tables suivantes en fonction du type d’événement :
    • processus : champ nom dans la table Processus de bot de base [cmdb_ci_base_rpa_process].
    • robot : champ de nom dans la table Robot de base [cmdb_ci_base_rpa_robot].

    Type de données : chaîne
    Priorité Type d’événement d’exécution uniquement. Priorité de l’exécution.
    Valeurs possibles (sensibles à la casse) :
    • Critique
    • Élevée
    • Moyenne
    • Faible
    Cette valeur est stockée dans le champ Priorité de la table Exécution de l’automatisation [sn_ac_automation_execution].

    Type de données : chaîne

    Par défaut : Aucun - non affiché dans le tableau de bord
    processId Type d’événement d’exécution uniquement. Obligatoire. Identificateur unique du processus sur lequel exécuter l’exécution. Cette valeur se trouve dans le champ correlation_id de l’enregistrement de processus correspondant dans la table Processus de bot de base [cmdb_ci_base_rpa_process].

    Cette valeur est ensuite stockée dans le champ d’automatisation de la table Exécution de l’automatisation [sn_ac_automation_execution].

    Type de données : chaîne
    ID robot Type d’événement d’exécution uniquement. Obligatoire. Identificateur unique du robot sur lequel exécuter l’exécution. Cette valeur se trouve dans le champ correlation_id de l’enregistrement de robot correspondant dans la table Robot de base [cmdb_ci_base_rpa_robot].

    Cette valeur est ensuite stockée dans le champ robot de la table Exécution de l’automatisation [sn_ac_automation_execution].

    Type de données : chaîne
    source Requis. Source à laquelle l’événement appartient, telle que « servicenow_rpa ». Cette valeur figure dans le champ internal_name de la table Source d’automatisation [sn_ac_automation_source].
    Cette valeur est ensuite stockée dans les tables suivantes en fonction du type d’événement :
    • exécution : champ source dans la table Exécution de l’automatisation [sn_ac_automation_execution].
    • processus : champ source dans la table Processus de bot de base [cmdb_ci_base_rpa_process].
    • robot : champ source dans la table Robot de base [cmdb_ci_base_rpa_robot].

    Type de données : chaîne
    starttime Type d’événement d’exécution uniquement. Heure de début de l’exécution. Cette valeur est stockée dans le champ start_time de la table Exécution de l’automatisation [sn_ac_automation_execution].

    Format : JJ-MM-AAAA HH :MM :SS

    Type de données : chaîne
    État Types d’événements de robot et d’exécution uniquement. État de l’événement associé.
    Valeurs possibles pour le robot (sensible à la casse) :
    • Annulé
    • Terminé
    • Erreur
    • Mis en file d'attente
    • En cours d'exécution
    Par défaut : Mis en file d’attente
    Valeurs d’exécution possibles (sensible à la casse) :
    • Disponible
    • Occupé
    • Déconnecté
    • Nouvelle
    • Réactif
    Par défaut : Nouveau
    Cette valeur est stockée dans les tables suivantes en fonction du type d’événement :
    • exécution : champ d’état dans la table Exécution de l’automatisation [sn_ac_automation_execution].
    • robot : champ robot_state dans la table Robot de base [cmdb_ci_base_rpa_robot].

    Type de données : chaîne
    statut Type d’événement de processus uniquement. Obligatoire. État du processus.
    Valeurs possibles (sensibles à la casse) :
    • Version
    • En cours de maintenance
    • En cours d'utilisation
    • Mis hors service
    Cette valeur est stockée dans le champ life_cycle_stage_status de la table Processus de bot de base [cmdb_ci_base_rpa_process].

    Type de données : chaîne
    triggeredBy Type d’événement d’exécution uniquement. Source du déclencheur de l’exécution. Cette valeur est stockée dans le champ trigger_by de la table Exécution de l’automatisation [sn_ac_automation_execution].
    Remarque :
    Cette valeur n’est pas utilisée par l’instance ServiceNow et peut contenir n’importe quelle valeur requise par votre implémentation.

    Type de données : chaîne
    type Types d’événements de processus et de robot uniquement. Requis pour le processus, facultatif pour le robot. Type de traitement à effectuer.
    Valeurs possibles (sensibles à la casse) :
    • Assisté
    • Non assisté
    Cette valeur est stockée dans les tables suivantes en fonction du type d’événement :
    • processus : champ process_type dans la table Processus de bot de base [cmdb_ci_base_rpa_process].
    • robot : champ robot_type dans la table Robot de base [cmdb_ci_base_rpa_robot].

    Type de données : chaîne

    Par défaut : Non assisté pour le robot
    version Type d’événement de robot uniquement. Version du robot.

    Cette valeur est stockée dans le champ Version de la table Robot de base [cmdb_ci_base_rpa_robot].

    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 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
    Content-Type Format de données du corps de la demande. 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 Échec. La demande a été rejetée en raison de champs obligatoires manquants ou la demande contient des valeurs non valides. Le message d’erreur associé décrit la raison de l’échec.

    Paramètres du corps de réponse

    Nom Description
    résultat Vide si la demande aboutit. En cas de défaillance, des informations supplémentaires sont fournies.

    Type de données : objet

    "result": {
  "fields": {
    "<record_number>": [
      "<field_in_err_or_missing>": "String"
    ]
  }
  "reason": "String"
}
    Par exemple, si les enregistrements 1, 2 et 3 n’ont pas tous un champ obligatoire, un message similaire au suivant est renvoyé :
    {
  "result": {
    "fields": {
      "1": [
        "id"
      ],
      "2": [
        "status"
      ],
      "3": [
        "name"
      ]
    },
    "reason": "We are not able to process the data as following records have insufficient data"
  }
}

    Demande cURL

    L’exemple de code suivant montre comment publier trois enregistrements de type d’événement de robot.

    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"

    Ce point de terminaison renvoie uniquement un code d’état HTTP en cas de réussite, ainsi qu’un code d’état HTTP et un message d’erreur en cas d’échec.

    None

    Demande cURL

    L’exemple de code suivant montre comment valider trois enregistrements de type d’événement de processus.

    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"

    Ce point de terminaison renvoie uniquement un code d’état HTTP en cas de réussite, ainsi qu’un code d’état HTTP et un message d’erreur en cas d’échec.

    None

    Demande cURL

    L’exemple de code suivant montre comment publier trois enregistrements de type d’événement d’exécution.

    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"

    Ce point de terminaison renvoie uniquement un code d’état HTTP en cas de réussite, ainsi qu’un code d’état HTTP et un message d’erreur en cas d’échec.

    None

    Demande cURL

    L’exemple de code suivant montre comment créer ou mettre à jour un processus. Vous créez un processus en transmettant tous les paramètres obligatoires pour qu’un processus s’exécute avec le eventName paramètre défini sur « processus ». Les paramètres obligatoires nécessaires à la création d’un processus sont : id, type, namestatus, et 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"

    Ce point de terminaison renvoie uniquement un code d’état HTTP en cas de réussite, ainsi qu’un code d’état HTTP et un message d’erreur en cas d’échec.

    None

    Demande cURL

    L’exemple de code suivant montre comment publier un processus. Vous pouvez publier un processus en transmettant le status jeu de paramètres sur « Publié ».

    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"

    Ce point de terminaison renvoie uniquement un code d’état HTTP en cas de réussite, ainsi qu’un code d’état HTTP et un message d’erreur en cas d’échec.

    None

    Demande cURL

    L’exemple de code suivant montre comment créer ou mettre à jour un robot. Vous créez un robot en transmettant tous les paramètres obligatoires pour un robot avec le eventName réglage sur « robot ». Les paramètres obligatoires nécessaires à la création d’un robot sont : id, status, nameet 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"

    Ce point de terminaison renvoie uniquement un code d’état HTTP en cas de réussite, ainsi qu’un code d’état HTTP et un message d’erreur en cas d’échec.

    None

    Demande cURL

    L’exemple de code suivant montre comment créer ou mettre à jour une exécution. Pour créer une exécution, transmettez tous les paramètres obligatoires d’une exécution avec le eventName paramètre défini sur « exécution ». Les paramètres obligatoires nécessaires à la création d’une exécution sont : id, processId, robotIdet 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"

    Ce point de terminaison renvoie uniquement un code d’état HTTP en cas de réussite, ainsi qu’un code d’état HTTP et un message d’erreur en cas d’échec.

    None