WorkflowGen 9.2.1 Upgrade

Overview

The following procedures apply to the WorkflowGen 9.2.1 (9.2 Beta 2) upgrade pack, available at https://github.com/advantys/workflowgen-releases/releases.

Package contents

The upgrade pack is distributed as a compressed file containing the following folders:

• Inetpub: WorkflowGen web application files

• Program Files: WorkflowGen Windows Services files

• Databases: WorkflowGen database update and creation files

IIS server

Stop the IIS server (or at least your WorkflowGen web applications) if other websites are using the same IIS server.

WorkflowGen Windows Services

Stop the WorkflowGen Directory Sync and Engine services in the Windows Services Management Console.

Backup

Application and data files

Back up the following folders:

• DRIVE:\Inetpub\wwwroot\wfgen

• DRIVE:\Program Files\Advantys\WorkflowGen

If the file storage path isn't the standard DRIVE:\Inetpub\wwwroot\wfgen\App_Data path, then you have to back up the corresponding folder.

Database

Perform a standard database backup using your DBMS tools.

Update WorkflowGen web application files

Delete deprecated Node.js application files and folders

Verify if the following deprecated files and folders used by Node.js-based applications still exist in your \wfgen folder, and delete them if they do.

1. Delete the following files and folders from the \wfgen\graphql folder:

   • \controllers

   • \models

   • \node_modules

   • \services

   • \utils

   • config.js

   • config.production.js

   • server.js

2. Delete the following files and folders from the \wfgen\hooks folder:

   • \controllers

   • \models

   • \node_modules

   • \services

   • \test

   • \utils

   • config.js

   • config.production.js

   • server.js

   • upload.js

3. Delete the following files and folders from the \wfgen\auth folder:

   • \controllers

   • \models

   • \node_modules

   • \static

   • \utils

   • config.js

   • config.production.js

   • server.js

4. Delete the following files and folders from the \wfgen\scim folder:

   • \controllers

   • \models

   • \node_modules

   • \services

   • \utils

   • config.js

   • config.production.js

   • server.js

Delete deprecated assembly files

Delete the following deprecated assembly .dll files from the \wfgen\bin, \wfgen\ws\bin, and \Program Files\Advantys\WorkflowGen\services\bin folders:

• Advantys.Directories

• Advantys.Directories.Web.UI.Administration

• Advantys.Web.UI.Charting

• Advantys.Workflow.Applications.ExecSql

• Advantys.Workflow.Applications.GetUsersFromDir

• Advantys.Workflow.Applications.MergeForm

• Advantys.Workflow.Applications.RestApiClient

• Advantys.Workflow.Applications.SendMessage

• Advantys.Workflow.Applications.XmlToDatabase

• Advantys.Workflow.Applications.XmlTrans

• Advantys.Workflow.Reports

• Advantys.Workflow.Web.UI.Reports

Copy the upgrade pack content

Copy and overwrite the upgrade content from Update\Inetpub\wwwroot\wfgen to your WorkflowGen web application folder. By default, the suggested physical path is DRIVE:\Inetpub\wwwroot\wfgen.

• Domain users and the Windows accounts used to run the WorkflowGen IIS application pool and Engine service must have read and write permissions for the \wfgen\App_Data folder.

• Do NOT copy and overwrite your existing DRIVE:\Inetpub\wwwroot\wfgen\web.config file if you want to keep your current WorkflowGen configuration settings and database connection information.

• It’s possible that the following default CSS files have been updated in this release and could overwrite any changes you had made in your existing installation:

  • \wfgen\App_Themes\Default\portal\css\Default.css

  • \wfgen\App_Themes\Default\admin\css\Default.css

• If you've made changes to any of the default files in the following folders (e.g. *.aspx, *.css, *.resx files), make a backup of the existing files prior to the upgrade and manually re-apply these changes to the corresponding version 9.x.x files:

  • \wfgen

  • \wfgen\App_Themes

  • \wfgen\App_Data\Templates\Emails

  • \wfgen\App_Data\Templates\Forms

  • \wfgen\App_Data\Templates\Processes

Update WorkflowGen Windows Services files

Delete deprecated DLL file

Delete the deprecated DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\EAGetMail40.dll file.

Overwrite the WorkflowGen Windows Services folder

Overwrite the contents of your WorkflowGen Windows Services folder with the contents of Update\Program Files\Advantys\WorkflowGen. By default, the suggested physical path is DRIVE:\Program Files\Advantys\WorkflowGen.

Do NOT copy and overwrite your existing DRIVE:\Program Files\Advantys\WorkflowGen\Services\bin\*.config files.

Update Node.js program files

Copy node.exe.config and trace.config (located in Update\Program Files\nodejs) to DRIVE:\Program Files\nodejs.

If there's already a node.exe.config file in the DRIVE:\Program Files\nodejs folder, do not overwrite it. Instead, add the following to the existing file's <configuration> node:

<runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
        <dependentAssembly>
            <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-13.0.0.0" newVersion="13.0.0.0" />
        </dependentAssembly>
    </assemblyBinding>
</runtime>
<system.diagnostics configSource="trace.config" />

Update configuration files

This section contains configuration parameter changes you need to apply, based on the version of WorkflowGen from which you're upgrading.

This section has been divided to provide a quicker reference for clients upgrading from version 8.0.0 and later. If you're upgrading from version 7.22.15 or earlier, see the WorkflowGen Legacy Upgrade section and perform the required modifications to the web configuration file based on the version from which you're upgrading, then return to this section and continue with the rest of the required modifications.

📌 Examples

• When upgrading to version 9.2.1 Beta 2 from version 9.0.1 Beta, apply the changes in the When upgrading from version 9.0.1 Beta (v9 Beta 2) and earlier, When upgrading from version 9.0.2 Beta (v9 Beta 3), When upgrading from version 9.0.7 and earlier, and When upgrading from version 9.1.0 and earlier sections.

• When upgrading to version 9.2.1 Beta 2 from version 9.2.0 Beta 1, there are no changes to make to the web configuration file.

When upgrading from version 8.0.0 and earlier

1. Add the following new parameters to <appSettings>:

   <add key="RemoteApprovalAuthClientId" value="" />
   <add key="RemoteApprovalAuthClientSecret" value="" />
   <add key="RemoteApprovalAuthScope" value="" />
   <add key="RemoteApprovalAuthAccessTokenUri" value="" />

2. Remove the following deprecated parameter from <appSettings>:

   EngineTraceMode

When upgrading from version 8.0.1 and earlier

Add the following new parameters to <appSettings>:

<!-- AdobeSign -->
<add key="AdobeSignClientId" value="" />
<add key="AdobeSignClientSecret" value="" />
<add key="AdobeSignHostServer" value="" />
<add key="AdobeSignRefreshToken" value="" />
<add key="AdobeSignSendLogLevel" value="0" />
<add key="AdobeSignCheckLogLevel" value="0" />

When upgrading from version 8.0.2 and earlier

Add the following new parameters to <appSettings>:

<add key="EngineNotificationNotifyDelegator" value="Y" />
<add key="EnginePushNotificationSendExpoApiUrl" value="https://exp.host/--/api/v2/push/send" />

<!-- Docaposte -->
<add key="DocaposteUsername" value="" />
<add key="DocapostePassword" value="" />
<add key="DocaposteHostServer" value="" />
<add key="DocaposteOfferCode" value="" />
<add key="DocaposteOrganizationalUnitCode" value="" />
<add key="DocaposteSendLogLevel" value="0" />
<add key="DocaposteCheckLogLevel" value="0" />

When upgrading from version 8.0.7 and earlier

1. Add the following new parameter to <appSettings> :

   <add key="EngineServiceMaxPausedSynchroActions" value="25" />

2. Update the value of the EngineServiceTimeoutSystemActionFrequency parameter to 120000 as follows:

   <add key="EngineServiceTimeoutSystemActionFrequency" value="120000" />

When upgrading from version 8.0.10 and earlier

Add the following new parameter to <appSettings> :

<add key="PortalReportAdvancedViewPaging" value="N" />

When upgrading from version 8.1.0 Beta and earlier

1. Update the value of the following parameter in <appSettings>:

   <add key="PortalListPageSize" value="25" />

2. Remove the following parameters from <appSettings> from version 8.1.0 Beta only:

   <add key="PortalReportAdvancedViewPageSize" value="25" />
   <add key="PortalReportAdvancedViewPageSizeOptions" value="10,25,50,100,250" />

When upgrading from version 8.1.2 and earlier

Add the following new parameters to <appSettings> :

<add key="GraphqlApiKeyEnabled" value="N" />
<add key="GraphqlApiKey" value="" />

When upgrading from version 8.1.3 and earlier

1. Add the following new parameters to <appSettings>:

   <add key="PortalDisplayAssignedTeamAction" value="N" />
   <add key="HooksAllowImpersonateUser" value="N" />
   <add key="HooksApiKeyEnabled" value="N" />
   <add key="HooksApiKey" value="" />

2. Update the bindingRedirect node in all of the affected configuration files (listed below) from <bindingRedirect oldVersion="0.0.0.0-12.0.0.0" newVersion="12.0.0.0" /> to <bindingRedirect oldVersion="0.0.0.0-13.0.0.0" newVersion="13.0.0.0" />:

   • \wfgen\web.config

   • \wfgen\ws\web.config

   • \Program Files\Advantys\WorkflowGen\Services\bin\WfgWorkflowEngineService.exe.config

   • \Program Files\nodejs\node.exe.config

When upgrading from version 8.2.4 and earlier

1. Add the following new parameter to <appSettings>:

   <add key="ApplicationDefaultFullWidth" value="N" />

2. Update the value of the following parameter in <appSettings>:

   <add key="PortalCommentsPopUpHeight" value="600" />

3. Remove the following deprecated parameters from <appSettings>:

   ChartServiceAvoidColorCollision
   ChartServiceMaxSliceInPie
   ReportsChartServiceUrl
   ReportsChartTemplatePath
   ReportsChartTemplateExtension

When upgrading from version 8.2.4 and earlier OR from version 9.0.0 Beta (v9 Beta 1)

Add the following new parameters to <appSettings>:

<!-- Auth: Gardian -->
<add key="ApplicationSecurityAuthAcrValues" value="" />

<add key="AdobeSignRefreshUrl" value="/oauth/v2/refresh" />

<!-- Yousign -->
<add key="YousignApiKey" value="" />
<add key="YousignHostServer" value="" />
<add key="YousignSendLogLevel" value="0" />
<add key="YousignCheckLogLevel" value="0" />

When upgrading from version 9.0.1 Beta (v9 Beta 2) and earlier

Add the following new parameters to <appSettings>:

<add key="PortalDisplayRequestListWithActionsFollowUp" value="N" />

<!-- OpenAi -->
<add key="OpenAiApiKey" value="" />
<add key="OpenAiTranscriptionLogLevel" value="0" />

When upgrading from version 9.0.2 Beta (v9 Beta 3) and earlier

Add the following new parameter to <appSettings>:

<add key="OpenAiChatLogLevel" value="0" />

When upgrading from version 9.0.7 and earlier

1. Rename the following parameters in <appSettings>:

   <!-- OpenAI -->
   OpenAiApiKey
   OpenAiTranscriptionLogLevel
   OpenAiChatLogLevel

   as

   <!-- OpenAI -->
   OpenAIApiKey
   OpenAITranscriptionLogLevel
   OpenAIChatLogLevel

2. Add the following new parameter to <appSettings>:

   <!-- OpenAI -->
   <add key="OpenAIChatApiUrl" value="" />

When upgrading from version 9.1.0 and earlier

If you want to enable default HTTP error handling by WorkflowGen, replace the following parameter in <appSettings>:

<customErrors mode="Off"/>

with the following:

<customErrors mode="On" defaultRedirect="default_error_page.htm">
    <error statusCode="401" redirect="401.htm" />
    <error statusCode="404" redirect="404.htm" />
    <error statusCode="500" redirect="500.htm" />
</customErrors>

Update the root web configuration file

This step is mandatory when upgrading to version 9.2.1 (9.2 Beta 2), including if you're upgrading from version 9.2.0 (9.2 Beta 1) and had previously updated the root web.config file.

You must update your site's root web.config file with the new URL Rewrite rules.

First, make sure the URL Rewrite tool is installed on your WorkflowGen server.

There are two sample files provided in the installation pack.

• If your WorkflowGen site uses the /wfgen path in its URL (e.g. https://yoursite/wfgen), refer to the Inetpub\wwwroot\web.config (in the manual installation pack) or Inetpub\wwwroot\web.config.sample sample file (in the update pack) for the new rules.

• If your WorkflowGen site does NOT use the /wfgen path in its URL (e.g. https://yoursite), refer to the Inetpub\wwwroot\web.config.without-wfgen sample file for the new rules.

Update the login.aspx sample file (custom authentication only)

As of WorkflowGen 9.2.0, If you're using custom form authentication with a login page created based on the provided /wfgen/login.aspx sample template, you need to update the login page file. To do this:

1. Open your WorkflowGen site's /wfgen/login.aspx file (which might have been renamed).

2. Replace the redirectToUrl = "/wfgen/show.aspx?QUERY=WELCOME"; line with redirectToUrl = "/wfgen/dashboard";.

Update Form Designer webforms for versions 8 and later

As of WorkflowGen version 8, the WorkflowGen.My.Web.UI.WebControls.dll assembly has been merged into WorkflowGen.My.dll. This breaking change impacts webforms created in the Form Designer and the webforms' \bin folders, so you must perform one of the following procedures:

Method 1: Use the provided PowerShell script

Run the \update\configuration\update-webforms-wfg-my-assembly.ps1 script in PowerShell inside the \wfgen\wfapps\webforms\ folder. This will automatically update your ASPX webforms and delete deprecated files and folders.

This script requires PowerShell version 7.0 or later.

It will update all .aspx files located in the \webforms folder, including those not managed by the Form Designer. If you have custom webforms in this folder that use another version of WorkflowGen.My.dll, then you should skip the changes to these .aspx files. You can do this by moving these files to a temporary folder before running the script, and then copying them back to the original folder.

Usage example

.\update-webforms-wfg-my-assembly.ps1 -Path "c:\inetpub\wwwroot\wfgen\wfapps\webforms" -Verbose

Method 2: Manually

1. Delete the following files and folders from the\wfgen\wfapps\webforms\bin\ folder:

   • WorkflowGen.My.Web.UI.WebControls.dll

   • WorkflowGen.My.Web.Handlers.dll

   • \de

   • \fr

   • \hu

   • \pl

2. Upgrade each of your webforms created in the Form Designer, either by re-saving them or by manually replacing the <%@ Register Assembly="WorkflowGen.My.Web.UI.WebControls" ... %> tag with <%@ Register Assembly="WorkflowGen.My" ... %> inside each of your .aspx files.

Update the GraphQL and webhooks configuration files

In the \wfgen\graphql\web.config and \wfgen\hooks\web.config files, add the following to <system.webServer>:

<httpErrors existingResponse="PassThrough" errorMode="Detailed"></httpErrors>

Upgrade the WorkflowGen database

Run the SQL scripts listed below in order, starting with your current version of WorkflowGen.

This section has been divided to provide a quicker reference for clients upgrading from version 8.0.0 and later. If you're upgrading from version 7.22.15 or earlier, see the WorkflowGen Legacy Upgrade section and run the required database update scripts based on the version from which you're upgrading, then return to this section and continue with the rest of the required scripts.

Oracle database is no longer supported as of WorkflowGen 7.16.0.

For versions 8.0.1 and earlier

Launch the Update\Databases\MsSQLServer\Update_WFG-V8-0-2.sql database update script in your SQL Server Management Studio tool.

For versions 8.0.2 and earlier

Launch the Update\Databases\MsSQLServer\Update_WFG-V8-0-3.sql database update script in your SQL Server Management Studio tool.

For versions 8.0.x and earlier

Launch the Update\Databases\MsSQLServer\Update_WFG-V8-1-0.sql database update script in your SQL Server Management Studio tool.

For versions 8.1.3 and earlier

Launch the Update\Databases\MsSQLServer\Update_WFG-V8-2-0.sql database update script in your SQL Server Management Studio tool.

For versions 8.2.4 and earlier or version 9.0.0 Beta (v9 Beta 1)

Launch the Update\Databases\MsSQLServer\Update_WFG-V9-0-1.sql database update script in your SQL Server Management Studio tool.

For versions 9.0.1 Beta (v9 Beta 2) and earlier

Launch the Update\Databases\MsSQLServer\Update_WFG-V9-0-2.sql database update script in your SQL Server Management Studio tool.

For versions 9.0.2 Beta (v9 Beta 3) and earlier

Launch the Update\Databases\MsSQLServer\Update_WFG-V9-0-3.sql database update script in your SQL Server Management Studio tool.

For versions 9.0.7 and earlier

Launch the Update\Databases\MsSQLServer\Update_WFG-V9-1-0.sql database update script in your SQL Server Management Studio tool.

For versions 9.1.0 and 9.2.0 Beta 1

There is no database update script to run.

Configure IIS

Domain users and the Windows accounts used to run the WorkflowGen IIS application pool and Engine service must have read and write permissions for the \wfgen\app_data folder.

Update or create the application pool in .NET 4

The WorkflowGen website and web applications must now use an application pool in .NET 4. If this hasn't already been configured, do the following:

1. Install .NET Framework 4 on the server, if it's not already installed.

2. Update the existing application pool or create a new application pool using .NET Framework 4 for:

   • the WorkflowGen website

   • \wfgen

   • \wfgen\wfapps\webforms (create this IIS web application if it isn’t already created)

   • \wfgen\ws

3. If your application pool is set to use Classic Managed Pipeline Mode, make sure ASP.NET v4.0.30319 is set to Allowed in the IIS manager ISAPI and CGI Restrictions list.

WorkflowGen Node.js-based web applications

To use the GraphQL, incoming webhooks, OpenID Connect Auth, and SCIM APIs, you must first install the following requirements:

• Node.js v18.20.4 LTS

• iisnode

• IIS URL Rewrite

• Visual C++ Redistributable ✏️ Note: This library is required if you encounter the error The specified module could not be found regarding the edge and edge-js libraries when accessing the /wfgen/graphql, /wfgen/hooks, or /wfgen/scim web apps.

• Delete each Node.js-based application's node_modules folder (located under \wfgen\auth, \wfgen\graphql, \wfgen\hooks, and \wfgen\scim) before copying the files from the upgrade pack.

• After enabling GraphQL, incoming webhooks, OpenID Connect Auth, or SCIM, the WorkflowGen DLLs will be in use by Node.js, so they'll be locked from being updated. In order to update the DLLs, it's necessary to stop IIS.

To enable WorkflowGen GraphQL:

1. In IIS, convert /wfgen/graphql to an application with a .NET 4 application pool (integrated pipeline).

2. Configure the GraphQL application authentication mode:

   • For Basic authentication: Enable Basic authentication.

   • For WorkflowGen Applicative authentication:

     • Make sure the /wfgen web application already has WorkflowGen Applicative authentication enabled.

     • Enable Anonymous authentication.

3. Update the WorkflowGen web.config file with the following parameters used by GraphQL:

   <add key="GraphqlMaxPageSize" value="100" />
   <add key="GraphqlMaxBatchSize" value="1000" />
   <add key="GraphqlDefaultPageNumber" value="1" />
   <add key="GraphqlDefaultPageSize" value="30" />
   <add key="GraphqlGraphiqlEnabled" value="N" />
   <add key="GraphqlLoadersCacheEnabled" value="Y" />
   <add key="GraphqlDebugEnabled" value="N" />
   <add key="GraphqlQueryTimeout" value="90000" />
   <add key="GraphqlOperationTimeout" value="30000" />
   <add key="GraphqlMaxOperationCount" value="10000" />
   <add key="GraphqlMaxInputFileSize" value="10240" />
   <add key="GraphqlMaxInputFileContentSize" value="0" />
   <add key="GraphqlInputFileDownloadTimeout" value="100000" />
   <add key="GraphqlInputFileAllowedFolders" value="" />
   <add key="GraphqlInputFileAllowedHttpUrls" value="" />

To enable WorkflowGen incoming webhooks:

1. Update the WorkflowGen web.config file with the following parameters used by incoming webhooks:

   <add key="HooksDebugEnabled" value="N" />
   <add key="HooksOperationTimeout" value="30000" />
   <add key="HooksMaxInputFileSize" value="10240" />
   <add key="HooksMaxInputFileContentSize" value="0" />
   <add key="HooksInputFileDownloadTimeout" value="100000" />
   <add key="HooksInputFileAllowedFolders" value="" />
   <add key="HooksInputFileAllowedHttpUrls" value="" />

2. In IIS, convert /wfgen/hooks to an application with a .NET 4 application pool (integrated pipeline), and configure the hook application in Anonymous authentication mode.

If your WorkflowGen is configured to use WorkflowGen Applicative authentication or a custom authentication, you must remove the authentication module from the /hooks/web.config file as follows:

For WorkflowGen Applicative authentication:

<location path="hooks" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="ApplicationSecurityAuthenticationModule" />
        </modules>
    </system.webServer>
</location>

For Custom authentication:

<location path="hooks" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="MyCustomAuthModule" />
        </modules>
    </system.webServer>
</location>

To enable WorkflowGen SCIM:

In IIS, convert /wfgen/scim to an application with a .NET 4 application pool (integrated pipeline), and configure the application in Anonymous authentication mode.

If your WorkflowGen is configured to use WorkflowGen Applicative authentication or a custom authentication, you must remove the authentication module from the /scim/web.config file as follows:

For WorkflowGen Applicative authentication:

<location path="scim" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="ApplicationSecurityAuthenticationModule" />
        </modules>
    </system.webServer>
</location>

For Custom authentication:

<location path="scim" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="MyCustomAuthModule" />
        </modules>
    </system.webServer>
</location>

To enable WorkflowGen OpenID Connect Auth:

In IIS, convert /wfgen/auth to an application with a .NET 4 application pool (integrated pipeline), and configure the application in Anonymous authentication mode.

If your WorkflowGen is configured to use WorkflowGen Applicative authentication or a custom authentication, you must remove the authentication module from the \auth\web.config file as follows:

For WorkflowGen Applicative authentication:

<location path="auth" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="ApplicationSecurityAuthenticationModule" />
        </modules>
    </system.webServer>
</location>

For Custom authentication:

<location path="auth" inheritInChildApplications="false">
    <system.webServer>
        <modules>
            <remove name="MyCustomAuthModule" />
        </modules>
    </system.webServer>
</location>

Restart the WorkflowGen server

Reboot your WorkflowGen web server.

New location of workflow application temporary and log files

The following workflow applications store their files in these new locations:

• EFORMASPX: \wfgen\App_Data\Files\EFormAspx

• XMLTODATABASE: \wfgen\App_Data\LogFiles\XmlToDatabase

• XMLTRANS: \wfgen\App_Data\Files\XmlTrans and \wfgen\App_Data\LogFiles\XmlTrans