<< Click to Display Table of Contents >> Navigation:  Low-code Process Automation > Studio Cloud - Authoring environment > Bizagi Studio > Process wizard > Business Rules > Bizagi Functions > CEntityManager

Overview

This article offers an overview of the CEntityManager and CEntity objects, which are employed in scripting business rules to access entity information without relying on XPaths. The CEntityManager object proves beneficial for retrieving records and general information directly stored in Bizagi's entities. Simultaneously, the CEntity object provides functions for performing operations with entity information.

 

CEntity Manager functions

The CEntityManager object functions used to retrieve or modify entities and their attributes are:

 

 

 

CEntity functions

The CEntity object functions used to perform operations with entities' information are:

 

 

Using CEntityManager functions

This section offers a series of examples illustrating how to utilize the various CEntityManager functions explained earlier:

 

1. ExistsEntityInstance

To verify the existence of a record or entity instance within the mLiability Master entity based on a given surrogate key value (1356), employ the following syntax:

 

var bEntityInstanceCheck = CEntityManager.ExistsEntityInstance("mLiability", 1356);

 

After execution, the result is true if an instance with SurrogateKeyValue = 1356 exists; otherwise, it returns false.

 

Alternatively, you can perform this validation using the entity-list function:

 

var oLiabObject = Me.getXPath("entity-list('mLiability','idmLiability = 1356')");
var ObjectSize = oLiabObject.size();

 

If the ObjectSize value is greater than zero, it means that the instance exists.

 

2. GetEntityFromPath

You need to access the mLiability Master entity using the mLiabilityCollect.kmSingleLiability XPath.

 

 

The function requires the Id (SurrogateKeyValue) from the root entity (i.e., mLiabilityCollect).

 

The syntax is as follows:

 

var iLiabSGTKValue = <mLiabilityCollect.Id>;//SurrogateKeyValue from root entity

 

//To obtain the mLiability object linked to the root entity

var oEntFrmPathObjct = CEntityManager.GetEntityFromPath("mLiabilityCollect.kmSingleLiability", iLiabSGTKValue);

 

//To obtain the amount from the mLiability object linked to the root entity

var cLiabilityAmount = oEntFrmPathObjct.Attributes["cAmount"].Value;

 

//To obtain the surrogate key value from the mLiability object linked to the root entity

var iLiabilitySGKV = oEntFrmPathObjct.SurrogateKeyValue;

 

 

3. setAttrib

In the mLiability Master entity, you need to update the value stored in the sLiabilityStatus attribute for a record, using the record's surrogate key value (idmLiability = 901). The current value is Pending Collection and you must update it to Collected.

 

 

The syntax is as follows:

 

CEntityManager.setAttrib("mLiability", 901, "sLiabilityStatus", "Collected");

 

 

Alternatively, if the entity record's Id is available or has been previously retrieved, you can use the CHelper.setAttrib function as follows:

 

CHelper.setAttrib("mLiability", 901, "sLiabilityStatus", "Collected");//Sets a value in the sLiabilityStatus attribute for the record with idmLiability = 901

 

4. getAttrib

In the mLiability Master entity, you need to obtain the value stored in the DebtorID attribute for a record, using the record's surrogate key value (idmLiability = 901).

 

The syntax is as follows:

 

var DebtorID = CEntityManager.getAttrib("mLiability", 901, "iDebtorID");

 

As an alternative, you can use the entity-list function:

 

var oLiability = Me.getXPath("entity-list('mLiability', 'idmLiability = 901')");
for(var j = 0; j < oLiability.size(); j++){
  var oLiabRecord = oLiability.get(j);
  var DebtorID = oLiabRecord.getXPath("iDebtorID");
}

 

Likewise, if the entity record's Id is available or has been previously retrieved, you can use the CHelper.getAttrib function as follows:

 

var DebtorID = CHelper.getAttrib("mLiability", 901, "iDebtorID");//Gets the DebtorID for the record with idmLiability = 901

 

Using CEntity functions

This section offers a series of examples illustrating how to utilize the various CEntity functions explained earlier:

 

1. GetEntityList

You need to iterate over the records in the mPendingLiability entity that have been selected for processing. The filtering criteria is based on a single attribute bSelect4Processing.

 

 

To retrieve all the records matching the filtering criteria, you must use the GetEntityList function. The syntax is as follows:

 

var oPndngLblty = CEntityManager.GetEntity("mPendingLiability").GetEntityList("bSelect4Processing","true", "","");

 

Alternatively, you can retrieve the records using the entity-list function:

 

var oPndngLblty = Me.getXPath("entity-list('mPendingLiability','bSelect4Processing = true')");

 

When using a filter with more than one criterion:

 

 

The syntax should be as follows:

 

var oEntEntityNameList = CEntityManager.GetEntity("mLiability").GetEntityList("", "", "dDueDate BETWEEN '2023-05-01' AND '2023-06-30' AND iUncollected = 1", "");

 

You can also retrieve the records using the entity-list function:

 

var oPndngLblty = Me.getXPath("entity-list(mLiability,' dDueDate BETWEEN '2023-05-01' AND '2023-06-30' AND iUncollected = 1')");

 

2. GetEntityListCount

You can count the number of existing records in an entity using the GetEntityListCount function. Use filtering conditions to count the number of matching records or do not include filtering criteria to get the total number of records.

 

 

Option 1 – with filters

var oLiabCllct = CEntityManager.GetEntity("mLiabilityCollect");
var iLiabCollectCount = oLiabCllct.GetEntityListCount("bLiabDataLoad = true");

 

Option 2 – without filters

var oLiabCllct = CEntityManager.GetEntity("mLiabilityCollect");
var iLiabCollectCount = oLiabCllct.GetEntityListCount("");

 

Filters

When constructing filters, you can use operators and dates as follows:

 

Operators

You can use the following operators in filters:

 

 

Dates

Dates saved in the data model via the Work Portal are stored in the database with minutes and seconds, given that all dates are recorded as Date-Times. Therefore, when accessing these dates using CEntityManager, you must convert the date into a format that can be easily read.

 

To illustrate this scenario, let's consider a Purchase Request process where purchase orders are generated once a supplier is chosen. All purchase order details, including payment dates, are entered in the Work Portal.

 

Now, imagine another process called Accounts Payable, where you need to identify all pending purchase orders scheduled for payment in the next week. To achieve this, you must utilize CEntityManager to select from the Purchase Orders entity all orders that remain unpaid and have an upcoming payment date.

 

The required code for the expression that selects from the specified entity (i.e., the Purchase Orders entity) and filters by date is:

 

FirstDate = Convert.ToDateTime(<Process.Date1>);

DateToFilter = CHelper.FormatDate(Date, "yyyy-MM-dd HH:mm:ss");

ListOfRecords =

CEntityManager.GetEntity("EntityToFilter").GetEntityList("","","DateAttribute = '" + DateToFilter + "'","");

 

3. Add new record(s)

The use of CEntityManager functions for adding or modifying records of Parametric entities is discouraged. This process should be exclusively performed through Bizagi Studio, the Work Portal (Admin>Process Management>Entities), or Bizagi's API.

 

As a best practice, adding records to Master entities for immediate persistence in the database should be approached after thorough analysis of business case scenarios. This analysis should consider all potential impacts, whether positive or negative, on data and subsequent behaviors in activities, rules, forms, integrations, etc. It is recommended to add records to Master entities using Activity or Event forms, business rules (expressions), upon receiving a response from an external system through a web service call, or when an external system calls Bizagi's OData or SOA Layer.

 

There might be scenarios where adding records to Master entities using expressions is deemed necessary (e.g., due to performance considerations or complex business scenarios). In such cases, these scenarios should be reviewed meticulously by the project team.

 

Example A

You need to create new records in two different Master entities, considering the previously configured one-to-many relationship. The mLiabilityCollect entity can be associated with multiple records (one or many) of the mPendingLiability entity.

 

 

To create the new records and link them, follow the next steps:

•Step 1: Add the new record in the mLiabilityCollect entity and store the new record’s SurrogateKeyValue.

 

//Step 1
var oLiabCllctEntity = CEntityManager.GetEntity("mLiabilityCollect");
oLiabCllctEntity.Attributes["bLiabDataLoad"].Value = false;
oLiabCllctEntity.Attributes["bDeleteBadCorrupt"].Value = false;
oLiabCllctEntity.Add();
var iLiabCllctSgtKeyValue = oLiabCllctEntity.SurrogateKeyValue;

 

•Step 2: Add the new record in the mPendingLiability entity.

 

//Step 2
var oPndngLblty = CEntityManager.GetEntity("mPendingLiability");
oPndngLblty.Attributes["bSelect4Processing"].Value = false;

 

•Step 3: Link the newly created record in mPendingLiability with the new record in mLiabilityCollect by assigning the SurrogateKeyValue stored in Step 1 to the attribute kmLiabilityCollect_FK. This attribute must be configured during the creation of the one-to-many relationship between these two entities.

 

//Step 3
oPndngLblty.Attributes["kmLiabilityCollect_FK"].Value = iLiabCllctSgtKeyValue;
oPndngLblty.Add();

 

Example B

You need to create records in two different master entities, namely mLiabilityCollect and mLiability, which are linked through a 1:1 relationship, as illustrated in the data model below:

 

 

To create the new records and link them, follow the next steps:

•Step 1: Add the new record in the mLiability entity and store the new record’s SurrogateKeyValue in a temporary variable (iLiabilitySgtKeyValue).

 

//Step 1

var oPndngLblty = CEntityManager.GetEntity("mLiability");
oPndngLblty.Attributes["cAmount"].Value = 1250;
oPndngLblty.Attributes["iUncollected"].Value = 1;
oPndngLblty.Attributes["sLiabilityStatus"].Value = "Uncollected";
oPndngLblty.Attributes["dRegistrationDate"].Value = DateTime.Today;
oPndngLblty.Add();
var iLiabilitySgtKeyValue = oPndngLblty.SurrogateKeyValue;

 

•Step 2: Add the new record in the mLiabilityCollect entity and link the new mLiability record from Step 1.

 

//Step 2

var oLiabCllctEntity = CEntityManager.GetEntity("mLiabilityCollect");
oLiabCllctEntity.Attributes["bLiabDataLoad"].Value = false;
oLiabCllctEntity.Attributes["bDeleteBadCorrupt"].Value = false;
oLiabCllctEntity.Attributes["kmSingleLiability"].Value = iLiabilitySgtKeyValue;//Link new mLiability record
oLiabCllctEntity.Add();

 

Example C

Consider the mLiability Master entity as an example. Prior to executing the automated business process tailored for collecting liabilities (refer to the image below), it is necessary to populate their values. To accomplish this, an Excel sheet containing all the pertinent information is employed. A Bizagi process enables you to upload the Excel file, and upon the submission of the case creation, a new record is generated in the mLiability entity for each row in the Excel sheet.

 

 

 

The syntax is as follows:

 

var bFileExists = <exists(mLiabilityCollect.uExcelDataLoad1)>;
if(BAIsTrue(bFileExists)){
oDataFile = Chelper.GetValueAsCollection(<mLiabilityCollect.uExcelDataLoad1>);
  for(f = 0; f < oDataFile.size(); f++){
    oFile = oDataFile.get(f);
    oFileData = oFile.getXPath("Data");
    FileContent = Chelper.GetDataTableFromWorkSheetAsString(oFileData, 0);
iRowsCount = FileContent.Rows.Count;
for(g=0; g < iRowsCount; g++){
    oCEntLiability = null;
        var oExcelRow = FileContent.Rows[g]; //Object containing excel row data
var oCEntLiability = CentityManager.GetEntity("mLiability");//Returns an empty object
 
//Setting values to the new mLiability record
oCEntLiability.Attributes["cAmount"].Value = Chelper.ToInt( oExcelRow["cAmount"]);
oCEntLiability.Attributes["iUncollected"].Value = oExcelRow["iUncollected"];
oCEntLiability.Attributes["iDebtorID"].Value = oExcelRow["iDebtorID"];
oCEntLiability.Attributes["sLiabilityStatus"].Value = oExcelRow["sLiabilityStatus"];
oCEntLiability.Add();//Function call to create the new mLiability  record
}
}
}

 

 

4. Update record(s)

You are required to update all records with an empty registration date in the mLiability entity with the current date (DateTime.Today). To accomplish this, you need to obtain an object containing all existing records that meet this specific condition, iterate over this object, and execute the update function for each record.

 

 

The syntax is as follows:

 

var dToday = DateTime.Today;
var oLiability = CEntityManager.GetEntity("mLiability");
oLiabRecords = oLiability.GetEntityList("", "", "dRegistrationDate is null", "");//Returns object with records matching the filtering criteria
for(u = 0; u < oLiabRecords.Length; u++){
  var oRecord2Update = oLiabRecords [u];
  oRecord2Update.Attributes["dRegistrationDate"].Value = dToday;
  oRecord2Update.Update();//Function call to update the record
}

 

5. Delete record(s)

Consider that in the mLiability entity there are records lacking registration or due dates. Consequently, you must delete these records from the entity. To accomplish this task, you can:

•Use the GetEntity function to retrieve all the records in the entity.

•Use the GetEntityList function with a filter to keep only the records with empty dates.

•Use the GetEntityListCount function to count the records to be deleted. This count is then used to define the number of iterations.

•Use the Delete function to delete each record matching the filtering criteria.

 

The syntax is as follows:

 

var oLiability = CEntityManager.GetEntity("mLiability");
Filter = "dDueDate is null OR dRegistrationDate is null";//Filter to retrieve mLiability records with empty dates
var oBadRecords = oLiability.GetEntityList("", "", Filter, "");//Returns object with records matching the filtering criteria
var iRecordCount = oLiability.GetEntityListCount(Filter);
for(var r = 0; r < iRecordCount; r++){
    oRecord2Delete = oBadRecords[r];
    oRecord2Delete.Delete();//Function call to delete record
  }

 

6. SetAttribValue

You need to update the Amount value in the mLiability entity using the mLiabilityCollect.kmSingleLiability Xpath.

 

 

The function requires the Id (SurrogateKeyValue) from the root entity (i.e., mLiabilityCollect).

 

The syntax is as follows:

 

var idLiabCllct = <mLiabilityCollect.Id>;
 
var oDbtrRcrds = CEntityManager.GetEntity("mLiabilityCollect", idLiabCllct);//Gets the specific record from mLiabilityCollect based on the SurrogateKeyValue provided
 
oDbtrRcrds.SetAttribValue("kmSingleLiability.cAmount", 560);//Updates the Amount value

 

7. GetAttribValue

You need to retrieve the DebtorID value in the mLiability entity using the mLiabilityCollect.kmSingleLiability XPath.

 

 

The function requires the Id (SurrogateKeyValue) from the root entity (i.e., mLiabilityCollect).

 

The syntax is as follows:

 

var idLiabCllct = <mLiabilityCollect.Id>;
 
var oDbtrRcrds = CEntityManager.GetEntity("mLiabilityCollect", idLiabCllct);//Gets the specific record from mLiabilityCollect based on the SurrogateKeyValue provided
 
//Gets the DebtorID value in the related mLiability record
var iDbtrID = oDbtrRcrds.GetAttribValue("kmSingleLiability.iDebtorID");

Last Updated 12/22/2023 2:13:43 PM