KB003717

PRODUCT

Nintex Automation K2

BASED ON

Nintex Automation K2

Introduction 

This article provides guidance for customers with existing Nintex Automation K2 for SharePoint solutions who plan to upgrade their SharePoint farm to SharePoint Subscription Edition (SE). The SharePoint upgrade process itself is out of scope for K2 documentation. This article covers only the K2-specific steps you must complete before and after the SharePoint upgrade to ensure your K2 solutions continue to work. 

Background and risk  

When you upgrade a SharePoint farm using the database detach-and-attach approach, SharePoint generates a new SPAuthenticationRealm value for the new farm. This causes the following issues for existing K2 for SharePoint solutions: 

• Since the OAuth flow between K2 and SharePoint relies on the SPAuthenticationRealm value, the new value no longer matches K2's configuration. K2 will be in an unauthenticated state. 

• Remote Event Receivers will stop executing because the SharePoint Realm in their configuration no longer matches the new farm’s realm. 

• The SPTrustedRootAuthority and SPTrustedSecurityTokenIssuer entries for K2 are removed from the new farm during the upgrade. This means the K2 for SharePoint app must be redeployed to the App Catalog. 

Note   

Setting the SPAuthenticationRealm of the new farm to the SPAuthenticationRealm of the old farm resolves these issues. There is no automated fix for the realm mismatch. The steps in this article describe how to prevent or resolve this manually.

New customers 

If you are a new customer who has not yet installed K2, you must upgrade your SharePoint farm to Subscription Edition first before installing K2 for SharePoint on the new farm. This avoids the realm mismatch entirely. 

Existing customers 

For existing customers with K2 already integrated into a SharePoint farm, follow the steps below. 

Before you begin 

Confirm that you have the following before starting the upgrade process: 

• Administrative access to the existing SharePoint farm. 

• Access to the SharePoint Management Shell on the existing farm. 

• The Nintex Automation K2 installation file. 

• Administrative access to the new SharePoint Subscription Edition farm after upgrade. 

• Access to the SharePoint App Catalog on the new farm. 

Important   

Back up your existing environment before proceeding. This includes your SharePoint databases and your K2 environment. 

Step 1: Before the SharePoint upgrade - record the current SPAuthenticationRealm 

Complete this step on your existing SharePoint farm before you begin the Microsoft upgrade procedure. 

The SPAuthenticationRealm value from your existing farm must be applied to the new farm after the upgrade. Without this value, K2 will not authenticate correctly with SharePoint. 

Record the SPAuthenticationRealm 

1. Log in to your existing SharePoint farm. 

2. Open the SharePoint Management Shell. 

3. Run the following command: 

Get-SPAuthenticationRealm 

4. Copy the value returned by the command and store it securely. You will need this value after the upgrade. 

Step 2: Upgrade your SharePoint farm 

Upgrade your SharePoint farm to Subscription Edition following the Microsoft upgrade guide: Upgrade databases from SharePoint Server 2019 and SharePoint Server 2016 to SharePoint Server Subscription Edition. 

Do not proceed to Step 3 until the SharePoint upgrade is fully complete. 

Step 3: After the SharePoint upgrade, restore K2 integration 

Complete the following steps on your new SharePoint Subscription Edition farm after the upgrade. 

3.1) Restore the SPAuthenticationRealm 

Restoring the original SPAuthenticationRealm ensures that the OAuth flow between K2 and SharePoint continues to work without requiring you to redeploy all Remote Event Receiver workflows. 

1. Log in to your new SharePoint Subscription Edition farm. 

2. Open the SharePoint Management Shell. 

3. Run the following command to record the new farm realm (you must keep this value in case you need to roll back): 

Get-SPAuthenticationRealm 

4. Restore the original realm by running the following command, replacing the placeholder with the value you recorded in Step 1: 

Set-SPAuthenticationRealm -Realm {value from existing old farm} 

Note   

If you choose not to restore the original SPAuthenticationRealm and instead proceed with a new realm, you must redeploy all Remote Event Receiver workflows after completing Step 3b and Step 3c below. This ensures the workflows align with the new realm value. 

3.2) Redeploy the K2 for SharePoint app 

The  SPTrustedSecurityTokenIssuer and SPTrustedRootAuthority entries for K2 are not carried over to the new farm during a database attach-and-detach migration. Redeploying the app restores these entries to the new environment.  

1. Prepare the Installer: Copy the Nintex Automation K2 installation executable to your new SharePoint server.  

2. Extract and Locate: Extract the contents of the executable.  

3. Launch App Deployment: Navigate to the \Installation\ folder and launch AppDeployment.exe.  

4. Initiate Wizard: Click Next on the Welcome screen.  

5. Configure Web Service: Enter your environment's Web Service URL SSL value.  

   Best practice to find the URL: 

   • Navigate to your Nintex Automation Management site.  

   • Expand Environment Library > select your environment (Development or Production).  

   • Copy the value from the Web Service URL SSL environment variable. 

6. Target the Catalog: Click Next, select your new SharePoint App Catalog, and click Next again.  

7. Complete Deployment: Once the setup completes successfully, click Finish. 

3.3) Run the Registration Wizard 

1. Navigate to your SharePoint App Catalog site. 

2. Open the K2 Five for SharePoint app. 

3. Select Registration Wizard under Administration. 

4. The wizard should detect the Web Service URL from your previous SharePoint farm. Click Next to continue through the wizard and complete the registration. 

Note   

If the wizard does not detect the previous URL automatically, enter the Web Service URL SSL value manually. This is the same value used in Step 3.2. 

Verification 

After completing all steps, verify that your K2 solutions are working correctly: 

• Open a K2-integrated SharePoint list or library and confirm that K2 workflows start as expected. 

• Trigger a Remote Event Receiver workflow and confirm that it executes. 

• Log in to the Nintex Automation Management site and confirm that the environment shows a healthy connection to SharePoint. 

Rollback 

If you need to reverse the SPAuthenticationRealm change, run the following command on the SharePoint Subscription Edition farm using the new realm value you recorded in Step 3a: 

Set-SPAuthenticationRealm -Realm {new farm’s realm value} 

After restoring the new realm, repeat Steps 3b and 3c, and redeploy all Remote Event Receiver workflows.