1. Getting to the Bottom of the Line-of-Business Application

Use this pattern when you design a line-of-business application in **MDriven Designer** and want a consistent structure for finding data, working through business cases, reporting, and enforcing business rules.

MDriven applications can be described through a small set of recurring concepts: three kinds of forms, four kinds of actions, and two levels of rule enforcement. In **MDriven Turnkey**, the user interface is based on the application's Manifest.

For the broader application-building process, see Build Enterprise Information Systems. For the canonical documentation page, see Documentation:Getting to the bottom of the Line of Business Application.

1. 1. Start with the business objects and rules

Before defining forms and actions, model the information that the application manages:

1. Define classes for the business objects. 2. Add associations to describe how those objects relate. 3. Define the rules that control valid changes. 4. Create forms and actions for the use cases that people must complete.

For example, an order-handling application may include `Customer`, `Order`, and `OrderLine` classes. An `Order` is associated with one `Customer` and with its `OrderLine` objects. The user interface then needs to let users find orders, work with an individual order, and print an order report.

This separation matters:

- The **model** describes the business information and its rules. - A **form** presents information for a user task. - An **action** starts a task, changes information, or opens a form.

See Documentation:Introduction to MDriven Designer for an introduction to modeling classes, associations, and behavior in MDriven Designer.

1. 1. Use the three form types

A line-of-business application uses three distinct kinds of forms. Choose the form type from the user's task rather than from the class alone.

| Form type | Use it when the user needs to | Key behavior | Example | |---|---|---|---| | **Seek form** | Find objects in persistent storage | Searches from no initial object and displays matching objects in a list | Find all orders for a customer or within a date range | | **Document form** | Complete a use case for one business object and its related objects | Starts from a root object and lets the user navigate its associations over as many steps as the use case requires | View an order, its customer, and its order lines | | **Report form** | Produce a non-interactive, paginated output | Expands all master-detail combinations at once; it is non-cursored | Print orders and all their order lines |

1. 1. 1. Seek forms: find objects from persistent storage

A **seek form** searches persistent storage without starting from an already selected object. It presents the matching objects in a list and can be restricted by one or more filtering parameters.

For example, a user may search for `Order` objects using a customer, an order date, and an order status. The result is a list of orders that meet all selected restrictions.

Use seek forms in two modes:

| Mode | Purpose | Example | |---|---|---| | **Context-less seek** | Let the user search for objects as an independent task, typically from the main menu | A user opens the order search and filters orders by date and status | | **Seek and pick** | Let the user find and select one or more objects for a specific use case | A user searches for a customer to assign to an order |

1. 1. 1. 1. Use seek and pick for large selections

• • Seek and pick** is a modal form: the user completes or cancels the selection before returning to the form that opened it. Use it when a user must choose one or more existing objects for a specific purpose.

A common use is setting an association end with multiplicity `0..1`, meaning that an object can be related to zero or one object at that association end. For example, an order can have zero or one assigned customer while it is being prepared.

Use seek and pick instead of a combo box when the possible object quantity is too large for a practical list. The user can filter the candidates before choosing the customer.

1. 1. 1. Document forms: complete a use case from a root object

A **document form** is an interactive form for a particular use case. It has a **root object**: the object from which the use case begins. The form can expose information through the root object's associations in as many navigational steps as the task needs.

For example, an order document form can use an `Order` as its root object. From that order, the user can view or change the associated customer and work with the order lines. The form represents the use case of processing an order, rather than a generic view of every possible class.

Design a document form around the question: *What must the user accomplish for this root object?* If the task is "review and update one order," use an `Order` root object and include the information and actions needed for that task.

1. 1. 1. Report forms: present expanded, paginated output

A **report form** is for non-interactive output. Unlike a document form, it is paginated and expands all combinations in master-detail relationships at once; it is non-cursored.

For example, an order report can show each order together with every associated order line in the report output. The user reads or prints the result rather than navigating through the order and its lines as an interactive document.

Use a report form when the required result is a complete presentation of the data. Use a document form when the user needs to navigate and interact with the data.

1. 1. Put actions in the correct context

An **action** is an operation that a user can execute. Actions differ by the context in which they act. Classify the action first; this makes its availability and behavior clear.

| Action kind | Acts on | Example | |---|---|---| | **Class-based action** | An object based on its class | Execute an action for an `Order` object | | **Context or use-case action** | A document form or seek form context | Execute an action while working in the order document form | | **Global action** | No object or form context, commonly the main menu | Open the order search from the main menu | | **Structured action** | An action organization structure, such as a submenu | Group order-related actions under an order menu |

Any action can be enabled or disabled according to the state of its context.

For example, an action for an order can be unavailable when the order is in a state where that operation is not allowed. Do not treat availability as the only business-rule enforcement mechanism: the object must also enforce its business rules through its state machine.

1. 1. Define what happens when an action runs

When an action executes, it can perform code, open a form, establish a root object for that form, or combine these behaviors.

Use the following design sequence for each action:

1. **Identify the context.** Decide whether the action is class-based, form-contextual, global, or structured. 2. **Define its availability.** Specify when the action is enabled or disabled for the current context. 3. **Define its work.** Determine whether the action executes code, opens a form, or both. 4. **Assign a root object when opening a document form.** Code can determine the object that becomes the opened form's root object. 5. **Decide whether the form is modal.** A modal form returns control only after the user closes it. 6. **Handle an OK result when needed.** When a modal form closes with **OK**, optional code can process the selected result.

For example, an **Assign customer** action on an order document form can:

1. Open a seek-and-pick form for `Customer` objects. 2. Let the user filter and select a customer. 3. Close the modal form with **OK**. 4. Execute follow-up code that assigns the selected customer to the order.

This is the standard pattern for selecting an existing object for an association when a combo box is not appropriate.

1. 1. Enforce rules at both the user-interface and business-object levels

Use two complementary kinds of rules.

1. 1. 1. UI validations communicate current input problems

• • UI validations** communicate rule breaks in the current user input. They help the user correct information while working in a form.

For example, if an order requires a customer before the user can continue with the current input, a UI validation can communicate that the customer has not been set.

UI validation improves the interaction, but it is not the full definition of the business rule.

1. 1. 1. State machines enforce object business rules

Objects implement business rules through **state machines**. A state machine represents the allowed states and transitions in an object's lifecycle. A **guard** is a condition that must be true for a transition to be allowed.

For example, if an order has a lifecycle with states such as prepared and processed, a guard can prevent a transition when the required business conditions are not met. The state machine keeps the rule with the object, regardless of which form or action attempted the change.

Use UI validations to explain input problems to the user. Use state-machine guards to ensure that objects follow the business rules.

1. 1. Apply the pattern: an order-management example

Use the following checklist to turn a use case into forms, actions, and rules:

1. **Model the business objects.** Create `Customer`, `Order`, and `OrderLine` classes, then associate orders with their customer and order lines. 2. **Define the lifecycle.** Add an `Order` state machine that represents the allowed order changes and guards invalid transitions. 3. **Create a context-less seek form.** Let users search persistent `Order` objects by filtering parameters such as customer, date, or status. 4. **Create an order document form.** Use an `Order` as the root object and expose its customer and order lines for the order-processing use case. 5. **Add a seek-and-pick action.** From the order document form, open a modal customer seek form when the user must assign a customer from a large set of customers. 6. **Add a report form.** Create a non-interactive, paginated report that expands orders and their order lines. 7. **Set action availability.** Enable or disable order actions according to the current context and state. 8. **Add UI validations.** Communicate incomplete or invalid current input in the document form. 9. **Keep lifecycle enforcement in the state machine.** Ensure that invalid order transitions remain blocked by guards, not only by the user interface.

1. 1. Design checklist

Before considering a use case complete, confirm the following:

- Does every independent search use a seek form? - Does every selection of existing objects use seek and pick when a combo box cannot handle the quantity? - Does each interactive use case have a document form with a clear root object? - Does each non-interactive, paginated master-detail output use a report form? - Is each action placed in the correct context? - Is each action enabled or disabled based on the current context where appropriate? - Does each modal selection action handle the result when the form closes with **OK**? - Do UI validations communicate current input problems? - Do state machines and guards enforce the business rules for object changes?

For a broader starting point for model-driven development, see Discovering Business Requirements and Training:What is MDriven.