Deploying A Package

Once the package (.kspx file) has been created, you can use the Deploy Package function to deploy the package to the target K2 environment.

K2 Package and Deployment uses the Secure Hash Algorithm 1 (SHA-1) protocol to determine whether artifacts on the target server are an exact match for artifacts in the package. When matches are found, the packaged artifact is not deployed. If an exact match is not found, the artifact from the package is deployed as a new version, or overwrites the artifact on the target server (depending on whether the artifact is versioned).

Setting the Default Target Environment

When a K2 Package is deployed, it is deployed to the current default environment on the target server. The default target environment can be set within K2 Workspace, as in the screenshot below:

1. Launch K2 Workspace on the target server. Open the Management Console.
2. Use the server tree to navigate to Environment settings ([Target server] / Environment Library / Templates / Default Template / Environments.)
3. The current default environment will be listed as True under the work space Default column. If you need to change the default environment, use the available radio buttons to select the new default environment from the list of available environments.
4. Refer to the Templates - Environments section of the K2 blackpearl User Guide for more information about creating and editing K2 Environment settings.

Default environment string tables

The String Tables of the default environment will be used to provide the environment settings used during deployment of the package. For further help and information on this topic, refer to the K2 Environment Library White Paper.

To Deploy a K2 Deployment Package

1. Select Deploy Package from the Microsoft Management Console (MMC) window.
2. Use the Browse button to locate and load the K2 Deployment Package into the Select Package dialog screen. (Note that the file path in the screen shot is for demonstration purposes only.)
   

   Partial Analysis Pre-K2 blackpearl 4.6.9

   Partial analysis should only be used in cases where you are 100% confident that what is included in the package will function on the target environment. The package should be analyzed on the target environment with full analysis to see whether any issues exist before the intended deployment date. This way any problems can be investigated and resolved before deployment. If all issues have been resolved -- including missing references -- Partial Analysis can be used on the day of deployment to bypass the analysis step in order to speed up the deployment process.

   The P&D tool does not verify solution validity once deployed, so using Partial Analysis in a scenario like this might work but you run the risk of ending up in an unrecoverable state on your target (live) environment.

   Partial Analysis K2 blackpearl 4.6.9 and Later

   In 4.6.9 validation was added during the packaging process. This stops you from creating a package that cannot be deployed. You are warned when artifacts that are dependent on other artifacts may not exist. An example of this is where a property or method has been removed from a SmartObject which is referenced in a View or Workflow.

   With 4.6.10, validation messaging has been improved. This allows you to more easily find and address problems in the package. This enhanced messaging is available as a cold fix for 4.6.9.

   Catching items at the time of packaging is only a partial solution. K2 is working to include most of the validation that you see in P&D 4.6.10 into the various parts of the platform responsible for artifact inter-dependencies, so you will start seeing validation messages when, for example, you try to deploy a workflow that uses a SmartObject property that no longer exists. In this scenario you will know immediately that there's a dependency problem.Partial

3. Packaged Items radio buttons:
   • Select the Automatically select all items option if all items in the current deployment package should be deployed. When Next is clicked in the Select Package window, all items within the deployment package will be selected by default.
   • Select the Manually select specific items option if only some items within the current package should be deployed. After clicking Next, individually select the artifacts to be packaged.
4. Analyze radio buttons:
   • The analysis function compares the artifacts on the server (if they exist) with the artifacts in the K2 package. If any items to be deployed contain content which differs from existing items, the analysis function offers the option to replace the existing artifacts and dependencies with current versions.
   • Select the Full option to analyze all artifacts, as well as all dependencies in the dependency chain, for the selected artifacts.
   • Select the Partial option to analyze all artifacts without analyzing the dependencies comprising the artifacts.
   • Enable the Automatically re-analyze after each change option if needed. For large packages we recommend that this option remains disabled.
5. The Continue deploying packaged items if one or more items cannot be deployed check box is checked by default.
   • Deselecting the check box will halt the deployment entirely if any artifacts cannot be found, or are incompatible with the current deployment.
   • Selecting the check box will halt the deployment of individual artifacts if the relevant artifacts cannot be found or are incompatible with the current deployment. Package and Deployment will continue to deploy all artifacts which are not in conflict with the target environment.
6. The Remember my settings check box is checked by default. This allows K2 Package and Deployment to remember which package-selection options have been specified for the current package, and apply the options to future package deployments. Should different selection options be needed for future package deployments, deselect the check box.
7. Click Next. The Deploy Package window will open. If variables must be assigned at this point, see Assigning Variables for more details.
   
8. Check that all needed artifacts and dependencies have been checked for inclusion in the deployment package. The total number of items to be deployed appears in the lower left corner of the window.
9. All conflicts must be resolved before the package can be deployed to the new environment. If a conflict cannot be resolved, the artifact or dependency causing the conflict must be de-selected. See Conflict Resolution for more details. Once all conflicts have been resolved, run the Analyze option to update the tool's internal status check.
10. Click Next. K2 Package and Deployment will interrogate both the K2 artifact definitions and the K2 environment to be deployed to.
11. The Deploy Package – Deploying window will appear. This is a list of the packaged items and their readiness status. The time taken to deploy the package’s artifacts and dependencies will be shown in the right-hand column once deployment is complete. Where a status icon to the left side of a deployed item shows a green check mark, the item has been successfully deployed.
    
    

    Deployment times may vary depending on the size of packages to be deployed. To avoid inconvenience, it is recommended that large packages are deployed only after regular working hours.

12. If an artifact fails to deploy due to circumstances beyond K2 Package and Deployment's control, a red exclamation mark will be displayed next to the artifact that fails to deploy:
    
13. If such a deployment failure occurs, double-click on the artifact responsible to view an explanation for the failure:
    
    
14. When the reason for the deployment failure has been rectified, click on the Retry or Retry All link next to the relevant artifact or dependency to re-attempt deployment.

    If the K2 Server has been rebooted since the deployment of the package, using the Retry option will not work.

15. If a deployment log needs to be created and saved, click the Save Log button. The Save As window will open, allowing you to re-name and save the log file.
16. Close the Deploy Package – Deploying window. This will conclude the deployment process.

Deployment of Microsoft SharePoint Event Processes

K2 Package and Deployment supports SharePoint events created using K2 Studio, K2 for Visual Studio and K2 Designer. However, it does not support SharePoint Workflow-integrated artifacts.

For a complete list of which SharePoint artifacts are or are not included, refer to the Included Artifacts and Artifacts Not Included sections of the K2 Package and Deployment Overview topic.

SharePoint event processes can be packaged and deployed using K2 Package and Deployment. However, the lists and libraries associated with these SharePoint Event Processes cannot be packaged and deployed using the K2 Package and Deployment interface. These lists and libraries must be manually pre-created on the target environment before packaging and deploying the relevant SharePoint event processes to the target environment.

If the user attempts to deploy SharePoint Event Process lists and libraries using Package and Deployment, deployment of the lists and libraries to the target environment may succeed, but the relevant process will fail when it is run.

Also, if the needed SharePoint lists and libraries are not pre-created and an instance of the relevant SharePoint process is started, an error will be given stating that the list and/or library was not found, and the process will fail.

SharePoint event processes must be deployed using the following procedure:

1. Pre-create the needed lists and libraries at the target environment by manually copying the lists and libraries from the source environment to the target environment.
2. Package and deploy the associated SharePoint processes from the source environment to the target environment, using K2 Package and Deployment.

Deployment of K2 connect SmartObjects

If K2 connect SmartObjects are to be packaged and deployed, the following prerequisites are needed:

• The K2 connect application must be installed on both the source and target environments.
  
• The K2 connect installation on the target environment must include a K2 connect service instance (this is typically created during the K2 connect installation).

SmartObjects created using K2 connect can be packaged and deployed using the Package and Deployment interface. However, the K2 connect Service objects (in *.SVD file format) associated with these SmartObjects cannot be packaged and deployed using the K2 Package and Deployment interface.

The relevant K2 connect Service objects must be manually pre-created on the target environment before the relevant SmartObjects are packaged and deployed to the target environment using K2 Package and Deployment.

K2 connect Service objects must be deployed using the following procedure:

1. Pre-create the relevant *.SVD-format Service objects at the target environment by manually copying the Service objects from the source environment (on the local machine) to the target environment.
2. Open the relevant K2 connect Service objects in a new Visual Studio project. Publish the Service objects.
3. Package and deploy the K2 connect SmartObjects associated with the Service objects from the source environment to the target environment, using K2 Package and Deployment.

Processes which contain Project References

Processes containing Project Reference(s) (i.e. where the Reference type is listed as 'Project' in the Process References window) cannot be deployed to a target environment:

• If the user tries to deploy an existing process containing Project References, the system will return a System.Reflection.TargetInvocationException: Value cannot be null. error.
• If the user tries to include a process which contains Project References in a new deployment package, the user will be prevented from creating that deployment package.

For a process containing Project References to be successfully deployed, the Project References within a process must be deleted and re-added as assembly references before the package is recreated and the process deployed, as in the procedure below.

Within the source environment:

1. Open the project using K2 Designer for Visual Studio.
2. Right-click on the process Start icon. Select Properties.
3. In the Configuration menu, click on the Process References icon. The Manage Process References window will appear.
4. Locate and make a note of all processes where the 'Type' is listed as 'Project'. Remove these Project Reference(s) by clicking on them and clicking the Delete button.
5. Click the Add button in the Manage Process References window.
6. The Add References window will open. Click on the .NET tab.
7. Search for the previously deleted references in the Component Name column. Click on the correct references and click the Select button.
8. Click OK. The references will be re-added as Assembly References (i.e. listed as .NET).
9. The references will now be visible in the Manage Process References window. Locate the references, ensuring that the Copy Local check box is checked for each process.
10. Prior to recreating the package, a local disk cache must be cleared, or the new Assembly References will not be picked up. To delete the cache file, navigate to the HostServer folder on the source server (C:\ProgramData \SourceCode\HostServer). Delete the HostServer folder and its contents.
11. Recreate and redeploy the deployment package.