If you are upgrading from a different type of environment or want to learn more, see K2 for SharePoint Upgrades (KB001793).
If you are upgrading from K2 blackpearl 4.7 to K2 Five, see Upgrading to K2 Five

Introduction

When your K2 environment is upgraded to a newer version of K2, you need to update the K2 for SharePoint in your SharePoint App Catalog. This is because the App may have been updated to cater for changes introduced by the newer version of K2. If you do not update the K2 for SharePoint App, you may encounter errors when trying to use K2 integration because the app version does not match the underlying K2 environment version. Use the information in this article to learn about these potential errors and for instructions on how to update the K2 for SharePoint app.

This article is divided into the following sections:

Typical Errors

If you do not upgrade your K2 for SharePoint App when your K2 environment is upgraded, you may see the following errors:

  • Error: Trying to browse to the K2 settings page of a list or library results in an error like:
    Thread 1: K2 for SharePoint must be configured from the App Catalog. See http://k2.com/help/K2ForSharePoint/register/newversion for more information. If you have multiple K2 for SharePoint apps installed, keep the shared version only

    Image

  • Error: Trying to use the Registration Wizard on the app catalog results in an error like:
    A newer version of the K2 for SharePoint App is available. See http://help.k2.com/en/KB001610.aspx for more information

    Image

  • Other Errors: You may see other errors relating to the version of your K2 for SharePoint app not being in sync with the server. If you see these errors, contact your K2 administrator to determine if your K2 environment was recently upgraded. If so, follow the steps in this article to update your K2 for SharePoint app

Updating the K2 for SharePoint App

You can follow these high-level steps to update the K2 for SharePoint App in the app catalog. For more information and specific steps to deploy the app, see the product documentation for K2 for SharePoint

  1. Add the new version of the K2 for SharePoint App on your App Catalog Site using the Apps for SharePoint list. If there is an existing K2 for SharePoint App in the app catalog, you must replace the existing version with the new version, do not delete the existing version of the app. You grant K2 for SharePoint permissions during this step, and it requires Global Admin (Tenant) permissions, so you must be a Global Admin.
  2. Add the K2 for SharePoint app to your app catalog. You grant K2 for SharePoint permissions during this step, and it requires Global Admin (Tenant) permissions, so you must be a Global Admin.
  3. On the Site Contents page of the app catalog, 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.)
  4. Click the K2 for SharePoint app from the Site Contents page or Quick Launch menu of the app catalog site, and run through the Registration Wizard by clicking the Registration Wizard link in the Administration section to register the app with your K2 environment's URL. (If you do not see the Registration wizard, make sure you are on the app catalog.).
    If you see the error message "A newer version of the K2 for SharePoint App is available" during this step, see Troubleshooting below to resolve the error.
  5. Deploy the app to one or more site collections using the Manage App Deployments page in SharePoint. A link to this page is provided on the K2 for SharePoint settings page. It is recommended you do this by paths rather than individual URLs, but individual URLs give you more control regarding which site collections have K2 integration. You should deploy as a SharePoint Administrator if you are deploying to multiple site collections.
  6. Activate the app to every site collection using the Manage App Activations page. A link to this page is provided on the K2 for SharePoint settings page. This page activates to every subsite in the site collection, so point it to the root site of the site collection. You need Site Collection Administrator permissions on each site collection you're activating, and you can activate from the app catalog or from each site collection individually as long as you have the permissions.
  7. Start using K2 for SharePoint to modify existing solutions or create new ones.

Appendix

There are some differences when you upgrade to a version of K2 that requires the K2 for SharePoint app to be deployed from the app catalog. Keep these in mind as many of the benefits of an app catalog-registerd app make the maintenance and management of K2 integration easier, especially in site provisioning scenarios.

All sites in the site collection that K2 is integrated with, get K2 integration. Before K2 blackpearl 4.7, you had to add the app to each subsite in the site collection. If you did not add the app, the site did not have K2 integration. As of K2 4.7, all sites in the site collection get K2 integration. If you add sites at a later point, you must activate to the site collection again, where it picks up the changes and activates to new subsites only.

  1. Due to the K2 app being deployed to all sites in a site collection, there is no longer support for having multiple K2 servers associated to different subsites in a single site collection. The upgrade preserves ties to multiple K2 servers but you will have to activate them separately. See Working with Multiple K2 Servers for more information.
  2. The K2 for SharePoint settings page, which is what you see when you click on the app in SharePoint, may look different depending on if you're browsing the app catalog or a regular site. The app catalog has links to the Manage App Deployments and Manage App Activations pages, as pictured below. The settings page at the site level does not have these links.
  3. You do not have the ability to integrate lists and libraries in the app catalog with K2.
  4. App parts are now web parts due to the change in how the K2 for SharePoint app is built. K2 for SharePoint is now a tenant-scoped app, and these types of apps cannot contain add-in parts (app parts) as described by Microsoft. The way in which you add the K2 Worklist and the K2 SmartForms Viewer web parts to a page in SharePoint is the same, but you will no longer find them in the App Part list but instead in the Web Part list.
  5. If you have external users that use your SharePoint sites, you must enable sharing on the app catalog and share the app catalog site with external users before they can participate in workflows. In the past you had to do this on every site collection.

Image
Figure 1
: The administration links on the settings page in the app catalog. You will not see these links on the site's settings page.

When you are upgraded to K2 4.7 and have solutions built on the older version, do not uninstall the version of the app from each site before upgrading. Activating from the app catalog to a site collection removes the site-deployed app (that used the older method of app integration). For more information about what deployment and actvation do, see K2 for SharePoint Deployment and Activation

Once the app is installed, registered, deployed and activated to a site, when you browse to a list or library that has been previously integrated with K2, and you go into the K2 artifacts page, you may notice that SmartObjects need to be resynchronized. This is the same behavior as previous versions and includes the same warning: If you customized your forms based on your SmartObjects, do not regenerate your forms and views, only regenerate your SmartObjects. You should not need to manually update your forms or views unless you made some structural changes to the list or library.

App Parts now Web Parts

If you have existing pages that use the K2 app parts, such as the K2 Worklist and the SmartForms Viewer, these pages must be updated to instead use the K2 web parts. When you edit the page, click the Web Parts button in the ribbon and scroll down until you see K2. Select that category and you see the K2 Worklist web part and the K2 SmartForms Viewer web part. Add these to where you originally had the app parts on the page, configuring them as you normally would.

If The activation of the app to a site collection removes the older version of the app, and along with it the app parts associated with it. Your pages that included the K2 Worklist or K2 SmartForms Viewer app parts will not function until you manually reconfigure them with web parts.

Working with Multiple K2 Servers

When you have multiple K2 servers, you may want to integrate some sites with one K2 server and other sites with a different K2 server. This allows you to simulate different environments on a single SharePoint farm or tenancy. See Integrating K2 for SharePoint with Multiple K2 Servers for more information.

Use this section if you run into problems or error messages while installing and configuring K2 for SharePoint.

Error Message 1: A newer version is available (dialog popup)

If you have not installed the latest version of the app on the site, and you click on the K2 for SharePoint app, you see the following error message:

A newer version of the K2 for SharePoint App is available. Contact your administrator to register the K2 for SharePoint App on this site. After that has been done, you can create new K2 artifacts or synchronize existing ones. See http://help.k2.com/en/KB001661 for more information

Image
Figure 2: The error message stating there's a new version of the app available.

To correct this error message, you must install, register, deploy and activate the K2 for SharePoint app from the App Catalog, and not once per site like KB001661 states.

Error Message 2: K2 for SharePoint must be configured from the App Catalog.

The following error message is shown if you try to register the app from a regular site instead of on the app catalog: 

K2 for SharePoint must be configured from the App Catalog. See KB001738 for more information. If you have multiple K2 Appit for SharePoint apps installed, keep the shared version only.

Image
Figure 3: The error message when you have added the app directly to a site instead of activating it from the app catalog.

To correct this error message, you must install, register, deploy and activate the K2 for SharePoint app from the app catalog, and not once per site like KB001661 states.

Duplicate Ribbon Buttons and Duplicate Apps

If you find that you have duplicate ribbon buttons in a list or library, as shown in Figure 4, you have activated the K2 for SharePoint app from the app catalog as well as deployed it directly on the site. This also means that you will see two K2 for SharePoint apps on the Site Contents page, as shown in Figure 5. Remove the app that does NOT have the (shared) tag. The one with the (shared) tag is the one activated from the app catalog.

Image
Figure 4: Duplicate Ribbon Buttons in a List or Library

Image

Figure 5: Duplicate K2 for SharePoint Apps

Beginning with K2 for SharePoint 4.7, the way in which you deploy K2 for SharePoint is enhanced and different from previous versions. As of these versions, the K2 for SharePoint app must first be added and registered in the SharePoint app catalog. From that point forward, the app is deployed and activated to the site collections serviced by that app catalog.

The table below highlights the main differences between the new app catalog approach introduced in K2 for SharePoint 4.7 and previous versions. 

Prior to K2 for SharePoint 4.7 K2 for SharePoint 4.7 and later
K2 for SharePoint added on each site K2 for SharePoint added on the app catalog
K2 for SharePoint registered once per site, including every subsite K2 for SharePoint registered once on the app catalog, then deployed and activated to every site collection
One service broker instance per site collection One service broker instance per site collection
K2 Worklist and Form Viewer App Parts K2 Worklist and Page Viewer Web Parts (requires manual reconfiguration)