Component library guidelines

<< Click to Display Table of Contents >>

Navigation:  Application integration > Custom components >

Component library guidelines

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.

Through such bespoke code you may integrate with other applications, or you may extend any processing and overall operations that your processes execute.

 

Bespoke code that is included via the Component library, is done by registering and uploading DLL assemblies (i.e components) in Bizagi.

You may 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

Having said the above, it is a common scenario that such components connect to external applications and services, or legacy systems and databases.

Given that coding in components is not restricted but up to you to produce through your installed IDE, make sure you consider the following guidelines:

 

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.

 

note_pin

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.

 

note_pin

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.

 

9. Performance and integration when using a VPN

In case that your component targets an on-premises asset (e.g, system, service or database), which does not offer a public endpoint, then it will demand the use of a VPN.

When using a VPN, you will need to evaluate beforehand (e.g. test by carrying out a PoC) whether the performance impact of connecting to an on-premises asset from the cloud is appropriate for the requirements of your business applications.

To do this, 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, it will not be possible to delete the components these processes use, as registered in the Component Library.

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 where it uses no components or it uses a different component.

Edit the components of the Component library from the development environment (through Bizagi Studio), so that you upload a different DLL assembly.

When editing the component, you may not change the component's main details (such as name or its namespace).

Any change done to such components will require that you deploy these changes (and follow usual deployment cycles to testing, staging and production environments in that order).