User Journeys
A User Journey is the surface through which a participant takes part in an Ormuz Process. It presents actions intended for them, reflects Process progress, and returns validated responses to the same execution context.
The journey follows the Process
The User Journey does not carry parallel business logic. Provider calls, Decisions, Agents, routing rules, and automated steps remain in the Process. When it reaches a User action, the journey presents the interaction to the authorized participant and the Process durably waits for its resolution.
This separation lets one operation combine systems, automation, and human interactions without rebuilding an independent frontend journey engine. Closing the page does not remove Process state: the instance remains the source of truth for what is waiting and what comes next.
The Process reaches a User Action, the journey presents the interaction to the participant, then typed completion lets the same instance resume.
User actions, Forms, and provider interactions
The journey has no screen catalog of its own: it renders interaction nodes present in the Process. The node catalog remains the source of truth for available contracts, including interactions provided by extensions.
| Need | Recommended contract |
|---|---|
| Collect values with a reusable Form | custom_form references a Form resource selected at design time. |
| Build questions during execution | dynamic_form consumes a common.form_spec produced at runtime. |
| Present a choice, consent, or content | Use the Core User Action matching the expected contract. |
| Have a provider interact in the browser | Use the extension node; the Process preserves waiting and resumption around the interaction. |
A dynamic_form may, for example, receive a common.form_spec produced by an Agent activity after analyzing a case. Submission is validated against the form actually presented, then returned as common.form_submission. The dynamic form does not silently create a persisted Form resource.
The User Action is a Process step. The User Journey is the surface that may present several of these actions throughout the same instance.
Progress and business phases
A Process may request several interactions from the same person: identity, company information, clarification, acceptance of terms, etc. The journey projects actual Process state into readable progress instead of maintaining a second UI-side state.
Interactions can be grouped into named phases phases. A phase organizes presentation; it changes neither execution order nor Process rules.
Phases give a business-readable view of visible interactions without creating a second journey engine.
Process Builder can propose phases from interactions already present in the graph. This generation remains a dedicated action and the result remains User Journey configuration.
Participant access bounded to one instance
A participant accesses their journey through a temporary capability linked to one Process instance and one precise participant identity. This access is not a general platform session.
Create a link from an instance
POST /v1/process-instances/{instance_id}/journey-linkThe response notably exposes url, token_id, participant_key and
expires_at. When the use case requires a specific duration, provide
expires_in_seconds when creating the link.
Some business objects, such as a checkout_session, may directly expose the URL corresponding to their associated journey. In every case, scope remains that of the relevant participant and instance.
Do not share this URL as a generic public link. It authorizes the interactions intended for this participant in this Process context, not arbitrary access to objects, the API, or the Console.
The journey can be rendered by Ormuz
Ormuz can host the page presenting the journey. Depending on product context, you may redirect the participant to the supplied URL or embed it in a compatible area of your interface. Hosting is a delivery mechanism; the functional concept remains the User Journey connected to the Process.
| Mode | Behavior | Cas courant |
|---|---|---|
| Redirection | The participant opens the journey URL in the browser window. | Onboarding, checkout, mandate collection. |
| Embedded | The journey is presented in an integrated area when the context and contract allow it. | Operator portal or customer area. |
The response resumes the same operation
When a User Action is completed, its typed outputs become available to following nodes and the same Process instance resumes. Completion emits
process.user_action.completed ; the instance also remains inspectable through observability surfaces and the API.
A redirect or interface acknowledgment does not prove an external effect succeeded. For payment, signature, or provider verification, use the result or business event documented by the relevant integration.
Approvals and human review remain distinct concepts
A Process may also wait for an internal human decision. An
approval_request approval request carries its own aggregation policy, approval_assignmentassignments, deadline, and terminal outcome. This model must not be reduced to a simple User Action.
The end participant's journey may show that the operation is waiting for internal review, but approval authority lives in the request and its assignments. The channel distributing an approval link is separate from the decision itself.