Ajout de lookups
Les lookups sont des mécanismes en lecture seule qui interrogent le service pour obtenir une liste de valeurs présentées ensuite sous forme de liste déroulante. Les lookups peuvent être basés sur d'autres éléments d'informations déjà fournis sur le formulaire. Leur utilisation vous évite d'avoir à saisir manuellement ou à mémoriser les valeurs associées à vos ressources de compte tiers lors de la configuration d'une action ou d'un déclencheur.
Utilisez des lookups dans des actions et des déclencheurs. Pour afficher un grand nombre d'éléments, les lookups utilisent un mécanisme de pagination.
Les lookups prennent en charge le filtrage initial des données. Par exemple, lorsque vous saisissez du texte dans le champ de lookup et que vous cliquez ensuite sur la flèche, une liste de valeurs contenant le texte saisi apparaît.
Contrairement aux autres artefacts, les lookups ne font pas l'objet d'un versionnage externe. Chaque appel de lookup est une fonction dans l'artefact de lookup. Par conséquent, il ne peut y avoir qu'un seul artefact de lookup par connecteur.
Par exemple, la figure qui suit illustre une action de lookup. Le lookup récupère le courrier électronique de l'utilisateur dans Gmail et les valeurs s'affichent dans le champ ID message en tant qu'entrée. Cette opération est possible car le schéma spécifie qu'un lookup peut être utilisé pour ce champ.
Pour implémenter l'action get-mail-details, vous avez besoin de l'ID du compte de messagerie. Le script du lookup utilise l'authentification de votre compte Gmail pour rechercher tous les e-mails de votre compte. La liste est ensuite affichée dans le formulaire de l'action et vous pouvez alors sélectionner l'ID approprié pour la recherche.
Pour créer un nouveau lookup, procédez comme suit :
1. A l'invite de commande, exécutez les commandes suivantes :
a. cd <user project root directory>
b. flow add lookup
Le lookup hérite du nom du connecteur et il est créé dans le dossier des lookups du répertoire du projet.
Les options suivantes sont disponibles pour la commande :
Options | Description | Type de données |
|---|---|---|
--version | Affiche le numéro de version. | [booléen] |
--help | Affiche l'aide. | [booléen] |
--parentDir, -d | Répertoire parent du projet. | [par défaut : "."] |
--logLevel, -1 | Définit le niveau de consignation. | [par défaut : "info"] |
2. Mettez à jour les propriétés disponibles dans le fichier index.js.
Un JavaScript de Lookup doit exporter un seul objet JavaScript. L'objet peut contenir un nombre quelconque de méthodes. Le fichier index.js présente la structure suivante :
function(input, options, output){
return}
return}
 | Le code peut différer si le service externe utilise une connexion au lieu d'une OAuth. |
L'objet Options fournit un certain nombre de méthodes d'utilitaire requises pour le lookup.
validateDependencies(input.<property name>) : vérifie que l'entrée contient la propriété donnée.
options.getAccessToken(input.auth, function(err, data) { }): Fetch the access token from the server. input.auth contains a UID that is used to fetch the access token. options.getConnection(input.connection, function(err, data){ }) : Fetch the connection corresponding to the UID contained in the connection property.
Pour plus d'informations sur les API utilisables dans les lookups, consultez la section
SDK des connecteurs ThingWorx Flow.
La table suivante décrit la façon dont les arguments sont utilisés.
Argument | Utilisation |
|---|---|
input | Contient les dépendances configurées dans le lookup. |
options | Fournit des méthodes d'utilitaire pour récupérer le mécanisme d'authentification (connexion ou jeton d'accès) et pour activer la prise en charge de la pagination. |
output | Rappel qui doit être appelé pour renvoyer les résultats vers ThingWorx Flow. Suit la convention "erreur en premier" du noeud. Le résultat doit être un tableau d'objets JSON. Typiquement, il s'agit de paires ID et valeur. Des champs supplémentaires peuvent être ajoutés si le schéma dynamique est ajouté. Pour plus d'informations, reportez-vous à la section Injection de schémas dynamiques. Le résultat doit être transmis au rappel (fonction de sortie), et doit être un tableau d'objets JSON contenant l'ID et la valeur. Les résultats doivent être au format suivant : { [ {"id":"id1","value":"value1"}, {"id":"id2","value":"value2"}, ], “next_page”: true } |
Injection de schémas dynamiques
Les schémas d'entrée et de sortie fixes pour les actions posent des limites à la mise en oeuvre d'actions fonctionnellement riches. Les schémas d'entrée et de sortie d'une action peuvent être mis à jour sur la base des choix de l'utilisateur lors du chargement d'un lookup ou de la sélection d'une valeur dans le lookup. Dès lors, le formulaire est actualisé pour correspondre au schéma d'entrée mis à jour avec les valeurs actuelles. De plus, les champs de sortie disponibles pour le mappage de l'action suivante sont mis à jour pour correspondre au schéma de sortie mis à jour.
Les mises à jour des schémas d'entrée et de sortie d'une action peuvent être effectuées sur l'interface de traitement des résultats du lookup.
Vous pouvez injecter le schéma dynamique lors du renvoi des résultats du lookup ou vous pouvez ajouter une autre fonction au lookup via l'attribut onSelect (pour une option sélectionnée). Exécutée au moment du chargement du lookup, l'injection du schéma dynamique a besoin du schéma pour toutes les valeurs de lookup.
| | L'injection multiniveau (sur la base de lookups consécutifs) est possible pour certains objets. Elle permet des ajouts avec restrictions, mais les suppressions sont impossibles. |
Pour ajouter un schéma d'entrée affiché par le formulaire, il convient d'utiliser les attributs schema, parent et append sur le résultat JSON pour le lookup aux côtés des id et value. De même, utilisez outSchema, outAppend et outParent pour ajouter un schéma de sortie, qui est affiché comme schéma de sortie de l'action lorsque l'action connectée est ouverte. En règle générale, les attributs append ou outAppend et parent ou outParent sont utilisés conjointement, lorsque le schéma fourni est ajouté au parent indiqué pour étendre les propriétés. Si append n'est pas utilisé, tout le schéma sera remplacé par le schéma nouvellement ajouté.
L'attribut parent ou outParent est l'ID de l'élément de schéma (doit être de type object) du schéma correspondant. En l'absence d'attribut parent ou outParent, le contexte par défaut pour la mise à jour est la racine du schéma correspondant. La mise à jour du schéma s'effectue dans le périmètre de l'objet parent ou outParent par fusion, ou remplacement en l'absence d'attribut append/outAppend, des propriétés fournies dans le schéma d'injection avec les propriétés existantes.
Vous pouvez également utiliser l'attribut userSelected sur le schéma de sortie qui est injecté. Cet attribut s'utilise pour injecter un schéma par défaut (avec la valeur "faux") et le remplacer par un sous-ensemble (valeur "vrai") lorsque vous sélectionnez des options sur le formulaire. Si tous les attributs userSelected = true sont supprimés (lorsqu'un élément de tableau du formulaire est supprimé), le schéma revient à la valeur par défaut.
Par exemple, pour le connecteur OData, définissez les schémas d'injection d'entrée et de sortie comme indiqué dans la figure suivante :
Le schéma d'injection d'entrée pour OData est le suivant :
"schema": {
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
Le schéma d'injection de sortie pour OData est le suivant :
"outSchema": {
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
Comme le montre l'exemple ci-dessus, il est possible de fixer quelques paramètres sur l'interface utilisateur de mappage dans le schéma de sortie injecté dynamiquement en définissant la propriété suivante : visible = true.
Pour internationaliser vos schémas dynamiques d'entrée et de sortie, consultez la section
Prise en charge de l'internationalisation par les connecteurs.
Pagination
Les lookups prennent en charge la pagination, c.-à-d. la possibilité de produire de nombreuses pages de résultats. Chaque invocation produit une seule page de résultats. Dans l'interface utilisateur, vous pouvez récupérer la page en cliquant sur "Plus de résultats" dans la liste. Les objets Entrée et Options contiennent des méthodes et des propriétés permettant de traiter la pagination.
• options.getNextPage(boolean) : utilisé dans la pagination pour renvoyer l'URL afin de récupérer la page suivante. Cette URL doit être définie sur la propriété "next_page" de l'objet de résultat pour que la pagination fonctionne correctement. Si aucune autre page ne doit être renvoyée, définissez cette propriété sur "faux".
• options.maxResults : utilisé avec la pagination pour obtenir le nombre maximal de résultats à renvoyer à la fois.
• input.page : numéro de page actuel.
• input.searchById : recherche par ID.
• input.searchByValue : recherche par valeur.
La recherche par ID et par valeur est disponible si l'indicateur de recherche du lookup est défini sur "vrai". Pour obtenir un exemple de lookup, reportez-vous aux sections ci-dessus. Ces propriétés permettent d'affiner la recherche en recherchant dans le système cible les éléments qui correspondent à l'ID ou à la valeur.
| | L'ID et la valeur peuvent faire référence à des champs différents dans le système cible. |