Overview
The Component library provides the possibility to extend functionality in Bizagi, by allowing you to include custom code to be used in the logic behind your processes.
You may register any number of components with custom code in the Component Library, to be executed directly from Bizagi's business rules.
Recommendations
Having said the above, it is very common that such custom components connect to external applications, such as legacy systems, other databases or operating systems' applications.
Since coding is not restricted in this regard, make sure you consider the following guidelines to minimize risks and potential problems in a custom solution:
1. Evaluate referenced libraries (third-party APIs)
When referencing libraries or APIs from third-party products, make sure you have evaluated if you can build the final component according to the expected system architecture of your production environment (64-bit vs 32-bit).
Consider further configuration possibilities in case your component cannot be produced to comply with your system's architecture, such as producing the functions as Web services instead, separate from Bizagi.
When evaluating such libraries, you need to make sure that any third-party library is supported by the vendor, in order for your project to be able to handle and escalate issues to that vendor (for example, a bug or performance issue produced by those third-party libraries).
2. Follow loose coupling practices
It is important that within the design of the functions of your component, you consider best practices and a sound 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.
3. Design and use promoting maintainability
To avoid an overhead in administrative tasks, avoid including references to assemblies of Bizagi directly in your components.
Otherwise, you will not be able to upgrade your project's Bizagi version without rebuilding 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 the Library rule as a black box, invoked from more than one 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 place.
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.
4. Include logging options
Make sure you include logging options in your component, so that in a production environment it can both provide the means to diagnose issues on specific scenarios and record traces that help you monitor the system's health.
Apart from catching and throwing errors appropriately, make sure you can record a detailed log whenever your component's tracing is enabled (note that logging detail involves a trade-off with performance, and therefore a lot of information should not be recorded on a regular basis unless enabled temporarily).
Predefine and design your component so it can log different levels of tracing: information, warnings, or errors.
In addition to the type of trace, you should at least print the detailed message, and the date/timestamp.
If logging to a central log and using a cluster setup, consider printing the server that executes the component.
Evaluate pros and cons of each alternative such as: rights to log in that source, resource consumption (processing overhead and memory use when logging), and the feasibility of monitoring that information (to produce automatic alerts on critical-level error logs).
Use the above to determine the size at which to split log files, if applicable (log rotation), and whether you need to log asynchronously or in parallel 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 one component, they should all be able to rely on it.. |
5. Allow administration of parameters
As a best practice, your component should read parameters from a central configuration source, such as a configuration file. This way, your component can:
•Comply with security practices by ensuring that authorized credentials (for example, to access a location, path, system, or database) are not hard-coded, but instead placed in the configuration file. This also lets administrators change the configuration and credentials periodically, and store credentials in an encrypted format.
•Promote maintainability by presenting a set of parameters that let you easily manage information subject to change, such as an external server's name, IP address, or URL.
•Allow administrators to turn detailed-trace logging on and off at any time, with different levels of detail as mentioned above, so they can gather detail only when specific issues requiring diagnosis arise.
•Support a configuration that adapts easily to your different project environments, typically Development, Test, and Production.
6. 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 confirm:
•Your component's functions work correctly in each of the predefined use cases they should support.
•Your code has been tested against a test system with conditions similar to those of the production environment, so you can validate its real-world performance.
•If applicable, you have carried out load or stress testing to anticipate how your component responds under peak load conditions.
It is also your responsibility to determine and communicate to your team the safe usage limits of your component (how it should be used). Avoid having the component perform operations that require a lot of resources (high CPU, RAM usage, or long execution times), as this could lead to deteriorating performance and causing issues for other processes running on the server at the same time.
In case this is absolutely needed, consider appropriate measures to make sure you can scale out your resources, or handle such operations adequately (for example, using timeouts, and always closing connections or program instances, including when unexpected events occur).
Only when you have verified that your component is stable for its intended specifications, you may test the component by integrating it in Bizagi.
7. Consider its execution through Asynchronous tasks
Once the component is ready to be integrated in Bizagi, and given that custom code in components will most likely connect to external systems (be it a legacy system, a web service, or even an Excel spreadsheet), configure its execution in Bizagi by preferably relying on Asynchronous tasks (useful for most scenarios).
This is due to the fact that connecting to an external system may represent a delay (or an occasional timeout), and the component should run as a background task (offline in terms of the Work Portal), by having a predefined timeout and number of automatic retries.
This also avoids potential locks on tables that could be at risk when committing a queued transaction originating from a manual activity.
Even so, when using Asynchronous tasks, you still 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 the same transaction (and roll back if a failure occurs).
Bizagi does not roll back whichever operation has already been sent and triggered at an external application. |
Last Updated 10/19/2026 1:39:03 PM