Upgrading to Nintex K2 Five/Nintex Automation

KB002045

K2 Five Release Notes (for all versions read here.)
K2 Product Compatibility, Integration and Support
Nintex Automation (5.8) Installation and Configuration Guide
All K2 Five Installation, User and Developer guides.

What's New in Nintex K2 Five (5.3)
What's New in Nintex K2 Five (5.4)
What's New in Nintex K2 Five (5.5)
What's New in Nintex K2 Five (5.6)
What's New in Nintex Automation (5.7)
What's New in Nintex Automation (5.8)

Upgrade your existing K2 4.7 environment to K2 Five to get the latest tools and feature available to K2 customers. This article discusses what you need to know before, during, and after upgrading.

Pay attention to deprecated functionality and components to determine if you need to make changes to your environment before upgrading.

Contents

• Upgrade Path
• Prerequisites and Preparation
• Before Upgrading
• While Upgrading
• After Upgrading
• Deprecated Functionality and Components
• Behavioral Changes
• Considerations
• FAQ

Upgrade Path

• You must have K2 4.7 before you can upgrade to K2 Five. If you are on version prior to K2 4.7, you must upgrade to K2 4.7 and only then can you upgrade to K2 Five.
• If you have been part of the K2 Five RC program you can upgrade your K2 Five RC environment to K2 Five RTM.
• If you have a single SharePoint web app/app catalog containing multiple site collections that serve your different K2 environments (which is not recommended best practice but can work), see the SharePoint On-premises > Upgrade steps section of K2 for SharePoint App Registration and Activation in the K2 Five Installation and Configuration Guide.
• Upgrading Nintex K2 blackpearl (4.7) or Nintex K2 Five versions (5.0), (5.1), (5.2), (5.3), (5.4), and (5.5) to Nintex Automation (5.8) is not supported.  With Nintex Automation (5.8), you must upgrade from a previous version to at least Nintex K2 Five (5.6) or Nintex Automation (5.7) before upgrading to the latest version of Nintex Automation.

Prerequisites and Preparation

• Before upgrading your environment, refer to Third-party support with K2 Five article as a number of supporting product versions are no longer supported. If certain versions of third-party software are detected, you cannot proceed with the upgrade.
• Refer to the K2 Five Compatibility, Integration and Support matrix to ensure you have the correct version of supporting software installed.
• You may want to read the following articles to prepare for upgrading from K2 4.7 to K2 Five:
  • K2 Cloud and K2 Five: Product Features and Functionality Comparison
  • Product Compatibility, Integration and Support
  • Comparison of capabilities between K2 Management Console and K2 Management Site
  • Comparison of capabilities between K2 4.7 Workflow Designer and K2 Five Workflow Designer
• Before upgrading your environment, run the configuration analysis on the current version to see if any warnings and errors are shown in order for them to be addressed. This will ensure the environment is in a good state before the upgrade.
• Check the latest install logs on the environment to see if any errors were logged as this will indicate what the state of the environment is. Any errors and warnings will need to be addressed.

Before Upgrading

Please be aware of the following considerations before you start:

• A new license key is required on upgrade. You can get a new license key from the K2 Partner and Customer Portal to have it ready when the installer requests the key.
• Single Installer: The K2 Setup Manager installs as well as upgrades all tools you need to design, deploy, and use K2.
• Unattended Installer: New variables are present in the installer, so you must regenerate any unattended installation files with the new installer before you can use the XML file for other K2 Five installations.
• If you use the upgrade command /NoUI/Update you are prompted for your new license key as well as the service account password.
• Packages created with K2 Package and Deployment on previous versions of K2 cannot be deployed to K2 Five. Once upgraded, you must recreate those packages.
• An administrator with the K2 service account credentials must be present during the upgrade so that the new K2 service is registered.
• Remove blocked components (such as K2 for Reporting Services, K2 for Visual Studio 2012, and K2 for SharePoint 2010) by running the K2 Setup Manager from the Program Files (x86) folder and not from a downloaded copy. See the Third-party support with the K2 Five release for a full list of blocked components.
• If you currently have K2 connect installed, K2 recommends you wait for K2 connect 5.0 to be released before upgrading to K2 Five.

While Upgrading

• The K2 Five Setup Manager guides you through the upgrade configuration.
• After the K2 Five Setup Manager completes, you have the option to automatically run AppDeployment.exe to add the new version of the K2 for SharePoint app to your app catalogs. When you browse to your app catalog's Site Contents page, make sure to go into the app and click GET IT.
• For more  information on the upgrade steps, see the Upgrade topic in the Installation and Configuration Guide. 

After upgrading

• Update the K2 for SharePoint App: There is a new K2 for SharePoint App called K2 Five for SharePoint that is added to the app catalog. To update the existing app, browse to the Site Contents page of the App Catalog, and click the upgrade link for K2 for SharePoint app. If you do not see the link, go into the Details page for the app to upgrade it. Then run the Registration Wizard to see the new app on the Site Contents page as shown below:
  
  • • There is a known issue that the Trust it dialog displays the K2 blackpearl for SharePoint name rather than K2 Five for SharePoint name. The workaround to get the correct name to appear is to completely remove the app, rerun AppDeployment.exe to install K2 Five for SharePoint to the app catalog, and then adding, registering, deploying and activating. See KB001738 for steps on updating the app.
    • You must run the Registration wizard on each app catalog in your farm served by the K2 Five installation.
    • Troubleshooting tip: If you have followed the update steps above and cannot get the app updated, remove the existing K2 blackpearl for SharePoint app from the App Catalog by clicking the ellipsis and selecting Remove. After it's removed, add the K2 Five for SharePoint app to the App Catalog using AppDeployment.exe, and then register the app with your K2 server. You must also deploy and activate the app from the App Catalog using the links on the K2 for SharePoint Settings page. Your K2 artifacts are preserved using this method.
      
      
    • If you have installed K2 blackpearl for SharePoint from the SharePoint store, which is not recommended, you need to remove that app to upgrade to K2 Five for SharePoint.
    • If you integrate with SharePoint Online, you may see a version conflict message as described in Upgrading K2 for SharePoint App in SharePoint Online Fails (KB002090).
    • You may also see a Renew button when looking at the K2 for SharePoint app page, as shown here. To upgrade, completely remove the app from the app catalog and reinstall.
      
  • K2 Five includes the authorization framework in this release. By default, the Everyone role is given rights to K2 objects. This ensures that your K2 environment functions after upgrade as it currently does. For information on how to change security on K2 objects in K2 Five, read the Authorization Framework Overview topic to begin planning your security implementation.

  • From Nintex Automation (5.7) onwards there are two different apps for SharePoint. The legacy Nintex K2 for SharePoint: used for SharePoint on-premises and upgraded environments for SharePoint Online, and Nintex Automation for SharePoint: used on new installations for SharePoint Online.

    Microsoft has announced the deprecation of the SharePoint App Add-In Model, which is used to integrate the product with SharePoint Online.

    Note: The App Add-In model support only affects SharePoint Online. To continue using the product with SharePoint Online, you can now migrate your Nintex K2 for SharePoint solutions to Nintex Automation for SharePoint which supports SharePoint Framework (SPFx).

Deprecated Functionality and Components

K2 Five includes new and updated functionality. Please note the following features and components that are deprecated:

1. K2 Workspace is deprecated. The functionality that was available in the site is split between K2 Management (administrative tasks) and the new K2 Workspace (worklist and reporting). For more information see KB001769 - Comparison of capabilities between K2 Management Console and K2 Management Site. The Custom Event Notifications feature in prior versions is deprecated and is not available in K2 Five.
2. In K2 Five, MSMQ is replaced with an internal K2 queue called the Memory Queue.  The benefit of the new queue is that it stores data in the database and, in the event of a server crash, the data remains and continues to process when the server restarts. When upgrading to K2 Five, if there are messages in the MSMQ queue they are moved to the Memory Queue to be processed.
3. The SourceCode.Forms.Controls.Web.Shared.BaseControl namespace used when creating custom controls is replaced with SourceCode.Forms.Controls.Web.SDK.BaseControl. You must update any exiting custom controls with the new namespace."
4. The K2Api has been deprecated and should not be used for web service integration with K2. All existing custom code that makes use of the K2API must be updated to use the Workflow REST API.
5. In K2 Five, the ability to use a SmartObject method to populate a Role with users is deprecated. See KB002145 for more information.

Behavioral Changes

Please note the following behavioral changes that could affect your environment after upgrade:

•  K2 now enables strict MIME type checking which could affect custom controls and images. For more information see Considerations and best practices for Custom Controls.
• Set Control Properties Action: When using the Set a control's properties rule action and configuring the Expression property, the ellipsis is no longer present which means you cannot create a new expression from this location. You must create new expressions using the Layout step of the view or form designer. You can select existing expressions from the Context Browser tree or by typing the string representation of the GUID in the configuration of the Set a control's properties action.
  Backwards Compatibility: The expression is badged for any expression selected, via the ellipsis, that are not on the current view or form you're editing. Reconfigure the Set a control's properties rule action to resolve the dependency issue.
• Data transfer for SmartForms list controls is handled using JSON instead of XML, also includes custom list controls.
• Workflow Start rights: Changes have been made to how and who is automatically assigned Start rights in the workflow designers. Below is an explanation of how it worked in K2 4.7 and how rights are now assigned in K2 Five.
  In 4.7
  • When you deployed a K2 for SharePoint workflow, the people who were members of the Solution Participants group would automatically be assigned Start rights to the workflow and the person deploying the workflow was granted Admin rights.
  • When you deployed a K2 workflow from K2 Designer not from K2 for SharePoint, the K2 Service account was assigned Admin rights to the workflow so that it could be started as a Scheduled workflow.
  In K2 Five
  • When you deploy any workflow from K2 for SharePoint or K2 Designer, only the person deploying the workflow is granted Admin rights. Any additional Start/Admin/View rights need to be manually configured in the K2 Management Site.
  • The Solution Participants option on the configure permissions page in the K2 for SharePoint app only applies to workflows created in Workflow Designer (Legacy).
  • The deployment toast message (deployment successful message)  in the new Workflow Designer has a direct link to the K2 Management Site that indicates that you need to configure rights manually.
• The property OAuthResourceName in the ServiceConfigInfo.ServiceAuthenticationInfo class of the SourceCode.SmartObjects.Services.Management namespace has been changed to OAuthResourceID. The OAuthResourceName was previously used to identify the OAuth Resource, now use the OAuthResourceID to identify the OAuth Resource. If you have previously used this property in your code, you need to replace all instances of OAuthResourceName with OAuthResourceID.The OAuthResourceID can be retrieved via the OAuthManagement API. The following method will retrieve an OAuthResource object that will contain the OAuthResourceID:
  public OAuthResource GetOAuthResource(string resourceName)

Considerations

Please consider the following information when planning your upgrade:

• Differences: Read the Comparison of capabilities between K2 4.7 Workflow Designer and K2 Five Workflow Designer to understand what the differences are in your environment after upgrading.
• Package and Deployment: Read the Package and Deployment between K2 versions article that describes what can be deployed on your upgraded environment.
• Legacy Processes: When upgrading to K2 Five, a warning message is logged if the installer detects any K2.net 2003 processes in your environment. In a future release, the installer will block an upgrade if any K2.net 2003 processes are detected on the system. Contact your K2 Customer Account Manager for assistance with updating these legacy processes.
• Site Configuration: In K2 Five, all web properties and services (K2 Workspace, K2 Management, K2 Designer, SmartForms runtime) are grouped under K2 Sites in IIS. When upgrading your K2 4.7 environment, the installer preserves the existing configuration of your sites. When reconfiguring the environment after the upgrade, the existing configuration is also preserved. If you would rather have a single K2 Sites configured, select the new site option in the installer or create a new site within IIS and select it when installing.
• Formulas: In the Workflow Designer you can find the Formula expression inline function in the Mathematical node.
• SharePoint Recursive Search: Read KB002074 to see how a recursive search filter for SharePoint Lists and Libraries can be configured in the K2 Workflow Designer.
• K2 Five for SharePoint App, Multiple Versions:
  • Only one K2 Five for SharePoint app is allowed per app catalog. If you need multiple K2 servers/versions, you must have multiple app catalogs.
  • You cannot have a SharePoint farm served by a single app catalog and have different versions of K2 integrated with that SharePoint farm.
• Nintex Automation for SharePoint app:
  • ​​​​​From Nintex Automation (5.7) onwards there are two different apps for SharePoint. The legacy Nintex K2 for SharePoint: used for SharePoint on-premises and upgraded environments for SharePoint Online, and Nintex Automation for SharePoint: used on new installations for SharePoint Online.

    Microsoft has announced the deprecation of the SharePoint App Add-In Model, which is used to integrate the product with SharePoint Online.

    Note: The App Add-In model support only affects SharePoint Online

    To continue using the product with SharePoint Online, you can now migrate your Nintex K2 for SharePoint solutions to Nintex Automation for SharePoint which supports SharePoint Framework (SPFx).

• SmartForms Themes: In K2 Five the Lithium theme's background and tab text color has changed to a lighter color. After upgrading existing forms that use the Lithium theme and that have tabs, with a dark page background color set, will not be able to see the tab text due to the lighter color implementation. To resolve the issue edit the forms and remove the Page Color property. A blank Page Color property allows the theme to decide the background color.
  • After upgrade
    
     
  • Page Color property set to blank
    
     
• SmartObject Services Hosted Endpoints: If SmartObject Services endpoints are enabled prior to upgrading to K2 Five in the K2HostServer.exe.config, an error will occur in the K2 HostServer log files.
  The error message states ""114995","2017-10-17 09:20:38","Error","General","1","GeneralErrorMessage",
  "SourceCode.Endpoint.Server.EndpointServer.LoadSharedEndpoints","1 Category 'K2' not found.","","","DLX:C:Program Files (x86)K2 blackpearlHost ServerBin","114995","8e5798c3661246c0944e95dccc7e54c2",""...".
  Resolution: The error can be ignored as the K2 installer will resolve the error by restarting the K2 Server for a second time.
• Upgrading K2 blackpearl Only Installation: If you are upgrading from K2 4.7 and you only have K2 blackpearl installed (no SmartForms or SharePoint) you will be required to follow certain steps to get the full K2 Site, K2 Designers and Management sites installed and functional. If you receive a HTTP Error 404.0 - Not Found when trying to browse to one of the sites, be sure to follow the steps below to configure your K2 environment.
  Single Machine installation steps: Distributed installation steps (where K2 Server and K2 Workspace were previously installed on separate machines):
  1. Download the K2 Five RTM Installation Package.
  2. Extract on the system.
  3. Run the Setup.exe.
     • You will be prompted for the K2 Service Account password and a new K2 Five license Key.
     • Continue through the Setup Manager until it has completed.
     • Close the Setup Manager.
  4. Relaunch the K2 Setup Manager by double clicking the Setup.exe again.
     • Choose the "CONFIGURE" option.
     • Click NEXT until the Web Site Configuration Panel is reached.
     • Ensure the Selected web site was the previous K2 Workspace site and click NEXT.
     • Ensure the selected K2 Application Pool is correct, Click NEXT.
     • Continue through the Setup Manager until it has completed.
  5. Three newly configured K2 Sites are available, namely:
     1. K2 Designer
     2. K2 Workspace
     3. K2 Management
  6. 1. Download the K2 Five RTM Installation Package.
     2. Extract onto K2 Server machine and ensure it is upgraded first.
     3. Extract onto K2 Workspace Machine.
     4. Run the Setup.exe.
        • You will be prompted for the K2 Service Account password and a new K2 Five license key.
        • Continue through the Setup Manager until it has completed.
        • Close the Setup Manager.
     5. Relaunch the K2 Setup Manager by double clicking the Setup.exe again.
        • Choose the "CONFIGURE" option.
        • Click NEXT until the Web Site Configuration Panel is reached.
        • Ensure the Selected web site is the previous K2 Workspace site and click NEXT.
        • Ensure the selected K2 Application Pool is correct, Click NEXT.
        • Continue through the Setup Manager until it has completed.
     6. Three newly configured K2 Sites are available, namely:
        1. K2 Designer
        2. K2 Workspace
        3. K2 Management

FAQ

Upgrading

Q: Can I upgrade my K2 Five RC environment to K2 Five RTM?
A: Yes the K2 Five Public RC is upgradable to K2 Five RTM.

Q: Will my upgraded workflows continue to be supported?
A: Yes, except for K2.net 2003 workflows. The K2 blackpearl designers themselves (K2 Studio and K2 Designer for Visual Studio) remain in place but are no longer eligible for code fixes but you can still use them to maintain existing workflows and design new ones. However, any issues you find in the designers or the workflow wizards that are only available in those designers will no longer receive code fixes. It is recommended to rebuild your workflows using the new Workflow Designer in K2 Five.

Q: Once I've upgraded to K2 Five, if I want to build a new server or add one to the farm, how do I get the 4.7 features enabled that are not installed with K2 Five?
A: If you want features that are not available in a new install, you must first install 4.7 and then upgrade. Keep in mind that the deprecated designers are features in 4.7 and earlier, so you must install it first to get those features. If you have 4.7 and want to maintain and use SharePoint 2010 integration, you must first install 4.6.x to get that feature enabled, and then you can do an upgrade. Also keep in mind that you cannot upgrade to K2 Five and keep your SharePoint 2010 integration. If you are on SharePoint 2010 you must remain on K2 blackpearl 4.7. 

Q: So if I have a new developer who is setting up his or her machine and needs K2 for Visual Studio to support legacy workflows built on 4.7, what do they need to install?
A: They must first install and configure K2 4.7 to get the Visual Studio Designer on their machine. Then they can upgrade to K2 Five.

Q: What about a new K2 connect developer who is setting up his or her machine and needs Visual Studio to design SAP service instances, what do they need to install?
A: They must first install K2 4.7 to get the Visual Studio Designer on their machine. Then they can upgrade to K2 Five and then install K2 connect 5.0.

Q: What if my SharePoint environment is still on SharePoint 2010?
A: Go back to your workflows and forms, remove all SharePoint 2010 integration points, uninstall the K2 for SharePoint 2010 component on K2 4.7, and then upgrade to K2 Five. This means that if you cannot do this, you must remain on K2 4.7.

Q: What if my environment has the K2 Language Pack (Preview) installed?
A: Upgrade your environment to K2 Five then install the K2 Language Pack (Preview) (5.0001.0000.0). The install will identify what langauge is installed and will make an update to the translations.
 

Designing Workflows

Q: If I upgrade to K2 Five, will I be able to edit or create new v4-based workflows using the 4.7 designers?
A: Yes.

Q: If I upgrade to K2 Five, will my 4.7 based workflows continue to work?
A: Yes, except for K2.net 2003 workflows.  All workflows continue to run and new instances can be started. You can maintain those 4.7 based workflows using the 4.7 designers and the workflows are supported.

Q: If I upgrade to K2 Five, will I be able to open 4.7-based workflows in the new v5-based workflow designer?
A: No. You can open 4.7-based workflows in the designer in which they were built,  i.e. K2 Studio, K2 for Visual Studio, or K2 Workflow Designer (Silverlight)

Q: Can I import or migrate my 4.7-based workflows to the new K2 Five workflow designer?
A: No. You must use the designer in which you created the workflows to maintain them.
 
Q: Are there any updates to the 4.7 based designers?
A: No.  If you upgrade to K2 Five, K2 Studio and K2 for Visual Studio remain installed and are supported for bug fixes, but no new features have been added.

Q: If I perform a clean install of K2 Five, will it install any of the 4.7 K2 Designers? (K2 Studio, K2 for Visual Studio or K2 Workflow Designer (Silverlight))?
A: No. You must first install K2 blackpearl 4.7 and then upgrade to K2 Five.