Créer une action de flux de données

Rversion finale: Xanadu

Mis à jour 1 août 2024

11 minutes de lecture

Créez une action réutilisable pour traiter un flux de données de réponse dans un flux.

Avant de commencer

Configurez une application dans Création d’apps guidée pour stocker Studio de workflow du contenu.
Désactivez tout conflit de règles métier ou de workflows avant de créer une action.
Rôle requis : action_designer ou admin

Pourquoi et quand exécuter cette tâche

La création d’une application personnalisée pour contenir votre Studio de workflow contenu vous permet de le déployer à l’aide du référentiel d’applications ou du ServiceNow Storefichier .

Remarque :

La désactivation d'une option dans une page de configuration supprime l'étape du plan Flux de données ainsi que toutes les données associées à l'étape.

Procédure

Accédez à la Tout > Concepteur de flux > Concepteur.
Cliquez sur l’onglet Actions et sélectionnez Flux de données.

Renseignez les propriétés de l’action et cliquez sur Soumettre.


Champ	Description
Nom de l'action	Saisissez un nom unique pour votre action de flux de données.
Description	Description de l’action de flux de données.
Application	Périmètre d’application de l’action de flux de données.
Domaine	Champ d’application de domaine de l’action de flux de données. Pour plus d’informations sur Séparation de domaine, reportez-vous à la section Domain separation explained.
Propriétés supplémentaires
Accessible depuis	Accessible à partir de toutes les applications incluses dans le périmètre ou uniquement dans le périmètre de l’application spécifié.
Catégorie	Catégorie définie dans le périmètre de l’application pour une action. À partir de la Xanadu mise en production, vous pouvez créer une catégorie personnalisée pour organiser vos actions de flux de données.
Protection	Indiquez si l’action de flux de données est en lecture seule. Vous ne pouvez sélectionner une valeur que lorsque vous créez l’action de flux de données dans un périmètre de l’application que vous possédez. La valeur par défaut est Aucun.
Annotation sur l'action	Texte d’aide qui s’affiche sous le titre de l’action de flux de données dans pour aider les auteurs d’actions de flux de données à Studio de workflow comprendre ce que fait l’action de flux de données lorsqu’elle est utilisée dans un flux.

Une action vide Flux de données s’ouvre.

Définissez des entrées d’action pour rendre les données disponibles aux étapes d’action.
1. Sélectionnez + Créer une entrée et renseignez les champs.
  Les entrées sont représentées sous forme de pastilles de données dans le volet droit.
Pour plus d’informations sur les entrées d’action, consultez Studio de workflow - Création d’actions personnalisées.
Cliquez sur Prétraitement de l’action dans le Flux de données plan et configurez les options souhaitées.
1. Sélectionnez Récupérer les informations de connexion pour ajouter l’étape Obtenir des informations de connexion comme première étape dans le prétraitement de l’action.
  L’étape Obtenir des informations sur la connexion vous permet de récupérer les informations de connexion et d’identification à utiliser dans votre action. Pour plus d'informations, consultez Get Connection Info step.
2. Sélectionnez Activer le script de prétraitement à exécuterun script de prétraitement avant que l'action n'envoie la demande d'API initiale. Par exemple, validez les entrées d'action ou définissez les valeurs par défaut. Le prétraitement s'exécute une fois par action, avant la première demande d'API.
  
  La sélection de cette option ajoute une étape de script à l'action Flux de données. Pour plus d'informations, consultez Script step.
  
  Important :
  Les actions du flux de données nécessitent une connexion constante au flux de réponse. Ils ne prennent pas en charge les scripts de prétraitement qui mettent en pause l’action pour appeler ou Serveur MID mettre en pause l’action pour attendre une condition ou une durée. Un script de prétraitement qui interrompt l’action pour une raison quelconque renvoie un message d’erreur.
Cliquez sur Demander dans le Flux de données plan et configurez les options souhaitées.
1. Dans le champ Comment obtiendrez-vous des données , sélectionnez Étape REST, Étape SOAP ou Étape JDBC pour ajouter l’étape associée à l’action Flux de données .
  Pour plus d’informations, reportez-vous aux sections Étape REST, Étape SOAPet Étape JDBC .
  
  Cette section peut s’exécuter sur l’instance ou sur Serveur MID l’instance. L’environnement est déterminé par le champ Utiliser un MID Server dans l’enregistrement de connexion [sys_connection] associé.
  Remarque :
  Si vous utilisez l’étape JDBC, vous devez la tester. Une fois l’exécution réussie, vous pouvez utiliser le résultat pour créer la sortie d’étape et la sortie d’action de flux de données.
  
  Si vous utilisez l’étape REST ou l’étape SOAP, vous devez créer manuellement la sortie de l’action de flux de données.
2. Sélectionnez Activer la pagination pour demander entraîne des lots. Une fois que la page de données est traitée, l'action Flux de données réexécute la section de demande pour retourner le jeu suivant de résultats. Cette option ajoute une étape de configuration de la Flux de données pagination au plan.
  
  Remarque :
  Pour une étape JDBC, la pagination n’est pas applicable. Chaque page peut récupérer jusqu’à 1 Go de données et une demande peut récupérer jusqu’à 8 Go de données.
3. Sélectionnez Exécuter un script avant chaque requête pour exécuter un script avant chaque demande pour la page suivante lors de l’appel d’une API paginée.
  Par exemple, écrivez un script pour transformer les types de données de variables de la réponse initiale avant d’envoyer une demande pour la page suivante.
  
  La sélection de cette option ajoute une étape de script à l'action Flux de données. Pour plus d'informations, consultez Script step.
  
  Remarque :
  Pour une étape JDBC, cela n’est pas applicable.
  
  Cette section peut s'exécuter sur le Serveur MID ou l'instance. L'environnement est déterminé par le champ Exécution obligatoire de l'étape de script.
  
  Important :
  évitez de déplacer plusieurs fois l'environnement d'exécution entre l'instance et le Serveur MID. Par exemple, vous pouvez configurer l'étape de script de demande à exécuter sur le Serveur MID, mais l'étape REST à exécuter sur l'instance. Dans ce cas, le système déplace les environnements entre l'instance et Serveur MID pour chaque page de données, ce qui peut dégrader les performances.
Facultatif : Si la pagination est activée, configurez l’étape de configuration de la pagination.
Configurez manuellement l’étape de configuration de la pagination ou sélectionnez un modèle prédéfini pour appliquer des configurations courantes. Par exemple, appliquez le modèle Limite/décalage pour spécifier le nombre d'éléments que vous souhaitez retourner par page (limite), ainsi que le numéro de départ du premier élément (décalage). Après l'application d'un modèle, mettez à jour les valeurs pour vous assurer que la configuration est conforme aux exigences de l'API.
1. Créer des variables de pagination.
  Par exemple, si l’API tierce prend un paramètre limit dans la demande, créez la variable limit et définissez la valeur initiale pour limiter le nombre de résultats par page. La valeur initiale n’est utilisée que dans la première demande. getNextPage est une variable réservée en lecture seule. Tant que la variable getNextPage est définie sur vrai et que la page précédente contient des données, l'action continue d'envoyer des demandes pour la page suivante.
2. Dans le champ Valeur suivante de , définissez comment les variables de pagination reçoivent une valeur pour les demandes suivantes.
  Choisissez entre :
  - Script : écrivez un script de variables de pagination pour définir la façon dont les variables sont renseignées. Les variables de pagination prennent uniquement en charge les données de type chaîne. Pour effectuer des opérations mathématiques, vous devez convertir la valeur en nombre entier, effectuer toutes les opérations requises, puis la convertir en chaîne.
  - Corps de la réponse : utilisez une valeur dans la réponse de la demande précédente pour remplir la variable. Si la réponse est au format JSON, définissez Extraire la valeur à l’aide de l’expression JSONPath et indiquez le chemin d’accès à la valeur dans le champ Expression . Si la réponse est au format XML, définissez Extraire la valeur à l’aide de XPath Expression et indiquez le chemin d’accès à la valeur.
Dans cet exemple, la variable getNextPage est vraie jusqu’à ce que la variable nextOffset atteigne la valeur de nombre total renvoyée dans l’en-tête de réponse API. Tant que la variable getNextPage est définie sur vrai et que la page précédente contient des données, l'action continue d'envoyer des demandes pour la page suivante. Cet exemple inclut une configuration courante de pagination de limite/décalage. Les API tierces avec lesquelles interagit votre Flux de données action peuvent utiliser un jeton de page ou une autre méthode.

Important :
Évitez les boucles infinies dans les demandes de pagination en créant une condition qui définit la variable getNextPage sur faux. Annulez tous les flux en cours d'exécution. Testez toujours les actions Flux de données avant de les utiliser en production.
Cliquez sur Analyse dans le Flux de données plan et configurez les options souhaitées.

Remarque :
Pour une étape JDBC, cela n’est pas applicable.
1. Dans le champ Comment identifierez-vous chaque enregistrement , sélectionnez Séparateur JSON/XML pour ajouter une étape de séparation au Flux de données plan.
2. Dans le champ Comment allez-vous analyser chaque élément en un objet , sélectionnez Analyseur de script pour ajouter une étape Analyseur de script au Flux de données plan.
Configurez l’étape de séparation.

Cette étape identifie le nœud parent dans le flux de réponse à mapper à un objet complexe. Par exemple, identifiez un élément utilisateur dans une charge utile XML pour créer un objet complexe pour chaque utilisateur dans le flux de réponse.

Remarque :
Pour une étape JDBC, cela n’est pas applicable.
1. Dans le champ Format source , sélectionnez le format renvoyé par la section Demande.
  - JSON : identifie les objets d'un flux de données JSON. Utilisez une expression JSONPath pour identifier un tableau JSON contenant des données répétées.
  - XML : identifie les objets à partir d'un flux de données XML. Utilisez une expression XPath pour identifier un élément XML contenant des données répétées.
2. Dans le champ Chemin d’accès de l’élément , définissez le chemin d’accès absolu à l’élément dans le flux de données que vous souhaitez mapper à un objet.
  
  JSON
  
  Identifiez le chemin d’accès absolu à un tableau d’objets sous la forme d’une expression JSONPath. Par exemple, utilisez $.result pour séparer chaque élément d’un tableau de résultats JSON en un objet de résultat .
  Remarque :
  Si vous sélectionnez un tableau au niveau du nœud racine d’un flux de données JSON, le système affiche le chemin d’accès absolu sous la forme $.* dans les détails de l’exécution et les messages d’erreur.
  
  XML
  
  Identifiez le chemin absolu vers un objet de données répétitif sous la forme d’une expression XPath. Par exemple, utilisez /result pour séparer chaque instance d’un élément XML de résultat en un objet de résultat .
  Remarque :
  L’étape de séparation ignore les espaces de noms XML.
  Par exemple, supposons que l’étape REST renvoie un flux de données JSON. Le chemin d’accès de l’élément $.response.result.companies renvoie chaque élément du tableau des entreprises .
```
{
  "response": {
    "result": {
      "companies": [
        {
          "name": "company1"
        },
        {
          "name": "company2"
        },
        {
          "name": "company3"
        }
      ],
      "metadata": {
        "token": 1558666526
      }
    }
  }
} 
```
  Par exemple, supposons que l’étape REST renvoie un flux de données XML. Le chemin d’accès de l’élément /réponse/result/entreprises/société renvoie chaque élément de l’entreprise à partir des données XML.
```
<response>
  <result>
    <companies>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <batch>10645C53D4BED73YQ</batch> 
    </companies>
    <metadata>
      <timestamp>1558666526</timestamp>
    </metadata>
  </result>
</response>
```
Dans l’étape de l’analyseur de script, utilisez JavaScript et ServiceNow les API pour mapper les éléments du flux de réponse à une sortie d’objet complexe représentée par l’objet global targetObject .
Par exemple, mappez les éléments d'enregistrement d'incident identifiés à l'étape de séparation à un objet complexe contenant des champs d'incident. Si le flux de données inclut des frères et sœurs de l'élément identifié dans l'étape de séparation que vous ne souhaitez pas mapper à un objet complexe, incluez des conditions pour exclure ces éléments.

Remarque :
Pour une étape JDBC, cela n’est pas applicable.
Vous pouvez accéder aux sorties des étapes précédentes de votre action de flux de données à l’aide de l’objet fd_data , à l’exclusion de :
- Étape REST ou SOAP Corps de la réponse, Flux ou Message d’erreur.
- Sorties de l’étape de séparation.
Exemple de script qui analyse une réponse JSON.
```
(function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.id=record.number;
    outputs.targetObject.name=record.short_description;
})(inputs, outputs)
```
Exemple de script qui analyse une réponse XML.
```
(function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.id = xmlDoc.getNodeText("/result/number");
    outputs.targetObject.name = xmlDoc.getNodeText("/result/short_description");
})(inputs, outputs)
```
Facultatif : Si vous avez sélectionné l’étape JDBC, cliquez sur Transformer.
Après avoir testé avec succès l’étape JDBC, cliquez sur Utiliser le résultat pour créer la sortie de l’étape et la sortie de l’action de flux de données. Vous pouvez utiliser ce résultat ou le personnaliser à l’aide du script de transformation.
1. Cochez la case Activer le script de transformation pour transformer et personnaliser la sortie de flux de données par défaut.
Créez une sortie d’objet complexe.

Remarque :
Pour une étape JDBC, cela n’est pas applicable.
1. Sélectionnez Sorties dans Plan d’action et cliquez sur + pour créer une sortie.
2. Mettez à jour le champ Étiquette pour représenter l’objet.
  Par exemple, si l’action analyse un flux d’enregistrements de société, ajoutez l’étiquette de société .
3. Mettez à jour le champ Type sur Objet.
  Il s’agit de la sortie d’objet complexe représentée par l’objet global targetObject à l’étape de l’analyseur de script.
4. Ajoutez des champs enfants à l’objet complexe à l’aide de l’icône + .
5. Rendez le nom de chaque champ enfant plus convivial afin de pouvoir y faire référence de manière significative dans le script.
  
  La valeur du champ Nom est le nom interne utilisé dans l’étape de l’analyseur de script. Par exemple, pour faire référence à la sortie City dans l’étape de l’analyseur de script, vous devez utiliser outputs.targetObject.city.
  
  Avertissement :
  Une fois l’action enregistrée, vous ne pouvez pas modifier les Flux de données valeurs du champ Nom .
Cliquez sur Enregistrer.
Studio de workflow Enregistre un brouillon de l’action.

Que faire ensuite

Tester une Flux de données action.