Using the K2 Environment Switcher App

KB003109

When using K2 for SharePoint with multiple K2 servers, you may ask yourself how to:

• use different versions of K2 on the same SharePoint environment/app catalog
• use multiple K2 servers on the same SharePoint environment/app catalog
• switch to a different K2 environment without running the Registration Wizard as a SharePoint farm or tenant administrator
• switch to a different K2 environment prior to managing app activations to a new site collection
• activate a new site collection using a specific K2 server
• design K2 artifacts using different K2 servers

Use the K2 Environment Switcher app in scenarios where you have multiple K2 environments, running the same or different versions of K2, and where they all use the same SharePoint app catalog. Typically, the K2 server with which you last registered the K2 for SharePoint app is the active server and is used for registering new site collections for K2 integration and for designing K2 artifacts. You can use the K2 Environment Switcher app in the app catalog to set the active K2 server without needing to run the Registration Wizard.

Necessary permissions to run the app on the app catalog

To use the K2 Environment Switcher app, you must be a Site Collection Administrator or a member of the Site Owners group on the app catalog.

How to use the K2 Environment Switcher app

Follow the steps below to use the K2 Environment Switcher app to change the active K2 server for activating new site collections or designing artifacts (appifying and maintaining K2 items in SharePoint lists and libraries):

1. Download and unzip the K2 Environment Switcher app located at the bottom of this article. 
2. Open your SharePoint app catalog site and click Apps for SharePoint.
   
3. On the Apps for SharePoint page click New.
   
4. On the Add a document dialog, upload the K2 Environment Switcher.app file from the location you saved it and click OK. The K2 Environment Switcher app is added to the Apps for SharePoint page.
   
5. Open the Site Contents page of the app catalog and click add an app.
   
6. On the Site Contents >  Your Apps page select the K2 Environment Switcher App.
   
7. Click Trust It on the Do you trust K2 Environment Switcher? dialog.
   
8. On the Site Contents page click the K2 Environment Switcher app.
   
9. On the K2 Environment  Switcher page, an Environment List is displayed if you have the necessary permissions on the app catalog. The Environment List displays all K2 servers with which the K2 for SharePoint app is registered. The last K2 server registered is the default K2 server for the SharePoint environment. In this example, the K2 server called docs.denallix.com (a K2 Five on-premises server) is active. This means that all new site collections activated with K2 for SharePoint use this K2 server. 
   
10. When you want to activate a new site collection to a different K2 server, you could run the Registration Wizard to switch the active server. However, the Registration Wizard requires that you log in as a SharePoint farm or tenant administrator. Using the K2 Environment Switcher to change the active server only requires that you are a Site Collection Administrator on the app catalog, or that you are a member of the Site Owners group. In this example, you want the CloudKUID.onk2.com (a K2 Cloud tenant) to be the active K2 server. You select it from the Environment List and click Manage App Activations.
    
11. On the Manage App Activations page, the K2 Cloud server details are populated automatically. Add the URL of a newly-created site collection in the Site Collections section and click Activate.
    Make sure to uncheck the Enable auto-activation on sites where the app is deployed option on this page. See Considerations for more information.
    
    
12. On the Activate Site Collection page, because the site collection URL being activated needs a K2 Cloud tenant, you must create a token. Click click here on the Please log in page. This step is different when activating a site collection using an on-premises K2 server.
    
13. Click Close on the Activate Site Collection page. The activated site collection is activated using the K2 Cloud tenant. 
    
14. To activate another site collection, for example against a K2 Five on-premises server, run the K2 Environment Switcher app again, select the K2 on-premises server, and activate the new site collection. After a site collection is activated, you cannot switch its K2 server without removing the K2 integration from the site collection, deleting the K2 artifacts, and then reactivating the site collection using the different K2 server.

Considerations

Keep in mind the following considerations when using the K2 Environment Switcher app:

• Once you activate a site collection, runtime components use the K2 server value in a hidden list on the site collection, not on the app catalog.
• However, design-time components use the K2 server value on the app catalog, which means that to create or edit K2 artifacts in a SharePoint list or library using the SharePoint ribbon, you must switch the active K2 server to the one associated with the site collection on which you're creating or editing artifacts. If you edit existing artifacts directly in the K2 Designer, you do not have to switch the active server.

• You cannot switch an already-activated site collection to use a different server. In this case, you need to remove the K2 integration from the site collection, delete your artifacts, and then reactivate with a different server to ‘switch’ the K2 server for an existing, K2-integrated site collection.
• When you need to use multiple K2 servers with the same SharePoint app catalog, you should not deploy the K2 for SharePoint app using the Managed Paths - (All Paths) option on the Manage App Deployments page. You can either deploy the app to the root sites of each site collection or use separate managed paths to logically divide your SharePoint site collections based on each K2 server. If you only use SharePoint on-premises, the recommended way of handling multiple K2 servers and/or versions is to create separate app catalogs. SharePoint Online is limited to a single app catalog.
• Uncheck the Enable auto-activation on sites where the app is deployed option on the Manage App Activations page to stop K2 from trying to auto-activate with potentially the wrong K2 server or environment.
• The servers you see in the Environment List represent servers with which you've registered the K2 for SharePoint app. If you need to add a server to this list, run the Registration Wizard using the new K2 server's URL. After the K2 for SharePoint app is registered with the new K2 server, the new server appears in the Environment List in the K2 Environment Switcher app.
• You must keep track of the version for each K2 server you have as the Environment List does not contain this information.
• If you are not a member of the Site Owners or Site Collection Administrators groups, the following error displays when using the K2 Environment Switcher.
  You must be a member of the Site Owners or Site Collection Administrators to use this application
  
• You must add and use the K2 Environment Switcher app on the app catalog, not on each site collection. If you do try to use the app on a site collection, you see the following message:
  List 'K2S Tracking' does not exist at site with URL "tServerURL]".