> For the complete documentation index, see [llms.txt](https://docs.advantys.com/workflowgen-integration-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.advantys.com/workflowgen-integration-guide/7.1.0-1/incoming-webhooks.md). # Incoming Webhooks ## Overview As of version 7.0.0, 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: * [IIS URL Rewrite](https://www.iis.net/downloads/microsoft/url-rewrite)
* [Node.js version 6.11.5](https://nodejs.org/download/release/v6.11.5/)
* [iisnode](https://github.com/Azure/iisnode/releases/tag/v0.2.21)
* [Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads)\ \ **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 security reasons, it is strongly recommended to enable the HTTPS protocol on your IIS server. For information on the installation procedure, see the [WorkflowGen Technical Guide](https://advantys.gitbooks.io/workflowgen-technical-reference-guide/content/). ## Create 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. **Important:** 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. 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**). ## Send 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](/workflowgen-integration-guide/7.1.0-1/graphql.md) 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` and `inTest` parameters are optional and are 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, "isTest": true } } }' 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 **Note:** 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](https://docs.advantys.com/workflowgen-administration-module-reference-guide/process-definition#process-form) section in the [WorkflowGen Administration Guide](https://docs.advantys.com/workflowgen-administration-module-reference-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 [Parameter definitions](/workflowgen-integration-guide/7.1.0-1/incoming-webhooks.md#parameter-definitions)) | ### 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" } ] } ``` #### 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 [Parameter definitions](/workflowgen-integration-guide/7.1.0-1/incoming-webhooks.md#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 | | `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 | ## 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 [Parameter definitions](/workflowgen-integration-guide/7.1.0-1/incoming-webhooks.md#parameter-definitions)) | ### 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 | |

exception: {

message

source

| String |

Exception:

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

| ### 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 | ## 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 | ## 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, "isTest": true, "onBehalfOfUserName": "wfgen_admin" } } } ``` ``` { "operation": "createRequest", "args": { "input": { "processName": "2_LEVELS_APPROVAL", "processVersion": 1, "isTest": true, "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, "isTest": true, "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.