Create a Contributor

This recipe continues the Workshop App and Note Resource from the Resource Generator. It adds publish and archive as business permissions while keeping the generated read, create, update, and delete permissions.

What appears when you finish

Result	Where to see it
`WorkshopWorkflowPermissions`	`packages/workshop/src/Contribution/`
`workshop.note.publish` and `workshop.note.archive`	Permission catalog
Publish and archive choices	Settings → Roles → New role → Permissions → Workshop → Note

Workshop Note permissions in the role editor

This is the actual catalog after applying the recipe and synchronizing the tenant. Searching for the stable workshop.note. prefix shows the four Resource Generator permissions together with Publish Note and Archive Note.

A Contributor publishes capability metadata. It does not create App navigation or add buttons to the Note screen. Routes, Policies, and frontend affordances must consume these permissions to complete the business behavior.

Which contract it implements and how Core receives it

WorkshopWorkflowPermissions does not extend a Core class. It implements the App SDK Nexia\Permission\Contracts\PermissionContribution interface and returns static permission definitions from catalogPermissionDefinitions().

WorkshopAppManifest::contributionLocations()
  → NexiaContributionRegistry::classesImplementing(PermissionContribution::class)
  → WorkshopWorkflowPermissions::catalogPermissionDefinitions()
  → AppRegistry::permissionDefinitions()
  → PermissionContributionRegistry → PermissionCatalog
  → nexia-access:sync-permissions materializes tenant permission rows
  → Access catalog API sends permissions for installed Apps to the role editor1234567

The generated NoteModule represents the whole Resource, so it extends AbstractResourceModule and contributes CRUD permissions through ContributesResourcePermissions. Publish and archive are separate business actions rather than baseline Resource CRUD, so this recipe uses a small standalone class that directly implements only PermissionContribution. Core discovers the file because a concrete class inside a registered discovery root implements that SDK interface, not merely because the file was copied there.

Discovery and synchronization are separate stages. Discovery adds the code definition to the catalog; nexia-access:sync-permissions materializes that catalog in the tenant database. Neither stage grants the permission to a user.

1. Add the Contributor

WorkshopAppManifest already registers src/Contribution/ as a discovery root. Copy the example there:

Code example

Shell

cp docs/developers/examples/contributor/WorkshopWorkflowPermissions.php \
  packages/workshop/src/Contribution/WorkshopWorkflowPermissions.php12

The implementation uses only public App SDK contracts:

Code example

PHP

final class WorkshopWorkflowPermissions implements PermissionContribution
{
    public static function catalogPermissionDefinitions(): array
    {
        return PermissionDefinition::many(
            appKey: 'workshop',
            resource: 'note',
            actions: ['publish', 'archive'],
            assignmentScope: AssignmentScope::LegalEntity,
        );
    }
}123456789101112

PermissionDefinition::many() normalizes the actions to workshop.note.publish and workshop.note.archive.

2. Discover and synchronize it

Inspect discovery and the planned tenant change first:

Code example

Shell

TENANT=abc123def456 sh docs/developers/examples/contributor/verify.sh1

Then synchronize the intended tenant:

Code example

Shell

task artisan -- nexia-access:sync-permissions --tenant=abc123def456 --no-ansi1

Synchronization grants nothing automatically. An access administrator still adds the permissions to a Role and assigns that Role through a Legal Entity Access Grant.

3. Change the Contributor

For example, replace archive with restore:

Code example

PHP

actions: ['publish', 'restore'],1

Refresh runtime discovery and synchronize again. Removing workshop.note.archive from code does not immediately remove its tenant row or existing assignments. Review consumers and Access Grants, then use the explicit permission-retirement workflow.

Common errors

Symptom	Cause	Fix	Confirm
Doctor does not find another contributor	The class namespace is wrong or the file is outside the Manifest contribution root	Keep `WorkshopWorkflowPermissions.php` under `packages/workshop/src/Contribution/` and confirm that it implements `PermissionContribution`	`verify.sh` prints `Contributor discovered.`
Sync reports a duplicate key	A new action overlaps a CRUD key already owned by `NoteModule`	Publish only separate business actions such as `publish` and `archive`, not the baseline Resource actions	The dry run lists only `workshop.note.publish` and `workshop.note.archive` as new changes
The permission is visible in Roles but no button exists	A Contributor publishes definitions; it does not create a Route, Policy method, or frontend action	Implement the App Route, Policy, and UI for the business action	An allowed user sees the implemented action and its backend request succeeds
A Role contains the permission but the user is denied	The Role is not assigned through an Access Grant in the current Legal Entity	Assign the Role to the user in the current Legal Entity	Selecting that Legal Entity allows the request

Create a Contributor

Overview

Create a Contributor

What appears when you finish

Which contract it implements and how Core receives it

1. Add the Contributor

2. Discover and synchronize it

3. Change the Contributor

Common errors

Included files

Permission contributor

Refresh and inspect discovery