Tutorial: Een workflow aanmaken

Een uitgewerkt voorbeeld van het gebruik van de Portant Developer API om een workflow aan te maken, deze uit te voeren via de webhookbron en te luisteren naar events wanneer documenten worden aangemaakt. Alle verzoeken gebruiken cURL. Vervang <DEVELOPER_ACCESS_TOKEN> door het token dat het Portant-integratieteam u heeft verstrekt.

Tip: bouw en voer eerst een workflow uit in de Portant Workflow-webapplicatie voordat u begint, zodat u vertrouwd bent met hoe workflows werken. Wij adviseren een Google Docs-sjabloon, wat tevens bevestigt dat uw account correct is geautoriseerd bij de API's van Google.

In deze tutorial wordt ervan uitgegaan dat u de stappen in de handleiding Developers overview heeft voltooid.

Stap 1. Een workflow aanmaken

We noemen de workflow "Developer Workflow" en maken deze aan via het eindpunt 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"
}'

Een geslaagd verzoek retourneert 201 Created met een JSON-body die er als volgt uitziet:

{
    "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"
}

Sla de waarde van id op. U gebruikt deze in de volgende verzoeken.

Als u https://app.portant.co/w/wkf_<id>/ opent met dat ID, ziet u uw nieuwe workflow in de webapplicatie. Twee velden zijn hier het belangrijkst: source.webhookUrl en status.

Nieuwe workflow geopend in de Portant-webapplicatie na de API-aanroep

source.webhookUrl is het adres waarnaar u gegevens POST om een automatisering te starten zodra de workflow is voltooid. Sla dit ook op.

status is "INCOMPLETE" omdat de workflow nog geen sjabloondocumenten bevat. Een workflow heeft zowel een bron als minstens één sjabloon nodig om uitvoerbaar te zijn. We voegen hierna een sjabloon toe.

Stap 2. Een sjabloondocument aanmaken

Om een sjabloon toe te voegen, kopieert u een bestaand Google Docs-bestand naar de 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 is het ID van een bestand in Google Drive waartoe u toegang heeft. U kunt het ID van een bestand vinden in de URL. Het bovenstaande voorbeeld-ID is afkomstig van dit openbare Portant-document, dus u kunt het gebruiken voor testdoeleinden.

De respons ziet er als volgt uit:

{
    "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"
}

Er is een nieuw sjabloon aan uw workflow toegevoegd met een kopie van het bestand dat u heeft opgegeven. De documentresource beschikt over een set opties waarmee u kunt bepalen hoe uitvoerdocumenten worden aangemaakt. U kunt deze wijzigen met een PATCH-verzoek naar het eindpunt Document.

Als u de workflow opnieuw ophaalt via GET, is de status nu "COMPLETE". Voordat we de eerste automatisering uitvoeren, stellen we ook eventmeldingen in.

Stap 3. Luisteren naar automatiseringsevents

Om een melding te ontvangen wanneer een automatisering wordt uitgevoerd, registreert u een uitgaande webhook op de workflow. Voor testdoeleinden kunt u een tijdelijke webhook aanmaken op 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>"
}'

U ontvangt een 201 Created-respons met de URL die u heeft geregistreerd. De workflow is klaar om te worden uitgevoerd.

Stap 4. Gegevens POSTen naar de webhookbron

Om een automatisering te starten, stuurt u een JSON-body via POST naar de webhook-bron-URL van de workflow (de URL die is geretourneerd in stap 1).

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

Het eindpunt retourneert 200 OK met een lege JSON-body. Binnen een minuut zou uw webhook.site-inbox een gebeurtenis moeten tonen met een link naar het nieuwe document in uw Google Drive.

In de Portant Workflow-webapplicatie verschijnt de nieuwe uitvoer ook op de uitvoerpagina van de workflow. Dat is alles: u hebt uw eerste workflow aangemaakt en uitgevoerd via de Developer API.

Raadpleeg de rest van de API-referentie voor meer informatie over elk eindpunt en elke resource. Als u vragen of functieverzoeken hebt, neemt u contact op met het customer success- of integratieteam.

(En ja, Jeremy is het mascotte van Portant. 🐨)