Tutorial: Einen Workflow erstellen

Ein ausgearbeitetes Beispiel für die Verwendung der Portant Developer API, um einen Workflow zu erstellen, ihn über seine Webhook-Quelle auszuführen und auf Ereignisse zu lauschen, wenn Dokumente erstellt werden. Alle Anfragen verwenden cURL. Ersetzen Sie <DEVELOPER_ACCESS_TOKEN> durch das Token, das Ihnen das Portant-Integrationsteam gegeben hat.

Tipp: Bevor Sie beginnen, erstellen und starten Sie einen Workflow in der Portant Workflow-Webanwendung, damit Sie mit der Funktionsweise von Workflows vertraut sind. Wir empfehlen eine Google Docs-Vorlage, die außerdem bestätigt, dass Ihr Konto korrekt mit den APIs von Google autorisiert ist.

Dieses Tutorial setzt voraus, dass Sie die Schritte im Leitfaden Developers overview abgeschlossen haben.

Schritt 1. Einen Workflow erstellen

Wir nennen den Workflow "Developer Workflow" und erstellen ihn mit dem Endpunkt 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"
}'

Eine erfolgreiche Anfrage gibt 201 Created mit einem JSON-Body zurück, der wie folgt aussieht:

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

Speichern Sie den Wert id. Sie werden ihn in den nächsten Anfragen benötigen.

Wenn Sie https://app.portant.co/w/wkf_<id>/ mit dieser ID öffnen, sehen Sie Ihren neuen Workflow in der Webanwendung. Zwei Felder sind hier besonders wichtig: source.webhookUrl und status.

Neuer Workflow, der nach dem API-Aufruf in der Portant-Webanwendung geöffnet wurde

source.webhookUrl ist die Adresse, an die Sie Daten per POST senden, um eine Automatisierung zu starten, sobald der Workflow abgeschlossen ist. Speichern Sie auch diese.

status ist "INCOMPLETE", da der Workflow noch keine Vorlagendokumente enthält. Ein Workflow benötigt sowohl eine Quelle als auch mindestens eine Vorlage, um ausführbar zu sein. Als Nächstes fügen wir eine Vorlage hinzu.

Schritt 2. Ein Vorlagendokument erstellen

Um eine Vorlage hinzuzufügen, kopieren Sie eine vorhandene Google Docs-Datei in den 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 ist die ID einer Datei in Google Drive, auf die Sie Zugriff haben. Die ID einer Datei finden Sie in deren URL. Die obige Beispiel-ID stammt aus diesem öffentlichen Portant-Dokument, sodass Sie sie zum Testen verwenden können.

Die Antwort sieht wie folgt aus:

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

Ihrem Workflow wurde eine neue Vorlage mit einer Kopie der von Ihnen angegebenen Datei hinzugefügt. Die Dokumentressource verfügt über eine Reihe von Optionen, die bestimmen, wie Ausgabedokumente erstellt werden. Sie können diese mit einer PATCH-Anfrage an den Endpunkt Document ändern.

Wenn Sie den Workflow erneut per GET abrufen, ist der Status jetzt "COMPLETE". Bevor wir die erste Automatisierung ausführen, richten wir auch Ereignisbenachrichtigungen ein.

Schritt 3. Auf Automatisierungsereignisse lauschen

Um benachrichtigt zu werden, wenn eine Automatisierung ausgeführt wird, registrieren Sie einen ausgehenden Webhook für den Workflow. Zum Testen können Sie einen temporären Webhook unter webhook.site einrichten.

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

Sie erhalten eine 201 Created-Antwort mit der von Ihnen registrierten URL. Der Workflow ist bereit zur Ausführung.

Schritt 4. Daten an die Webhook-Quelle per POST senden

Um eine Automatisierung zu starten, senden Sie einen JSON-Body per POST an die Webhook-Quell-URL des Workflows (die in Schritt 1 zurückgegebene URL).

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

Der Endpunkt gibt 200 OK mit einem leeren JSON-Body zurück. Innerhalb einer Minute sollte Ihr webhook.site-Posteingang ein Ereignis mit einem Link zum neuen Dokument in Ihrem Google Drive anzeigen.

In der Portant Workflow-Webanwendung erscheint die neue Ausgabe ebenfalls auf der Outputs (Ausgaben)-Seite des Workflows. Das war es: Sie haben Ihren ersten Workflow über die Developer API erstellt und ausgeführt.

Einzelheiten zu jedem Endpunkt und jeder Ressource finden Sie im übrigen Teil der API-Referenz. Bei Fragen oder Feature-Anfragen wenden Sie sich an das Customer-Success- oder Integrations-Team.

(Und ja, Jeremy ist das Portant-Maskottchen. 🐨)