Contribute to Electronic Signature

This recipe publishes the same Workshop Note name as an App-data field that Electronic Signature documents can fill automatically. It continues the Workshop story from the earlier recipes.

What appears when you finish

This is the actual editor after applying the generated descriptor and locale entries. Add field offers App: Workshop, Resource: Workshop Note, and Field: Note Name. Example NoteFieldsV1 value is a synthetic authoring sample, not tenant data.

Which contracts it implements and how Core receives them

The generator does not create a subclass of a Core class. It creates two classes that implement separate App SDK contracts.

SignatureDocumentDataSourceContribution extends AppDescriptorContribution, so the generated contribution provides both appDescriptors() and signatureDocumentDataSourceProviders(). Core resolves the contribution through its container, allowing it to receive the generated Provider through constructor injection.

NexiaContributionRegistry discovers SignatureDocumentDataSourceContribution
  ├─ AppDescriptorCatalog collects the static source and field contract
  └─ SignatureDocumentDataSourceRegistry collects Providers
       → pairs exact appKey + sourceKey + sourceVersion and contribution ownership
       ├─ Template authoring: CatalogController returns descriptor + synthetic sample
       └─ Request preparation: RuntimeExecutor checks tenant context and contract,
                              invokes Provider::resolve(query) within a deadline,
                              then validates the returned result12345678

The field appearing in the editor and a real Note value being filled are therefore separate stages. A static descriptor can create the authoring choice, but a fail-closed runtime Provider returns no value during request preparation.

1. Preview generation

The included script is a dry run by default:

sh docs/developers/examples/electronic-signature-contribution/commands.sh1

Expect two WOULD CREATE targets:

packages/workshop/src/Descriptors/NoteFieldsV1SignatureDocumentDataSource.php
packages/workshop/src/Signature/NoteFieldsV1SignatureDocumentDataSourceProvider.php12

Write them only after reviewing the preview:

WRITE=1 sh docs/developers/examples/electronic-signature-contribution/commands.sh1

The command uses workshop.note as both subject and source, direct-subject lookup, cardinality one, and a string name field. The generator never infers a model or database column.

2. Add locale entries

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

{
  "workshop.signature_document_data.fields.name": "Note name",
  "workshop.signature_document_data.note_fields_v1.label": "Workshop Note",
  "workshop.signature_document_data.note_fields_v1.description": "Provides the linked Note to an Electronic Signature document."
}12345

The descriptor's syntheticSample is only for the static authoring catalog. Never put real or sensitive data there.

3. Implement the Provider

The generated Provider intentionally returns Unavailable. Generating files must not expose real Note values. Before activation, implement all of these:

• verify the Core-restored tenant, Legal Entity, and actor;
• reauthorize the requested workshop.note subject ResourceRef;
• check workshop.note.read and record-level Policy;
• enforce the requested-field allowlist and asOf instant;
• bound the lookup and timeout;
• return provenance and keep values out of diagnostics.

The Provider may query the Note model inside Workshop. It must not import a Core model or another App model.

4. Understand authoring versus runtime

The Add field dialog reads only the static descriptor and synthetic sample, so the choice appears while the generated Provider still fails closed. Real values resolve only during request preparation after Core restores subject and actor context.

Template authoring                    Request preparation
Static Descriptor catalog            Runtime Provider
└─ Workshop Note                      └─ reauthorize actor and subject
   └─ Note Name · sample                 └─ return the allowed Note name1234

5. Refresh and inspect

task artisan -- nexia-runtime:refresh-runtime-caches --if-route-cached --no-ansi
task artisan -- nexia-apps:validate-app-descriptors workshop --no-ansi
task artisan -- nexia-apps:doctor-package-app workshop --no-ansi123

After Doctor reports a paired Signature document data source, open Add field at the screenshot path and select Workshop.

Common errors

Revision rules