You can use this manifest to design the forms, actions, and rule boundaries of a MDriven Turnkey line-of-business application before you build individual ViewModels.
A line-of-business application supports people in recurring business work: finding stored information, working through a business case, and producing output. This page describes the minimum interaction patterns used by the MDriven Turnkey user interface.
The purpose of the manifest is to keep business behavior in the model and keep the user interface focused on interaction. For the reasoning behind this separation, see Documentation:ViewModel for Business.
Start with business processes
Identify the business processes before deciding which forms and actions to create. Work with representative domain users to identify:
- Triggers â who or what starts work. For example, a customer requests a delivery.
- Goals â the outcome that person or system needs. For example, the customer needs a delivery arranged.
- Processes â the central steps that achieve the goal. For example, find the customer, create the delivery, and confirm it.
Each important process normally becomes one or more document-form use cases, supported by seek forms and actions. A workshop method for discovering these processes is described in Documentation:Knowing nothing, where to begin.
The three form types
Applications use three kinds of forms. Choose the form type from the user's task, not from the class name alone.
| Form type | Use it when the user needs to | Characteristics | Example |
|---|---|---|---|
| Seek form | Find objects in persistent storage. | Starts without a root object and presents matching objects in a list. It can accept filtering parameters. | Search for customers whose name contains a supplied value, then show the matching customers. |
| Document form | Work on one business case or use case. | Has a root object and can navigate its associations through as many steps as the use case requires. It is interactive. | Open one customer, review its details, and navigate to that customer's orders. |
| Report form | Produce a non-interactive, paginated result. | Expands master-detail combinations at once rather than navigating them with a cursor. | Produce a paginated customer-and-orders listing in which the relevant master-detail combinations are expanded. |
Seek forms
A seek form searches persistent storage and shows the resulting objects in a list. It has two modes.
| Mode | Purpose | Typical entry point | Example |
|---|---|---|---|
| Context-less seek | Let the user search independently, starting with no current object. | A main-menu entry. | A user opens Customer search, enters filter values, and opens a result. |
| Seek and pick | Find one or more objects for a particular assignment. | A modal form opened from a current use case. | While editing an order, the user searches for and selects the customer to assign to its 0..1 customer association. |
Use seek and pick when a combo box is unsuitable because the selectable data quantity is too large. The form returns the selected object or objects to the calling use case when the user closes it with OK.
In the education walkthrough, a Person seeker is used as an example of a seek form, while a Person form rooted in a Person instance is a document form. The walkthrough also demonstrates testing expressions in the OCL Debugger when building search behavior. Watch the walkthrough
Document forms
A document form is designed around a specific use case. Give it a root object, then expose the information and navigation needed to complete that use case.
For example, a document form rooted in an Order can show Order properties and let the user move to associated Customer or order-line information. Do not turn this into a generic all-purpose editor: create the form around the work the user must perform.
Report forms
A report form is for output rather than interaction. It is paginated and non-interactive, and it expands the applicable combinations in master-detail relationships at once.
For example, a report based on customers and their orders can present the customer/order combinations as output. Use a document form instead when the user must select an order, edit it, or navigate step by step.
The four action contexts
Actions express what the user can do. An action can be enabled or disabled according to the state of its context.
| Action kind | Context | Example |
|---|---|---|
| Class action | An object, based on its class. | An action available for a Customer object. |
| Context or use-case action | A document form or seeker form. | An action on an order document that performs work in that order use case. |
| Global action | Neither an object nor a particular form context. | A main-menu action that opens a context-less seek form. |
| Structured action | An action structure such as a sub-menu. | A sub-menu that groups related actions. |
Decide the action context explicitly. For example, a main-menu Customer search is global because it starts without a current customer. An action that changes a selected Customer belongs to the Customer class or the form context where that Customer is being worked on.
Define what happens when an action runs
When you define an action, specify the complete interaction sequence:
- Execute code when the action is invoked, if the use case requires it.
- Optionally open a form.
- If the opened form needs a root object, execute code that assigns that root object.
- Choose whether the opened form is modal.
- If it is modal, optionally execute code when it closes with OK.
For example, an order document can open a modal seek-and-pick form to find a customer. When the picker closes with OK, the optional closing code assigns the selected customer to the order association. This pattern is appropriate when the selection has a specific purpose in the calling use case.
Keep UI validation separate from business rules
Use both of the following rule mechanisms, but give them different responsibilities.
| Mechanism | Purpose | Example |
|---|---|---|
| UI validation | Communicate a rule break in the user's current input. | A seeker input must be convertible to an integer before it is used as an integer search value. |
| State machine with guards | Ensure that objects follow business rules. | A transition is allowed only when its guard is satisfied. |
A UI validation helps the user correct the current input. It does not replace a business rule. Put rules that must hold for the business object in its state machine and guards, so the object follows those rules regardless of which UI path initiated the work.
When an input expression needs checking, test it in the OCL Debugger. For example, the education walkthrough shows that parsing a numeric string produces an integer result, while parsing non-numeric text produces an empty result; use an is-null check to distinguish a missing parse result from the numeric value zero.
Design checklist
Use this checklist for each business process:
- Identify the process trigger, goal, and central steps with domain users.
- Decide whether each user task needs a seek form, a document form, a report form, or a combination.
- For each seek form, choose context-less seek or seek and pick.
- Define the document form's root object and the associations the use case must navigate.
- Define each action's context: class, form/use case, global, or structured.
- Specify action code, any opened form, root-object assignment, modal behavior, and any OK closing behavior.
- Define UI validations for current input feedback.
- Define object business rules with state machines and guards.
- Verify that business logic remains in the model rather than accumulating in UI behavior.