' \
--data-raw '{
"operation" : "createRequest",
"args" : {
"input" : {
"processName" : "PROCESS_NAME",
"processVersion" : 1
}
}
}'
```
To give or revoke system operations permissions to or from specific users, refer to the [System operations allowed users](https://docs.advantys.com/docs/admin/configuration-panel#system-operations-allowed-users-usernames-separated-by-commas) setting in the **Security** section on the Configuration Panel **Integration** tab; alternately, you can edit the `ProcessesRuntimeWebServiceAllowedUsers` setting in the `\wfgen\web.config` file.
## Sending data in JSON
The incoming webhook application receives your HTTP POST request payload formatted as a JSON object.
Using the URL provided, you can post HTTP requests from external applications (e.g. Postman) to WorkflowGen in order to execute the available operations in your WorkflowGen application. For operations that require you to provide an object ID, the object ID value can be retrieved by using the [GraphQL](https://docs.workflowgen.com/integration/8.3/graphql) API. In most cases, object numbers can be used instead of IDs in operation payloads.
In case of an error, you will get a response payload providing error details such as:
```
{
"error": "Advantys.Workflow.ServiceFacade: CreateRequest error: A process ID or name is required"
}
```
### Curl example
The requests should respect the structure shown in this example, where `operation` refers to the name of the operation to execute, and `args` contains the `input` node that groups all of the request parameters to perform the operation.
To create a new request, the `processName` parameter is required. The `processVersion` parameter is optional and is used to find the correct process you want to use to create your request.
#### Request payload:
```json
curl -u yourusername -X POST -H "Content-Type: application/json" -d '{
"operation": "createRequest",
"args": {
"input": {
"processName": "2_LEVELS_APPROVAL",
"processVersion": 1
}
}
}' http://localhost/wfgen/hooks/yourtoken
```
#### Response payload:
The response payload will be structured as follows:
```
{
"clientMutationId": null,
"requestId": "UmVxdWVzdDoxNzI4",
"number": 10,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Parameters
| **Parameter** | **Description** |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `processName` | Process name (required) |
| `processVersion` | Process version, used to find the correct process you want to use to create the request |
| `clientMutationId` | This parameter will be null if the request creator did not define it in the request payload |
| `requestId` | ID of newly created request |
| `number` | Number of newly created request |
| `onBehalfOf` | This parameter contains the delegator ID; however, if the request was not created in delegation mode, its value will be null |
| `onBehalfOfUserName` | This parameter contains the delegator username; however, if the request was not created in delegation mode, its value will be null |
## OpenAPI v2 endpoints
As of version 7.17.0, incoming webhooks now offer a new endpoint that supports the [OpenAPI v2 specification](https://swagger.io/docs/specification/2-0/basic-structure/) for operation definitions and another endpoint for operation execution. This allows for seamless integration with other OpenAPI-ready solutions such as Swagger, Microsoft Flow, Azure Logic Apps and Postman.
### Webhook operation definitions
Use this endpoint to retrieve webhook operation definitions based on the OpenAPI v2 specification (in JSON format).
```
URI: /wfgen/hooks/openapi/v2
```
### Webhook operation execution
Use this endpoint to execute a webhook operation using HTTP POST, replacing `:operation` with the name of the incoming webhook operation (e.g. `createRequest`).
```
URI: /wfgen/hooks/operations/:operation
```
#### Required parameters
* `:operation`: Name of the incoming webhook operation defined in the URI\
\
✏️ **Note:** The operation name is not required inside the request payload.
* `x-wfgen-hooktoken`: Webhook token value specified in the HTTP request header, which is the same token value as used in a classic incoming webhooks URL
* Properties with an asterisk `*` next to their name
{% hint style="info" %}
Other required or optional parameters specific to the webhook operation might be needed.
{% endhint %}
## Request operations
### Create a new request
{% hint style="info" %}
o create a new request from the webhooks API, make sure that sub-process mode is enabled with public access on the target process. (See the [Process Definition](https://docs.workflowgen.com/admin/process-definition) section in the [WorkflowGen Administration Guide](https://docs.advantys.com/workflowgen-administration-module-reference-guide/) for more information.)
{% endhint %}
#### Request payload:
```
{
"operation": "createRequest",
"args": {
"input": {
"processName": "2_LEVELS_APPROVAL",
"processVersion": 1
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"requestId": "UmVxdWVzdDoxNzI4",
"number": 1728,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
A parameter's array can be included in the `createRequest` operation payload. Be aware that a data with the same name and data type must previously exist in the process for each parameter in the array to store the parameter's value. The following example shows how to send parameters corresponding to the four supported data types (TEXT, NUMERIC, DATETIME, and FILE).
#### Request payload:
```
{
"operation": "createRequest",
"args": {
"input": {
"processName": "2_LEVELS_APPROVAL",
"processVersion": 1,
"parameters": [
{
"name": "TEXT",
"textValue": "My text parameter"
},
{
"name": "NUMERIC",
"numericValue": 5
},
{
"name": "DATE",
"dateTimeValue": "2017-02-23T20:46:00Z"
},
{
"name": "FILE",
"fileValue": {
"name": "TestFile.txt",
"contentType": "text/plain",
"size": 616,
"url": "file:///c:/TestFile.txt",
"updatedAt": "2017-02-21T15:06:38Z"
}
}
]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"requestId": "UmVxdWVzdDoxNzY1",
"number": 1765,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `processId` | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `processName` | String | Process name |
| `processVersion` | Int | Process version, used to find the correct process you want to use to create the request |
| `isTest` | Boolean | Indicates if the process is in test |
| `parameters` | Array | Array of parameters (see [Parameter definitions](#parameter-definitions)) |
| `onBehalfOf` | Base64-encoded string | User identifier that is used by the user to perform the mutation on behalf of another person, with the pattern `[User:1]` where `1` is the user identifier from the database |
### Update a request dataset
A request dataset context can be updated by adding a parameter array. In this case a request number or a request ID should be provided.
This operation requires users to have system access to perform it. This can be configured in the **System operations allowed users** field under **Security** on the **Integration** tab in the **Configuration Panel**.
#### Request payloads:
```
{
"operation": "updateRequestDataset",
"args": {
"input": {
"number": 1750,
"parameters": [
{
"name": "NEW_PARAMETER",
"textValue": "My parameter"
}
]
}
}
}
```
```
{
"operation": "updateRequestDataset",
"args": {
"input": {
"id": "UmVxdWVzdDoxMDAw",
"parameters": [
{
"name": "NEW_PARAMETER",
"textValue": "My parameter"
}
]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"requestId": "UmVxdWVzdDoxNzIx",
"parameters": [
{
"name": "NEW_PARAMETER",
"textValue": "My parameter"
}
]
}
```
For more information on FILE parameter manipulations when sent within incoming webhook payloads, see the [File upload](#file-upload) section.
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Request identifier with the pattern `[Request:1]` where `1` is the request identifier from the database |
| `number` | Int | Request number |
| `parameters` | Array | Array of parameters (see [Parameter definitions](#parameter-definitions)) |
### Cancel a request
You can cancel a request by using the request number or the request ID.
#### Request payloads:
```
{
"operation": "cancelRequest",
"args": {
"input": {
"number": 1728
}
}
}
```
```
{
"operation": "cancelRequest",
"args": {
"input": {
"id": "UmVxdWVzdDoxNzI4"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"requestId": "UmVxdWVzdDoxNzI4",
"number": 1728,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Request identifier with the pattern `[Request:1]` where `1` is the request identifier from the database |
| `number` | Int | Request number |
| `notifyParticipant` | Boolean | Indicates if participant members have to be notified |
| `onBehalfOf` | Base64-encoded string | User identifier that is used by the user to perform the mutation on behalf of another person, with the pattern `[User:1]` where `1` is the user identifier from the database |
### Delete a request
A request can be deleted by using the request number or the request ID.
#### Request payloads:
```
{
"operation": "deleteRequest",
"args": {
"input": {
"number": 1728
}
}
}
```
```
{
"operation": "deleteRequest",
"args": {
"input": {
"id": "UmVxdWVzdDoxNzI4"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Request identifier with the pattern `[Request:1]` where `1` is the request identifier from the database |
| `number` | Int | Request number |
## Action operations
### Complete an action
To complete an action, provide the request number and the action number, or the action ID.
#### Request payloads:
```
{
"operation": "completeAction",
"args": {
"input": {
"requestNumber": 1765,
"number": 1,
"parameters": [
{
"name": "NEW_PARAMETER",
"textValue": "My parameter"
}
]
}
}
}
```
```
{
"operation": "completeAction",
"args": {
"input": {
"id": "QWN0aW9uOjE3NTktLS0x"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"actionId": "QWN0aW9uOjE3NTktLS0x",
"number": 1,
"requestNumber": 1759,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
To complete an action, a parameter array can be included in the request payload arguments.
#### Request payload:
```
{
"operation": "completeAction",
"args": {
"input": {
"requestNumber": 1765,
"number": 1,
"parameters": [
{
"name": "NEW_PARAMETER",
"direction": "IN",
"type": "TEXT",
"textValue": "My parameter"
}
]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"actionId": "QWN0aW9uOjE3NjUtLS0x",
"number": 1,
"requestNumber": 1765,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Action identifier with the pattern `[Action:1---2]` where `1` is the request identifier from the database and `2` is the action identifier from the database |
| `requestNumber` | Int | Request number |
| `number` | Int | Action number |
| `activityName` | String | Activity name |
| `parameters` | Array | Array of parameters (see [Parameter definitions](#parameter-definitions)) |
| `onBehalfOf` | Base64-encoded string | User identifier that is used by the user to perform the mutation on behalf of another person, with the pattern `[User:1]` where `1` is the user identifier from the database |
### Complete a form action
#### Request payload:
```
{
"operation": "completeFormAction",
"args": {
"input": {
"requestNumber": 1765,
"number": 1,
"parameters": [
{
"name": "NEW_PARAMETER",
"textValue": "My parameter"
}
]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"actionId": "QWN0aW9uOjE3NjUtLS0x",
"number": 1,
"requestNumber": 1765,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Action identifier with the pattern `[Action:1---2]` where `1` is the request identifier from the database and `2` is the action identifier from the database |
| `requestNumber` | Int | Request number |
| `number` | Int | Action number |
| `activityName` | String | Activity name |
| `parameters` | Array | Array of parameters (see [Parameter definitions](#parameter-definitions)) |
| `onBehalfOf` | Base64-encoded string | User identifier used by the user to perform the mutation on behalf of another person with the pattern `[User:1]` where `1` is the user identifier from the database |
### Cancel an action
To cancel an action, provide the request number and the action number, or the action ID. The following conditions must be met:
* The viewer and the user (if they don't share the same identity, as in delegation mode) must have access to the request.
* The action must be open.
* The action must have a cancel or default exception defined in the transition.
* The viewer is:
* an administrator or process folder manager\
\
**OR**
* a supervisor with cancellation rights\
\
**OR**
* the action assignee.
#### Request payloads:
```
{
"operation": "cancelAction",
"args": {
"input": {
"requestNumber": 1759,
"number": 2
}
}
}
```
```
{
"operation": "cancelAction",
"args": {
"input": {
"id": "QWN0aW9uOjEwMDAtLS0x"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"actionId": "QWN0aW9uOjE3NTktLS0y",
"number": 2,
"requestNumber": 1759,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Action identifier with the pattern `[Action:1---2]` where `1` is the request identifier from the database and `2` is the action identifier from the database |
| `requestNumber` | Int | Request number |
| `number` | Int | Action number |
| `type` | String | Cancellation type:
CANCEL: Cancellation exceptionERROR: Error exception
|
| exception: {
message\*,
source
}
| Object {
String,
String
}
| Exception:
- Exception message
- Exception source
|
| `onBehalfOf` | Base64-encoded string | User identifier used by the user to perform the mutation on behalf of another person with the pattern `[User:1]` where `1` is the user identifier from the database |
### Cancel a request's actions by name
All of the actions with the same name in a request can be cancelled at the same time by using their name in this operation payload. The following conditions are met:
* The viewer and the user (if they do not share the same identity, as in delegation mode) must have access to the request.
* The action must be open.
* The action must have a cancel or default exception defined in the transition.
* The viewer is:
* an administrator or a process folder manager\
\
**OR**
* a supervisor with cancellation rights\
\
**OR**
* the action assignee.
#### Request payload:
```
{
"operation": "cancelRequestActionsByName",
"args": {
"input": {
"requestNumber": 4399,
"activityName": "Initiates"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"actionIds": [
"QWN0aW9uOjQzOTktLS0x",
"QWN0aW9uOjQzOTktLS0y",
"QWN0aW9uOjQzOTktLS0z"
],
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `requestNumber` | Int | Request number |
| `activityName`\* | String | Activity name |
| `type` | String | Cancellation type:
CANCEL: Cancellation exceptionERROR: Error exception
|
| exception: {
message\*,
source
}
| Object {
String,
String
}
| Exception:
- Exception message
- Exception source
|
| `onBehalfOf` | Base64-encoded string | User identifier used by the user to perform the mutation on behalf of another person with the pattern `[User:1]` where `1` is the user identifier from the database |
### Assign an action
To assign an action, provide the request number and the action number, or the action ID; you must also provide the `assigneeUserName` or the `assigneeId`.
#### Request payloads:
```
{
"operation": "assignAction",
"args": {
"input": {
"requestNumber": 1751,
"number": 2,
"assigneeUserName": "johnsmith"
}
}
}
```
```
{
"operation": "assignAction",
"args": {
"input": {
"id": "QWN0aW9uOjEwMDAtLS0x",
"assigneeId": "QXNzaWduZWU6MQ=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"actionId": "QWN0aW9uOjE3NTEtLS0y",
"number": 2,
"requestNumber": 1751,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Action identifier with the pattern `[Action:1---2]` where `1` is the request identifier from the database and `2` is the action identifier from the database |
| `assigneeId`\* | Base64-encoded string | User identifier of the person assigned to the action with the pattern `[User:1]` where `1` is the user identifier from the database |
| `requestNumber` | Int | Request number |
| `number` | Int | Action number |
| `onBehalfOf` | Base64-encoded string | User identifier used by the user to perform the mutation on behalf of another person with the pattern `[User:1]` where `1` is the user identifier from the database |
### Cancel an action assignment
To cancel an action assignment, you should provide the request number and the action number, or the action ID.
#### Request payloads:
```
{
"operation": "cancelActionAssignment",
"args": {
"input": {
"requestNumber": 1751,
"number": 2
}
}
}
```
```
{
"operation": "cancelActionAssignment",
"args": {
"input": {
"id": "QWN0aW9uOjEwMDAtLS0x"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"actionId": "QWN0aW9uOjE3NTEtLS0y",
"number": 2,
"requestNumber": 1751,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id` | Base64-encoded string | Action identifier with the pattern `[Action:1---2]` where `1` is the request identifier from the database and `2` is the action identifier from the database |
| `requestNumber` | Int | Request number |
| `number` | Int | Action number |
| `onBehalfOf` | Base64-encoded string | User identifier used by the user to perform the mutation on behalf of another person with the pattern `[User:1]` where `1` is the user identifier from the database |
## End-user operations
### Create a new favorite
The incoming webhook application lets users add processes and views to their favorites lists using the process or view IDs.
#### Request payload:
```
{
"operation": "createFavorite",
"args": {
"input": {
"itemId": "UHJvY2VzczoxMTA="
}
}
}
```
The above code will create a favorite using the process or view description, but adding a custom description is also possible, as shown in the following example:
#### Request payload:
```
{
"operation": "createFavorite",
"args": {
"input": {
"itemId": "UHJvY2VzczoxMTA=",
"description": "My custom description"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"favoriteId": "RmF2b3JpdGU6MTQ="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `itemId`\* | Base64-encoded string | Process or view identifier with the pattern `[Process:1]` or `[View:1]` where `1` is the identifier from the database |
| `description` | String | Favorite description |
### Update a favorite
The incoming webhook application lets users update an existing favorite process or view by using its favorite ID.
#### Request payload:
```
{
"operation": "updateFavorite",
"args": {
"input": {
"id": "RmF2b3JpdGU6MTQ=",
"description": "Updated description"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"favoriteId": "RmF2b3JpdGU6MTQ="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Favorite identifier with the pattern `[Favorite:1]` where `1` is the favorite identifier from the database |
| `description` | String | Favorite description |
### Delete a favorite
The incoming webhook application lets users delete an existing favorite process or view from their favorites list by using its favorites ID.
#### Request payload:
```
{
"operation": "deleteFavorite",
"args": {
"input": {
"id": "RmF2b3JpdGU6MTQ="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Favorite identifier with the pattern `[Favorite:1]` where `1` is the favorite identifier from the database |
### Add a comment
The incoming webhook application lets users add comments to requests. This operation requires that the portal comments feature be enabled.
#### Request payload:
```
{
"operation": "addComment",
"args": {
"input": {
"subjectId": "UmVxdWVzdDo0MzY1",
"message": "This is my comment"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"commentId": "Q29tbWVudDo0MzY1LS0tMg=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `clientMutationId` | String | Client mutation identifier |
| `subjectId`\* | Base64-encoded string | Request identifier on which the comment will be added with the pattern `[Request:1]` where `1` is the request identifier from the database |
| `message`\* | String | New comment message |
### Update a comment
Users can update comments if they are administrators, process manager of the process or process supervisor, or standard users who are members of the process participants, have write permissions, and are the comment author. This operation requires that the portal comments feature be enabled.
#### Request payload:
```
{
"operation": "updateComment",
"args": {
"input": {
"id": "Q29tbWVudDo0MzY1LS0tMg==",
"message": "This is my updated comment"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"commentId": "Q29tbWVudDo0MzY1LS0tMg=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Comment identifier with the pattern `[Comment:1---2]` where `1` is the request identifier from the database and `2` is the comment identifier from the database |
| `message`\* | String | Updated comment message |
### Remove a comment
The incoming webhook application lets users remove comments from requests. This operation requires that the portal comments feature be enabled.
#### Request payload:
```
{
"operation": "removeComment",
"args": {
"input": {
"id": "Q29tbWVudDo0MzY1LS0tMg=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Comment identifier with the pattern `[Comment:1---2]` where `1` is the request identifier from the database and `2` is the comment identifier from the database |
## Delegation operations
### Create a delegation
Standard users can only create delegations for themselves; only administrators can create a delegation for another user. This operation requires that the portal delegation feature be enabled.
#### Request payload:
```
{
"operation": "createDelegation",
"args": {
"input": {
"delegatorId": "VXNlcjox",
"delegateeId": "VXNlcjoy",
"processId": "UHJvY2Vzczoz",
"participantId": "TG9jYWxQcm9jZXNzUGFydGljaXBhbnQ6OA==",
"start": "2017-04-23T18:25:43.000Z",
"end": "2017-11-23T18:25:43.000Z",
"notifyDelegatee": true
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"delegationId": "RGVsZWdhdGlvbjoxMA=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `delegatorId` | Base64-encoded string | User identifier that is delegating its requests and actions to another person, with the pattern `[User:1]` where `1` is the user identifier from the database |
| `delegateeId`\* | Base64-encoded string | User identifier to whom the requests and actions are delegated from the delegator, with the pattern `[User:1]` where `1` is the user identifier from the database |
| `processId` | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `participantId` | Base64-encoded string | Participant identifier, with the pattern `[GlobalParticipant:1]` or `[LocalProcessParticipant:1]` where `1` is the participant identifier from the database |
| `start` | DateTime | Indicates the date and time (`ISO 8601` date format) when the delegation starts |
| `end` | DateTime | Indicates the date and time (`ISO 8601` date format) when the delegation ends |
| `notifyDelegatee` | Boolean | Indicates if the delegatee should be notified of the delegation |
### Update a delegation
Standard users can only update delegations for themselves; only administrators can update a delegation for another user. This operation requires that the portal delegation feature be enabled.
#### Request payload:
```
{
"operation": "updateDelegation",
"args": {
"input": {
"id": "RGVsZWdhdGlvbjoxMA==",
"start": "2018-05-01T00:00:00.000Z",
"end": "2018-9-01T00:00:00.000Z",
"notifyDelegatee": true
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"delegationId": "RGVsZWdhdGlvbjoxMA=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Delegation identifier with the pattern `[Delegation:1]` where `1` is the delegation identifier from the database |
| `delegatorId` | Base64-encoded string | User identifier that is delegating its requests and actions to another person, with the pattern `[User:1]` where `1` is the user identifier from the database |
| `delegateeId` | Base64-encoded string | User identifier to whom the requests and actions are delegated from the delegator, with the pattern `[User:1]` where `1` is the user identifier from the database |
| `processId` | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `participantId` | Base64-encoded string | Participant identifier, with the pattern `[GlobalParticipant:1] or [LocalProcessParticipant:1]` where `1` is the participant identifier from the database |
| `start` | DateTime | Indicates the date and time (`ISO 8601 date format`) when the delegation starts |
| `end` | DateTime | Indicates the date and time (`ISO 8601 date format`) when the delegation ends |
| `notifyDelegatee` | Boolean | Indicates if the delegatee should be notified of the delegation |
### Delete a delegation
Standard users can only delete their own delegations; only administrators can delete another user's delegations. This operation requires that the portal delegation feature be enabled.
#### Request payload:
```
{
"operation": "deleteDelegation",
"args": {
"input": {
"id": "RGVsZWdhdGlvbjoxMA=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Delegation identifier with the pattern `[Delegation:1]` where `1` is the delegation identifier from the database |
## Category operations
### Create a new category
Only administrators can create a category.
#### Request payload:
```
{
"operation": "createCategory",
"args": {
"input": {
"name": "Human resources",
"description": "Human resources category"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"categoryId": "Q2F0ZWdvcnk6Mg=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | -------- | -------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `name`\* | String | Category name |
| `description`\* | String | Category description |
### Update a category
Only administrators can update a category.
#### Request payload:
```
{
"operation": "updateCategory",
"args": {
"input": {
"id": "Q2F0ZWdvcnk6Mg==",
"name": "My category updated name"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"categoryId": "Q2F0ZWdvcnk6Mg=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | String | Category identifier with the pattern `[Category:1]` where `1` is the category identifier from the database |
| `name` | String | Category name |
| `description` | String | Category description |
### Delete a category
Only administrators can delete a category.
#### Request payload:
```
{
"operation": "deleteCategory",
"args": {
"input": {
"id": "Q2F0ZWdvcnk6Mg=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | String | Category identifier with the pattern `[Category:1]` where `1` is the category identifier from the database |
## Process folder operations
### Create a new process folder
Only administrators can create a process folder.
#### Request payload:
```
{
"operation": "createProcessFolder",
"args": {
"input": {
"name": "Human Resources processes folder",
"description": "Human Resources processes folder",
"managerId": "R2xvYmFsUGFydGljaXBhbnQ6MQ=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processFolderId": "UHJvY2Vzc0ZvbGRlcjoz"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `name`\* | String | Process folder name |
| `description`\* | String | Process folder description |
| `managerId`\* | Base64-encoded string | Process folder manager identifier with the pattern `[GlobalParticipant:1]` where `1` is the global participant identifier from the database |
### Update a process folder
Only administrators and the process folder manager can update a process folder.
#### Request payload:
```
{
"operation": "updateProcessFolder",
"args": {
"input": {
"id": "UHJvY2Vzc0ZvbGRlcjoz",
"name": "Updated process folder name"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processFolderId": "UHJvY2Vzc0ZvbGRlcjoz"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Process folder identifier with the pattern `[ProcessFolder:1]` where `1` is the process folder identifier from the database |
| `name` | String | Process folder name |
| `description` | String | Process folder description |
| `managerId` | Base64-encoded string | Process folder manager identifier with the pattern `[GlobalParticipant:1]` where `1` is the global participant identifier from the database |
### Delete a process folder
Only administrators can delete a process folder.
#### Request payload:
```
{
"operation": "deleteProcessFolder",
"args": {
"input": {
"id": "UHJvY2Vzc0ZvbGRlcjoz"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Process folder identifier with the pattern `[ProcessFolder:1]` where `1` is the process folder identifier from the database |
## Process operations
### Create a new process
This operation creates a process from the process properties. The process name, description, and folder identifier or name are required.
#### Request payloads:
```
{
"operation": "createProcess",
"args": {
"input": {
"description": "My new process",
"folderName": "DEFAULT",
"name": "My new process"
}
}
}
```
```
{
"operation": "createProcess",
"args": {
"input": {
"fromProcessId": "UHJvY2Vzczoy"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processId": "UHJvY2Vzczoy"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| --------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `accessLevel` | String | Process access level:
|
| `categoryNames` | Array of strings | Process categories |
| `description` | String | Process description |
| `folderId` | Base64-encoded string | Process folder identifier with the pattern `[ProcessFolder:1]` where `1` is the process folder identifier from the database |
| `folderName` | String | Process folder name |
| `fromProcessId` | Base64-encoded string | Process identifier used in new version creation with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `helpEmail` | String | Process help information email |
| `helpText` | String | Process help information text |
| `helpUrl` | URI string | Process help information URL |
| `isActionDataArchived` | Boolean | Indicates if action's associated data is archived when a request is closed |
| `isBuiltInForm` | Boolean | Indicates if form management is built-in |
| `isDatabaseStorageForFiles` | Boolean | Indicates if file content is stored in the database |
| `isSubProcess` | Boolean | Indicates if sub-process mode is enabled |
| `leadTime` | Int | Process lead time |
| `leadTimeUnit` | String | Process lead time duration unit:
YEARSMONTHSDAYSHOURSMINUTESSECONDS
|
| `leadTimeUseWorkingDays` | Boolean | Indicates if working days/hours are used to compute the lead time |
| `notifyRequesterOnClosure` | Boolean | Indicates if the requester is notified upon request closure |
| `name` | String | Process name |
| `notifyRequesterOnClosure` | Boolean | Indicates if the requester is notified upon request closure |
| `state` | String | Process state:
|
### Create a new process from an XPDL
A process can be created from its XPDL definition.
#### Request payload:
```
{
"operation": "createProcessFromXpdl",
"args": {
"input": {
"addNewParticipantsAsGlobal": false,
"addSelfToParticipant": true,
"description": "My new process",
"folderName": "DEFAULT",
"name": "My new process",
"xpdl": {
"contentType": "text/xml",
"name": "process.xml",
"size": 123,
"updatedAt": "2017-03-15T15:02:00Z",
"url": "file:///c:/temp/process.xml"
}
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processId": "UHJvY2Vzczoy"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ---------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `clientMutationId` | String | Client mutation identifier |
| `addNewParticipantsAsGlobal` | Boolean | Specifies whether or not to import process participants as global participants (can only be used by users with an administrator profile) |
| `addGlobalParticipantAssociations` | Boolean | Specifies whether or not to import global participant associations |
| `addSelfToParticipant` | Boolean | Specifies whether or not to add the current user to process participants |
| `folderId` | Base64-encoded string | Process folder identifier with the pattern `[ProcessFolder:1]` where `1` is the process folder identifier from the database |
| `folderName` | String | Process folder name |
| `fromProcessId` | Base64-encoded string | Process identifier used when creating a new version with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `name` | String | Process name |
| `newVersionIfExists` | Boolean | Creates a new version if the process already exists |
| `state` | String | Process state:
|
| `useVersionNumber` | Boolean | Specifies whether or not to import the process version number from the process definition |
| `xpdl` | FileInput | Process definition in XPDL format (see [FileInput values](#fileinput-values)) |
### Update a process
This operation updates process properties from the process identifier.
#### Request payload:
```
{
"operation": "updateProcess",
"args": {
"input": {
"id": "UHJvY2Vzczoy",
"name": "New name"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processId": "UHJvY2Vzczoy"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| --------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `accessLevel` | String | Process access level:
|
| `categories` | Array of strings | Process categories |
| `description` | String | Process description |
| `folderId` | Base64-encoded string | Process folder identifier with the pattern `[ProcessFolder:1]` where `1` is the process folder identifier from the database |
| `helpEmail` | String | Process help information email |
| `helpText` | String | Process help information text |
| `helpUrl` | URI string | Process help information URL |
| `isActionDataArchived` | Boolean | Indicates if action's associated data is archived when a request is closed |
| `isBuiltInForm` | Boolean | Indicates if form management is built-in |
| `isDatabaseStorageForFiles` | Boolean | Indicates if file content is stored in the database |
| `isSubProcess` | Boolean | Indicates if sub-process mode is enabled |
| `leadTime` | Int | Process lead time |
| `leadTimeUnit` | String | Process lead time duration unit:
YEARSMONTHSDAYSHOURSMINUTESSECONDS
|
| `leadTimeUseWorkingDays` | Boolean | Indicates if working days/hours are used to compute the lead time |
| `name` | String | Process name |
| `notifyRequesterOnClosure` | Boolean | Indicates if the requester is notified upon request closure |
| `state` | String | Process state:
|
### Update a process from an XPDL
A process can be updated from its XPDL definition. The `.xml` file is uploaded by using the [multipart file upload](#multipart-file-upload) feature as shown below.
#### Request payload:
```
{
"operation": "updateProcessFromXpdl",
"args": {
"input": {
"id": "UHJvY2Vzczoy",
"xpdl": {
"contentType": "text/xml",
"name": "process.xml",
"size": 123,
"updatedAt": "2017-03-15T15:02:00Z",
"url": "file:///c:/temp/process.xml"
}
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processId": "UHJvY2Vzczoy"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ---------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `addNewParticipantsAsGlobal` | Boolean | Specifies whether or not to import process participants as global participants (can only be used by users with an administrator profile) |
| `addGlobalParticipantAssociations` | Boolean | Specifies whether or not to import global participant associations |
| `addSelfToParticipant` | Boolean | Specifies whether or not to add the current user to process participants |
| `useVersionNumber` | Boolean | Specifies whether or not to import the process version number from the process definition |
| `xpdl` | FileInput | Process definition in XPDL format (see [FileInput values](#fileinput-values)) |
### Delete a process
A process can be deleted by using the process identifier.
#### Request payload:
```
{
"operation": "deleteProcess",
"args": {
"input": {
"id": "UHJvY2Vzczoy"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
## Participant operations
### Create a new global participant
#### Request payload:
```
{
"operation": "createGlobalParticipant",
"args": {
"input": {
"name": "My global participant",
"description": "My global participant description",
"type": "COORDINATOR",
"userIds": ["VXNlcjox", "VXNlcjoy"],
"groupIds": ["R3JvdXA6MQ=="],
"directoryIds": ["RGlyZWN0b3J5OjE="],
"coordinatorIds": ["VXNlcjoy"]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"participantId": "R2xvYmFsUGFydGljaXBhbnQ6MQ=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `name`\* | String | Global participant name |
| `type`\* | String | Global participant type:
|
| `description`\* | String | Global participant description |
| `directoryIds` | Array of Base64-encoded strings | List of directories (identifier) associated to the global participant with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `groupIds` | Array of Base64-encoded strings | List of groups (identifier) associated to the global participant with the pattern `[Group:1]` where `1` is the group identifier from the database |
| `userIds` | Array of Base64-encoded strings | List of users (identifier) associated to the global participant with the pattern `[User:1]` where `1` is the user identifier from the database |
| `coordinatorIds` | Array of Base64-encoded strings | List of coordinators (identifier) associated to the global participant with the pattern `[User:1]` where `1` is the user identifier from the database |
### Update a global participant
#### Request payload:
```
{
"operation": "updateGlobalParticipant",
"args": {
"input": {
"id": "R2xvYmFsUGFydGljaXBhbnQ6MQ=="
"name": "My global participant",
"description": "My global participant description",
"type": "COORDINATOR",
"userIds": ["VXNlcjox", "VXNlcjoy"],
"groupIds": ["R3JvdXA6MQ=="],
"directoryIds": ["RGlyZWN0b3J5OjE="],
"coordinatorIds": ["VXNlcjoy"]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"participantId": "R2xvYmFsUGFydGljaXBhbnQ6MQ=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Global participant identifier with the pattern `[GlobalParticipant:1]` where `1` is the global participant identifier from the database |
| `name` | String | Global participant name |
| `type` | String | Global participant type:
|
| `description` | String | Global participant description |
| `directoryIds` | Array of Base64-encoded strings | List of directories (identifier) associated to the global participant with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `groupIds` | Array of Base64-encoded strings | List of groups (identifier) associated to the global participant with the pattern `[Group:1]` where `1` is the group identifier from the database |
| `userIds` | Array of Base64-encoded strings | List of users (identifier) associated to the global participant with the pattern `[User:1]` where `1` is the user identifier from the database |
| `coordinatorIds` | Array of Base64-encoded strings | List of coordinators (identifier) associated to the global participant with the pattern `[User:1]` where `1` is the user identifier from the database |
### Delete a global participant
#### Request payload:
```
{
"operation": "deleteGlobalParticipant",
"args": {
"input": {
"id": "R2xvYmFsUGFydGljaXBhbnQ6MQ=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Global participant identifier with the pattern `[GlobalParticipant:1]` where `1` is the global participant identifier from the database |
### Add a new process participant profile
To be used with `global participant` only.
#### Request payload:
```
{
"operation": "addProcessParticipantProfile",
"args": {
"input": {
"role": "ACTOR"
"participantId": "R2xvYmFsUGFydGljaXBhbnQ6NQ==",
"processId": "UHJvY2Vzczox"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processParticipantProfileId": "UHJvY2Vzc1BhcnRpY2lwYW50UHJvZmlsZToxLS0tMTE="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| -------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `processId`\* | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `participantId`\* | Base64-encoded string | Global participant identifier with the pattern `[GlobalParticipant:1]` where `1` is the global participant identifier from the database |
| `query` | String | Supervisor scope query |
| `role`\* | String | Participant role:
|
| `canCancelRequests` | Boolean | Indicates if the participant can cancel requests |
| `canReadComments` | Boolean | Indicates if the participant can read comments |
| `canReassignActions` | Boolean | Indicates if the participant can reassign an action |
| `canViewGraphicalFollowUp` | Boolean | Indicates if the participant can view the graphical follow-up |
| `canViewStatistics` | Boolean | Indicates if the participant can view statistics |
| `canWriteComments` | Boolean | Indicates if the participant can write comments |
### Update a process participant profile
To be used with `global participant` only.
#### Request payload:
```
{
"operation": "updateProcessParticipantProfile",
"args": {
"input": {
"role": "SUPERVISOR",
"id": "UHJvY2Vzc1BhcnRpY2lwYW50UHJvZmlsZToxLS0tMTE="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"processParticipantProfileId": "UHJvY2Vzc1BhcnRpY2lwYW50UHJvZmlsZToxLS0tMTE="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| -------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Process participant profile identifier with the pattern `[ProcessParticipantProfile:1---2]` where `1` is the process identifier from the database and `2` is the participant identifier from the database |
| `query` | String | Supervisor scope query |
| `role` | String | Participant role:
|
| `canCancelRequests` | Boolean | Indicates if the participant can cancel requests |
| `canReadComments` | Boolean | Indicates if the participant can read comments |
| `canReassignActions` | Boolean | Indicates if the participant can reassign an action |
| `canViewGraphicalFollowUp` | Boolean | Indicates if the participant can view the graphical follow-up |
| `canViewStatistics` | Boolean | Indicates if the participant can view statistics |
| `canWriteComments` | Boolean | Indicates if the participant can write comments |
### Remove a process participant profile
To be used with `global participant` only.
#### Request payload:
```
{
"operation": "removeProcessParticipantProfile",
"args": {
"input": {
"id": "UHJvY2Vzc1BhcnRpY2lwYW50UHJvZmlsZToxLS0tMTE="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Process participant profile identifier with the pattern `[ProcessParticipantProfile:1---2]` where `1` is the process identifier from the database and `2` is the participant identifier from the database |
### Create a new local process participant
#### Request payload:
```
{
"operation": "createLocalProcessParticipant",
"args": {
"input": {
"name": "My local process participant",
"description": "My local process participant description",
"type": "COORDINATOR",
"userIds": ["VXNlcjox", "VXNlcjoy"],
"groupIds": ["R3JvdXA6MQ=="],
"directoryIds": ["RGlyZWN0b3J5OjE="],
"coordinatorIds": ["VXNlcjoy"],
"processId": "UHJvY2Vzczoy"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"participantId": "TG9jYWxQcm9jZXNzUGFydGljaXBhbnQ6MTI="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `name`\* | String | Local process participant name |
| `processId`\* | Base64-encoded string | Process identifier with the pattern `[Process:1]` where `1` is the process identifier from the database |
| `description`\* | String | Local process participant description |
| `type`\* | String | Local process participant type:
|
| `directoryIds` | Array of Base64-encoded strings | List of directories (identifier) associated to the local process participant with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `groupIds` | Array of Base64-encoded strings | List of groups (identifier) associated to the local process participant with the pattern `[Group:1]` where `1` is the group identifier from the database |
| `userIds` | Array of Base64-encoded strings | List of users (identifier) associated to the local process participant with the pattern `[User:1]` where `1` is the user identifier from the database |
| `coordinatorIds` | Array of Base64-encoded strings | List of coordinators (identifier) associated to the local process participant with the pattern `[User:1]` where `1` is the user identifier from the database |
### Update a local process participant
#### Request payload:
```
{
"operation": "updateLocalProcessParticipant",
"args": {
"input": {
"id": "TG9jYWxQcm9jZXNzUGFydGljaXBhbnQ6MTI="
"name": "My local process participant",
"description": "My local process participant description",
"type": "COORDINATOR",
"userIds": ["VXNlcjox", "VXNlcjoy"],
"groupIds": ["R3JvdXA6MQ=="],
"directoryIds": ["RGlyZWN0b3J5OjE="],
"coordinatorIds": ["VXNlcjoy"]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"participantId": "TG9jYWxQcm9jZXNzUGFydGljaXBhbnQ6MTI="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Local process participant identifier with the pattern `[LocalProcessParticipant:1]` where `1` is the local process participant identifier from the database |
| `name` | String | Local process participant name |
| `description` | String | Local process participant description |
| `type` | String | Local process participant type:
|
| `directoryIds` | Array of Base64-encoded strings | List of directories (identifier) associated to the local process participant with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `groupIds` | Array of Base64-encoded strings | List of groups (identifier) associated to the local process participant with the pattern `[Group:1]` where `1` is the group identifier from the database |
| `userIds` | Array of Base64-encoded strings | List of users (identifier) associated to the local process participant with the pattern `[User:1]` where `1` is the user identifier from the database |
| `coordinatorIds` | Array of Base64-encoded strings | List of coordinators (identifier) associated to the local process participant with the pattern `[User:1]` where `1` is the user identifier from the database |
### Delete a local process participant
#### Request payload:
```
{
"operation": "deleteLocalProcessParticipant",
"args": {
"input": {
"id": "TG9jYWxQcm9jZXNzUGFydGljaXBhbnQ6MTI="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Local process participant identifier with the pattern `[LocalProcessParticipant:1]` where `1` is the local process participant identifier from the database |
## Application operations
### Create an application
Only administrators can create a workflow application.
#### Request payload:
```
{
"operation": "createApplication",
"args": {
"input": {
"name": "My assembly application",
"description": "My assembly application description",
"type": "ASSEMBLY",
"assemblyName": "CustomAssembly.Applications",
"assemblyClassName": "CustomAssembly.Applications.Converters",
"method": "Convert",
"isDefault": false,
"isActive": true
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"applicationId": "QXBwbGljYXRpb246Mzk="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `assemblyClassName` | String | Application assembly class name |
| `assemblyName` | String | Application assembly name |
| `contentType` | String | Application content type |
| `contextFormat` | String | Application context format:
JSON: Application JSON context format typeWFCONTEXT: Application XML ADO.NET Dataset context format typeRECORDSET: Application XML ADO Recordset context format type
|
| `description`\* | String | Application description |
| `isActive`\* | Boolean | Application active |
| `isDefault` | Boolean | Application default |
| `isSchemaDefinitionEmbedded` | Boolean | Application schema definition embedded |
| `method` | String | Application method |
| `name`\* | String | Application name |
| `password` | String | Application password |
| `token` | String | Application token |
| `type`\* | String | Application type:
ASSEMBLY: AssemblyWEBPROCASYNC: Asynchronous web procedureINWEBHOOK: Incoming webhookWEBSERVICE: SOAP web serviceWCFSERVICE: WCF serviceWEBAPP: Web applicationWEBPROC: Web procedureNONINTERACTIVECLIENT: Non-interactive client
|
| `url` | String | URL |
| `username` | String | Application username |
| `wsdl` | String | WSDL |
### Update an application
Only administrators can update a workflow application.
#### Request payload:
```
{
"operation": "updateApplication",
"args": {
"input": {
"id": "QXBwbGljYXRpb246Mzk=",
"name": "My assembly application name"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"applicationId": "QXBwbGljYXRpb246Mzk="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ---------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Application identifier with the pattern `[Application:1]` where `1` is the application identifier from the database |
| `assemblyClassName` | String | Application assembly class name |
| `assemblyName` | String | Application assembly name |
| `contentType` | String | Application content type |
| `contextFormat` | String | Application context format:
JSON: Application JSON context format typeWFCONTEXT: Application XML ADO.NET Dataset context format typeRECORDSET: Application XML ADO Recordset context format type
|
| `description` | String | Application description |
| `isActive` | Boolean | Application active |
| `isDefault` | Boolean | Application default |
| `isSchemaDefinitionEmbedded` | Boolean | Application schema definition embedded |
| `method` | String | Application method |
| `name` | String | Application name |
| `password` | String | Application password |
| `url` | String | URL |
| `username` | String | Application username |
| `wsdl` | String | WSDL |
### Delete an application
Only administrators can delete a workflow application.
#### Request payload:
```
{
"operation": "deleteApplication",
"args": {
"input": {
"id": "QXBwbGljYXRpb246Mzk="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Application identifier with the pattern `[Application:1]` where `1` is the application identifier from the database |
### Add an application parameter
Only administrators can add a workflow application parameter.
#### Request payload:
```
{
"operation": "addApplicationParameter",
"args": {
"input": {
"applicationId": "QXBwbGljYXRpb246MjA=",
"name": "My parameter",
"description": "My parameter description",
"dataType": "TEXT",
"direction": "IN",
"isRequired": true,
"isDefault": false
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"parameterId": "QXBwbGljYXRpb25QYXJhbWV0ZXI6MjAtLS02"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `applicationId`\* | Base64-encoded string | Application identifier with the pattern `[Application:1]` where `1` is the application identifier from the database |
| `dataType`\* | String | Application parameter data type:
|
| `description`\* | String | Application parameter description |
| `direction`\* | String | Application parameter direction:
|
| `isDefault`\* | Boolean | Application parameter default |
| `isRequired`\* | Boolean | Application parameter required |
| `name`\* | String | Application parameter name |
### Remove an application parameter
Only administrators can remove a workflow application parameter if it is not associated to any activity and is not required.
#### Request payload:
```
{
"operation": "removeApplicationParameter",
"args": {
"input": {
"id": "QXBwbGljYXRpb25QYXJhbWV0ZXI6MjAtLS02"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Application parameter identifier with the pattern `[ApplicationParameter:1---2]` where `1` is the application identifier from the database and `2` is the parameter identifier from the database |
## Global list operations
### Create a global list
The operation creates a global list from the global list's properties. If no input argument is provided, the global list is created with the default values.
#### Request payloads:
```
{
"operation": "createGlobalList",
"args": {
"input": {
"connectionName": "WfgenDatabase",
"name": "USER_LIST",
"providerName": "SYSTEM_DATA_SQLCLIENT",
"selectCommand": "SELECT USERNAME, LASTNAME, FIRSTNAME FROM USERS"
}
}
}
```
```
{
"operation": "createGlobalList",
"args": {
"input": {
"fromGlobalListId": "R2xvYmFsTGlzdDoxMw=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"globalListId": "R2xvYmFsTGlzdDoxMw=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `clientMutationId` | String | Client mutation identifier |
| `connectionName` | String | Global list connection name |
| `connectionString` | String | Global list connection string |
| `name` | String | Global list name |
| `managerId` | Base64-encoded string | Global list manager identifier (global participant) with the pattern `[GlobalParticipant:1]` where `1` is the global participant identifier from the database |
| `fromGlobalListId` | Base64-encoded string | Duplicates a global list given its identifier with the pattern `[GlobalList:1]` where `1` is the global list identifier from the database |
| `providerName` | String | Global list provider name:
SYSTEM\_DATA\_SQLCLIENTSYSTEM\_DATA\_OLEDBSYSTEM\_DATA\_ODBCSYSTEM\_DATA\_ORACLECLIENTORACLE\_DATAACCESS\_CLIENT
|
| `selectCommand` | String | Global list select command |
### Create a global list from an XML definition
A global list can be created from its XML definition. The `.xml` file is uploaded by using the [multipart file upload](#multipart-file-upload) feature as shown below.
#### Request payload:
```
{
"operation": "createGlobalListFromXmlDefinition",
"args": {
"input": {
"xmlDefinition": {
"contentType": "text/xml",
"name": "list.xml",
"size": 123,
"updatedAt": "2017-03-15T15:02:00Z",
"url": "file:///c:/temp/list.xml"
}
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"globalListId": "R2xvYmFsTGlzdDoxMw=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------- | -------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `xmlDefinition` | FileInput | Global list definition in XML format (see [FileInput values](#fileinput-values)) |
### Update a global list
#### Request payload:
```
{
"operation": "updateGlobalList",
"args": {
"input": {
"id": "R2xvYmFsTGlzdDoxMw==",
"name": "New list name"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"globalListId": "R2xvYmFsTGlzdDoxMw=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Global list identifier with the pattern `[GlobalList:1]` where `1` is the global list identifier from the database |
| `connectionName` | String | Global list connection name |
| `connectionString` | String | Global list connection string |
| `name` | String | Global list name |
| `managerId` | Base64-encoded string | Global list manager identifier (global participant) with the pattern `[GlobalParticipant:1]` where `1` is the global participant identifier from the database |
| `providerName` | String | Global list provider name:
SYSTEM\_DATA\_SQLCLIENTSYSTEM\_DATA\_OLEDBSYSTEM\_DATA\_ODBCSYSTEM\_DATA\_ORACLECLIENTORACLE\_DATAACCESS\_CLIENT
|
| `selectCommand` | String | Global list select command |
### Update a global list from an XML definition
A global list can be updated from its XML definition. The `.xml` file is uploaded by using the [multipart file upload](#multipart-file-upload) feature as shown below.
#### Request payload:
```
{
"operation": "updateGlobalListFromXmlDefinition",
"args": {
"input": {
"id": "R2xvYmFsTGlzdDoxMw==",
"xmlDefinition": {
"contentType": "text/xml",
"name": "list.xml",
"size": 123,
"updatedAt": "2017-03-15T15:02:00Z",
"url": "file:///c:/temp/list.xml"
}
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"globalListId": "R2xvYmFsTGlzdDoxMw=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Global list identifier with the pattern `[GlobalList:1]` where `1` is the global list identifier from the database |
| `xmlDefinition` | FileInput | Global list definition in XML format (see [FileInput values](#fileinput-values)) |
### Delete a global list
#### Request payload:
```
{
"operation": "deleteGlobalList",
"args": {
"input": {
"id": "W0dsb2JhbExpc3Q6MV0="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Global list identifier with the pattern `[GlobalList:1]` where `1` is the global list identifier from the database |
## User and group operations
### Create a user
Only administrators can create a user.
#### Request payload:
```
{
"operation": "createUser",
"args": {
"input": {
"userName": "emily_taylor",
"lastName": "Taylor",
"firstName": "Emily",
"commonName": "Emily",
"directoryId": "RGlyZWN0b3J5OjM=",
"password": "TestPassword$",
"fax": "1234567",
"jobTitle": "Engineer",
"systemIdentifier": "70f63326-3947-4052-8bf5-ce4912e7e7b5",
"managerId": "VXNlcjoz",
"mobile": "422 543 8765",
"phone": "666 543 9839",
"postalCode": "R6H 8K0",
"office": "444 Main St",
"postalAddress": "333 Bank St",
"isAdministrator": true,
"isActive": true
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"userId": "VXNlcjox"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `directoryId`\* | Base64-encoded string | Directory identifier with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `userName`\* | String | User's login name |
| `password` | String | User's password |
| `lastName`\* | String | Last name (refers to the `SN` attribute in `LDAP`) |
| `firstName` | String | First name (refers to the `GIVENNAME` attribute in `LDAP`) |
| `email` | String | Email address |
| `isAdministrator` | Boolean | Indicates if the user has an `Administrator` profile. Otherwise, the user will be set with a `User` profile. |
| `isActive` | Boolean | Indicates if the user account is `Active` or `Inactive` |
| `isSynchronized` | Boolean | Indicates if the user account is managed by the directory synchronization |
| `defaultLanguage` | String | Default language in `Language-Country` format, e.g. `en-US` |
| `defaultTimeZoneId` | Int | Default time zone identifier, e.g. `9` for `(GMT-05:00) Eastern Time (US and Canada)`. See the [Time Zone IDs and GMT Values Mapping](https://docs.workflowgen.com/integration/8.3/appendix-time-zone-ids-and-gmt-values-mapping) appendix for the list of time zone identifiers. |
| `city` | String | City |
| `commonName` | String | Common name (refers to the attribute `CN` in `LDAP`) |
| `company` | String | Company |
| `country` | String | Country |
| `department` | String | Department |
| `distinguishedName` | String | Distinguished name (refers to the `DN` attribute in `LDAP`) |
| `employeeNumber` | String | Employee number |
| `employeeType` | String | Employee type |
| `extendedAttribute1` | String | Extended attribute 1 |
| `extendedAttribute2` | String | Extended attribute 2 |
| `extendedAttribute3` | String | Extended attribute 3 |
| `extendedAttribute4` | String | Extended attribute 4 |
| `extendedAttribute5` | String | Extended attribute 5 |
| `fax` | String | Fax number |
| `initials` | String | User's initials |
| `jobTitle` | String | Job title |
| `ldapADsPath` | String | LDAP Active Directory path (refers to the `ADSPATH` attribute in `LDAP`) |
| `managerId` | Base64-encoded string | Manager's identifier with the pattern `[User:1]` where `1` is the user identifier from the database |
| `mobile` | String | Mobile phone number |
| `office` | String | Office phone number |
| `pager` | String | Pager number |
| `personalTitle` | String | Personal title |
| `phone` | String | Phone number |
| `postalAddress` | String | Postal address |
| `postalCode` | String | Zip or postal code |
| `state` | String | State, province, or county |
| `systemIdentifier` | String | System identifier (refers to the `OBJECTSID` attribute in `LDAP`) |
### Update a user
Only administrators can update a user.
#### Request payload:
```
{
"operation": "updateUser",
"args": {
"input": {
"id": "VXNlcjox",
"userName": "jane_doe",
"lastName": "Doe",
"firstName": "Jane",
"commonName": "Jane",
"directoryId": "RGlyZWN0b3J5OjM=",
"fax": "1234567",
"systemIdentifier": "70f63326-3947-4052-8bf5-ce4912e7e7b5",
"isAdministrator": false,
"isActive": false
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"userId": "VXNlcjox"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| -------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | User identifier with the pattern `[User:1]` where `1` is the user identifier from the database |
| `directoryId` | Base64-encoded string | Directory identifier with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `userName` | String | User's login name |
| `password` | String | User's password |
| `lastName` | String | Last name (refers to the `SN` attribute in `LDAP`) |
| `firstName` | String | First name (refers to the `GIVENNAME` attribute in `LDAP`) |
| `email` | String | Email address |
| `isAdministrator` | Boolean | Indicates if the user has an `Administrator` profile. Otherwise, the user will be set with a `User` profile. |
| `isActive` | Boolean | Indicates if the user account is `Active` or `Inactive` |
| `isSynchronized` | Boolean | Indicates if the user account is managed by the directory synchronization |
| `defaultLanguage` | String | Default language in `Language-Country` format, e.g. `en-US` |
| `language` | String | Preferred language in `Language-Country` format, e.g. `en-US` |
| `defaultTimeZoneId` | Int | Default time zone identifier, e.g. `9` for `(GMT-05:00) Eastern Time (US and Canada)`. See the [Time Zone IDs and GMT Values Mapping](https://docs.workflowgen.com/integration/8.3/appendix-time-zone-ids-and-gmt-values-mapping) appendix for the list of time zone identifiers. |
| `timeZoneId` | Int | Preferred time zone identifier, e.g. `9` for `(GMT-05:00) Eastern Time (US and Canada)`. See the [Time Zone IDs and GMT Values Mapping](https://docs.workflowgen.com/integration/8.3/appendix-time-zone-ids-and-gmt-values-mapping) appendix for the list of time zone identifiers. |
| `city` | String | City |
| `commonName` | String | Common name (refers to the `CN` attribute in `LDAP`) |
| `company` | String | Company |
| `country` | String | Country |
| `department` | String | Department |
| `distinguishedName` | String | Distinguished name (refers to the `DN` attribute in `LDAP`) |
| `employeeNumber` | String | Employee number |
| `employeeType` | String | Employee type |
| `extendedAttribute1` | String | Extended attribute 1 |
| `extendedAttribute2` | String | Extended attribute 2 |
| `extendedAttribute3` | String | Extended attribute 3 |
| `extendedAttribute4` | String | Extended attribute 4 |
| `extendedAttribute5` | String | Extended attribute 5 |
| `fax` | String | Fax number |
| `initials` | String | User's initials |
| `jobTitle` | String | Job title |
| `ldapADsPath` | String | LDAP Active Directory path (refers to the `ADSPATH` attribute in `LDAP`) |
| `managerId` | Base64-encoded string | Manager's identifier with the pattern `[User:1]` where `1` is the user identifier from the database |
| `mobile` | String | Mobile phone number |
| `office` | String | Office phone number |
| `pager` | String | Pager number |
| `personalTitle` | String | Personal title |
| `phone` | String | Phone number |
| `postalAddress` | String | Postal address |
| `postalCode` | String | Zip or postal code |
| `state` | String | State, province, or county |
| `systemIdentifier` | String | System identifier (refers to the `OBJECTSID` attribute in `LDAP`) |
### Delete a user
Only administrators can delete a user.
#### Request payload:
```
{
"operation": "deleteUser",
"args": {
"input": {
"id": "VXNlcjox"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ---------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | User identifier with the pattern `[User:1]` where `1` is the user identifier from the database |
### Add groups to a user
Only administrators can add groups to a user.
#### Request payload:
```
{
"operation": "addGroupsToUser",
"args": {
"input": {
"id": "VXNlcjox",
"groupIds": ["R3JvdXA6Mw==", "R3JvdXA6Nw=="]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"userId": "VXNlcjox"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | User identifier with the pattern `[User:1]` where `1` is the user identifier from the database |
| `groupIds`\* | Array of Base64-encoded strings | List of groups (identifier) associated to the user with the pattern `[Group:1]` where `1` is the group identifier from the database |
### Remove groups from a user
Only administrators can remove groups from a user.
#### Request payload:
```
{
"operation": "removeGroupsFromUser",
"args": {
"input": {
"id": "VXNlcjox",
"groupIds": ["R3JvdXA6Nw=="]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"userId": "VXNlcjox"
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | User identifier with the pattern `[User:1]` where `1` is the user identifier from the database |
| `groupIds`\* | Array of Base64-encoded strings | List of groups (identifier) associated to the user with the pattern `[Group:1]` where `1` is the group identifier from the database |
### Create a group
Only administrators can create a group.
#### Request payload:
```
{
"operation": "createGroup",
"args": {
"input": {
"name": "Group G",
"description": "Group G",
"directoryId": "RGlyZWN0b3J5OjM=",
"isSynchronized": true,
"email": "group_g@company.com",
"systemIdentifier": "13499ebd-f6d6-45c6-8c50-2a1fdc6336cc"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"groupId": "R3JvdXA6MQ=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `directoryId`\* | Base64-encoded string | Directory identifier with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `name`\* | String | Group's name |
| `code` | String | Group's code |
| `commonName` | String | Common name (refers to the `CN` attribute in `LDAP`) |
| `description` | String | Description |
| `distinguishedName` | String | Distinguished name (refers to the `DISTINGUISHEDNAME` attribute in `LDAP`) |
| `email` | String | Email address |
| `isSynchronized` | Boolean | Indicates if the group is managed by the directory synchronization |
| `ldapADsPath` | String | LDAP Active Directory path (refers to the `ADSPATH` attribute in `LDAP`) |
| `query` | String | Query used to select and filter group members from users in the database |
| `systemIdentifier` | String | System identifier (refers to the `OBJECTSID` attribute in `LDAP`) |
### Update a group
Only administrators can update a group.
#### Request payload:
```
{
"operation": "updateGroup",
"args": {
"input": {
"id": "R3JvdXA6MQ==",
"name": "Group E",
"description": "Group E",
"email": "group_e@company.com",
"query": "CITY='NEW YORK'"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"groupId": "R3JvdXA6MQ=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Group identifier with the pattern `[Group:1]` where `1` is the group identifier from the database |
| `directoryId` | Base64-encoded string | Directory identifier with the pattern `[Directory:1]` where `1` is the directory identifier from the database |
| `name` | String | Group's name |
| `code` | String | Group's code |
| `commonName` | String | Common name (refers to the `CN` attribute in `LDAP`) |
| `description` | String | Description |
| `distinguishedName` | String | Distinguished name (refers to the `DISTINGUISHEDNAME` attribute in `LDAP`) |
| `email` | String | Email address |
| `isSynchronized` | Boolean | Indicates if the group is managed by the directory synchronization |
| `ldapADsPath` | String | LDAP Active Directory path (refers to the `ADSPATH` attribute in `LDAP`) |
| `query` | String | Query used to select and filter group members from users in the database |
| `systemIdentifier` | String | System identifier (refers to the `OBJECTSID` attribute in `LDAP`) |
### Delete a group
Only administrators can delete a group.
#### Request payload:
```
{
"operation": "deleteGroup",
"args": {
"input": {
"id": "R3JvdXA6MQ=="
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Group identifier with the pattern `[Group:1]` where `1` is the group identifier from the database |
### Add users to a group
Only administrators can add users to a group.
#### Request payload:
```
{
"operation": "addUsersToGroup",
"args": {
"input": {
"id": "R3JvdXA6MQ==",
"userIds": ["VXNlcjox", "VXNlcjoy"]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"groupId": "R3JvdXA6MQ=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Group identifier with the pattern `[Group:1]` where `1` is the group identifier from the database |
| `userIds`\* | Array of Base64-encoded strings | List of users (identifier) associated to the group with the pattern `[User:1]` where `1` is the user identifier from the database |
### Remove users from a group
Only administrators can remove users from a group.
#### Request payload:
```
{
"operation": "removeUsersFromGroup",
"args": {
"input": {
"id": "R3JvdXA6MQ==",
"userIds": ["VXNlcjoy"]
}
}
}
```
#### Response payload:
```
{
"clientMutationId": null,
"groupId": "R3JvdXA6MQ=="
}
```
#### Properties
| **Property** | **Type** | **Description** |
| ------------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `clientMutationId` | String | Client mutation identifier |
| `id`\* | Base64-encoded string | Group identifier with the pattern `[Group:1]` where `1` is the group identifier from the database |
| `userIds`\* | Array of Base64-encoded strings | List of users (identifier) associated to the group with the pattern `[User:1]` where `1` is the user identifier from the database |
## Parameter definitions
These parameters define single data values used in the **Create a new request**, **Update a request dataset**, **Complete an action**, and **Complete a form action** operations.
### Operation values
| Property | Type | Description |
| --------------- | --------- | ---------------------------------------------------------------- |
| `dateTimeValue` | DateTime | Parameter datetime value |
| `name`\* | String | Parameter name |
| `numericValue` | Float | Parameter numeric value |
| `textValue` | String | Parameter text value |
| `fileValue` | FileInput | Parameter file value (see [FileInput values](#fileinput-values)) |
### FileInput values
| Property | Type | Description |
| ------------- | --------------------- | ------------------------------------------------------------------------------- |
| `content` | Base64-encoded string | File content |
| `contentType` | String | File content type |
| `description` | String | File description |
| `name` | String | File name |
| `size` | Int | File size in bytes |
| `updatedAt` | DateTime | Identifies the date and time (`ISO 8601 date format`) when the file was updated |
| `upload` | Upload | File upload |
| `url` | URI string | File URL |
## File upload
As of version 7.2.0, the incoming webhook application supports the `fileValue.updatedAt`, `fileValue.content`, and `fileValue.url` fields when sending FILE parameters (as shown in the previous example).
The `fileValue.updatedAt` field should use the ISO 8601 date format.
### File content
The `fileValue.content` field should contain the file content encoded in base64. In this case, the `fileValue.url` field is not required. You must set the maximum input file content size (see the [Configuration](#configuration) section above for instructions on how to set these).
```
...
{
"name": "FILE",
"fileValue": {
"name": "test.txt",
"contentType": "plain/text",
"size": 76,
"updatedAt": "2017-03-15T15:02:00Z",
"content": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4="
}
}
...
```
### File URL
The `fileValue.url` field contains the file URL. When working with FILE parameters, you must set the input file allowed folders and the maximum input file size (see the [Configuration](#configuration) section above for instructions on how to set these).
You can also disallow file uploads using HTTP and/or HTTPS URLs setting the **Input file allowed HTTP URLs** in the **Webhooks** section on the **Integration** tab in the Administration Module **Configuration Panel** (see [Input file allowed HTTP URLs](https://docs.workflowgen.com/admin/configuration-panel#input-file-allowed-http-urls-1) in the WorkflowGen Administration Guide).
The following path patterns are supported:
* **Local file** should use the File URI scheme:
```
...
{
"name": "FILE",
"fileValue": {
"name": "test.txt",
"description": "test.txt",
"contentType": "plain/text",
"url": "file:///c:/temp/test.txt",
"size": 4714,
"updatedAt": "2017-03-15T15:02:00Z"
}
}
...
```
* **Public file URL:**
```
...
{
"name": "FILE",
"fileValue": {
"name": "update.zip",
"description": "update.zip",
"contentType": "application/zip",
"url": "http://download.workflowgen.com/product/latest/update.zip",
"size": 4120858,
"updatedAt": "2017-03-15T15:02:00Z"
}
}
...
```
* **File URL:**
```
...
{
"name": "FILE",
"fileValue": {
"name": "test.txt",
"description": "test.txt",
"contentType": "plain/text",
"url": "http://localhost:8081/test.txt",
"size": 4714,
"updatedAt": "2017-03-15T15:02:00Z"
}
}
...
```
### Multipart file upload
Incoming webhooks support multipart file uploads for the following mutations:
* `createRequest`
* `completeAction`
* `completeFormAction`
* `updateRequestDataset`
* `createProcessFromXpdl`
* `updateProcessFromXpdl`
* `createGlobalListFromXmlDefinition`
* `updateGlobalListFromXmlDefinition`
#### 📌 Curl example for a single upload
```
curl -X
POST http://localhost/wfgen/hooks/TOKENXXXXXXXXXXXXX
-H 'content-type:multipart/form-data'
-F "payload={\"operation\": \"createRequest\", \"args\": { \"input\": {\"processName\": \"SIMPLE_REQUEST\", \"processVersion\": 1, \"parameters\": [ { \"name\": \"FILE1\", \"fileValue\": {\"uploadMap\":\"1\" }}] } } }"
-F "1=@C:\test1.txt"
```
* The content type should be `multipart/form-data`.
* The `payload` field is required and contains the operation and its arguments.
* `input.parameters[X].fileValue` should contain an `uploadMap` whose value is the `(\"fileValue\": {\"uploadMap\":\"1\" })` key of the file to be uploaded.
* The key should be an alphanumeric string that matches the file key (`"1"` in the above example).
* For each `uploadMap` declared, a file with the same key must be attached.
* Each file to be uploaded should contain the alphanumeric key and the file path (`"1=@C:\test1.txt"`).
* Each attached file must match an `uploadMap`.
* The files should follow the `payload` part.
#### 📌 Curl example for multiple uploads
```
curl -X
POST http://localhost/wfgen/hooks/TOKENXXXXXXXXXXXXX \
-H 'content-type:multipart/form-data' \
-F "payload={\"operation\": \"createRequest\", \"args\": { \"input\": {\"processName\": \"SIMPLE_REQUEST\", \"processVersion\": 1, \"parameters\": [ { \"name\": \"FILE1\", \"fileValue\": {\"uploadMap\":\"1\" }}, { \"name\": \"FILE2\", \"fileValue\": {\"uploadMap\":\"2\" }}] } } }" \
-F "1=@C:\test1.txt" \
-F "2=@C:\test2.txt"
```
#### Limits
* The maximum number of uploads in the same request is 30.
* The maximum file upload size is set in the `HooksMaxInputFileSize` configuration parameter.
{% hint style="info" %}
The `multipart/form-data` content type is only advised for HTTP requests with file uploads. If the `fileValue.name`, `fileValue.description`, `fileValue.contentType`, and `fileValue.size` properties are not defined, they will be set from the uploaded file information; otherwise, they will take the values defined the payload.
{% endhint %}
## Delegation mode
Some of these operations can be done in delegation mode, by adding the `onBehalfOfUserName` (delegator username) or the `onBehalfOf` (delegator ID) arguments to the request JSON payload, such as in the following example:
#### Request payloads:
```
{
"operation": "createRequest",
"args": {
"input": {
"processName": "2_LEVELS_APPROVAL",
"processVersion": 1,
"onBehalfOfUserName": "wfgen_admin"
}
}
}
```
```
{
"operation": "createRequest",
"args": {
"input": {
"processName": "2_LEVELS_APPROVAL",
"processVersion": 1,
"onBehalfOf": "VXNlcjox"
}
}
}
```
In this case, the response payload will also contain the `onBehalfOf` and `onBehalfOfUserName` arguments.
```
{
"clientMutationId": null,
"requestId": "UmVxdWVzdDoxNzI5",
"number": 1729,
"onBehalfOf": "VXNlcjox",
"onBehalfOfUserName": "wfgen_admin"
}
```
In the case of `CancelActionAssignment` and `UpdateRequestDataset` operations, the delegation mode is not supported.
## `clientMutationId`
`clientMutationId` is an optional argument that can be used by the requester to identify the execution of an operation. Its value is defined in the input payload (e.g. a UUID). If defined, the same value is returned by the operation.
#### Request payload:
```
{
"operation": "createRequest",
"args": {
"input": {
"processName": "2_LEVELS_APPROVAL",
"processVersion": 1,
"clientMutationId": "e9468d12-ca3e-4164-ba6c-2bb0843117d0"
}
}
}
```
#### Response payload:
```
{
"clientMutationId": "e9468d12-ca3e-4164-ba6c-2bb0843117d0",
"requestId": "UmVxdWVzdDoxNzY4",
"number": 1768,
"onBehalfOf": null,
"onBehalfOfUserName": null
}
```
## Known limitations
For file type data parameters, the URL must start with `file://`, and the path has to be available to the WorkflowGen server.
## Performance optimization
The value of the `nodeProcessCountPerApplication` setting is set to `0` by default for the best performance in Node.js applications. This creates one node process based on the number of virtual processors that are configured. You can change this value at any time to a custom number of node processes; for example, `nodeProcessCountPerApplication=2` will create two node processes independently of the number of virtual processors.
For more information, see .