Créer une action de flux de données

Washington DC : créer des intégrations pour les applications

Release

washingtondc

ft:locale

fr-FR

ft:publication_title

Washington DC : créer des intégrations pour les applications

ft:clusterId

crint

bundleId

crint

workflow

Creator

Créer une action de flux de données

Rversion finale: Washingtondc

Mis à jour 1 févr. 2024

10 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éateur intuitif d’application pour stocker Concepteur de flux 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 Concepteur de flux contenu vous permet de le 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 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	Nom de l’action.
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.
Description	Description de l'action.
Protection	Indiquez si l’action est en lecture seule. Vous ne pouvez sélectionner une valeur que lorsque l’action se trouve dans un périmètre de l’application que vous possédez. La valeur par défaut est Aucun.
Application	Champ d’application de l’action.
Annotation dans le flux	Texte qui s’affiche sous le titre de l’action pour aider les concepteurs de flux à Concepteur de flux comprendre ce que l’action fait 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 pour les étapes d’action.
1. Sélectionnez + Créer une entrée et remplissez 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 Concepteur d'action - 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 du 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électionnez Activer le script de prétraitement à exécuter un 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 Serveur MID . 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 d’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 requête 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 communes. 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 de limite dans la demande, créez la variable de limite 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 commune 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.

Dans le script de pagination, l’objet pageResponse contient le response_headers, le response_body et un code d’état.

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 analyserez-vous chaque élément dans 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 du 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 niveau du nœud racine d’un flux de données JSON, le système affiche le chemin absolu sous la forme $.* dans les détails d’exécution et les messages d’erreur.
  
  XML
  
  Identifiez le chemin d’accès absolu vers 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 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 sociétés .
```
{
  "response": {
    "result": {
      "companies": [
        {
          "name": "company1"
        },
        {
          "name": "company2"
        },
        {
          "name": "company3"
        }
      ],
      "metadata": {
        "token": 1558666526
      }
    }
  }
} 
```
  Supposons, par exemple, que l’étape REST renvoie un flux de données XML. Le chemin d’accès de l’élément /réponse/résultat/sociétés/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 des API pour mapper des é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 des éléments suivants :
- Étape REST ou SOAP Corps de la réponse, Flux ou Message d’erreur.
- Sorties de l’étape de séparation.
Exemple de script analysant 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 analysant 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 les 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 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 dans 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 Ville dans l’étape de l’analyseur de script, vous utiliseriez outputs.targetObject.city.
  
  Avertissement :
  Après avoir enregistré l’action, vous ne pouvez pas modifier les Flux de données valeurs du champ Nom .
Cliquez sur Enregistrer.
Concepteur d'action Enregistre un brouillon de l’action.

Que faire ensuite

Tester une Flux de données action.