Créer une action de flux de données

Rversion finale: Zurich

Mis à jour 31 juil. 2025

11 minutes de lecture

Créez une action réutilisable pour traiter un flux de données de réponse au sein d’un flux.

Avant de commencer

Configurez une application dans Guided Application Creator pour stocker Studio de workflow du contenu.
Désactivez toutes les règles métier ou tous les workflows conflictuels 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 la déployer à l’aide du référentiel d’applications ou du .ServiceNow Store

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 Tous > 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 de l’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 la séparation en domaines, 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 de l’application 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 version, 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 Studio de workflow pour aider les auteurs d’actions de flux de données à 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, voir 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 détails de connexion et d’informations d’identification à utiliser dans votre action. Pour plus d'informations, consultez Get Connection Info step.
2. Sélectionner Activer l’exécution du script de prétraitementun 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 interrompent l’action pour appeler ou Serveur MID interrompent l’action pour attendre une condition ou une durée. Un script de prétraitement qui met l’action en pause 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 à Étape REST, Étape SOAP et Étape JDBC .
  
  Cette section peut s’exécuter sur le Serveur MID ou sur l’instance. L’environnement est déterminé par le champ Utiliser un Serveur MID 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 demande 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 à partir 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 :
  Cela ne s’applique pas à une étape JDBC.
  
  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 l’étape de configuration de la pagination manuellement ou sélectionnez un modèle prédéfini auquel 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 utilise 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 la façon dont les variables de pagination reçoivent une valeur pour les demandes suivantes.
  Choisissez entre :
  - Script : écrire des variables de pagination Script pour définir le mode de remplissage des variables. 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 sur 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 deXPath Expression et indiquez le chemin d’accès à la valeur.
Dans cet exemple, la variable getNextPage est true 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 commune de pagination limite/décalage. Les API tierces avec lesquelles votre Flux de données action interagit 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 :
Cela ne s’applique pas à une étape JDBC.
1. Dans le champ Comment allez-vous identifier chaque enregistrement ? Sélectionnez Séparateur JSON/XML pour ajouter une étape de Flux de données séparation au plan.
2. Dans le champ Comment analyser chaque élément dans un objet , sélectionnez Analyseur de script pour ajouter une étape d’analyseur Flux de données de script au 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 :
Cela ne s’applique pas à une étape JDBC.
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 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 en tant qu’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 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 d’exécution et les messages d’erreur.
  
  XML
  
  Identifiez le chemin d’accès absolu à un objet de données répétitif en tant qu’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 retourne 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 /response/result/companies/company renvoie chaque élément de company à 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 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 :
Cela ne s’applique pas à une étape JDBC.
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 Sorties de 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 du flux de données par défaut.
Créez une sortie d’objet complexe.

Remarque :
Cela ne s’applique pas à une étape JDBC.
1. Sélectionnez Sorties dans le 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 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 vous y référer de manière significative dans le script.
  
  La valeur du champ Nom est le nom interne utilisé à l’étape Analyseur de script. Par exemple, pour faire référence à la sortie Ville dans l’étape Analyseur de script, vous pouvez utiliser outputs.targetObject.city.
  
  Avertissement :
  Après avoir enregistré l’action, vous ne pouvez plus 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.