Triggers and events

The launchers

A ProcessLauncher has its own key, Working Revisions, and Releases. Its versioned contract carries the type, the processreference, exposed inputs, mapping, and, depending on type, the event or User Journey presentation. The activeflag, public URL, and grants remain environment-local.

The launcher is independent from the Process: changing its contract creates a ProcessLauncher Revision, never a Process Revision. Conversely, saving a new Process Working revision does not change the launcher contract; only resolution of a :working reference can change the Process Revision used by a future launch.

Versioned Process reference

The ProcessLauncher Revision directly references the target Process using the shared artifact syntax: customer_onboarding:working, customer_onboarding:latest, a Release, or an exact digest. There is no longer a parallel revision_mode on the launcher.

resolved_process_definition_revision_id indicates the Process Revision currently resolved. An invocation never remains floating after it starts: Ormuz records the exact Process Revision and ProcessLauncher Revision on the attempt before any effect.

Launcher types

For checkout, onboarding, dispute and return, Ormuz knows the expected system input contract. When several active definitions offer the same type for a merchant, the context creating the resource must explicitly select the definition; Ormuz never arbitrarily chooses among candidates.

Event triggering

A launcher event listens to exactly the event_type configured for its merchant. Upon receiving a matching event, Ormuz applies its input_mapping, creates an instance, and preserves in start_source the identities of the event and launcher that originated the start.

Each event contract declares values available to the process: generic event context, resolved platform objects, snapshots, projections, or extension objects depending on type. The event name alone can never invent a resource not declared by that contract.

This list is deliberately illustrative. See the platform event catalog and extension-specific event pages in extensions for the exhaustive reference.

Hosted-experience link

The launcher journey publishes a stable URL intended for a person, with its identity in the path /launcher/:id. Opening this link displays an entry page: no process instance is created until the person explicitly chooses to start. After confirmation, Ormuz creates a new instance and opens the hosted experience for the primary participant without reloading the document: the SPA replaces the URL with canonical User Journey access and continues directly.

Its public presentation is distinct from the administration name: presentation.title is required and presentation.description optional on the ProcessLauncher Revision. These texts explain what the person is about to do; no generic fallback or internal name is exposed.

Presentation and input contract are versioned with the launcher. The reference process independently determines whether future accesses follow Process Working or remain tied to an immutable snapshot.

This mode fits self-service journeys, for example onboarding accessible from a marketing site. No onboarding_case or other prior business object is required by the launcher: the process may start without external input, collect useful information, then create business objects at the appropriate time.

Query parameters are not technical routing for the launcher: they belong entirely to the external contract, for example campaign, language, or channel. Only non-sensitive scalar values may be exposed this way. Unknown parameters are rejected, and knowing a business-object identifier never by itself grants the right to resolve or expose it in the experience.

Dedicated API endpoint

The launcher api publishes a POST URL specific to one process and a reduced input contract. Use it when a partner must be able to trigger one precise operation without receiving the general process_instance:run right or the ability to choose another process definition.

Every key must have the permission process_launcher:invoke on the merchant and and an explicit grant on this launcher. From Process Builder, the action Create a dedicated key performs both operations atomically with the minimum scope: no other business permission is granted and the grant targets only this endpoint. The secret is shown only once. Using an existing key remains available as an advanced option.

The JSON body accepts only fields declared by the exposed contract; launcher-fixed values cannot be overridden by the caller. The Process Revision is resolved from the launcher's versioned reference process : the caller never chooses the revision.

POST /v1/process-launcher-invocations/pln_123
Authorization: Bearer ormuz_live_…
Idempotency-Key: partner-request-123

{
  "reference": "partner-order-8472",
  "country": "FR"
}

Idempotency-Key is required. The first durable creation responds with the instance identifier and status; replaying the same request with the same key resolves that instance, while reusing the key with a different payload is rejected. A new key represents a new request even when business data is identical.

This endpoint creates no hosted-experience access and grants no general read access to instances. If the process later contains a human interaction, that access must be produced by the business mechanism defined by the process, independently from the API launcher.

Wait for an event in an existing instance

Triggering a new process and suspending an existing process are two different primitives. wait_for_platform_event waits for an event for one precise resource, then resumes the same instance with outputs declared by that event contract.

wait_for_platform_events applies the same principle to a typed collection and completes only when every expected target has produced its event. Use these nodes when the event belongs to continuity of an already-started instance; use a launcher when the event must create an independent execution.

Launch a process through API

An external system can explicitly start an active definition with POST /v1/processes/:id/runs. Input is prepared and validated against the input schema of the Working snapshot used for the instance.

POST /v1/processes/prd_123/runs

{
"input": {
  "invoice": "inv_abc123",
  "amount_threshold": 5000
}
}

This endpoint can also request bounded synchronous waiting through its parameter wait. This mechanism does not change instance identity or execution model: it only changes how the caller waits for the Run result.

Launcher input mapping

input_mapping transforms startup context into fields of theinput_schema. For an event, every source must be provided by that event's canonical contract and be compatible with the type expected by the process. An unknown or incompatible source is rejected during configuration.

System launchers have a canonical mapping for their primary object — checkout_session, onboarding_case, dispute or return. The process may declare additional fields only when they are optional or have defaults compatible with this trigger.

For journey and apilaunchers, every process input may be supplied by a declared external field, a launcher-fixed value, or the process default. A mandatory input not satisfied by any of these prevents activation. The contract is closed: undeclared JSON or query fields are never implicitly merged into process inputs.

For journey and api, you explicitly choose for each input whether it is supplied by the caller, fixed by the launcher, or left to the process default. The exposed contract may therefore deliberately be smaller than the completeinput_schema contract; a launcher-fixed field cannot be overridden by the caller.

Idempotency and deduplication

When the same event is delivered more than once, event launch uses a deduplication identity combining the event and launcher. The same event therefore does not create several instances for one launcher while legitimately being able to trigger several different launchers.

An API Endpoint uses an Idempotency-Key provided by the caller. The hosted-experience link uses a temporary start attempt so a double click or lost response does not create two instances. In both cases, this guarantee protects technical repetition; it never infers that the same email, business reference, or identical inputs represent the same business request.

Do not transpose these guarantees to direct launch POST /v1/processes/:id/runs : that endpoint represents, by default, an explicit request for a new execution.