# 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`
// <dependency>
// <groupId>com.cognitect</groupId>
// <artifactId>transit-java</artifactId>
// <version>1.0.0</version>
// </dependency>
import cognitect.transit.TransitFactory;
import cognitect.transit.Writer;
// Create a Transit writer
Writer writer = TransitFactory.writer(TransitFactory.Format.JSON_VERBOSE);
// Convert your JSON object
Map<String, Object> jsonObject = new HashMap<>();
jsonObject.put("key", "value");
jsonObject.put("number", 42);
jsonObject.put("active", true);
String transitString = writer.writeToString(jsonObject);
{% 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`
* 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.
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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.unifize.com/developer/api-reference/processes.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.