Understanding Environment Libraries

Many organizations have multiple K2 environments, for example Development, Test, QA and Production. These environments usually have different server names, URL’s settings and so on. K2 makes provision for multiple environments with the Environment Library, which is essentially a repository of environment-specific values or "placeholders" for each of your K2 environments. Consider the table below:

Environment Field Environment
Development Production
SharePoint Portal URL http://devportal.denallix.com http://portal.denallix.com
Email Server devmail.denallix.com mail.denallix.com

When building workflows or SmartForms, designers may need to interact with the SharePoint or Email servers. Here is an example: perhaps the developer will use a SharePoint document event to copy a document from one document library to another. Part of that event wizard needs the URL of the SharePoint site where the document libraries exist. It would be tedious (not to mention hazardous) to develop the solution for the Dev environment using the hard-coded URL for the development SharePoint server and then have to go through the event wizard again to replace the URL with the production SharePoint server before deploying the solution to the production environment. This is where the environment library comes into play.

To learn more about the K2 Environment Library, we recommend that you download the K2 Environment Library whitepaper, available at http://help.k2.com/en/environmentLibrary_Whitepaper.aspx
 

Consider the screenshot below, which is one of the screens for the document move wizard. Instead of hard-coding the URL of the SharePoint site into the wizard, the developer can browse through the values stored in the environment library, and then drag and drop the “placeholder” for the SharePoint site URL into the wizard. (The actual value of the SharePoint server is not resolved until runtime.) The designers will deploy the workflow with the [Portal] placeholder. When the workflow executes at runtime, K2 will replace the URL of the SharePoint server for the current environment (in other words, the Development SharePoint server URL if the workflow is running in Development, and the production SharePoint server URL if the workflow is running in Production)

Using an environment field in the K2 designer

Using an environment library field in the K2 SmartForms design tool

Environment fields are stored on a K2 server, and K2 is “context-aware” at runtime. This means that even if one K2 environment contains multiple copies of the same placeholder for each environment, when the workflow retrieves a environment field at runtime, K2 will know which values to use for the placeholder for the current environment. The currently-active environment is defined by the "Default setting for the environment.

The default values in the environment library are set up when K2 is installed, but it may be necessary to update these values from time to time. This can be done either through the K2 Studio environment or by the K2 administrator using the K2 management site. Regardless of the approach used, the values are centrally stored on the K2 server.

Strictly speaking, workflows retrieve the field values at runtime from the String Table , not the environment library. We don’t recommend that you modify or maintain values in the string table by hand, since the string table values are overwritten by the environment library values when a workflow is deployed. This means you may end up in an unexpected situation where a change you made in the string table is lost when a workflow is deployed.

To keep things simple, we recommend that you define and maintain environment-specific placeholders in the Environment Library and rely on the deployment mechanism to keep the String table up-to-date. If it is vitally important to change a string table value by hand to address a runtime issue then you can do so, but remember to change the value in the environment library as well so that the change is "remembered" when a new workflow is deployed

By default K2 is installed with two Environments. When a developer deploys a K2 project, they will target a specific environment. The project will then retrieve the values for the specified environment from the K2 server and publish the project to the relevant K2 server

Selecting the target environment when deploying a K2 project

Environment Libraries - Setup Options

To help you decide on an appropriate approach for managing and maintaining your environment libraries, let's look at some common approaches used to define and separate Environment Libraries. We will discuss three common options.

Each approach has its benefits and drawbacks, and there are many factors that may determine whether you chose one over the other. If you are unsure which to use, the recommended approach is to the use Single model. This way, you only need to maintain Environment Library settings in one K2 server and it is easier to create deployment packages. You should set up server-level rights to restrict deployment to specific environments to prevent developers from mistakenly deploying to the wrong environment.

For larger environments, shared development environments or environments with strict change control policies we recommend that you make use of K2's consulting services to select am approach for your Environment Library, Templates and Security that will work well with the way your organization plans to use K2

With the Single approach, a single K2 environment stores the Environment Libraries for all the other environments. This approach is the simplest to use and is used most often.

Consider the diagram below, where we have three separate K2 environments: Dev, QA and Production. In the Single model, the Development K2 environment stores the Environment Library for Development, QA and Production. When a developer wishes to deploy a solution (or create a deployment package), they will always connect to the Development K2 server and then select the target environment that they want to deploy to

Environment Library Setup - Single

Although this Single approach is the simplest to use and maintain, there is a risk because a developer may inadvertently select the wrong environment to deploy to. You can mitigate this risk by setting up Server Rights for the Workflow Server in the Production environment, and only allowing Administrators to deploy to the Production environment. This way, even if a developer mistakenly selects Production, they won't be able to deploy the solution

With the isolated approach, each K2 environment has a separate and dedicated Environment Library that only contains the environment settings for itself. This is probably the most secure option, since the developer would physically need to change the connection string in their development workstation before they will be able to deploy to the selected environment.

Consider the diagram below. Here, we have the same three K2 environments (Dev, QA and Production), but each one only knows about itself

Environment Library Setup - Isolated

At design time, the developer would have to physically change the connection before they will be able to deploy to the target environment, as shown below. This adds some additional overhead to the developer and they need to be very careful to connect to the correct K2 server, but it makes it very difficult to mistakenly deploy to the wrong environment because the developer would only have one option in the Environment drop-down box when they deploy. If you couple this with server-level rights on each K2 environment, you can harden the deployment security even more.

Changing the connection to the Environment Server

Another Environment Library setup approach is where each environment only knows about itself and the environment immediately following.

Consider the example below with the Dev, QA and Production environments. In this setup, the Development K2 server only knows about itself and the QA environment. This means that developers can deploy to both Development and QA, but not to Production, because the Development server doesn’t even know about Production

Environment Library Setup – Self + 1

To deploy a solution to Production, the person creating the deployment package would need to physically connect to the QA server and select the Production environment (or target the production environment in their deployment package).

This approach combines the Single and Isolated models to make it easier for developers to move between Development and QA, but harder to inadvertently deploy to production. The drawback of this approach is that the Environment Library settings are maintained separately, so it adds workload to the K2 administrators to maintain settings across multiple servers.