Import-Export - good practices of process creation

Applies to version: 2021.1.x and above; author: Dawid Golonka

The article is an update of the already existing article, it shows the configuration in version 2021.1.x. For the original see: Import-Export – Good process design.

 

Introduction

WEBCON BPS has a mechanism that allows you to transfer process definitions between several independent environments. The DEV-TEST-PROD environment model is fully supported, in which the development environment (DEV) model is designed to create new processes, the test environment (TEST) is used to perform functional tests before the final implementation of the solution on the production environment (PROD) on which they work users.

Creating processes in such a way that they are insensitive to the context of the environment in which they work requires adherence to a certain regime. However, it results naturally from the functionalities available in WEBCON BPS Studio and the operation of the platform mechanisms. Thanks to the appropriate approach to designing processes, it will be possible to use the Import-Export mechanism to automatically and quickly transfer changes between environments.

Before moving on to discussing the principles to be followed when creating exportable workflows, a few words of explanation about the operation of the  Import-Export mechanism have been included. Understanding it will make it easier to explain the necessity of using this approach when creating processes.

Import-Export from the technical side

All elements of the created process, such as form fields, form types, workflows or data sources, are uniquely identifiable in the system by the ID.

 

Workflow:

Fig.1. Workflow ID

 

Form field:

Fig.2. Form field ID

 

Step:

Fig.3. Step ID

 

ID’s are unique in the scale of the environment (or more precisely, the database) on which they were created. This means that an identical process created in two different environments will have different identifiers of its objects (form fields, workflows, workflow instances, etc.).

 

An example “Absence process wizard" implemented in the TEST and PROD environments - different process ID’s.

 

Fig.4. Process ID in the test environment

Fig.5. Process ID in the production environment

 

When transferring a process to another environmen the Import-Export mechanism must be able to associate the imported process with the existing one in the environment to recognize which items have been changed, added or removed. In order to be able to unambiguously identify all elements of the process, the Import-Export mechanism is based not on the ID (which, as previously mentioned, differs in different environments) but on a dedicated GUID. The GUID, like the ID, is automatically assigned to the process elements when they are created. However, unlike an ID, a GUID remains unchanged in the context of many environments. The GUID is saved in the database and transferred along with the imported process to new environments. Thanks to this technical solution, the Import-Export mechanism based on the GUID is able to recognize any changes and correctly update the process. To check the GUID of a given system element (process, workflow), select the icon to the right of the identifier:

Fig.6. Item GUID

 

Working in the DEV-TEST-PROD regime, using the Import-Export mechanism to transfer changes from one environment to another, you cannot manually change the process on the PROD environment. A new process element added to the PROD environment outside of the Import-Export mechanism will have a different GUID identifier. This will result in overwriting any changes at the next import of this process from the TEST environment (the newly created element will be deleted, because in the TEST environment the object with this GUID does not exist).

During an emergency in which any modification of the process had to be made manually, apart from the Import-Export mechanism, it is necessary to ensure that all environments are correctly synchronized after such a change. Correct synchronization means exporting the changed process from the PROD environment, and then importing it into the TEST and DEV environment.

Manual synchronization, i.e. manual execution of identical process modifications on other environments, is not a correct approach because it does not guarantee process consistency within DEV-TEST-PROD environments and may lead to errors when importing at a later time.

 

Basic principles of creating exportable processes

Here you will learn about the basic principles that should be followed when designing and creating processes so that they can be implemented in the PROD environment, using the Import-Export mechanism in a quick and error-free manner. The following recommendations are important not only for usage of the Import-Export. They should be used in general as good practices for creating processes thanks to which the created solutions will be more understandable, less sensitive to change and, consequently, more reliable.

 

Use of Tags

Tags are elements used to create expressions (SQL, CAML, JavaScript) as well as Business Rules and Form Rules. The tag represents a specific value of a specific object in the system, e.g. the value of an attribute.

Tags in the case of SQL and CAML are in the form of curly braces { and }

in the case of JavaScript, the curly braces in combination with the "hash" sign # { i } #

Tags are converted to specific values while the expression is running.

Since tags represent objects whose IDs can change after moving the process to another environment, it is extremely important to use tags instead of numbers as constant identifiers in the created expressions (execution conditions, queries). Then, in the imported process, they will be automatically replaced with the correct object identifiers from the environmental point of view.

Below is an example of a JavaScript expression that sets the value of a specific attribute. Form field identifier has been defined with a tag.

 

Fig.7. JavaScript expression configured with a tag (advanced editing mode)

 

The same expression in the JavaScript Expression Editor Basic Mode.

Fig.8. JavaScript expression configured with a tag (basic editing mode)

 

Using global constants or a process to become environmentally independent

Different environments will, by definition, differ in certain characteristics. The most obvious one is that the PROD environment will have a different web address than the TEST environment. There may be more similar differences resulting from the fact that the environments are based on a different technical infrastructure.

If it is necessary inside a process to refer to a value that may be different in different environments, use the functionality of Global Constants or Process Constants.

The functionality of global constants allows you to define different values depending on the environment in which the process will be run. These values, used as tags when creating expressions within the process, will be replaced with appropriate ones depending on the environment.

 

Fig.9. Create constants depending on the current environment

 

Data sources in the DEV-TEST-PROD mode

Data sources are another element that can naturally vary depending on the environment in which it is defined. This difference may be due to a different source address, user, or source access password.

Connections to data sources defined in WEBCON BPS Studio allow you to specify various parameters depending on the environment on which they are to work. The use of this functionality makes the created process independent of the context of the environment in which it will work.

Fig.10. Create connections to sources that work in any environment

 

Data sources as an element defined outside the process (the process uses a data source, but the source is defined in the system configuration, not in the process configuration) can be safely modified after importing it into the target environment. This means that when creating a process on the DEV environment that uses an external data source, it is not necessary to know the address of this source in all environments (TEST and PROD). Configuring the source in the context of the appropriate environment can be deferred until the process is deployed to that environment.

 

Using database column names

Process form field values are stored in the database column assigned when the form field is created.

An example of the "Acceptor" form field, the values of which will be stored in the WFD_AttChoose3 column.

Fig.11. The form fields created in the system have their counterparts in the form of columns in the database

 

When exporting and then importing the process to another environment, the Import-Export mechanism ensures that the form field is still embedded in the same database column in the new environment as in the environment from which the process was exported. This allows you to uniformly create queries, SQL functions or stored procedures based on column names without having to modify them in the context of multiple environments.

Below is an example of a query returning an instance number and the date of registration of a vacation request. This design will work properly, regardless of the environment (DEV-TEST-PROD) it will be run on.

Fig.12. An example of a query that works correctly, regardless of the selected environment

 

Examples of correct and incorrect constructions

Below are some specific examples of SQL expressions in an incorrect form from the point of view of the Import-Export functionality and their transferability between environments. There is also an explanation of what the errors are, what they will result in, and what the correct expressions should look like.

 

• Object identifiers in expressions

As mentioned earlier - in the construction of expressions, avoid entering object identifiers as constant numbers.

Below is an example of an action execution condition depending on the form type (Incorrect).

 

Fig.13. Form ID assigned as a number - invalid configuration

 

This example incorrectly uses the value 514 for the form type ID.

This identifier is correct in the context of the DEV environment, but after importing the process into the PROD environment, the form type identifier may be different, and consequently the whole condition may not work correctly.

Instead of specifying the object identifier directly, use the appropriate tag, which will be correctly replaced when importing the process.

Expression after correction (Correct).

 

Fig.14. Form type identifier assigned as a tag - correct configuration. Advanced editing mode

 

And the same expression in basic mode (Correct).

 

Fig.15. Form type identifier assigned as a tag - correct configuration. Basic editing mode

 

 

• SharePoint group as a global constant

Another, more complex example, is the use of the SQL function that checks whether a user with a given login belongs to a given SharePoint group.

This condition can be used to define the visibility of the form field (Invalid).

 

Fig.16. SharePoint group ID assigned manually. Incorrect configuration

 

In the example above, the number 45 was incorrectly used as the SharePoint group identifier and the site address in the form of the string http://wdr01/. Both of these values will be different in the PROD environment, which will make the condition malfunction.

To make the above expression independent from the context of the environment in which it will be executed, the mechanism of global constants should be used.

We create two constants in the system configuration: "Site address" and "Group SP administrators" in which we define the correct values, separately for each environment.

Use the constants you created as tags in an expression. In addition, a tag representing the currently logged in user was used instead of a rigidly entered user login.

The expression (Correct).

 

Fig. 17. Correctly configured expression in advanced editing mode

 

And the same expression in basic mode (Correct).

Figure 18. Correctly configured expression in basic editing mode

 

At the expression execution, the tags will be replaced with the correct value from the point of view of the environment in which the expression is executed.

 

• Hyperlink

Consider a case in which the "Correspondence" workflow has two form types: Incoming and Outgoing correspondence. Each Outgoing Correspondence form type is linked to one Incoming Correspondence form type. On the Incoming correspondence form we want to display all instances related to the Outgoing correspondence and give the possibility to go to these instances using a link.

For this purpose, you can use the "Data table" form field in which the instance number, date of registration and date of sending the related workflow instance will be displayed. The document number will be a link to a given instance.

An example expression that returns data for an Data Table might look like this (Incorrect).

Fig. 19. Incorrect configuration of Data Table type form field

 

 The solution is to create a Global Constant in which the correct website address for different environments will be defined. This constant must then be used when creating the link in the SQL expression (Valid).

 

Fig. 20. Correct configuration of the Data Table form field

 

In this way, the expression on which the SQL list is based will be insensitive to the context of the environment in which it will be executed, which means that it will functionally work correctly in any environment.

Staying on the topic of generating links to instances, it is worth mentioning that to achieve a similar effect, you can also use the built-in "Open Element" function available in the "Functions"> "Hyperlinks" tab.

You can read more about the feature in this article: The Hyperlink action.

 

 

Fig. 21. Using the Open Element function to create a link

 

Summary

By applying to the practices described in this article, it is possible to create processes and avoid problems when moving them between environments.