This page explores the optional use of Logicdoc and several related technologies, using the Place Order / Check Credit
This describes how you solve a familiar Place Order transaction:
How to enhance your existing approach for uncovering Business Requirements
Declaring actual Logic
Preserving the design for Business Users and Maintenance
The basic approach for defining and implementing Business Logic is familiar and business-oriented:
- Uncover the requirements using the "PURL" approach: Processes, Use Cases and Requirements, then
- 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.
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 RequirementsHaving 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 Dialog||Resultant Business Logic|
Is Executable: replaces 10 pages of code
|What does it mean to Check Credit?|
- The Balance can't exceed the Credit Limit
customer.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
customer.balance = Sum(orders.amountUnPaid where isReady)
|What is the AmountUnPaid?|
- Discounted amount - amount paid
purchaseorder.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
purchaseorder.totalAmount = Sum(lineitems.amount)
|What is the Lineitem Amount?|
- Quantity Ordered * Part's Price
lineitem.amount = lineitem.qtyOrdered * lineitem.partPrice
|What if the Price changes after the PO?|
- Ah, right, customer gets the original price
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)
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:
- Obtain the Parent Copy PartPrice
- Derive Lineitem.amount
- Derive PurchaseOrder.amountTotal
- Derive PurchaseOrder.amountDiscounted
- Derive PurchaseOrder.amountUnPaid
- Derive Customer.Balance
- Verify Customer Credit Limit
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
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:
- User Update of
- User Update of
- Several formulas (notes, isReady, amount)
- Check for Bill of Materials Explosion (none here, as you can infer from no subtree)
- Forward chain to adjust the
- Forward chain to adjust the
Purchaseorder (in cache), since this
Purchaseorder is entered as ready
- Which runs its formulas, and
- Forward chains to adjust the
Customers balance, and
- Check the Credit Limit
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.
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).
Sum Adjustments drive
* Adjustments predicated on Purchaseorder.isReady
; // includes node
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.