Workflows

Overview

The Workflow resources represents the stages of an automation that -in its simplest form- will transform source data to output documents.

Fields

Field	Type	Editable	Description
id	String		The unique ID of the workflow. This is used to reference the specific workflow in all requests.
name	String		The name of the workflow.
color	String		The colour of the workflow icon in Portant Workflow as a hex string, prefixed with #.
icon	String		The name of the icon used in Portant Workflow
status	String		The current status of the workflow. Can be one of the following: - "COMPLETE": The workflow is runnable - "INCOMPLETE": The workflow requires further configuration before it can be run - "ARCHIVED": The workflow is no longer usable
autoCreate	Boolean		The workflow will be listening to events via its source and will create a new automation when the autoCreate flag is enabled.
owner	Owner		The owner of this workflow.
team	Team		The team this workflow belongs to.
source	Source		The source of data for this workflow.
documents	Document		The template documents for this workflow.
outgoingWebhook	Outgoing Webhook		The outgoing webhook of this workflow, used to listen for automation events from the workflow.
createdByApi	Boolean		Flag indicating this workflow was created via the Developer API
createdAt	String		An ISO Format timestamp representing when the workflow was created.
updatedAt	String		An ISO Format timestamp representing when the workflow was last updated.

Example

```json
{
    "id": "wkf_kGQK9PBWDT1JCr",
    "name": "Invoice Workflow",
    "icon": "DocumentText",
    "color": "#cccccc",
    "status": "COMPLETE",
    "autoCreate": true,
    "owner": {
        "id": "usr_DsH4TGYXs4XPpB",
        "name": "Blake Lockley",
        "email": "[email protected]"
    },
    "team": null,
    "source": {
        "id": "src_NZHJYjlgrvklHb",
        "sourceType": "WEBHOOK",
        "sourceFields": [
            "Order Number",
            "LineItem.Name",
            "LineItem.Price",
        ],
        "webhookUrl": "https://webhooks.portant.co/50c7912b14c7acbe9df32521ec60a27c"
    },
    "documents": [
        {
            "id": "doc_5LGGqC5S78RNS0",
            "documentType": "GOOGLE_DOCS",
            "file": {
                "id": "1uNfBHAKhcgRsiftb7xRpTJRS0k9LY1iX1gUnTOE0zU4",
                "name": "Complete Workflow Please - [Template]",
                "url": "https://docs.google.com/document/d/1uNfBHAKhcgRsiftb7xRpTJRS0k9LY1iX1gUnTOE0zU4/edit?usp=drivesdk",
                "mimeType": "application/vnd.google-apps.document"
            },
            "outputName": "Document for {{First Name}}",
            "pdfPassword": "jeRe/\/\eyWaZH3re",
            "enablePdfPassword": true,
            "enablePdfPreventCopy": false,
            "previewUrl": "https://preview.portant.co/doc_5LGGqC5S78RNS0"
        }
    ],
    "outgoingWebhook": {
        "id": "owc_XY1Ys4gqrpX8cp",
        "webhookUrl": "https://webhook.site/d22c56ab-40ac-4f9a-93ef-02520235c0da"
    },
    "createdByApi": true,
    "createdAt": "2024-08-12T16:20:44.346666+10:00",
    "updatedAt": "2024-08-12T16:20:48.408357+10:00"
}
```

Endpoints

List all Workflows

GET /workflows/

Retrieve the list of Workflow objects that are owned by- or shared with the team of the user of the API.

Responses

Status	Body
200 OK	Array<Workflow>
403 Unauthorised	Error

Create a Workflow

POST /workflows/

Create a new workflow.

Request

A partial Workflow object as JSON. The only field required to created the simplest form of workflow is the name field.

{
    name: "A simple workflow"
}

Alternatively, an entire complete workflow can be created via a single POST request by providing the optional subcomponents with their respective required fields as outlined below. Fields suffixed with ? are not required.

{
    name: "A complete Workflow from Scratch",
    color?: "#...",
    icon?: "...",
    source?: {
        "sourceFields": ["Field Name 1", "Field Name 2"]
    },
    document?: {
        fileId: "<google file id>"
    },
    outgoingWebhook?: {
        webhookUrl: "<webhook url for event listening>"
    }
}

Responses

Status	Body
201 Created	Workflow
400 Bad Request	Error
403 Unauthorised	Error

Retrieve a Workflow

GET /workflows/<wkf_id>/

Retrieve a specific workflow via its id.

Responses

Status	Body
200 OK	Workflow
403 Unauthorised	Error
404 Not Found	Error

Update a Workflow

PATCH /workflows/<wkf_id>/

Update a specific workflow via its id.

Request

A partial Workflow object as JSON. Fields suffixed with ? are not required.

{
    name?: "...",
    color?: "#...",
    icon?: "..."
 }

Response

Status	Body
200 OK	Workflow
400 Bad Request	Error
403 Unauthorised	Error
404 Not Found	Error

Delete a Workflow

DELETE /workflows/<wkf_id>/

Delete a specific workflow via its id. This method does not actually delete the workflow but sets its status to "ARCHIVED". Deleted workflows can be restored by contacting our custom success team.

Response

Status	Body
204 No Content
400 Bad Request	Error
403 Unauthorised	Error
404 Not Found	Error