Créer une activité de service Web REST

Utilisez cette procédure pour créer une activité de service Orchestration Web REST personnalisée.

Avant de commencer

Rôle requis : web_service_admin, activity_admin activity_creator

Pourquoi et quand exécuter cette tâche

Pour créer et utiliser une activité de workflow de service Web REST :

• Créer un Créez un message REST si un message approprié n’est pas déjà configuré.
• Affectez le rôle de web_service_admin à n’importe quel utilisateur devant créer ou modifier une activité REST personnalisée.
• Déterminez une application ou un périmètre de l’application pour cette activité.
• Déterminez le Créez un message REST à utiliser pour l’activité. Utilisez cette valeur pour remplacer le point de terminaison configuré dans le message REST.
• Vous pouvez également créer des informations d’identification d’authentification de base. Utilisez cette valeur pour remplacer les informations d’identification configurées dans le message SOAP.

Procédure

1. Créez une activité personnalisée.
   Cette action crée une activité personnalisée à l’aide d’un modèle.
2. Après avoir configuré les propriétés générales et créé des variables d’entrée, configurez la commande d’exécution du service Web REST.

   Option	Description
   Mapper les variables d’entrée	Utilisez les variables que vous avez créées pour configurer la commande qu’exécute Orchestration.
   Message REST	Nom d’un message REST existant à utiliser dans cette activité.
   Fonction de message REST	Fonction de message REST à utiliser pour cette activité.
   Point de terminaison	URL du point de terminaison pour le service Web REST que cette activité utilise. Entrez un point de terminaison dans ce champ pour remplacer le point de terminaison configuré dans le message REST. Cliquez sur le verrou pour ouvrir le champ d’entrée.
   Substitutions de variables	Paires nom-valeur à transmettre au point de terminaison REST. Vous pouvez créer ces paramètres manuellement ou faire glisser des variables d’entrée dans les champs de paramètres, puis affecter une valeur. Les paramètres définis dans le message REST qui utilisent ${} peuvent être des données affectées à partir de ce modèle d’activité. Utilisez la colonne Attribut supplémentaire pour configurer le système afin qu’il ne soit pas soumis à une séquence d’échappement du texte. Par défaut, le texte envoyé au message REST est échappé. Si les utilisateurs ont fourni des variables à l’aide de la substitution de variables dans des messages REST sortants dans le message REST, la colonne Nom est automatiquement renseignée.
   En-têtes supplémentaires	Paramètres d’en-tête HTTP supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
   Paramètres de requêtes supplémentaires	Paramètres de requête supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
   Utiliser un serveur MID	Case à cocher qui détermine si un serveur MID doit être utilisé pour appeler le service Web REST. Remarque : Si la fonction de message de service Web REST définit un serveur MID, ce serveur MID est utilisé à la place de celui sélectionné ici.
   Capacités de Serveur MID requises	Serveur MID avec les options de Serveur MID appropriées pour la connexion au point de terminaison REST. Par défaut, le système sélectionne un serveur MID avec les options REST. Ce champ est disponible lorsque la case Utiliser Serveur MID est cochée.
   Délai	Durée autorisée de la demande de service Web REST avant l’expiration de celle-ci, en secondes. La valeur par défaut est 10.
   Authentification	Détermine le type d’authentification requis pour le point de terminaison. Les options sont les suivantes : Utiliser les informations d’identification existantes dans le message REST : utilise les définitions d’informations d’identification de la définition de message REST. Remplacer par les informations d’identification de base : utilise l’option Activer l’authentification de base pour les informations d’identification SOAP sortantes afin de remplacer les informations d’identification dans la définition de message REST. Les informations d’identification d’authentification de base doivent être mises en service avant d’être disponibles à la sélection. Remplacer par certificat Informations d’identification d’authentification : utilise un certificat, tel qu’une clé privée, pour remplacer les informations d’identification dans la définition du message REST. Remplacer par les informations d’identification de base et par certificat : utilise à la fois l’authentification de base et l’authentification par certificat pour remplacer les informations d’identification dans la définition du message REST. Remplacer par les informations d’identification d’authentification OAuth : utilise les informations d’identification OAuth 2.0 pour remplacer les informations d’identification dans la définition du message REST. Le message REST sélectionné pour cette activité doit avoir son didacticiel OAuth 2.0 - créez un message REST défini sur OAuth 2.0 et ses profils et champs d’application OAuth configurés de manière appropriée.
   Informations d'identification	Point de terminaison REST requis : informations d’identification d’authentification de base. Ce champ est disponible lorsque Remplacer les informations d’identification de l’authentification de base est sélectionné dans le champ Authentification . Seules les informations d’identification d’authentification de base apparaissent dans la liste de sélection, qui comprend les informations d’identification stockées sur l’instance et les ID d’informations d’identification d’un système de stockage externe. Si vous utilisez des informations d’identification stockées dans un coffre-fort CyberArk, vous pouvez remplacer le coffre-fort par défaut défini dans le fichier de configuration du serveur MID. Pour plus d’informations, consultez Configurer le serveur MID pour CyberArk . Ajoutez le nom d’un autre coffre-fort comme préfixe à l’ID d’identifiant, séparé par deux points. Par exemple, newsafe:orch-test-f5.
   Profil du protocole	Authentification par certificat à utiliser. Ce champ est disponible lorsque les sélections dans l’authentification sont soit Remplacer par les informations d’identification d’authentification de certificat , soit Remplacer par les informations d’identification de base et d’authentification par certificat.
   Profil OAuth	Profil du fournisseur OAuth pour ce message REST. Consultez Spécifier un profil OAuth pour plus d’informations.

   Remarque :

   Vous pouvez mapper automatiquement les valeurs des paramètres d’une charge utile de test aux variables de l’onglet Sorties . Voir variables de sortie de mappage automatique.

Que faire ensuite

Terminez la création de votre activité de service Web Rest en créant des variables de sortie, une règle d’analyse ou desconditions. Reportez-vous à la rubrique Créer des activités personnalisées pour connaître les options de votre modèle.

Mapper automatiquement les variables de sortie d’activité REST

Le ServiceNow concepteur d’activité vous permet de mapper automatiquement les valeurs des paramètres d’une charge utile de test REST aux variables de l’étape Sorties .

Avant de commencer

Rôle requis : web_service_admin, activity_admin activity_creator

Pourquoi et quand exécuter cette tâche

Remarque :

Vous pouvez tester les variables d’entrée à n’importe quelle étape du concepteur d’activité si vous avez fourni suffisamment d’informations pour qu’Orchestration contacte le point de terminaison et renvoie les données. En règle générale, l’étape de commande d’exécution est le point auquel vos entrées sont prêtes pour le test.

Procédure

1. Dans le concepteur d’activité, passez à l’étape Commande d’exécution .
2. Définir un Serveur MID approprié, si demandé.
   Le test échoue si le serveur MID est introuvable ou s’il ne peut pas se connecter à la cible.
3. Cliquez sur Activité de test pour tester les paramètres d’entrée.
   Si vous avez ajouté des valeurs réelles pour les paramètres et les champs, le système exécute ces valeurs par rapport à la cible spécifiée et renvoie la charge utile résultante. Si vous avez mappé des variables d’entrée à des champs et des paramètres, le système affiche une boîte de dialogue permettant d’affecter des valeurs de test à ces variables.
4. Fournissez des valeurs de test, si demandé, et cliquez sur OK pour afficher la charge utile.
   L’ensemble de la charge utile apparaît dans l’onglet Sortie brute du formulaire de réponse.

   

5. Sélectionnez l’une de ces options de mappage automatique.
   • Mappage automatique vers local : mappe directement les valeurs à une variable locale à utiliser dans l’activité.
   • Mappage automatique vers la sortie : mappe directement les valeurs à la variable de sortie pour les transmettre à d’autres activités du workflow. Le mappage automatique à une variable de sortie crée un tableau d’objets, chacun contenant les noms de colonnes du résultat de la requête.

Paramètres d’exécution du modèle REST

Vous utilisez les paramètres d’exécution pour créer le script de processus d’entrée dans le formulaire Prétraitement du concepteur d’activité.

Pour obtenir des descriptions des champs de commande du service Web REST, reportez-vous à la section Configurer la commande d’exécution REST.

Remarque :

Vous devez utiliser le préfixe executionParam. avec toutes les variables de cette table.

Tableau 1. Paramètres d’exécution du modèle REST

Nom	Variable	Type	Utilisation
Message de service Web	web_service_message	Référence	La sys_id du message de service Web correspondant.
Fonction de message de service Web	web_service_message_function	Référence	Le sys_id de la fonction de message REST.
Point de terminaison de service Web	web_service_endpoint	Chaîne	URL du point de terminaison REST.
Paramètres	paramètres	Tableau d’objets JavaScript	Tableau d’objets JavaScript, exprimé avec le préfixe executionParam. Pour obtenir des instructions sur la création de tableaux à l’aide de ce paramètre, reportez-vous à la section Créer un tableau JavaScript dans un modèle REST.
Utiliser un Serveur MID	use_mid_server	Booléen	Indique s’il faut utiliser ou non le Serveur MID. Une valeur vrai utilise le serveur MID et une valeur faux n’utilise pas le serveur MID.
Capacités moyennes	midCapabilities	Chaîne (séparée par des virgules)	Liste de références aux options de Serveur MID requises.
Délai d'expiration atteint	arrêt de jeu	Chaîne	Durée du délai d’expiration autorisé, exprimé en secondes.
ValeurCapacités	valueCapabilities	Tableau de la carte de hachage	Valeurs d’aptitude utilisées pour sélectionner le Serveur MID. Pour plus d’informations, voir Aptitudes du serveur MID. Utilisez cet exemple pour personnaliser la sélection de Serveur MID si des options supplémentaires sont affectées par valeur : var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability);
Type d'authentification	Type d’authentification	Booléen	Type d’informations d’identification à utiliser. Les choix possibles sont les suivants : basic_auth_pick_credentials use_existing_credentials
Informations d'identification	informations d'identification	Référence	Contient les informations d’identification à utiliser pour ce message REST lorsque le auth_type sélectionné est basic_auth_pick_credentials.

Créer un tableau JavaScript dans un modèle REST

Il s’agit d’instructions pour créer des tableaux JavaScript à l’aide des paramètres d’exécution REST.

Avant de commencer

Rôle requis : web_service_admin, activity_admin activity_creator

Pourquoi et quand exécuter cette tâche

Pour ajouter d’autres paires nom-valeur au tableau du paramètre, ajoutez les valeurs au tableau existant.

Procédure

1. Créez un objet JavaScript avec la syntaxe suivante et ajoutez-le au tableau executionParam.parameter :

   var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; 
   executionParam.parameters.push(newParameter);

   En ajoutant le nouvel objet JavaScript paramètre au tableau, vous vous assurez que les éléments déjà disponibles dans le tableau ne sont pas affectés.

2. Assurez-vous de définir la valeur dans la colonne Attribut supplémentaire du champ d’entrée Paramètres du message REST sur Ne pas échapper de texte.

   Dans ce cas, le système n’échappe pas la valeur spécifiée pour l’attribut value . Par exemple :

   var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; 
   executionParam.parameters.push(newParameter);

   Remarque :

   Si la valeur du champ additional_attribute est Aucun, le système échappe la valeur spécifiée par l’attribut value . Dans le premier exemple, parameterValue est échappé.

Paramètres de post-traitement du modèle REST

Utilisez ces paramètres pour créer un script de post-traitement.

Tableau 2. Paramètres de post-traitement du concepteur d’activité

Nom	Variable	Type	Utilisation
Code d'état	status_code	Entier	Contient le code d’état renvoyé par le service Web REST.
En-tête	header	Hashmap de l’objet JavaScript	Carte de hachage des paires clé-valeur associées aux valeurs d’en-tête transmise au service Web. Vous pouvez accéder à chaque valeur à l’aide de executionResult.header[keyName].
Détails	body	Chaîne	Contient une valeur de chaîne représentant la sortie du message REST
Erreur	erreur	Chaîne	Renvoie la chaîne d’erreur du service Web REST, sauf s’il n’y a pas d’erreur, auquel cas renvoienull.

Configurer la commande d’exécution REST

Utilisez les variables d’entrée que vous avez créées pour configurer la commande qu’Orchestration exécute sur le point de terminaison REST.

Avant de commencer

Créez les variables d’entrée dont vous avez besoin dans le formulaire Entrées avant de pouvoir passer à l’étape de commande d’exécution .

Rôle requis : web_service_admin, activity_admin activity_creator

Remarque :

Vous pouvez tester la connexion REST entre le serveur MID et le point de terminaison sans avoir à exécuter l’activité dans un contexte de workflow. Pour plus d’informations, consultez Sorties de modèles de tests.

Procédure

1. Faites glisser les variables de la liste des entrées et déposez-les dans les champs de commande.
   Le système formate la variable dans la syntaxe appropriée pour la commande.

   Figure 1. Commande d’exécution REST

   

2. Renseignez les champs indiqués dans la table.

   Tableau 3. Champs de commandes d’exécution REST

   Champ	Description
   Entrée	Générateur de variables d’entrée. Créer des variables d’entrée pour mapper aux champs disponibles.
   Message REST	Nom d’un message REST existant à utiliser dans cette activité. Les utilisateurs doivent disposer du rôle web_service_admin pour configurer ce champ.
   Fonction de message REST	Fonction de message REST à utiliser pour cette activité. Les utilisateurs doivent disposer du rôle web_service_admin pour configurer ce champ.
   Point de terminaison	URL du point de terminaison pour le service Web REST que cette activité utilise. Entrez un point de terminaison dans ce champ pour remplacer le point de terminaison configuré dans le message REST. Cliquez sur le verrou pour ouvrir le champ d’entrée.
   Substitutions de variables	Paires nom-valeur à transmettre au point de terminaison REST. Vous pouvez créer ces paramètres manuellement ou glisser-déplacer des variables d’entrée dans les champs de paramètres, puis affecter une valeur. Les paramètres définis dans le message REST qui utilisent ${} peuvent être des données affectées à partir de ce modèle d’activité. Utilisez la colonne Attribut supplémentaire pour configurer le système afin qu’il ne soit pas soumis à une séquence d’échappement du texte. Par défaut, le texte envoyé au message REST est échappé. La colonne Nom est automatiquement renseignée si les utilisateurs ont fourni des variables à l’aide de la substitution de variables dans les messages REST sortants dans le message REST.
   En-têtes supplémentaires	Paramètres d’en-tête HTTP supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
   Paramètres de requêtes supplémentaires	Paramètres de requête supplémentaires pour le message REST sélectionné. Vous pouvez également utiliser ces valeurs pour remplacer les paramètres hérités du message REST.
   Utiliser un serveur MID	Case à cocher qui détermine si un serveur MID doit être utilisé pour appeler le service Web REST. Remarque : Si la fonction de message de service Web REST définit un serveur MID, ce serveur MID est utilisé à la place de celui sélectionné ici.
   Capacités de Serveur MID requises	Serveur MID avec les options de Serveur MID appropriées pour la connexion au point de terminaison REST. Par défaut, le système sélectionne un serveur MID avec les options REST. Ce champ est disponible lorsque la case Utiliser Serveur MID est cochée.
   Délai	Durée autorisée de la demande de service Web REST avant l’expiration de celle-ci, en secondes. La valeur par défaut est 10.
   Authentification	Détermine le type d’authentification requis pour le point de terminaison. Les options sont les suivantes : Utiliser les informations d’identification existantes dans le message REST : utilise les définitions d’informations d’identification de la définition de message REST. Remplacer par les informations d’identification de base : utilise l’option Activer l’authentification de base pour les informations d’identification SOAP sortantes afin de remplacer les informations d’identification dans la définition de message REST. Les informations d’identification d’authentification de base doivent être mises en service avant d’être disponibles à la sélection. Remplacer par certificat Informations d’identification d’authentification : utilise un certificat, tel qu’une clé privée, pour remplacer les informations d’identification dans la définition du message REST. Remplacer par les informations d’identification de base et par certificat : utilise à la fois l’authentification de base et l’authentification par certificat pour remplacer les informations d’identification dans la définition du message REST. Remplacer par les informations d’identification d’authentification OAuth : utilise les informations d’identification OAuth 2.0 pour remplacer les informations d’identification dans la définition du message REST. Le message REST sélectionné pour cette activité doit avoir son didacticiel OAuth 2.0 - créez un message REST défini sur OAuth 2.0 et ses profils et champs d’application OAuth configurés de manière appropriée.
   Informations d'identification	Point de terminaison REST requis : informations d’identification d’authentification de base. Ce champ est disponible lorsque Remplacer les informations d’identification de l’authentification de base est sélectionné dans le champ Authentification . Seules les informations d’identification d’authentification de base apparaissent dans la liste de sélection, qui comprend les informations d’identification stockées sur l’instance et les ID d’informations d’identification d’un système de stockage externe. Si vous utilisez des informations d’identification stockées dans un coffre-fort CyberArk, vous pouvez remplacer la valeur Configurer le serveur MID pour CyberArk définie dans le fichier de configuration du serveur MID en ajoutant le nom d’un autre coffre-fort comme préfixe à l’ID d’informations d’identification, séparé par deux points. Par exemple, newsafe:orch-test-f5.
   Profil du protocole	Authentification par certificat à utiliser. Ce champ est disponible lorsque les sélections dans le champ Authentification sont soit Remplacer par les informations d’identification de l’authentification de certificat , soit Remplacer par les informations d’identification de base et de certificat.
   Profil OAuth	Profil du fournisseur OAuth pour ce message REST. Consultez Spécifier un profil OAuth pour plus d’informations.

3. Cliquez sur Enregistrer.
4. Cliquez sur Continuer pour passer à l’étape Sorties .