Creating APIs‎ > ‎Logic‎ > ‎Rule Types‎ > ‎

InsertIntoFrom System Method

It is a common requirement to copy one or more source rows to target rows. A corollary requirement is that the created target rows are usually children of the source rows, and require proper initialization of their attributes. The general concept is loosely analogous to the Insert Into Select From SQL command.

You can use the following services:
  • Auditing. This is a copy of the current row, with provisions for audit conditions and target attribute initialization.
    System method: InsertChildFrom

The Audit Transaction Example is a common example.

  • Deep Copy. It is a common requirement to "clone" a business object, meaning a "master" and its related objects. For example, a customer might like to create a new order by copying an existing one.
    System method: copyMyAttributesFrom
  • Bill of Materials Explosion. This pattern is a variant of a deep copy and can be solved this pattern with a few rules.
    System method: insertChildrenFrom

The Bill Of Materials Explosion example is an advanced example used in the Live API Creator training.

You can provide such services with ad-hoc Java code, either in API Creator or (better, for re-use!) using rules. But this pattern is so prevalent that this is simply reinventing the wheel. You can save cost and increase agility for copying with the re-usable InsertIntoFrom system method. You can then invoke these from action rules under the appropriate conditions. This class provides the set of similar services.

Examples

Auditing

The most common case of auditing follows this 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. Live 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 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 parentWithin 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).

    Note: An exception is raised in the rare case where more than one such method is found.

    For more information about how to associate a child with its parents, see PUT.

    • Copy like-named attributes from source
    This 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 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 service. 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.

    Important! You may be tempted to set an transient attribute to trigger the copy operations. This is an excellent idea, but fails since Live API Creator detects updates which involve only transient attributes, and prunes the update. This prevents logic execution.

    Insert Into Operation

    While there are varying formulations of the InsertIntoFrom system method, the following example illustrates this system method's operation. 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. copyAttributesFromTo 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 (role name: kitItem).
    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 = 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

    Note: copyAttributesFromTo does not copy primary key attributes. Non-null values are over-written. For example, copied Source values override copied Parent values.