# ProcessContext — Declarations, Parameters, and Scoping

Every process has a single `<ProcessContext>` block nested inside `<Entry>`. It defines the
variables (Declarations) and caller-provided inputs (Parameters) available throughout the flow.

---

## Entry Block Structure

```xml
<Entry>
  <ProcessContext>
    <Declarations>
      <Declaration name="VisitBo"         type="BoVisit" />
      <Declaration name="RescheduleVisitBo" type="BoWizardRescheduleVisit" />
      <Declaration name="duration"         type="String" />
    </Declarations>
    <Parameters>
      <Input name="VisitPKey"        type="DomPKey" />
      <Input name="dateFrom"         type="String" />
      <Input name="Silent"           type="DomString" />
    </Parameters>
  </ProcessContext>
  <EntryActions>
    <!-- LOAD / CREATE / LOGIC actions that run before defaultAction -->
  </EntryActions>
</Entry>
```

**Real file:** `src/Visit/PR/Visit_Reschedule/Visit_RescheduleProcess.processflow.xml` (lines 2-47).

---

## Declarations

`<Declaration>` creates a named, typed variable scoped to the process.

```xml
<Declaration name="VisitBo"   type="BoVisit" />
<Declaration name="TaskList"  type="LoVisitAssessmentTask" />
<Declaration name="isReady"   type="String" />
```

-   `name` — identifier used in `ProcessContext::<name>` paths throughout the process.
-   `type` — the BO, LO, LU, or primitive type. Common primitives: `String`, `DomString`, `DomPKey`,
    `DomInteger`, `DomBool`.
-   Initially `undefined` — must be populated before it is read (by a LOAD/CREATE/LOGIC action).
-   Names must be unique within the process. Duplicate Declaration names are rejected at build time.

**Critical:** any variable that a VIEW action's UI bindings reference must be populated
**before** the VIEW action executes. Leave them uninitialized only if no UI binding touches them.

---

## Parameters

`<Input>` elements under `<Parameters>` are caller-provided values — they are populated when the
process is invoked (via a PROCESS action or a menu trigger).

```xml
<Parameters>
  <Input name="VisitPKey"       type="DomPKey" />
  <Input name="targetClbStatus" type="String" />
  <Input name="ResponsiblePKey" type="DomPKey" />
</Parameters>
```

-   `name` — the key the caller uses in its PROCESS action `<Input name="..." value="...">`.
-   `type` — same type vocabulary as Declarations.
-   Parameters are read-only in the flow (treat them as constants).
-   Accessible via `ProcessContext::<InputName>` — same namespace as Declarations.

**Real file:** `src/Visit/PR/Visit_ChangeStatusWizard/Visit_ChangeStatusWizardProcess.processflow.xml`
(lines 8-12) — `VisitPKey`, `targetClbStatus`, `ResponsiblePKey`.

---

## Accessing Values in Actions

All ProcessContext variables (both Declarations and Parameters) share the `ProcessContext::` prefix:

```xml
<!-- Load a BO using a Parameter value -->
<Input name="pKey" value="ProcessContext::VisitPKey" />

<!-- Load a BO using a BO property (dotted path) -->
<Input name="operatingHoursId" value="ProcessContext::RetailStoreBo.operatingHoursId" />

<!-- DECISION on a BO property -->
<Action name="StatusDecision" actionType="DECISION"
        parameter="ProcessContext::VisitBo.status">

<!-- Return a value into a Declaration -->
<Return name="ProcessContext::VisitBo" />
```

-   Use `ProcessContext::<VarName>` for top-level variables.
-   Use `ProcessContext::<VarName>.<propertyName>` for BO/LO property access.
-   Property names are case-sensitive and must match the BO's `<SimpleProperty name="...">` or
    `<ComplexProperty name="...">` exactly.

---

## Return Clause

`<Return>` maps the output of a LOAD, CREATE, LOGIC, or VALIDATION action into a Declaration:

```xml
<Action name="LoadVisit" actionType="LOAD" type="BoVisit">
  <Parameters>
    <Input name="pKey" value="ProcessContext::VisitPKey" />
  </Parameters>
  <Return name="ProcessContext::VisitBo" />
</Action>
```

-   The target must be a declared Declaration name.
-   For LOGIC actions, the return is whatever the BL method returns.
-   For VALIDATION actions, the framework always writes to `ProcessContext::validationResult`.

---

## Event.\* Variables

Inside an action that handles a VIEW event, the event payload properties are available as
`Event.<propertyName>`. These are transient — they only exist in the action that receives the event.

```xml
<!-- UI fires itemSelected event with pKey -->
<Action name="LoadSelectedItem" actionType="LOAD" type="BoOrder">
  <Parameters>
    <Input name="pKey" value="Event.pKey" />
  </Parameters>
  <Return name="ProcessContext::SelectedOrder" />
  <TransitionTo action="ShowDetail" />
</Action>
```

**Where `Event.*` comes from:** The UI's `<ItemSelectedEvent>` or `<ContextOpeningEvent>` defines
which parameters are sent. See `references/ui-binding.md`.

`Event.*` variables are NOT accessible in other actions — capture them into ProcessContext
immediately if they are needed downstream.

---

## Sub-Process Parameter Passing

When calling a child process via `actionType="PROCESS"`, the parent maps its ProcessContext values
to the child's declared Input names:

```xml
<!-- Parent process calls child -->
<Action name="OpenCockpit" actionType="PROCESS"
        process="Visit::RetailStoreCockpitProcess">
  <Parameters>
    <Input name="MainBO"  value="ProcessContext::VisitBO" />
    <Input name="StoreId" value="ProcessContext::VisitBO.StoreId" />
  </Parameters>
</Action>
```

-   `name` in the parent's `<Input>` must match an `<Input name="...">` in the child process's `<Parameters>` block.
-   Type coercion is not automatic — pass the right type.

When the child process ends with `<ReturnValues>`, the parent's PROCESS action can map them back:

```xml
<ReturnValues>
  <Return name="ProcessContext::CreatedPKey" value="createdPKey" />
</ReturnValues>
```

Here `value="createdPKey"` matches the `name` attribute of the child's END `<Return>`.

**Real file:** `src/Visit/PR/Visit_LoadVisit/Visit_LoadVisitProcess.processflow.xml` (lines 24-29).

---

## Scoping Rules Summary

| Variable kind      | Prefix             | Scope                     | Mutable?                          |
| ------------------ | ------------------ | ------------------------- | --------------------------------- |
| Declaration        | `ProcessContext::` | Entire process            | Yes (LOAD/CREATE/LOGIC writes it) |
| Input Parameter    | `ProcessContext::` | Entire process            | No (caller sets it)               |
| Event property     | `Event.`           | Only the receiving action | No (read-only snapshot)           |
| LOGIC return value | via `<Return>`     | Written to a Declaration  | Yes                               |

---

## Empty EntryActions

When no pre-loading is needed, the EntryActions block must still be present but can be empty:

```xml
<EntryActions></EntryActions>
```

**Real file:** `src/Visit/PR/Visit_ChangeStatusWizard/Visit_ChangeStatusWizardProcess.processflow.xml` (line 14).

---

## Initialization Patterns for UI-Bound Variables

Variables that UI bindings read must be initialized before the VIEW action fires:

```xml
<EntryActions>
  <!-- Initialize a date to today -->
  <Action name="InitDate" actionType="LOGIC" call="Utils.createAnsiDateToday">
    <Return name="ProcessContext::CurrentDate" />
  </Action>

  <!-- Initialize a string literal -->
  <Action name="SetTitle" actionType="LOGIC" call="Utils.identity">
    <Parameters>
      <Input name="value" value="My Title" type="Literal" />
    </Parameters>
    <Return name="ProcessContext::PageTitle" />
  </Action>
</EntryActions>
```

Failure to initialize causes `Cannot read properties of null` errors in the simulator console
immediately upon navigating to the process screen.