# Workflows

## Overview

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

## Fields

<table><thead><tr><th width="224">Field</th><th width="139">Type</th><th width="94" data-type="checkbox">Editable</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>String</td><td>false</td><td>The unique ID of the workflow. This is used to reference the specific workflow in all requests.</td></tr><tr><td>name</td><td>String</td><td>true</td><td>The name of the workflow.</td></tr><tr><td>color</td><td>String</td><td>true</td><td>The colour of the workflow icon in Portant Workflow as a hex string, prefixed with <code>#</code>.</td></tr><tr><td>icon</td><td>String</td><td>true</td><td>The name of the icon used in Portant Workflow</td></tr><tr><td>status</td><td>String</td><td>false</td><td>The current status of the workflow. Can be one of the following:<br>- "COMPLETE": The workflow is runnable<br>- "INCOMPLETE": The workflow requires further configuration before it can be run<br>- "ARCHIVED": The workflow is no longer usable</td></tr><tr><td>autoCreate</td><td>Boolean</td><td>false</td><td>The workflow will be listening to events via its source and will create a new automation when the autoCreate flag is enabled.</td></tr><tr><td>owner</td><td><a href="owner">Owner</a></td><td>false</td><td>The owner of this workflow.</td></tr><tr><td>team</td><td><a href="team">Team</a></td><td>false</td><td>The team this workflow belongs to.</td></tr><tr><td>source</td><td><a href="source">Source</a></td><td>false</td><td>The source of data for this workflow.</td></tr><tr><td>documents</td><td><a href="document">Document</a></td><td>false</td><td>The template documents for this workflow.</td></tr><tr><td>outgoingWebhook</td><td><p><a href="broken-reference">Outgoing</a></p><p><a href="broken-reference">Webhook</a></p></td><td>false</td><td>The outgoing webhook of this workflow, used to listen for automation events from the workflow.</td></tr><tr><td>createdByApi</td><td>Boolean</td><td>false</td><td>Flag indicating this workflow was created via the Developer API</td></tr><tr><td>createdAt</td><td>String</td><td>false</td><td>An <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO Format</a> timestamp representing when the workflow was created.</td></tr><tr><td>updatedAt</td><td>String</td><td>false</td><td>An <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO Format</a> timestamp representing when the workflow was last updated.</td></tr></tbody></table>

### Example

````
```json
{
    "id": "wkf_kGQK9PBWDT1JCr",
    "name": "Invoice Workflow",
    "icon": "DocumentText",
    "color": "#cccccc",
    "status": "COMPLETE",
    "autoCreate": true,
    "owner": {
        "id": "usr_DsH4TGYXs4XPpB",
        "name": "Blake Lockley",
        "email": "blake@portant.co"
    },
    "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.&#x20;

```
{
    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.&#x20;

```
{
    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.&#x20;

```
{
    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 |