K2 for SharePoint App Registration and Activation

Once K2 is installed, if the Setup Manager detects any SharePoint app catalogs, you are given the option to deploy the K2 Five for SharePoint App to the App Catalog by checking the check box on the Finished page.
You can also run AppDeployment.exe from the setup folder ("%ProgramFiles%\K2\Setup") to start the App deployment Wizard.

Installation steps

1. After reading the App Deployment Welcome page and choosing whether or not you want to analyze the SharePoint configuration, click Next.
2. On the K2 Server page, enter a K2 URL and click Next to continue. An example of a K2 server URL is: https://k2.denallix.com. You can use the Test button to check the connection to the server.
3. Before App deployment, if you chose to analyze the SharePoint configuration, the App Deployment Health Check shows a green tick for items that passed the check, a red cross for failures, a blue i for information, and a yellow exclamation point for a warning. You can export the results as a text file using the Export button. Selecting an item shows the results for that item in the right panel with additional information. Click Next to continue.
   If you chose not to analyze the SharePoint configuration, neither the pre- or post- health check is shown.
4. Check the applicable Web Applications (or select all) that you want to deploy the App to, and then click Next.
5. After the app is deployed, the App Deployment Health Check runs again (as mentioned, only if you chose to analyze the SharePoint configuration).
6. When the Finished window appears, click the Finish button to complete the installation.

Upgrade Steps

If you are upgrading from K2 blackpearl 4.7, and you have a single app catalog serving your different K2 environments, you must take care when deploying the K2 Five for SharePoint app.

1. The best practice recommendation is to have a separate and discreet K2 server for each environment, for example DEV and PROD, and a separate and discreet SharePoint Web App/App Catalog for each environment.
2. The second-best approach is to have a separate and discreet K2 server for each environment, and separate site collections in SharePoint for each of those environments. This means that you have one app catalog that serves different K2 servers of potentially different versions.
3. When you upgrade your first K2 environment (DEV) from 4.7, you deploy the K2 Five version of K2 for SharePoint to the app catalog. At this point you can do your testing to make sure your solutions still function as expected in DEV. However, you lose the ability in your other environment (PROD) and may get errors when you try to create new solutions, edit existing solutions, make structural changes to your PROD SharePoint site collection, etc., but existing PROD solutions continue to function.
4. If you need to go back to the 4.7 version of the app in your PROD environment before you’re ready to upgrade PROD to K2 Five, you can run the Registration Wizard from the app catalog using the PROD server URL. This sets the K2 for SharePoint app (the K2 Five version) to run as if it’s the K2 4.7 version of the app. This causes you to lose the ability in your DEV environment to create new solutions, edit existing solutions, make structural changes to your DEV SharePoint site collection, etc., but existing solutions in DEV continue to function.
5. When you need to go back to DEV to continue testing, you run the Registration Wizard from the app catalog using the DEV server URL, and the app in the app catalog is set to run as the K2 Five version.
6. This switching back and forth of the app’s functional version from K2 Five to K2 4.7 was designed to work this way to support upgrades from K2 blackpearl 4.7 to K2 Five.
7. If the app doesn’t seem to switch after running the Registration Wizard, run App Activation from the site collection.

App Deployment Health Check

If the Analyze SharePoint Configuration before looking for app catalogs check box on the Welcome page is selected, the App Deployment installer proceeds with the pre- and post-deployment health checks for on-premises installs and upgrades. The health check verifies that the settings required by the K2 for SharePoint App are correctly configured in a SharePoint on-premises environment. If the check box is not checked, the installer attempts to deploy the app without performing the health check. If no errors are encountered, you may continue. If errors are encountered, the health check should be run by starting the App Deployment wizard again and selecting the check box.

The following checks are performed:

Pre-deployment Health Check
Check	Description
Execution User Required Permissions for Configuration Analysis Tasks	A bullet list of permissions required to run these checks and upload the app to an app catalog.
Verify the App Catalogs and Permissions	Iterates all web applications and searches for App Catalog site collections, checks that the user has Contribute permissions, and SPShellAdmin Access to the web app’s database.
Subscription Settings Service Application is available	Check if the Subscription Settings Service Application is provisioned on the Farm and the related service is running.
App Management Service Application	Check if the App management Service Application is provisioned on the Farm and the related service is running.
User Profile Tasks User Profile Service Application Query User Profile Service User Profile Sync Connection Task	Check if the User Profile Service Application is provisioned on the Farm and the related service is running. Enumerates the User Profile service, produces the user count for each authentication mode found. Check that User Profile Synchronization is possible.
App Domain Tasks SharePoint App Domain SharePoint App Site Subscription Name Ping SharePoint App Domain	Test if the app domain has been set – this can be manually set in Central admin > Apps > Configure App URLS but only if subscription settings and app management services are provisioned and running. Test if the app prefix for the app domain has been set – this can be manually set in Central admin > Apps > Configure App URLS but only if subscription settings and app management services are provisioned and running. Executes a Test-Connection call to the app domain URL; pings the URL
SharePoint Windows Services SharePoint Timer Service	Checks that the SharePoint Timer Service is running.
Post-deployment Health Check
Check	Description
Server to server High Trust Verifies Root Authority Verifies Security Token Issuer Verifies K2 OAuth High Trust for SharePoint Farm	Ensures the High trust certificate used to setup the ‘K2 for SharePoint App’ and SharePoint Server to Server communication is trusted by SharePoint. Ensures the Security Token Service issuer is set for the ‘K2 for SharePoint App’. Compares the High trust certificate thumbprints from the Root Authority mapping and Security token issuer mapping match. They need to match or Server to Server communication will fail.
Metadata and OAuth Exchange over HTTP	Checks that OAuth exchange and Metadata exchange over HTTP is enabled if any site collections are running (non-SSL) Microsoft recommends SSL and so you need to set it explicitly.
Kerberos authentication and the new SharePoint app model	Warns users running Kerberos to ensure NTLM fallback is enabled, there is no actual script execution – it’s just a note you need to be aware of.
Upload Test App	Attempts to Install a Test App to the each of the selected web application’s root site collections' root web sites from the previous page (where you selected the app catalogs); then tries to download the page; and then uninstalls it. The Upload Test App will stop trying to execute after two minutes as this is a very time consuming task.

Additional Notes

All scripts are output to [extractionDirectory]\Configuration Analysis Scripts.
For example: C:\Users\Administrator\Desktop\K2 Five\Installation\Configuration Analysis Scripts\

If any of the checks fail you must fix the configuration before continuing with the app deployment. It is recommended that you read the notes for each setting to understand what needs to be configured. The health check is there to notify you if your environment’s configuration is correct or if further configuration is required. For more information see the online KB article: SharePoint 2013 Health Check and App Deployment Script.

The K2 for SharePoint app is available from the SharePoint Store, however you should use the app that's included with the version that you're installing. Manually add the app from your Setup Manager install folder. See the topic Manually Adding the K2 for SharePoint App to the App Catalog for more detail.

The K2 for SharePoint app must be registered with the K2 Server. For configuration details see the section below: Adding the app to the App Catalog.

Additional Configuration

• The URL for the remote event receiver must be publicly accessible.
  SharePoint Online requires SSL to be enabled on your system.
• Custom Scripting capabilities are off by default for personal sites and self-service created sites and you may encounter errors when the registration wizard uploads pages to SharePoint. See KB001711 - SharePoint Online Root Site Collection Document Library ASPX upload issue and the Microsoft article: Turn scripting capabilities on and off for more information.

The K2 for SharePoint App is deployed to the SharePoint App Catalog by the K2 Setup Manager or by using the AppDeployment.exe found in the setup folder after K2 installation.

Once the app has been deployed to the app catalog (step 4 in the Installation Steps listed above), the app is available to be added to the app catalog's Site Contents page by selecting add an app and selecting the K2 Five for SharePoint app. Click Trust it when you see the prompt and then continue.

The next step is to register the K2 Five for SharePoint app in the app catalog.

Follow these steps to register the K2 Five for SharePoint app in the app catalog:

1. In the Site Contents of the app catalog, click the K2 Five for SharePoint app.
2. On the App Catalog > K2 for SharePoint page, click the Registration Wizard link in the Administration section.
   
3. On the Portal Apps > K2 for SharePoint > Settings > Registration Wizard page, enter a K2 URL and click Next.
   
4. The Registration Wizard runs. Click Finish once complete.
   

The next step is to deploy the app to required site collections.

Follow the steps below to deploy the app to the site collections:

1. On the Portal Apps > K2 for SharePoint page, click the Manage App Deployments (SharePoint) link.
   
2. The Manage App Deployments > K2 for SharePoint page opens. On the Manage App Deployments page, there are two methods to deploy the app to the required site collections. Firstly via the Site Collections section where site collections can be individually specified and secondly via the Managed Paths section, where all site collections can be specified via the (All Paths) option. The second method is recommended unless you need to control which site collections serviced by the app catalog are integrated with K2. Use step 3 for using individual site collections and step 4 for using paths.
3. In the Site Collections section, add the required site collections and click the Add button.
   
   Multiple site collections can be added at once, if required.
   
   
4. In the Managed Paths section, select the (All Paths) option and click Add. This deploys the app to all site collections and associated subsites that reside in the farm (All Paths), or under a valid path, such as sites. This is the more efficient and recommended way to accomplish K2 integration with SharePoint than step 3 where you specify site collections individually.
   
5. Click OK.
6. Click the Trust It button on the Do you trust K2 for SharePoint screen.

The last step is to activate the app.

Use Manage App Activations to set your default K2 server, activate K2 to site collections served by the app catalog, and see which site collections are activated. Follow these steps to activate the K2 for SharePoint app:

1. On the Site Contents page, click on the K2 for SharePoint app.
2. Click the Manage App Activations link on the App Catalog > K2 for SharePoint page.
   
3. On the K2 for SharePoint > Settings > Manage App Activations page, set the default K2 Server and specify the required site collections for activation. On the Manage App Activations page, select or deselect the Enable auto-activation on sites where the app is deployed check box, the check is selected by default. If the Enable auto-activation on sites where the app is deployed check box is deselected, you must activate the app from this page though the app appears on each site collection where the app is deployed. Click the Save button then specify the site collection, then click the Activate button.
   
4. The Activate Site Collection page opens and the specified site collection is activated. Notice that the site collection and all subsites now have the activated app.
   
   
   At activation time, all existing subsites in the site collection are activated with K2 for SharePoint. New subsites that are added at a later point, either manually or via a K2 workflow, are also activated with K2 for SharePoint through remote event receivers as long as the auto-activation setting is turned on. This automatic activation may take a few minutes depending on your SharePoint environment. SharePoint Online instances do NOT include the remote event receiver, and hence do not get K2 for SharePoint automatically added to new subsites. For SharePoint Online you must reactivate the site collection using the Manage App Activations page, which finds the new subsites and only activates those.
5. When activating a site collection which contains a high number of subsites (50+), the activation may fail. To correct this issue click the Retry button on the Activate Site Collection page.
   
6. Multiple site collections can be activated all at once if required, simply repeat the above steps on the Manage App Activations page.
   
   Ensure that if multiple site collections are required for activation, the app is deployed via the Manage App Deployments page first. For more information see KB001755 - K2 for SharePoint Deployment and Activation.
7. Click the Close button on the Activate Site Collection page.
8. Click the Close button Manage App Activations page.