Overview
The Component Library lets you extend functionality in Bizagi; by including custom code to be used in the logic behind your processes.
Through such custom code you can integrate with other applications, or extend any processing and overall operations that your processes execute.
Custom code is included via the Component library by registering and uploading DLL assemblies (components) in Bizagi.
You can include any number of components and then choose to use them directly from Bizagi's business rules.
For introductory information about this feature, refer to Custom components.
Guidelines
It is common for custom components to connect to external applications and services, or legacy systems and databases.
Since the coding in components is not restricted but is up to you to produce through your installed IDE, consider the following guidelines:
1. Follow loose coupling practices
Within the design of the functions of your component, it is important to consider best practices and a design that renders your component as loosely coupled.
This implies that your functions should have well-defined inputs and outputs that never update information directly in Bizagi, but return information instead so that any update is done within business rules by Bizagi itself.
A component that is tightly coupled to Bizagi will not provide good maintainability over time.
2. Design to promote maintainability
To avoid adding overhead in administrative tasks, avoid including references to assemblies of Bizagi directly in your components.
If you include such references, you cannot upgrade your project's Bizagi version without re-building the component.
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, that you can invoke from more than one business rule.
When doing this, if the function of your component changes, you only need to modify that Library rule even if it is used by 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 the Development environment
Make sure any logging options in your component are applicable only to the Development environment, to help you diagnose issues when building that component.
Apart from making sure the component catches and throws errors appropriately, make sure you can record a detailed log whenever your component's tracing is enabled, logging details affects performance, and therefore you should avoid logging a lot of information temporarily, when you need it to investigate an issue.
Design your component so you can enable logging at different levels of tracing: information, warnings or errors.
In addition to reporting the type of trace, you should at least print the detailed message, and the date/timestamp.
When logging in detail, decide whether to save the trace 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 saving to the server which executes the component.
Evaluate the pros and cons in each option, including: rights to log in that source, resource 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).
You should be able to set the size at which to split log files if applicable (log rotation), or if you need to log asynchronously or in parallel to avoid having the log processing your primary operations.
|
A logger that handles traces can be useful as a reusable class, because if your project uses more than one component, they 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 can rely on Custom options in Bizagi.
This way, through a business rule you send this information as input parameters, and your component:
•Comply with security practices by ensuring that credentials (i.e to authenticate to a service) are not hard-coded but managed separately.
•Promote maintainability by presenting a set of parameters, where you can easily manage information which is subject to change, such as an external service URL or a service name.
•Support a configuration which adapts easily to your different project environments (typically, the Development, Test and Production environments).
5. Perform adequate tests before integrating in Bizagi
Before integrating the component in Bizagi and executing it from your business rules, carry out proper testing to make sure that:
•Your code (your component's functions) works 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 and stress testing if applicable to anticipate to how your component responds under peak load conditions.
It is your responsibility to determine, and communicate to your team, the safe use limits of your component.
Avoid having the component perform operations which require a lot of resources (i.e, use high CPU, RAM, or involving a long time), as this could lead to deteriorating performance that causes issues for other processes running on the server at the same time.
If the component absolutely must perform resource-heave operations, consider measures to make sure you can scale out your resources, or handle the operations adequately (using timeouts, closing connections or program instances always and upon unexpected events, etc).
Once you have verified that your component is stable for its intended specifications, you can test the component by integrating it in Bizagi.
6. Consider component execution through asynchronous tasks
Once the component is ready to be integrated in Bizagi, configure the execution of your component in Bizagi using asynchronous tasks (useful for most scenarios).
If your component targets an external service and carries out significant processing, there may be delays (or even occasional timeouts), and it is most appropriate for the component to run as a background task (offline in terms of the Work Portal), with a predefined timeout and number of automatic retries.
Asynchronous execution avoids potential locks in tables which can be a risk when committing a queued transaction from a manual activity.
When using asynchronous tasks, you will need to carry out proper user acceptance tests with the appropriate configuration before adding your component to a Production environment.
|
Bizagi manages transactions and carries out a rollback of tasks and information within Bizagi, if there is a failure at some point. Make sure you take this into account in the design of your process workflow so you can narrow down which actions and activities are grouped under a single transaction (and rollback if a failure occurs). Bizagi will not roll back an operation that has already been sent and triggered at an external application. |
7. Components must be self-contained
Self-contained in this context means that a component uploaded via the Component Library has everything it needs to execute.
Custom components should not look for other drivers, templates or files in specific paths, or any other locally-installed assemblies.
8. Code accountability and security
Make sure that components are built securely and do not contain malicious code.
You as a customer, are completely responsible for the code you develop and for the custom components you upload to Bizagi.
Bizagi is not responsible for inadequate content of the component, for what it does or for how it works.
9. Performance and integration when using a VPN
If your component targets an on-premises asset (such as a system, service or database) which does not offer a public endpoint, then it requires the use of a VPN.
When using a VPN, you need to evaluate beforehand (by carrying out proof-of-concept tests) whether the performance impact of connecting to an on-premises asset from the cloud is appropriate for the requirements of your business applications.
Consider variables such as the volume of data being exchanged with your on-premise data source.
To learn more about a VPN and its requirements, refer to Integration using a VPN.
10. Implementation round-trips
Once business processes have been deployed to the Production environment, you cannot delete the components that are registered in the Component Library that these processes use.
Therefore, consider the following in case that you need to roll-out changes to that process:
•You may choose to create a new version of the process which uses different components, or no custom components.
•Edit the components in the Component Library in the Development environment (through Bizagi Studio) to support the changes you are making to a business process. Then upload a different DLL assembly.
When editing a component, you may not change the component's main details such as its name or namespace.
When you change a custom component, you have to take it through the usual deployment cycles through testing and staging before deploying it to the Production environment.