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:

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

Configuration

Maximum query content length

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

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

Input file allowed folders

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

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

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:

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.

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

Sending data in JSON

The incoming webhook application receives your HTTP POST request payload formatted as a JSON object.

In case of an error, you will get a response payload providing error details such as:

{
  "error": "Advantys.Workflow.ServiceFacade: CreateRequest error: A process ID or name is required"
}

Curl example

The requests should respect the structure shown in this example, where operation refers to the name of the operation to execute, and args contains the input node that groups all of the request parameters to perform the operation.

To create a new request, the processName parameter is required. The processVersion parameter is optional and is used to find the correct process you want to use to create your request.

Request payload:

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

OpenAPI v2 endpoints

Webhook operation definitions

Use this endpoint to retrieve webhook operation definitions based on the OpenAPI v2 specification (in JSON format).

URI: /wfgen/hooks/openapi/v2

Webhook operation execution

Use this endpoint to execute a webhook operation using HTTP POST, replacing :operation with the name of the incoming webhook operation (e.g. createRequest).

URI: /wfgen/hooks/operations/:operation

Required parameters

• :operation: Name of the incoming webhook operation defined in the URI Note: The operation name is not required inside the request payload.

• x-wfgen-hooktoken: Webhook token value specified in the HTTP request header, which is the same token value as used in a classic incoming webhooks URL

Request operations

Create a new request

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

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

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

Delete a request

A request can be deleted by using the request number or the request ID.

Request payloads:

{
  "operation": "deleteRequest",
  "args": {
    "input": {
      "number": 1728
    }
  }
}

{
  "operation": "deleteRequest",
  "args": {
    "input": {
      "id": "UmVxdWVzdDoxNzI4"
    }
  }
}

Response payload:

{
  "clientMutationId": null
}

Properties

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

Complete a form action

Request payload:

{
  "operation": "completeFormAction",
  "args": {
    "input": {
      "requestNumber": 1765,
      "number": 1,
      "parameters": [
        {
          "name": "NEW_PARAMETER",
          "textValue": "My parameter"
        }
      ]
    }
  }
}

Response payload:

{
  "clientMutationId": null,
  "actionId": "QWN0aW9uOjE3NjUtLS0x",
  "number": 1,
  "requestNumber": 1765,
  "onBehalfOf": null,
  "onBehalfOfUserName": null
}

Properties

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

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

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

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

End-user operations

Create a new favorite

The incoming webhook application lets users add processes and views to their favorites lists using the process or view IDs.

Request payload:

{
  "operation": "createFavorite",
  "args": {
    "input": {
      "itemId": "UHJvY2VzczoxMTA="
    }
  }
}

The above code will create a favorite using the process or view description, but adding a custom description is also possible, as shown in the following example:

Request payload:

{
  "operation": "createFavorite",
  "args": {
    "input": {
      "itemId": "UHJvY2VzczoxMTA=",
      "description": "My custom description"
    }
  }
}

Response payload:

{
  "clientMutationId": null,
  "favoriteId": "RmF2b3JpdGU6MTQ="
}

Properties

Update a favorite

The incoming webhook application lets users update an existing favorite process or view by using its favorite ID.

Request payload:

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

Response payload:

{
  "clientMutationId": null,
  "favoriteId": "RmF2b3JpdGU6MTQ="
}

Properties

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

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