Tutoriel : Créer un workflow

Un exemple pratique d'utilisation de l'API Portant Developer pour créer un workflow, l'exécuter via sa source webhook et écouter les événements lors de la création de documents. Toutes les requêtes utilisent cURL. Remplacez <DEVELOPER_ACCESS_TOKEN> par le jeton que l'équipe d'intégration Portant vous a fourni.

Conseil : avant de commencer, créez et exécutez un workflow dans l'application web Portant Workflow afin de vous familiariser avec le fonctionnement des workflows. Nous recommandons un modèle Google Docs, ce qui confirme également que votre compte est correctement autorisé avec les API de Google.

Ce tutoriel suppose que vous avez suivi les étapes du guide Présentation des développeurs.

Étape 1. Créer un workflow

Nous allons nommer le workflow "Developer Workflow" et le créer avec l'endpoint Workflows POST.

curl --location --request POST 'https://api.portant.co/v0/workflows/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Developer Workflow"
}'

Une requête réussie renvoie 201 Created avec un corps JSON qui ressemble à ceci :

{
    "id": "wkf_<id>",
    "name": "Developer Workflow",
    "icon": "DocumentText",
    "color": "#cccccc",
    "status": "INCOMPLETE",
    "autoCreate": true,
    "owner": {
        "id": "usr_<id>",
        "name": "Your Name",
        "email": "you@email.com"
    },
    "team": null,
    "source": {
        "id": "src_<id>",
        "sourceType": "WEBHOOK",
        "sourceFields": [],
        "webhookUrl": "https://webhooks.portant.co/<webhook_token>"
    },
    "documents": [],
    "outgoingWebhook": null,
    "createdByApi": true,
    "createdAt": "2024-08-13T17:49:28.639426+10:00",
    "updatedAt": "2024-08-13T17:49:28.659242+10:00"
}

Enregistrez la valeur id. Vous l'utiliserez dans les requêtes suivantes.

Si vous ouvrez https://app.portant.co/w/wkf_<id>/ avec cet identifiant, vous verrez votre nouveau workflow dans l'application web. Deux champs sont particulièrement importants ici : source.webhookUrl et status.

source.webhookUrl est l'adresse à laquelle vous enverrez des données via POST pour démarrer une automatisation une fois le workflow terminé. Enregistrez cette valeur également.

status est "INCOMPLETE" car le workflow ne contient pas encore de documents modèles. Un workflow nécessite à la fois une source et au moins un modèle pour être exécutable. Nous allons ajouter un modèle à l'étape suivante.

Étape 2. Créer un document modèle

Pour ajouter un modèle, copiez un fichier Google Docs existant dans le workflow.

curl --location --request POST 'https://api.portant.co/v0/workflows/wkf_<id>/documents/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_id": "1frlTt7Jj8HuXWHkS9o0mshLaym6NQBImsAIhw4Iiew4"
}'

file_id est l'identifiant d'un fichier dans Google Drive auquel vous avez accès. Vous pouvez trouver l'identifiant d'un fichier dans son URL. L'identifiant d'exemple ci-dessus provient de ce document Portant public, vous pouvez donc l'utiliser à des fins de test.

La réponse ressemble à ceci :

{
    "id": "doc_<id>",
    "documentType": "GOOGLE_DOCS",
    "file": {
        "id": "1MvPvT3cLilEw6ktXxjOYFUGrZH6JO8dm5Gpj8GExMcc",
        "name": "Developer Workflow - [Template]",
        "url": "https://docs.google.com/document/d/1MvPvT3cLilEw6ktXxjOYFUGrZH6JO8dm5Gpj8GExMcc/edit?usp=drivesdk",
        "mimeType": "application/vnd.google-apps.document"
    },
    "outputName": "Developer Workflow - {{Timestamp}}",
    "createPdfCopy": false,
    "removeOutput": false,
    "enablePdfPassword": false,
    "pdfPassword": "",
    "pdfPasswordPreventCopy": false,
    "previewUrl": "https://preview.portant.co/doc_LcQWshvjR9XLzQ"
}

Un nouveau modèle a été ajouté à votre workflow avec une copie du fichier que vous avez fourni. La ressource document dispose d'un ensemble d'options qui modifient la façon dont les documents de sortie sont créés. Vous pouvez les modifier via une requête PATCH vers l'endpoint Document.

Si vous effectuez à nouveau un GET sur le workflow, le statut est désormais "COMPLETE". Avant d'exécuter la première automatisation, configurons également les notifications d'événements.

Étape 3. Écouter les événements d'automatisation

Pour être notifié lorsqu'une automatisation s'exécute, enregistrez un webhook sortant sur le workflow. À des fins de test, vous pouvez créer un webhook temporaire sur webhook.site.

curl --location --request POST 'https://api.portant.co/v0/workflows/wkf_<id>/outgoing-webhook/' \
--header 'Authorization: <DEVELOPER_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "webhookUrl": "https://webhook.site/<token>"
}'

Vous recevrez une réponse 201 Created contenant l'URL que vous avez enregistrée. Le workflow est prêt à être exécuté.

Étape 4. Envoyer des données à la source webhook

Pour démarrer une automatisation, envoyez un corps JSON via POST à l'URL source webhook du workflow (celle retournée à l'étape 1).

curl --location --request POST 'https://webhooks.portant.co/<webhook_address>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "Name": "Jeremy the Koala"
}'

Le point de terminaison renvoie 200 OK avec un corps JSON vide. En moins d'une minute, votre boîte de réception webhook.site devrait afficher un événement contenant un lien vers le nouveau document dans votre Google Drive.

Dans l'application web Portant Workflow, le nouvel élément généré apparaît également sur la page des sorties du workflow. C'est tout : vous avez créé et exécuté votre premier workflow via l'API Developer.

Pour obtenir des détails sur chaque point de terminaison et chaque ressource, consultez le reste de la référence API. Si vous avez des questions ou des demandes de fonctionnalités, contactez l'équipe customer success ou l'équipe integrations.

(Et oui, Jeremy est la mascotte de Portant. 🐨)