Nintex K2 Cloud SPFx Migration Tool

Microsoft has announced the deprecation of the SharePoint App Add-In Model and recommends migrating custom developed SharePoint Add-Ins to SharePoint Framework based solutions. See Modernization guidance for existing SharePoint Add-In model implementations in Microsoft 365 for more information about the transformation to use other long term supported features.

To continue to integrate with SharePoint Online, we have rewritten our integration points that rely on the deprecated Add-In model to the modern SharePoint extensibility model, SharePoint Framework (SPFx).

The Nintex K2 Cloud app uses the SharePoint Framework extension model (SPFx) that allows for full page, client side customization of SharePoint, including web parts, forms, command bars, and context menu items.

If you have existing SharePoint Online solutions using the legacy Nintex K2 Cloud for SharePoint app, you must move your existing solutions to Nintex K2 Cloud (SPFx) app before the deadline provided by Microsoft. From Nintex K2 Cloud Update 21 onwards, you can use the Nintex K2 Cloud SPFx Migration Tool to do this. The migration tool connects to the K2 database, create an inventory of Add-In based artifacts and perform the changes for you.

The App Add-In model support only affects SharePoint Online

Software prerequisites:

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.

  • Contact Nintex Customer Central for assistance with creating a backup of your K2 database.

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.
Before migrating your solutions, we suggest everyone working with the SharePoint solutions you want to migrate stop working on it to ensure there is no confusion in which app to use. Once migration is done, people can continue using the Nintex K2 Cloud (SPFx) app. This ensures there are no work lost or duplicates created while migrating the solution.

To migrate your existing Nintex K2 Cloud for SharePoint solutions to Nintex K2 Cloud (SPFx) app, follow the steps below.

  1. Download and extract the Nintex K2 Cloud (SPFx) app Migaration 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. A dialog window will show prompting you to sign in to your K2 Cloud environment. Sign in using a K2 Server Administrator account.


  5. On connecting, the server connection properties dialog will be populated with the server name and port (also used for Package & Deployment). Click Save to store the connection string and connect to the environment.

  6. 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.
  7. 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.
  8. 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.
  9. Click Start Migration to migrate your Nintex K2 Cloud for SharePoint artifacts to the Nintex K2 Cloud (SPFx) app.
  10. 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
  11. 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 K2 Cloud (SPFx) app. Click Finish to return to the main page.
  12. 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)

If the connection expires or drops and you close the app, it may fail to launch. This issue occurs because the token has expired. Follow the steps below to resolve the issue:

  1. Open the SourceCode.MigrationTool.exe.Config file.

  2. Delete the existing connection string.

  3. Save the file.

  4. Relaunch the app.

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.

After completing the migration successfully, you must manually remove the legacy K2 Workflows context menu item and K2 ribbon items from all activated site collections. A cleanup script is available to assist with this process. Follow the steps provided to run the script and complete the cleanup.

  • 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.

  • When you connect to the K2 server remotely using the Migration Tool, network latency may cause noticeable delays while interacting with the application.

  • After completing the migration, you must manually remove the legacy app. Only perform this step after confirming that webhook events and modern forms are running as expected. You can keep both the SPFx and legacy add-in on the site during testing, but remove the legacy app only as the final step to avoid disrupting functionality.

  • Once you remove the legacy app, reinstalling it will create a new app web with a different URL. This change will break existing integrations. Keep the legacy app installed until you have fully verified that the post-migration environment is functioning correctly. Only remove the app once all functionality has been confirmed.