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.
lac42
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.
In this article:
 
 
3
 
 
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 Kit Explosion Example.
The examples are drawn from the 
Sample
 API.
Auditing Example
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 Employee Changes
 example follows this pattern. When you alter the 
Employee
 source object that meets an audit condition of salary changes, copy the source object to the 
employee_audits
 child target object. This initializes the appropriate target attributes to record the old salary. 
Layer7 Live API Creator
 supplies the following 
Audit Employee Changes
 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 
    employee_audits
     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 Employee Changes
 example, see the Audit Transaction Example.
Target Object Attribute Initialization
The 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.
    Layer7 Live API Creator
     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 
    EmployeeAudit
     child target is linked to the 
    Employee
     parent source. 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.
    Layer7 Live API Creator
     uses the heuristic to introspect the child target for an entity-type method that returns the type of the parent source.
    Layer7 Live API Creator
     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()
     method. 
    Layer7 Live API Creator
     copies like-named attributes from the children rows that it is copying. In the previous example, the 
    Salary
     attribute is set.
  • Target object derivation rules.
    Layer7 Live API Creator
     saves and creates target objects, which invokes their business logic. You can define formula rules on these objects.
Deep Copy Example
The 
Deep Copy
 example is an advanced example.
For more information about the 
Deep Copy
 example, see the Logic Tutorial.
Copy from Target
The 
clonePurchaseorder
 example uses the 
InsertIntoFrom#copyMyAttributesFrom()
 method. This example provides an interface where the client inserts a purchase order which sets the 
clonedFrom
 entity attribute as the source of the deep copy. 
Layer7 Live API Creator
 invokes the functionality 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 creates a copy of itself.
Do no set an transient attribute to trigger the copy operations. This fails since 
Layer7 Live API Creator
 detects updates which involve only transient attributes, and prunes the update. This prevents logic execution.
Method Operation Illustrated
The following example illustrates the operation of the 
InsertIntoFrom()
 method. This example creates a series of 
Lineitem
 target objects, one for each component source object. The parent object issues the 
InsertIntoFrom()
 method. In this example, a 
Lineitem
Layer7 Live API Creator
 copies the source objects. In this example, the 
lineitem.product.components
 list. Target is the class in which 
Layer7 Live API Creator
 inserts rows. In this example, the created 
Lineitem
 subitems.
 
Layer7 Live API Creator
 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 row to the target row. In the example, the target 
    SubItem
     is linked to the 
    Order
     .
    The 
    copyAttributesFromTo()
     method does not copy primary key attributes. 
    Layer7 Live API Creator
     overwrites non-null values. For example, copied source values override copied parent values.
  2. Link the target to the parent (there is a presumed one-to-many relationship from the parent to the target). This links the created 
    Lineitem
     subitem target to the 
    Lineitem
     parent (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. The 
    copyAttributesFromTo()
     method copies like-named attributes from the source to the target. In the example, this copies the 
    ProductBillofMaterials.kitNumberRequired
     source to the 
    kitNumberRequired
     subitem target.
  5.  
    Layer7 Live API Creator
     invokes the target logic. In the example, the lineitems rules compute 
    qtyOrdered
     as:
    row.kitNumberRequired * row.kitItem.qtyOrdered