Tutorial - Create a Workflow

Tutorial to create and run a workflow via the developer API

In this this tutorial we will go through the process of creating a workflow via the Developer API, running the workflow via the created webhook source, and then listening for events to capture the newly created document. All API calls within this tutorial will use cURL, don't forget to insert the Developer Access Token that was provided to you by the Portant integrations team.

💡TIP: Before getting started with the Developer API, try creating and running a workflow in the Portant Workflow web app to get familiar with how workflows in Portant operate. We recommend creating a workflow with a Google Docs template to ensure your account is correctly authorised with Google's APIs.

The following tutorial assumes you have covered all steps in the Getting Started guide.

Step 1. Create a workflow

We will name our first workflow "Developer Workflow" and use the Workflows POST endpoint to create the workflow.

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

If all is set up correctly you will receive as 201 Created status code and see the following JSON response:

{
    "id": "wkf_<id>",
    "name": "Developer Workflow",
    "icon": "DocumentText",
    "color": "#cccccc",
    "status": "INCOMPLETE",
    "autoCreate": true,
    "owner": {
        "id": "usr_<id>",
        "name": "Your Name",
        "email": "[e-mail]"
    },
    "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"
}

Note the ID value that was returned as we will use this for future requests in this tutorial. If you navigate to https://app.portant.co/w/wkf_<id>/ with the return workflow ID you will see your newly created workflow. Important fields to note here are the source.webhookUrl and status fields.

The source.wbehookUrl field contains the address that data will be sent to in order to initiate an automation once the workflow is complete and ready to create automations, note this value down as we will do this later in the tutorial.

The status field shows that the workflow is "INCOMPLETE" because we do not have any template documents in the workflow. The minimum requirements for a workflow to be complete is that it contains both a source and at least one type of template document. We will create our first template document in the next step.

Step 2. Create a Template Document

To create a template document we will use the following request to copy an existing Google Docs file to our workflow to use as a template.

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

The file_id must contain the the ID of a file in Google Drive that you have access to. The ID of a file can be found simply by looking at the URL. For example the ID used in the request above is extracted from the following url: https://docs.google.com/document/d/1frlTt7Jj8HuXWHkS9o0mshLaym6NQBImsAIhw4Iiew4/

The actual file ID included above can be used for testing as this contains links to a publicly accessible document created by Portant.

Once the request is submitted you can expect to see the following response:

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

As we can see, a new document template has been added to our workflow that contains a copy of the template document we provided. The document resource contains a set of options that affect how the output documents are created. These options can be toggled via a PATCH request to the Document.

If you query the GET endpoint for our previously created workflow you will see the status is now complete but we would also like to set up notifications when a new document is created before we run our first automations.

Step 3. Listen for Automation Events

In order to listen for events from our automations we can configure an outgoing webhook to have our workflow notify us when a document is created. For this tutorial we will use https://webhook.site to quickly create a test webhook. Once you have your webhook address ready we will create a POST request as follows to create a new Outgoing Webhook configuration.

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

We can expect a 201 Created response containing the webhook url we provided. Our workflow is now ready to run.

Step 4. Post Data to our Webhook Source

In order to start an automation our workflow's webhook source will be listening for a POST request that contains a JSON body with key-value pairs. We can use the following request for example. Note, we are submitting this to the webhook url that returned in the Workflow payload from Step 1:

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

Currently this endpoint will return a 200 OK with an empty JSON dictionary as a payload. If you check the webhook.site you set up in the previous stage within a minute you should see an event occur that links to the the newly created document in your Google Drive.

In the Portant Workflow web app you will also be able to see the created outputs in the outputs page of your workflow. Congratulations! You have just created your first workflow and automation via the Portant Developer API!

For more details on all endpoints and resources please explore the API Reference. If you have any questions or feature requests for the API or Portant in general please don't hesitate to contact our customer success or integration teams directly. Happy Hacking!

...and if you were wondering... Jeremy is our Portant mascot! 🐨