Incoming Webhooks

Overview

WorkflowGen features an incoming webhook application that allows users to interact with WorkflowGen from external sources by exchanging JSON payloads using HTTP POST requests. The application supports multiple types of operations, such as creating a new request, completing an action, and some process deployment operations like creating a new process from an XPDL.

Technical requirements

In addition to the standard WorkflowGen installation, the following components are required:

• Node.js v18.20.6

• iisnode

• IIS URL Rewrite

• Visual C++ Redistributable ✏️ Note: This library is required if you encounter the error The specified module could not be found regarding the edge and edge-js libraries when accessing the /wfgen/graphql, /wfgen/hooks, or /wfgen/scim web apps.

For information on the installation procedure, see the WorkflowGen Technical Guide.

Configuration

Maximum query content length

The maximum query content length for incoming webhooks can be set by configuring the maxAllowedContentLength property in the WorkflowGen web.config file. The following example shows how to configure this property as 1 MB (note that the value should always be specified in bytes, so the value in the example is 1,024,000 bytes). The default value is 30,000,000 bytes.

<system.webServer> 
    <security> 
        <requestFiltering> 
            <requestLimits maxAllowedContentLength="1024000" /> 
        </requestFiltering> 
    </security> 
</system.webServer>

Input file allowed folders

You can configure the local or remote folder paths where files used by FILE type parameters are located using the Input file allowed folders setting In the Webhooks section on the Configuration panel Integration tab. (Alternately, you can add the folder names separated by commas to the HooksInputFileAllowedFolders parameter in the WorkflowGen web.config file.)

When using file uploads, you don't need to include the original file folder.

To disallow input file allowed folders, leave this field empty (or the parameter undefined). To allow certain folders only, enter comma-separated values according to the table below:

Value	Description
Empty	No folders allowed
*	All folders allowed
c:\*	All folders on drive c:
c:\Inetpub\*	All subfolders in a specific folder
c:\Inetpub\folder*	All c:\Inetpub folders whose names start with folder 📌 Examples: c:\Inetpub\folder1 c:\Inetpub\folder1\abc c:\Inetpub\folder2
c:\Inetpub\folder2\abc\def	Specific folder only

Input file allowed HTTP URLs

You can configure allowed HTTP URLs for input files using the Input file allowed HTTP URLs setting in the Webhooks section on the Configuration panel Integration tab. (Alternately, you can add the folder names separated by commas to the HooksInputFileAllowedHttpUrls parameter in the WorkflowGen web.config file.)

To disallow file uploads using HTTP and/or HTTPS URLs, leave the field empty (or the parameter undefined). To allow certain URLs only, enter comma-separated values according to the table below:

Value	Description
Empty	No HTTP or HTTPS URLs allowed
*	All HTTP and HTTPS URLs allowed
https://*	HTTPS URLs only
http://*	HTTP URLs only
http://mydomain/*	HTTP from a specific domain only
http://mydomain/folder/*	HTTP from a specific folder only
http://mydomain/folder*	All files and folders whose names start with folder 📌 Examples: http://mydomain/folderfile.jpg http://mydomain/folder/file.jpg http://mydomain/folder2/file.jpg
http://mydomain/folder/file.jpg	Specific file only

Maximum input file size

In the Webhooks section on the Integration tab in the Administration Module Configuration panel, enter the maximum input file size in kilobytes in the Maximum input file size (kB) field.

Alternately, you can set the maximum input file content size in kilobytes as the value of the HooksMaxInputFileSize parameter in the WorkflowGen web.config file.

Maximum input file content size

When working with FILE type parameters content encoded in base64, you must enter the maximum input file content size in kilobytes in the Maximum input file content size (kB) field in the Webhooks section on the Integration tab in the Administration Module Configuration panel.

Alternately, you can set the maximum input file content size in kilobytes as the value of the HooksMaxInputFileContentSize parameter in the WorkflowGen web.config file.

FILE type data content is only recommended for small files under 1 MB.

Performance tuning

WorkflowGen is installed with the following default webhooks settings (located under iisnode in \wfgen\hooks\web.config):

nodeProcessCountPerApplication="1"
maxConcurrentRequestsPerProcess="1024"

With these settings, only one node.exe instance will handle HTTP requests. This should be sufficient in most cases, but you can optimize performance if needed by adjusting these values based on the number of potential concurrent requests.

Creating an incoming webhook application

To create a new incoming webhook application in your WorkflowGen application, click the Add Application button on the Applications page. Then, choose Incoming webhook from the Application type drop-down list, enter the Name and Description, and click Save.

The Applications page will now display your incoming webhook application information, including the application URL. This is the URL you should use to send WorkflowGen incoming webhooks. The last component of this URL corresponds to a token that WorkflowGen will use to identify your incoming webhooks.

You should fill in the Impersonate username textbox with the WorkflowGen username you use to perform your desired operations. Be aware that your impersonated user must have your asked-operation-required rights to complete the action; if not, you'll receive a security error on your response payload. As well, if the impersonate username is not set, the workflow engine service default identity will be used (as defined in the Security section on the Integration tab in the Configuration panel).

• The generated URL and its associated token must remain private and not exposed to end-users in client-side (in JavaScript, for example). You should treat the token with the same level of security as you would a password.

• If the token used in the incoming webhook URL is missing or invalid, a 404 status code will be returned. If the associated user is invalid, archived, or inactive, a 403 status code will be returned. In both cases, the response will contain a descriptive error message.

User impersonation

User impersonation is supported but not recommended, and should be used only when no other technical solutions are possible. (For example, OpenID Connect-based authentication methods allow you to use access tokens to perform API operations on the client and server sides without impersonation.)

System operations allowed users can impersonate another WorkflowGen user account by setting this account’s username as the value of the x-wfgen-impersonate-username HTTP request header.

To enable webhooks impersonation, you need to set the following parameters in the \wfgen\web.config file:

<add key="HooksAllowImpersonateUser" value="Y" />
<add key="HooksApiKeyEnabled" value="Y" />
<add key="HooksApiKey" value="<YOUR_SECRET_VALUE>" />

Here's an exemple of a curl request with user impersonation:

curl --location --request POST 'https://<your_server>/wfgen/hooks/<yourHooksUrlKey>' \ 
--header 'Content-Type: application/json' \ 
--header 'x-wfgen-impersonate-username: <usernameToImpersonate>' \ 
--header 'x-wfgen-hooks-api-key: <YOUR_SECRET_VALUE>' \ 
--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 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 API. In most cases, object numbers can be used instead of IDs in operation payloads.

In case of an error, you'll 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:

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

Other required or optional parameters specific to the webhook operation might be needed.

Request operations

Create a new request

To 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 section in the WorkflowGen Administration Guide for more information.)

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)
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 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)

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)
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)
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 exception ERROR: 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 exception ERROR: 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: PRIVATE PUBLIC
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: YEARS MONTHS DAYS HOURS MINUTES SECONDS
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: DEV TEST ACTIVE ARCHIVE

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: DEV TEST ACTIVE ARCHIVE
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)

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: PRIVATE PUBLIC
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: YEARS MONTHS DAYS HOURS MINUTES SECONDS
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: DEV TEST ACTIVE ARCHIVE

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 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)

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: HUMAN ROLE COORDINATOR
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: HUMAN ROLE COORDINATOR
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: REQUESTER ACTOR SUPERVISOR
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: REQUESTER ACTOR SUPERVISOR
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: HUMAN ROLE COORDINATOR
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: HUMAN ROLE COORDINATOR
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 type WFCONTEXT: Application XML ADO.NET Dataset context format type RECORDSET: 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: Assembly WEBPROCASYNC: Asynchronous web procedure INWEBHOOK: Incoming webhook WEBSERVICE: SOAP web service WCFSERVICE: WCF service WEBAPP: Web application WEBPROC: Web procedure NONINTERACTIVECLIENT: 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 type WFCONTEXT: Application XML ADO.NET Dataset context format type RECORDSET: 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: TEXT NUMERIC DATETIME FILE
description*	String	Application parameter description
direction*	String	Application parameter direction: IN OUT INOUT
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_SQLCLIENT SYSTEM_DATA_OLEDB SYSTEM_DATA_ODBC SYSTEM_DATA_ORACLECLIENT ORACLE_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 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)

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_SQLCLIENT SYSTEM_DATA_OLEDB SYSTEM_DATA_ODBC SYSTEM_DATA_ORACLECLIENT ORACLE_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 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)

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 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 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 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": "[email protected]",
      "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": "[email protected]",
      "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

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 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 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 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.

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.

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 the Best practices and troubleshooting guide for node applications on Azure App Service Windows Microsoft article.