Export & Import – Good process design

Facebooktwitterpinterestlinkedinmail
Applies to version 8.3.x; Author: Jacek Język

Intro

WEBCON BPS 8.3 comes outfitted with a new mechanism allowing one to move process definitions across multiple independent environments. The system features full support for the widely used DEV-TEST-PROD environment model, where the development environment (DEV) is used for designing new processes, the testing environment (TEST) is used to verify all necessary function before they are finally implemented on the production environment (PROD) where the users conduct their work.

Designing processes so that they are unaffected by the context of the environment in which they are currently actives requires following certain guidelines. These guidelines are a natural consequence of mechanisms and functionalities available in WEBCON BPS. With the right mindset and approach to designing processes in Designer Studio, it will be possible to utilize the Export-Import mechanism to automatically and instantaneously transfer changes between different environments.

Before we proceed to discuss the guidelines of creating easily-exportable processes, let us first take a moment to glance over the technical side of the Export-Import mechanism. With a basic understanding of what goes on under the hood, it will be easier to explain and justify the do’s and don’ts of designing a process.

 

Export-Import – The technical side

All the pieces that make up a  WEBCON BPS process, like form fields, document types, workflows and data sources are clearly distinguished in the system with a completely unique identifier (ID).

Sample ID’s of the various elements that make up a process:

Workflow:

1

 

Form field:

2

 

Step:

3

 

ID’s are unique within the environment (within the database, to be more precise) on which they were created. This means that an identical process created on a different environment will have different ID’s for its elements (form fields, workflows, documents etc.).

One of the sample processes: “Vacation request process” has been implemented on the both the TEST and PROD environments – their process ID’s are different.

 

TEST environment PROD environment
4 5

 

During import, the Export-Import mechanism has to be able to associate components of the exported process with those already in place on the target environment, and recognize which of them were changed, added or deleted. To unanimously identify every single building block of a process, Export-Import isn’t based around ID’s (since they are different on every environment – they cannot be used reliably) but rather on a dedicated identifier named GUID. GUID’s, similarly to ID’s, are automatically assigned to components of the process as they are created. Unlike ID’s however, a GUID remains unchanged regardless of environment. GUID’s are not visible to users designing processes in WEBCON BPS Designer Studio, nonetheless they are saved in the database and carry over to the target environment when imported. With this solution, Export-Import should be able to easily pinpoint all differences between processes and correctly update the target process.

 

Warning.

Working with a DEV-TEST-PROD model, and using Export-Import to transfer all introduced changes between the environments, means that you can’t make manual changes to the PROD environment. The fact of the matter is simple – if a component is added to the PROD environment without using the Export-Import system, it will have a different GUID. The next time this process is imported from the TEST environment, changes made directly to the PROD environment will be overwritten – the newly created elements will be deleted because a counterpart with the same GUID does not exist on the TEST environment.

In emergency situations, when a process has to modified manually without the assistance of Export-Import, it is important to synchronize the environments correctly afterwards. This means that the modified PROD process should be exported and then imported to the TEST and DEV environments.

Manual synchronization (mimicking the changes made on one environment and replicating them by hand on the other two environments) is not the recommended approach, since it doesn’t guarantee consistency between the environments, and can lead to serious problems during future import attempts.

 

Basic principles behind creating exportable processes

I will now outline the basic guidelines which one should follow when designing and building process in order to deploy them on the PROD environment using Export-Import quickly and without fail. The principles below are not only beneficial because they allow Export-Import to be used to full effect, but because they are good practices in general and should be employed as often as possible. The resulting processes will not only be easier to understand, but will also be less vulnerable to changes – making them more reliable.

 

Using Tags

Tags are often employed to create expressions (SQL, CAML, JavaScript). A tag represents a specific value of a specific component in the system e.g.: the value of a form field.

SQL and CAML tags are denoted by curly brackets { I }

Since version 8.3, JavaScript tags are a combination of curly brackets and number signs (a.k.a. hashes) #{ I }#

Tags are turned into specific values whenever an expression is invoked.

Since tags reference objects whose ID’s may change when moved to a different environment, it is critically important to use tags in all created expressions (execution conditions, queries) instead of number ID’s. As a result, whenever a process is imported, they will be updated to reference the correct object ID’s in the context of their new environment.

Below is an example of a JavaScript expression which sets the value of a row in a specific column of an item list. Both the item list and column identifiers have been defined using tags.

6

 

The same expression as seen in the basic mode of the JavaScript editor:

7

 

Using global and process variables to make a process universal and independent of environment.

There will always be a number of key differences between environments. One of the most obvious ones is the WWW address, PROD and TEST environments will naturally have different sites. Since the environments are based on different technological infrastructures, there can be many more similar differences.

If a process needs to reference values that vary based on environment, it is recommended to use either Global variables or Process variables – both new features introduced in BPS 8.3.

When creating a variable in Designer Studio you can associate multiple values with it – a different one for each environment. A variable like this can then be placed into expressions within the process in the form of reference tags. The system will automatically the use the value appropriate for the environment the process is on.

8

 

Data sources in the DEV-TEST-PROD model

Data sources a yet another component which will differ based on the environment it was defined on. This difference may be caused by a different access settings like address, username or password. Data sources defined in WEBCON BPS Designer Studio allow you to provide different connection parameters for each environment. Using these settings makes a process independent from the context of the environment it operates in.

9

 

Note:

The environment settings section of a data source can be safely modified even after a process is imported to a target environment (since data sources are defined on system level, and not process level). Essentially this means that when creating a process on the DEV environment, which uses an external data source, it is not necessary to know what the address of this external data source is for other environments (TEST and PROD). Environment-specific data source configuration can be delayed until the process is actually implemented on that environment.

 

Using database column names

The values of a process’ form fields are stored in database columns, assigned the moment a form field is created.

In the example below, values of the “Substitution date” form field are held in column WFD_AttDateTime13.

10

 

When a process is exported and later imported to a different environment, the Export-Import mechanism makes sure that the form field is located in the exact same database column as on the source environment. This is to ensure the continuity of expressions, queries, SQL functions and stored procedures which rely on column names, without the need to adjust them to the context of a new environment.

Below is an example of a query that returns a document signature as well as the registration date a vacation request. A query structured this way will always work regardless of environment (DEV-TEST-PROD).

11

 

Examples of correct and incorrect syntax

In this section, I will present various examples of SQL queries which are incorrect from the perspective of the Export-Import functionality. I will the attempt to explain why the given example would be troublesome to move between environments, and how to make them Export-Import friendly.

Object identifiers in expressions

As mentioned above, when constructing expressions it is better to avoid entering object identifiers as constants.

The below example is an execution condition of an action, which relies on a document type (Incorrect):

12

 

In this example, the value 21 was used incorrectly do designate the ID a document type.

This ID may be Correct on the DEV environment, however after being imported to the PROD environment the ID will be different and therefore the entire execution condition will work incorrectly.

Instead of entering the Object ID directly, provide the correct tag which will be suitably adjusted during import.

Adjusted expression (Correct):

13

 

The same expression again in basic mode (Correct):

14

 

SharePoint group as a global variable

Another more complex example would be using an SQL function to check whether a user with the specified login belongs to the given SharePoint group.

Such a condition can be used to define whether a form field is visible or not (Incorrect):

15

 

In the example above, the number 45 was used incorrectly as the SharePoint group identifier, furthermore the site address entered as a string of characters https://intranet.webcon.com is also incorrect. Both these values will be different on the PROD environment, which means that the condition will not work as intended.

In order to make the expression independent of the environment on which it is executed, it is necessary to employ the Global variables mechanism.

In System settings, create two new variables: “Site URL” and “Administrators group” where we define values specific to each environment.

16

 

17

 

Variables created this way should be added as reference tags in the expression. Additionally, instead of entering the username directly into the expression, a tag was used that represents the user that is currently logged in.

Adjusted expression (Correct):

18

 

The same expression again in basic mode (Correct):

19

 

Whenever the expression is called, tags are substituted with the relevant value, correct for the current environment.

 

Hyperlink

Let’s use an example where the workflow “Correspondence” has two document types: Incoming correspondence and Outgoing correspondence. Every element of Outgoing correspondence is linked with one element of Incoming correspondence. On the Incoming correspondence form, we want to display all linked workflow elements from Outgoing correspondence, and make them directly accessible via hyperlink.

We will be using an “SQL Grid” form field to display the document number (Signature), registration date as well as the send date of the linked element. The document number will be a hyperlink leading to the given workflow element.

An example of an expression returning data for an SQL Grid may look like this (Incorrect):

20

 

In order for the values in Signature column to be displayed as hyperlinks linking to specific elements, the following syntax was used:

‘link:http://intranet.webcon.com/DEV/Correspondence/_layouts/15/WebCon/WFDynamic.aspx?WFD_ID=’ + cast(WFD_ID as varchar(12)) + ‘;displayname:’ + WFD_Signature

When the query is invoked, it takes the following form:

link:http://intranet.webcon.com/DEV/Correspondence/_layouts/15/WebCon/WFDynamic.aspx?WFD_ID=1;displayname:BPM/2015/03/0001

The result on the form will be a table, where clicking the document number (signature) will link to the form of the linked workflow element.

21

 

Such a solution will work perfectly on the DEV environment, where the address to the Outgoing correspondence workflow is http://intranet.webcon.com/DEV/Correspondence/.

However, when this workflow is moved to the PROD environment (where the site address is completely different), the link will lead to a different element.

The solution to this is creating a Global variable which will store the different addresses for various environments.

22

 

This variable is then inserted as a tag when creating the SQL expression (Correct)

23

 

The expression on which the SQL Grid is based will now be independent of the environment – the tag referencing the Global variable will insert the correct value for each environment and the expression will work correctly as a result.

One thought to “Export & Import – Good process design”

Leave a Reply

Your email address will not be published. Required fields are marked *