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).
|
•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
•Although entity-list function is handled using XPath, it does not support using the setXPath nor newCollectionItem functions
•To set values not related entities attributes use a temporary attribute. See Obtain and use entity values
|
The following is the syntax of the entity-list function:
Me.getXPath("entity-list('Entity','FilterExpression')",FilterParameters);
The function has two parameters:
•The Entity parameter is the name of the entity to access.
•The FilterExpression 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 = @Code')".
The following can be used as operators in filters:
OPERATOR |
NAME |
EXAMPLE |
|---|---|---|
= |
Equals to |
'Client = @Client' |
<> |
Other than |
'ClientName <> @ClientName' |
> >= |
Greater than / Greater than or equals to |
'Balance >= @Balance' |
< <= |
Less than / Less than or equals to |
'Balance <= @Balance' |
AND |
And |
'Minimum <= @BorrowingCapacity> and Maximum >= @BorrowingCapacity' |
OR |
Or |
'Minimum <= @BorrowingCapacity> and Maximum >= 1000' |
BETWEEN |
Between |
'Balance BETWEEN @lowest AND @higher' |
IN () |
In |
"Balance in (@param1, @param2, @param3)" |
IS NULL |
Equals null |
"CityName IS NULL" |
IS NOT NULL |
Other than null |
"CityName IS NOT NULL" |
•The FilterParameters parameter is used to set the values of the parameters configured in the filter expression. This parameter is a FilterParameters object, on which the parameters to be used in the filter are defined. If the filter does not have filter parameters, do not use this parameter.
The following example shows how to define a FilterParameters object:
var parameters = new FilterParameters();
parameters.AddParameter("@Code", 1);
parameters.AddParameter("@Name", "John");
parameters.AddParameter("@Client", <Request.Client>);
parameters.AddParameter("@IsActive", false);
You can add as many parameters as you need.
How to access the entity's information
The entity-list function is found in the Data navigation category.
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:
//Define the filter parameters
var parameters = new FilterParameters();
parameters.AddParameter("@param1", value1);
parameters.AddParameter("@param1", value1);
.
.
.
parameters.AddParameter("@paramN", valueN);
//Get the identifier of the record
var Entity = Me.getXPath("entity-list('Entity','Filter')", parameters);
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");
}
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.
The image below shows the list of all Medical tests that will be uploaded to the collection.
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.
//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
RequiredTest = Me.getXPath("entity-list('MedicalTest','')");
//Iterate the variable in which the Tests are stored
for(var Counter=0; Counter < RequiredTest.size(); Counter++)
{
//Add each Test to the collection
NewTest = Me.newCollectionItem("Request.Applicant.ApplicantMedicalTests");
NewTest.setXPath("MedicalTest",RequiredTest[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.
The image below shows the list of all Medical tests where only the records marked as required must be uploaded to the collection.
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.
//Evaluate if the collection has items.
if(<count(Request.Applicant.ApplicantMedicalTests)> == 0)
{
//Define the filter parameters
var parameters = new FilterParameters();
parameters.AddParameter("@Required", true);
//Use the entity-list function to get all the Tests to be added to the collection. Filter the records by the required status.
RequiredTest = Me.getXPath("entity-list('MedicalTest','Required = @Required')",parameters);
//Iterate the variable in which the Tests are stored.
for(var Counter=0; Counter < RequiredTest.size(); Counter++)
{
//Add each Test to the collection.
NewTest = Me.newCollectionItem("Request.Applicant.ApplicantMedicalTests");
NewTest.setXPath("MedicalTest",RequiredTest[Counter].getXPath("Id"));
NewTest.setXPath("Delivered",RequiredTest[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.
The Parameter entities store the information to be evaluated in order to upload the applicable records as items of a collection:
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.
//Create a filter to identify the role and the income source of the Applicant
var parameters = new FilterParameters();
parameters.AddParameter("@ApplicantRole", <Applicant.ApplicantRole.id>);
parameters.AddParameter("@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','ApplicantRole = @ApplicantRole and IncomeSource = @IncomeSource')",parameters);
//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.
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.
//Obtain the component and production date of the appliance and build the filter
var parameters = new FilterParameters();
parameters.AddParameter("@Component", <WarrantyRequest.Defectivecomponent>);
parameters.AddParameter("@ProductionDate", <WarrantyRequest.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','Component = @Component and SupplierFrom <= @ProductionDate and SupplierTo > @ProductionDate')",parameters);
//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");
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','FilterExpression'), 'AttributeOfTheEntity')",FilterParameters)
The function's first parameter, is the list retrieved by entity-list explained before. The second parameter, indicates the attribute by which, the collection will be sorted in ascending order. Finally, the last parameter is used to set the values of the parameters configured in the filter expression.
This function follows the same behavior than the sort function of Collection functions.
Last Updated 1/25/2023 11:48:37 AM