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:
Visual C++ Redistributable ✏️ Note: This library is required if you encounter the error
The specified module could not be found
regarding theedge
andedge-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.
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, 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 Control 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
):
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 will 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, a403
status code will be returned. In both cases, the response will contain a descriptive error message.
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 will get a response payload providing error details such as:
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:
Response payload:
The response payload will be structured as follows:
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).
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
).
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
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 form section in the WorkflowGen Administration Guide for more information.)
Request payload:
Response payload:
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:
Response payload:
Properties
Property
Type
Description
processName
String
Process name (required)
processVersion
Int
Process version, used to find the correct process you want to use to create the request
clientMutationId
String
Client mutation identifier
isTest
Boolean
Indicates if the process is in test
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
processId
Base64-encoded string
Process identifier with the pattern [Process:1]
where 1
is the process identifier from the database
parameters
Array
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:
Response payload:
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
number
Int
Request number
id
Base64-encoded string
Request identifier with the pattern [Request:1]
where 1
is the request identifier from the database
parameters
Array
Cancel a request
You can cancel a request by using the request number or the request ID.
Request payloads:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
number
Int
Request number
id
Base64-encoded string
Request identifier with the pattern [Request:1]
where 1
is the request identifier from the database
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:
Response payload:
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:
Response payload:
To complete an action, a parameter array can be included in the request payload arguments.
Request payload:
Response payload:
Properties
Property
Type
Description
requestNumber
Int
Request number
number
Int
Action number
activityName
String
Activity name
clientMutationId
String
Client mutation identifier
isTest
Boolean
Indicates if the process is in test
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
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
parameters
Array
Complete a form action
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
activityName
String
Activity name
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
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
parameters
Array
requestNumber
Int
Request number
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:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
exception: {
message
source
String
Exception:
Exception message
Exception source
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
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
requestNumber
Int
Request number
type
Cancellation type:
CANCEL
: Cancellation exceptionERROR
: Error exception
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:
Response payload:
Properties
Property
Type
Description
activityName
String
Activity name
clientMutationId
String
Client mutation identifier
exception: {
message
source
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
requestNumber
Int
Request number
type
Cancellation type:
CANCEL
: Cancellation exceptionERROR
: Error exception
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:
Response payload:
Properties
Property
Type
Description
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
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
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
requestNumber
Int
Request number
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:
Response payload:
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
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
requestNumber
Int
Request number
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:
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:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
description
String
Favorite description
itemId
Base64-encoded string
Favorite item identifier with the pattern [Favorite:1]
where 1
is the favorite identifier from the database
Update a favorite
The incoming webhook application lets users update an existing favorite process or view by using its favorite ID.
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
description
String
Favorite description
itemId
Base64-encoded string
Favorite item identifier with the pattern [Favorite:1]
where 1
is the favorite identifier from the database
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:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
itemId
Base64-encoded string
Favorite item 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.
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
message
String
New comment message
subjectId
Base64-encoded string
Identifier of the object to which the comment with be added with the pattern [Request:1]
where 1
is the request identifier from the database
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.
Request payload:
Response payload:
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.
Request payload:
Response payload:
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
Category operations
Create a new category
Only administrators can create a category.
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationid
String
Client mutation identifier
description
String
Category description
name
String
Category name
Update a category
Only administrators can update a category.
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationid
String
Client mutation identifier
description
String
Category description
id
String
Category identifier with the pattern [Category:1]
where 1
is the category identifier from the database
name
String
Category name
Delete a category
Only administrators can delete a category.
Request payload:
Response payload:
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:
Response payload:
Properties
Property
Type
Description
clientMutationid
String
Client mutation identifier
description
String
Process folder description
name
String
Process folder name
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:
Response payload:
Properties
Property
Type
Description
clientMutationid
String
Client mutation identifier
description
String
Process folder description
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
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:
Response payload:
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:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
accessLevel
Process access level:
PRIVATE
PUBLIC
categoryNames
String
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
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
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
Process state:
DEV
TEST
ACTIVE
ARCHIVE
Create a new process from an XPDL
A process can be created from its XPDL definition.
Request payload:
Response payload:
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
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
Update a process
This operation updates process properties from the process identifier.
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
accessLevel
Process access level:
PRIVATE
PUBLIC
categoryNames
String
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
helpEmail
String
Process help information email
helpText
String
Process help information text
helpUrl
URI
Process help information URL
id
Base64-encoded string
Process identifier with the pattern [Process:1]
where 1
is the process identifier from the database
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
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
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:
Response payload:
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
id
Base64-encoded string
Process identifier with the pattern [Process:1]
where 1
is the process identifier from the database
useVersionNumber
Boolean
Specifies whether or not to import the process version number from the process definition
xpdl
FileInput
Process definition in XPDL format
Delete a process
A process can be deleted by using the process identifier.
Request payload:
Response payload:
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:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
name
String
Global participant name
type
Global participant type:
HUMAN
ROLE
COORDINATOR
description
String
Global participant description
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
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
Update a global participant
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
name
String
Global participant name
type
Global participant type:
HUMAN
ROLE
COORDINATOR
description
String
Global participant description
id
Base64-encoded string
Global participant identifier with the pattern [GlobalParticipant:1]
where 1
is the global participant 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
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
Delete a global participant
Request payload:
Response payload:
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:
Response payload:
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 where 1
is the global participant identifier from the database
query
String
Supervisor scope query
role
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:
Response payload:
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
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:
Response payload:
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:
Response payload:
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
Local process participant type:
HUMAN
ROLE
COORDINATOR
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
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
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
Update a local process participant
Request payload:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
name
String
Local process participant name
id
Base64-encoded string
Local process participant identifier with the pattern [LocalProcessParticipant:1]
where 1
is the local process participant identifier from the database
description
String
Local process participant description
type
Local process participant type:
HUMAN
ROLE
COORDINATOR
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
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
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
Delete a local process participant
Request payload:
Response payload:
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:
Response payload:
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
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
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:
Response payload:
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
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
id
Base64-encoded string
Application identifier with the pattern [Application:1]
where 1
is the application identifier from the database
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
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
Delete an application
Only administrators can delete a workflow application.
Request payload:
Response payload:
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:
Response payload:
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
Application parameter data type:
TEXT
NUMERIC
DATETIME
FILE
description
String
Application parameter description
direction
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:
Response payload:
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:
Response payload:
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
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:
Response payload:
Properties
Property
Type
Description
clientMutationId
String
Client mutation identifier
xmlDefinition
FileInput
XML definition
Update a global list
Request payload:
Response payload:
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
providerName
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:
Response payload:
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
XML definition
Delete a global list
Request payload:
Response payload:
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
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
Object
File values (see below)
File 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 when the file was updated
upload
Upload
File upload
url
URI
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).
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 prevent 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:
Public file URL:
File URL:
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
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 anuploadMap
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
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:
In this case, the response payload will also contain the onBehalfOf
and onBehalfOfUserName
arguments.
In the case of CancelActionAssignment
and UpdateRequestDataset
operations, the delegation mode is not supported.
clientMutationId
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:
Response payload:
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 https://docs.microsoft.com/en-us/azure/app-service/app-service-web-nodejs-best-practices-and-troubleshoot-guide#nodeprocesscountperapplication.
Last updated