Best practices in business rules

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Best practices and implementation guidelines >

Best practices in business rules

Bizagi provides powerful Business rules that can be implemented in various places throughout the Process to Perform actions, route your Processes, manage user interfaces and allocate users.


There are many ways to define a rule and have the exact same results. You should implement the most efficient and flexible one.


This section provides some guidelines to build rules focused on minimizing the impact on the performance of the application and enabling Processes to easily adapt to changing business conditions.


General guidelines

All business rules for routing processes are built in Bizagi


If a business rule exists in another system

oRequest the customer to expose the business rule and consume it from Bizagi

Recommendation: Using web services

Alternative 1: Using the Bizagi component library as a facade.

Invoking an API provided by the customer

Using a component to access an external data source (i.e. stored procedures)

oIf the system will be replaced in a short time

Recommendation: Build the logic in Bizagi.


If a business rule has high computational demand

oIt should be implemented on another system and consumed from Bizagi

Recommendation: Implement it as a web service

Alternative 1: Using the Bizagi component library as a facade.

Invoking an API provided by the customer

Using a component to access an external data source (i.e. stored procedures)


If a business rule is changed frequently by business users

oIt can be done inside or outside Bizagi

In Bizagi, if there is no other system that can implement it or it doesn’t have a user interface that allows modification by business users

In an external system, if it has an interface for business users and can be consumed from Bizagi

Recommendation: Implement as web services.

Alternative 1: Using the Bizagi component library as a facade.

Invoking an API provided by the customer

Using a component to access an external data source (i.e. stored procedures)


If a new business rule is required and must be consumed from other systems

oYou can build it in Bizagi if it is not of high computational demand

oOther systems may access it through the SOA layer (just business rules, this does not apply to expressions or functions)


Nomenclature for expressions

Using prefixes in rules, has two roles, explain the purpose of the rule and where it’s been used; follow this guide to select the appropriate prefix:


Rule type



Visibility, required, editable,



Is_CustomerVIP, Is_Allowed

Button Rule



Event Rule (On Enter, On Exit)  



Event Rule (On Save, Submit

on change)



Library Rules



Filter Rules  


Fil_CustomerVIP, Fil_Requests


Designing efficient and governable business rules

When defining business rules you should take into account the following basic principles:


1. Design flexible rules

2. Implement efficient code

3. Document rules


Below you will find useful guidelines to follow these principles and aid the rules definition and administration.


1. Design flexible expressions

Business rules are used to model business conditions. As these conditions are in constant change, so it is fundamental to create rules that can be easily changed.

Plan carefully which changes your Process may face and build rules in the way they can be easily adapted to respond the changing business conditions.


Use policies

Use Policies to model business rules that face changing business conditions. Using policies instead of Expressions offers the advantage of allowing users to easily manage them from the Work Portal. This way they can perform changes in values or logic in real-time to instantly adapt to the current business conditions.


The image below shows an Expression and a decision table (Policy) used to evaluate the risk assessment of a loan application based on a credit assessment. Both expression and decision table work for this purpose, but if the values of the risk assessment change to respond the business conditions, you cannot access the expression from the production environment to modify them. In contrast, by using a decision table, users can easily change these values from the Work Portal.




Use Vocabularies

Vocabularies are definitions that obtain or set all the information used in the Policies or Expressions. If a business rule cannot be modeled as a Policy, but their parameters need to be frequently changed for adapting to the business conditions, you can use Expressions including Vocabularies.


Vocabularies can be invoked from Expressions or Policies and managed in production environment by end users from the Work Portal.


The image below shows two ways to assign the duration to an activity. The duration of this activity depends on a customer SLA (Service Level Agreement).


In the upper image, the activity duration is defined as a fixed value if the SLA changes, the expression has to be modified in development environment and then be taken to production environment, via deployment.


In the lower image, a Vocabulary is used to define the duration. If the SLA changes, an administrator user can access the Work Portal and modify the value of the vocabulary to instantly reflect the new condition in the Process.




Do not assign an entity instance by using their ID

When having an entity instance, do not assign it with an ID.

You will have to use objects instead.




Reuse business rules

Business rules can be reused along a Process. In many cases, the same logic is followed in different steps of the Process and does not make sense to build the same rule over and over again. Reuse rules everywhere they are need, this way if changes are required you only modify them once and reflect changes every place the rule is used.


Use library rules

Library rules are reusable for the entire project, as they are defined globally. In Library rules it is mandatory to use the first parameter as Me and NO other object.


Declare all variables

Use the expression element to declare the variables that will be used in the Expression, giving each one a type, and an initial value.




2. Implement efficient code

Some complex situations may require you to implement code in Bizagi. For these cases, take into account that there are practices that highly affect the performance of the application. Keep these practices in mind when implementing business rules to make you application faster and improve the user experience:


Avoid manipulating plenty of records at once

When using methods to obtain a set of records, make sure that filters are used accordingly and that you only fetch those records which you really need.

This should avoid major iterations through a set, and should promote quick access to the needed information. It is not usual to manipulate a considerably large amount of records;  as this would suggest there would most likely be an improved way to cover a business requirement.


Avoid nested for's

Nested iterations may take a long time to process and create performance issues.


Avoid the combination of the following functions in a single expression/sentence

an iteration (for) within the iteration addRelation and removeRelation functions

within the iteration addRelation and removeRelation functions

within the iteration, using Collection Xpaths with filters

The combination of these functions may take a long time to process and create performance issues.


Options: Save the Collection XPath with its filter in a variable and manipulate the variable in the expression.

Perform newcollectionitem and deletecollectionitem functions at the beginning of the expression and not within the iteration. Assign the Collection’s XPath, including its filter, in a variable and manipulate the variable in the Expression.


Avoid handling attachments in rules

Keep in mind that handling directly attachments within business rules will most likely involve working with bytes. In many instances; these attachments will have a large file size, and this could demand more resources by the application resulting in performance inadequacies.


Avoid using CEntityManager method to manipulate entities other than Parameter entities

When use of XPath does not apply for the business requirement and use of CEntityManager and its methods is strictly needed, make sure you always include filters.


Keep in mind that the use of CEntityManager is recommended for performing searches in Parameter Entities when looking for a specific record typically related to a business key (i.e code). Pay special attention when using such methods with virtual Entities, as this may involve tracking down the rule’s response time, and eventually reviewing indexing in the external data source.


Avoid the use of several expressions executed On save  / Avoid On Save expressions with heavy processing workload

On save expressions are executed each time the form is saved or a submit on change is executed. If there are complex calculations or patters that take a long time to process on save, the work portal present performance problems. Avoid using expressions set at the On Save activities that perform heavy processing (that is, executing sophisticated calculations, manipulating multiple information or invoking interfaces or other components).


Having minimal use of On Save expressions will represent better performance when re-loading forms. Use On Save expressions to perform actions which involve how information is displayed when Actions and Validations are not applicable.



Save collection Xpaths in variables and manipulate the variables, instead of manipulating the XPath directly.

Use the newcollectionitem and deletecollectionitem functions outside of the iteration.

Change On Save actions to On exit actions where possible.


Avoid the invocation of Bizagi services in expressions

Some projects tend to use the Bizagi SOA layer within expressions to use Bizagi services. Bizagi services are available to be used directly, without instead of invoking the SOA layer you should use these methods (i.e. CHelper.setEvent).

Calling Bizagi's services from Bizagi processes is considered a bad-practice, and should be avoided as it’ll create an unnecessary overhead.


Invoke Me operations before of cycles.

To have a better performance, when manipulating data inside a cycle, before entering the cycle extract in a variable the Process entity and then use the variable inside the cycle.



var max = 1500;
for (var x = 0; x < max; x++)
      var Newrecord = Me.newCollectionItem("ProcessEntity.RelationshipToTheCollection");
      Newrecord.setXPath ("Column","Value");



var max = 1500;
var PEntity = Me.getXPath("ProcessEntity");
for (var x = 0; x < max; x++)
      var Newrecord = PEntity.newCollectionItem("RelationshipToTheCollection");


Avoid the use of collections to temporary save records

To avoid performance issues, do not use the addRelation method in an activity action of a task if you are about to remove that relation using the deleteRelation method on the next task.


3. Document business rules

Many people can work on a Process during its life cycle. Business rules must be built in the way any person can understand the logic followed and its real purpose. Take into account the following guidelines to make the understanding of business rules a lot easier:


Give expressions a name and description

Being able to identify the purpose of a rule is very important to make sure the understanding of the logic followed by a Process and to enable their reusability along Processes. Always fill the name and description properties of rules in a clear manner that describes its main purpose and any other relevant information.




Comment code

Frequently, when code is used, understanding what someone else wrote before you might be a challenge. Each person has their own point of view and capture businesses logic in rules in different manners.


When you use code in expressions take into account that you will not the only person that needs to understand the logic followed. Use comments to describe the purpose of your code lines in expressions and save time and effort to other people trying to understand the way a condition was modeled.


The following images show an expression with and without comments. Note how easy is to understand the logic of the expression when using comments.