Access entities not related to the data model

<< Click to Display Table of Contents >>

Navigation:  Bizagi Studio > Process wizard > Business Rules > Business rules elements > Expression element >

Access entities not related to the data model

Overview

It is common to require access to Parameter and System entities that are not related to the data model, in order to extract information and use in Xpath expressions.

In such cases, where the entities cannot be accessed directly through Xpath navigation, the entity-list function is employed. The information returned by entity-list is handled as a collection of items. You need to iterate over the collection to access specific information (i.e. the item values).

 

note_pin

entity-list should only be used to get and work with entities that are not related to the case and that CANNOT be accessed directly surfing the data model with Xpath.

 

The following is the syntax of the entity-list function:

 

Me.getXPath("entity-list('Entity','Filter')");

 

The function has two parameters:

The Entity parameter is the name of the entity to access.

The Filter parameter is used at your discretion and it can be empty. This parameter filters the entity according to several conditions.

You can configure Xpaths within your filters, e.g., Entity-list('Customer', 'city.country.code =\"ES\"').

 

The following can be used as operators in filters:

 

OPERATOR

NAME

EXAMPLE

=

Equals to

"Client =" +<Request.Client>

<>

Other than

"ClientName <> \"John\""

>      >=

Greater than / Greater than or equals to

"Balance >= 600"

<      <=

Less than / Less than or equals to

"Balance <= 600"

AND

And

"Minimum <= " + <Request.BorrowingCapacity> + " and Maximum >= " + <Request.BorrowingCapacity>

OR

Or

"Minimum <= " + <Request.BorrowingCapacity> + " or Maximum >= 1000"

BETWEEN

Between

"Balance BETWEEN 200 AND 500"

IN ()

In

"Balance in (500, 600, 700)"

IS NULL

Equals null

"CityName IS NULL"

IS NOT NULL

Other than null

"CityName IS NOT NULL"

 

note_pin

When using string-type values, recall to set this value between backslash and double quote characters, i.e Name = \"John\".

 

The entity-list function is found in the Data navigation category.

 

EntityManager1

 

How to access the entity's information

Recall the returned entity is handled as a collection of items. The entity collection must be stored in a variable, in order to iterate over it.

To identify how many items the entity collection has, use the size() command.

 

Iterate with a for loop through each item in the following way:

 

 //Get the identifier of the record

 var Entity = Me.getXPath("entity-list('Entity','Filter')");

 for(var Counter=0; Counter< Entity.size();Counter++)

 {

         //Get the attribute value of the record

         var Surrogate= Entity[Counter].getXPath("Id");

         var Value= Entity[Counter].getXPath("AttributeOfTheEntity");

 }

 

Sorting the entity's information

The entity's information is sorted by its entity id, that is to say, in the same order in which records were created.

To customize the order in which the information will be retrieved, use the sort function.

 

The sort function has the following syntax:

 

Me.getXPath("sort(entity-list('Entity','Filter'), 'AttributeOfTheEntity'");

 

The function's first parameter, is the list retrieved by entity-list explained before; whilst the second parameter, indicates the attribute by which, the collection will be sorted in ascending order.

This function follows the same behavior than the sort function of Collection functions.

 

Example with no filter

An Onboarding Process requires the applicant to perform some medical tests prior to signing a contract.

These Medical Tests are saved in a Parameter entity, and are uploaded to a collection when the case requires them.

 

The following is the Data Model of the Onboarding Process.

 

EntityManager3

 

The image below shows the list of all Medical tests that will be uploaded to the collection.

 

EntityManager2

 

1. Go to the fourth step of the Bizagi Process Wizard. Add an expression to the On Enter action of the Task where the tests will be uploaded.

 

2. Write the code of the business rule to add the records of the Tests as elements in a collection.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

 

EntityManager4

 

//Evaluate if the collection has items

if(<count(Request.Applicant.ApplicantMedicalTests)> == 0)

{

 //Use the entity-list function to get all the Tests that will be added to the collection        

 Test = Me.getXPath("entity-list('MedicalTest','')");

 //Iterate the variable in which the Tests are stored

 for(var Counter=0; Counter < Tests.size(); Counter++)

 {

         //Add each Test to the collection

         Test = Me.newCollectionItem("Request.Applicant.ApplicantMedicalTests");

         Test.setXPath("MedicalTest",Tests[Counter].getXPath("Id"));

 }

}

 

Example with a simple attribute filter

We will continue to use the Onboarding Process where the applicant must perform medical tests prior to signing a contract.

These Medical Tests are saved in a Parameter Entity, and are uploaded to a collection when the case requires them. Only required tests should be added to the collection, and the associated Required attribute flagged.

 

The following is the Data Model of the Onboarding Process.

 

EntityManager3

 

The image below shows the list of all Medical tests where only the records marked as required must be uploaded to the collection.

 

EntityManager2

 

1.  Go to the fourth step of the Bizagi Process Wizard and create an On Enter action of the Task where the tests will be uploaded.

 

2. Write the code of the business rule to add the records of the required Tests as elements to a collection.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

 

EntityManager5

 

//Evaluate if the collection has items.

if(<count(Request.Applicant.ApplicantMedicalTests)> == 0)

{

//Use the entity-list function to get all the Tests to be added to the collection. Filter the records by the required status .

 Test = Me.getXPath("entity-list('MedicalTest','Required = true')");

//Iterate the variable in which the Tests are stored.

 for(var Counter=0; Counter < Tests.size(); Counter++)

 {

//Add each Test to the collection.

         Test = Me.newCollectionItem("idRequest.idApplicant.ApplicantMedicalTests");

         Test.setXPath("MedicalTest",Tests[Counter].getXPath("Id"));

         Test.setXPath("Delivered",Tests[Counter].getXPath("Required"));

 }

}

 

Example with complex filter

A bank requests certain documents for a Loans request, according to the Applicant's income and job role.

The Documents that apply for each case are stored in a Parameter entity called Documents per Applicant. For each case, there must be a rule that analyzes the Applicant's properties and add the applicable documents to a collection.

The Documents per Applicant entity is not related to the data model. In order to obtain the records, you must use entity-list to iterate the entity and associate the documents with a collection of the data model.

 

Below is the data model of the case.

 

EntityManager10

 

The Parameter entities store the information to be evaluated in order to upload the applicable records as items of a collection:

 

EntityManager7

 

EntityManager8

 

EntityManager9

 

1.  Go to the fourth step of the Bizagi Process Wizard. Add an expression to the On Enter action of the Task where the documents will be uploaded.

 

2. Write the code of the business rule to add the records of the Documents table as items to a collection.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

 

EntityManager6

 

//Create a filter to identify the role and the income source of the Applicant

FilterDocs = "ApplicantRole = " + <Applicant.ApplicantRole.id>

+ " and IncomeSource = " + <Applicant.IncomeSource.id>;

//Use the entity-list function to get all the Documents to be added to the collection. Filter by the required status.

DocsXApplicant = Me.getXPath("entity-list('DocumentXApplicant','"+FilterDocs+"')");

 

//Iterate the variable in which the Documents are stored.

for(Count =0; Count < DocsXApplicant.size(); Count++)

{

 //Add each Document to the collection

 IdDocument = DocsXApplicant[Count].getXPath("Document");

 ApplicantDocument = Me.newCollectionItem("Applicant.Documents");

 ApplicantDocument.setXPath("Document",IdDocument);

 ApplicantDocument.setXPath("Required",DocsXApplicant[Count].getXPath("Required"));

}

 

Example using dates in filter

A company dedicated to producing appliances uses Bizagi to manage warranties of their products. When a customer reports a problem with an appliance, a technician evaluates and determines which component is causing the appliance to fail. Once the defective component is identified, the company proceeds to request warranty to the supplier of this component. As suppliers changes along time, records are kept in order to identify the period of time in which a supplier provided an specific component. This way, based on the production date of the appliance, the company has traceability and can easily identify to which supplier the warranty has to be requested.

 

Below is the data model of the case.

 

EntityManager11

 

The historical records of suppliers are stored in the SuppliersTrace entity. It contains the supplier, the component provided and the period of time in which that supplier provided that component (supplier from (date), supplier to (date)).

 

To obtain the supplier that provided a specific component in a specific date we will use the entity-list function using as parameters the SuppliersTrace entity, and a filter that identifies the component and the date in which the component was supplied.

 

1.  Go to the fourth step of the Bizagi Process Wizard. Add an expression to the On Enter action of the Task where the supplier is identified.

 

2. Write the code of the business rule to obtain the supplier to which warranty for the component has to be requested.

Select the Get entity with entity-list function from the Data navigation category to access the Parameter entity.

Note how the filter using dates is defined.

 

EntityManager12

 

//Obtain the component and production date of the appliance

var Component = <WarrantyRequest.Defectivecomponent>;
var ProductionDate = <WarrantyRequest.ProductionDate>;

//Convert the date to a string in the specified format

ProductionDate =ProductionDate.ToString("yyyy-MM-dd");

//Build the filter

var Filter = "Component = "+ Component + " and SupplierFrom <= " + "\"" + ProductionDate + "\"" + " and SupplierTo > " + "\"" + ProductionDate + "\"";

//Use the entity-list function to get all the Suppliers that meet the Filter. We expect only one record because the effective period of a supplier is unique for a component.

var Suppliers = Me.getXPath("entity-list('SuppliersTraces','"+Filter+"')");

//Obtain the record of the unique supplier of the list and assign it to the attribute of the process

<WarrantyRequest.SupplierToClaim>=Suppliers[0].getXPath("Supplier");