--- title: Process (PR) — Layer 4 aliases: [PR, process, processflow, orchestration] sources: [sources/sessions/2026-02-18-process-analysis.md, sources/sessions/2026-04-20-process-patterns-and-context-menus.md] last_updated: 2026-04-28 status: draft --- # Process (PR) — Layer 4 Processes orchestrate the application flow — they coordinate BO/LO loading, execute business logic, make decisions, and display UI screens. ## Overview Processes serve as the orchestration layer that: - Coordinate loading and saving of Business Objects and ListObjects - Define navigation flow between screens - Implement decision logic and conditional branching - Execute business logic methods at the right time - Manage process-level state and variables (ProcessContext) - Connect the business layer (BO/LO) to the presentation layer (UI) - Invoke sub-processes and return values to callers ## XML Structure ```xml Visit::InfoUI ``` ## Action Types | Action Type | Purpose | Key Attributes | | -------------- | ------------------------------ | -------------------------------------------------- | | **VIEW** | Display a UI screen | ``, `` | | **LOAD** | Load a BO or LO | `type`, ``, `` | | **CREATE** | Create an empty BO or LO | `type`, ``, `` | | **SAVE** | Persist a BO or LO | `` | | **LOGIC** | Execute a BO/LO/utility method | `call`, ``, `` | | **DECISION** | Conditional branching | `parameter`, ``, ``, `` | | **CONFIRM** | User confirmation dialog | `confirmType`, ``, `` | | **VALIDATION** | Validate a BO | `` | | **PROCESS** | Invoke a sub-process | `process`, ``, `` | | **END** | Terminate process | `` (optional) | ## DECISION Patterns ### On BO Property (Status Routing) ```xml ``` ### On Boolean Flag ```xml ``` ### On Event Property (Context Menu Selection) ```xml ``` ### Multi-Value with Nested Decisions ```xml ``` ## CONFIRM Patterns ### YesNo ```xml ``` ### Ok (Acknowledgment) ```xml ``` ### YesNoCancel ```xml ``` ## Sub-Process Invocation (PROCESS Action) ```xml ``` - `process="Module::ProcessName"` — fully qualified process name - `` maps child process END ReturnValues back to parent's ProcessContext ## END Action (Returning Values to Caller) ```xml ``` ## LOGIC Action Patterns ### Call BO Method with Parameters ```xml ``` ### Call BO Method with Input/Return ```xml ``` ### Utility Methods ```xml ``` ## Event Handling ### VIEW with Multiple Events ```xml Visit::CalendarUI ``` ### Event.\* Parameters Events pass properties from the UI item that triggered them: ```xml ``` UI defines which properties are available via ``: ```xml ``` ## Context Menu Implementation See [[cockpit-cards]] for the cockpit card variant. For standalone lists: ### Process Flow ``` contextMenuOpening event → LOAD Lo*ContextMenu (with Event.* params) → BL builds menu items conditionally → returns to ProcessContext::ContextMenuList contextMenuItemSelected → DECISION on Event.selected → Routes to appropriate action per menu item ``` ### Context Menu LO Structure (empty DS, items built in BL) The DS returns `undefined` — all items are built programmatically: ```javascript var contextMenuItemList = []; contextMenuItemList.push({ id: '0000001', actionImg: 'ExecuteDarkGrey24', actionId: 'Execute', processEvent: 'Execute', actionEnabled: isAllowed ? '1' : '0', actionVisible: '1', }); me.addItems(contextMenuItemList); ``` ### UI Wiring ```xml ``` ## Common Process Patterns | Pattern | Flow | Use Case | | ------------------ | ----------------------------------------------------------------------- | ---------------------- | | **Load & View** | LOAD → VIEW | Display detail | | **Create Wizard** | CREATE → VIEW → VALIDATE → DECISION → SAVE → END | New record | | **Edit & Save** | LOAD → VIEW → VALIDATE → DECISION → SAVE | Edit existing | | **Status Change** | LOAD → LOGIC (check) → DECISION → CONFIRM → LOGIC (change) → SAVE → END | Complete/cancel | | **Lazy Card Load** | CREATE (empty) → CardLoadEvent → LOGIC (load) → LOGIC (info) | Cockpit cards | | **Context Menu** | VIEW (events) → LOAD menu → DECISION → action per case | Right-click/long-press | | **Sub-Process** | PROCESS → ReturnValues → DECISION → continue | Lookup, wizard | ## Process Lifecycle ``` Caller invokes process with parameters ↓ ProcessContext initialized (Declarations empty, Parameters populated) ↓ EntryActions execute sequentially (LOAD, CREATE, LOGIC) ↓ defaultAction in Body executes (typically VIEW) ↓ User interacts → Events trigger → Actions chain via TransitionTo ↓ Process reaches END action (optionally returns values to caller) ``` ## Build-Critical Syntax Rules ### `` Element Is Mandatory Inside ``, the schema requires **both** `` **and** `` as siblings. Omitting `` — even when the process has no work to do before its body — fails the build with validator code `00000001`: ``` Element 'Entry': Missing child element(s). Expected is ( EntryActions ) ``` Use the self-closing form when the process has no entry actions: ```xml ``` Every `.processflow.xml` in `src/` contains an `` element (either populated or self-closing). Confirm with `grep -L '` element accepts only `messageId`. The `messageDefault` attribute does **not exist** and will fail the build: ```xml ``` The message text is defined in localization resources, not inline in the process XML. ### CONFIRM Types | confirmType | Buttons | Case Values | | ------------- | --------------- | --------------------------- | | `YesNo` | Yes, No | `"Yes"`, `"No"` | | `Ok` | Ok | `"Ok"` | | `YesNoCancel` | Yes, No, Cancel | `"Yes"`, `"No"`, `"Cancel"` | ## Runtime Pitfalls ### ProcessContext Variables Must Be Initialized Before VIEW Any ProcessContext variable bound to a UI control must have a value before the VIEW action executes. If a variable is declared but never assigned, UI controls that bind to it will receive `null`, causing runtime crashes — especially for controls that parse the value (CalendarControl, DatePicker, etc.). **Common symptom:** `Cannot read properties of null` errors in the browser console immediately after navigating to a process. **Fix:** Initialize all UI-bound variables in EntryActions using `Utils.createAnsiDateToday`, `Utils.identity`, or direct LOAD/CREATE actions: ```xml ``` This is especially critical when creating a new process entry point (e.g., from a menu item) that doesn't receive input parameters — unlike sub-processes that get values passed from their caller. ## Best Practices | Do | Don't | | ----------------------------------------------------------- | -------------------------------------------------- | | Initialize all UI-bound ProcessContext vars in EntryActions | Leave declared variables uninitialized before VIEW | | Load data in EntryActions (before UI) | Load data after VIEW action | | Use descriptive action names | Name actions "Action1", "DoStuff" | | Use explicit `` | Rely on implicit flow | | Use `type="Literal"` for string constants | Pass raw strings without type | | Use `CaseElse` and `CaseEmpty` in DECISIONs | Leave unhandled cases | | Use only `messageId` on `` | Add `messageDefault` attribute | | Pass only needed Event.\* params | Pass entire BO through events | | Return refresh flags from sub-processes | Force parent to always reload | ## Validation rules The Process validator is the second-heaviest in the modeler — the dependency builder alone is 389 lines. Note the XSD quirk: the root element is ``, not ``, even though the file extension and contract type use the ProcessFlow name. ### Cross-cutting (every contract) - Contract names must be unique workspace-wide — two Process files cannot share the same `@name`. - Files must be readable, well-formed XML with `` as the root element. ### Must - Root element is `` (not ``). - File name ends with `.processflow.xml`. Custom Processes additionally start with the customizing indicator in the file name and the root `@name`. - Every `` must be unique within the Process; so must every `` and `` name in ProcessContext. - Every action reference resolves to an existing action: `defaultAction`, ``, ``, ``, ``, and `` all get resolved by the dependency builder — a dangling name is rejected. - `` and `` must name an existing BO / LO / LU / UIDescription contract. - A `VIEW` action must declare exactly one `` child (and at most one ``). The referenced UIDescription must exist. - For `DECISION` actions, the switch parameter must exist and at least one `` other than `CaseEmpty`/`CaseElse` should exist — single-case decisions are warned. - `` must be one of `barcodeEvent`, `linkLaunchEvent`, `agentforceLaunchEvent`. - Action BO / LO / LU references must resolve, and `@process` attributes on sub-process calls must resolve. ### Must not - At most one `linkLaunchEvent` ExternalEvent per Process — duplicates are rejected. - Attributes that don't apply to the given `actionType` (e.g. LOGIC-only attrs on a LOAD action) are rejected. - Dropdown + paging LO bindings must have `paging="false"` on the LO — otherwise the dropdown pagination misbehaves (warned, not errored, but the runtime is broken). - `LOGIC` actions must not `call` a method from the deprecated engine-methods list — depending on the entry, deprecation is warned or rejected. ### Coerced (silently rewritten) - `actionType` values are case-normalized to their canonical enum — `load` becomes `LOAD`, `view` becomes `VIEW`, and so on. The migrator rewrites the file silently; there's no marker in the XML to tell you it happened. - `xmlns="*.xsd"` on the root is stripped. - `TransitionTo` pointing to the entry action is warned; missing `CaseEmpty`/`CaseElse` on a DECISION is warned / informational. Internal schema reference: `rcg-mobile-dev-agent/wiki/contracts/process-flow.md`. ## Cross-References - [[business-objects]] — Process loads/saves/creates BOs - [[list-objects]] — Process loads LOs and passes to UI - [[user-interface]] — Process binds to UI via ProcessContext; events defined in UI - [[cockpit-cards]] — Cockpit uses complex lazy-load process patterns - [[business-logic]] — Process calls BL methods via LOGIC actions