Workflow engine licence monitor

Scope. How the Workflow engine counts and lists Designated Workflows, reads a licence record offline, reports a licence status with its warnings and shows the licence notice. For operators who run the engine and for implementers who host it. The file format is the component licence file contract.

The licence status is informational. The engine refuses, restricts and stops nothing because of a count, a notice level, a licence record or its status: every workflow registered in code or imported is registered, recorded and served, whatever the count (Thresholds and warnings). The status never fails readiness or liveness and never triggers a restart. The engine makes no network call and sends no telemetry: the count, the licence record and the status stay in the installation.

The status describes the licence records the local reader can see. It is not a determination of entitlement or compliance; the order and the applicable licences prevail over the file and over any status. The absence of a warning is not a compliance attestation.

Counting

The counted unit is the Designated Workflow: every workflow the installation has ever registered in code (the code catalogue, IWorkflowRegistrationCatalog) or stored in the definition store (definition import). The count is cumulative:

• A workflow counts from the first time the engine sees it and keeps counting. Removing it from the code catalogue, replacing its versions or activating another version does not reduce the count. The product has no operation that removes a workflow from the count.
• Versions are not counted: a workflow with several versions counts once.
• Names that differ only in letter case are one workflow, as the engine resolves them.

The engine counts with a technical counter: the workflow names recorded in the first-seen ledger. It is separate from the contractual Designated Workflow count of the component licence. It includes names registered only for non-production use and counts names, not logical workflows: a new name adds a unit even when it continues an earlier workflow, and distinct workflows that share a name are one unit. Its rules:

1. The counter is cumulative within its ledger: a recorded name is never removed. The durable ledger keeps its names across restarts; the process-memory ledger keeps them only while the process runs.
2. A unit is added only when a name is recorded, by registration from the code catalogue or by storage through an import.
3. An operation that fails before its name is recorded adds nothing.
4. Further versions under a recorded name add nothing.
5. Names compare case-insensitively. There is no alias mechanism: each distinct name is a unit.
6. Deleting and registering again, or restoring, a workflow whose name is recorded adds nothing, because the ledger is insert-only.
7. Engines that share one ledger are serialised, so each name is recorded once. A host without the shared ledger applies the same rule in memory, per process.

Losing or replacing the ledger does not reset the installation’s contractual count.

The count is kept in the first-seen ledger:

On a host without a workflow store the count can therefore be incomplete. The health entry reports the ledger as process-memory in that case, and durable on the PostgreSQL, Oracle and MongoDB stores.

The ledger is filled in two places:

• Licence evaluation, at startup and every hour: the engine records every workflow of the code catalogue, then every workflow stored in the definition store (active or not). The second pass also records definitions that were stored before the ledger existed, and imports whose recording failed.
• Definition import (WorkflowDefinitionDeploymentService.ImportAsync): a stored workflow is recorded after it is stored. An import that fails before it is stored records nothing. If the ledger cannot be written, the import still succeeds, a warning with the count-unavailable message is logged, and the next evaluation records the workflow from the definition store.

On PostgreSQL and Oracle every recording locks the ledger table for its transaction, so engine instances that share the database record each name once. The lock only orders the recordings; it refuses nothing. On MongoDB the unique index keeps one document per name: of concurrent first sightings, the first one written is kept, and the others find the name recorded.

The definition stores (PostgreSQL, MongoDB, and the optional Oracle adapter) delete no definition; activating another version keeps the earlier ones. A stored workflow therefore stays in the count for the life of the store.

Thresholds and warnings

The component licence sets two levels for the count, ComponentFreeLimits.WorkflowNoticeLevel and ComponentFreeLimits.WorkflowFreeLimit (StellaOps.Components.Licensing). The component licence states their values.

• Up to the notice level the status is within-free-limit. It is logged at information level at startup and when it changes.
• Above the notice level and within the free limit, without a licence entry that covers the running version, the status is above-notice-level: a warning with counsel’s message, which says that the technical count is not the contractual Designated Workflow count. Crossing the notice level does not itself establish that additional production permission is required and creates no fee.
• Above the free limit the status depends on the licence records: record-matches when a standard-capacity entry covers the running version and the count is within its capacity, count-exceeds-recorded-capacity when the count is above that capacity, no-matching-record when no entry covers the running version, and development-build when the running build carries no first-publication date.

Every status except within-free-limit and record-matches is a warning in the log at startup and every hour (Output). A warning refuses nothing: imports and code registrations are never refused for licence reasons, every workflow keeps running and takes new versions, and readiness and liveness never change. Every installation counts, in every environment; no setting turns the count or the warnings off. A development build carries no first-publication date, so no standard-capacity entry covers it.

When the ledger cannot be read, the status is count-unavailable with the message “The local workflow-name count is unavailable.” The engine keeps serving every workflow and accepts imports; the next evaluation reads the ledger again.

A status withdraws no right; the order and the applicable licences prevail over the licence record and over any status or warning.

Listing the count

GET /api/workflow/designated-workflows lists the first-seen ledger and returns its count. It needs the View policy (scope workflow:view, workflow:operate or workflow:admin). It only reads: it records nothing and sends nothing anywhere. It also returns the licence status and the licence notice of the latest licence evaluation.

curl -s https://workflow.example/api/workflow/designated-workflows -H "Authorization: Bearer $TOKEN"

{
  "designatedWorkflows": 3,
  "ledger": "durable",
  "workflows": [
    { "workflowName": "SampleImported", "firstSeenSource": "import", "firstSeenOnUtc": "2027-06-01T08:05:00+00:00" },
    { "workflowName": "SampleRetired", "firstSeenSource": "catalog", "firstSeenOnUtc": "2027-06-01T08:00:00+00:00" },
    { "workflowName": "SimpleApproval", "firstSeenSource": "catalog", "firstSeenOnUtc": "2027-06-01T08:00:00+00:00" }
  ],
  "licence": {
    "status": "within-free-limit",
    "message": "Recorded workflow-name count: 3.",
    "explanation": "The notice levels are informational and are below the standard free-production limits of [free limit] Endpoints for Router and [free limit] Designated Workflows for Workflow. Crossing a notice level does not itself establish that additional production permission is required and does not create a fee. The applicable LICENSE, any Order and other independently applicable permissions determine permitted use.",
    "warns": false
  },
  "notice": {
    "text": "Licensed to Northwind Traders | component: workflow | licensed capacity: 1000 | covers versions first published before: 2027-11-03 | status: within-free-limit",
    "case": "licensed-to",
    "licensee": "Northwind Traders",
    "permission": "standard-capacity",
    "licensedCapacity": 1000,
    "coversVersionsPublishedBefore": "2027-11-03",
    "versionScope": null,
    "effectiveDate": null,
    "recordsInForce": 1,
    "licenceFilesNotInForce": 0
  }
}

The list shows the ledger as its latest recording left it. An import is listed at once, while the monitor’s designatedWorkflows (the licence entry of /readyz) changes at its next evaluation, at most an hour later; after that evaluation both report the same count. If the ledger cannot be read, the request fails; the endpoint never returns a partial list.

Count procedure

On a host with the PostgreSQL, Oracle or MongoDB store (ledger is durable):

1. Read GET /api/workflow/designated-workflows.
2. The count is designatedWorkflows. It includes every workflow ever registered in code or stored, also those removed from the code catalogue since.
3. To check it against the monitor, compare it with designatedWorkflows in the licence entry of /readyz after the next evaluation, or after a restart.

On a host without a workflow store (ledger is process-memory) the endpoint lists only the workflows registered in code in the running process, so a workflow removed from the code catalogue in an earlier deployment is missing. Keep a local register instead:

1. Opening register. When counting starts on the installation, record every workflow the endpoint lists, with the date.
2. Later designations. After every deployment, read the endpoint again and add each workflow the register does not hold, with the date.
3. No removals. Never remove an entry. A workflow removed from the code catalogue stays in the register, as it would stay in the durable ledger.
4. The count is the number of entries. Names that differ only in letter case are one entry, and versions are not counted.

The register stays in the installation and is sent nowhere.

Covered versions

A licence file entry covers the versions of the engine first published before its date (coversVersionsPublishedBefore, an exclusive UTC calendar date). The engine takes the first-publication date of the running version from the StellaOps.Component.PublishedAt assembly metadata of the engine assembly, stamped when the release is packed. A build or adaptation of a released version keeps the stamp of its source release; its own build date is never used. A build without the stamp is a development build.

The current date never changes the result: a version first published before an entry’s date stays covered after that date has passed. A standard-capacity entry records its capacity as a number of Designated Workflows; the highest capacity among the entries that cover the running version applies, and entries are never added together.

An embedded line records a no-fee permission for software a customer delivers to its own clients: one entry with unlimited capacity, the version scope delivered-without-cutoff (any version the customer delivers) and an effective date, without a cutoff. It covers every version, a development build included. The engine cannot verify the named product, the end-customer installation or the delivery, so above the notice level the status is embedded-scope-not-established, and the notice describes the recorded permission without certifying it.

The licence file

The licence record is a DSSE envelope signed with a Stella Ops vendor-entitlement key and checked offline, supplied as a file or as a licence key (the same signed record as one base64 line). Use within the free limit needs no record. A record that fails a check is not loaded and its reason is shown as a detail; it never stops the engine.

The engine reads the records again at every evaluation, so a new file takes effect within an hour without a restart. The refusal codes and the continuity rules of later revisions are in the contract.

Statuses

The first status that holds is reported. [count] is the technical count, [notice level] the notice level, [date] the cutoff of the deciding entry.

The licence-status explanation accompanies the messages in the warning log, the health entry and the designated-workflows API:

The notice levels are informational and are below the standard free-production limits of [free limit] Endpoints for Router and [free limit] Designated Workflows for Workflow. Crossing a notice level does not itself establish that additional production permission is required and does not create a fee. The applicable LICENSE, any Order and other independently applicable permissions determine permitted use.

No status or message says that an installation is unlicensed, non-compliant or expired.

Licence notice

The engine shows a licence notice built from each licence evaluation. When an entry of a loaded record covers the running version, the notice is “Licensed to” the licensee display name of the line whose entry decides; otherwise it is the message of the case:

“Licensed to [licensee]” identifies the local licence record. It does not certify the author, content, authenticity or compliance of a workflow, diagram or other output. For an embedded line the notice describes the recorded permission (permission, unlimited capacity, version scope and effective date) and does not certify that the use is within it.

The contract states the cases and the one-line form. In the health and API output the notice is an object with the fields and case names of the Router’s licence notice, and the fields of an embedded line:

The notice appears in four places:

• Logs: one information line at startup and one at every hourly evaluation, whatever the status, in the one-line form, for example Workflow licence notice: Licensed to Northwind Traders | component: workflow | licensed capacity: 1000 | covers versions first published before: 2027-11-03 | status: record-matches.
• Health: the notice object in the data of the licence entry. The retained web host serves /readyz without authentication, so the licensee display name is visible to anyone who can reach that endpoint; licence serials, order references and the Installation identifier are not in it. /healthz reports no entry data.
• Licence API: the notice of GET /api/workflow/designated-workflows, which needs the View policy.
• SVG renders: WorkflowRenderSvgRenderer.Render(layout, title, licenceNotice) (StellaOps.Workflow.Renderer.Svg) writes the notice as visible text along the bottom edge of every diagram (attribute data-licence-notice), escaped for XML. A host that runs the engine passes NoticeHeadline of the latest evaluation (WorkflowLicenceState.Current); a host that loads no licence record, such as a build-time export, passes WorkflowRenderSvgRenderer.NoLicenceRecordNotice. An SVG stored with an imported definition is served as it was imported.

Output

The monitor (WorkflowLicenceMonitor) and the health entry are registered by AddWorkflowEngineHostedServices; the ledger, the licence record reader and the evaluation by AddWorkflowEngineCoreServices, and the durable ledger by AddWorkflowPostgresDataStore. The first evaluation runs once the host has started, after the store has created its schema.