InsertIntoFrom System Method

You can copy one or more source rows to target rows, commonly in a child entity (table or view), using the InsertIntoFrom() method. If the target rows are in a child entity, they require proper initialization of their attributes. The concept is loosely analogous to the Insert Into Select From SQL command.
You can copy one or more source rows to target rows, commonly in a child entity (table or view), using the 
 method. If the target rows are in a child entity, they require proper initialization of their attributes. The concept is loosely analogous to the 
Insert Into Select From
 SQL command.
You can provide these services with ad-hoc Java code, either in API Creator or (better, for re-use!) using rules.
The following examples illustrate the methods:
  • Auditing. 
    A copy of the current row, with provisions for audit conditions and target attribute initialization. The 
     method is useful for auditing and deep copy.
  • Deep Copy.
     Cloning a business object (a master object) and its related objects. For example, create an order by copying an existing one.
  • Bill of Materials Explosion.
     This example illustrates a pattern that is a variant of a deep copy. The 
     method is useful for auditing and deep copy.
    For more information about this example, see the advance Bill of Materials Kit Explosion Example.
The examples are drawn from the 
The most common case of auditing follows the following pattern:
When you alter a source object meeting an audit condition, copy the source object to a child target object, which initializes the appropriate target attributes.
The Audit Salary Changes example follows this pattern. When you alter a source object
meeting an audit condition of salary changes, copy the source object to a child target object
, which initializes the appropriate target attributes to record the old salary. API Creator supplies the following event rule in the
source object:
if (row.baseSalary != oldRow.baseSalary) 
("employee_audits", logicContext);
From the pattern:
  • The 
     source object is the origin of the rule.
  • The audit condition is the salary change.
  • The child target object 
     is the first parameter.
Common to all variations of this pattern is the initialization of created objects.
For more information about the Audit Salary Changes example, see the Audit Transaction Example.
Target Object Attribute Initialization
All variations of the auditing pattern create one or more target objects. A mechanism is required to initialize the attributes of these created objects:
  • Copy like-named attributes from parent.
    API Server copies like-named attributes from the source to the target. In the previous example, this sets the 
  • Set the foreign key.
    Insert Into
     creates one or more children of the source object. Set the foreign key of the created child. In this example, the target child 
     is linked to the 
     source parent. Within a relationship, a child is the table containing the foreign key on the "many" side. For example, Purchaseorder is a child to Customer. PUT/POST JSON provides mechanisms to associate a child with its parents.
    API Server uses the heuristic to introspect the target (child) for an entity-type method that returns the type of the source (parent).
    API Server raises an exception in the rare case where it finds more than one of these methods. For more information about how to associate a child with its parents, see PUT.
  • Copy like-named attributes from source.
    This initialization applies only to the 
     system method. API Server copies like-named attributes from the children rows being copied. In the previous example, the 
     attribute is set.
  • Target object derivation rules.
    Target objects are saved after they are created, which invokes their business logic. You can define formulas on these objects.
Deep Copy
The Deep Copy example is an advanced example used in the 
CA Live API Creator
 For more information about the Deep Copy example, see the Reactive Logic Tutorial.
Copy from Target
The clonePurchaseorder example uses the 
 method. This example provides an interface where the client inserts a Purchaseorder, setting an Entity attribute (clonedFrom) as the source of the deep copy. The functionality is invoked by way of an action rule:
* Deep copy of clonedFrom PO (if non-null) to this new PO.
public void actionClonedFromPurchaseorder() { 
  if (logicContext.verb == Verb.INSERT && logicContext.logicNestLevel == 0 && 
  purchaseorder.clonedFrom != null) { 
    String[] deepCopy = ["lineitems", "lineitemUsages"]
    logicContext, // indicates current object (copy target)
    purchaseorder.clonedFrom, // copy source 
    deepCopy) // collections to copy
Copy from Source
Another design approach is to update an existing order, whose logic create a copy of itself.
You might be tempted to set an transient attribute to trigger the copy operations. This is an excellent idea, but fails since
CA Live API Creator
detects updates which involve only transient attributes, and prunes the update. This prevents logic execution.
Method Operation Illustrated
While there are varying formulations of the 
 system method, the following example illustrates the operation of this system method. The basic idea is to create a series of (target) 
 objects, one for each (source) component object.
The following lists the key players:
  • Parent. The object that issues the 
     system method. In this example, a 
  • Source. The objects being copies. In this example, a list: 
  • Target. The class in which rows are inserted. In this example, also 
     (the created sub items).
API Server iterates over the source list, creating a target instance that is initialized as follows:
  1. The
    method copies like-named attributes from the Parent to the Target. In the example, the target
    is linked to the
  2. Link the Target to the Parent (there is a presumed one-to-many relationship from the Parent to the Target). This links the Target
    to the Parent
  3. Link the Target to the Source. There is an optional one-to-many relationship from the Parent to the Target. The caller specifies whether this linkage exists with the 
     parameter. In the example, this linkage does not occur. The helper used sets the 
     parameter equal to
  4. copyAttributesFromTo
     copies like-named attributes from the Source to the Target. In the example, this copies 
     to the Target (SubItem) 
  5. Target logic is invoked. In the example, lineitems rules compute 
    row.kitNumberRequired * row.kitItem.qtyOrdered
method does not copy primary key attributes. API Server overwrites non-null values. For example, copied Source values override copied Parent values.