SYNTAX

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

newUnique is an unusual operator in that it contains both action and condition logic. When an Action containing this operator is executed, a new <Entity> will be created only if no other entity exists with the characteristics defined by <Expression1> and <Expression2>, etc. <Expression1> and <Expression2> are optional. If no expression is present within the square brackets [..], the newUnique operator will create a new entity only if none currently exists in memory.

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

There is some restriction to using newUnique with associations. newUnique is valid for associations of multiplicity One to One or Many to One, but is invalid for associations One to Many or Many to Many, as illustrated:

The following Rulesheet uses .newUnique to create a new Entity2 element with string1=“item1”, and add it to collection1 only if no existing Entity2 already has  string1=“item1”. A collection alias is not required by the .newUnique operator because it is possible to create a new entity at the root level, without inserting it into a collection. The collection alias used here is required by the += (Associate Element to collection) operator.

Each of three sample tests provides different combinations of Entity1 and Entity2. Input and Output panels are illustrated below: