Deploying workflows between installations
An installation is a Workflow host, or several nodes of one, with its own definition store. A release moves workflow definitions from one installation (the source, such as staging) to another (the target, such as production): an export on the source, an import on the target, which stores the version inactive, and an activation on the target, fenced and audited. This page describes what moves, the setup of both installations, a deployment over HTTP for a CI/CD pipeline, a deployment from code, activation and rollback on the target, provenance, and the pitfalls.
Governed activation and publishing describes import, activation, rollback and the audit within one installation.
What moves and what does not
| Moves | Does not move |
|---|---|
| The canonical definition of one version, as the JSON string the source stores, with its content hash | The code: the workflow classes, their registrations and the transports, functions and activities they use |
| The rendering assets stored with the version | The active flag: the target stores every imported version inactive |
| The provenance (origin, managed code, build hashes), when the import repeats it (Provenance) | The audit rows, the instances and the tasks of the source |
What that means for a release:
- The code goes first. The engine starts and runs the workflows registered in code (Hosting). A stored definition is the governed record: review, export, rendering, the version history and the admission of a durable start. A workflow runs on the target only when the target’s hosts register its code at that version; a start of a workflow that is stored and active but not registered answers 404
WorkflowDefinitionNotFound. Deploy the application build to the target first, then promote its definitions. - The target validates. The import validates the definition against the target’s own installed modules (transports, stores), expression functions and external activity registry. A definition that needs something the target lacks is refused, and nothing is stored.
- Export without a version takes the active version. A workflow that the source registers in code and never imported is exported from the code catalogue: the export carries an empty content hash and
isActive: true. - A version is an identity. The target stores a version once. The same content again is a no-op; other content under the same version is refused with 409. The content hash is the SHA-256 of the UTF-8 bytes of the JSON string, so a change of white space is other content.
- The target counts it. A workflow name the target stores counts as a Designated Workflow on the target from its first import, like one it registers in code; a refused import records nothing (Licensing).
The source installation
- A definition store. The PostgreSQL or MongoDB store (Persistence and signals). The versions to promote are imported on the source and, usually, activated there after their tests.
- The endpoints.
MapWorkflowEndpointswith authentication andAddWorkflowAuthorization, as in Hosting. - A read identity. The deployment reads the source with a token that carries
workflow:view:POST /api/workflow/definitions/exportandGET /api/workflow/definitions/{name}/versions.
The target installation
A definition store. Without one, the import cannot store anything and fails with 500.
The endpoints, as on the source.
A deploy identity with the
workflow:adminscope and an actor claim. The import and the activation record the caller as the importer and as the actor of the audit row, so the token must name one:subby default, or the claim types inWorkflowAuthorization:ActorIdClaimTypes(The actor of a task action). A client-credentials token usually carriessub; when your provider puts the client in another claim only, add that claim type to the list.Token Import and activation answer None or invalid 401 Without workflow:admin(for exampleworkflow:operate)403, without a body workflow:adminwithout an actor claim403 with error: WorkflowActorUnresolvedThe same registrations as the source. The workflows in code, at the same versions; the transports and function modules the definitions require; the external activity registry when a definition uses external activities;
WorkflowDurableStart:Definitionswhen durable starts are used (Durable execution).GET /api/workflow/functionslists the target’sinstalledModules, andPOST /api/workflow/canonical/validateon the target validates a definition without storing it.
Deploy over HTTP: the CI/CD step
A release runs in this order:
- Deploy the application build to the target’s hosts, so that they register the new code.
- Promote the definitions of the release.
Promoting one workflow version takes five calls:
- Export it from the source:
POST /api/workflow/definitions/export, with the version, or without it for the source’s active version. - Read the source’s version list,
GET /api/workflow/definitions/{name}/versions: the export carries no provenance, the list does. - Import it into the target,
POST /api/workflow/definitions/import, with the exported JSON string unchanged and the provenance. - Read the target’s version list and activate the version with the active version and hash as the fence,
POST /api/workflow/definitions/{name}/activate, unless the version is already active. - Read the target’s version list again: the version, its hash and its active flag.
There is no batch route: a deployment promotes one version per call, in a loop. import-multi and export-multi convert other formats (YAML, a ZIP bundle) and also carry one definition per call.
The script
The script below does these calls with jq and curl for each workflow it is given. It reads the tokens from files and passes them to curl in a header file, so they never appear on a command line.
#!/usr/bin/env bash
# Promotes stored workflow definitions from one Stella Ops Workflow installation (the source) to another
# (the target) over the HTTP API with jq and curl: export from the source, import into the target with
# the source's provenance, activate with a fence, and check the version and the content hash on both
# sides. A CI/CD step runs it once per release, after the target's hosts run the new code.
#
# Usage: promote.sh <workflow>[@<version>] [<workflow>[@<version>] ...]
# Without @<version>, the active version of the source is promoted.
#
# Environment:
# SOURCE_URL the base URL of the source, for example https://workflow.staging.example
# SOURCE_TOKEN_FILE a file holding a bearer token for the source (workflow:view)
# TARGET_URL the base URL of the target, for example https://workflow.production.example
# TARGET_TOKEN_FILE a file holding a bearer token for the target (workflow:admin and an actor claim)
# ACTIVATE true (the default) activates each promoted version on the target; false only imports
# REASON the reason code of the activation in the target's audit (default PROMOTION)
#
# Exit: 0 every workflow promoted and verified; 1 a workflow was not; 2 usage.
set -euo pipefail
usage() { sed -n '7,18p' "$0" | sed 's/^# \{0,1\}//' >&2; exit 2; }
[ "$#" -gt 0 ] || usage
for name in SOURCE_URL SOURCE_TOKEN_FILE TARGET_URL TARGET_TOKEN_FILE; do
[ -n "${!name:-}" ] || { echo "$name is not set" >&2; usage; }
done
for tool in "${CURL:-curl}" jq; do
command -v "$tool" >/dev/null || { echo "$tool is required" >&2; exit 2; }
done
ACTIVATE="${ACTIVATE:-true}"
REASON="${REASON:-PROMOTION}"
SOURCE_URL="${SOURCE_URL%/}"
TARGET_URL="${TARGET_URL%/}"
# The tokens go into header files that only this user can read, so they never appear on a command line.
umask 077
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
printf 'Authorization: Bearer %s\n' "$(tr -d '\r\n' < "$SOURCE_TOKEN_FILE")" > "$work/source.headers"
printf 'Authorization: Bearer %s\n' "$(tr -d '\r\n' < "$TARGET_TOKEN_FILE")" > "$work/target.headers"
# call <source|target> <method> <path> [<body file>]: sends the request to the source or the target, writes
# the answer to $work/response and prints the status. The client is ${CURL:-curl}; another binary can be set
# in that variable.
call() {
local base="$SOURCE_URL"
[ "$1" = target ] && base="$TARGET_URL"
local args=(-sS -o "$work/response" -w '%{http_code}' -X "$2" -H "@$work/$1.headers")
if [ "$#" -gt 3 ]; then
args+=(-H 'Content-Type: application/json' --data-binary "@$4")
fi
"${CURL:-curl}" "${args[@]}" "$base$3"
}
# field <jq filter> [<file>]: one value of a JSON answer, without the carriage return a Windows jq adds.
field() { jq -r "$1" "${2:-$work/response}" | tr -d '\r'; }
failed=0
fail() { echo "$1: FAILED: $2" >&2; failed=$((failed + 1)); }
promote() {
local name="${1%@*}" version=""
[ "$1" != "$name" ] && version="${1#*@}"
local path status
path=$(jq -rn --arg n "$name" '$n | @uri' | tr -d '\r')
# Without a version the source exports its active version. A workflow registered in code on the
# source and never imported there comes from the code catalogue, with an empty content hash.
jq -cn --arg n "$name" --arg v "$version" \
'{workflowName: $n, includeRendering: true} + (if $v == "" then {} else {version: $v} end)' > "$work/export.json"
status=$(call source POST /api/workflow/definitions/export "$work/export.json")
[ "$status" = 200 ] || { fail "$1" "the source refused the export: $status $(cat "$work/response")"; return; }
cp "$work/response" "$work/exported.json"
version=$(field .version "$work/exported.json")
local label="$name $version" source_hash
source_hash=$(field .contentHash "$work/exported.json")
echo "$label: exported from the source, hash ${source_hash:-none (code catalogue)}"
# The import body: the exported JSON string copied as it is (jq copies the string and never parses
# its content, so the bytes and the hash stay the same), the rendering, and the provenance of the
# stored version, which only the source's version list carries.
status=$(call source GET "/api/workflow/definitions/${path}/versions")
[ "$status" = 200 ] || { fail "$label" "the source refused the version list: $status"; return; }
jq -c --slurpfile versions "$work/response" '
. as $e
| ($versions[0].versions | map(select(.version == $e.version)) | .[0]) as $stored
| {canonicalDefinitionJson: $e.canonicalDefinitionJson,
renderingSvgBase64: $e.renderingSvgBase64, renderingJsonBase64: $e.renderingJsonBase64,
renderingPngBase64: $e.renderingPngBase64,
origin: ($stored.origin // "OPERATOR_IMPORTED"), managedCode: $stored.managedCode,
sourceBuildSha256: $stored.sourceBuildSha256, compatibilitySha256: $stored.compatibilitySha256}' \
"$work/exported.json" > "$work/import.json"
status=$(call target POST /api/workflow/definitions/import "$work/import.json")
case "$status" in
200)
if [ "$(field '.validationIssues | length')" != 0 ]; then
field '.validationIssues[] | " \(.code) at \(.path): \(.message)"' >&2
fail "$label" "the target's validation refused the definition; nothing was stored"; return
elif [ "$(field .wasImported)" = true ]; then
echo "$label: imported into the target, stored inactive"
else
echo "$label: the target already stores this content; nothing changed"
fi ;;
409)
case "$(field .error)" in
WORKFLOW_DEFINITION_VERSION_HASH_CONFLICT)
fail "$label" "the target stores other content under version $version; raise the version on the source" ;;
*) fail "$label" "the target refused the import: 409 $(field .error)" ;;
esac
return ;;
403)
if [ "$(field '.error? // empty' 2>/dev/null)" = WorkflowActorUnresolved ]; then
fail "$label" "the target token carries no actor claim"
else
fail "$label" "the target token lacks the workflow:admin scope"
fi
return ;;
*) fail "$label" "the target refused the import: $status $(cat "$work/response")"; return ;;
esac
local target_hash
target_hash=$(field .contentHash)
# The fence: the version and hash active on the target now, or neither when no version is active.
# A version that is already active with the same hash is left alone; activating it again would write
# another audit row.
if [ "$ACTIVATE" = true ]; then
status=$(call target GET "/api/workflow/definitions/${path}/versions")
[ "$status" = 200 ] || { fail "$label" "the target refused the version list: $status"; return; }
local active_version active_hash
active_version=$(field '[.versions[] | select(.isActive)][0].version // empty')
active_hash=$(field '[.versions[] | select(.isActive)][0].contentHash // empty')
if [ "$active_version" = "$version" ] && [ "$active_hash" = "$target_hash" ]; then
echo "$label: already active on the target"
else
jq -cn --arg n "$name" --arg v "$version" --arg r "$REASON" --arg av "$active_version" --arg ah "$active_hash" \
'{workflowName: $n, version: $v, reasonCode: $r}
+ (if $av == "" then {} else {expectedActiveVersion: $av, expectedActiveSha256: $ah} end)' > "$work/activate.json"
status=$(call target POST "/api/workflow/definitions/${path}/activate" "$work/activate.json")
case "$status:$(field '.error? // empty' 2>/dev/null)" in
200:*) echo "$label: activated on the target$([ -n "$active_version" ] && echo " in place of $active_version" || echo ' (no version was active)')" ;;
409:WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOST)
fail "$label" "another activation changed the target's active version after it was read; run again"; return ;;
409:WORKFLOW_DEFINITION_ROLLBACK_NOT_AUTHORIZED)
fail "$label" "the version is older than the target's active $active_version; roll back on the target instead"; return ;;
*) fail "$label" "the target refused the activation: $status $(cat "$work/response")"; return ;;
esac
fi
fi
# The target's version list again: the version is stored with the hash the import reported, which is
# the source's hash when the source stores the version, and it is active when it was activated.
status=$(call target GET "/api/workflow/definitions/${path}/versions")
[ "$status" = 200 ] || { fail "$label" "the target refused the version list: $status"; return; }
local stored_hash stored_active
stored_hash=$(jq -r --arg v "$version" '[.versions[] | select(.version == $v)][0].contentHash // empty' "$work/response" | tr -d '\r')
stored_active=$(jq -r --arg v "$version" '[.versions[] | select(.version == $v)][0].isActive // false' "$work/response" | tr -d '\r')
if [ "$stored_hash" != "$target_hash" ] || { [ -n "$source_hash" ] && [ "$stored_hash" != "$source_hash" ]; }; then
fail "$label" "the target stores hash ${stored_hash:-none}; the source has ${source_hash:-none}, the import reported $target_hash"; return
fi
if [ "$ACTIVATE" = true ] && [ "$stored_active" != true ]; then
fail "$label" "the version is not active on the target"; return
fi
echo "$label: verified: the target stores hash $stored_hash$([ "$stored_active" = true ] && echo ', active')$([ -n "$source_hash" ] && echo '; the source stores the same hash')"
}
# There is no batch route: each workflow is promoted in turn.
for workflow in "$@"; do
promote "$workflow"
done
[ "$failed" = 0 ] || { echo "$failed of $# workflow(s) not promoted" >&2; exit 1; }
echo "promoted $# workflow(s) from $SOURCE_URL to $TARGET_URL"
Two details of the script matter for any client:
- The definition passes through unchanged. jq copies the
canonicalDefinitionJsonstring value and never parses its content, so the target hashes the same bytes as the source. Decoding the definition and writing it again (fromjson | tojsonin jq, or a JSON library) changes the white space and therefore the hash. - No raw output of the definition. A native jq for Windows writes raw output (
-r,-j) with CRLF line ends. The script reads only scalar values with-r, and removes the carriage return from them.
Run it once per release, with the workflows of the release:
export SOURCE_URL=https://workflow.staging.example
export SOURCE_TOKEN_FILE=/run/secrets/workflow-staging-reader
export TARGET_URL=https://workflow.production.example
export TARGET_TOKEN_FILE=/run/secrets/workflow-production-deployer
bash promote.sh InventoryRestock ExpenseClaim@1.0.0
InventoryRestock 1.1.0: exported from the source, hash 2bcad9f3234557f003c209de889798805f8179f774bff91620d2a33c20302309
InventoryRestock 1.1.0: imported into the target, stored inactive
InventoryRestock 1.1.0: activated on the target in place of 1.0.0
InventoryRestock 1.1.0: verified: the target stores hash 2bcad9f3234557f003c209de889798805f8179f774bff91620d2a33c20302309, active; the source stores the same hash
ExpenseClaim 1.0.0: exported from the source, hash none (code catalogue)
ExpenseClaim 1.0.0: imported into the target, stored inactive
ExpenseClaim 1.0.0: activated on the target (no version was active)
ExpenseClaim 1.0.0: verified: the target stores hash 7b5f60b32940900346ae2b5ec3e3418319cc773f0717143f4a0e3a3004a346a7, active
promoted 2 workflow(s) from https://workflow.staging.example to https://workflow.production.example
InventoryRestock is stored and active on the source, so its active version, 1.1.0, is promoted. ExpenseClaim is registered in code on the source and was never imported there, so the export comes from the code catalogue without a hash. A second run finds both versions stored and active, changes nothing and exits 0, so a repeated pipeline run is safe.
The answers of the import
| Answer | Meaning | What the step does |
|---|---|---|
200, wasImported: true | A new version, stored inactive | Continue with the activation |
200, wasImported: false, validationIssues empty | The target already stores this content; nothing changed | Continue |
200, wasImported: false, validationIssues not empty | The target’s validation refused the definition; nothing was stored | Fail, and show the issues |
409 WORKFLOW_DEFINITION_VERSION_HASH_CONFLICT | The target stores other content under this version | Fail; raise the version on the source |
409 WORKFLOW_DEFINITION_ORIGIN_COLLISION | The target stores this content with another origin or other build hashes | Fail (Provenance) |
403 WorkflowActorUnresolved, 403 without a body, 401 | The deploy identity (The target installation) | Fail |
A refused definition answers 200, not 4xx: read validationIssues before wasImported. When the target does not install a module the definition requires, the answer has wasImported: false, an empty contentHash and one issue in validationIssues:
code | path | message |
|---|---|---|
WFIMP010 | $.requiredModules[3] | Required workflow module ‘transport.rabbit’ is not installed. |
In C#
A client in C# uses the request and response types of the StellaOps.Workflow.Contracts package and needs no engine package. The import and its answers, with the export in definition, the import request in import and a small HTTP client that returns the status, the body and the refusal code:
var imported = await target.ImportAsync(import, cancellationToken);
switch (imported)
{
// 200 with validation issues: the target's own modules, functions or activities refuse the
// definition. Nothing is stored.
case { Succeeded: true, Body.ValidationIssues.Count: > 0 }:
foreach (var issue in imported.Body!.ValidationIssues)
{
Write(label, $" {issue.Code} at {issue.Path}: {issue.Message}");
}
return Fail(label, "the target's validation refused the definition; nothing was stored");
case { Succeeded: true, Body.WasImported: true }:
Write(label, "imported into the target, stored inactive");
break;
// 200 without validation issues and not imported: the target already stores this content.
case { Succeeded: true }:
Write(label, "the target already stores this content; nothing changed");
break;
case { Status: HttpStatusCode.Conflict, Error: "WORKFLOW_DEFINITION_VERSION_HASH_CONFLICT" }:
return Fail(label, $"the target stores other content under version {definition.Version}; a stored version never changes, so raise the version on the source");
case { Status: HttpStatusCode.Conflict, Error: "WORKFLOW_DEFINITION_ORIGIN_COLLISION" }:
return Fail(label, "the target stores this content with another origin or other build hashes");
case { Status: HttpStatusCode.Forbidden, Error: "WorkflowActorUnresolved" }:
return Fail(label, "the target token carries no actor claim (WorkflowAuthorization:ActorIdClaimTypes)");
case { Status: HttpStatusCode.Forbidden }:
return Fail(label, "the target token lacks the workflow:admin scope");
default:
return Fail(label, $"the target refused the import: {imported}");
}
Deploy from code
WorkflowDefinitionRemoteDeployService (package StellaOps.Workflow.Publisher) sends one version from the host it runs in to another installation’s import route. Version 1.0.0 has no registration of the service in the container: create it with an HttpWorkflowDefinitionImportTransport, and register that transport as a typed HttpClient:
/// <summary>
/// Registers the HTTP import transport of remote deploy as a typed HttpClient. AddWorkflowPublisher
/// would register it too, but it also adds the publisher's start-up job and checks the
/// WorkflowPublisher options, which remote deploy does not use.
/// </summary>
public static IServiceCollection AddRemoteDeploy(this IServiceCollection services, IConfiguration configuration)
{
services.Configure<RemoteDeployOptions>(configuration.GetSection(RemoteDeployOptions.SectionName));
services.AddHttpClient<HttpWorkflowDefinitionImportTransport>();
return services;
}
An administrator endpoint of the source host, mapped only when configured:
/// <summary>Maps the <c>/deploy</c> route (a POST) behind the admin policy when <c>RemoteDeploy:Enabled</c> is true.</summary>
public static WebApplication MapRemoteDeploy(this WebApplication app)
{
var options = app.Configuration.GetSection(RemoteDeployOptions.SectionName).Get<RemoteDeployOptions>()
?? new RemoteDeployOptions();
if (!options.Enabled)
{
return app;
}
if (string.IsNullOrWhiteSpace(options.TargetUrl) || string.IsNullOrWhiteSpace(options.TargetTokenFile))
{
throw new InvalidOperationException(
"RemoteDeploy:Enabled is true: set RemoteDeploy:TargetUrl and RemoteDeploy:TargetTokenFile.");
}
app.MapPost("/deploy", DeployAsync).RequireAuthorization(WorkflowPolicies.Admin);
return app;
}
It creates the service, reads the target’s token from a file and deploys:
private static async Task<IResult> DeployAsync(
RemoteDeployBody body,
WorkflowDefinitionDeploymentService deployment,
HttpWorkflowDefinitionImportTransport transport,
IOptions<RemoteDeployOptions> options,
ILoggerFactory loggers,
CancellationToken cancellationToken)
{
// The remote deploy service is not registered in the container: create it with the transport.
var service = new WorkflowDefinitionRemoteDeployService(
transport, loggers.CreateLogger<WorkflowDefinitionRemoteDeployService>());
var token = (await File.ReadAllTextAsync(options.Value.TargetTokenFile!, cancellationToken)).Trim();
var result = await service.DeployAsync(
new WorkflowDefinitionRemoteDeployRequest
{
TargetServerUrl = options.Value.TargetUrl!,
TargetAuthToken = token,
WorkflowName = body.WorkflowName,
WorkflowVersion = body.Version,
},
ct => ExportWithProvenanceAsync(deployment, body.WorkflowName, body.Version, ct),
cancellationToken);
return Results.Ok(new RemoteDeployAnswer(Outcome(result), result));
}
The caller supplies the export. WorkflowDefinitionDeploymentService.CreateImportRequestAsync(name, version, importedBy) is the short form, but it leaves the provenance out, so a managed definition arrives as an operator definition. This export copies the provenance from the source’s version list:
/// <summary>
/// Exports a version as an import request, with the provenance of the stored version: its origin,
/// managed code and build hashes. <c>CreateImportRequestAsync</c> leaves them out, so a managed
/// definition would arrive as an operator definition.
/// </summary>
private static async Task<WorkflowDefinitionImportRequest?> ExportWithProvenanceAsync(
WorkflowDefinitionDeploymentService deployment,
string workflowName,
string? version,
CancellationToken cancellationToken)
{
var exported = await deployment.ExportAsync(
new WorkflowDefinitionExportRequest { WorkflowName = workflowName, Version = version, IncludeRendering = true },
cancellationToken);
var versions = await deployment.GetVersionsAsync(
new WorkflowDefinitionVersionsGetRequest { WorkflowName = exported.WorkflowName },
cancellationToken);
var stored = versions.Versions.SingleOrDefault(v => v.Version == exported.Version);
return new WorkflowDefinitionImportRequest
{
CanonicalDefinitionJson = exported.CanonicalDefinitionJson,
RenderingSvgBase64 = exported.RenderingSvgBase64,
RenderingJsonBase64 = exported.RenderingJsonBase64,
RenderingPngBase64 = exported.RenderingPngBase64,
Origin = stored?.Origin ?? "OPERATOR_IMPORTED",
ManagedCode = stored?.ManagedCode,
SourceBuildSha256 = stored?.SourceBuildSha256,
CompatibilitySha256 = stored?.CompatibilitySha256,
};
}
The result reports Succeeded: true only when the target stored a new version. A false result is one of three cases:
/// <summary>
/// <c>Succeeded</c> is true only when the target stored a new version; a false result is one of three
/// cases.
/// </summary>
private static string Outcome(WorkflowDefinitionRemoteDeployResult result) => result switch
{
{ Succeeded: true } => "imported",
// The export or the HTTP call failed. A refusal of the target arrives as the text of the
// HTTP status, for example "... 409 (Conflict)."; the target's error code is not in it.
{ Error: not null } => "failed",
// The target's validation refused the definition; nothing was stored.
{ ValidationIssues.Length: > 0 } => "invalid",
// The target already stores this content.
_ => "already-stored",
};
Behaviour of the service in 1.0.0:
- Refusals of the target. An answer of the target other than 2xx becomes
Errorwith the text of the HTTP status:Target server rejected the import: Response status code does not indicate success: 409 (Conflict).The target’s error code (WORKFLOW_DEFINITION_VERSION_HASH_CONFLICThere) is not in the result. A deployment over HTTP reads it from the answer. - Validation issues come back as text, one string per issue:
WorkflowCanonicalValidationIssue { Code = WFIMP010, Path = $.requiredModules[3], Message = ... }. - Timeout and retries. Each deployment waits 30 seconds for the target and does not retry; the request has no timeout setting. Retry in the caller when the target was unreachable.
- No activation. The target stores the version inactive; activate it on the target (Activate on the target).
Configure the endpoint on the source:
{
"RemoteDeploy": {
"Enabled": true,
"TargetUrl": "https://workflow.production.example",
"TargetTokenFile": "/run/secrets/workflow-production-deployer"
}
}
| Key | Default | Meaning |
|---|---|---|
RemoteDeploy:Enabled | false | Maps the /deploy route, behind the workflow.admin policy |
RemoteDeploy:TargetUrl | none | The base URL of the target; required when enabled |
RemoteDeploy:TargetTokenFile | none | A file with the target’s token: workflow:admin and an actor claim; required when enabled |
curl -s -X POST https://workflow.staging.example/deploy \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"workflowName":"InventoryRestock","version":"1.2.0"}'
{
"outcome": "imported",
"result": {
"succeeded": true,
"targetServerUrl": "https://workflow.production.example",
"workflowName": "InventoryRestock",
"workflowVersion": "1.2.0",
"validationIssues": [],
"error": null
}
}
The same call again answers "outcome": "already-stored" with "succeeded": false.
The publisher is a different feature: at the start of an application it compiles the workflows of that application’s assemblies and imports them into one workflow host. Remote deploy moves a version that one installation stores to another installation.
Activate on the target
Read the target’s active version and hash, then activate with them as the fence:
curl -s https://workflow.production.example/api/workflow/definitions/InventoryRestock/versions \
-H "Authorization: Bearer $TOKEN"
curl -s -X POST https://workflow.production.example/api/workflow/definitions/InventoryRestock/activate \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"workflowName":"InventoryRestock","version":"1.2.0","expectedActiveVersion":"1.1.0","expectedActiveSha256":"2bcad9f3234557f003c209de889798805f8179f774bff91620d2a33c20302309","reasonCode":"RELEASE"}'
{"workflowName":"InventoryRestock","version":"1.2.0","activated":true}
- The body must carry
workflowName, although the route names the workflow: a body without it answers 400 without a body. - Leave out both fence fields when no version is active on the target.
- A fence that no longer holds answers 409
WORKFLOW_DEFINITION_ACTIVATION_FENCE_LOST: another activation came first. Read the versions again. - Activating the version that is already active writes another audit row. A repeated deployment checks the active version and hash first and skips the activation, as the script does.
Roll back
Activating a version older than the active one is a rollback. The request sets allowRollback and names the activation it undoes in rollbackOfAuditId: the audit row’s id, or your change record. With the fence of the active version, 1.2.0:
curl -s -X POST https://workflow.production.example/api/workflow/definitions/InventoryRestock/activate \
-H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"workflowName":"InventoryRestock","version":"1.1.0","expectedActiveVersion":"1.2.0","expectedActiveSha256":"5281627b35280c3a18a104742ba65612852e579bbb6687961e9a740826bf4476","reasonCode":"ROLLBACK","allowRollback":true,"rollbackOfAuditId":"CHG-2041"}'
Without the two fields the target refuses with 409 WORKFLOW_DEFINITION_ROLLBACK_NOT_AUTHORIZED; with them for a version that is not older, with 400 WORKFLOW_DEFINITION_ROLLBACK_TARGET_INVALID.
Every activation and rollback writes one audit row on the target; an import writes none. The HTTP API has no route that reads the audit; on PostgreSQL, query the table:
SELECT action_code, workflow_version, previous_active_version, actor_id, reason_code, rollback_of_audit_id
FROM workflow.wf_definition_audit
WHERE workflow_name = 'InventoryRestock'
ORDER BY created_at_utc;
action_code | workflow_version | previous_active_version | actor_id | reason_code | rollback_of_audit_id |
|---|---|---|---|---|---|
ACTIVATE | 1.0.0 | release-pipeline | PROMOTION | ||
ACTIVATE | 1.1.0 | 1.0.0 | release-pipeline | PROMOTION | |
ACTIVATE | 1.2.0 | 1.1.0 | target-admin-1 | RELEASE | |
ROLLBACK | 1.1.0 | 1.2.0 | release-pipeline | ROLLBACK | CHG-2041 |
The actor is the actor claim of the token that activated: here the pipeline’s deploy identity and an administrator.
Provenance
A stored version has an origin: OPERATOR_IMPORTED, the default of an import, or MANAGED_EMBEDDED for a managed definition with a managed code and two build hashes (Managed import). A durable start admits only a managed, active version whose hash matches, listed in WorkflowDurableStart:Definitions (Durable execution).
The export answer carries no provenance; the source’s version list does (origin, managedCode, sourceBuildSha256, compatibilitySha256). A deployment keeps a managed definition managed only when its import repeats those four fields, as the script and the remote deploy export above do. In C#:
// The export carries no provenance; the source's version list does. A managed definition keeps
// its origin, managed code and build hashes only when the import repeats them.
var sourceVersions = await source.GetVersionsAsync(definition.WorkflowName, cancellationToken);
if (!sourceVersions.Succeeded)
{
return Fail(label, $"the source refused the version list: {sourceVersions}");
}
var stored = sourceVersions.Body!.Versions.SingleOrDefault(v => v.Version == definition.Version);
var import = new WorkflowDefinitionImportRequest
{
CanonicalDefinitionJson = definition.CanonicalDefinitionJson,
RenderingSvgBase64 = definition.RenderingSvgBase64,
RenderingJsonBase64 = definition.RenderingJsonBase64,
RenderingPngBase64 = definition.RenderingPngBase64,
Origin = stored?.Origin ?? OperatorImported,
ManagedCode = stored?.ManagedCode,
SourceBuildSha256 = stored?.SourceBuildSha256,
CompatibilitySha256 = stored?.CompatibilitySha256,
};
- A managed definition imported without these fields is stored as an operator definition, which a durable start never admits.
CreateImportRequestAsyncproduces such an import. - A stored version keeps its provenance. Importing the same content with another origin or other build hashes is refused with 409
WORKFLOW_DEFINITION_ORIGIN_COLLISION; to correct it, import a new version. importedByon the target is the actor of the deploy token, not the importer on the source.
Pitfalls
- Promoting before the code. A definition stored and active on the target does not run until the target’s hosts register the workflow; a start answers 404
WorkflowDefinitionNotFound. - Writing the JSON again. Pretty-printing, minifying or re-encoding the definition changes the bytes and the hash: the target then refuses it under a version it already stores, with 409. Pass the string on unchanged.
- jq on Windows. Raw output (
-r,-j) of a native jq for Windows has CRLF line ends; never write the definition with it. - Reading
wasImported: falseas success. CheckvalidationIssuesfirst. - Reading
Succeeded: falseas a failure. Remote deploy also reportsfalsewhen the target already stores the version; tell the cases apart byErrorandValidationIssues. AddWorkflowPublisherfor the transport. It also registers the publisher’s job, which publishes the application’s own workflows at start, and checks theWorkflowPublisheroptions. Register the transport withAddHttpClient<HttpWorkflowDefinitionImportTransport>().- A target without a module the source has. The import is refused with
WFIMP010; register the module on the target, then deploy again. - Changing content under a released version. The target keeps the version it stored first; raise the version.
- A stale fence. Read the target’s versions just before you activate.
