Tutorial‎ > ‎

Place Order

This page explores the optional use of Logicdoc and several related technologies, using the Place Order / Check Credit example.



This describes how you solve a familiar Place Order transaction:

  • Analysis and Design
How to enhance your existing approach for uncovering Business Requirements
  • Implementation
Declaring actual Logic
  • Maintenance
Preserving the design for Business Users and Maintenance

Requirements Definition

The basic approach for defining and implementing Business Logic is familiar and business-oriented:

  1. Uncover the requirements using the "PURL" approach: Processes, Use Cases and Requirements, then

  2. Uncover the Business Logic using a familiar step-wise definition of terms

We offer Logicdoc to support this requirements gathering process.  It is effective even after implementation is complete.   

Logicdoc: optional support for requirements gathering

Logicdoc is entirely optional.  You can use it, and blend it into your own methodology, etc.  

We do recommend explicit capture of Use Case, Requirements and the Logic that implements them - even if this is delayed until implementation or maintenance.

While optional, it is very useful for showing one way of using Business Logic, so logicdoc is used in this documentation.

Uncover Process

For larger systems, you might begin by defining the Business Processes (Work Flows).  

Processes organize the project, and establish good Business User communication.

If you choose to use Logicdoc (optional), a Process corresponds to a Package.

The diagram is helpful, but not required.  You can build the it with Presentation Graphics (as here), or use a Process Management tool.


Uncover Use Case Requirements

We select the Place Order Use Case, and enumerate its requirements (check credit, create Line Item Usage documents, etc).

Capturing this information is invaluable:
  • Defines what must be built

  • Suggests an obvious set of Test Cases

  • Useful input to the Project Plan

If you choose to use Logicdoc (optional)
  • A Use Case corresponds to a Class (typically in the Process Package)

    • Note: this class is not executable; it simply documents and preserves the design

  • A Requirement corresponds to a Method

Elaborate Requirements

Having uncovered the Order Process and Place Order Use Case, we select the Requirement Check Credit, and elaborate it.  To nail down the understanding of the Check Credit Requirement, an Analyst might
  • Have the the following conversation with a Business User in the course of elaborating the Check Credit requirement (left column).  As shown below, this often follows the classic "stepwise definition of terms".  Once a term is identified...

  • Capture the agreed-upon logic for the requirement (right column), in sufficient rigor so it can be implemented.  In particular, we focus on what must be done, not how to implement it (e.g., we would not typically capture pseudocode here - too much "how").

Analysis / Design Process - stepwise definition of terms
Analyst / Business User DialogResultant Business Logic

Is Executable: replaces 10 pages of code

What does it mean to Check Credit?
The Balance can't exceed the Credit Limit
Constraintcustomer.balance < customer.creditLimit
What is the Credit Limit?
Entered by the Sales Department
Assure Data Model contains this attribute, and that an Application exposes it to the Sales Department
What is the Balance?
It is the sum of the unpaid orders marked "ready" by the user
Sumcustomer.balance = Sum(orders.amountUnPaid where isReady)
What is the AmountUnPaid?
Discounted amount - amount paid
Formulapurchaseorder.amountUnPaid = purchaseorder.amountDiscounted - purchaseorder.amountPaid
What is the discount amount?
Platinum customers get a 5% discount off the total

purchaseorder.amountDiscounted = purchaseorder.amountTotal
if (purchaseorder.customer.creditLevel == "P")

purchaseorder.amountDiscounted = purchaseorder.amountTotal * 0.95
What is the AmountPaid?
Let's defer that until we discuss Make Payment, later in the Order Process
What is the AmountTotal?
The total of all the Lineitem Amounts
Sumpurchaseorder.totalAmount = Sum(lineitems.amount)
What is the Lineitem Amount?
Quantity Ordered * Part's Price
Formulalineitem.amount = lineitem.qtyOrdered * lineitem.partPrice
What if the Price changes after the PO?
Ah, right, customer gets the original price

Formula lineitem.partPrice = ParentCopy("Part.price") // no cascade

You can use Logicdoc to record these Requirements:

Focusing on Check Credit, we now elaborate exactly what that means (not how to program it).

You might imagine this documents a joint Analysis session, as described below.

If you choose to use Logicdoc (optional), the Requirement details are simply Javadoc comments.

Note that the Logicdoc processor (an extension to Javadoc) provides business-friendly terminology (e.g. "Requirement", not "Method")

This facilitates Business User / IT communication

We have denoted the rules in the right column. As you can see, Business Logic closely matches the detailed statement of the problem.

Implementation: Executable Requirements

We can specify the Logic for the Requirements in either of two ways, since the system orders the logic automatically based on dependencies, regardless of how you enter it.

Top Down (Requirement Step-wise definition of terms)

Executable Requirements

As you no doubt guessed, the "logic" in the right hand column of the table is fully executable ("executable requirements"),  eliminating traditional design and implementation.

You directly declare your Business Logic by entering rules in the right column into your Business Logic Components.

Logicdoc (optional) can preserve your design:

@see entries provide traceability to the actual logic (serializes relevant logic from multiple Business Logic Components)

Bottom Up (Execution Order)

Alternatively, you may find the more natural design process to be "bottoms up".

State the rules in the order you anticipate they will fire by virtue of processing the transaction, and the Forward Chaining from Logic Execution.


You can imagine this same execution-order Forward Chaining in a graphical manner:

  1. Obtain the Parent Copy PartPrice

  2. Derive Lineitem.amount

  3. Derive PurchaseOrder.amountTotal

  4. Derive PurchaseOrder.amountDiscounted

  5. Derive PurchaseOrder.amountUnPaid

  6. Derive Customer.Balance

  7. Verify Customer Credit Limit


Forward Chaining

That completes the set of rules that implement Check Credit.  Recall that re-use means these rules are also applied to related transactions automatically, such as Delete Order, Pay Order and so forth.

Business Logic executes as an optimized series for Forward Chain events.  For example, inserting/altering a Line Item Amount triggers the system to adjust the related Purchase Order, and to execute its Business Logic (which, in turn, adjusts the Customer Balance and executes its logic, such as the Credit Limit Check).

You can see such Forward Chaining in the Logging information. 

The following is a tree-view of the console log, gathered from a real transaction execution. It illustrates every rule that fired, with tree nesting to reflect Forward Chaining:

  1. User Update of Purchaseorder
  2. User Update of Lineitem
    1. Several formulas (notes, isReady, amount)
    2. Check for Bill of Materials Explosion (none here, as you can infer from no subtree)
    3. Forward chain to adjust the Product
    4. Forward chain to adjust the Purchaseorder (in cache), since this Purchaseorder is entered as ready
      1. Which runs its formulas, and
      2. Forward chains to adjust the Customers balance, and
        1. Check the Credit Limit

Performance Optimizations

Enterprise-class performance is not sacrificed by the simplicity and agility of automation.  The Business Logic Engine is architected to Minimize/Eliminate SQL overhead.
  • Pruning: the Business Logic Engine analyzes updates, and avoids parent access, adjustment and cascade when the referenced data is not changed 

  • Adjustment Logic: maintains aggregates with a single SQL
    Unlike Rete Business Rule Engines that load all the data into memory, or issue aggregate Select sum queries, this assures optimal performance. This is particularly important with there are chained aggegrates.


Automated Business Logic brings substantial value not just in building systems, but also in Iteration and Maintenance.  

Maintenance Automation

Automation of re-use, re-ordering and re-optimization relieves you of these time-consuming tasks: you simply change the rules, and proceed.  Contrast this Declarative automation to a Procedural approach.

Transparency - Preserving the design

Realizing the value of Maintenance Automation requires a contextual understanding of the existing system: its requirement objectives, and how the logic was intended to operate.  The examples above illustrate that you can use Logicdoc to preserve this important information.

Certainly, it is common that capturing such information is sacrificed under the pressures of getting a system into production.  You can use Logicdoc, even after the system has been built, to recover this understanding and contribute this knowledge to the organization.

The sections above illustrate the use of Logicdoc to capture Processes, Use Cases, Requirements, and provide Requirements Traceability to the logic implementation.   The sub-sections below illustrate additional services from Logicdoc.

UMLGraph for Domain Objects

UMLGraph TM - integrated with Logicdoc - provides automated drawing services so you can quickly generate diagrams without any layout effort.

To visualize your Domain Objects, UMLGraph TM provides the diagram shown here.

  • Click an object to see its detail

    • Its attributes

    • Related Domain Objects

Note there is no effort to obtain this diagram - it is generated by default whenever you run Logicdoc.

UMLGraph for Use Case Visualization

For complex Use Case Requirements, you can use the UMLGraph TM services to define views of your Domain Model that will assist colleagues in understanding the rules.

You can define the Domain Objects to be included, as well as the notes, by defining nested classes inside your Use Case Classes as shown below (see the BusLogicIntro sample database for examples).


 * @note Sum Adjustments drive multi-object transaction

 * Lineitem adjusts Purchaseorder, Product

 * Purchaseorder adjusts Customer

 * @note Ready Pattern

 * Adjustments predicated on Purchaseorder.isReady



 class PurchaseorderSave {

private Customer drawCust;  // includes node

private Purchaseorder drawOrder;

private Lineitem drawItem;

private Product drawProduct;



System Logic Map

The Logicdoc process builds the System Logic Map.  This is a tab-delimited text file, which you can import into many tools.  Here, we have pasted its contents into Mindmap TM.  It lists all your Domain Objects, Processes, Use Cases, Requirements, and their Traceability into Logic.

We have closed the nodes for all the Domain Objects and (most of) the Business Logic Components, enabling us to focus on the Requirements and Rules for this Place Order (Purchaseorder_save) Use Case.

Note how this naturally depicts the structure: Processes, Use Cases, Requirements and Logic.