EntityRecordsRecipe

EntityRecordsRecipe is a definition, or recipe, for a set of records of a specific Entity. It can be built and configured in a structured way and supports both filter-based selection and explicit UID exclusion.

You can treat EntityRecordsRecipe as an extended filter that can be applied, for example, when a Context is opened or when records are loaded through LoadEntity.

Technical background

An EntityRecordsRecipe does not hold the records themselves. Instead, it defines them. In practice, it behaves like a filter that can additionally exclude specific UIDs.

Previously, this definition could only be represented by the single UIDs of all corresponding records. This did not scale well because additional or changed records required UID list updates and large Entities could cause performance and memory issues.

EntityRecordsRecipe provides a scalable solution for defining records without indicating every UID. For example, if a table's select all button is checked and the user then unchecks three records, ADITO builds an EntityRecordsRecipe that describes all datasets except those three UIDs.

General usage

The first step is to create a builder object:

var entityRecordsRecipeBuilder = neonFilter.createEntityRecordsRecipeBuilder();

Each method returns the builder object itself, so methods can be chained. The conditions resulting from these methods are combined with a logical AND.

Common methods:

Name	Description
.entity(<Name of Entity>)	Defines the Entity by name, for example .entity("Person_entity"). If this is the only method you call, the definition is all records of the Entity.
.filter(<filter>)	Restricts the record definition to specific filter conditions. The filter can be a FilterGroup object or a JSON string.
.uidsExcludelist(<Array of UIDs>)	Specifies UIDs that must be excluded from the remaining records.
.uidsIncludelist(<Array of UIDs>)	Restricts the definition to records whose UIDs are included in this list. An empty array loads nothing; null means no UID-related restriction.

$sys.selectionsRecordsRecipe

The system variable $sys.selectionsRecordsRecipe holds an EntityRecordsRecipe describing the Entity name and the records selected by the client user.

The content depends on the Entity property recordsRecipeSupported:

• If recordsRecipeSupported is false, selected records are described only through uidsIncludelist. Variables $sys.selections and $sys.selectionRows continue to work.
• If recordsRecipeSupported is true, methods such as filter and uidsExcludelist can also be used, depending on the selection situation.

warning

If recordsRecipeSupported is set to true, variables $sys.selections and $sys.selectionRows are deactivated and hold null. This is intended to make code visible that has not yet been migrated to EntityRecordsRecipe.

---

Examples

Usage in openContextWithRecipe

The following example opens the FilterView of Person_entity with records restricted to persons whose last name starts with B, excluding two specific persons.

var myFilterCondition = neonFilter.createFilterCondition()
.field("LASTNAME")
.searchOperator(neonFilter.SEARCH_OPERATOR_STARTSWITH)
.contentType(neonFilter.CONTENT_TYPE_TEXT)
.key("B");

var myFilter = neonFilter.createFilterGroup()
.addFilterCondition(myFilterCondition);

var myUidList = ["701569b7-d791-4682-89a1-bf26682187af", "a38a19f6-6255-47b0-bbea-138bae2271c4"];

var myEntityRecordsRecipe = neonFilter.createEntityRecordsRecipeBuilder()
.entity("Person_entity")
.filter(myFilter)
.uidsExcludelist(myUidList);

neon.openContextWithRecipe("Person", "PersonFilter_view", myEntityRecordsRecipe,
    neon.OPERATINGSTATE_SEARCH, null, false);

Example of uidsIncludelist

This modified example results in exactly the two records from myUidList:

var myEntityRecordsRecipe = neonFilter.createEntityRecordsRecipeBuilder()
.entity("Person_entity")
.uidsIncludelist(myUidList);

Combining filter and include list

This example combines a filter with an include list. The result is restricted to records that match both definitions.

var myFilterCondition = neonFilter.createFilterCondition()
.field("FIRSTNAME")
.searchOperator(neonFilter.SEARCH_OPERATOR_STARTSWITH)
.contentType(neonFilter.CONTENT_TYPE_TEXT)
.key("C");

var myFilter = neonFilter.createFilterGroup()
.addFilterCondition(myFilterCondition);

var myEntityRecordsRecipe = neonFilter.createEntityRecordsRecipeBuilder()
.entity("Person_entity")
.filter(myFilter)
.uidsIncludelist(myUidList);

neon.openContextWithRecipe("Person", "PersonFilter_view", myEntityRecordsRecipe,
    neon.OPERATINGSTATE_SEARCH, null, false);

Usage in LoadEntity

EntityRecordsRecipe can also define the records to load through LoadEntity. Specify an EntityRecordsRecipe instance as parameter of the LoadRowsConfig method fromEntityRecordsRecipe.

var myEntityRecordsRecipe = (...);

var myLoadRowsConfig = entities.createConfigForLoadingRows()
.fields(["FIRSTNAME", "LASTNAME"])
.fromEntityRecordsRecipe(myEntityRecordsRecipe);

var myRows = entities.getRows(myLoadRowsConfig);

logging.log(JSON.stringify(myRows));

Usage in customized methods

var attributeValue = (...);

var activeStatusFilter = neonFilter.createFilterCondition()
.field("STATUS")
.searchOperator(neonFilter.SEARCH_OPERATOR_EQUAL)
.key($KeywordRegistry.contactStatus$active())
.contentType(neonFilter.CONTENT_TYPE_TEXT);

var affectedContactsRecordsRecipe = neonFilter.createEntityRecordsRecipeBuilder()
.entity("Person_entity")
.filter(activeStatusFilter)
.parameters({"NoCommRestriction_param": "EMAIL"});

AttributeRelationUpdateUtils.addAttribute(
  $AttributeRegistry.deliveryTerm(),
  "Person",
  affectedContactsRecordsRecipe,
  attributeValue);

note

The argument of method .filter can be a filter object or a JSON filter object string. Method .filter only works if method .entity is also used.

Using $sys.selectionsRecordsRecipe

The following example opens the FilterView restricted to the selected records.

var myEntityRecordsRecipeAsJSON = vars.get("$sys.selectionsRecordsRecipe");

logging.log("------> " + myEntityRecordsRecipeAsJSON);

neon.openContextWithRecipe("Person", "PersonFilter_view", myEntityRecordsRecipeAsJSON,
    neon.OPERATINGSTATE_SEARCH, null, false);

$sys.selectionsRecordsRecipe holds the recipe as a JSON string. Convert this string into an EntityRecordsRecipeBuilder object by passing it to the create method:

var myEntityRecordsRecipe = neonFilter.createEntityRecordsRecipeBuilder(vars.get("$sys.selectionsRecordsRecipe"));