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.

Technical requirements

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

Node.js v10.15.3
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 must set the local or remote folder paths where files used by FILE type parameters are located. In the Webhooks section on the Integration tab in the Administration Module Configuration Panel, enter the folder names separated by commas in the Input file allowed folders (comma separated values) field.

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.

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.

To disallow file uploads using HTTP and/or HTTPS URLs, leave the field empty. 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 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, a 403 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:

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

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

System access users

Some operations (such as CancelAction and UpdateRequestDataset) require users to have system access to perform the operations. This can be configured in the System operations allowed users field under Security on the Integration tab in the Configuration Panel.

Request operations

Create a 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:

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

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

Array of parameters (see )

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

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

Array of parameters (see )

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

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

Array of parameters (see )

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

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 exception
ERROR: 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:

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

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:

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

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 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,
  "favorite": {
    "id": "RmF2b3JpdGU6MjA=",
    "ownerId": "VXNlcjox",
    "description": "My custom description",
    "type": "PROCESS",
    "itemId": "UHJvY2VzczoxMTA=",
    "onBehalfOf": null
  }
}

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:

{
  "operation": "updateFavorite",
  "args": {
    "input": {
      "id": "UHJvY2VzczoxMTA=",
      "description": "Updated description"
    }
  }
}

Response payload:

{
  "clientMutationId": null,
  "favorite": {
    "id": "RmF2b3JpdGU6MTQ=",
    "ownerId": "VXNlcjox",
    "description": "Updated description",
    "type": "PROCESS",
    "itemId": "UHJvY2VzczoxMTA=",
    "onBehalfOf": null
  }
}

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:

{
  "operation": "deleteFavorite",
  "args": {
    "input": {
      "id": "RmF2b3JpdGU6MTQ="
    }
  }
}

Response payload:

{
  "clientMutationId": null
}

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:

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

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:

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

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

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

description

String

Category description

name

String

Category name

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

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:

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

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:

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

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:

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

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,
  "application": {
    "id": "QXBwbGljYXRpb246Mzk=",
    "name": "MY_ASSEMBLY_APPLICATION",
    "description": "My assembly application description",
    "type": "ASSEMBLY",
    "url": null,
    "wsdl": null,
    "username": null,
    "password": null,
    "assemblyName": "CustomAssembly.Applications",
    "assemblyClassName": "CustomAssembly.Applications.Converters",
    "method": "Convert",
    "contentType": null,
    "contextFormat": null,
    "isSchemaDefinitionEmbedded": false,
    "isDefault": false,
    "isActive": true,
    "clientId": null
    }
  }
}

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

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,
  "application": {
    "id": "QXBwbGljYXRpb246Mzk=",
    "name": "MY_NEW_ASSEMBLY_APPLICATION_NAME",
    "description": "My assembly application description",
    "type": "ASSEMBLY",
    "url": null,
    "wsdl": null,
    "username": null,
    "password": null,
    "assemblyName": "CustomAssembly.Applications",
    "assemblyClassName": "CustomAssembly.Applications.Converters",
    "method": "Convert",
    "contentType": null,
    "contextFormat": null,
    "isSchemaDefinitionEmbedded": false,
    "isDefault": false,
    "isActive": true,
    "clientId": null
    }
  }
}

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 type
WFCONTEXT: Application XML ADO.NET Dataset context format type
RECORDSET: 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: 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

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,
  "applicationParameter": {
     "id": "QXBwbGljYXRpb25QYXJhbWV0ZXI6MjAtLS02",
    "name": "MY_PARAMETER",
    "description": "My parameter description",
    "dataType": "TEXT",
    "direction": "IN",
    "isRequired": true,
    "isDefault": false
  }
}

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:

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

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

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

As of WorkflowGen version 7.14.0, incoming webhooks support multipart file uploads for the following mutations:

createRequest
completeAction
completeFormAction
updateRequestDataset

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 https://docs.microsoft.com/en-us/azure/app-service/app-service-web-nodejs-best-practices-and-troubleshoot-guide#nodeprocesscountperapplication.

PreviousWeb Services API NextOutgoing Webhooks

Last updated 3 years ago