> For the complete documentation index, see [llms.txt](https://docs.workflowgen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.workflowgen.com/upgrade/copy-of-upgrade-10.5.0/important-notes-before-upgrading.md).

# Important Notes Before Upgrading

## Update .NET version <a href="#update-net" id="update-net"></a>

WorkflowGen 10.6.0 Beta requires .NET Framework 4.8, so you must install it **before** proceeding with this upgrade.

## WorkflowGen 10.6.0 compatibility and security requirements

### MCP Server

#### Authentication requirements

MCP connections require **OpenID Connect (OIDC) or SAML authentication** on the main WorkflowGen site, with OAuth access enabled on the MCP server. Windows, Basic, Applicative, Form, and custom authentication modules are not supported for MCP connections.

{% hint style="warning" %}
Upgrading WorkflowGen doesn't automatically change the site's authentication mode. If another mode is configured, keep `OAuthServerEnabled=false` until OIDC or SAML authentication is enabled. Installations that don't use MCP can retain their existing authentication mode.
{% endhint %}

#### Permissions and security

Before granting MCP design access, verify the server's allowed scopes, the client's OAuth grant, and the connected account's WorkflowGen permissions. An Administrator profile or a successful identity lookup doesn't automatically grant OAuth write access. Existing clients may require reauthorization for additional scopes.

Form source editing and custom ASP.NET publication are trusted designer capabilities and should not be made available to untrusted users.

Review `McpInputFileAllowedFolders` and `McpFileUploadPath`. Use dedicated import and upload folders without unrelated or sensitive files, and avoid unrestricted `*` access.

### Process definition compatibility

WorkflowGen 10.6.0 introduces stricter validation for process definition operations used by MCP, GraphQL, incoming webhooks, and native administration:

* **Global IDs:** Operations requiring a typed global ID must use the exact ID returned by WorkflowGen.
* **Process versions:** Archived versions cannot be reactivated.
* **Process management:** Moving processes requires administrator rights.
* **XPDL and version creation:** These require access to the affected process family, including versions in other folders.
* **Categories and file storage:** Unknown categories and prohibited storage changes now return errors instead of being silently ignored or partially applied.

{% hint style="warning" %}
Review affected integrations before upgrading. These validation changes don't make all MCP tools available through GraphQL or incoming webhooks.
{% endhint %}

### Request size compatibility

GraphQL and incoming webhooks retain their separate import size settings, `GraphqlMaxInputFileSize` and `HooksMaxInputFileSize`. The new MCP request size policy doesn't replace these settings or change User Portal and webform attachment limits.

For the applicable configuration changes, see the WorkflowGen 10.6.0 configuration steps and the [WorkflowGen Integration Guide](https://docs.workflowgen.com/integration).

### SAML authentication compatibility

Authentication 3.4.4 introduces stricter SAML validation, including updated request correlation, audience, signature, and validity checks.

**Before upgrading, test SAML login and logout with your configured identity provider (IdP)** and review the following requirements:

* **Encryption:** RSA-1.5 key transport and TripleDES encrypted assertions are no longer supported.
* **Redirect messages:** Decompressed messages are limited to 1 MiB.
* **Sign-in:** SAML authentication must start from WorkflowGen; unsolicited IdP-initiated sign-in is not supported.
* **Encrypted assertions:** If `ApplicationSecurityAuthSAMLWantAssertionsEncrypted=true`, the IdP must encrypt assertions using the service provider (SP) certificate, and `ApplicationSecurityAuthSAMLPrivateKey` must contain the matching private key. A missing or blank key prevents SAML initialization, and plaintext assertions are rejected.
* **Logout:** Register the exact SP logout response URL from the metadata, including casing: `https://your-domain.com/wfgen/auth/logout/callback`. The `/wfgen/auth/logout` URL is used to initiate logout.

If a logout response is invalid, WorkflowGen ends the local session and reports a validation error, but logout from the IdP or other applications isn't confirmed. External return URLs are rejected.

Correct incompatible IdP settings rather than disabling validation. No new WorkflowGen configuration key is required.

## Update the root `web.config` file's URL rewrite rules

As of WorkflowGen 9.2.0, you MUST update your site's root `web.config` file with the new URL rewrite rules, based on how your WorkflowGen URL is configured. For instructions on how to do this, see the [Update the root web configuration file](/upgrade/copy-of-upgrade-10.5.0/workflowgen-upgrade.md#update-the-root-web-configuration-file) section.

## Using `BACKURL_SUBMIT` and `BACKURL_CANCEL` parameters in custom WorkflowGen URLs

As of version 7.15.5, the optional `BACKURL_SUBMIT` and `BACKURL_CANCEL` HTTP parameters used in custom WorkflowGen URLs (for example, [when launching a new request and starting the first action within another website](https://docs.advantys.com/docs/integration/integration-using-workflowgen-urls)) now **ONLY** support absolute URLs (starting with `http://` or `https://`), relative URLs (starting with `/`), or URLs defined in the `PortalRedirectAllowedHttpUrls` configuration parameter (e.g. `value='blank.htm, myPage.htm'`).

## Password encryption change

As of version 7.15.0, the SMTP server account and Remote Approval incoming server account passwords are no longer encrypted in the `web.config` file.

Before upgrading an existing WorkflowGen server, you must manually reset the passwords in cleartext for the `ApplicationSmtpPassword` and `RemoteApprovalIncomingServerPassword` parameters in the `web.config`. Alternatively, you can use the provided `convert-web-config-pwd.ps1` PowerShell script in `\wfgen` to decrypt and convert the passwords in the `web.config`.

## Database server

{% hint style="warning" %}
SQL Server Full-Text Search is required for WorkflowGen v10, with or without vector support, even if full-text search is not used. Existing v10 installations should already meet this prerequisite; no reinstallation is needed if the component is present.
{% endhint %}

WorkflowGen 10.6.0 can use SQL Server 2016-2022 for full-text-only search when the required Full-Text Search component and indexes are available. Semantic and hybrid search require vector-capable SQL Server 2025 or Azure SQL storage and a configured embedding provider.

An engine upgrade does not convert an existing compatibility column automatically. Oracle and SQL Server 2005, 2008, 2012, and 2014 remain unsupported. Rehearse the upgrade and required application functions on a restored database before production deployment.

### Migrating a legacy WorkflowGen database from MS SQL Server 2005/2008

SQL Server 2005 and 2008 are not supported targets for WorkflowGen 10.6.0. Before moving a legacy WorkflowGen database from one of these engines, complete the mandatory historical trigger compatibility preparation described by its corresponding Upgrade guide.

Use the `Update_WFG-V7-0_SQL_Triggers_2012.sql` preparation script at the stage prescribed by the corresponding historical Upgrade Guide. This preparation is not required for a database already running on SQL Server 2012 or later.

Use the historical guide to apply that preparation in SQL Server Management Studio at the prescribed stage, then move the database to a supported target engine and complete the remaining product-version upgrades for the actual starting version.

{% hint style="warning" %}

* SQL Server 2012 and 2014 are also unsupported 10.5.0 targets.
* The v8/v9 assisted runner does not perform an engine migration and cannot be run on SQL Server 2005/2008.
* Rehearse the complete route on restored backups before production deployment.
  {% endhint %}

## Node.js modules <a href="#node-js-modules" id="node-js-modules"></a>

The Node.js modules include the GraphQL API, webhooks, SCIM, Auth, and MCP Server. For instructions on how to enable them, see the [WorkflowGen Node.js-based web applications](https://docs.workflowgen.com/upgrade/copy-of-upgrade-10.5.0/pages/2pPL9mH28y37sTMNIj9y#workflowgen-node.js-based-web-applications) section.

### Update Node.js version

Update existing installations separately to the recommended [Node.js v24.22.2 LTS runtime](https://nodejs.org/dist/v24.22.2/) for WorkflowGen 10.6.0. The pack supports Node.js 24.19.0 or later within the 24.x release line (i.e., not v25 or later); older compatible patches are not the recommended security baseline. Copying the WorkflowGen Update package does not install or upgrade Node.js. The PowerShell installation package is intended for new installations.

Before enabling MCP Server, make sure the applicable[ WorkflowGen database updates](/upgrade/copy-of-upgrade-10.5.0/workflowgen-upgrade.md#update-the-workflowgen-database), including the existing OAuth persistence schema, have been applied. WorkflowGen 10.6.0 adds no new versioned database script after 10.4.0. Do not replay updates already applied to the database.

### GraphQL and incoming webhooks file upload management parameters

As of WorkflowGen version 7.10.0, if you're using incoming webhooks or GraphQL to upload files when starting a new request or completing an action, you must set the `GraphqlFileInputAllowedFolders`, `HooksFileInputAllowedFolders`, `GraphqlMaxInputFileContentSize`, and `HooksMaxInputFileContentSize` configuration parameters with the appropriate values (see the [When upgrading from version 7.9.1 and earlier](/upgrade/copy-of-upgrade-10.5.0/workflowgen-upgrade/legacy-upgrade.md#id-791-earlier) section).

* `GraphqlFileInputAllowedFolders` and `HooksFileInputAllowedFolders`: These parameters should contain the physical paths of folders that contain files used in uploads.
* `GraphqlMaxInputFileContentSize` and `HooksMaxInputFileContentSize`: These parameters should contain the maximum file size in kilobytes when uploading files using the file content method.<br>

  ✏️ **Note:** We recommend limiting the file content size to small files under 1 megabyte.

### GraphQL and incoming webhooks XPDL file access restrictions

As of WorkflowGen version 10.4.0, GraphQL and incoming webhook operations that use `xpdl.url` to access server-local XPDL files are restricted to trusted folders.

Before upgrading, review any existing integrations that pass a server-local `file://` URI using `xpdl.url`. If an XPDL file is located outside the application's managed upload directory, add its trusted directory to the corresponding configuration parameter:

* `GraphqlInputFileAllowedFolders`: Comma-separated list of trusted folders for GraphQL input file
* `HooksInputFileAllowedFolders`: Comma-separated list of trusted folders for incoming webhook input files

Use narrowly scoped directories controlled by WorkflowGen administrators. The resolved file and its existing parent path must remain inside an allowed directory and must not traverse junctions, symbolic links, or other reparse points.

#### 📌 Example

```xml
<add key="GraphqlInputFileAllowedFolders" value="D:\WorkflowGen\TrustedDefinitions" />
<add key="HooksInputFileAllowedFolders" value="D:\WorkflowGen\TrustedDefinitions" />
```

When these parameters are empty, WorkflowGen still allows files located in the corresponding managed upload directory under the configured `ApplicationDataPath`:

* GraphQL: `Files\GraphQL\Uploads`
* Incoming webhooks: `Files\Hooks\Uploads`

Existing multipart file uploads therefore continue to work without configuring an additional trusted folder. Existing integrations that use `xpdl.url` to read files from other server-local directories must add those directories to the appropriate configuration parameter before upgrading.

{% hint style="info" %}

* Inline XPDL content must be Base64-encoded valid UTF-8 and must not exceed the configured input file size limit. Invalid UTF-8 content is rejected instead of being decoded using replacement characters.
* MCP artifact files are managed separately by the `McpInputFileAllowedFolders` configuration parameter and the MCP managed upload directory.
  {% endhint %}

## Configuring custom web forms in WorkflowGen 8 or later <a href="#custom-web-forms" id="custom-web-forms"></a>

If you're using custom web forms configured in .NET 2.0, you can keep using them in .NET 2.0 or migrate them to .NET 4.

#### To configure custom web forms for .NET 2.0

1. Use `WorkflowGen.My.dll` in version 2.x.<br>

2. Use a .NET 2.0 application pool.<br>

3. Disable **Web apps secure mode** in the **Security** section on the **General** tab in the **Configuration Panel**.<br>

4. Define or update the following nodes in the web form’s `web.config`:

   ```html
   <configuration>
       <system.web>
           <pages validateRequest="false" enableSessionState="true" />
       </system.web>
   </configuration>
   ```

5. If your web form’s authentication is configured to use the built-in WorkflowGen authentication mode, then the new password hashing mode (One-way Hashing) introduced in version 6.1 will not be compatible with your web form. There are two solutions:<br>
   * Use **Version 5** password management mode instead. Make sure to use the `Advantys.My.dll` and `Advantys.Security.dll` files from version 5.x in the web form’s `\bin` folder.<br>

     **OR**<br>
   * Migrate your web form to .NET 4. Make sure to use the `Advantys.My.dll` and `Advantys.Security.dll` files from WorkflowGen version 8.x in the in the web form’s `\bin` folder. For instructions on how to do this, see the next section.

#### To migrate custom web forms to .NET 4

1. Use `WorkflowGen.My.dll` in version 8.x.x or later.<br>

2. Use a .NET 4 application pool.<br>

3. Define or update the following nodes in the web form’s `web.config`:

   ```html
   <configuration>
       <system.web>
           <httpRuntime requestValidationMode="2.0" targetFramework="4.8" />
           <pages validateRequest="false" enableSessionState="true" clientIDMode="AutoID" controlRenderingCompatibilityVersion="3.5" />
       </system.web>
   </configuration>
   ```

4. If your web form’s authentication mode is configured with the built-in WorkflowGen authentication, then make sure to use the `Advantys.My.dll` and `Advantys.Security.dll` files from version 8.x.x or later in the web form’s `\bin` folder.

{% hint style="warning" %}

* These instructions apply only to configuring web forms to run properly without configuration errors. They do not cover potential migration or compatibility issues that may arise due to changes in the latest version of WorkflowGen.My. You must fully retest all of your web forms before production.
* After an upgrade or migration to WorkflowGen 8 or later, custom web forms that use a version 8 or later `WorkflowGen.My.dll` in their custom `\bin` folders require the `WorkflowGenMy.*.resx` resource files in their `App_GlobalResources` sub-folders.
  {% endhint %}

## Preserving Change events configuration <a href="#sdk-workflow-application" id="sdk-workflow-application"></a>

{% hint style="info" %}
This section does not apply when upgrading from a version earlier than 9.7.0, or if Change events was never enabled. In those cases, use the normal first-time activation procedure after completing the upgrade.
{% endhint %}

When upgrading from WorkflowGen version 9.7.0 or later, you must preserve the existing Change events integrity key and data if this feature was enabled. Do not replace the key with the empty sample value.&#x20;

Under **Change events** on the Administration Module **Configuration** panel **General** tab, set the **Audit mode** to **Off** before the upgrade and retain the exact key on every web and engine service instance sharing the database. After every instance has been upgraded, restore the previous mode and follow the instructions in the **Verify Change events activation** in the Technical Guide Operations documentation.

{% hint style="warning" %}
Do not combine this product upgrade with a database-provider migration.
{% endhint %}

## When deploying a custom assembly SDK workflow application <a href="#sdk-workflow-application" id="sdk-workflow-application"></a>

The WorkflowGen.My and Workflow Web Controls assemblies are no longer strong-named in order to allow non-specific version dependency when referenced by other applications such as custom assembly SDK Workflow applications in WorkflowGen.

This simplifies the deployment procedure of an assembly SDK Workflow application to WorkflowGen 6.2.0 and later, and allows upgrading WorkflowGen to a newer version without having to rebuild the application's assembly that was referencing an older version of WorkflowGen.My.

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

### Assembly location <a href="#assembly-location" id="assembly-location"></a>

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 3.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 [https://msdn.microsoft.com/en-us/library/6axd4fx6(v=vs.110).aspx](https://msdn.microsoft.com/en-us/library/6axd4fx6%28v=vs.110%29.aspx).<br>

   **OR**<br>
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 [How to add an assembly resolve event delegate to overcome WorkflowGen.My dependency issue when deploying custom assembly SDK workflow application](https://discuss.workflowgen.com/t/how-to-add-an-assembly-resolve-event-delegate-to-overcome-workflowgen-my-dependency-issue-when-deploying-custom-assembly-sdk-workflow-application/330) WorkflowGen Knowledge Base article.<br>

   **OR**<br>
3. Add a web configuration setting to redirect the required version to the current version of WorkflowGen.My. For more information, see [https://msdn.microsoft.com/en-us/library/twy1dw1e(v=vs.110).aspx](https://msdn.microsoft.com/en-us/library/twy1dw1e%28v=vs.110%29.aspx).

{% hint style="info" %}
If your assembly is built with WorkflowGen.My version 3.1.0 or earlier, it can be used in WorkflowGen versions 6.2.0 and later if one of the above workarounds has been implemented.
{% endhint %}

#### WorkflowGen.My 3.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 [Assembly location](#assembly-location) section above in WorkflowGen version 6.2.0 and later.

{% hint style="info" %}
If your assembly is built with WorkflowGen.My version 3.2.0 or later, it can be used in WorkflowGen versions prior to 6.2.0 if you've implemented **either workaround 2 or 3** above.
{% endhint %}

### Reference 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.

## FIPS compliance configuration

WorkflowGen is FIPS compliant as of version 7.10.0. If you want to enable FIPS compliance in your Windows environment, you have to configure the configuration password management and user password management modes beforehand.

### Configuration password management mode

In the **Security** section on the Configuration Panel **General** tab, set **Configuration password management mode** to **AES (FIPS Compliant)** and enter a 32-character encryption key. When you click **Save**, the application passwords will automatically be converted to the new symmetric encryption mode.

### User password management mode

In the **Authentication** section on the Configuration Panel **General** tab, set **Password management mode** to **One-way Hashing (SHA256 FIPS Compliant)** mode.

* If you're using Applicative authentication in **Version 5 (Legacy)** password management mode, users' passwords will automatically be converted into One-way Hashing (SHA256 FIPS Compliant) the next time they log into WorkflowGen.<br>
* If you're using Applicative authentication in **One-way Hashing (SHA256)** password management mode:
  1. Select **IIS** authentication mode.
  2. Select **One-way Hashing (SHA256 FIPS Compliant)** password management mode, then click **Save**.
  3. Re-enter all user passwords.
  4. Reset the authentication mode to Applicative.

## Legacy software support

### Browser and OS versions

WorkflowGen no longer supports Internet Explorer, Windows XP, Windows 7, Windows 8, or Windows Server 2003 or 2008.

### Database

Microsoft SQL Server 2005, 2008, 2012, and 2014 are not supported targets for WorkflowGen 10.6.0.&#x20;

SQL Server 2016, 2017, 2019, and 2022 can be used for full text-only search with the required Full-Text Search component and indexes. Semantic and hybrid search require native vector-capable SQL Server 2025 or Azure SQL storage and the matching embedding provider configuration.

Oracle is not supported.

### Workflow applications

The following applications are deprecated and are no longer provided as of WorkflowGen version 6:

* EFORMPDF
* DOCAPPROVAL
* DOCUPLOAD
* FDFTOXML
* PDFTODATABASE

However, if any of your processes still use these workflow applications, you can keep them declared under the WorkflowGen website as in version 5.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.workflowgen.com/upgrade/copy-of-upgrade-10.5.0/important-notes-before-upgrading.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
