Créer un panneau
Découvrez comment créer des applications de panneau pour des pages spécifiques dans Coupa.
Introduction
Les applications de panneau permettent aux clients d'afficher des données provenant de sources externes dans un panneau d'interface utilisateur sur une page Coupa donnée. Ces données peuvent être spécifiques au contexte et peuvent être actualisées automatiquement ou manuellement. Par exemple, lorsqu'une page de fournisseur se charge dans Coupa, une application de panneau sur cette page peut automatiquement obtenir des données d'une source externe via une API qui se rapporte à ce fournisseur particulier et afficher les données dans Coupa.
Créez une application de panneau en allant dans Configurer les > IFrames et les panneaux de la > plate-forme , puis cliquez sur le bouton Créer , puis sur l'option : Panel. La clé de la création et de la configuration d'une application Panel se trouve dans son descripteur, un ensemble de paramètres au format JSON pour votre application.
Voici un exemple d'application de panneau sur la page d'accueil Coupa.
Vous pouvez créer une application de panneau en allant dans Configurer les applications > installées de > la plate-forme. Cliquez sur le bouton Créer et sélectionnez Créer une application de panneau.
Conditions exigées
À partir de R29, les applications Panel nécessitent au moins TLS v1.2 pour établir des connexions sortantes vers des API tierces.
Notions de base sur l'application Panel
Les applications Panel sont construites à l'aide d'un descripteur d'application qui utilise le format JSON. Le descripteur se compose de deux propriétés principales : les données et les blocs. Les données sont traitées à l'aide de JQ v1.6.
| Propriété | Description |
|---|---|
slot |
Spécifie le type de page où le panneau sera rendu. Les options actuelles sont :
Seul un emplacement peut être spécifié par application de panneau. Pour que l'application apparaisse sur plusieurs pages, créez à nouveau l'application avec la valeur d' |
|
|
L'attribut data décrit comment récupérer les données souhaitées qui sont rendues dans le panneau. Objet JSON qui décrit les données à récupérer pour rendre le panneau. Les valeurs de cet objet seront des URL auxquelles Coupa enverra une demande afin de récupérer les données. Les réponses de toutes ces demandes de données seront fusionnées en un hachage, alias sous le nom de clé qui leur est donné dans cet objet. |
contexte |
Un appel API à la recherche d'articles du NY Times pour des articles récents sur un fournisseur ressemblerait à ceci : Contactez Coupa pour obtenir une liste mise à jour des données contextuelles disponibles pour chaque créneau. |
| Paramétrer les appels API (propriétés) |
Un tableau de propriétés qu'un utilisateur/administrateur doit fournir après avoir activé votre application de panneau. Si votre application/API nécessite une clé API unique, ou un identifiant/mot de passe pour chaque client Coupa qui l'active, voici comment vous fournissez cette option. Un exemple de bloc serait : Vous référencez ensuite vos propriétés dans les blocs de données comme ceci : Lorsqu'un administrateur Coupa active une nouvelle application de panneau, il est invité à remplir tous les champs « propriétés » spécifiés dans le descripteur de votre application. |
lancement |
Ajoute un bouton de lancement qui peut être utilisé lorsqu'une application de panneau n'a pas besoin d'être affichée immédiatement. Plutôt que de communiquer automatiquement avec le tiers et de rendre les données, l'application Panel ne communique que si l'utilisateur final clique manuellement sur le bouton de lancement. Cet objet JSON comprend Comment utiliser
|
allow_refresh |
Ajoute un bouton d'actualisation qui peut être utilisé lorsque les données de la page changent et affectent les données rendues dans l'application Panel. Ceci est pratique pour votre application Panier lorsqu'une ligne de demande est mise à jour. L'utilisateur peut cliquer sur le bouton Actualiser pour mettre à jour les données dans l'application Panneau. Cette option booléenne est utilisée pour afficher un bouton d'actualisation sur l'application Panel dans le descripteur de l'application : "allow_refresh" : true Comment utiliser
Lorsque vous cliquez dessus, le bouton actualise le contenu de cette application. Ce champ doit être ajouté au même niveau que « slot », « data », « launch », etc., mais pas dans des blocs. Le bouton d'actualisation est affiché en haut de l'application du panneau. |
blocs |
L'attribut blocks décrit comment afficher les données dans le panneau. Il s'agit d'un tableau d'objets JSON (« blocs ») de différents types qui décrivent chacun une visualisation séparée. Les blocs ont accès aux données qui ont été précédemment envoyées et les utilisent pour créer des visualisations. |
error_blocks |
L'attribut blocs d'erreur fonctionne de la même manière que l'attribut blocs, mais est utilisé pour créer des messages d'erreur en cas de problème d'obtention ou de rendu des données. |
Extraction de données
Nous autoriserons les applications à passer jusqu'à 5 appels HTTP distincts afin de récupérer des données pour l'application. Celles-ci seront spécifiées à l'aide de l'attribut de données dans le descripteur. Les appels API doivent renvoyer JSON (préféré) ou XML.
Types de blocs d'applications Panel
Panel App restitue ces données sur une page Coupa existante à l'aide de différents types d'éléments d'interface utilisateur appelés blocs. Coupa prend en charge les types de blocs suivants :
- Texte enrichi (y compris les images)
- Champs (essentiellement des paires clé-valeur)
- Nombre
- Argent
- Diagramme circulaire
- Graphique ligne/barre/colonne
- Lancer
- Actualiser
- Ligne
- Tableau dynamique
Configuration de l'application
| Attributs | Description |
|---|---|
|
|
Identifie le type de bloc. Par exemple, |
|
|
Cet objet JSON aura des propriétés différentes en fonction de la stratégie. JQ
Traitement des données avec JQ Par exemple, le script JQ suivant peut être utilisé pour extraire plusieurs éléments de données spécifiques et les reconditionner dans un autre objet JSON : Cela entraînerait la production de l'objet JSON suivant : Plus d'informations : |
|
|
Différents types de blocs peuvent avoir d'autres propriétés spécifiques à ce type de bloc. |
Types de blocs d'applications Panel
Bloc de texte
| Attributs | Description |
|---|---|
|
|
Doit être égal au |
modèle |
Le type de bloc de texte utilise un modèle Liquid Markdown. Le modèle est d'abord analysé en tant que liquide pour interpoler les données renvoyées par les demandes. Ensuite, le modèle est à nouveau analysé en tant que Markdown pour générer le code HTML. Markdown fournit une méthode sûre pour générer du HTML, et pour des raisons de sécurité, Coupa bloque le HTML en ligne dans le modèle. Il n'y a pas de limite de caractères autre que la limite maximale de la colonne de données qui stocke la configuration du bloc. Markdown permet les en-têtes, la mise en évidence en ligne, les listes, les images, les liens et les guillemets. Coupa prend également en charge la mise en évidence de la syntaxe et les tableaux. Pour plus d'informations sur l'utilisation de Liquid et Markdown, voir Langage du modèle Liquid et Mastering Markdown. |
données |
La stratégie de données doit produire un seul objet JSON. Toutes les clés de l'objet seront disponibles pour le modèle Liquide en tant que variables. |
Actuellement, un bloc de texte est le meilleur/le seul moyen d'afficher des données dans un tableau en utilisant le format de tableau kramdown.
Bloc de champs
| Propriété | Description |
|---|---|
|
|
Doit correspondre au |
données |
La stratégie de données doit produire un tableau d'objets JSON avec des attributs d'étiquette et de valeur. Lors du rendu, l'étiquette sera utilisée comme étiquette de champ et la valeur sera utilisée comme valeur de champ. |
titre |
Un titre facultatif qui apparaîtra au-dessus de la liste des champs. |
Bloc barre/ligne
| Propriété | Description |
|---|---|
|
|
Doit être égal à |
données |
La stratégie de données doit produire un tableau de tableaux. Contrairement au bloc de tableau, les données pour les graphiques à barres/lignes seront orientées colonnes. Chaque tableau représente une seule série de données qui seront affichées. Le premier élément est le nom de la série, puis les éléments restants sont les points de la série. |
axe |
Permet de configurer les étiquettes sur les axes x et y. |
titre |
Un titre facultatif qui apparaîtra sous le graphique. |
description |
Une description des options qui apparaîtra sous le graphique dans un texte plus petit. |
Bloc à tarte
| Propriété | Description |
|---|---|
|
|
Doit être égal à la tarte |
données |
La stratégie de données doit produire un tableau de tableaux orienté colonne tel que décrit dans la section Bloc de barres/lignes. |
titre |
Un titre facultatif qui apparaîtra au-dessus du graphique. |
description |
Une description des options qui apparaîtra sous le graphique dans un texte plus petit. |
Money block
| Propriété | Description |
|---|---|
|
|
Doit être égal à l'argent |
données |
La stratégie de données doit produire un objet JSON avec la structure suivante :
|
Titre |
Un titre facultatif qui apparaîtra au-dessus du numéro. |
Description |
Une description facultative qui apparaîtra sous le numéro dans un texte plus petit. |
Bloc de numéros
| Propriété | Description |
|---|---|
|
|
Doit être égal à nombres |
Données |
La stratégie de données doit produire un seul entier JSON ou Flottant. |
Décimal |
Le nombre de décimales à afficher après la virgule. La valeur par défaut est 0. |
Titre |
Un titre facultatif qui apparaîtra au-dessus du numéro. |
Description |
Une description facultative qui apparaîtra sous le numéro dans un texte plus petit.Exemple d'applications Panel |
Champs personnalisés
L'accès aux champs personnalisés sur un objet en contexte suit ce format général : context.<object>.custom_fields.<field_name>
Où se <field_name> trouve l'invite Nom de champ lors de la création d'un champ personnalisé :
Puisque nous examinons l'objet Fournisseur et que nous avons un champ, Numéro de téléphone, vous le référenceriez comme suit : context.supplier.custom_fields.phone_number
| Fente | Accessoire - Champ personnalisé |
|---|---|
| contracts.show | context.contract.custom_fields.<field_name> |
| projects.show | context.project.custom_fields.<field_name> |
| devis/requests.show | context.quote_request.custom_fields.<field_name> |
| réquisition_en-têtes.edit | context.requisition_header.custom_fields.<field_name> |
| suppliers.show | context.supplier.custom_fields.<field_name> |
Les champs personnalisés ne sont pas applicables pour les emplacements qui ne font pas référence à un objet spécifique, comme :
user.homeexpenses.index
Détails de l'API
Authentification
Coupa prend en charge les types d'authentification suivants :
| Méthode | Exemple |
|---|---|
| Clé API standard |
|
| Authentification de base |
|
| Demande de jeton de courte durée à l'aide de la demande « before_data » |
|
URL de l'API
- Les URL doivent être HTTPS
- Les URL doivent être accessibles par les serveurs Coupa (c'est-à-dire qu'une requête HEAD doit réussir)
- Les URL doivent être analysées avec succès en tant que modèles liquides valides. Cela permet l'interpolation
Détails de la demande d'API
- Lors de l'interpolation des données dans les URL à l'aide de Liquid, le résultat doit être une URL valide
- Le code de réponse doit être 200 ou 204
- Le serveur distant doit répondre dans un délai de 5 secondes
- Le type de contenu de réponse doit être
application/jsonouapplication/xml
Boutons
Vous pouvez configurer un bouton de lancement ( launch)et un bouton d'actualisation (allow_refresh) pour vos applications de panneau. Bien que la fonctionnalité ressemble à un bloc, techniquement, les boutons ne sont pas des blocs. Vous trouverez des détails sur les boutons dans la section Bases de l'application Panel de cet article. pour plus d'informations.
Contexte de l'application Panel
Vous pouvez créer des applications de panneau pour les pages suivantes :
- Page d'accueil :
/et/utilisateur/accueil - Page fournisseurs :
/suppliers/:id/record - Page des contrats :
/contracts/show/:id - Panier :
/requisition_headers/{id}/edit - Page d'accueil des projets :
projects.show - Page Paramètres de l'événement de sourcing :
devis/requests.show
Chaque type d'application Panel a sa propre charge utile contextuelle. Vous trouverez ci-dessous les champs qui seront fournis dans la charge utile de l'API Panel Apps, qui sont utilisés comme contexte pour faire correspondre et trouver des données.
| Page | Champs disponibles |
|---|---|
| Toutes les applications du panneau | user_instance (c.-à-d. [nom de domaine].coupahost.com) est inclus dans la charge utile. |
| Page d'accueil | id, e-mail, nom complet, connexion, Employee_NUMBER |
| Afficher/modifier la facture |
|
| Page fournisseur |
custom_fields : |
| Page contrat | id, parent_contract_id, nom, numéro, version, supplier_id, start_date, statut |
| Panier | La charge utile de l'application Panier contiendra les mêmes champs que la charge utile de l'API d'en-tête de la demande |
| Projets | Tous les champs du système de projet et les champs personnalisés |
| Événement d'approvisionnement |
|
Exemples d'applications Panel
Recherche d'article dans le New York Times
Cette application ajoute les dernières nouvelles sur le fournisseur du New York Times sur la page du fournisseur. Vous devrez obtenir une clé API NYT pour que celle-ci fonctionne.
Il s'agit du code qui anime l'application.
{
"properties" : {
"api_key" : {
"type" : "string"
}
},
"slot" : "fournisseurs.show",
"before_data" : {},
"data" : {
"nyt_data" : {
"URI" : "https://api.nytimes.com/svc/search/v2/articlesearch.json?q={context.supplier.name}&api-key={properties.api_key}"
}
},
"blocks" : [
{
"type" : "texte",
"data" : {
"type" : "jq",
"jq" : "{ \"docs\": .nyt_data | .response | .docs }"
},
"text" : "{:height=\"100px\"}"
},
{
"type" : "texte",
"data" : {
"type" : "jq",
"jq" : "{ \"docs\": .nyt_data | .response | .docs }"
},
"texte" : "1. [{{ docs[0] .headline.main}}]({{ docs[0].web_url }}) \n2. [{{ docs[1] .headline.main}}]({{ docs[1].web_url }})\n3. [{{ docs[2] .headline.main}}]({{ docs[2].web_url }})\n4. [{{ docs[3] .headline.main}}]({{ docs[2].web_url }})\n5. [{{ docs[2] .headline.main}}]({{ docs[4].web_url }})\n"
}
]
}Application Weather Panel
Cet exemple d'application montre la représentation graphique des aspects de température d'un emplacement. Vous devez obtenir une clé API pour que celle-ci fonctionne.
Il s'agit du code qui anime l'application.
{
"properties" : {},
"slot" : "fournisseurs.show",
"data" : {
"chicago_data" : {
"method" : "obtenir",
"URI" : "https://api.openweathermap.org/data/2.5/weather ?q=Chicago&appid=155057bc8e3dde82a6482e76bddf9c10&units=imperial"
}
},
"blocks" : [
{
"type" : "bar",
"titre" : "Voici la météo à Chicago",
"data" : {
"type" : "jq",
"jq" : "[{name : \"Temp\", data : [.chicago_data.main.temp]}, {name : \" Vitesse du vent\", data : [.chicago_data.wind.speed]}, {name : \"Humidité\", data : [.chicago_data.main.humidity]}]"
},
"axes" : {
"xAxis" : {
"labels" : {
"enabled" : false
}
},
"yAxis" : {
"title" : {
"text" : ""
},
"max" : 100
}
}
},
{
"type" : "ligne",
"titre" : "Voici la météo à Chicago",
"data" : {
"type" : "jq",
"jq" : "[{name : \"Minimum, Current, max temp for Chicago\", data : [[.chicago_data.main.temp_min], [.chicago_data.main.temp], [.chicago_data.main.temp_max]] }, {name : \"Fake data not from API\", data : [44, 52, 130, 87, 74, 88] }]"
},
"axes" : {
"xAxis" : {
"labels" : {
"enabled" : true
},
"categories" : [
"Jan",
"Fév",
"Mars",
"TAP",
"Mai",
"Juin"
]
},
"yAxis" : {
"title" : {
"text" : ""
},
"max" : 200
}
}
}
]
}Exemple d'API d'application Panel
Vous trouverez ci-dessous le descripteur d'application utilisé pour un test automatisé. Nous éliminons la réponse de l'API pour renvoyer exactement ceci :
[
{
"data_title" :"Titre",
"data_number" :42,
"second_score" :88
}
]
{
# Voici l'endroit où vous configureriez les champs spécifiques au client. Comme login/mot de passe. Le client serait invité à remplir
# ces valeurs une fois, lors de l'activation de l'application
"properties" : {},
# Il s'agit de la page où l'application est affichée. Voir la propriété "slot" pour les valeurs possibles.
"slot" : "fournisseurs.show",
# Certaines API nécessitent un jeton porteur, ou un processus en 2 étapes, c'est là que vous gérez cela.
"before_data" : {},
"data" : {
"coupa_data" : {
# Vous pouvez ajouter des valeurs spécifiques au contexte à cet appel d'API, {{context.contract.supplier_name}} par exemple
"URI" : "http://fake.test",
# Cela fonctionne intuitivement, il suffit de spécifier vos en-têtes API ici, jeton porteur, paramètres, etc.
"en-têtes" : {}
}
},
"blocks" : [
{
"type" : "numéro",
# This is hard-coded title for this block, cannot use api data, or contextual data here
"titre" : "Titre pour le bloc de numéros",
# "coupa_data" était la réponse de l'API ci-dessus, .[0] renvoie le contenu dans le {}, ".data_number" obtient la valeur,
# dans ce cas "42"
"data" : {
"type" : "jq",
"jq" : ".coupa_data | .[0] | .data_number"
}
},
# Donc, ce bloc rend un bloc de nombre spécialement formaté, avec le nombre "42" en grande police en gras,
# et un libellé/titre de « Title for number block »
{
# Fields block has some of the strictest requirements for data, It displays all data in key -> value pairs
"type" : "champs",
"data" : {
"type" : "jq",
"jq" : ".coupa_data | .[] | to_entries | map({ label : .key, value : .value })"
}
},
{
# Pour ce bloc, nous allons simplement extraire le hachage du [] et utiliser les valeurs qu'il contient
"type" : "texte",
"data" : {
"type" : "jq",
"jq" : " .coupa_data | .[0]"
},
# Les blocs de texte vous donnent beaucoup de flexibilité pour afficher les données de la réponse de l'API dans le contexte.
# Le texte peut être formaté tout comme le balisage, de sorte que vous pouvez créer des liens, des tableaux, rendre/redimensionner des images, etc.
"text" : "{{ data_number }} est le data_number"
},
{
# La configuration du graphique à barres est assez délicate, peut-être que vous pouvez travailler avec nous si vous voulez suivre cette voie.
# Mais cet exemple crée un graphique à barres avec des valeurs/étiquettes de tailles de barres basées sur les valeurs de la réponse API
"type" : "bar",
"titre" : "Graphique à barres avec de fausses données",
"data" : {
"type" : "jq",
"jq" : "[{name : \"Score global\", data : [.coupa_data | .[0].data_number]},
{name : \"Score d'environnement\", data : [.coupa_data | .[0].second_score]}]"
},
"axes" : {"xAxis" : {"labels" : { "enabled" : false}}, "yAxis" : {"title" : { "text" : ""}, "max" : 100} }
}
]
}Test dans l'instance du partenaire
Pour tester cela dans Coupa, vous devrez être sur la version R25.0 ou supérieure. En fin de compte, votre application fera partie de l'annuaire des applications et ne sera pas une application de panneau personnalisée, mais en utilisant ces étapes, vous pouvez la tester vous-même avant que Coupa n'ajoute officiellement l'application à l'annuaire des applications.
- Aller à la configuration
- Sous Plateforme, cliquez sur « Applications installées »
- Cliquer sur le bouton 'Créer', puis sélectionner 'Créer une nouvelle application de panneau'
- Créez l'application
- Ajouter un nom
- Dans la section du descripteur, incluez le code indiqué ci-dessus
Une fois terminé, si aucune erreur ne se produit, une application de panneau sera affichée sur chaque page du fournisseur.
Téléchargez une application sur Coupa App Marketplace
Visitez Coupa App Marketplace pour télécharger un panneau et suivez les instructions d'installation fournies. Pour plus d'informations sur l'affichage des applications installées, consultez l'App Marketplace de Coupa.