Package and Deployment Considerations
Before creating or deploying a package, review the following considerations.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
All packaging and deployment actions use the identity of the K2 server service account. However, your credentials are validated to ensure you have the necessary permissions to package and deploy.
To create and deploy a package, ensure that you have the following rights and memberships in the source and target K2 environments:
- Workflow Export Rights
- SmartObject Publish rights. A check is performed to validate if SmartObject Publish rights have been set on specific SmartObjects that have been generated in the K2 application
- You are a member of the Package and Deployment role
When creating a workflow, remember that you are the owner of the workflow, and you need to enable sharing before other users can view or edit it.
To ensure a successful package and deployment, you must have View rights to all objects in the system. This ensures that when dependencies are checked, Package and Deployment can determine whether items exist (and need to be updated) or do not exist (and need to be created). The Package and Deployment role grants its members global view rights but membership in this role does not override any Deny rights you may have set for the identity currently packaging or deploying.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
In some cases it is possible to deploy packages created in one K2 product to a different K2 product. The table below lists which cross-product deployment scenarios are possible.
Package Created In | Deploying To | |
---|---|---|
K2 Cloud | Nintex K2 Five | |
K2 Cloud | Yes | No |
Nintex K2 Five | Yes* | Yes |
K2 blackpearl 4.7 | No** | No** |
* You can deploy packages created in Nintex K2 Five to K2 Cloud as long as the packages only contain items that are available in K2 Cloud, and the artifacts in the package were designed using a tool available in K2 Cloud. ** To create useable packaged solutions designed using K2 blackpearl, upgrade your 4.7 environment to Nintex K2 Five and then re-create your packages. |
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
The following table lists the K2 artifacts that are included in or excluded from deployment packages. You can assume that anything not explicitly listed as "Included in Package?" in this table, is not included in the deployment package.
Artifacts included in the package are based on selections you make when creating the package. You may need to manually add or remove items from the package depending on the artifacts used in your application, however K2 Package and Deployment is designed to include all dependent artifacts it can find.
K2 Artifact | Included in Package? | Notes |
---|---|---|
SmartObjects | Yes | SmartObjects used by the workflow will be included. |
Workflows | Yes | You may need to add workflows manually |
Forms and Views | Yes | Only K2 SmartForms Forms and Views are included automatically. Custom user interfaces such as custom web pages, ASP.NET forms or other custom user interfaces are not included in the K2 deployment package. |
Custom SmartForms Controls | Yes | Custom controls are included in the package. You must have K2 server Administration rights when deploying custom controls. |
Reports | Yes | Only generated reports for the application are included by default. If you have created custom forms and views for reporting purposes, you may need to add those items manually. Any custom reports created with another technology are not included. |
SmartBox SmartObject Data | User Configurable | SmartBox SmartObject data is excluded by default. You can change this option to include the data from the SmartBox SmartObject. If you change a SmartBox SmartObject to an Advanced SmartObject you will not be able to package the data. |
Roles | Yes | Roles are deployed, but will be empty. You need to add roll members in the target environment after deployment. If a role exists in the target environment, you can’t deploy that role (with the same name) to the target environment. |
Service Objects | Yes | |
Categories/Folders | Yes | |
Service Instances/Custom Service Instances | Yes |
Service Instances are not packaged nor deployed by K2 Package and Deployment. It is expected that these be manually created in the target environment with the same System Name. When SmartObjects are packaged, K2 Package and Deployment will record the Services Instance type and System Name in the package. When K2 Package and Deployment deploys a SmartObject it will try to locate a Service Instance of same type and System Name as included in the package. When SmartObjects are packaged By Reference Only these service instances can be mapped to the service instances in the target environment. When using the PowerShell snapin command to deploy service instances and environment fields, the generated XML configuration file properties always default to "UseExisting" and you must manually change them to "Deploy" or "Default". |
Service Types and Service Brokers | By Reference Only* | Service Types and the associated Service Brokers must already exist in the target environment. |
Environment Library Fields | By Reference Only* | Environment fields other than miscellaneous (Misc) need to exist on the target. Miscellaneous fields are included in the package. |
Workflow Permissions | No | Your account is automatically assigned admin rights on the workflow. After a workflow is deployed, use the K2 Management site to set workflow permissions for the workflow. You should only have to do this the first time you deploy the workflow. |
Custom Service Brokers | No | You must register any custom service brokers on the target environment before deploying solutions that use the custom broker. |
Custom SmartForm Themes | By Reference Only* | You must install custom themes on the target environment before deploying solutions that use the custom theme. |
Custom Workflow Wizards | No | You must install custom workflow wizards on the target environment before deploying solutions that use the custom wizard. |
*"By Reference Only" means that the definition/design of the item is not included. Instead, a reference to the item is included in the package, and as part of the deployment procedure you may need to map the reference to an existing, matching item in the target environment |
Artifacts Not Included
K2 deployment packages include K2 application artifacts such as SmartObjects, views, forms, and workflows. K2 deployment packages do not include third-party components or certain K2 artifacts, including (but not limited to):
- SharePoint lists or libraries
- SharePoint items (e.g list items or documents)
- SharePoint fields, columns or content types
- Workflow reporting data
- External data stores such as SQL Server databases and tables
- Custom environment configurations (for example, changes to configuration files like 'K2HostServer.exe.config') cannot be packaged. You must make these configuration changes to the target environment
- Custom Service Brokers, custom workflow wizards, custom user managers
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
The table below describes some artifacts or scenarios that require special attention when using package and deployment.
Area | Consideration |
---|---|
K2 connect SmartObjects |
K2 connect SmartObjects can be packaged and deployed using K2 Package and Deployment. However, you must manually create the K2 connect service objects associated with these SmartObjects on the target environment. For more information, see the Deployment of K2 connect SmartObjects section of Deploying a Package . |
Custom SmartForms Themes |
If you use a custom SmartForms theme, that theme must exist on the target environment before you deploy the package. If the custom theme does not exist on the target, the view or form that uses the theme displays a missing reference, and you must rebind the view or form to an existing theme on the target environment before you can deploy. |
SmartObject Data |
SmartObject data allows you to package SmartBox data that exists on the source K2 environment. This option is only available for SmartBox SmartObject data. SmartObject data from other sources cannot be packaged. Packaging SmartBox SmartObject data is off by default, so that SmartObject data from one environment is not automatically deployed to other environments. For further information on this subject, please refer to Creating a Package. You can only deploy SmartObject data as an option, if the associated SmartBox SmartObject definition is included in the package. If a SmartObject definition has already been deployed to the target environment, you will need to configure the deployment action to either overwrite the existing SmartObject definition, or use the existing definition. Smartbox SmartObjects that do not have the general Create, Read, Update, and Delete (CRUD) methods, cannot be packaged with data. All CRUD methods must exist in order for SmartObject data to be packaged. Smartbox SmartObjects must also contain at least one unique property, for example, a unique ID key field. |
Multiple K2 Servers and versions |
If you have multiple servers or environments, ensure that all the servers and environments are running the same version of K2. |
Anti-Virus |
Some anti-virus monitoring prevents Package and Deploy from functioning. We recommend that you:
|
SharePoint Considerations
- For lists with managed metadata, you may have to manually fix the Term Store and Term Set GUIDs after deployment.
- If you package a K2 App where the SmartObject property is based on a taxonomy field (managed metadata), the Term Store and Term Set are not included in the package.
- If you have a Referenced Item in a package and it already exists on the target environment at a higher site level (for example you are deploying a package to a subsite where the main site already has that artifact with a match), the auto-matching function preselects the main site artifact. If that artifact is not what your solution must map to, change the artifact in the Items Packaged By Reference section of the Additional References page by double clicking the artifact and selecting the correct artifact from the drop down list. This is only necessary when dealing with same site collection deployment.
- Categories in SharePoint are updated when deploying across environments. For example,
on the source environment (http://portal.denallix.com/), when you integrate K2 with a list called “Sales”, your category structure resembles the following:
- SharePoint
- Portal.denallix.com
- Lists
- Sales
- Sales SmartObject
- Sales Form
- Sales View
- Sales
- Lists
- Portal.denallix.com
- SharePoint
- sales.denallix.com
- Lists
- SalesX
- Sales SmartObject
- Sales Form
- Sales View
- SalesX
- Lists
- sales.denallix.com
- The artifact names still contain the original list's name
- When clicking on your list ‘SalesX’ and then the K2 application icon, the artifact page breadcrumb still show as the ‘Sales’ list, as this is based on the category name from the source environment
- SharePoint
- In certain scenarios when remapping to a list or library that does not match the definition in the source environment, the SharePoint fields show an error. You must cancel the deployment, fix the definition of the target list or library, and then try deploying the package again.
- If you add multiple servers to the K2 Package and Deployment console, ensure that all the servers are running the same version of K2.
-
When deploying a package to a target environment that has a new document library, deployment notifies you that the document library does not contain all the properties required for the solution to deploy. The following messages display:
- Shared With (SharedWithUsers) Property is missing from the selected object
- Shared With (Value) (SharedWithUsers_Value) Property is missing from the selected object
This message is shown because SharePoint only adds the SharedWithUsers column to the document library after a document has been uploaded and shared.
To resolve this issue:
- Navigate to the target document library.
- Upload a document.
- Share the document with someone.
- Delete the document.
- Click on the refresh button on the list or library remapping page.
- Select the target document library.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
Area | Consideration |
---|---|
K2 environments | The only way to ensure consistent package and deployment behavior between K2 environments is to align your K2 product version across the environments. This includes major version as well as fix packs (FPs) and cumulative updates (CUs). |
.NET Versions |
Source and target servers must have the same .NET versions installed. |
Matching Artifacts |
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 of the artifact you choose, or it overwrites the artifact on the target server if the artifact doesn't have versioning. |
SmartObject Versions |
If you have generated data (SmartObjects) for a SharePoint list or library and then subsequently make changes to that list or library (such as adding or removing a column), the generated SmartObject will be out of sync with the changed list or library. To fix this, you need to re-generate the SmartObject to sync the changes. Keep in mind that forms, views and workflows based on SmartObjects always use the latest deployed version of that SmartObject. While this is normally not a problem if you are adding properties or methods to a SmartObject, deleting or changing an existing SmartObject property or method might affect existing forms, views or workflows. |
Form and View Versions |
While K2 retains an audit trail of form and view changes, forms and views are not version-aware and the latest deployed version of the form or view is always used. When forms are associated with a workflow (for example, to start the workflow or action a task), the workflow always uses the latest version of the deployed form or view. Workflow versions are not bound to form versions. |
Workflow Versions |
When a workflow is deployed, a new version of the workflow is created and the new version is set as the default version when starting new instances of the workflow. Existing workflow instances are not automatically upgraded to the new version and they continue to run the version of the workflow that they were started against. |
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
There are two environments in the Environment Library, Development and Production. When working with Environment Fields, keep in mind the following:
- K2 Cloud does not support custom fields in the environment library. This means that you cannot deploy packages created in Nintex K2 Five which contain custom environment library fields to a K2 Cloud tenant.
- Packages are deployed to the environment that is set as Default.
- When there is a matching item on the target environment, the default environment's field value is used, as shown by the Use Existing Field.
- When no matching item is found on the target environment, the Create New Field option is selected.
- Miscellaneous fields are deployed as new fields.
Miscellaneous fields cannot be overwritten using the right-click menu.
- You can overwrite an environment field on deployment.
Any packages that are force deployed using the Create New Version option or deploying with Powershell using the -NoAnalyse option will overwrite environment fields.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
Consider the following items when designing a solution as it will affect the performance of the K2 Package and Deployment tool:
- Limit the number of forms, views, tabs, rules, controls, subforms, subviews, and the use of the Navigate to Form rule event in your solution. These items are included in the package as references or dependencies that are processed during packaging and merged during deployment. Using too many of these items may result in performance issues.
- The maximum size for packages is 5MB. If your package exceeds this size, try reducing the size of your solution by reducing the number of artifacts included in the solution.
- Use the Navigate to URL rule event instead of the Navigate to Form rule event because the form that is navigated to is also included in the package.
- Use the option to package by reference if the artifact already exists on the target environment. Referencing items that already exist saves space and time when creating and deploying packages across environments. It is important that the solution is structurally the same on the source and target environments.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
When you use the Navigate to option in a workflow Task SmartForm configuration as shown in the image below, the form URL in the current environment is used. When you use the Package and Deployment tool to migrate applications between environments, this URL is no longer valid in the new environment. If you’re planning to migrate the solution to another environment, we recommend using the Navigate to URL rule action instead to navigate to a SmartForm.
Follow the steps below to configure the Navigate to URL rule action:
- In K2 Designer, edit the form used for the Task in your workflow, create a new rule and add the Navigate to a URL action.
- Click configure to add the form URL to the action. You can get the form URL by clicking the Runtime link in the Browse section on the form’s properties page. Click OK.
- This rule doesn’t have a rule event, so you can name the rule and click OK to save it.
- Edit the configuration of the Open the Task Worklist Item rule action by clicking the configure link. The action is typically found in the When the Form is Initializing rule.
- Select Call this Rule and select your new rule from the drop-down list. Click OK to save the configuration and OK to save the rule. Click Finish to save the form.
- The option is automatically updated in the Task Form configuration in your workflow.
![Closed](../../Skins/Default/Stylesheets/Images/transparent.gif)
Known issue:
When you use a DocuSign template with any of the DocuSign workflow events, package and deploy your solution to a target environment containing a different DocuSign instance with different template GUIDs, and start a workflow instance of the workflow containing the event in the target environment, an error occurs. This is because Package and Deployment doesn’t support refactoring of Docusign templates.
Workaround:
Open the workflow in the target environment, reselect the correct template in the DocuSign workflow event, and deploy the workflow.