With InRule v5.0.11, a new “Deep copy” option has been added to the Copy Entity, Copy Collection and Add Collection Member actions.
Before going any further, however, let me provide a definition of “deep copy”. And…to fully grasp that concept, the definitions of “by reference” and “shallow copy” are useful as well.
- By reference: Creates a new reference at the target location pointing to the source of the copy operation. This results in no new Entities being created.
- Shallow copy: Creates a new Entity at the target location, copying over all of the Entity’s primitive Field values. However, the child Entity Field and Entity Collection values keep a reference to the existing Entities in the source location. This results in one new Entity being created.
- Deep copy: Creates a new Entity at the target location, copying over all of the Entity’s primitive Field values and creates new instances for each of the child Entity Fields and Entity Collections in the source location. If an Entity is found that has already been copied, the copied Entity reference will be used. This results in a new Entity being created for each unique Entity in the source.
Prior to version 5.0.11, these actions did not allow a deep copy of entities. The Copy Entity action always performed a shallow copy, and the Copy Collection and Add Collection Member actions allowed for the selection between by referenceand shallow copy only.
With this enhancement, all of the options for these three actions have been made consistent. Each will display a setting called “Entity copy mode” with the 3 options of “By reference”, “Shallow copy” and “Deep copy”.
Why should you care, you may ask? Well, it depends on your particular rule scenario and entity structure. But let’s take, for example, a claim. A claim has various primitive fields like Claim Number (text), Loss Date (datetime), etc. But it may also have an entity collection of transactions. If you have a need to copy a claim, without a deep copy option, you would either get only a reference to the source claim and all of its child fields (by reference), or a new claim but with references to all of the source claim’s transactions (shallow copy). With a reference to an object, whenever the original object is updated, those updates are visible in the reference as well, because it’s the same underlying object instance. With a deep copy option, you not only get a new claim, but also all new transactions for that claim.
What option you need depends on your situation.
Using the entity structure below, I’d like to take you through each action and show you how the results will differ for each copy mode option.
Entity structure
In each of the examples below, the image displayed from irVerify will show the instance IDs of the objects in grey text on the right.
You’ll want to pay attention to these values 
in each of the examples to see how the copy options affect it.
Copy Entity action
Example: Copy the Claim’s Claimant1 field to Claimant2.
By reference
results
No new entity instances were created.
Shallow copy
results
A new instance of the Claimant was created, but the address entity fields (PhysicalAddress and MailingAddress) are simply references.
Deep copy
results
A new instance of the Claimant was created. In addition, new instances of the address entity fields were created. When it encountered the MailingAddress field, it realized that entity was already copied, so it used the copied entity reference rather than creating another new entity. This results in a “mirror image” of the original entity.
The default for new actions will be “Shallow copy” as this was the default behavior of the Copy Entity action prior to this enhancement.
Copy Collection action
Example: Copy the claim’s PendingTransactions collection members into the ApprovedTransactions collection.
NOTE: These options are only applicable when copying one Entity Collection to another Entity Collection. (Complex Collections are always deep copied)
By reference
results
No new entity instances were created.
Shallow copy
results
New instances of the Transactions were created, but the address entity fields (TransactionSourceAddress and TransactionTargetAddress) are simply references. NOTE: The PendingTransactions collection had duplicate references to Transaction instance 2. When it encountered the duplicate Collection Member instance, it realized that member was already copied, so it used the copied reference rather than creating another Collection Member. (* see below for a special note about how this behavior changed from previous versions)
Deep copy
results
New instances of the Transactions were created. In addition, new instances of the address entity fields were created. When it encountered the duplicate entity instances (both within the PendingTransactions collection and of the child entity address fields), it realized that entity was already copied, so it used the copied entity reference rather than creating another new entity. This results in a “mirror image” of the original entity.
The default for new actions will be “By reference” as this was the default behavior of the Copy Collection action prior to this enhancement (previous “Copy Link” option selected).
Add Collection Member
Example: Add the first member of the claim’s PendingTransactions collection to the ApprovedTransactions collection.
NOTE: For this action, a collection member may be either created new or created by copying from an entity field or specific entity collection member. Only if “Existing” is selected will these copy mode options be applicable.
When choosing to source the new collection member from an existing entity field or entity collection member, there cannot be any field values specified in the “Initial field values” section as all of the values will come from the specified source.
When using an entity collection member as the source in “Existing entity field”, you may not see the expected options in the “…” pick list. You must refer to the specific member of the collection by using the CollectionName(index).
By reference
results
No new entity instances were created.
Shallow copy
results
A new instance of the Transaction was created, but the address entity fields (TransactionSourceAddress and TransactionTargetAddress) are simply references.
Deep copy
results
A new instance of the Transaction was created. In addition, new instances of the address entity fields were created. When it encountered the duplicate instances of the address entity field, it realized that entity was already copied, so it used the copied entity reference rather than creating another new entity. This results in a “mirror image” of the original entity.
The default for new actions will be “By reference” as this was the default behavior of the Add Collection Member action prior to this enhancement (previous “Copy Entity” option unchecked).
*Note about behavior change
With this enhancement, an issue was resolved with the Copy Collection functionality. In prior versions, when the “Copy entity” option was selected (which equates to the new “Shallow copy” option) and duplicate Entity Collection Members were encountered, new instances were created for each. For example, copying a collection with members 1, 2 and 2 would previously create members 3, 4 and 5. This has been resolved so that new instances are only created for each unique instance in the source, resulting in a “mirror image” behavior. In the example of members 1, 2 and 2, it will now be copied as 3, 4 and 4.
In Summary
I hope this deep dive (pun intended) into the Entity Copy Mode options will help you make the right decisions when writing your rules in the future.
