Créer une activité de service Web REST

Cette procédure permet de 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 REST si aucun message approprié n’est 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 défini 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 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 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 de saisie.
   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 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, c’est ce serveur MID qui est utilisé à la place de celui sélectionné ici.
   Options de Serveur MID requises	Serveur MID avec les options de Serveur MID appropriées pour se connecter au point de terminaison REST. Par défaut, le système sélectionne un Serveur MID avec des options REST. Ce champ est disponible lorsque la case Utiliser un 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 du message REST. Remplacer par les informations d’identification de l’authentification de base : utilise l’option Activer l’authentification de base des informations d’identification SOAP sortantes pour remplacer les informations d’identification dans la définition du message REST. Les informations d’identification d’authentification de base doivent être mises en service avant d’être disponibles à la sélection. Remplacer par les informations d’identification de l’authentification par certificat : 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 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 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 didacticiel OAuth 2.0 - créez un message REST défini sur OAuth 2.0 et ses profils et champs d’application OAuth doivent être configurés correctement.
   Informations d'identification	Informations d’identification d’authentification de base de point de terminaison REST requises. Ce champ est disponible lorsque l’option Remplacer par les informations d’identification 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 comprend 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 Serveur MID pour CyberArk . Ajoutez le nom d’un autre coffre-fort en 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 l’authentification sont soit Remplacer par les informations d’identification de l’authentification par 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. Pour plus d’informations, reportez-vous à la section Spécifier un profil OAuth .

   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, en créant 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 des 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 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 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 les compare à la cible spécifiée et renvoie la charge utile qui en résulte. 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 s’affiche dans l’onglet Sortie brute du formulaire de réponse.

   

5. Sélectionnez l’une de ces options de mappage automatique.
   • Mapper automatiquement au local : mappe directement les valeurs à une variable locale pour une utilisation dans l’activité.
   • Correspondance automatique avec 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 commandes de services 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	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 Serveur MID. Une valeur vrai utilise le serveur MID et une valeur faux n’utilise pas le serveur MID.
Capacités MID	Capacités MID	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 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 serveur MID. Pour plus d’informations, consultez Options de 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	credentials	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 de 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 de la colonne Attribut supplémentaire dans le champ d’entrée des paramètres de message REST sur Ne pas échapper le texte.

   Dans ce cas, le système n’échappe pas la valeur spécifiée pour l’attribut de valeur . En 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 de valeur . 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 clé-valeur associées aux valeurs d’en-tête transmises dans le service Web. Vous pouvez accéder à chaque valeur avec executionResult.header[keyName].
Corps	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 à partir 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 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 serveur MID et le point de terminaison sans avoir à exécuter l’événement dans un contexte de workflow. Pour plus d’informations, consultez les sorties des modèles 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 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 de saisie.
   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 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 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, c’est ce serveur MID qui est utilisé à la place de celui sélectionné ici.
   Options de Serveur MID requises	Serveur MID avec les options de Serveur MID appropriées pour se connecter au point de terminaison REST. Par défaut, le système sélectionne un Serveur MID avec des options REST. Ce champ est disponible lorsque la case Utiliser un 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 du message REST. Remplacer par les informations d’identification de l’authentification de base : utilise l’option Activer l’authentification de base des informations d’identification SOAP sortantes pour remplacer les informations d’identification dans la définition du message REST. Les informations d’identification d’authentification de base doivent être mises en service avant d’être disponibles à la sélection. Remplacer par les informations d’identification de l’authentification par certificat : 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 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 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 didacticiel OAuth 2.0 - créez un message REST défini sur OAuth 2.0 et ses profils et champs d’application OAuth doivent être configurés correctement.
   Informations d'identification	Informations d’identification d’authentification de base de point de terminaison REST requises. Ce champ est disponible lorsque l’option Remplacer par les informations d’identification 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 comprend 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 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 le champ Authentification sont soit Remplacer par les informations d’identification d’authentification de certificat , soit Remplacer par les informations d’identification d’authentification de base et de certificat.
   Profil OAuth	Profil du fournisseur OAuth pour ce message REST. Pour plus d’informations, reportez-vous à la section Spécifier un profil OAuth .

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