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:

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 fieldMeaning
wasImportedtrue when a new version was stored; false when the same content was already stored
wasNewVersiontrue for a version number the store did not have
isActivefalse for a new version; for content that is already stored, the stored version’s flag
contentHashThe SHA-256 of the canonical content
validationIssuesThe validation issues of a definition that was not stored

Rules:

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 fieldValue
originMANAGED_EMBEDDED (the default, OPERATOR_IMPORTED, stores an operator definition)
managedCodeThe definition code that durable starts name, as listed in WorkflowDurableStart:Definitions
sourceBuildSha256The SHA-256 of the build that produced the definition: 64 hexadecimal digits, not all zero
compatibilitySha256The 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\"}"
RefusalStatusCause
WORKFLOW_DEFINITION_ORIGIN_INVALID400origin is neither MANAGED_EMBEDDED nor OPERATOR_IMPORTED
WORKFLOW_MANAGED_DEFINITION_HASH_REQUIRED400A managed import without sourceBuildSha256 or compatibilitySha256
WORKFLOW_DEFINITION_HASH_INVALID400A hash that is not 64 hexadecimal digits
WORKFLOW_DEFINITION_ORIGIN_COLLISION409The 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 fieldMeaning
versionThe version to activate
expectedActiveVersion, expectedActiveSha256The 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, reasonCodeThe 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, rollbackOfAuditIdRequired 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.

StatuserrorCause
404WorkflowDefinitionNotFoundThe version is not stored
409WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOSTThe active version or hash is not the one the request expects; someone activated another version, or the fence was omitted
409WORKFLOW_DEFINITION_ROLLBACK_NOT_AUTHORIZEDThe target is older than the active version, and the request is not marked as a rollback
400WORKFLOW_DEFINITION_ROLLBACK_TARGET_INVALIDThe 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>
OptionDefaultMeaning
Enabledtruefalse skips publishing
EndpointnoneThe base URL of the target host: an absolute http or https URL; required unless DryRun is set
CommandPath/api/workflow/definitions/importThe import path on the target, starting with /: the route MapWorkflowEndpoints serves; change it only for a host that maps the import elsewhere
ServiceNamenoneSent as importedBy (<ServiceName>/publisher); a host that maps MapWorkflowEndpoints records the token’s actor instead
AuthTokennoneA bearer token for the target
Timeout30 sThe timeout of one import; positive
MaxRetriesPerWorkflow, RetryBaseDelay3, 2 sRetries with exponential delay; neither negative
FailOnErrorfalsetrue stops the host when a publish fails
DryRunfalseLogs 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

Pitfalls