Component library guidelines

<< Click to Display Table of Contents >>

Navigation:  Integration and authentication > Application integration > Custom components >

Component library guidelines


The Component library provides the possibility to extend functionality in Bizagi, by allowing you to include bespoke code to be used in the logic behind of your processes.

You may register in the Component library, any number of components having custom code that is executed directly from Bizagi's business rules.

For more information about this possibility, refer back to Custom components.




Having said the above, it is very common that such custom components connect to external applications, such as legacy systems, other databases or operating system's applications.

Due to this and since coding is not restricted in this point, make sure you consider the following guidelines to minimize risks and potential problems in a bespoke solution:


1. Follow loose coupling practices

It is important that within the design of the functions of your component, you consider best practices and a best design that renders your component as loosely coupled.

This implies that your functions should have well-defined inputs and outputs, and these should never update information directly in Bizagi; but return that information instead so that any update is done within business rules by Bizagi itself.

Making a component that is tightly coupled to Bizagi will not provide good maintainability over time.


2. Design and use promoting maintainability

To avoid an overhead in administrative tasks, avoid including references to assemblies of Bizagi directly in your components.

Otherwise, this will not allow you to upgrade your project's Bizagi version without re-building the component.  


Additionally and for a best maintainability design, consider the use of Bizagi Library rules.

This way your Library rule uses your component, and you can reuse it as a black box, invoked from more than 1 business rule.

When doing this, in the event of changing the function of your component, you will only need to modify that Library rule even when used in more than one point.

The same concept applies if you need to apply XSLT transformations before the component sends out final information to an external system (or after it receives a response from it), in which case you may choose to handle the transformations inside of a Library rule.


3. Log details only for development environment

Make sure you acknowledge that any logging options included in your component are applicable only to the development environment, helpful to provide the means to diagnose issues on specific scenarios when building that component.

Apart from catching and throwing errors appropriately, make sure you can record a detailed log whenever your component's tracing is enabled (recall that logging detail involves a trade-off with performance, and therefore a lot of information should not be recorded at a regular basis unless enabled temporarily).


It is recommended to predefine and design that you can log different levels of tracing: information, warnings or errors.

In addition to type of trace, you should at least print the detailed message, and the date/timestamp.

When logging such detail, consider if you will record this into the server's log (i.e event viewer), to an external database, or to files. If logging to a central log and using a cluster setup, considering printing the server which executes the component.

Evaluate pros and cons in each of the alternatives such as: rights to log in that source, resources consumption (processing overhead and memory use when logging), and the feasibility of monitoring that information (i.e to produce automatic alerts on error logs -critical level).

The above should also allow you to determine the size to split log files if applicable (log rotation), or if you need to log asynchronously or in a parallel manner in order to avoid having the logs hold up your primary operations.



A logger that handles traces should be useful as a reusable class, namely because if your project uses more than 1 component, these all should be able to rely on its utility.


4. Allow administration of parameters

As a best practice, you should have your component read parameters from a central configuration source, and for this, you may rely on the use of Custom options in Bizagi.

This way, through a business rule you send out this information as input parameters, and your component will be able to:

Comply to security practices by ensuring that any authorized credentials (i.e to authenticate to a service) are not hard-coded but managed separately.

Promote best maintainability by presenting a set of parameters, in which it is possible to easily manage information which is subject to change at some point, or be administered frequently (e.g, an external service URL, service name, etc).

Support a configuration which adapts easily to your different project environments (i.e typically Development, Test and Production environments).


5. Perform adequate tests before integrating in Bizagi

Before even integrating the component in Bizagi and executing it from there (specifically from business rules), make sure you carry out proper testing to make sure that:

Your code (i.e, you component's functions) work in each of the predefined use cases that is should support.

Your code works, and it is explicitly tested when targeting a test system so that you can validate its performance (with the test system having similar conditions to those of the production environment).

You consider proper load testing if applicable (stress testing), in order for you to anticipate to how your component can respond under peak load conditions.

Recall that it is your responsibility to both determine and communicate to your team, about the safe usage limits of your component (how it should be used).

It is recommended to avoid having the component perform operations which require a lot of resources (i.e, high CPU, RAM usage, or involving a long time executing), as this could lead to deteriorating performance and causing issues to other processes running on the server at the same time.

In case this is absolutely needed, consider appropriate measures to ensure you can scale out your resources, or handle such operations adequately (using timeouts, closing connections or program instances always and upon unexpected events, etc).

Only when you have verified that your component is stable for its intended specifications, you may test the component by integrating it in Bizagi.


6. Consider its execution through Asynchronous tasks

Once the component is ready to be integrated in Bizagi, configure the execution of your component in Bizagi by relying best on Asynchronous tasks (useful for most scenarios).

This is so because it is likely that your component targets an external service and carries out a significant processing, and this may represent a delay (or an occasional timeout), and it is most appropriate that the component runs as a background task (offline in terms of the Work portal), by having a predefined timeout and number of automatic retries.

This also allows its execution to avoid potential locks in tables which can be at risk when committing a queued transaction, incoming from a manual activity.

Still when using Asynchronous tasks, you will need to carry out proper user acceptance tests with such configuration before rolling it out to a production environment.



Consider that Bizagi manages the transactions and carries out a rollback of tasks and information within Bizagi, should there be a failure at some point.

Make sure you acknowledge this from the very design of your process workflow so that you can narrow down which actions and activities are grouped under a same transaction (and rollback if a failure occurs).

Recall that Bizagi will not rollback whichever operation has been already sent and triggered at an external application.


7. Components must be self-contained

Self-contained in this context will imply that component uploaded via the Component library have everything these need to execute.

These should not look for other drivers, templates or files in specific paths, or any other locally-installed assemblies.


8. Code accountability and security

Ensure that components are built securely in the sense that these do not contain malicious code.

Note that you as a customer, are completely responsible of the developed code and of the custom components uploaded in Bizagi added through this feature.

Bizagi is not to be held responsible for inadequate content of the component, nor for what it does or how it works.



In case that your component targets an on-premises system (web service, database or a “non-cloud ready” system), then it demands the use of a VPN, and customers will need to assess that such integration performs well.


Components in Production

Once a project has been deployed to the Production environment, it will not be possible to delete its components (registered in the Component Library).

Therefore, in the development environment (through Bizagi Studio) edition of components’ information is restricted according to whether or not this component is already deployed on a productive environment.

Edition of a deployed component’s information will consider:

You may edit its registered compilation file (dll assembly).

You may not edit the component’s name or its defined namespace in the Component library.