Maintenant que nous avons créer une intégration avec une application tierce, nous pouvons commencer à créer des actions.

Les actions seront visibles dans les workflow et permettront aux utilisateurs de s'intégrer très simplement avec l'application en question.

Par exemple, voici une liste d'actions disponible pour Github.

Pour créer une nouvelle action, on se rend dans l'onglet Connexion API, puis on choisit l'application de son choix (Trello pour l'exemple). Cliquer sur l'icon pour afficher la liste des actions disponibles

Créer une action

Choisir le nom de la nouvelle action, commencer le nom de l'action par le nom de l'application pour que ce soit plus simple de la retrouver dans les workflow (ici Trello - Create card)

Editer les paramètres de l'action

Sur la droite, la fenêtre de personnalisation de l'action s'ouvre. Voici la liste des champs qu'il faut renseigner et les bonnes pratiques:
La plupart des réponse sont tirées de la documentation officielle de Trello: https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/#cards

  • name: nom de l'action (trelloCreateCard)
    Attention: ce nom doit contenir le nom de l'application et doit respecter une écriture camelCase sans espace.

  • slug: nom unique qui sera utilisé pour stocker des variables lors du paramètrage de l'action (trello_create_card)
    Attention: ce nom doit contenir le nom de l'application et doit respecter une écriture snake_case sans espace.

  • logo: URL du logo de l'application pour que ce soit visuel dans les workflow

  • path: route de l'action api (/1/cards)

  • fullURL: Ce champs est à renseigner seulement si l'url de base est différente de l'url de base de l'application. C'est très rare.

  • méthode: Type de la requête HTTP qui sera envoyée au serveur tiers (POST)

  • needAuth: Est ce que nous avons besoin d'un utilisateur connecté pour effectuer l'action, ce sera true la plupart du temps (true)

  • scope: Liste des scope nécessaire pour avoir les droits nécessaires pour effectuer l'action (write)

  • payload: Json qui sera envoyé au serveur lors du call API. Vous pouvez définir vos propre variable en utilisant la notation "moustache".
    Si vous souhaitez inclure une variable qui sera une URL, vous devez utiliser la notation avec 3 moustache {{{shortUrl}}} par exemple.
    Par exemple dans notre cas, nous permettons de créer une card trello qui aura la position bottom, et 3 variables qui devront être récupéré (idList, name, description)
    Laisser vide dans les cas où vous n'avez pas besoin de body dans le call API.

  • response_json_strucure: Coller simplement la valeur retournée par l'api en cas de succès. Ca permettra aux utilisateurs de l'action de simplement récupérer les valeurs qui les intéressent

  • handleResponse: Ce champs permet d'extraire une partie de l'object retourné par l'api pour être utilisé dans les autoCompleteActions (nous allons expliquer plus tard l'intérêt des autoCompleteActions).

  • failure_response_json_structure: Coller le message d'erreur renvoyée par l'api en cas d'erreur

Variables de l'action

Nous devons maintenant paramétrer les variables de l'action. En effet, nous avons indiqué des variables dans le payload (on aurait pu en mettre dans l'url ou les headers), il faut donc fournir à Vizir des information sur la variable.

Ici il faut ajouter les champs (input) suivants:

  • idList

  • name

  • description

Il faut remplir les différents input du formulaires comme dans l'exemple ci dessous.

Informations importantes:
- slug doit être similaire à la variable qui est appelée dans le payload de l'action à l'étape précédente.
- required: si vous laissez required à false, la valeur sera alors optionnelle.

- reqLocation: il est préférable d'utiliser payload (si la variable est utilisée dans le body via le payload renseigné à l'étape précédente) ou url (si la variable est utilisée dans l'url via le path renseigné à l'étape précédente).
Utiliser body, query ou headers seulement si vous savez ce que vous faites :)
query sera utilisé lorsqu'on souhaite rajouter une variable (non required) dans les query params

- default: Laisser vide si vous ne souhaitez pas avoir de valeur par défaut. Le champs sera alors "retiré" du json pour le call API.

Ensuite vous avez 3 derniers champs qui vont permettre aux utilisateurs d'avoir une meilleure expérience utilisateur de l'action.

AutocompleAction

Pour comprendre l'intérêt des actions autocomplete prenons l'exemple de idList. Nous avons 2 solutions pour demander idList.
- demander l'idList directement (pas simple de le trouver dans l'interface de Trello)
- récupérer l'idList via API

En lisant la documentation API de Trello nous nous rendons compte pour que récupérer la liste de idList, nous devons dans un premier temps connaitre l'Id de la board.

Nous créons donc 2 nouvelles actions pour :
- récupérer les boards d'un utilisateur (trelloGetBoards)

- récupérer les listes d'une board (trelloGetBoardsList)

On peut maintenant proposer à l'utilisateur non pas de renseigner "à la main" l'idList qu'il aurait dû récupérer dans Trello mais de compléter un formulaire qui sera bien plus simple avec des listes de choix directement récupérées depuis l'api de Trello.
Nous aurons donc des champs de ce type dans l'interface de création de workflows

Choix de la board

Choix de la board

Choix de la liste (dans cette board)

Pour faire cela, on renseigne en autoCompleteAction comme ci dessous:

- autocompleteAction: Nom de l'action utilisée pour avoir une liste de proposition

- autocompleteSubmit: Key de l'api qui sera utilisée dans le call API

- autocompleteDisplay: Key de l'api qui sera utilisée dans l'interface utilisateur pour qu'il soit compréhensible par l'utilisateur.

Si vous avez des questions n'hésitez pas à envoyer un email à aide@vizir.co.

Cette action doit ensuite être validé par Vizir.co pour qu'elle soit accessible pour tous les utilisateurs (et tous les bots). Vous pouvez faire vos demande de validation par email à l'adresse aide.vizir.co en fournissant une vidéo exemple de l'intégration et le lien d'édition des actions de l'API.

Avez-vous trouvé votre réponse?