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éez un message Créez un message REST si un message approprié n’est pas déjà configuré.
• Affectez le rôle web_service_admin à n’importe quel utilisateur qui doit 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
   Mappez les variables d’entrée	Utilisez les variables que vous avez créées pour configurer la commande exécutée par 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 utilisé par cette activité. 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 les variables d’entrée dans les champs de paramètres, puis affecter une valeur. Les données des paramètres définis dans le message REST qui utilisent ${} peuvent être affectées à partir de ce modèle d’activité. Utilisez la colonne Attribut supplémentaire pour configurer le système afin qu’il n’échappe pas le 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 variable dans les messages REST sortants du 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 MID Server doit être utilisé pour appeler le service Web REST. Remarque : Si la fonction de message de service Web REST définit un MID Server, ce MID Server est utilisé à la place de celui sélectionné ici.
   Options requises de Serveur MID	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 MID Server avec des 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 son expiration, 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 d’authentification de base : utilise Activez 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 pour la sélection. Remplacer par les informations d’identification d’authentification de certificat : utilise un certificat, tel qu’une clé privée, pour remplacer les informations d’identification dans la définition de message REST. Remplacer par les informations d’identification d’authentification 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 de 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 de message REST. Le didacticiel OAuth 2.0 - créer un message REST doit être défini sur OAuth 2.0 et ses profils et périmètres OAuth doivent être configurés de manière appropriée.
   Informations d'identification	Informations d’authentification de base de point de terminaison REST requises. Ce champ est disponible lorsque l’option Remplacer par les informations d’identification d’authentification de base est sélectionnée dans le champ Authentification . Seules les informations d’identification d’authentification de base apparaissent dans la liste de sélection, qui inclut les informations d’identification stockées sur l’instance et les ID d’informations d’identification provenant 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 MID Server. Pour plus d’informations, consultez Configurer le MID Server pour CyberArk . Ajoutez 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 de 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. Reportez-vous à la section 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 . Reportez-vous à la section 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 à des 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 à partir de n’importe quelle étape dans le 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 Commande d’exécution est le point où 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 MID Server approprié, si demandé.
   Le test échoue si le MID Server est introuvable ou s’il ne peut pas se connecter à la cible.
3. Cliquez sur Tester l’activité 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é, puis 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.
   • Mapper automatiquement vers local : mappe directement les valeurs à une variable locale à utiliser dans l’activité.
   • Mapper automatiquement à 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 des 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 de 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	sys_id du message du service Web correspondant.
Fonction de message de service Web	web_service_message_function	Référence	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 MID Server	use_mid_server	Booléen	Sélectionne s’il faut utiliser ou non le MID Server. Une valeur vrai utilise le MID Server et une valeur false n’utilise pas le MID Server.
Capacités MID	Fonctionnalités MID	Chaîne (séparée par des virgules)	Liste de références aux options de MID Server requises.
Délai d'expiration atteint	Délai d’expiration	Chaîne	Durée autorisée du délai d’expiration, exprimée en secondes.
Options de valeur	valueCapabilities (en anglais seulement)	Tableau de la carte de hachage	Valeurs d’aptitude utilisées pour sélectionner le MID Server. Pour plus d’informations, consultez Options du MID Server. Utilisez cet exemple pour personnaliser la sélection du MID Server en cas d’options supplémentaires 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	credentials	Référence	Contient les informations d’identification à utiliser pour ce message REST lorsque la auth_type sélectionnée 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 de paramètre au tableau, vous vous assurez que les éléments déjà disponibles dans le tableau ne sont pas impactés.

2. Veillez à définir la valeur de la colonne Attribut supplémentaire dans le champ d’entrée des paramètres de message REST sur Texte Ne pas échapper.

   Dans ce cas, le système n’échappe pas la valeur spécifiée pour l’attribut value . Voici un 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	Carte de hachage de l’objet JavaScript	Carte de hachage des paires de valeurs clés associées aux valeurs d’en-tête transmises au service Web. Vous pouvez accéder à chaque valeur avec 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 la valeurNull est renvoyée.

Configurer la commande d’exécution REST

Utilisez les variables d’entrée que vous avez créées pour configurer la commande exécutée par Orchestration 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 Commande d’exécution .

Rôle requis : web_service_admin, activity_admin activity_creator

Remarque :

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

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 affichés dans la table.

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

   Champ	Description
   Entrée	Générateur de variable 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 avoir le rôle web_service_admin pour configurer ce champ.
   Fonction de message REST	Fonction de message REST à utiliser pour cette activité. Les utilisateurs doivent avoir le rôle web_service_admin pour configurer ce champ.
   Point de terminaison	URL du point de terminaison pour le service Web REST utilisé par cette activité. 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 données des paramètres définis dans le message REST qui utilisent ${} peuvent être affectées à partir de ce modèle d’activité. Utilisez la colonne Attribut supplémentaire pour configurer le système afin qu’il n’échappe pas le 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 fonction Substitution de variable dans les messages REST sortants du 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 MID Server doit être utilisé pour appeler le service Web REST. Remarque : Si la fonction de message de service Web REST définit un MID Server, ce MID Server est utilisé à la place de celui sélectionné ici.
   Options requises de Serveur MID	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 MID Server avec des 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 son expiration, 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 d’authentification de base : utilise Activez 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 pour la sélection. Remplacer par les informations d’identification d’authentification de certificat : utilise un certificat, tel qu’une clé privée, pour remplacer les informations d’identification dans la définition de message REST. Remplacer par les informations d’identification d’authentification 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 de 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 de message REST. Le didacticiel OAuth 2.0 - créer un message REST doit être défini sur OAuth 2.0 et ses profils et périmètres OAuth doivent être configurés de manière appropriée.
   Informations d'identification	Informations d’authentification de base de point de terminaison REST requises. Ce champ est disponible lorsque l’option Remplacer par les informations d’identification d’authentification de base est sélectionnée dans le champ Authentification . Seules les informations d’identification d’authentification de base apparaissent dans la liste de sélection, qui inclut les informations d’identification stockées sur l’instance et les ID d’informations d’identification provenant d’un système de stockage externe. Si vous utilisez des informations d’identification stockées dans un coffre-fort CyberArk, vous pouvez remplacer l’option Configurer le MID Server pour CyberArk définie dans le fichier de configuration du MID Server en ajoutant le nom d’un autre coffre-fort en tant que préfixe de l’ID d’informations d’identification, séparé par un deux-points. Par exemple, newsafe:orch-test-f5.
   Profil du protocole	Authentification de certificat à utiliser. Ce champ est disponible lorsque les sélections dans le champ 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. Reportez-vous à la section Spécifier un profil OAuth pour plus d’informations.

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