Workflow Packages

Pre-built scenario bundles via the pkg.* code registry.

Workflow packages — pre-built scenarios

A WorkflowPackage bundles {required_custom_properties, workflows, config_schema} so that a tenant can activate a complete scenario in a single call.

Packages live as CODE in app/domain/workflow_package/registry.py — there is no database table. The manifest is static; activation writes custom_property and workflow_definition rows.

Activation semantics

• Idempotent on the uniqueness keys (tenant_id, target_kind, property_key) and (tenant_id, business_id) respectively
• overwrite=true refreshes non-builtin workflows
• is_builtin=true workflows are NEVER overwritten (this raises PackageActivationError)

Starter packages (current)

• pkg.samaccountname — Active Directory sAMAccountName generation and write
• pkg.work_email — primary email template and propagation
• pkg.ad_username — Active Directory username convention
• pkg.external_identity_classification — auto-classify external accounts
• pkg.manager_change_notify — email on a manager change
• pkg.ivip_mode — legacy POC / packaging flag (de-emphasized since 2026-06-07: visibility-only is a per-object opt-in capability, not a separate product tier or default)
• pkg.externals_data — the "Externals & data" feature flag

Adding a new package — three steps

1. Define a PackageSpec in registry.py with id="pkg.<vendor>_<name>", a builds(config) -> BuildResult callable, and an optional config_schema.
2. Append it to the _PACKAGES registry. No migration, no seed, and no lifespan bootstrap.
3. Add a unit test in tests/test_workflow_packages.py: one for the default build, one for the build with configuration, and one for what the activator skips versus creates.

⚠ Note

Packages may ONLY write CustomProperty and WorkflowDefinition rows. No notification templates, no groups, and nothing else — keep them bounded. For other seeds, use a dedicated seeder.

Config-packs (pack.*) — the broader bundle

Alongside workflow packages, config-packs (app/domain/config_pack, id prefix pack.*) have existed since 2026-06-16. On top of the workflow-package contents, these also bundle object types (SchemaDefinition) and scoped roles (delegated admin: a capability set bound to an owner-anchored scope). Installation is idempotent (created / kept). The flagship is pack.external-org-delegated-onboarding.

Further reading:

• Filter DSL