Business Process

Run an App-owned workflow in Nexia's BPMN runtime. Your App publishes work actions and implements their handlers; Core schedules tasks, waits, and resumes the instance.

Start with one work action

1. Prepare the App Resource and authorized domain operation. Publish a ProcessWorkActionDescriptor through AppDescriptorContribution with a stable topic and explicit input/output contract.
2. Implement ProcessWorkActionHandler and register its factory with ProcessWorkActionRegistrar in the App service provider. The registered App/action pair must match the descriptor. Validate restored actor, tenant, organization, record state, and retry identity before the domain write.
3. Reference the action in an App-contributed Process template or a tenant-authored BPMN definition. Save and publish the definition before executing it. For App-initiated starts, publish a start binding and call ProcessStarter::start(BoundProcessStart); follow Business Process contracts for the full binding, invocation, and result forms.
4. Start one instance and observe the domain operation and task result. Retry delivery of the same work without repeating the effect.

This descriptor factory is an exact excerpt from packages/people/src/Descriptors/PeopleOnboardingProcessDescriptors.php; $actionKey selects one of that App's registered handlers:

private static function service(string $actionKey): ProcessWorkActionDescriptor
{
    return new ProcessWorkActionDescriptor(
        kind: 'serviceTask',
        appKey: 'people',
        actionKey: $actionKey,
        labelKey: 'people.process_actions.'.$actionKey.'.label',
        topic: 'people.'.$actionKey,
    );
}12345678910

packages/people/src/PeopleCoreServiceProvider.php registers the corresponding handler factories. Copy the descriptor/registration pattern into your App, not People model imports. Handle events and jobs supplies the durable boundary for external effects.

Confirm the result

An operational App with an eligible published definition starts for an authorized actor. The handler receives the intended action, writes only within its authorized scope, and returns output matching the descriptor. Missing bindings, revoked authority, and stale record versions must not fall through to an unprotected write. Use the conformance helpers documented in Business Process contracts and the workflow in Test an App.

Add forms, decisions, and waits

A task form's allowedResourceActions limits what the form may request; the App endpoint still authorizes each action. Correlation and idempotency belong to the actual waiting task and accepted request. Do not complete a wait from an unrelated subject's event.

Version and publication details

Template selection alone persists nothing. Normal definition save and publish owns BPMN and paired-decision deployment. External tasks pin their work-action App, key, topic, and version. The runner refuses a descriptor mismatch. When saving with source_template_keys, Core records source_template_key and source_template_version for a prepared template whose key matches the definition key. Default installation also records this provenance; later revisions of the same definition retain it. Selecting a template alone is not a save, and copying unrelated fragments does not imply a single source template. Preserve the meaning of a published action version when updating the App. Deprecate old capabilities before removal.

Exact work-action schemas, suspension/retry results, user-task transport, decision outputs, and Approval/Signature wait contracts are maintained together in Business Process contracts. A Board is a visual record projection; choose Resource projections when that is the actual requirement.

Walk through purchase settings and execution

This extension uses the installed Supply Planning and Procurement implementations. The supplied procedure creates a purchase-request draft; the author adds the later approval step. It does not automatically add approval behavior to the Workshop note-archive example.

Start a Process from a purchase proposal
  → [Optional] Human review of purchase-request inputs
  → Create purchase-request draft
  → [Added by the author] Submit purchase request
      ├ Approval not required: App direct operation → not_required
      └ Approval required: [Prepare line if needed] → submit and wait → outcome123456

1. What the App contributes

packages/supply-planning/src/Contribution/PurchaseProposalProcess.php contributes the supply-planning.purchase_proposal start binding, purchase_proposal.create_request action, supply-planning.purchase_proposal.inputs form, and a default-installation template. Its default procedure has only an automatic task, so it needs no assignment group.

Procurement separately contributes purchase_request.submit_approval. Its ProcurementProcessDescriptors uses resourceInputs and targetResourceInput to address the created request; approvalTask.supportsLinePreparation: true permits line preparation. ProcurementApprovalWorkActionHandler calls the existing SubmitProcurementApproval. The shared App operation decides whether approval is required rather than duplicating that policy in the handler.

2. What the administrator configures

1. In Approval → Form templates, create a business form bound to procurement.purchase_request.submit, choose a designated line or submitter selection, and publish it.
2. In Approval → Operation requirements, configure Procurement purchase-request submission at company or Legal Entity scope. Whether approval is required and which line to use are separate settings. See Electronic Approval for the configuration sequence.
3. Edit the supplied purchase-proposal procedure in Process definitions. If its form belongs to a Legal Entity, author the definition in that entity. A company-wide definition cannot statically select a particular entity's form or route policy.

3. Connect inputs and the next operation

Keep the automatic path by omitting the review task. For human review, insert the contributed input form before draft creation and assign a real person. Map initial number, requested date, and stock-management values; choose editable fields with editableFields. The server also rejects changes to fixed fields. Completing this input task is not formal approval.

Map the creation action's result_reference to variables.purchase_request; the supplied template already does this. Add the purchase-request submission action, map that reference to its resource_ref input, and select a compatible published form. The Process origin remains the proposal; only the submission action's target becomes the request. Branch on the creation result so status=rejected or a missing reference never enters submission.

4. What each setting does

Branch after submission on approval_outcome. Send only approved and not_required down the business-success path; connect rejected, recalled, and cancelled to the company's follow-up procedure. Applying the result in the App and resuming the Process wait must remain safe under duplicate delivery.

5. Change and update the supplied procedure

installByDefault: true opts a template into installation for eligible entities. Installation checks dependencies; missing publication prerequisites leave an editable draft. It invents neither assignees nor approval configuration. Reinstallation does not overwrite company revisions or reactivate a stopped definition.

A newer App template is shown as an available update. An administrator reviews, saves, and publishes a new definition version; existing instances continue on their starting version. Template provenance and the frozen Work Action execution contract are separate version concerns.