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.
lac31
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 provide these services with ad-hoc Java code, either in API Creator or (better, for re-use!) using rules.
Examples
The following examples illustrate the methods:
  • Auditing. 
    A copy of the current row, with provisions for audit conditions and target attribute initialization. The 
    insertChildFrom()
     method is useful for auditing and deep copy.
    Method:
    InsertChildFrom()
  • Deep Copy.
     Cloning a business object (a master object) and its related objects. For example, create an order by copying an existing one.
    Method
    :
    copyMyAttributesFrom()
  • Bill of Materials Explosion.
     This example illustrates a pattern that is a variant of a deep copy. The 
    insertChildrenFrom()
     method is useful for auditing and deep copy.
    Method
    :
    insertChildrenFrom()
    For more information about this example, see the advance Bill of Materials Kit Explosion Example.
The examples are drawn from the 
Sample
 API.
Auditing
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
Employee
meeting an audit condition of salary changes, copy the source object to a child target object
EmployeeAudit
, which initializes the appropriate target attributes to record the old salary. API Creator supplies the following event rule in the
employees
source object:
if (row.baseSalary != oldRow.baseSalary) 
 
SysLogic.insertChildFrom
("employee_audits", logicContext);
From the pattern:
  • The 
    employees
     source object is the origin of the rule.
  • The audit condition is the salary change.
  • The child target object 
    employee_audits
     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 
    Salary
     attribute.
  • 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 
    EmployeeAudit
     is linked to the 
    Employee
     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 
    insertChildrenFrom()
     system method. API Server copies like-named attributes from the children rows being copied. In the previous example, the 
    Salary
     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
 training.
 For more information about the Deep Copy example, see the Reactive Logic Tutorial.
Copy from Target
The clonePurchaseorder example uses the 
InsertIntoFrom#copyMyAttributesFrom()
 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.
*/
@Action
public void actionClonedFromPurchaseorder() { 
  if (logicContext.verb == Verb.INSERT && logicContext.logicNestLevel == 0 && 
  purchaseorder.clonedFrom != null) { 
    String[] deepCopy = ["lineitems", "lineitemUsages"]
    
InsertIntoFrom.copyMyAttributesFrom
 ( 
    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 
InsertIntoFrom()
 system method, the following example illustrates the operation of this system method. The basic idea is to create a series of (target) 
Lineitem
 objects, one for each (source) component object.
The following lists the key players:
  • Parent. The object that issues the 
    InsertIntoFrom()
     system method. In this example, a 
    Lineitem
    .
  • Source. The objects being copies. In this example, a list: 
    lineitem.product.components
    .
  • Target. The class in which rows are inserted. In this example, also 
    Lineitem
     (the created sub items).
API Server iterates over the source list, creating a target instance that is initialized as follows:
  1. The
    copyAttributesFromTo()
    method copies like-named attributes from the Parent to the Target. In the example, the target
    SubItem
    is linked to the
    Order
    .
  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
    SubItem
    to the Parent
    Lineitem
    (the 
    kitItem
     role).
  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 
    aLinkToSource
     parameter. In the example, this linkage does not occur. The helper used sets the 
    aLinkToSource
     parameter equal to
    false
    .
  4. copyAttributesFromTo
     copies like-named attributes from the Source to the Target. In the example, this copies 
    ProductBillofMaterials.kitNumberRequired
     to the Target (SubItem) 
    kitNumberRequired
    .
  5. Target logic is invoked. In the example, lineitems rules compute 
    qtyOrdered
     as:
    row.kitNumberRequired * row.kitItem.qtyOrdered
The 
copyAttributesFromTo()
method does not copy primary key attributes. API Server overwrites non-null values. For example, copied Source values override copied Parent values.