SYNTAX

<Entity>.new[<Expression1>,<Expression2>…]

creates a new <Entity> with attribute values defined by optional <Expression>. Expressions (when present) should be written as assignments in the form: attribute = value. The attribute used in <Expression> (when present) must be an attribute of <Entity>.

The Operators row in the table of Summary Table of Vocabulary Usage Restriction does not apply. Special exceptions: new may only be used in Action Rows (section 5 in Sections of Rulesheet that correlate with usage restrictions).

The following Rulesheet uses .new to create a new Entity2 element in collection1 when Entity1 has a string1 value equal to 'PO 123-ABC'. An alias is not required by the .new operator, because it is possible to create a new entity at the root level, without inserting it into a collection. The collection1 alias used here is required by the += (Associate Element to collection) operator.

A sample Ruletest provides 2 collections of Entity1. Input and Output panels are illustrated below:

Behavior of the .new operator

The .new operator does not consider implied conditions of non-mandatory attributes (from the initialize expressions) during execution (in other words, a .new operator always fires when explicit conditions are met).

Each initialize expression within a .new… expression will be executed (or not) depending upon implied conditions; that is, if any input to the expression is null, the target attribute remains null. Another case where an implied condition would prevent a .new operator for executing is where the new entity is a target to an association assignment and the parent of that association does not exist.

The following examples assume that all attributes are not mandatory.

  • Rule 1: 
    IF entity1.attr1 > 10 THEN Entity2.new[attr1 = entity1.attr2]
    Executes only if entity1 exists, entity1.attr1 is not null, and entity1.attr1 > 10. The newEntity2.attr1 will be left as null if entity1.attr2 is null.
  • Rule 2: 
    Entity2.new[attr1 = entity1.attr1 + entity1.attr2]
    Will always execute. Entity2.attr1 will remain null if entity1 does not exist, or entity1.attr1 is null, or entity1.attr2 is null.
  • Rule 3: 
    entity1.assoc2 += Entity2.new[attr1 = entity1.attr1]
    Will execute only if entity1 exists. Entity2.attr1 will remain null if entity1.attr1 is null.
  • Rule 4: 
    Entity2.new[attr1 = entity1.assoc1.attr1]
    This action will always fire. entity2.attr1 will remain null if entity1 does not exist, or entity1.assoc1 does not exist, or entity1.assoc1.attr1 is null. Note that this action will fire multiple times if entity1.assoc1 contains multiple entities (once for each entity contained in the entity1.assoc1 collection).