Configuring an IIS SMTP gateway

1. Make sure the SMTP service is installed on the Windows server used as the SMTP gateway.

2. In IIS, edit the properties of the Default SMTP virtual server.

3. On the Access tab, click Relay.

4. Click the All except the list below radio button.

5. Click Apply and close this window. (For an increased security level, grant access only to the web server IP.)

6. On the Delivery tab, click the Advanced button.

7. In the Smart host field, enter your SMTP gateway address (IP or hostname).

8. Click Apply.

Using a pickup directory

Alternatively, WorkflowGen also supports pickup directories. Notifications are created in a pickup directory managed by the SMTP server. The path to the pickup directory is set in the SMTP server section on the General tab in the Administration Module Configuration Panel. (Alternately, you can set the path to the pickup directory as the value of the ApplicationSmtpPickupDirectory parameter in the WorkflowGen web.config file.) The default pickup directory path is C:\inetpub\mailroot\Pickup.

Once you've properly configured the pickup directory in WorkflowGen, you need to configure your external SMTP service (such as IIS SMTP Server or Exchange) to process the emails that are created by WorkflowGen in the pickup directory.

This integration is specific to AD FS 2016.

How to configure WorkflowGen authentication using AD FS

How to configure delegated authentication for the WorkflowGen Plus v2 mobile application using AD FS

How to authorize WorkflowGen access to server-side scripts using AD FS

How to authorize WorkflowGen access to single-page applications using AD FS

How to generate a universal link to simplify the WorkflowGen Plus mobile app user login

Additional information on SOAP services support and configurable options

• User Portal: http://[yoursite]/wfgen

• Administration Module: http://[yoursite]/wfgen/admin

If you're unable to log in, verify the web.config file in the root folder of the WorkflowGen application (usually DRIVE:\Inetpub\wwwroot\wfgen) and validate that the MainDbSource connection string contains the correct database connection information including server, database name, user, and password.

Test sample processes

You can create processes using the list of built-in process samples.

Additional configurations

You can change the security configuration (such as the authentication method) by following the instructions in the Security section.

• The DIR_V100 table gets data from the VIEW_PUB_DIR_V100 view

• The REQ_FILE_V100 table gets data from the VIEW_PUB_REQ_FILE_V100 view

Setup and configuration

To configure multiple instances of WorkflowGen on a single server, perform the steps outlined below. While more than two installations are possible, the following steps assume only two instances are installed.

Before modifying the service, it must be uninstalled using the winsvc-uninstall.cmd file found in the \bin folder of the application installation (for example, DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\winsvc-uninstall.cmd). Be sure to run it as the administrator of the server.

WorkflowGen directory synchronization service

For both instances of WorkflowGen, edit the parameter name in the WfgDirectoriesSyncService.exe.config WorkflowGen directory synchronization service configuration file as shown in the following examples.

Instance 1:

Edit the DRIVE:\Program Files\Advantys\WorkflowGen1\Services\bin\WfgDirectoriesSyncService.exe.config file as follows:

Instance 2:

Edit the DRIVE:\Program Files\Advantys\WorkflowGen2\Services\bin\WfgDirectoriesSyncService.exe.config file as follows:

WorkflowGen engine service

For both instances of WorkflowGen, edit the parameter name in the WfgWorkflowEngineService.exe.config WorkflowGen engine service configuration file.

Instance 1:

Edit the DRIVE:\Program Files\Advantys\WorkflowGen1\Services\bin\WfgWorkflowEngineService exe.config file as follows:

Instance 2:

Edit the DRIVE:\Program Files\Advantys\WorkflowGen2\Services\bin\WfgWorkflowEngineService exe.config file as follows:

Windows command scripts (install and uninstall of services)

For both instances of WorkflowGen you need to modify the Windows shell scripts that are used to install and uninstall the WfgDirectoriesSyncService and WfgWorkflowEngineService Windows services as described above.

Instance 1:

Install script: DRIVE:\Program Files\Advantys\WorkflowGen1\Services\bin\winsvc-install.cmd Based on the value given for the ServiceName parameter defined in the WorkflowGen directory synchronization service section above, your winsvc-install.cmd file should appear as follows:

Uninstall script: DRIVE:\Program Files\Advantys\WorkflowGen1\Services\bin\winsvc-uninstall.cmd Based on the value given for the ServiceName parameter defined in the WorkflowGen directory synchronization service section above, your winsvc-uninstall.cmd file should appear as follows:

Instance 2:

Install script: DRIVE:\Program Files\Advantys\WorkflowGen2\Services\bin\winsvc-install.cmd Based on the value given for the ServiceName parameter defined in the WorkflowGen directory synchronization service section above, your winsvc-install.cmd file should appear as follows:

Uninstall script: DRIVE:\Program Files\Advantys\WorkflowGen2\Services\bin\winsvc-uninstall.cmd Based on the value given for the ServiceName parameter defined in the WorkflowGen directory synchronization service section above, your winsvc-uninstall.cmd file should appear as follows:

Install the Windows Services

For both instances, you must run the install scripts that have been modified as described above using administrator permissions.

Instance 1:

DRIVE:\Program Files\Advantys\WorkflowGen1\Services\bin\winsvc-install.cmd

Instance 2:

DRIVE:\Program Files\Advantys\WorkflowGen2\Services\bin\winsvc-install.cmd

• Make sure to have a licensed copy of WorkflowGen installed and running on a server.

• Make sure to have administrative access to WorkflowGen.

• Make sure to have administrative access to AD FS to be able to configure it properly.

• Make sure to have successfully configured delegated authentication to AD FS on your WorkflowGen instance following the instructions in the section.

AD FS configuration

Step 1: Register a new server application

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. In the WorkflowGen Properties window, click Add application.

3. Select the Server application type, then click Next.

4. Configure the server application:

   1. Name: My Server Application

   2. Copy the client identifier, which you'll need for the client credentials grant flow. You won't be able to retrieve it afterwards.

   3. Add a redirect URI. Here, it doesn't matter what you enter because the client credentials grant doesn't use this value.
5. In the Configure Application Credentials window, generate a client secret for the server application:

   1. Check the Generate a shared secret checkbox.

   2. Copy the value; you'll need it for the client credentials grant flow.

6. Review the configuration; once you've finished, click Next.

7. Click Close.

You should now see your new server application listed in the WorkflowGen application group.

Step 2: Grant access to the GraphQL API

Now that you've created your server application, you need to grant it access to the GraphQL API. To do this:

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. In the WorkflowGen Properties window, double-click WorkflowGen GraphQL API.

3. On the Client Permissions tab in the WorkflowGen GraphQL API Properties window, click Add.

4. Click the server application that you created in the previous section, then click Add.

5. You should now see your server application in the list of client applications; make sure it's selected.

6. Make sure that the openid, profile, and email scopes are checked.

7. Click OK.

You've now registered your server application in AD FS and granted it access to the WorkflowGen GraphQL API.

WorkflowGen configuration

As with user provisioning, WorkflowGen needs to know which application is accessing the GraphQL API. Therefore, you have to register the application, which consists of your script.

Register a new application

1. On the Applications page in the WorkflowGen Administration Module, click New application.

2. Fill in the form:

   • Name: My Server Application

   • Description: A description that clearly identifies the script.

   • Type: Non Interactive Client

   • Impersonate username: Any username that has the required access to the GraphQL API.

   • Client ID: The client ID you copied earlier.

   • Active: Check this checkbox.

3. Click Save.

Your application should now appear in the list of applications.

• Make sure to have a licensed copy of WorkflowGen installed and running on a server.

• Make sure to have administrative access to AD FS to be able to configure it properly.

• Make sure to have provisioned an existing Active Directory user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

• Make sure to have successfully configured delegated authentication to AD FS on your WorkflowGen instance following the instructions in the section.

AD FS configuration

Currently, AD FS only supports three types of applications: Native, Server, and Web API. As you can see, there's nothing for single-page applications in browsers or even regular web applications that renders pages on the server. However, you can use the supported types to get what you need. The Native application type enables you to retrieve a client ID and to specify a callback URI that can be used to perform an implicit grant flow with a single-page application; AD FS will answer as expected since it supports the OpenID Connect protocol.

This configuration is done in several steps. First, you have to register a new native application in AD FS. Then, you have to give the application the necessary permissions to access the WorkflowGen GraphQL API.

Step 1: Register a new native application

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. Click Add application.

3. Configure the application:

   1. Name: My Single-Page App

   2. Copy the client identifier, which you'll need in the application.

   3. Redirect URI: https://mysinglepageapp.com/callback

4. Click Add, then click Next.

5. Review the configuration; once you've finished, click Next and then Close.

Step 2: Grant access to the WorkflowGen GraphQL API

1. In the AD FS Management window, navigate to the Application Groups folder, and double-click on the WorkflowGen group.

2. Double-click on the WorkflowGen GraphQL API application.

3. On the Client Permissions tab, click the WorkflowGen Plus application, then click Add.

4. Select My Single-Page App in the application permissions list.

5. Make sure that the openid, profile, and email scopes are checked.

6. Click OK, then click OK in the WorkflowGen application group menu.

WorkflowGen directory synchronization service

The automatic user and group synchronization is provided by this Windows Service, which is installed by the setup and started automatically after installation. (Refer to WorkflowGen Windows Services installation if the manual installation procedure was used.)

If errors occurred while the service is running, those errors will appear in the Event Viewer (source: WorkflowGenDirSyncService) accessible in Windows Administrative Tools. All messages related to this service will be displayed in the Windows Logs / Application section.

To manage this Windows service execution, open Administrative Tools / Services, then select and open WorkflowGen Directory Sync (WorkflowGenDirSyncService).

Troubleshooting

After a WorkflowGen version upgrade or system change (such as a server update or configuration change), the automatic directory synchronization can fail with the error message The license file is missing, invalid or your trial period has expired.

To resolve this issue, perform the following checks on your WorkflowGen system:

• Verify that there is only one license file (.lic) in the wfgen\bin folder.

• Verify that the license file (.lic) is not locked; if so, unlock it.

• Verify that the two WorkflowGen service execution files (WfgDirectoriesSyncService.exe and WfgWorkflowEngineService.exe) are not locked; if so, unlock them.

• Verify that the account that executes the WorkflowGen services has read/write access to the \wfgen folder.

• Verify that the account that executes the WorkflowGen services is a local administrator.

• In the WfgDirectoriesSyncService.exe.config file, replace <add key="WebConfigPath" value="..." /> with <add key="webConfigPath" value="..." />.

License activation

Overview

You must have a trial, Developer, or Enterprise license to activate WorkflowGen.

You must have a serial number to activate the Developer and Enterprise versions of WorkflowGen. If you don't have one, contact your vendor.

How to activate WorkflowGen

Install the license file

1. Remove all current .lic files from the DRIVE:\Inetpub\wwwroot\wfgen\bin folder.

2. Copy your .lic file to the DRIVE:\Inetpub\wwwroot\wfgen\bin folder.

3. Make sure the license file inherits the security settings.

Add the serial number to the web.config file

For the Developer and Enterprise editions of WorkflowGen, you must edit the web.config file located in the DRIVE:\Inetpub\wwwroot\wfgen folder.

1. Edit the \Inetpub\wwwroot\wfgen\web.config file.

2. Set your serial number as the value of the ApplicationSerialNumber parameter.

License per user

If you have a license per user, you cannot exceed the maximum number of users supported by your license, otherwise you will receive an error message when you try to launch a new request. However, user management will still be accessible.

If you want to import several users from your enterprise directory (Active Directory, LDAP, etc.), and since only active users are considered, you can choose between the following cases:

• If your enterprise directory has fewer users than the maximum number of users supported by your WorkflowGen license, then you can import all of your users with the option New user default status set to Active.

• If your enterprise directory has more users than the maximum number of users supported by your WorkflowGen license, then you should import all your users with New user default status set to Inactive and set the Self activation option as follows:

  • If you want to manually activate users authorized to use WorkflowGen, uncheck the Self activation option. A user will be able to access WorkflowGen once you activate their account from the Administration Module.

  • If you don’t want to worry about account activation, keep the Self activation option checked. New users connecting for the first time will be activated until the maximum number of users supported by your WorkflowGen license is reached.

How to configure WorkflowGen authentication using Auth0

How to create a directory with the self-provisioning connector

How to configure delegated authentication for the WorkflowGen Plus v2 mobile application using Auth0

How to authorize WorkflowGen access to server-side scripts using Auth0

How to authorize WorkflowGen access to single-page applications using Auth0

How to authorize Auth0 access to the WorkflowGen command line interface

How to generate a universal link to simplify the WorkflowGen Plus mobile app user login

Additional information on SOAP services support and provisioning users and groups

Now, you need need to configure WorkflowGen to delegate its authentication to Gardian.

Add Gardian values to the WorkflowGen web.config

Open the WorkflowGen web.config file and add the following properties:

• Replace <ACR VALUES> with ACR values as specified by your Gardian service provider.

Parameters

You'll need to specify the following parameters:

• provider: adfs

• server_address: Your WorkflowGen application URL, whose value must be URL encoded (e.g. https://mycompany.com/wfgen)

• client_id: Use the client ID you created earlier in the configuration (e.g. 6g909d00-8580-49a4-9003-a30f6b87ae86)

• domain: The AD FS domain name without URL protocol (e.g. mycompany.com)

• audience: Your WorkflowGen GraphQL API URL, whose value must be URL encoded (e.g. https://mycompany.com/wfgen/graphql)

The universal link should follow this format:

The WorkflowGen application is hosted on a new or existing IIS website and is separated into two distinct modules:

• The User Portal for end-users

• The Administration Module for process designers, administrators, and process managers

Process actions can be handled by WorkflowGen applications such as EFORMASPX, which displays .NET web forms and stores the filled-out data once the forms are submitted. These applications are built-in, but you can develop custom applications using the SDK requirements and specifications.

Web applications

WorkflowGen main ASP.NET 4 application

This application contains the core application. The User Portal and Administration Module are both in that main application.

• \wfgen: User Portal

• \wfgen\admin: Administration Module

• \wfgen\bin: Contains all the core assembly files that are needed to run WorkflowGen.

• \wfgen\App_Data: Contains design, runtime, log, and temporary files, and template files for processes, notifications, and forms.

• \wfgen\App_GlobalResources: Contains the .resx files that are needed for globalization. If you want to add a new language support to WorkflowGen, you'll have to create the new .resx files in this folder.

• \wfgen\js: Used to store the different JavaScript files that are needed to run WorkflowGen.

• \wfgen\wfapps: Contains all the SDKs, web forms, and web services used by your WorkflowGen processes.

• \wfgen\ws: Contains the WorkflowGen web service API.

• \wfgen\App_Themes: Contains the styles of the User Portal and the Administration Module. The styles are completely customizable for both modules, since each module has its own corresponding CSS file. To create your own skins, see the section in the . You can change the currently selected skin on the tab in the Administration Module Configuration Panel.

ASP.NET workflow applications (\wfgen\wfapps)

Use the \wfgen\wfapps\webservices folder to store your own SDK web applications. See the WorkflowGen Integration Guide for more information.

Workflow web forms

The \wfgen\wfapps\webforms folder is used to store the web forms used in the process workflows.

WorkflowGen Windows services

WorkflowGen engine service

The following automatic task executions are provided by this Windows service:

• Action overdue exceptions

• Notification management

• Deletion of inactive delegations

• Deletion of ghost activities (a list of activities initialized but never started)

This service is installed by the setup pack and is started automatically after installation. The default suggested installation path is DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\WfgWorkflowEngineService.exe.

WorkflowGen directory synchronization service

Automatic user and group synchronization is provided by this Windows service. This service is installed by the setup pack and started automatically after installation.

The default suggested installation path is DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\WfgDirectoriesSyncService.exe.

The synchronization service can also be executed from a command line (see Synchronizing a directory in command line for more information).

WorkflowGen data

File data

• \wfgen\App_Data\files\runtime: This folder contains the data that are related to each process instance. Data generated by the workflows are stored in this folder. If the Process data storage option is selected to store file content in the database, then FILE type data are stored directly in the database and not in the directory structure.

• \wfgen\App_Data\files\design : This folder contains the data that are uploaded directly in the process definition, and when the process is instantiated, those data are copied to the runtime folder. If the Process data storage option is selected to store file content in the database, then FILE type data will be stored directly in the database and not in the directory structure.

• \wfgen\App_Data\files\charts\images: This folder contains the temporary files of the graphical charts.

Log files

• \wfgen\App_Data\LogFiles : This folder contains the logs created by WorkflowGen (directory synchronization, WorkflowGen authentication module).

Templates

• \wfgen\App_Data\Templates : This folder contains the templates used by WorkflowGen (notifications, charts, portlet, form designer styles and tools, processes).

Database

The WorkflowGen database contains:

• Users and groups that can be synchronized with an existing directory

• Process definitions and runtime data

• Information on the follow-up of ongoing and completed requests, as well as associated data (approvals, amounts, documents, etc.)

• Statistics on ongoing and completed requests

Processes can be imported from or exported to an XML file that contains the process definition based upon the XPDL 1.0 standard format of the WfMC (Workflow Management Coalition).

All data files, including the web form projects with their XML data and other attachments, are stored on the server disk and auto-archived chronologically.

Third-party software and licenses

The following software is distributed with WorkflowGen (Apache 2.0, BSD, MIT, and other compatible licenses):

• bluebird (see https://github.com/petkaantonov/bluebird/blob/master/LICENSE)

• busboy (see https://github.com/mscdex/busboy/blob/master/LICENSE)

• body-parser (see https://github.com/expressjs/body-parser/blob/master/LICENSE)

• change-case (see https://github.com/blakeembrey/change-case/blob/master/LICENSE)

• chart.js ()

• cookie-parser (see )

• cors (see )

• dataloader (see )

• edge-js (see )

• eml-format (see )

• express (see )

• express-graphql (see )

• file-uri-to-path (see )

• file-url (see )

• format (see )

• fs (see )

• got (see )

• graphiql (see )

• graphql-js (see )

• graphql-relay-js (see )

• graphql-tools (see )

• graphql-upload (see )

• htmx.org (see )

• iisnode (see )

• jquery (see )

• jquery-colorbox (see )

• jquery-ui (see )

• jquery-validation (see )

• jsonwebtoken (see )

• jszip (see )

• jwks-rsa (see )

• lodash (see )

• lucide (see )

• mem (see )

• mocha (see )

• mockery (see )

• Node.js (see )

• nyc (see )

• parse5 (see )

• proper-lockfile (see )

• pug ()

• request-promise-native (see )

• rimraf (see )

• samlify (see )

• seriate (see )

• sinon (see )

• supertest (see )

• uuid (see )

• valid-url (see )

• xml2js (see )

• xml-js (see )

• yargs (see )

Full (applications and data)

Application and data files

Back up the DRIVE:\Inetpub\wwwroot\wfgen folder.

If you've applied file storage, back up the folder as indicated in the ApplicationDataPath parameter in the web.config file.

Database

Perform a standard SQL database backup using your DBMS tools.

Data only

Database

Perform a standard SQL database backup using your DBMS tools.

Data files

Back up the DRIVE:\Inetpub\wwwroot\wfgen\App_Data folder.

Moving the WorkflowGen database

SQL Server database

To move the WorkflowGen SQL Server database from one server to another:

1. Stop IIS services on the production server.

2. Detach the WorkflowGen database.

3. Copy the .mdf and .ldf files to the new location.

4. Attach the file to the new database server.

5. Update the connection string in the Administration Module Configuration Panel.

6. Restart your IIS services.

Moving the WorkflowGen application

To move the WorkflowGen installation from one server to another:

1. Stop IIS services on the production server.

2. Set up the same version of WorkflowGen on the new server.

3. Copy the DRIVE:\Inetpub\wwwroot\wfgen\App_Data folder from the old server to the new one if you haven’t applied file storage externalization.

4. If you've created your own web forms, SDK applications, or web services:

   1. Copy their folders in the corresponding tree structure of the new server. For example, if you have created a web service named MyWebService located in DRIVE:\wfgen\wfapps\WebServices\MyWebServices then you need to copy the entire folder to the same place on the new server.

   2. Create the IIS application with the same directory security options on the new server for the applications you have copied.

   3. For web services or SDK Applications, make sure to update the application URL in the Administration Module.
5. Update the application URL from the Administration Module Configuration Panel.

Monitoring

Storage space

File data

The only folder that you need to monitor for storage space is DRIVE:\Inetpub\wwwroot\wfgen\App_Data. The other folders should always keep the same size because everything that is generated over the time is placed in this directory.

Database

The database size can be determined by checking the .mdf and .ldf files if you're using SQL Server, or using your DBMS tools.

Storage space needs may vary depending on whether or not the Store file content in database process data storage option is selected during the process definition.

Directory synchronization

The directory synchronization log files can be found in the \wfgen\App_Data\LogFiles\Dir\Synchro directory. Alternately, you can consult and manage the logs history directly in the WorkflowGen Administration Module.

Windows Services

Windows Services should be set to run automatically when the server starts. Periodically, Windows Services will perform the following necessary tasks:

• Raise overdue exceptions

• Send overdue notifications

• Delete inactive delegations

• Delete ghost activities (activities initialized but never started)

Usage

Requests/actions by day

A statistics module and charting functions are provided in the User Portal to generate detailed reports on the requests and actions. You can customize reports using filters.

Attachment file size

Attachments to requests submitted using web forms are saved in the DRIVE:\Inetpub\wwwroot\wfgen\App_Data\Files\EFormASPX temporary folder and are automatically deleted 24 hours after their creation.

WorkflowGen will copy those runtime files to a permanent location. If the Store file content in database process data storage option is enabled, then they are stored directly in the database. Otherwise, they're stored in the file system as determined by the ApplicationDataPath configuration parameter (e.g. \App_Data\Files\DataSet\runtime).

If you know that a process takes too much space on the disk because of the process data, or too much space in the database because of file attachments, you can turn off the Archive action associated data option in the process definition. This will prevent the attached file from being stored for each action of every request. Only the data after the last action will be kept on the disk or in the database.

Parameters

You'll need to specify the following parameters:

• provider: okta

• server_address: Your WorkflowGen application URL, whose value must be URL encoded (e.g. https://mycompany.com/wfgen)

• client_id: Use the client ID you created earlier in the configuration (e.g. 0o7gdj4hs92yh7) from the step .

• metadata_url: The metadata URL, which consists of the value of Metadata URI property from the Settings tab of your WorkflowGen GraphQL API authorization server with /.well-known/oauth-authorization-server replaced by /.well-known/openid-configuration (e.g. https://{YOUR_OKTA_DOMAIN}/oauth2/{AUTH_SERVER_ID}/.well-known/openid-configuration). The value must be URL encoded.

• audience: Your WorkflowGen GraphQL API URL, whose value must be URL encoded (e.g. https://mycompany.com/wfgen/graphql)

The universal link should follow this format:

Web service type application support

Web service type applications only support requests using classic authentication methods. If you still need to use these APIs, you have to perform some additional steps to configure it properly.

1. Make sure you have a local or domain account provisioned on your WorkflowGen server. (This can be the account you used prior to changing your authentication method to Okta.)

2. In the IIS Manager, enable either the Basic or Windows authentication method for your application (e.g. wfapps/webservices/myWebService).

3. In the web.config file (located in \Inetpub\wwwroot\wfgen), add the following new location under the last location: <location path="wfapps/webservices/myWebService" inheritInChildApplications="false"> The structure should be as follows:

Configurable options

This table lists all configurable options in WorkflowGen that you can use to customize your authentication experience; these are located in the WorkflowGen web.config file.

To configure Windows Authentication, use one of the following connection strings in the WorkflowGen web.config file, located in the DRIVE:\Inetpub\wwwroot\wfgen folder:

OR

You'll also need to modify the WorkflowGen application pool identity for a service account. To do this:

1. In IIS Manager, right-click on the WorkflowGen application pool, then select Advanced Settings.

2. In the Process Model section, select Identity, then click the ... button.

3. Select Custom Account, then click Set...

4. Enter your credentials, then click OK.

5. Make sure the application pools for the other WorkflowGen web applications (auth, graphql, hooks, scim,ws, and webforms) match the wfgen application pool.

6. Make sure the custom account has read/write and modify permissions for the WorkflowGen SQL database and the WorkflowGen files and folders.

7. Use the same account as the application identity to run the WorkflowGen engine and directory synchronization services.

For more information on SQL Server connection strings, see https://www.connectionstrings.com/sql-server/.

Database scaling

Overview

The database scaling feature allows for the addition of database servers in order to dramatically improve server performance and response times. The additional read-only replica database servers will be used as dedicated read-only servers (SELECT SQL queries). The read-only database servers are replicated from the existing primary database using the SQL Server Replication service.

Requirements

Overview

• SQL Server 2014 or later for all database servers

• SQL Server Replication feature must be installed on all SQL Server instances

• SQL Server Agent must be installed and configured on all SQL Server instances

Setup and configuration

Overview

This section provides a general procedure for configuring the SQL Server Replication service on all the SQL Server instances and enabling the WorkflowGen web server in database scaling mode. This procedure is an example based on one WorkflowGen instance and two database server instances architecture.

If your current architecture differs from this example, you can adapt the procedure and some specific configuration options according to your needs.

Your current WorkflowGen environment must meet the following prerequisites:

• The initial WorkflowGen database is already installed on the primary database instance.

• The read-only database instance does not contain an existing WorkflowGen database.

• The WorkflowGen web server is fully configured and allows access to the Administration Module with a WorkflowGen administrator account.

SQL Server configuration options

It is mandatory to update the SQL Server's max text repl size configuration option with a higher value in order for the database replication to function properly. We recommend setting this to the maximum value of 2147483647 instead of the default value of 65536.

Run the following SQL statements in the source (primary) and destination (read-only) SQL Server database instances (this example uses SQL Server 2008):

For more information, see http://msdn.microsoft.com/en-us/library/ms186225.aspx and select your version of SQL Server from the drop-down menu.

SQL Server replication services

To set up a publication on the primary database:

1. Open SQL Server Management Studio.

2. Connect to the primary database instance.

3. Open the Replication node.

4. Right-click on Local Publications and choose New Publication. The New Publication Wizard will open. Click Next.

5. Select WFGEN in the Publication Database list. Click Next.

6. Select Transactional publication in the Publication type list. Click Next.

7. Check all Tables and Views (optional if the WorkflowGen Reporting Module is installed in the current database instance) in the Articles list. Click Next.

8. The Article Issues dialog box will open if you selected Views in the previous step. Click Next.

9. The Filter Table Rows dialog box will open. There is no need to filter the data in the publication. Click Next.

10. The Snapshot Agent dialog box will open. Check Create a snapshot immediately and keep the snapshot available to initialize subscriptions. Click Next.

11. In Snapshot Agent Security, provide valid service or administrator credentials for the Windows account. Click Next.

12. Check Create the publication. Click Next.

13. Enter the Publication name WFGEN_PUB.

14. Click Finish. If all is successful, close the New Publication Wizard.

To set up a subscription on the read-only database:

1. Open SQL Server Management Studio.

2. Connect to the read-only database instance.

3. Open the Replication node.

4. Right-click on Local Subscriptions and choose New Subscription. The New Subscription Wizard will open. Click Next.

5. Select <Find SQL Server Publisher...>.

6. Connect to the primary database instance.

7. Select WFGEN_PUB in the Databases and publications list. Click Next.

8. Select Run each agent at its Subscriber (pull subscriptions). Click Next.

9. In the Subscription Database column, select <New database...>.

10. Enter the WFGEN as the Database name and click OK. Click Next.

11. In Distribution Agent Security, provide valid service or administrator credentials for the Windows account. Click Next.

12. In Synchronization Schedule, select Run continuously. Click Next.

13. In Initialize Subscriptions, select Immediately. Click Next.

14. Select Create the subscription(s). Click Next.

15. Click Finish. If all is successful, close the New Subscription Wizard.

16. Create and add the SQL user WFGEN_USER to the WFGEN read-only database security with db_datareader and db_datawriter permissions.

Database scaling in WorkflowGen

Enable the multi-database mode in WorkflowGen:

1. In the WorkflowGen Administration Module, open the Configuration Panel and select the General tab.

2. In the Read-only database connection string field, enter the WorkflowGen connection string of the read-only database instance.

3. Check Enable on Multi-database to turn on the database scaling feature.

4. Check each of the specific Portal pages and Modules:

   • If unchecked, it will use the primary database.

   • If checked, it will use the read-only replica database.

5. Save and close.

References

• For more information on SQL Server replication, see http://msdn.microsoft.com/en-us/library/ms151198.aspx and select your version of SQL Server from the drop-down menu.

• For more information on the SQL Server max text repl size option, see http://msdn.microsoft.com/en-us/library/ms186225.aspx and select your version of SQL Server from the drop-down menu.

• Make sure to have a working WorkflowGen instance.

• Make sure to know the instance's IP address or its fully qualified name.

• Make sure to know the address of the instance.

• Make sure to have configured Auth0 or one of the other OIDC-compliant authentication methods (Microsoft Entra ID, formerly Azure Active Directory; ; ; or ).

WorkflowGen configuration

This section will guide you through the WorkflowGen configurations necessary to set up the self-provisioning feature with a directory.

Step 1: Create a self-provisioning directory

This directory will contain all of the users that are not provisioned elsewhere. To create a self-provisioning directory, do the following:

1. On the Directories page in the WorkflowGen Administration Module, click New directory.

2. Fill in the form:

   • Name: SELF_PROVISIONING(or something else)

   • Description: A good description of the directory

   • Directory connector: Self-provisioning

3. Click Save.

Step 2: Configure the user fields-to-claims mapping

Now that you've created a new directory with the self-provisioning connector, you need to define which claims are mapped to which WorkflowGen user field. To do this:

1. On the new directory's page, click Edit mapping.

2. To the right of the name of a WorkflowGen user's field, enter the name of the claim in the session token that you want to map.

   Here's an example of a session token generated by the auth node application from the Auth0 ID token connected with Google Apps:

   These claims could be mapped in WorkflowGen like this:

   ✏️ Note: The Username and Name fields are required.

3. Click Save.

It's therefore important that you make all of the necessary checks to verify the validity of your requests and the responses.

This section provides instructions on how to configure Auth0 with a single-page application (SPA) so that users can authenticate through it and make requests to the WorkflowGen GraphQL API. This configuration is done in three steps: registering your SPA, granting access to the API, and setting some redirect URLs.

Prerequisites

• Make sure to have a licensed copy of WorkflowGen installed and running on a server.

• Make sure to have administrative access to Auth0 to be able to configure it properly.

• Make sure to have provisioned an existing Auth0 user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

• Make sure to have successfully configured delegated authentication to Auth0 on your WorkflowGen instance following the instructions in the section.

Auth0 configuration

Step 1: Register a new web application

1. In the Auth0 portal, click Create Application in the Applications section.

2. Fill in the form:

   • Name: Your SPA name

   • Type: Single Page Web Applications

3. Click Create at the bottom of the page.

You should now be on the registered application page.

Step 2: Add redirect URLs

1. On the Settings tab, scroll down to the Allowed Callback URLs section and add your application's login callback URL (for example, https://localhost/login/callback).

2. If you support logout from Auth0, scroll down to the Allowed Logout URLs section and add your post logout redirect URL (for example, https://localhost/logout/return).

Review the registration

• You need a client ID, which can be found on the application page's Settings tab.

• You need your Auth0 domain name, which can be found next to your Auth0 profile picture in the top right corner of the portal.

It's therefore important that you make all of the necessary checks to verify the validity of your requests and the responses.

This section provides instructions on how to configure Okta with a single-page application (SPA) so that users can authenticate through it and make requests to the WorkflowGen GraphQL API. This configuration is done in two steps: registering your SPA, then setting some redirect URLs.

Prerequisites

• Make sure to have a licensed copy of WorkflowGen installed and running on a server.

• Make sure to have administrative access to Okta to be able to configure it properly.

• Make sure to have provisioned an existing Okta user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

• Make sure to have successfully configured delegated authentication to Okta on your WorkflowGen instance following the instructions in the section.

Okta configuration

Create a new single-page application

1. In your Okta developer portal, go to the Applications item under the Applications menu, then click the Create App Integration button.

2. Select the OIDC - OpenID Connect sign-in method, select Single-Page Application as the application type, then click Next.

3. Enter the following information:

   • App integration name: My SPA, or the name of your single-page application

   • Grant type: Check Authorization Code

   • Sign-in redirect URIs: The login redirect URI for your single-page application

   • Sign-out redirect URIs: The logout redirect URI for your single-page application

   • Base URIs: The base URI of your single-page application

   • Controlled access: Check Allow everyone in your organization to access

4. Click Save.

Review the registration

• You need a client ID, which can be found on the General tab on your single-page application page.

✏️ Note: The Username and Name fields are required.

• Make sure to have a licensed copy of WorkflowGen installed and running on a server.

• Make sure to have administrative access to WorkflowGen.

• Make sure to have administrative access to Auth0 to be able to configure it properly.

• Make sure to have successfully configured delegated authentication to Auth0 on your WorkflowGen instance following the instructions in the section.

Auth0 configuration

Step 1: Register a new machine-to-machine application

1. In the Auth0 portal Applications section, click Create Applications.

2. Fill in the form:

   • Name: Your script name

   • Application Type: machine-to-machine

3. Click Create.

You've now successfully registered your script in Auth0.

Step 2: Grant access to the GraphQL API

1. In the Auth0 portal APIs section, click WorkflowGen GraphQL API.

2. On the Machine-to-Machine tab, authorize the application that you just created.

You've now successfully granted the GraphQL API access to your script.

Review the registration

Here's a review of the information you need:

• A client ID, which can be found on the registered application's General tab.

• A client secret, which can be found on the registered application's General tab.

• The WorkflowGen GraphQL API identifier, which can be found on its settings page.

You're now ready to register your script in WorkflowGen.

WorkflowGen configuration

As with user provisioning, WorkflowGen needs to know which application is accessing the GraphQL API. Therefore, you have to register the application, which consists of your script.

Register a new application

1. On the Applications page in the WorkflowGen Administration Module, click New application.

2. Fill in the form:

   • Name: My Server Application

   • Description: A description that clearly identifies the script

   • Type: Non-interactive Client

   • Impersonate username: Any username that has the required access to the GraphQL API

   • Client ID: The client ID you retrieved earlier

   • Active: Check this checkbox

3. Click Save.

Your application should now appear in the list of applications.

• Make sure to have a licensed copy of WorkflowGen installed and running on a server.

• Make sure to have administrative access to Okta to be able to configure it properly.

• Make sure to have provisioned an existing Okta user with which you can authenticate to WorkflowGen so that you can use the application afterwards.

• Make sure to have the WorkflowGen Plus mobile application installed on a device that you have access to.

• Make sure to have the latest WorkflowGen Plus version installed on your device and that your device is supported.

• Make sure to have successfully configured delegated authentication to Okta on your WorkflowGen instance following the instructions in the section.

Okta configuration

Step 1: Create the WorkflowGen Plus native application

1. In your Okta developer portal, go to the Applications item under the Applications menu, then click the Create App Integration button.

2. Select the following options under Create a new app integration, then click Next:

   • Sign-in method: OIDC - OpenID Connect

   • Application type: Native Application

3. Enter the following information:

   • App integration name: WorkflowGen Plus

   • Grant type: Check Authorization Code and Refresh Token
4. Click the Save button.

Step 2: Add an Initiate login URI

1. On your Okta WorkflowGen Plus native application page, go to the General Settings section on the General tab, then click the Edit button.

2. Enter the following information:

   • Initiate login URI: workflowgenplus://oidc

3. Click Save.

Review the registration

If you've set up delegated authentication to Okta on your WorkflowGen server, you should have an access policy on your Okta WorkflowGen GraphQL API authorization server that will let any configured client access it. Therefore, there's nothing left to do on the Okta side. Here's a review of the information you need:

• A client ID, which can be found on the Okta WorkflowGen Plus native application page's Settings tab.

• Your Okta domain name, which can be found directly to the left of your profile picture on the top right corner of the page.

• Make sure to have a licensed copy of WorkflowGen installed and running on a server.

• Make sure to have administrative access to WorkflowGen.

• Make sure to have administrative access to Okta to be able to configure it properly.

• Make sure to have successfully configured delegated authentication to Okta on your WorkflowGen instance following the instructions in the section.

Okta configuration

Create a new API services application

1. In the Applications item under the Applications menu in your Okta developer portal, click the Create App Integration button.

2. Select the API Services sign-in method, then click Next.

3. Enter the name of your application, then click Save.

Review the registration

Here's a review of the information you need:

• A client ID and a client secret, which can be found on the newly registered service application's general tab.

• The WorkflowGen GraphQL API identifier, which can be found on its settings page.

WorkflowGen configuration

As with user provisioning, WorkflowGen needs to know which application is accessing the GraphQL API. Therefore, you have to register the application, which consists of your script.

Register a new application

1. On the Applications page in the WorkflowGen Administration Module, click New application.

2. Fill in the form:

   • Name: My API Services App

   • Description: A description that clearly identifies the script

   • Type: Non-interactive Client

   • Impersonate username: Any username that has the required access to the GraphQL API

   • Client ID: The client ID you retrieved earlier from your registered service app (e.g. My API Services App)

   • Active: Check this checkbox

3. Click Save.

Your application should now appear in the list of applications.

✏️ Note: If the PowerShell Extensions aren't available for your SQL Server version or the installation script still doesn't detect the SQL Server PowerShell module, then try installing the PowerShell Extensions from the SQL Server 2016 Feature Pack, or try installing SQL Server 2016 Management Studio.