Contribute to Electronic Approval

This recipe connects the Workshop Note from the previous recipes to the real Electronic Approval composer. The Descriptor recipe published the Submit Note choice; this recipe joins its Slot Widget, frontend controller, and App-owned submission endpoint with the same identity.

What appears when you finish

The screenshot is the actual template form after selecting Submit Note from the Descriptor catalog. The App description, “Link an existing note to Electronic Approval,” appears below the selection. It reaches the end-user creation catalog only after an administrator creates and publishes this template.

How three contracts connect to Core's composer flow

This feature is not completed by extending one class. It connects three boundaries through the same workshop.note.submit identity.

Published Legal Entity template
  → Core composer reads the binding formWidgetKey
  → SlotWidgetCompositionResolver selects an allowed Slot descriptor
  → frontend registry loads the Workshop Widget with the same key
  → Widget calls the App submission endpoint
  → App rechecks the Note, Policy, and revision
  → ApprovalHost::submitBound()
  → CoreApprovalHost creates the Core Approval case12345678

The App endpoint neither imports nor extends CoreApprovalHost. Its constructor receives the SDK ApprovalHost interface, which the Core host binds to the CoreApprovalHost implementation. This boundary keeps Core unaware of the Workshop model and keeps Workshop away from Core Eloquent models.

1. Add the Slot Widget Descriptor

cp docs/developers/examples/approval-contribution/WorkshopApprovalSlotWidgets.php \
  packages/workshop/src/Descriptors/WorkshopApprovalSlotWidgets.php12

Four identities must match exactly:

Approval binding formWidgetKey
        = Slot descriptor key
        = Slot descriptor component
        = frontend registry key
        = workshop.note.submit12345

The descriptor fills Core's approval.composer.business_form slot and gates visibility with workshop.note.publish.

2. Register the frontend Widget

Add the public App SDK registry call to packages/workshop/resources/js/index.ts:

import { approvalComposerBusinessFormRegistry } from '@nexia/sdk/host';

approvalComposerBusinessFormRegistry.register(
    'workshop.note.submit',
    () => import('./approval/WorkshopNoteApprovalWidget'),
);123456

WorkshopNoteApprovalWidget receives ApprovalBusinessFormSlotPropsV2, loads the Note, and registers the composer controller:

registerController({
    canSubmit: note !== null && note.status === 'active',
    saveDraft: async () => ({ appDraftRef: note.public_id }),
    buildPreview: () => ({
        title: note.name,
        sections: [{
            title: t('workshop.approval.note.document.summary'),
            fields: [
                { key: 'name', label: t('workshop.note.name.label'), value: note.name },
                { key: 'status', label: t('workshop.note.status.label'), value: note.status },
            ],
        }],
    }),
    submit: async (envelope) => {
        const response = await api.post(
            `/legal-entities/${legalEntityPublicId}/workshop/notes/${note.public_id}/submit-approval`,
            {
                template_key: envelope.templateKey,
                template_version: envelope.templateVersion,
                line: envelope.line,
                reference_user_ids: envelope.referenceUserIds,
                circulation_user_ids: envelope.circulationUserIds,
            },
        );
        return { caseId: response.data.approval_case.public_id };
    },
});123456789101112131415161718192021222324252627

This shortened excerpt shows the controller boundary. A production Widget also handles loading, not-found, denial, idempotency, staged attachments, and error states. The browser calls an App endpoint, not a Core Approval endpoint.

3. Reauthorize and submit in the App

The App endpoint resolves the Note within the Legal Entity and rechecks the workshop.note.publish Policy. It locks and verifies current state and revision before using the App SDK ApprovalHost:

$case = $this->approvals->submitBound(
    new BoundApprovalSubmission(
        legalEntity: $legalEntity,
        drafter: $actor,
        templateKey: $input['template_key'],
        templateVersion: (int) $input['template_version'],
        bindingKey: 'workshop.note.submit',
        bindingVersion: '1.0',
        resourceRef: new ResourceRef(
            appKey: 'workshop',
            resourceKey: 'workshop.note',
            resourceId: (string) $note->public_id,
            display: $note->name,
            href: '/apps/workshop/notes/'.$note->public_id,
        ),
        resourceVersion: (string) $note->updated_at->getTimestamp(),
        documentValues: [
            'name' => $note->name,
            'status' => $note->status->value,
        ],
        lineDefinition: $line,
        title: $note->name,
    ),
);123456789101112131415161718192021222324

The App owns the Note and its Policy; Core owns approval lines, cases, and audit evidence. Neither side imports the other's model.

4. Publish the template and observe it

1. Under E-Approval → Template management → New template, choose Business form.
2. Select Domain form → Workshop → Submit Note.
3. Set its name, Legal Entity scope, and approval rules, then create and publish it.
4. Open E-Approval → Create E-Approval request and choose the published Workshop form.
5. Link a Note and confirm its name/status beside the shared approval line.
6. Submit and confirm navigation to the created Approval case.

A binding by itself is intentionally absent from the end-user creation catalog. That catalog lists published Legal Entity templates, not every active descriptor.

5. Inspect discovery

sh docs/developers/examples/approval-contribution/verify.sh1

Static contribution verification is complete when the script prints Workshop Approval contribution discovered and validated.

Common errors

Verify behavior across settings

This Workshop example verifies a minimal contribution. It does not automatically add configurable approval requirements or default procedure installation. Read Electronic Approval for the developer's enforcement obligations and the administrator's form, line, and requirement setup. Then follow the real purchase flow in Business Process to compare automatic inputs, human review, required versus optional approval, line preparation, outcome branches, and supplied-template updates in one journey.