Governed activation and publishing
The definition store keeps canonical definitions as versioned, immutable data. Getting a version into use takes two separate steps: an import stores the version inactive, and an activation makes it the active version, fenced against concurrent changes and recorded in an audit table. This page describes both steps, rollback, the publisher that imports the definitions of a workflow project, and deployment to another installation.
What the store is for
The engine runs the workflows registered in code (Hosting). The definition store is the governed record of definitions as data:
- Review and release. A version is imported by a pipeline and activated by an administrator, with an audit row for each activation.
- Durable start. A durable start admits only a stored, managed, active version whose content hash matches (managed import, Durable execution).
- Export and rendering. Stored versions can be exported, in several formats, and rendered.
- Several installations. A version is exported from one installation and imported into another.
Every workflow name that is stored counts as a Designated Workflow from its first import, like a workflow registered in code (Licensing).
Import
InventoryRestock.definition.json is a canonical definition in a file, here the workflow of lesson 2 of the tutorials, written with the export helper of Canonical definitions:
curl -s -X POST http://localhost:5090/api/workflow/definitions/import \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d "{\"canonicalDefinitionJson\": $(jq -Rs . < InventoryRestock.definition.json)}"
| Response field | Meaning |
|---|---|
wasImported | true when a new version was stored; false when the same content was already stored |
wasNewVersion | true for a version number the store did not have |
isActive | false for a new version; for content that is already stored, the stored version’s flag |
contentHash | The SHA-256 of the canonical content |
validationIssues | The validation issues of a definition that was not stored |
Rules:
- The import validates the definition first. An invalid definition is not stored: the response has
wasImported: falseand the issues invalidationIssues. - The same content under the same version is a no-op (
wasImported: false). - Different content under an existing version is refused with 409 (
WORKFLOW_DEFINITION_VERSION_HASH_CONFLICT): a stored version never changes. - An import never activates and is never refused for licence reasons.
The import needs the workflow:admin scope, and the audit records the token’s actor as the importer; an importedBy in the body is not used. import-multi takes the YAML and bundle formats (Canonical definitions).
Managed import
A durable start admits only a managed definition. An import is managed when its request carries:
| Request field | Value |
|---|---|
origin | MANAGED_EMBEDDED (the default, OPERATOR_IMPORTED, stores an operator definition) |
managedCode | The definition code that durable starts name, as listed in WorkflowDurableStart:Definitions |
sourceBuildSha256 | The SHA-256 of the build that produced the definition: 64 hexadecimal digits, not all zero |
compatibilitySha256 | The SHA-256 of its compatibility contract: 64 hexadecimal digits, not all zero |
curl -s -X POST http://localhost:5090/api/workflow/definitions/import \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d "{\"canonicalDefinitionJson\": $(jq -Rs . < OrderApproval.definition.json), \"origin\": \"MANAGED_EMBEDDED\", \"managedCode\": \"OrderApproval\", \"sourceBuildSha256\": \"$BUILD_SHA256\", \"compatibilitySha256\": \"$COMPATIBILITY_SHA256\"}"
| Refusal | Status | Cause |
|---|---|---|
WORKFLOW_DEFINITION_ORIGIN_INVALID | 400 | origin is neither MANAGED_EMBEDDED nor OPERATOR_IMPORTED |
WORKFLOW_MANAGED_DEFINITION_HASH_REQUIRED | 400 | A managed import without sourceBuildSha256 or compatibilitySha256 |
WORKFLOW_DEFINITION_HASH_INVALID | 400 | A hash that is not 64 hexadecimal digits |
WORKFLOW_DEFINITION_ORIGIN_COLLISION | 409 | The same content is already stored with another origin, managed code or hash |
An import without these fields, such as the first import of this page or one made by the publisher, stores an operator definition, which a durable start never admits. The publisher sends only the canonical JSON, so it cannot produce a managed definition.
Activate
curl -s -X POST http://localhost:5090/api/workflow/definitions/InventoryRestock/activate \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"workflowName":"InventoryRestock","version":"1.0.0","actorId":"admin-1","reasonCode":"RELEASE"}'
| Request field | Meaning |
|---|---|
version | The version to activate |
expectedActiveVersion, expectedActiveSha256 | The fence: the version and hash you expect to be active now. Leave both out for the first activation of a workflow; give both when a version is active |
actorId, reasonCode | The request contract’s fields. Over HTTP the audit row records the caller from the token as the actor; reasonCode (default OPERATOR_ACTIVATION) is recorded as sent |
allowRollback, rollbackOfAuditId | Required together to activate an older version (below) |
The activation is one transaction: it deactivates the current version, activates the target, and writes an audit row with the previous and the new version and hash, the actor and the reason.
A refused activation answers with the status below and the code in the body’s error (Refusals); nothing changes.
| Status | error | Cause |
|---|---|---|
| 404 | WorkflowDefinitionNotFound | The version is not stored |
| 409 | WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOST | The active version or hash is not the one the request expects; someone activated another version, or the fence was omitted |
| 409 | WORKFLOW_DEFINITION_ROLLBACK_NOT_AUTHORIZED | The target is older than the active version, and the request is not marked as a rollback |
| 400 | WORKFLOW_DEFINITION_ROLLBACK_TARGET_INVALID | The request is marked as a rollback, but the target is not older |
Read the current active version and hash first:
curl -s http://localhost:5090/api/workflow/definitions/InventoryRestock/versions -H "Authorization: Bearer $TOKEN"
Each version summary has version, contentHash, isActive, origin, importedBy, createdOnUtc and activatedOnUtc.
Roll back
Activating a version older than the active one is a rollback. The request must say so: set allowRollback to true and rollbackOfAuditId to the reference of the activation you undo (the audit row’s id, or your change record). Give the fence of the active version as for any activation.
{
"workflowName": "InventoryRestock",
"version": "1.0.0",
"expectedActiveVersion": "1.1.0",
"expectedActiveSha256": "<content hash of 1.1.0>",
"actorId": "admin-1",
"reasonCode": "ROLLBACK",
"allowRollback": true,
"rollbackOfAuditId": "<audit id of the 1.1.0 activation>"
}
Audit
Every activation writes one audit row: the workflow, the version, the previous and the new active version and hash, the actor, the reason, the rollback reference and the time. PostgreSQL keeps the rows in workflow.wf_definition_audit, MongoDB in the workflow_definition_audit collection. Nothing deletes them. The HTTP API has no route that reads them; query the store.
The publisher
StellaOps.Workflow.Publisher imports the workflows of your workflow projects into a running host at start. The workflow analyzer package writes the canonical JSON of the workflows of a project into its assembly at build time; the publisher finds it in the assemblies you name and posts each definition to the target’s import endpoint. A version the target already has is skipped by its hash.
/// <summary>
/// Publishes the workflows compiled into the given assemblies to a workflow host's import endpoint at
/// start. Each new version is stored inactive on the target. The options come from the host's
/// WorkflowPublisher configuration section and are checked when the host starts.
/// </summary>
public static IServiceCollection AddWorkflowDefinitionPublishing(
this IServiceCollection services,
params System.Reflection.Assembly[] workflowAssemblies)
{
services.AddWorkflowPublisher(workflowAssemblies);
return services;
}
AddWorkflowPublisher binds the options from the host’s WorkflowPublisher section (WorkflowPublisherOptions.SectionName). To read them from another section, pass it: services.AddWorkflowPublisher(configuration.GetSection("Publishing:Workflows"), workflowAssemblies).
{
"WorkflowPublisher": {
"Enabled": true,
"Endpoint": "<base URL of the workflow host>",
"ServiceName": "order-service",
"Timeout": "00:00:30",
"MaxRetriesPerWorkflow": 3,
"FailOnError": false,
"DryRun": false
}
}
WorkflowPublisher__AuthToken=<token with the workflow:admin scope>
| Option | Default | Meaning |
|---|---|---|
Enabled | true | false skips publishing |
Endpoint | none | The base URL of the target host: an absolute http or https URL; required unless DryRun is set |
CommandPath | /api/workflow/definitions/import | The import path on the target, starting with /: the route MapWorkflowEndpoints serves; change it only for a host that maps the import elsewhere |
ServiceName | none | Sent as importedBy (<ServiceName>/publisher); a host that maps MapWorkflowEndpoints records the token’s actor instead |
AuthToken | none | A bearer token for the target |
Timeout | 30 s | The timeout of one import; positive |
MaxRetriesPerWorkflow, RetryBaseDelay | 3, 2 s | Retries with exponential delay; neither negative |
FailOnError | false | true stops the host when a publish fails |
DryRun | false | Logs what would be published, sends nothing |
The options of an enabled publisher are checked when the host starts: an option outside the rules above stops the host with an options validation error that names the key (for example WorkflowPublisher:Endpoint must be the absolute http or https URL of the workflow service.). A host with the publisher registered and no Endpoint therefore needs "Enabled": false or "DryRun": true. A disabled publisher is not checked.
The publisher only imports; activate each new version as above. A workflow the build-time generator does not bundle (WF021) is listed in the assembly for runtime compilation, and the publisher compiles it at start with the runtime compiler before it posts it. A workflow that uses a C# delegate has no canonical definition: the publisher logs it as failed with the compiler’s WFCD codes, counts it in the failures, and stops the host only when FailOnError is true.
Deploying to another installation
WorkflowDefinitionRemoteDeployService (in StellaOps.Workflow.Publisher) sends a stored version to another installation’s import endpoint, where it is stored inactive. The caller supplies the export: WorkflowDefinitionDeploymentService.CreateImportRequestAsync(name, version, importedBy) of the source installation. The request names the target’s base URL (TargetServerUrl), an optional bearer token (TargetAuthToken) and an optional import path (TargetCommandPath, default /api/workflow/definitions/import). Every failure comes back as an unsuccessful result with the target’s validation issues or the error.
Without code, the same deployment is an export and an import over HTTP: POST /api/workflow/definitions/export on the source, then POST /api/workflow/definitions/import on the target with the exported canonicalDefinitionJson.
Cases
- Release pipeline. The pipeline imports the new version with a service token (
workflow:admin); an administrator reviews the versions list and activates with the fence. - Emergency rollback. Activate the previous version with
allowRollbackand the reference of the faulty activation. - Promotion between environments. Export from staging, import into production, activate in production.
Pitfalls
- Expecting an import to change behaviour. An import stores; the active flag changes only with an activation, and the engine runs the workflows registered in code.
- A stale fence. Read the versions list just before you activate; a concurrent activation makes yours fail with
WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOST. - Reusing a version number. Different content under a stored version is refused; increase the version.
- Counting. Every stored workflow name counts as a Designated Workflow from its first import, and stays counted.
