Create and Change a Descriptor

This recipe makes the same Workshop Note available to Electronic Approval by adding an ApprovalFormBindingDescriptor and an ApprovalDocumentSchema. It assumes the previous Contributor recipe added workshop.note.publish.

Scope of this recipe

Descriptors are the common way Apps expose capabilities to Core runtimes, but this recipe covers only the binding and document schema required by Electronic Approval. To execute an App-owned action from a Service Task in tenant-authored BPMN, publish a separate ProcessWorkActionDescriptor instead of reusing an Approval descriptor.

ProcessWorkActionDescriptor publishes the action to the BPMN picker
  → the service provider registers a handler factory with ProcessWorkActionRegistrar
  → ProcessWorkActionHandler::handle() receives the restored context and input
  → ProcessWorkActionResult returns the action output1234

A descriptor declaration publishes a catalog and execution contract; it does not execute the App's business logic. The App-owned handler performs the actual work. Process start bindings, user-task forms, and importable Process templates use the separate ProcessStartBindingDescriptor, ProcessUserTaskFormDescriptor, and ProcessTemplateDescriptor contracts. Continue with Contribute to Business Process for the descriptor, handler, and service-provider registration. See Business Process and Business Process contracts for the complete BPMN integration choices and runtime signatures.

What appears when you finish

This is the actual catalog result. Searching for Workshop shows Submit Note under Other Apps → Workshop. This stage gives administrators a binding choice; the next Approval contribution recipe connects the user-facing composer widget.

Which contract it implements and how Core receives it

WorkshopApprovalDescriptors also does not extend a Core class. It implements the App SDK AppDescriptorContribution interface and returns an AppDescriptorSet from appDescriptors(). ApprovalFormBindingDescriptor and ApprovalDocumentSchema are final SDK descriptor value objects, not base classes that App code subclasses.

WorkshopApprovalDescriptors implements AppDescriptorContribution
  → NexiaContributionRegistry discovers the implementing class
  → AppDescriptorCatalog calls appDescriptors()
  → catalog rejects duplicate descriptor type + key pairs and records Workshop ownership
  ├─ ApprovalBindingRegistry consumes ApprovalFormBindingDescriptor
  └─ ApprovalDocumentSchemaRegistry consumes ApprovalDocumentSchema
     (both registries recheck tenant App installation and descriptor lifecycle)1234567

Adding objects to appDescriptors() does not render UI directly. Core's Approval registries interpret the static contracts as an available domain form binding and the shape of document values to freeze. Because ContributionOwner comes from the Workshop namespace where the class was discovered, an App cannot publish a descriptor under another App's ownership.

1. Add the Descriptor

cp docs/developers/examples/descriptor/WorkshopApprovalDescriptors.php \
  packages/workshop/src/Descriptors/WorkshopApprovalDescriptors.php12

The binding is:

new ApprovalFormBindingDescriptor(
    appKey: 'workshop',
    resourceKey: 'note',
    actionKey: 'submit',
    labelKey: 'workshop.approval.note.submit.label',
    entryModes: ['link'],
    formWidgetKey: 'workshop.note.submit',
    documentSchemaKey: 'workshop.note',
    descriptionKey: 'workshop.approval.note.submit.description',
    submitPermissionKey: 'workshop.note.publish',
)1234567891011

link means that composition selects an existing Note. The submit permission filters catalog visibility but never replaces record-level backend Policy checks.

Publish the referenced schema in the same set:

new ApprovalDocumentSchema(
    appKey: 'workshop',
    resourceKey: 'note',
    titleKey: 'workshop.approval.note.document.title',
    sections: [[
        'title_key' => 'workshop.approval.note.document.summary',
        'fields' => [
            ['key' => 'name', 'label_key' => 'workshop.note.name.label', 'type' => 'string'],
            ['key' => 'status', 'label_key' => 'workshop.note.status.label', 'type' => 'string'],
        ],
    ]],
)123456789101112

The schema does not reflect model columns. It declares only the public documentValues shape the App freezes at submission.

2. Add locale entries

Add the exact dotted keys to every locale owned by Workshop:

{
  "workshop.approval.note.submit.label": "Submit note",
  "workshop.approval.note.submit.description": "Link an existing note to Electronic Approval.",
  "workshop.approval.note.document.title": "Note",
  "workshop.approval.note.document.summary": "Note details"
}123456

3. Discover and observe it

sh docs/developers/examples/descriptor/verify.sh1

Then search for Workshop at the path shown in the screenshot. Installation, submit authority, lifecycle, and locale resolution all participate in catalog visibility.

4. Change the Descriptor

For wording-only changes, update locale values and keep identity and version. For a compatible optional extension, confirm consumer compatibility and review the version:

version: '1.1',1

For breaking changes such as an action key, field type, or requiredness, add a new Active descriptor and deprecate the old one. Remove the old version only after stored templates and consumers have migrated.

Common errors