Package and Deployment Considerations

Before creating or deploying a package, review the following considerations.

If you have a firewall with port restrictions within your company network, you must open outbound connectivity over a port range to ensure the K2 Package and Deployment tool can connect from your company's network to your K2 Cloud environment. The port range is 25683 - 26707.

For more information on where to retrieve the IP address for your K2 Cloud server, see the Servers topic.

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:

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.

  • You must include the K2 Package and Deployment role, which is added by default, to every SmartObject you secure if you want to be able to create packages that include the data in those SmartObjects as part of the deployment.

    • In order for Package and Deployment to authenticate Azure Active Directory (AAD) users, an AAD Global Administrator must grant consent to the K2 for AAD Login app. If you see an error stating “Primary Credentials Not Authenticated. Session Not Authenticated,” see AAD Consent.

    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.

    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.
    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.
    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.
    *"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

    The table below describes some artifacts or scenarios that require special attention when using package and deployment.

    Area Consideration
    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:

    • Exclude files with extension .log and .txt. These are used by the logging framework
    • Excluding the path: "\K2\Host Server\Bin\Work"

    SharePoint Considerations

    1. For lists with managed metadata, you may have to manually fix the Term Store and Term Set GUIDs after deployment.
    2. 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.
    3. 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.
    4. 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
      On the target environment (http://sales.denallix.com/sites/main), when you deploy your package and rebind your list to “SalesX” your category structure resembles the following:
      • SharePoint
        • sales.denallix.com
          • Lists
            • SalesX
              • Sales SmartObject
              • Sales Form
              • Sales View
      • 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
    5. 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.
    6. If you add multiple servers to the K2 Package and Deployment console, ensure that all the servers are running the same version of K2.

    7. 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:

      1. Navigate to the target document library.
      2. Upload a document.
      3. Share the document with someone.
      4. Delete the document.
      5. Click on the refresh button on the list or library remapping page.
      6. Select the target document library.
    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.

    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.

    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:

    1. 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.
    2. 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.
    3. This rule doesn’t have a rule event, so you can name the rule and click OK to save it.
    4. 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.
    5. 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.
    6. The option is automatically updated in the Task Form configuration in your workflow.

    Related Topics