How to configure virtualization for related entities
From Business Process Management, BPM and Workflow Automation Wiki | BizAgi BPMS
<keywords content="keywords"> virtualization, related entities, relations, foreign key, virtualization example, crm, foreign, virtual relationship, relationships in virtualization </keywords>
Contents
|
How to configure virtualization for multiple (related) entities
Overview
A process will often need to access information residing in an existing repository, with the objective to present this information and manage it as part of the business process in Bizagi.
For this type of data integration Bizagi presents a feature called Virtualization, which is a data-level integration mechanism to synchronize the information between the process data model in Bizagi and the existing repository.
The data access to the external source is performed on-demand while in the process' execution, either to read or write data.
Throughout virtualization, more than 1 external table from the existing repository can be mapped into the data model of Bizagi's process, so that the external data source information is included in Bizagi's solution in a tranparent way.
When working with more than 1 external table (virtualizing multiple tables), it is common to find that these external tables have a relationship between them (typically, a foreign key). In order to configure properly this virtualization scenario, in Bizagi we may use the virtualization wizard and carry out an additional step to include the correct mapping for the relationship between the related entities.
The following article illustrates how to configure the related entities' virtualization settings and mappings so that Bizagi uses the foreign key relationship to automatically obtain the information from the existing relationship (a SQL "JOIN").
Example
In this article we will present as an example, a process in Bizagi which virtualizes 2 entities from an existing CRM repository (a sample database in SQL Server). The virtualized entities correspond to the tables: Customer and Customer_Account (with a 1-n relationship).
Our process in Bizagi is called Product Request, and it will allow an end user to search for an existing customer or to register a new one (by using a join search dialog). This is done in the process' first activity called Register Request.
When the end user searches and selects an existing customer, the customer's existing accounts (and their information) will be automatically presented in Bizagi. To achieve this, we will describe the procedure which involves: configuring the virtualization for the entities, including their relationships, specifying the relationship mapping, and defining the form for the Register Request activity.
Procedure
Configuring the virtualization from the existing repository
First, we will use Bizagi's virtualization wizard to create the virtual entities in our Bizagi project from the ones existing in our CRM database.
To do so, go to the Process wizard step 2 (Data model):
Launch the virtualization wizard to configure all the information necessary, related to our CRM database:
Include information to define and name your CRM as an "external system" in your Bizagi project:
Specify the connection details for the connection provider:
Bizagi will present the available tables and views for virtualization. Select (check) the entities you wish to virtualize:
Bizagi will create the entities that correspond to the virtualized external tables:
When finished, click on "Finish".
Including relationships for the virtual entities' use in the process
Now we will proceed to include relationship attributes in our Bizagi data model to represent and handle the relationship between these tables in the CRM database.
From our previous step, our Product Request data model will now show the 2 recently created virtual entities: Customer and Customer_Accou (shortened from Customer_Account).
Make sure you have included an entity reference type attribute in the process entity (called "Product Request" as well):
This way, we are setting that in our Product Request, we will be able to create a Customer or select an existing one.
Edit the Customer virtual entity so that we can specifically include a relationship between our Customer and Customer_Accou entity.
We will say and design, that one Customer has one or more accounts (records in Customer_Accou). For this definition, we include an attribute of type Collection:
We will see that Bizagi now includes attributes to represent these entities relationship.
Specifying the mapping for the relationship
Once our process data model in Bizagi is completed, we will include an additional mapping detail for the relationship we created in our previous step.
To do this, go to the Modules view and select the Systems module.
Navigate through the System and Provider as defined in the virtualization configuration ("MyCRM" and "MyProvider1"); and scroll down until you see the listed virtual entities: Customer and Customer_Accou.
Right-click on Customer_Accou and select the "Add attribute to virtual" option:
Include the "Customer" attribute created from the relationship in the Customer_Accou entity, and map it to the CRM's database corresponding source (that is, type in the name of the column for this information).
Notice that this is a key part in the configuration, mainly since what it is important is that we explicitally set that Bizagi's relationship attribute in the Customer_Accou entity (the entity having the foreign key in the 1-n relation) is mapped to the Customer key.
This means that whether if the virtualization was configured using the wizard or not (done manually in the systems module), the mapping in the end should consider that there is one attribute in Bizagi's virtual entity for the corresponding source column, and another attribute in Bizagi's virtual entity for the relationship with another entity in Bizagi.
In the example above, idCustomer will be showing the id of the Customer source table, while Customer is the attribute which has a Related entity in Bizagi, for the relationship in Customer_Account.
We have now included the additional mapping for the relationship in Bizagi, to set which column determines the relationship in the CRM database.
Using compound primary keys
Bizagi supports virtualization of entities which have compound primary keys in the existing repository (more than 1 column making up the primary key in the external data source).
To configure this type of scenarios, in Bizagi we have only to make sure that all the mapped attributes that correspond to the primary key, are included as business key for the virtual entity definition.
To review or modify (include) the definition of which attributes in the virtual entity are mapped to the source's primary key, you may right-click on the virtual entity and select its properties (in the Systems module).
In this Customer_Accou example, only the "accountnumber" attribute is set as the business key for the Customer_Accou entity (there is no compound primary key):
Take into account that this can be modified according to the source, by choosing more than 1 attribute as the businessKey attributes.
Compound primary key example
Using as an example an Customer_Products table in an external data source, we could have its primary key be defined by both ProductId and CustomerId attributes:
This means that in Bizagi, we would need to ensure that for this entity, the businessKey includes both attributes:
|
Note: If an additional entity is virtualized which references this compound key (a foreign relationship to the Customer_Products entity), then it is required to map in the virtual entity's relation attribute the source as "attribute1, attribute2". |
Defining the form for the Register Request activity
Finally we will include in our Register Request activity's form, the fields of our entities to: allow selection of a customer and automatically show the associated accounts for that customer.
To do this, go to the Process Wizard view and select the third step (Define forms):
Include the Customer attribute of your Process entity into the Register Request form. By default, this will be rendered as a Join search dialog.
Include as well the Accounts collection of the Customer entity into your form. By default, this will be rendered as a grid. Set the grid as non-editable, as well as the attributes in the Customer_Accou entity.
Make sure you define a Display form for the Join search dialog (also, a display attribute in the Join search dialog's properties and an Add form to allow registration of new customers):
Save the form and proceed to run your process:
In the work portal you may create a new Product Request case and in its first activity (Register Request) search for an existing customer:
Its associated accounts will be automatically shown in the grid below:
At this point, we have finished virtualizing entities from our external CRM database as related entities to be used transparently in our Product Request process!
Additional considerations
The following considerations follow best practices for virtualization use in Bizagi.
All attributes virtual
When using virtualization, it is recommended that all of the attributes of the virtual entities in Bizagi's data model are mapped to their corresponding source. This means that there should not be attributes in a virtual entity without mapping to the external source (this does not apply for collection-type attributes).
In case the process' data model design in Bizagi requires additional attributes for a virtual entity, then these should be created in another entity which has an entity reference attribute to the virtual entity.
In the following data model example of a Bizagi process, the additional attributes "Observations" and "Total Accounts" for a customer are created in another entity ("Customer_AdditionalInfo") which references the virtual Customer entity:
SQL Server's port
When using SQL Server as an external data source (database), it is recommended that the database's instance configuration has an explicit TCP port:
When configuring virtualization using Bizagi Enterprise JEE edition, if this TCP port (on which SQL Server's instance starts up, as mentioned previously) is different than 1433 (which is the default), then the port number needs to be specified explicitly in the data provider's properties.
To include this configuration, you will need to include a property called "SQLServerDBPort" with the value of the SQL Server instance's TCP port:
This las configuration is only required for the Bizagi Enterprise JEE edition and in its development environment.
JEE-production environment configuration
To configure virtualization or replication in a Test or Production environment using a JEE Application server (applies for Bizagi Enterprise JEE edition), an additional step is needed so that the external data source is configured at the Application server's level.
To carry out this step, ensure that your JEE Application server is already configured to work with Bizagi.
Take into account that this step is only needed in an environment different than the Development environment (in which case, Bizagi Studio automatically configures the JBoss 7.1.1 Application server's data source).
View How to configure virtualization and replication in a JEE Application server.
Related Articles
<comments />
