Overview
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.
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 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. 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 (i.e 64-bit vs 32-bit).
Consider further configuration possibilities in case that your component cannot be produced to comply with your system's architecture (i.e, 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 (i.e, any 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 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.
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, 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.
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 or to 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 (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.
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. |
5. Allow administration of parameters
As a best practice, you should have your component read parameters from a central configuration source, such as a configuration file.
This way, your component will be able to:
•Comply to security practices by ensuring that any authorized credentials (i.e to access a location or path, system or database) are not hard-coded but placed in such configuration file.
This will allow administrators to change the configuration and credentials periodically, and possibly store such credentials in an encrypted fashion.
•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 server's name or IP address, an URL, etc).
•Allow switching on and off at any time, the possibility to leave detailed traces of its execution (and with different levels of detail, as mentioned above).
This will allow administrators to turn on traces and gather detail strictly only when specific issues that need a diagnose arise.
•Support a configuration which adapts easily to your different project environments (i.e typically Development, Test and Production environments).
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 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 make sure 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.
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 (e.g, be it a Legacy system, a Web service, or even an Excel spreadsheet), configure the execution of your component in Bizagi by relying best on Asynchronous tasks (useful for most scenarios).
This is so because connecting to an external system 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. |
Last Updated 2/28/2024 9:58:06 AM