Nintex K2 for SharePoint SPFx Migration Tool

Software prerequisites:

• Nintex Automation for SharePoint app for SharePoint Online
• Nintex Automation (5.8) or greater

The following versions are not currently supported:

• SharePoint On-Premises
• K2 blackpearl
• Any Nintex K2 versions prior to Nintex K2 Five (5.8). To use the migration tool, you must first upgrade to Nintex Automation (5.8).

Before you use the migration tool, consider the following:

• Clean up your environment as this can help identify any issues that may exist. Any workflows that start with the An item check out was discarded event cannot be migrated. If a workflow starts with this event, it cannot be migrated as Microsoft does not support it in the SPFx model. Edit the workflow and change the start type or remove the workflow completely. See Delete a workflow for more information about deleting workflows.
• Make a backup of your K2 database. This is useful if any unforeseen issues occur with migration.

Workflows and forms are not modified, only the integration points in SharePoint. The migration tool adds/modifies the following data:

• For each list created with SharePoint event based workflows:
  • Remove the legacy remote event receiver URL in SharePoint linked to the list.
  • Register a new webhook URL against the list.
• For each form integrated with SharePoint
  • Modify the New/Edit/Display forms to use the built-in SPFx launch URL instead of the legacy K2Pages library hosting pages.

To migrate your existing Nintex K2 for SharePoint solutions to Nintex Automation for SharePoint, follow the steps below.

1. Download and extract the Nintex K2 for SharePoint SPFx Migration Tool.
2. Open the tool by clicking the link for the application (MigrationTool > SourceCode.MigrationTool.exe).
3. Click Add New Connection to create a connection to your Nintex K2 domain.
   

4. Add the server name and server port. This is the K2 server/farm domain name and port. When selecting the Integrated Security check box you don't have to provide a username, password and Windows domain. If you are running the tool on the K2 server, you can continue with the default settings for localhost and port 5555. Click OK.
   

5. Ensure the status shows Connected after creating the connection. Click New Scan to scan your environment. This allows the tool to check for prerequisites and any dependencies that are not supported.
   
6. A count of all SharePoint integrated artifacts that use the App Add-In model is shown. Once the scan is complete, you can click Logs to view the scan log. Click Finish to return to the main page.
   
7. Click Scan History to view the App Catalog URLs, status, artifacts count, and time it was scanned. Click Back to return to the main page.
   
8. Click Start Migration to migrate your Nintex K2 for SharePoint artifacts to the Nintex Automation for SharePoint (SPFx) app.
   
9. Each site collection is updated to support the SPFx settings. If any errors occur, click Logs to view the log files. If you require assistance solving these errors, contact Nintex Customer Support and provide them with the log file. Once you have fixed the errors, click Retry for a specific item or Retry All to re-evaluate the migration.
   Items shown in green are migrated
   Items shown in blue are not migrated yet
   Items shown in red contain errors
   
10. Once all items have passed evaluation, a message is shown to confirm the environment is switched to support the modern features. You can now access the artifacts using the Nintex Automation for SharePoint (SPFx) app. Click Finish to return to the main page.
    
11. To view your migration history, click Migration History on the main page. See post migration steps to cleanup your environment once all solutions have been migrated.
    

To validate the migration of lists, check the following:

• Forms
  To validate that forms have successfully migrated, open a list or document library that uses New/Edit/Display SharePoint integrated forms and select New/Edit item.
  Notice the URL bar contains _layouts/15/SPListForm.aspx for migrated SPFx forms.
  Example
  
  Example of a legacy form url: (Using K2Pages lib)
  
• Workflows/List settings
  To validate that webhooks have successfully registered for each list, perform a SQL select statement on the [K2].[Integration].[ProcessSharePointSetting] table where specifying a listId or listtitle. The SubscriptionId column must be populated with a guid containing the Id of the webhook subscription against that list or document library.

When errors occur during scanning or migration, they are logged to the application logs folder (“Logs” directory in the same folder as where the application was launched from). The main log file is Log.txt and a separate log file is created for each site collection.

Other log locations to check:

• Event viewer – Applications and Services Logs – K2
  During webhook registration look for Source "K2 SharePoint Workflow Integration" and the following is logged if successful:
  • [Detail]: Called SPWebhookController
  • [Detail]: Received validation token: guid
    
• K2 hostserver logs
  • Search for Error and look for SharePoint Integration broker methods that may fail with additional error information.

Once your SharePoint environment has been successfully migrated, two feature flags are set defining design time and runtime behavior from this point onwards:

• Webhooks – When designing a new workflow, SharePoint events using webhook integration are shown.
• SPOnlineModernForms – All new forms generated by appifying SharePoint lists are configured to load through SPFx and contain modern theme layout to improve rendering.

• Inspect errors by opening the log files from the scanning and migrating screens of the migration tool. If you require assistance solving these errors, or if you have any issues with migrated solutions, contact Nintex Customer Support and provide them with the log files and RecoveryDB as shown below. This can be found in the application's directory.
  
• When using Package and Deployment, ensure you migrate solutions on the source AND target environments. Both environments must be in sync before packaging and deploying solutions to a new environment.
• All new workflow instances use webhooks in the SPFx model which means there can be a delay when starting new instances. This is dependent on load, the time of day, and when in the cycle the item is added to the webhook stack. This change in behavior is due to webhooks being asynchronous.