This guide provides instructions on:

How to use the WorkflowGen GraphQL API

How to use the WorkflowGen web services API

How to create incoming and outgoing webhooks

How to build applications for WorkflowGen using .NET Framework

How to use WorkflowGen.My to develop a RemoteLaunch SDK application to launch a process from outside the WorkflowGen environment

How to use an OAuth 2.0 access token for server-side .NET development

How to create custom authentication modules

User management and directory synchronization

How to customize the WorkflowGen User Portal

How to create integrations using WorkflowGen URLs to perform certain process functions

How to set up and customize notifications

The appendix contains a table that lists time zone names and IDs

Overview

Outgoing webhooks are a simple way to send HTTP POST requests to external applications. They are like notifications, but the recipient is an external application URL instead of an email address, and the message is a JSON payload instead of a text or HTML body.

To create outgoing webhooks, use the RESTAPICLIENT or SENDHTTPPOST workflow application, which you can use as a system action in your workflows.

It's recommended to use RESTAPICLIENT instead of SENDHTTPPOST, since RESTAPICLIENT provides more extensive features.

Integrating webhooks with WorkflowGen

RESTAPICLIENT workflow application

The RESTAPICLIENT workflow application is the preferred solution for advanced REST integration, since SENDHTTPPOST provides only a subset of RESTAPICLIENT features intended for simple use cases.

RESTAPICLIENT allows you to call REST API endpoints to exchange information with other applications through HTTP requests, and can be used to build integrations with extendable applications (such as Azure services and Slack).

It also allows you to call a REST API endpoint using application/json or application/x-www-form-urlencoded payloads. RESTAPICLIENT will then receive and process the response from the external API by mapping the response content with defined OUT parameters.

For information on RESTAPICLIENT, see the section in the .

SENDHTTPPOST workflow application

The SENDHTTPPOST workflow application (available as of version 6.6.0) allows WorkflowGen to send HTTP POST requests to external applications using JSON or URLENCODED payloads. The SENDHTTPPOST application will then receive and process the response from the external API.

For more information on how the application works, see in the .

For samples of APIs that use SENDHTTPPOST, see the repository on GitHub.

Performance optimization

The value of the nodeProcessCountPerApplication setting is set to 0 by default for the best performance in Node.js applications. This creates one node process based on the number of virtual processors that are configured. You can change this value at any time to a custom number of node processes; for example, nodeProcessCountPerApplication=2 will create two node processes independently of the number of virtual processors.

For more information, see the Microsoft article.

Banner

📌 Example of a custom banner

The WorkflowGen app banner can be customized via the Administration Module, in the Banner section on the Portal tab in the Configuration panel.

Custom menus

You can create custom menus for the User Portal by creating and modifying the portal.xml XML file in the CustomMenu folder located in the \wwwroot\wfgen\App_Data\customMenus folder.

These custom menus will then be available as extra menu options on the User Portal home page.

Stylesheets

The User Portal stylesheet can be customized to match your organization's colors and styles. The CSS files are located in the \wfgen\App_Themes\Default\portal\css folder.

Common process data

This parameter allows you to enter the same names and data types, which can then be used in a multi-process view.

For example, if you have process data such as CUSTOMER (TEXT) that are used in most of your processes, you can define these data as User Portal common process data by entering them in the Common process data name list field.

Overview

Clients that are already using Shibboleth Service Provider 3 to manage resource access (such as services or applications) can quickly integrate with WorkflowGen by offering users Single Sign-On (SSO) authentication for a secure and seamless user experience.

For this, Shibboleth SP3 provides a native module for IIS 7 and later that passes user information to WorkflowGen via the REMOTE_USER environment variable.

The WorkflowGen website and web apps should have only the Anonymous Authentication method enabled under the IIS Manager Authentication feature page.

Installation

For installation and configuration details, see the documentation.

Overview

The majority of WorkflowGen clients use Windows Integrated Authentication in IIS, although several other modes are supported. By using Integrated Authentication, users are seamlessly authenticated to WorkflowGen by using the Windows local session (network password) of the user.

WorkflowGen also supports .NET web form-based authentication and custom HTTP module authentication for single sign-in (SSO) integration.

If your organization has implemented the Shibboleth ecosystem, you can integrate WorkflowGen with the Shibboleth SP3 SSO module.

Notification templates

Notification templates are text files with HTML content and WorkflowGen macros. The default notification templates are located in the \wfgen\App_Data\Templates\Emails folder.

The stylesheet must be embedded in the template. You can attach a file to the notification via the <WF_PROCESS_INST_RELDATA_FILE.YOURPROCESSDATANAME> macro.

📌 Example of notification template HTML code (body section)

You can also use a custom notification template in a process data and use this process data in an additional notification of a workflow action.

For more information, see the section in the .

SMTP gateway

We recommend using the local IIS SMTP server. There are several advantages to using an SMTP relay at the IIS WorkflowGen server:

• Better performance, since messages are sent directly to the relay.

• Local SMTP acts as a buffer to avoid loss of emails if the main SMTP server is not available.

• Connection problems are reduced because the relay manages communication problems.

• The relay traces email deliveries in its own log files.

WorkflowGen supports pickup directories for best performance and availability. This means that the notifications are created in a pickup directory managed by the SMTP server. IIS SMTP server and Exchange support pickup directory management.

For more information, see in the .

Directory synchronization

WorkflowGen supports multiple connectors to Active Directory and other LDAP user directories. If these connectors are not used or are not well populated, it may be necessary to consider using the WorkflowGen Text connector, which allows the import of user data from various sources of information such as HR systems.

Richer directory information gives WorkflowGen more ability to integrate organizational data seamlessly into processes:

• Automatically fill in some form fields by using macros (e.g. Current User.Department)

• Automatic to the manager assignment method

• Reuse groups in process participants

• to retrieve users

See the section in the for information on how to configure directory synchronization.

You can also find FAQs on user provisioning and directory synchronization in the section on the .

Overview

When using an OpenID Connect (OIDC) authentication method with WorkflowGen, an OAuth 2.0 access token is available for server-side .NET development. This token enables you to make requests to the GraphQL API as well as to your own APIs, depending on your provider's configuration.

For instructions on how to configure an OIDC provider with WorkflowGen, see the WorkflowGen for Azure guide for Microsoft Entra ID (formerly Azure Active Directory) or the WorkflowGen Technical Guide for Active Directory Federation Services (AD FS), Auth0, and Okta.

Using an access token in web form code-behind

You can get the current user's access token from the new this.CurrentUserAccessToken() public instance method of the WorkflowPage class (available since WorkflowGen.My version 4.6.0) in order to make calls from the code-behind to WorkflowGen's GraphQL API or to your own APIs. To do this, follow the example code below:

There are settings that need to be added to the WebForms web.config file in order for this example to work. You must add the reference to the System.Net.Http namespace and deactivate unobtrusive validation mode. Here's a minimal web.config content that you can use:

Overview

The RemoteLaunch SDK is used to launch a WorkflowGen process from the outside of the WorkflowGen environment. This section will explain how to develop a RemoteLaunch SDK application using WorkflowGen.My v3.3. You'll need to create a new website for each RemoteLaunch SDK application you need.

Creating the RemoteLaunch website

Suggested development tools

• Visual Studio Standard or Professional 2013 or later

Website installation directory

We strongly suggest that you put all of your RemoteLaunch SDKs in the \wfgen\wfapps\sdk\MyRemoteLaunch folder.

Creating the application in IIS

The RemoteLaunch site directory must be declared as an IIS application in order to be recognized as a .NET website application. Follow these instructions to declare your website directory as an IIS application:

For IIS 7 and later

1. Open Internet Information Services (IIS) Manager.

2. Navigate to your web form location, which should be placed under the Default Web Site node, under \wfgen\wfapps\sdk\MyRemoteLaunch.

3. Right-click on MyRemoteLaunch and choose Convert to Application.

Creating the project with Visual Studio

Creating the project

1. Open Visual Studio.

2. Choose File > New Web Site.

3. Select ASP.NET Empty Web Site.

4. Select File system from the Location

Obtaining detailed error messages

By default, you'll have no web.config file in your web project if you're using C# as your development language in the Visual Studio IDE. In order to be able to see complete error messages when you want to debug, you need to have a web.config file.

In order to be able to see complete error messages, change the following properties in the web.config file:

1. Make sure this line is set to "true":

2. Make sure this is not commented and that the mode="Off":

Basic implementation

Overview

In order to demonstrate how to implement a RemoteLaunch application, we'll make a simple RemoteLaunch example that sends a context containing two parameters to a WorkflowGen process: AMOUNT and NAME. This process will be launched with these two parameters.

Reference

You must add a reference to WorkflowGen.My.dll in your web project, then add a using statement for the WorkflowGen.My.Data namespace of the WorkflowGen.My assembly.

Defining the Page_Load event

We'll use the Page_Load event to immediately start the remote process. Here's the basic code structure we are going to use for the RemoteLaunch SDK application:

Using the web.config to store your configurations

It's recommended to use the web.config file to store all the configurations, instead of hard coding them directly in your website's code-behind. The advantage to this is that if you modify the name of the process to launch, or the username of the launching user, or any other configurations, you won't have to change your code-behind files, only your web.config file, without recompiling the web application. Here are the web.config values that we'll use:

The following code declares all the variables we need for the RemoteLaunch, then gets the web.config values to populate some of these variables:

Building a context from scratch

We now need to build a new context to send to WorkflowGen in order to start the new process that needs two parameters: AMOUNT and NAME, which are numeric and text parameters, respectively. Here's the necessary code to create a new context:

Starting the process and sending the context

After having created the context, we need to make a web request to WorkflowGen to start the remote process, and we also need to post the context to the new process instance. Here's the necessary code:

Managing errors

After starting the process, you might receive errors from WorkflowGen if something's not working as expected. Here's the necessary code to display the WorkflowGen error so that you can debug your RemoteLaunch application:

Application types

The following application types are covered in this section:

• Web procedures

• Asynchronous web procedures

The following application types are not covered in this section:

• Incoming webhooks

• Non-interactive clients

• SOAP web services

• WCF services

How it works

When an action using a workflow application is launched, WorkflowGen sends the parameters in a JSON or XML file (depending on the context format previously chosen during the creation of the application) to the application using the HTTP protocol. The application uses the JSON or XML file to get the parameters and executes its operations.

Once the application is done, a JSON or XML file with the OUT parameters is sent back to WorkflowGen. JSON is supported by Webproc and Webproc Async applications. For web services, the SOAP protocol is used to communicate with the application. Web services that don’t use the SOAP protocol to communicate with WorkflowGen application will be referred as Webproc applications.

Requirements for .NET development

.NET Framework version

The WorkflowGen.My assembly requires .NET Framework 4.

WorkflowGen.My assembly

In order to implement a custom workflow application using the .NET Framework, you must have the latest version of WorkflowGen.My 4.x referenced in your project. To directly reference an assembly in your web project, do the following:

1. Create a \bin directory under your project root folder (e.g. \wfgen\wfapps\sdk\MyProject\bin).

2. Copy the WorkflowGen.My.dll file to this folder.

3. Right-click on your project name and choose Add reference...

You can also put this assembly in your GAC (Global Assembly Cache) in order to have only one centralized reference, instead of referring to a copy of the assembly in each project. To install the assembly in your GAC, do the following:

1. Copy WorkflowGen.My.dll to DRIVE:\Windows\system32.

2. Open a command prompt and browse to DRIVE:\Program Files (x86)\Microsoft Visual Studio 14.0\SDK\v3.5\Bin.

3. Enter the command gacutil /i c:\windows\system32\WorkflowGen.My.dll, then press ENTER

If you want to use an assembly from the GAC, you should drop your assemblies into a local folder, and then add a reference to the assembly from this folder. You may want to set the Copy Local property to False for that assembly if you don't want the assembly to be copied locally to your project folders. At runtime, the application will automatically use the assembly from the GAC.

Configuration settings (app.config or web.config)

The WorkflowGen.My assembly does not require any particular configuration settings.

Deploying a custom assembly

There are some considerations when deploying a custom assembly SDK workflow application in WorkflowGen, namely the assembly location, the reference to WorkflowGen.My, and references to other software libraries.

Assembly location

There are two ways of deploying an assembly file in WorkflowGen.

Method 1: Reference by assembly’s full name

The assembly file must be copied to the three bin folders containing the WorkflowGen executable files: \wfgen\bin, \wfgen\ws\bin, and DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin.

Method 2: Reference by assembly’s path (full physical path with file name)

The assembly file can be copied to a custom folder such as DRIVE:\MyWorkflowApps\Assembly.dll, and then use that specific path in the workflow application’s definition.

Reference to WorkflowGen.My

WorkflowGen.My v3.1.0 and earlier

WorkflowGen.My versions 3.1.0 and earlier are strong-named, which means your assembly must be built with and use the same version as your target WorkflowGen. This requires recompiling your assembly whenever you upgrade WorkflowGen to a newer version.

You can use one of the following workarounds to overcome this requirement:

1. Install the required WorkflowGen.My version in the system's global assembly cache (GAC). For instructions on how to do this, see the Microsoft article. OR

2. Add a delegate to handle the assembly resolve event in order to load the current WorkflowGen.My version. For instructions on how to do this, see the article on the WorkflowGen Forum & Knowledge Base. OR

3. Add a web configuration setting to redirect the required version to the current version of WorkflowGen.My. For more information, see the Microsoft article.

WorkflowGen.My v3.2.0 and later

As of version 3.2.0, WorkflowGen.My is no longer strong-named in order to allow non-specific version dependency when referenced by your assembly. You can simply deploy your assembly file using one of the two methods in the section above in WorkflowGen 6.2.0 and later.

References to other software libraries

If your assembly uses third-party libraries, then these must also be deployed into the three WorkflowGen executable \bin folders. Alternatively, they can be installed into the system’s global assembly cache (GAC) if they are strong-named assemblies.

WorkflowContext

WorkflowContext is a JSON or XML data structure used to exchange parameters with WorkflowGen. The context format is used by both web procedures and asynchronous web procedures.

For an example of an XML ADO.NET DataSet context, see in the section.

As of WorkflowGen 7.0.0, the application can build ContextParameters instances from JSON strings. The JSON should respect the following structures:

📌 JSON example (web procedure)

📌 JSON example (asynchronous web procedure)

WorkflowContext creation with WorkflowGen.My

Loading the WorkflowGen context

In order to manipulate a WorkflowGen context, it is necessary to load it into a ContextParametersobject instance. Usually, you will receive the context in a string variable. The following sample code loads the context from a workflowGenContext string:

Get a particular parameter from the context

You can access any data parameter in the WorkflowGen context by using the contextHandler (ContextParameters instance) that you created in the previous section. When you access a single parameter, you store it in a ContextParameter object to manipulate it. The following example accesses a DATE_EXAMPLE parameter in the previously loaded context:

Get the ContextParameter value

To access the value of the context parameter, use the Value property of the ContextParameter instance that you retrieved in the previous section:

The dateValue variable now contains the DATE_EXAMPLE parameter value.

Filtering the ContextParameters collection

Suppose that you would like to iterate over all the IN parameters of the ContextParameters instance. You could do this by using a filter and then using the collection enumerator. Don't forget to remove the filter afterward, or else you won't be able to access the other parameters.

Modifying a parameter value in the context

After you have stored your data parameter in a ContextParameter, you can modify its value:

Adding a parameter to the context

In order to add a parameter to the context, you need to build a new ContextParameter instance, define its name and direction, and then add it to the ContextParameters instance you already have:

Working with file parameters

File parameters need to be put into a ContextFileReference instance. The following is an example that extracts a file parameter value into a ContextFileReference, then modifies the file parameter so that it points to another sample file.

As of WorkflowGen 7.1.0, JSON context file parameters use the file URI scheme in the fileValue URL field (see for more information).

Web procedure development using an ASP.NET XML web service

Overview

The most widely-used type of WorkflowGen integration is the web procedure. Web procedures are used to receive a WorkflowGen context as a parameter, manipulate it, and then return the modified context to WorkflowGen.

Creating the web procedure

Visual Studio Standard or Professional 2013 or later is suggested for development.

Web procedure installation directory

We strongly suggest that you put all of your web services in the \wfgen\wfapps\WebServices\MyWebProc folder.

Creating the application in IIS

The web service directory must be declared as an application in IIS in order to be recognized as a .NET web service application. To declare your web service directory as an IIS application, do the following:

For IIS 7 and later

1. Open Internet Information Services (IIS) Manager.

2. Navigate to your web form location, which should be under the Default Web Site node, under \wfgen\wfapps\webservices\MyWebProc.

3. Right-click on MyWebProc and choose Convert to Application.

Creating a web procedure workflow application using an ASP.NET XML web service

You can create a web procedure using an ASP.NET web service, but this Visual Studio template is only available for .NET versions 2.0 to 3.5.

1. Open Visual Studio.

2. Select File > New Web Site.

3. Choose ASP.NET Web Service (available for .NET Framework versions 2.0 to 3.5).

4. Choose File system from the Location drop-down list.

Obtaining detailed error messages

In order to be able to see complete error messages, change the following properties in the web.config file:

Make sure this line is set to true:

Make sure this is not commented and that the mode="Off":

Authorize GET and POST protocols

In order to use a web service with WorkflowGen, the GET and POST protocols must be enabled in the web service's web.config file. The following are the necessary nodes to insert in the system.web node of your web.config file:

Configuring the IIS rendering framework version in the web.config file

You will need to revert to the behavior of having only .aspx pages trigger request validation by adding the following code to your web.config file:

Basic implementation

Overview

In order to demonstrate how to implement a web procedure that processes a context from WorkflowGen, we'll build a simple web service that receives and returns TEXT, NUMERIC, FILE, and DATETIME parameters using the JSON and XML ADO.NET DataSet context formats and their respective content types.

Reference

You must add a reference to WorkflowGen.My.dll in your web project, and then add a using statement (for the WorkflowGen.My.Data namespace of the WorkflowGen.My assembly. For example:

Specifying your class signature

If you want to receive a JSON formatted context, you should add the following signature, located in the App_Code\Service.cs file, to your web procedure's Service class (note that ScriptService signatures aren't required for other context formats). Your service class should look like this:

Specifying your web method signature

Only the methods that have the WebMethod attribute can be remotely executed. The default web method signature created with your web service should look like this:

Here, we'll modify the web method signature. If JSON is the chosen context format with application/json content type, or if the context format is XML ADO.NET DataSet with application/xml content type, the web method will not receive any parameter. Otherwise, if you exchange a JSON or ADO.NET DataSet context using the application/x-www-form-urlencoded content type, your method must receive a string parameter called WFGEN_CONTEXT.

JSON (application/json) and XML ADO.NET DataSet (application/xml) context formats

JSON and XML ADO.NET DataSet context formats using application/x-www-form-urlencoded content type

Loading the WorkflowGen context

The next step is to retrieve the WorkflowGen context. In the case of JSON or XML ADO.NET DataSet contexts (when using application/json or application/xml, respectively), the context is retrieved from the HttpContext request as shown in the following example:

Otherwise, if the web method has received the WFGEN_CONTEXT in parameters (this is the case for JSON and XML ADO.NET DataSet contexts when using the application/x-www-form-urlencoded content type), it is available to be used within the method.

Now, we're ready to create a ContextParameters instance that will be used to manipulate the WorkflowGen context:

Retrieving the parameters from the context

We'll now retrieve the NUMERIC_IN value into our numericIn double variable, and at the same time, we'll verify that the value is not null (if it is, we'll send an exception):

Modifying the parameters with new values

We'll now modify some parameters by giving them new values:

Sending the modified context back to WorkflowGen

Now that we've processed the context, we need to send the context back to WorkflowGen. Below is the necessary code, depending on the context format you chose when creating or editing your WorkflowGen application.

JSON context using application/json content type

JSON context using application/x-www-form-urlencoded content type

XML ADO.NET DataSet using application/xml content type

XML ADO.NET DataSet using application/x-www-form-urlencoded content type

Asynchronous web procedure development in .NET Framework

Overview

Asynchronous web procedures allow a WorkflowGen system action to be run asynchronously, meaning that the action is initiated at some point in time during the workflow and can be completed at a later instance by an external application.

This type of asynchronous processing can be used in cases where a system action (such a web service) can time out or cause the UI to hang when processing a large volume of information.

This section will explain how to develop an asynchronous web procedure application using WorkflowGen.My v4.0. The example will consist of two different parts: an ASP.NET XML web service that receives and processes the context, and cURL examples of HTTP POST requests (you can choose the appropriate technology to post these) needed to complete the action.

Creating the asynchronous web procedure

To create the ASP.NET XML web service, follow the steps in the previous section, :

1. Create the web procedure.

2. Create the application in IIS

3. Create a web procedure workflow application using an ASP.NET XML web service.

4. Configure the IIS rendering framework version in the web.config file.

Basic implementation

In order to demonstrate how to implement an asynchronous web procedure application, we have developed an ASP.NET XML web service that receives a context in JSON or XML ADO.NET DataSet formats, processes the context and updates it.

You must add a reference to WorkflowGen.My.dll in your web project, then add a using statement for the WorkflowGen.My.Data namespace of the WorkflowGen.My assembly:

Only methods that have the WebMethod attribute can be remotely executed. If the chosen context format is JSON with the application/json content type, or if the context format is XML ADO.NET DataSet with application/xml content type, the web method will not receive any parameters. Otherwise, if you exchange a JSON or ADO.NET DataSet using the application/x-www-form-urlencoded content type, your method must receive a string parameter called WFGEN_CONTEXT.

JSON (application/json) and XML ADO.NET DataSet (application/xml) context formats

JSON and XML ADO.NET DataSet context formats using application/x-www-form-urlencoded content type

Loading the WorkflowGen context

Be aware that WorkflowGen will send the context to your external application formatted based on your chosen context format and context type when creating or editing your application in WorkflowGen application form.

For example, if you choose JSON context with the application/json content type, your incoming payload will have the following structure:

For an example of an XML ADO.NET DataSet context, see in the section.

The next thing to do is receive the WorkflowGen context. In the case of the JSON or XML ADO.NET DataSet contexts, when using application/json and application/xml respectively, the context is retrieved from the HttpContext request:

Otherwise, if the web method has received the WFGEN_CONTEXT in parameters (this is the case with the JSON and XML ADO.NET DataSet contexts when using the application/x-www-form-urlencoded content type), it is available to be used within the method.

Now, we're ready to create a ContextParameters instance that will be used to manipulate the WorkflowGen context.

Retrieving the parameters from the context

We'll now receive the NUMERIC_IN value into our numericIn double variable, and at the same time, we'll verify that the value is not null; if it is, we'll send an exception:

Modifying the parameters with new values

Now, we'll modify some parameters by giving them new values:

Saving the context in a file

Since the asynchronous web procedure will complete the action afterwards, the context and the replyToUrl values should be stored. In this example, we'll use files for this purpose:

JSON context format

XML ADO.NET DataSet context format

After the ASP.NET XML web service used to launch the asynchronous web procedure has saved the context, we need to complete the action by sending it back to WorkflowGen. The following cURL examples provide all of the information required to post the context back to WorkflowGen using the information previously saved in the text files. There are many technologies and applications available to do this; for example, you can develop a .NET console application, or post your request using the Postman application. Be aware that the special character must be correctly escaped depending on your application of technology requirements.

JSON context using application/json content type

JSON context using application/x-www-form-urlencoded content type

XML ADO.NET DataSet context using application/x-www-form-urlencodedcontent type

XML ADO.NET DataSet context using application/xml; charset=UTF=8 content type

Sample SSO using a .NET custom HTTP module

The advantage of the custom HTTP module solution is that it secures all WorkflowGen HTTP requests, including web services. It also provides more customization possibilities than the form authentication-based solution.

This section focuses on the custom HTTP module authentication solution.

Time zone IDs and names

The following table lists the IDs and names of time zones.

Overview

Most runtime and design time workflow operations can be operated via the web services API, such as:

• Retrieving requests and action data and statuses

Overview

Integrations with external systems using WorkflowGen are possible through the use of WorkflowGen applications, RSS feeds, and the WorkflowGen Web Service API. As well, integrations with WorkflowGen can be performed through the use of URLs to perform the following types of functions:

• Launching requests and actions from any external site, with or without WorkflowGen frames and menus.

• Launching an action in a non-WorkflowGen window and redirecting to another (non-WorkflowGen) website.

• Viewing a follow-up form disconnected from the WorkflowGen User Portal.

• Viewing a graphical follow-up disconnected from the WorkflowGen User Portal.

Use cases could include permitting the seamless integration of WorkflowGen into an external portal, such as Microsoft SharePoint, SAP Portal, DotNetNuke, or other web-based portals. Filling out and submitting web forms as well as following up activities could then be performed without the use of the default WorkflowGen web portal if desired.

To enforce the appropriate security in WorkflowGen, these URL launches require users to authenticate themselves, and therefore work best with Integrated Authentication.

Launch a new request and start the first action

• This starts a new request and launches the first action.

• Participant security is enforced.

Parameters

The parameters the URL uses are as follows:

From within the WorkflowGen portal

• WorkflowGen menus and banners are visible.

To launch a process directly from a link or URL, use one of the examples below based on your version of WorkflowGen:

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

From within another website

• WorkflowGen menus and banners are hidden.

• A Back button (or a link in versions 9.1 and earlier) is displayed in the top left corner.

• Redirection will be performed upon form submit.

To launch a process directly from a link or URL and redirect back to a website other than WorkflowGen, use one of the examples below based on your version of WorkflowGen:

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

Launch a new request and start the first action without the WorkflowGen portal

Parameters

The parameters the URL uses are as follows:

To launch a process directly from a link or URL without the WorkflowGen portal, use one of the examples below based on your version of WorkflowGen:

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

Start an existing action

• This launches any workflow action that has been created. It can be the first, second, or later action of a workflow.

• Participant security is enforced.

Parameters

The parameters the URL uses are as follows:

Without the WorkflowGen portal

• WorkflowGen menus and banners are hidden.

To launch an action (second) directly from a link or URL, use one of the examples below based on your version of WorkflowGen:

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

Within the WorkflowGen portal

• WorkflowGen menus and banners are visible.

To launch an action (second) directly from a link or URL with visible menus, use one of the examples below based on your version of WorkflowGen:

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

Display a request follow-up form

• This displays the request follow-up form.

• Participant security is enforced.

Parameters

The parameters the URL uses are as follows:

Without the WorkflowGen portal

• WorkflowGen menus and banners are hidden.

To display a request follow-up form directly from a link or URL, use one of the examples below based on your version of WorkflowGen:

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

Within the WorkflowGen portal

• WorkflowGen menus and banners are visible.

To display a request follow-up form directly from a link or URL with visible menus, use one of the examples below based on your version of WorkflowGen:

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

Display a graphical follow-up form without the WorkflowGen portal

• This displays the graphical follow-up form disconnected from the WorkflowGen User Portal.

• Participant security is enforced.

• WorkflowGen menus and banner are hidden.

• Drill-down to activities is disabled.

Parameters

The parameters the URL uses are as follows:

To display the disconnected graphical follow-up form, use one of the examples below based on your version of WorkflowGen:

Version 9.2 and later:

Versions 9.1 and earlier (deprecated):

Download file data of a specific request or action using a WorkflowGen URL

The following examples show how to download file data from specific requests or actions using WorkflowGen URLs.

📌 Download the latest form archive of request #192

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

📌 Download the form archive of the first action of request #192

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

📌 Download the form archive of the second action of request #192

Versions 9.2 and later:

Versions 9.1 and earlier (deprecated):

Display the User Portal inside another website

By using an iFrame you can embed the WorkflowGen User Portal inside another website. In this case, you have to define the URL of the "host" application in the Configuration Panel.

Settings

Possible errors

Overview

WorkflowGen features the GraphQL API, which is a modern solution to create process-driven solutions such as mobile apps, web apps, and microservices that require a powerful workflow and BPM engine.

The WorkflowGen GraphQL API is a Node.js application that runs in IIS using iisnode. It enables a high level of customization such as extending the GraphQL schema with custom types, queries or operations, or implementing new authentication methods.

About GraphQL

From the website presentation:

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

GraphQL is a and an open source technology created by Facebook. In September 2016, GitHub its GraphQL API.

We’ve often heard that our REST API was an inspiration for other companies; countless tutorials refer to our endpoints. Today, we’re excited to announce our biggest change to the API since we snubbed XML in favor of JSON: we’re making the GitHub API available through GraphQL.

GraphQL is a modern API solution for React, React Native, Angular 2, and Vue based applications.

Many GraphQL tutorials are available, it's available in many languages, and it has a large .

Technical requirements

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

• ✏️ Note:

For information on the installation procedure, see the .

Endpoints

The following endpoints are available:

• GraphQL API: http://localhost/wfgen/graphql

• GraphiQL IDE: http://localhost/wfgen/graphql

• GraphQL Schema (definition language): http://localhost/wfgen/graphql/schema

The HTTP GET method is supported on queries only. The HTTP POST method is supported on queries and operations.

HTTP usage

is used to serve GraphQL HTTP queries:

GraphQL will first look for each parameter in the URL's query-string: /graphql?query=query+getUser($id:ID){user(id:$id){name}}&variables={"id":"4"} If not found in the query-string, it will look in the POST request body. If the POST body has not yet been parsed, express-graphql will interpret it depending on the provided Content-Type header:

• application/json: the POST body will be parsed as a JSON object of parameters.

• application/x-www-form-urlencoded: this POST body will be parsed as a url-encoded string of key-value pairs.

Using GraphiQL IDE in a web browser

You can use , a graphical interactive in-browser GraphQL IDE, to test queries and operations, and to browse the schema documentation.

Configuration

Maximum query content length

The maximum GraphQL query content length 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 30000000 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 GraphQL section on the Configuration Panel Integration tab. (Alternately, you can add the folder names separated by commas to the GraphqlInputFileAllowedFolders parameter in the WorkflowGen web.config file.)

To disallow input file allowed folders, leave this field empty. 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 GraphQL section on the Configuration 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:

Maximum input file size

In the GraphQL section on the Configuration Panel Integration tab, 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 GraphqlMaxInputFileSize 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 GraphQL 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 GraphqlMaxInputFileContentSize parameter in the WorkflowGen web.config file.

GraphQL API key

As of version 8.1.3, if your WorkflowGen and GraphQL API are secured using the WorkflowGen applicative or OpenID Connect authentications, you can alternatively access the GraphQL schema (i.e. /wfgen/graphql/schema) and the queries using a GraphQL API key header (x-wfgen-graphql-api-key) defined in the HTTP request, without an authentication header.

Add or define the following configuration parameters to the main \wfgen\web.config:

• <add key="GraphqlApiKeyEnabled" value="N" />: Set to Y in order to enable the GraphQL API key feature.

• <add key="GraphqlApiKey" value="[YOUR_API_KEY]" />: The value sent in the x-wfgen-graphql-api-key header must match this key. We recommend using a long and unique key string such as a GUID for example.

Performance tuning

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

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.

You can also optimize performance if needed by adjusting the maxConcurrentRequestsPerProcess value based on the number of potential concurrent users and requests.

For more information, see the Microsoft article.

Cross-origin resource sharing (CORS)

In order to allow a client application (such as front-end JavaScript code from an outside domain) to access and request data from the API, you must enable and configure the settings in the WorkflowGen GraphQL API module. To do this:

1. Install the on the WorkflowGen web server.

2. Add the cors node with the list of external domains and their methods and headers (where HTTP requests will be allowed) to the WorkflowGen web configuration settings (located in \wfgen\web.config). See some common examples below.

📌 Example 1: Allow all origins

📌 Example 2: Allow specific origins

For more information about the CORS configuration, see the .

Authentication

The following authentication methods are supported:

• IIS Basic

• WorkflowGen authentication

• Custom .NET authentication modules

• OpenID Connect

HTTPS is required to secure credentials.

For OpenID Connect providers, you need to pass the access token as a bearer token in the Authorization header; for example, Authorization: Bearer <ACCESS TOKEN>(replace<ACCESS TOKEN> with your access token).

The GraphQL Node.js app code inside the \wfgen\graphql folder can also be customized to accommodate many other authentication methods (such as OAuth2, JWT, etc.) thanks to node libraries such as .

System access users

Some operations (such as 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 Configuration panel Integration tab.

User impersonation

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

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

This request header can be renamed according to your naming convention. You can specify a new header name in the GraphqlImpersonateUserNameHttpHeader setting in the \wfgen\web.config file (e.g. <add key="GraphqlImpersonateUserNameHttpHeader" value="my-custom-impersonate-username" />).

To give or revoke system operations permissions to or from specific users, refer to the setting in the Security section on the Configuration panel Integration tab; alternately, you can edit the ProcessesRuntimeWebServiceAllowedUsers setting in the \wfgen\web.config file.

Delegation mode

Some GraphQL queries and operations can be executed on behalf of another user. This is possible when a user has created a delegation in WorkflowGen. The delegatee has to specify the user ID of his delegator in the onBehalfOf argument.

List of actions to do on by the delegatee on behalf of the delegator with the user ID VXNlcjoy:

When the onBehalfOf argument is set, it is propagated implicitly to the all the sub-queries and fields until a User type is used.

Global identifiers

Each GraphQL type has an id: ID! field. This ID is global and is unique for all WorkflowGen objects.

You can use the node(id:ID!) query to retrieve a WorkflowGen object by its ID.

GraphQL queries

You can copy/paste these queries directly in the GraphiQL IDE. See the section above for more information.

Using curl

And the result is:

Viewer basic info (the authenticated user)

My actions to do