Workflow engine¶
This page covers authoring, operating, and extending Trustpoint’s WorkflowV2
implementation (workflows2). Workflows automate approval decisions, HTTP calls,
email, and Trustpoint notifications around devices and certificate requests.
The Mental Model¶
A workflow has five main parts:
triggerChooses which event starts the workflow.applyOptional preconditions. Every item inapplymust match.workflow.startThe first step to run.workflow.stepsNamed step definitions.workflow.flowTransitions between steps.
At runtime you can read:
event.*vars.*
event is read-only runtime input.
vars is mutable workflow state written by steps such as set, compute, and webhook.capture.
Triggers and scope¶
The built-in registry exposes these production triggers:
Event group |
|
Event context |
|---|---|---|
Device lifecycle |
|
|
Certificate lifecycle |
|
|
CMP requests |
|
|
EST enrollment |
|
|
REST enrollment |
|
|
workflows2.test is an internal test trigger. SCEP has no built-in enrollment
trigger. Lifecycle triggers allow automation steps; request triggers also allow
approval, except during after_issuance.
trigger.sources.trustpoint: true matches all sources. Otherwise, at least one
of ca_ids, domain_ids, or device_ids must be nonempty. A match in any of
these lists is sufficient; the lists are not combined with AND. CA and domain
IDs are integers, while device IDs are strings. In contrast, every condition in
apply must match. Source filtering and apply run before an instance is created.
The editor’s context catalog lists the supported paths for the selected trigger.
Enrollment context includes the requested profile at event.cmp.cert_profile,
event.est.cert_profile, or event.rest.cert_profile. EST and REST events also
include the CSR PEM and its fingerprint. CMP uses the encoded request body for
its fingerprint. Do not assume an arbitrary event.meta namespace exists.
Certificate lifecycle event.certificate.serial_number is the certificate’s
assigned serial number. The post-issuance enrollment subject serial number is a
separate field described under Effective enrollment certificate attributes.
Lifecycle States¶
Workflow instance and run states use the same vocabulary where possible.
State |
Meaning |
Operator action |
Request decision |
|---|---|---|---|
|
Work is waiting for a worker or inline drain. |
Wait. |
Wait. |
|
Work is currently executing. |
Wait. |
Wait. |
|
An approval step is waiting for a decision. |
Approve or reject. |
Wait. |
|
Execution stopped safely and can resume from the stored next step. |
Resume or stop. |
Wait. |
|
Execution hit a retryable runtime error. |
Resume or stop. |
Wait. |
|
The workflow reached the end of a branch without an explicit business result. |
None. |
Continue. |
|
The workflow ended with an approved business result. |
None. |
Continue. |
|
The workflow ended with a rejected business result. |
None. |
Reject. |
|
An approval timeout ended the workflow. |
None. |
Fail. |
|
An operator or workflow intentionally stopped execution. |
None. |
Fail. |
|
An operator cancelled the run or instance. |
None. |
Fail. |
Important:
erroris not final. It stays visible in Waiting until an operator resumes or stops it.stoppedis final, but keepsstatus_reasonandstatus_messageso a stopped-after-error workflow still shows the error context.finishedonly means there is no more workflow work to do. Useapproved,rejected,timed_out, orstoppedwhen the end state itself is the business result.
Enrollment decisions and request locks¶
A trigger emission groups matching definitions into a run. Each definition has its own instance, and all matching enrollment workflows must permit continuation. The request decision also checks stored approvals: a rejected approval rejects the request, and an expired approval fails it, even if later steps change the instance status. Pending approvals keep a request waiting.
Request fingerprints provide idempotency keys, allowing repeated requests or polls
to reuse a run. Successful requester-visible delivery can release the key
through request/workflow2_issuance.py. For terminal runs that still hold a key,
Allow same request again releases it manually without changing the old result.
An identical request can then create a new run. The Runs page displays locked,
released, and manually released states.
Operator views¶
Definitions: create, edit, enable, and disable definitions; their names come from YAML
name.Runs: inspect events, source snapshots, instances, results, and request locks; filter by status, trigger, and lock state.
Waiting / Approvals: resolve pending decisions and inspect paused or errored instances. Resume retries the stored current step; Stop ends the instance.
Minimal Example¶
schema: trustpoint.workflow.v2
name: Device created notification
enabled: true
trigger:
on: device.created
sources:
trustpoint: true
ca_ids: []
domain_ids: []
device_ids: []
apply:
- exists: ${event.device}
workflow:
start: notify
steps:
notify:
type: email
title: Send email
to:
- ops@example.com
subject: New device ${event.device.common_name}
body: |
Device ID: ${event.device.id}
flow: []
Demo workflows¶
Explicit demo-data setup installs four editable [Demo] workflows through the
existing add_domains_and_devices command. The setup wizard’s demo-data option,
TP_INJECT_DEMO_DATA, and reset_db --add all use this path. Normal initialization
without demo data installs none. Setup imports YAML definitions only; it does not
start executions. All demo workflows start disabled and must be enabled explicitly.
Repeating setup preserves existing definitions, including renamed, disabled, or
edited examples.
Workflow |
Initial state |
Behavior |
|---|---|---|
Enrollment approval |
Disabled |
CMP initialization waits for approval; rejection denies enrollment and one hour without a decision times out. |
Conditional enrollment approval |
Disabled |
CMP initialization with |
Issued certificate email |
Disabled |
Emails final certificate attributes after CMP initialization issuance. |
Final certificate webhook |
Disabled |
Posts final certificate attributes after CMP initialization issuance and branches on the HTTP response status. |
Open Workflows, select a [Demo] definition, and inspect its YAML and flow
graph. Each YAML file starts with comments explaining its inputs and behavior.
The normal Save & Compile formatter removes YAML comments.
The existing editor generates the graph layout automatically.
Fixtures live directly in workflows2/demo_workflows/*.yaml. The loader imports
the YAML files through the existing compiler; filenames provide stable workflow
identities. All examples use cmp.initialization with trustpoint: true, so they
apply across all domains. No manifest, placeholders, or editor changes are needed.
To execute an example, use a device with CMP enrollment configured in any domain.
Use the device’s enrollment help for credentials and request commands. Request an
application certificate using the existing tls_client profile. For conditional
approval, request tls_server to take the manual branch instead. Normal device,
authentication, CA, and profile checks still apply. Resolve pending approvals in
the workflow approval queue, then use CMP polling as instructed by the response.
The normal inline/worker execution setting applies; worker mode requires the
existing workflows2_worker process.
Both approval examples initially match the same CMP initialization requests. All matching workflows must permit issuance, so disable the manual approval example when trying the conditional example’s automatic path on its own.
Email and webhook examples use the services in docker-compose.demo.yml. Start
Trustpoint first so its shared Docker network exists, then start the demo services:
docker compose -p trustpoint-demo -f docker-compose.demo.yml up -d
Use the same TRUSTPOINT_NETWORK_NAME for both Compose projects if you override
the default trustpoint-net. The workflow worker must also join this network.
In Management > Settings > SMTP Email, enable SMTP and save these Mailpit settings:
Setting |
Value |
|---|---|
Host |
|
Port |
|
TLS / SSL |
Both disabled |
Username / password |
Both blank |
Sender |
|
The email workflow sends to operator@trustpoint.example; view captured messages
at http://localhost:8025. The webhook already posts to
http://webhook-echo:8080/trustpoint/certificates. Inspect its requests with:
docker compose -p trustpoint-demo -f docker-compose.demo.yml logs -f webhook-echo
For Trustpoint running directly on the host, use SMTP host localhost and webhook
URL http://localhost:8081/trustpoint/certificates instead. If you override
MAILPIT_SMTP_PORT, MAILPIT_UI_PORT, or WEBHOOK_ECHO_PORT, use those ports for
host access; container-to-container ports stay 1025, 8025, and 8080.
Enable the desired workflow and Save & Compile before submitting an enrollment. Email and webhook notifications run after the matching approval workflows permit issuance. Both examples initially remain disabled. Reinitialization preserves existing definitions, so apply these values in the editor for previously imported examples.
The email and webhook use the final issued certificate after profile processing.
For example, a final subject containing serialNumber=SN123456 produces
"subject_serial_number": "SN123456" in the webhook body, even if the original CSR
or stored device has a different value. If the final subject lacks this attribute,
the body contains "subject_serial_number": "". This is the subject serialNumber
(OID 2.5.4.5), separate from the certificate’s CA-assigned integer serial number.
Use a profile that permits the requested subject serialNumber, such as the default
tls_client profile, to preserve it through issuance.
The webhook captures HTTP status in vars.http_status. A 2xx response finishes the
workflow; other HTTP responses stop it with an explanatory message. Transport
failures enter the engine’s retryable error state. Both email and webhook run in
after_issuance, so notification failure cannot undo issuance or block delivery.
Effective enrollment certificate attributes¶
The existing enrollment triggers support trigger.phase: after_issuance:
cmp.initialization,cmp.certification, andcmp.keyupdateest.simpleenrollandest.simplereenrollrest.enrollandrest.reenroll(including enrollment through the management API)
Set this phase explicitly for notifications about a successfully issued certificate.
Omitting phase retains the existing before_issuance behavior, including approval,
rejection, and request gating. Those earlier events do not contain request.
An existing pre-issuance workflow must opt into after_issuance to use the effective
certificate fields. Approval steps are unavailable in this phase; notification
failure cannot reverse issuance or block delivery. Trigger names and source filters
are unchanged. SCEP is not supported by these workflow triggers.
Post-issuance events retain the existing device, source, and protocol-specific
(cmp, est, or rest) sections, and add:
{
"phase": "after_issuance",
"request": {
"subject": {
"common_name": "Trustpoint-Domain-Credential",
"serial_number": "SN123456",
"organization": null,
"organizational_unit": null,
"country": null,
"state_or_province": null,
"locality": null
},
"subject_alternative_names": {
"dns_names": ["plc.example.com"],
"ip_addresses": ["192.168.1.10"],
"uris": [],
"email_addresses": []
}
}
}
Despite its interface name, request contains attributes extracted from the final
issued X.509 certificate after certificate profile processing, including any
changes made by an upstream CA. It does not expose the original CSR or CRMF values.
request.subject.serial_number is the subject’s serialNumber attribute (OID 2.5.4.5).
It is independent of the stored device.serial_number and of the certificate’s
automatically assigned integer serial number.
Every listed subject key is a string or null; every SAN key is an array of strings
and is [] when absent. IP addresses use canonical string notation. For repeated
subject attributes, the first value in certificate subject order is selected,
matching credential saving’s first-value convention. This simple view does not
preserve repeated RDNs, arbitrary OIDs, or unsupported SAN types.
Values are captured when issuance succeeds, before deferred dispatch. Dispatch waits for the issuance transaction to commit, so failed or rolled-back issuance does not emit a post-issuance event. The run and each workflow instance persist the snapshot; later device or certificate changes do not affect delayed or retried execution. CMP approval followed by polling uses the original enrollment operation.
Example forwarding the effective subject serial number:
schema: trustpoint.workflow.v2
name: CMP Effective Subject Serial Number Webhook
enabled: true
trigger:
on: cmp.initialization
phase: after_issuance
sources:
trustpoint: true
ca_ids: []
domain_ids: []
device_ids: []
workflow:
start: forward_serial
steps:
forward_serial:
type: webhook
title: Forward effective certificate subject serial number
method: POST
url: http://webhook-echo:8080/trustpoint/certificates
headers:
Content-Type: application/json
body:
effective_subject_serial_number: ${event.request.subject.serial_number}
stored_device_serial_number: ${event.device.serial_number}
operation: ${event.cmp.operation}
flow: []
The URL targets webhook-echo from the demo Compose setup described above.
Replace it when using a different receiver.
The expression resolver renders ${...} templates as strings; a null subject
value becomes an empty string in a templated webhook body. The persisted event
still contains JSON null. To send only when a serial number exists, add:
apply:
- exists: ${event.request.subject.serial_number}
Supported Step Types¶
logic¶
Evaluates ordered cases and returns an outcome string.
route_status:
type: logic
cases:
- when:
compare:
left: ${vars.http_status}
op: ==
right: 200
outcome: ok
default: fail
Notes:
Supports nested
and,or,not,exists, andcompare.Every possible outcome must have a matching
workflow.flowentry.
webhook¶
Makes an HTTP request and can capture response data into workflow vars.
call_api:
type: webhook
method: POST
url: https://example.com/api/${event.device.serial_number}
headers:
x-device-id: ${event.device.id}
body:
serial: ${event.device.serial_number}
capture:
vars.http_status: status_code
vars.http_body: body
Capture sources:
status_codebodyheadersheaders.<name>body.<path>
email¶
Sends an email with templated subject and body.
notify:
type: email
to:
- ops@example.com
subject: Device ${event.device.common_name}
body: |
Status: ${vars.status}
notification¶
Creates a Trustpoint notification with templated custom text.
create_notification:
type: notification
severity: warning
source: device
short: Device ${event.device.common_name} needs review
long: |
Device ID: ${event.device.id}
Result: ${vars.result}
initial_status: new
event: workflow.device.review
related:
device_id: ${event.device.id}
Supported severities:
setupinfowarningcritical
Supported sources:
systemdevicedomaincertificateissuing_ca
Optional related keys:
device_iddomain_idcertificate_idissuing_ca_id
set¶
Writes literal or templated values into workflow vars.
mark_ok:
type: set
vars:
vars.result: ok
vars.message: Status was ${vars.http_status}
Important:
Prefer
set.varskeys invars.<name>form for consistency with webhook capture, compute, and references.Legacy plain keys are still accepted by the compiler, but the editor now writes
vars.<name>.
set_status¶
Sets the workflow instance status intentionally. Use this when the workflow itself has reached a business decision such as approved, rejected, stopped, paused, or timed out.
reject_device:
type: set_status
status: rejected
reason: policy_rejected
message: Device ${event.device.common_name} did not pass policy review.
Supported statuses:
finishedapprovedrejectedtimed_outstoppedpaused
Important:
reasonis a short static value stored on the workflow instance.messageis templated and shown on the instance detail page.pausedmust have one outgoing linear flow entry; that target becomes the next step after resume.Other
set_statusstatuses are terminal and cannot have outgoing flow entries.erroris reserved for retryable runtime failures withstatus_reason: runtime_error.
compute¶
Writes workflow vars using safe expressions.
compute_score:
type: compute
set:
vars.score: ${add(vars.base_score, 1)}
You can also use YAML operator mappings:
compute_score:
type: compute
set:
vars.score:
add:
- ${vars.base_score}
- 1
Important:
compute.settargets must usevars.<name>.Within one compute step, later assignments may reference vars assigned earlier in the same
compute.setblock.
approval¶
Pauses execution until an external approval decision is resolved.
approval_gate:
type: approval
timeout_seconds: 3600
Notes:
Approval outcomes default to
approved,rejected, andtimed_out.Approval outcomes can be routed in
workflow.flow, but they do not have to be.If an approved approval has no route, the workflow instance ends as
approved.If a rejected approval has no route, the workflow instance ends as
rejected.Without a timeout route, expired approvals end as
timed_out.approved_outcome,rejected_outcome, andtimeout_outcomecan customize outcome names.A routed timeout branch must reach an explicit
set_statusresult ofrejected,timed_out,stopped, orpaused. Implicit completion orapprovedis rejected by the compiler. The recorded expired approval still prevents enrollment from continuing.
Flow Rules¶
Linear transition:
- from: call_api
to: mark_ok
Outcome-based transition:
- from: route_status
on: ok
to: mark_ok
Every step must be reachable from workflow.start. Linear steps may have one
outgoing linear edge; logic needs a route for every declared outcome. Approval
routes follow the rules above. Terminal set_status steps cannot have outgoing
edges, while paused requires one linear edge to its resume point. There are no
special $end or $reject target tokens.
To end a branch, omit the outgoing transition. To end a branch with a non-finished
result, use set_status.
reject_device:
type: set_status
status: rejected
reason: policy_rejected
message: Device did not pass policy review.
Conditions¶
Supported condition operators:
existscomparenotandor
Example:
- and:
- exists: ${vars.http_status}
- compare:
left: ${vars.http_status}
op: ==
right: 200
compare.op supports ==, !=, <, <=, >, and >=.
and and or require nonempty condition lists.
apply uses list semantics, so all items in the apply: list must match.
Expressions¶
Expressions are written as ${...}.
Allowed reference roots:
event.*vars.*
Supported function families:
numeric:
add,sub,mul,div,min,max,round,int,floatstring:
str,lower,upper,concatdebug:
json
Examples:
${event.device.common_name}
${upper(event.device.common_name)}
${round(vars.score)}
${concat(vars.prefix, "-", vars.suffix)}
Variable Availability Rules¶
This is one of the most important Workflow 2 rules.
A step may only rely on workflow vars that are guaranteed to exist on every incoming reachable path.
That means:
a var created on only one branch is not safe at a later merge step
unreachable steps do not count
the graph and guide show the vars available before a step runs
the compiler enforces the same rule when you save and compile
Also note the difference between set and compute:
setrenders the full mapping first, then writes valuescomputeevaluates assignments in order, so later compute expressions can use earlier compute outputs from the same step
Using the Editor¶
YAML Editor¶
YAML is always the source of truth.
Save & Compile formats YAML canonically before saving.
Undo/redo works inside the editor.
Guide Drawer¶
Open the guide with Ctrl+K (Cmd+K on macOS).
Use it to:
inspect field requirements
edit structured content for logic, webhook, compute, set, and set_status steps
insert scoped variables and expression helpers
Graph Editor¶
Use the graph to:
preview incomplete workflows
drag nodes
create edges from node handles
right-click a node or edge to edit it
right-click empty canvas to add a step at the cursor
delete the selected node or edge with
DeleteorBackspaceclose editors or menus with
Escape
The graph stays available even if the workflow is incomplete. Problems show up in the issues panel instead of making the editor disappear.
Issues Panel¶
The issues panel highlights:
YAML syntax problems
draft graph problems
editor action errors
compile errors after save
When possible, selecting an issue focuses the YAML editor at the relevant location.
Common Compile Errors¶
Unreachable step¶
Every step must be reachable from workflow.start.
Missing outcome flow¶
Every logic outcome must have a matching workflow.flow entry. Approval
outcomes may omit routes and use the built-in terminal decisions.
Variable may not be initialized¶
You referenced vars.<name> before that var is guaranteed to exist.
Unknown key or step type¶
The schema linter rejects unsupported keys and step types early.
Wrong webhook capture format¶
Use:
capture:
vars.http_status: status_code
Do not use the older legacy capture shape.
Execution and worker operation¶
management.models.workflows2.WorkflowExecutionConfig stores the execution mode:
Mode |
Behavior |
|---|---|
|
Use the worker when a recent heartbeat exists; otherwise drain jobs inline. |
|
Enqueue jobs and drain them in the current process. Within a transaction, drain after commit. |
|
Enqueue jobs for the dedicated worker. |
All modes use the same database job queue and worker semantics. Inline mode does not bypass the queue. The default worker-liveness threshold is 30 seconds. Run the worker from the repository root:
python trustpoint/manage.py workflows2_worker
Option |
Default |
Purpose |
|---|---|---|
|
Hostname |
Worker identity. |
|
30 |
Job lease duration; |
|
10 |
Jobs per tick; |
|
1.0 |
Seconds between ticks. |
|
180 |
Wait for required tables; |
|
Off |
Run one tick and exit. |
The command writes worker-presence heartbeats every five seconds. A separate per-job heartbeat renews a running job’s lease at half the lease duration, with a minimum interval of one second; it is disabled on SQLite and during inline draining. PostgreSQL workers coordinate claims with row locking and skip locked rows. SQLite uses a best-effort fallback.
An expired job lease marks the job failed and pauses an eligible instance for
operator review. It does not automatically replay external side effects. Runtime
step exceptions record an error state at the current step, which an operator
can resume or stop. Job infrastructure failures can retry when the job’s
max_attempts allows it; the model defaults to zero retries. Do not assume
webhook failures receive automatic retries. Webhook HTTP error status codes are
returned as data; use capture plus logic to handle them. Transport exceptions
enter the runtime error path. External receivers should tolerate a repeated call
when an operator retries after an uncertain result.
The workflow worker is separate from Django-Q2’s maintenance scheduler. Workflow
steps do not directly issue, revoke, or renew certificates: the enrollment
pipeline performs those operations after any pre-issuance gates permit them.
There are no generic pki.* step types or approval-group settings.
Troubleshooting¶
Symptom |
Check |
|---|---|
Work remains queued |
Execution mode, worker process, heartbeat freshness, and database connection. |
Instance shows |
Step-run error and event snapshot, SMTP/HTTP destination, then Resume or Stop. |
Instance paused after lease expiry |
Worker crash or lease/heartbeat problem; inspect external side effects before resuming. |
Approval has expired |
Waiting / Approvals refresh and resolution paths apply expiration handling; it is not a dedicated Q2 timeout task. |
Enrollment still waits after an approval |
Other instances and pending approvals in the same run. |
Workflow never matches |
Enabled flags, trigger phase, source filters, and |
Implementation and extension¶
All paths below are relative to trustpoint/workflows2/ unless explicitly prefixed
with a repository path. This section describes the code implementing the authoring
and execution behavior above.
Compilation and persistence¶
WorkflowDefinitionService in services/definitions.py formats YAML, compiles it,
and saves Workflow2Definition. compile_workflow_yaml in
compiler/compiler.py loads the document, applies SchemaLinter, compiles
conditions, templates, expressions, steps, and transitions, and validates trigger
policy, flow completeness, reachability, and variable availability. The IR stores
workflow.transitions derived from YAML workflow.flow, plus source/IR hashes
and a compiler version in meta.
Module |
Responsibility |
|---|---|
|
Reject unknown schema keys and step types. |
|
YAML loading and canonical formatting. |
|
Allowed expression roots/functions and |
|
Compile condition trees. |
|
Stable source and IR hashing. |
|
Register trigger metadata. |
|
Advertise event context and allowed steps. |
|
Step-field and expression metadata consumed by the editor. |
Top-level keys are schema, name, enabled, trigger, apply, and workflow.
There is no description field; use comments for authoring notes. The demo loader
in services/demo.py compiles YAML from demo_workflows/ and preserves its source
comments on initial import. UUIDs derived from filenames allow reruns to skip
existing definitions even after users rename them. The only initialization hook
is the explicit pki command add_domains_and_devices.
Durable execution¶
Model in |
Responsibility |
|---|---|
|
YAML, compiled IR, hashes, enabled flag, and trigger index. |
|
Event emission, source snapshot, aggregate status, and idempotency metadata. |
|
One definition’s event/vars, current step, status, and reason/message. |
|
Step execution audit records. |
|
Pending/approved/rejected/expired decision, expiry, actor, and comment. |
|
Queued/running/done/failed/cancelled work, leases, attempts, and errors. |
|
Worker presence. |
|
Layout snapshot model; the current draft editor computes its layout client-side. |
services/dispatch.py selects enabled matching definitions, reuses idempotent
runs when appropriate, persists runs and instances, and enqueues jobs.
services/worker.py claims and executes jobs, normally advancing one step per job.
services/runtime.py checkpoints instance progress, records step runs and
approvals, and aggregates run status. services/transitions.py centralizes state
changes; services/request_decision.py translates them into enrollment decisions.
engine/executor.py evaluates steps against the RuntimeContext event and vars.
engine/eval.py evaluates conditions and expressions. engine/adapters.py
isolates email, HTTP, and Trustpoint notification side effects. Tests can inject
adapter doubles without contacting external services.
Enrollment integration and final certificate snapshots¶
trustpoint/request/workflows2_handler.py builds protocol event payloads.
trustpoint/request/enrollment.py preserves the pre-issuance decision gate and
calls Workflow2CertificateRequestHandler.handle_issued after successful
processing. CMP polling calls the same handler on its finalized replay context.
events/payloads.py:build_enrollment_request_snapshot extracts the supported
subject/SAN fields from the final cryptography.x509.Certificate.
The handler captures fresh JSON before registering a transaction on_commit
callback. Post-issuance dispatch uses issued:<certificate SHA-256 fingerprint>
as a separate idempotency key. Both the run and its instances persist the event
snapshot. Capture/dispatch failures are logged without changing the pre-issuance
authorization outcome or reversing issuance. This dispatch is best effort: there
is no transactional outbox protecting the interval between commit and dispatch.
Editor and HTTP interfaces¶
The Django page is trustpoint/templates/workflows2/definition_editor.html.
frontend/src/workflow_editor/index.js boots the workspace. The frontend parses
raw YAML into a tolerant draft graph; graph and guide actions mutate the YAML
through shared document operations. Backend compilation remains authoritative.
Frontend directory under |
Responsibility |
|---|---|
|
Workspace, DOM wiring, and CodeMirror controller. |
|
YAML mutations, flow/condition helpers, variable availability. |
|
Draft parsing, automatic layout, SVG rendering, canvas interactions, and overlays. |
|
Semantic context, catalog-driven guide rendering, and insertion actions. |
|
Structured condition/step controls and scoped runtime picker. |
|
Drawer, graph expansion, issues panel, DOM, and HTTP utilities. |
urls.py and views/ expose the following APIs under /workflows2/:
Path |
Purpose |
|---|---|
|
Trigger catalog. |
|
Event, step, expression, and DSL metadata. |
|
Compile supplied YAML to a graph without saving. |
|
Graph derived from stored IR. |
services/graph.py adapts IR for backend graph consumers; it does not replace the
client-side draft graph. Definition views in views/definitions.py save through
the definition service. Runtime controls are in views/runs.py,
views/instances.py, and views/approvals.py.
Extending the engine¶
Keep YAML as the only authoring source, preserve tolerant draft rendering, and
keep frontend document/variable_availability.js consistent with backend
WorkflowCompiler._compute_available_vars_before_step. A later compute
assignment can use an earlier assignment in the same step; set cannot.
Extension |
Code to update |
|---|---|
Step type |
|
Expression function |
|
Condition operator |
|
Trigger |
|
Update documentation and test both compiler rejection and runtime behavior for an extension. Catalog registration alone does not cause application events to fire.
Verification commands¶
From the repository root:
python -m pytest trustpoint/workflows2/tests trustpoint/request/tests/test_workflows2_handler.py trustpoint/request/tests/test_workflow2_issuance.py
The tests cover compilation, expression evaluation, dispatch, persistence,
approvals, worker/crash recovery, protocol enrollment, and the demo definitions.
tests/test_enrollment_events.py also compiles the complete final-certificate
webhook example in this page. Its local HTTP integration test needs permission to
bind a loopback socket.
Rebuild the browser bundle after frontend changes:
cd trustpoint/workflows2/frontend
npm ci
npm run build
frontend/build.mjs writes trustpoint/static/js/workflows2/editor_bundle.js.
Build the published documentation from the repository root with:
python -m sphinx -b html docs/source /tmp/trustpoint-docs-html