> For the complete documentation index, see [llms.txt](https://docs.unifize.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unifize.com/developer/api-reference/processes.md).

# Processes

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/workflow" method="get" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/workflow/{id}" method="get" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/workflow" method="post" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/workflow/{id}" method="patch" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/workflow/{id}" method="delete" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

{% openapi src="/files/isyTxDSEytZTcy98sbBT" path="/workflow/{id}" method="post" %}
[openapi.json](https://3661566390-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJofjecEbyzuivtchBrHn%2Fuploads%2FBPIoFZMfZUt49MV9XS35%2Fopenapi.json?alt=media\&token=b6723cf7-2b00-4025-8d42-96c88a41ed5a)
{% endopenapi %}

## Examples

The examples below will take you through creating your first process, to customizing it, and deleting it.

### Creating a blank process

Let's start by creating a blank process using the [Create process](#workflow-1) API.

As a bare minimum, you need to provide the `title`key.

```json
{
    "title": "My first process"
}
```

Congratulations, you have created your first process!

### Adding a checklist field

A process, on its own, is not very useful. Let's add a checklist field.

{% hint style="info" %}
Checklist fields are added/updated/removed to a process through the`checklistFields`array.\
Each element in the array represents a checklist field.\
\
The checklist field configuration is present in the `attrs` key, which is a [Transit](https://github.com/cognitect/transit-format) encoded JSON string.\
\
To convert a JSON object to a Transit encoded JSON string, you can make use of various libraries which have implemented the Transit spec. When writing the string, ensure you use the `json-verbose`type, instead of `json`.\
\
In the examples below, we may opt to write JSON objects for readability. You will need to convert them to Transit before making the API call.
{% endhint %}

Here are some code snippets demonstrating how to convert a JSON object to a Transit encoded string:

{% tabs %}
{% tab title="JavaScript" %}
Using `transit-js`

```javascript
// npm install @cognitect/transit-js

import transit from '@cognitect/transit-js';

// Create a Transit writer
const writer = transit.writer('json-verbose');

// Convert your JSON object
const jsonObject = {
  key: "value",
  number: 42,
  active: true
};

const transitString = writer.write(jsonObject);
```

{% endtab %}

{% tab title="Python" %}
Using `transit`

```python
# pip install transit

import transit

# Create a Transit writer
writer = transit.writer('json-verbose')

# Convert your JSON object
json_object = {
  "key": "value",
  "number": 42,
  "active": True
}

transit_string = writer.write(json_object)
```

{% endtab %}

{% tab title="Java" %}
Using `transit-java`

<pre class="language-java"><code class="lang-java">// &#x3C;dependency>
//    &#x3C;groupId>com.cognitect&#x3C;/groupId>
//    &#x3C;artifactId>transit-java&#x3C;/artifactId>
//    &#x3C;version>1.0.0&#x3C;/version>
// &#x3C;/dependency>
<strong>
</strong><strong>import cognitect.transit.TransitFactory;
</strong>import cognitect.transit.Writer;

// Create a Transit writer
Writer writer = TransitFactory.writer(TransitFactory.Format.JSON_VERBOSE);

// Convert your JSON object
Map&#x3C;String, Object> jsonObject = new HashMap&#x3C;>();
jsonObject.put("key", "value");
jsonObject.put("number", 42);
jsonObject.put("active", true);

String transitString = writer.writeToString(jsonObject);
</code></pre>

{% endtab %}
{% endtabs %}

For example, given a checklist configuration as a JSON object such as

```json
{
  "text": {
    "label": "My Text Field",
    "settings": {
      "multiline": true,
      "placeholder": "FooBar",
      "defaultValue": "abc"
    }
  }
}
```

After converting it to Transit encoded JSON string and escaping it, it should look like

```json
"{\"~#text\":{\"label\":\"My Text Field\",\"settings\":{\"~#text\":{\"multiline\":true,\"placeholder\":\"FooBar\",\"defaultValue\":\"abc\"}}}}"
```

which can then be used in the payload as

```json
{
  "checklistFields": [
    {
      "attrs": "{\"~#text\":{\"label\":\"My Text Field\",\"settings\":{\"~#text\":{\"multiline\":true,\"placeholder\":\"FooBar\",\"defaultValue\":\"abc\"}}}}"
    }
  ]
}
```

#### Text Field

Available configuration

* Label
* Multiline
* Placeholder
* Default value
* Supressing notification for default value

```json
{
  "text": {
    "label": "My Text Field",
    "settings": {
      "multiline": true,
      "placeholder": "FooBar",
      "defaultValue": "abc",
      "suppressDefaultNotification": false
    }
  }
}
```

#### Date Field

Available configuration

* Label
* Placeholder

```json
{
  "date": {
    "label": "My Date Field",
    "settings": {
      "placeholder": "Click to add date"
    }
  }
}
```

#### User Field

Available configuration

* Label
* Default users
* Supressing notification for default value
* Multivalued toggle (default off)

```json
{
  "user": {
    "label": "My User Field",
    "settings": {
      "users": [
        "GJuQurhdUOR9liGN1xGuACGM7pD2",
        "tOnGEe0vK7ZZ1B9798FISTPcdCz2"
      ],
      "suppressDefaultNotification": false,
      "multiple": true
    }
  }
}
```

#### Number Field

Available configuration

* Label
* Placeholder
* Max value
* Min value
* Step (only applicable to the web UI)
* Default value
* Supressing notification for default value
* Minimum places to display after decimal point (only applicable to the web UI)
* Round off if number digits entered after decimal are more than configured (default `false`, only applicable to web UI)

```json
{
  "number": {
    "label": "My Number Field",
    "settings": {
      "placeholder": "5",
      "max": 10,
      "min": 5,
      "step": 2,
      "defaultValue": 20,
      "suppressDefaultNotification": false,
      "format": {
        "decimalPlaces": 0,
        "roundOff": false
      }
    }
  }
}
```

#### Section Field

Available Configuration

* Open by default (when status is set to)

```
{
  "section": {
    "label": "My Section",
    "settings": {
      "status": [10]
    }
  }
}
```

#### Subsection Field

```json
{
  "section": {
    "label": "My Subsection",
    "settings": {
      "level": 1
    }
  }
}
```

#### File Field

Available Configuration

* Label
* Multivalued toggle
* Show full preview toggle (only applicable to web UI)
* Sorting by file name through `name` or upload date using `date`&#x20;
* Default files
* Suppressing notification for default value
* Restrict upload sources

```json
{
  "file": {
    "label": "My File Field",
    "settings": {
      "multiple": true,
      "preview": true,
      "sortBy": "name",
      "defaultFile": [],
      "suppressDefaultNotification": false,
      "uploadOptions": [
        "computer",
        "unifize"
      ],
    }
  }
}
```

#### PDF Field

Available Configuration

* Label
* Optional file field to attach the PDF to, instead of PDF field
* Customize checklist behavior through `preview` (don't attach to checklist, attach only latest to checklist, attach all to checklist, respectively)
* Sequence of PDFs to stitch
  * Generate from a template using PDFGeneratorAPI, specify a `templateId`
  * Generate from a template using Adobe, specify `name` (a file, which is a template)
  * Generate from a native file, specify `fieldId` (a file field)
* Button text (by default `Generate PDF`)

```json
{
  "pdf": {
    "label": "My PDF Field",
    "settings": {
      "targetField": 30,
      "preview": "none | latest | all",
      "pdf": [
        {
          "seqNo": 0,
          "templateId": "123"
        },
        {
          "seqNo": 1,
          "name": "e097504a-9b09-409c-90ed-16ebbbc1eadd"
        },
        {
          "seqNo": 2,
          "fieldId": 10
        }
      ],
      "buttonText": "abc"
    }
  }
}
```

#### Revision Field

Available Configuration

* Label
* Who is authorized to create a revision
  * All the participants
  * The owner
  * Roles
  * Specific users
  * Groups
  * Users from a field (must be a user field)
* Who is authorized to mark a revision current
  * All the participants (of the current revision)
  * All the participants (of the revision being marked current)
  * The owner (of the current revision)
  * The owner (of the revision being marked current)
  * Roles
  * Specific users
  * Groups
  * Users from a field (of the current revision) (must be a user field)
  * Users from a field (of the revision being marked current) (must be a user field)
  * Only when a specific status is set
* Fields to copy
* Navigate to new revision automatically when created (Only applicable for web UI)
* Mandate writing comment when creating revision
* Automations
  * On the new current revision
    * Add participants
    * Remove participants
    * Add participants to fields
    * Send message
    * Update privacy
    * Unarchive
  * On the old current revision
    * Add participants
    * Remove participants
    * Add participants to fields
    * Send message
    * Update privacy
    * Update status
    * Auto archive

```json
{
  "revision": {
    "label": "revision",
    "settings": {
      "version": 2,
      "authorizedToCreate": {
        "allParticipants": true,
        "owner": true,
        "roles": [
          619
        ],
        "users": [
          "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
        ],
        "groups": [
          73
        ],
        "fields": [
          340443
        ]
      },
      "authorizedToMarkCurrent": {
        "allParticipants": true,
        "owner": true,
        "roles": [
          619
        ],
        "users": [
          "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
        ],
        "groups": [
          73
        ],
        "fields": [
          340443
        ],
        "statuses": [
          -2
        ],
        "allParticipantsOfCurrent": true,
        "ownerOfCurrent": true,
        "fieldsOfCurrent": [
          340443
        ]
      },
      "copyableFields": [
        340441
      ],
      "navigateToNewRevision": true,
      "commentRequired": true,
      "automations": {
        "newCurrent": [
          {
            "active": true,
            "action": "addParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "removeParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "addParticipantsFromFields",
            "data": [
              340443
            ]
          },
          {
            "active": true,
            "action": "sendMessage",
            "data": "This is the current version now."
          },
          {
            "active": true,
            "action": "updatePrivacy",
            "data": {
              "mode": "content",
              "whitelistedUsers": [
                "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
              ]
            }
          },
          {
            "active": true,
            "action": "archive",
            "data": false
          }
        ],
        "oldCurrent": [
          {
            "active": true,
            "action": "addParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "removeParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "addParticipantsFromFields",
            "data": [
              340443
            ]
          },
          {
            "active": true,
            "action": "sendMessage",
            "data": "This is no longer the current version."
          },
          {
            "active": true,
            "action": "updatePrivacy",
            "data": {
              "mode": "full",
              "whitelistedUsers": [
                "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
              ]
            }
          },
          {
            "active": true,
            "action": "updateStatus",
            "data": -2
          },
          {
            "active": true,
            "action": "archive",
            "data": true
          }
        ]
      }
    }
  }
}
```

#### Approval Field

Available Configuration

* Label
* Show "Request Approval" button
* Minimum required approvers
* Required approvers
  * Set to `some` to let anyone sign
  * Set to `adhoc` to dynamically choose who can sign (Will override `Minimum required approvers` and `Show "Request Approval" button` )
* Who can approve
  * All participants
  * The owner
  * Prevent requester from approving
  * Users
  * Roles
  * Groups
  * Users in field(s) (Must be a user field)
* Who can cancel
  * All participants
  * Approvers/signatories
  * Prevent requester from approving
  * Users
  * Roles
  * Groups
  * Users in field(s) (Must be a user field)
  * Can cancel when
    * Allow cancellation post approval (`allowCancelOnApproval`)
    * Allow cancelling of approvals in progress\
      (`canCancelPartialApproval`)
* Require comments
  * During approval
  * During rejection
  * During cancellation
* Contingent of previous approval(s)
  * Hide/disable when inactive
  * Disable previous approvals while field is approved or in progress
* Lock fields
  * When mode is set to `new`, `fields` will be locked during and post approval/rejection
  * When mode is set to `inherit`, fields will continue to be locked under previous approval
* Lock status
  * On start / request of signature
  * On approval
  * On rejection
  * On cancellation
* Cancel all contingent approvals on rejection
* Automations
  * On start / request of signature
    * Update status
    * Add participants
    * Remove participants
    * Change owner
    * Send message
    * Update privacy
  * On approval
    * Update status
    * Add participants
    * Remove participants
    * Change owner
    * Send message
    * Update privacy
    * Mark revision as current
  * On rejection
    * Update status
    * Add participants
    * Remove participants
    * Change owner
    * Send message
    * Update privacy
  * On cancellation
    * Update status
    * Add participants
    * Remove participants
    * Change owner
    * Send message
    * Update privacy

{% code fullWidth="false" %}

```json
 {
  "approval": {
    "label": "approval",
    "settings": {
      "version": 2,
      "minApprovers": 1,
      "requiredApprovers": "some | adhoc",
      "showRequestApprovalButton": true,
      "approvers": {
        "allParticipants": true,
        "owner": true,
        "preventRequester": true,
        "users": [
          "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
        ],
        "roles": [
          619
        ],
        "groups": [
          73
        ],
        "fields": [
          340443
        ]
      },
      "cancellers": {
        "allParticipants": true,
        "approvers": true,
        "users": [
          "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
        ],
        "roles": [
          619
        ],
        "groups": [
          73
        ],
        "fields": [
          340443
        ]
      },
      "allowCancelOnApproval": true,
      "canCancelPartialApproval": true,
      "requireComment": true,
      "requireRejectionComment": true,
      "requireCancellationComment": true,
      "contingentApprovals": [
        340458
      ],
      "inactiveBehavior": "disable | hide",
      "canCancelContingentApprovals": true,      
      "cancelContingentApprovalsOnRejection": true,
      "lockFields": {
        "mode": "new | inherit",
        "fields": [
          340441,
          340443
        ]
      },            
      "lockStatus": {
        "onStart": true,
        "onApproval": true,
        "onCancellation": true,
        "onRejection": true
      },
      "automations": {
        "started": [
          {
            "active": true,
            "action": "updateStatus",
            "data": -2
          },
          {
            "active": true,
            "action": "addParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "removeParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "updateOwner",
            "data": "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
          },
          {
            "active": true,
            "action": "sendMessage",
            "data": "abc"
          },
          {
            "active": true,
            "action": "updatePrivacy",
            "data": {
              "mode": "content",
              "whitelistedUsers": [
                "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
              ]
            }
          },
          {
            "active": false,
            "action": "markRevisionAsCurrent",
            "data": null
          }
        ],
        "approved": [
          {
            "active": true,
            "action": "updateStatus",
            "data": -2
          },
          {
            "active": true,
            "action": "addParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "removeParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "updateOwner",
            "data": "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
          },
          {
            "active": true,
            "action": "sendMessage",
            "data": "abc"
          },
          {
            "active": true,
            "action": "updatePrivacy",
            "data": {
              "mode": "content",
              "whitelistedUsers": [
                "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
              ]
            }
          },
          {
            "active": true,
            "action": "markRevisionAsCurrent",
            "data": null
          }
        ],
        "rejected": [
          {
            "active": true,
            "action": "updateStatus",
            "data": -2
          },
          {
            "active": true,
            "action": "addParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "removeParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "updateOwner",
            "data": "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
          },
          {
            "active": true,
            "action": "sendMessage",
            "data": "abc"
          },
          {
            "active": true,
            "action": "updatePrivacy",
            "data": {
              "mode": "content",
              "whitelistedUsers": [
                "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
              ]
            }
          },
          {
            "active": false,
            "action": "markRevisionAsCurrent",
            "data": null
          }
        ],
        "cancelled": [
          {
            "active": true,
            "action": "updateStatus",
            "data": -2
          },
          {
            "active": true,
            "action": "addParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "removeParticipants",
            "data": [
              "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
            ]
          },
          {
            "active": true,
            "action": "updateOwner",
            "data": "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
          },
          {
            "active": true,
            "action": "sendMessage",
            "data": "abc"
          },
          {
            "active": true,
            "action": "updatePrivacy",
            "data": {
              "mode": "content",
              "whitelistedUsers": [
                "jA6d4gH0oMfGd90uKCrFyjMnrvt2"
              ]
            }
          },
          {
            "active": false,
            "action": "markRevisionAsCurrent",
            "data": null
          }
        ]
      }
    }
  }
}
```

{% endcode %}

#### Conversation Field

Available Configuration

* Label
* Set as child or parent conversation
* Multiselect toggle
* Allow selecting existing conversations through `select`
* Allow creating new conversations through `create`
* Autofill related conversation
* Specify type of conversation
* Process id through `workflow` (Only valid if `type` is set to `"workflow"`)
* Configure embedded fields (Only valid if `type` is set to `workflow`)
* Show field names in preview
* Show status and due date
* Sort conversations
* Select existing conversations by criteria
* Show/hide archived conversations
* Suppress title hyperlink to the record

```json
{
  "conversation": {
    "label": "My Conversation Field",
    "settings": {
      "child": true,
      "multiple": true,
      "select": true,
      "create": true,
      "autoFillRelated": true,
      "type": "group | workflow | approval | conversation | task",
      "workflow": 10,
      "fields": [50 60],
      "showFieldNames": false,
      "showMetaData": false,
      "sortBy": "added | created",
      "selectExistingBy": " | title",
      "showArchived": false,
      "disableTitleHyperlink": false
    }
  }
}
```

#### Linked Field

Available Configuration

* Label
* Specify process and embedded fields
* Allow linking multiple records
* Autofill related records
* Allow archived conversations
* Show compressed preview
* Show status, owner and due date
* Disable title hyperlink to record
* Set current process as child or parent
* Allow selecting existing record
* Allow creating new record
* Allow manual revision linking
* Select existing record by criteria
  * Title

```json
{
  "link": {
    "label": "linked",
    "settings": {
      "workflow": 16388,
      "fields": [
        340441
      ],
      "multiple": true,
      "autoFillRelated": true,
      "showArchived": true,      
      "showCompressedPreview": true,
      "showMetaData": true,
      "disableTitleHyperlink": true,
      "child": false,
      "select": true,
      "create": true,      
      "type": "workflow",
      "alwaysAllowManualLinks": true,
      "selectExistingBy": "title"
    }
  }
}
```

#### Form Fields

Available Configuration

* Label
* Allow multiple
* Specify form templates

```json
{
  "form": {
    "label": "form",
    "settings": {
      "multiple": true,
      "selectedForms": [
        6217
      ]
    }
  }
}
```

### Deleting a checklist field

To delete a checklist field, use the [Update process](#workflow-id-1) API and remove the checklist field you want to delete from the `checklistFields` array.

### Restoring a checklist field

To restore a checklist field, use a combination of the [Get process](#workflow-id) and [Update process](#workflow-id-1)  APIs.

The [Get process](#workflow-id)  API should include the field you want in its response, even if it is deleted.&#x20;

To restore it, set the values of `deleted`, `deletedAt` and `deletedBy` to `null` when using the [Update process](#workflow-id-1) API. Make sure you do not modify the rest of the checklist field object.