Modular certificate workflows¶

For a practical walkthrough of labels, references, conditions, Tomcat/P12 delivery, and backups, see Agent workflow usage.

This reference describes the modular workflows in Agent 1.3.70 and later. A modular workflow controls what happens after the Agent has issued or renewed a certificate: export it, update an application, and check the result. The certificate's ACME account, names, key type, delegation, renewal schedule, and revocation state remain part of its certificate policy.

On Windows, use Workflows → + New certificate workflow to choose a template, start from scratch, or import a JSON definition. Configure it in Workflow studio, then continue to certificate setup. For an existing certificate, choose Edit workflow… → Edit workflow settings and steps…. The studio has Setup, Steps, Review, and Advanced tabs; see the illustrated walkthrough.

A certificate uses either its selected modular workflow or its compatible storage/installation plans. Choose modular template… switches a certificate from plans to a workflow while retaining the old plan definitions and installed files. Bundled templates cannot be edited in place. Local workflow JSON can be exported/imported as independent copies. Templates are compiled into the Agent and come with its signed release: there are no template packages to download, and an Agent 1.5.0 template that talks to an appliance (see Appliance deployment) is still a bundled template that runs on the Agent machine. On Linux, the terminal interface (sudo certintel tui, Agent 1.3.77+) creates and edits workflows with guided types: save files (PEM, CRT + KEY, PFX, P12, DER, P7B or JKS), NGINX, Apache httpd and Tomcat, and (Agent 1.5.0+) the Linux service targets HAProxy, Caddy, Traefik, LiteSpeed, Postfix, Dovecot, PostgreSQL and MySQL, each optionally followed by a post-renewal script run through hook.run. Agent 1.5.0 and later also create a workflow from any bundled template that runs on the machine with T on the Workflows screen (New workflow from a template), and w/e on a template-based workflow edit only its fields, never its steps (This workflow comes from the bundled template … Only its fields are edited here; its steps stay as they are.). Windows-only templates are never offered there. For scripted setups use the CLI's versioned configuration transaction: config get --json, validate --file, then config apply --file, preserving the current revision when applying a proposal; Agent 1.3.93 and later also offer certintel workflows create, which clones a bundled template and adds the certificate in one command (see the command-line example).

Bundled template setup fields¶

Fields marked * are required in the template setup form. output_password is stored as an Agent protected secret, outside the workflow JSON. Template file paths refer to the local Agent machine. The Windows editor offers to detect keytool and to select an installed IIS site, and (Agent 1.5.0+) to pre-fill a template from the servers it finds on the machine (see Server detection).

service is the exact Windows service name or systemd unit. host and port identify the endpoint to verify after installation. The IIS template creates a binding on the selected site and verifies that it serves the new thumbprint. The Windows store and IIS templates end with Remove previous certificate from Windows store, which runs only when Remove previous certificate after confirmation is on. It rechecks the replacement and removes the renewal's recorded predecessor when the IIS template's post-binding endpoint comparison matched, or (machine-store template) when No other application uses the previous certificate is also on, and no IIS HTTPS binding, HTTP.sys SSL binding or Remote Desktop listener still references it. Otherwise the predecessor is retained and the step reports why. See Windows store verification. The service templates' first "inspect the current endpoint" step runs only when a previous certificate exists (${certificate.previousThumbprint}), so first issuance on an endpoint that is not yet serving TLS does not fail. The JKS templates import an Agent owned key into the keystore. Use the JKS CSR plan when the private key must be created inside that keystore.

Templates added in Agent 1.5.0¶

Agent 1.5.0 adds three groups of bundled templates (each version 1.0.0, minimum Agent 1.5.0). Their fields are listed on their own pages:

The Windows desktop app groups templates by category: Appliances (remote) and Microsoft services join Certificate stores and files, Java and Tomcat keystores and Web servers and services (older templates have no category). The Linux service templates are meant for dashboard assignments; on the machine itself the terminal interface's guided types do the same job.

Template field types¶

Each template field has a type. Agent 1.5.0 adds choice and credential:

A field marked local only (Agent 1.5.0+, shown with (this computer only), for example Accept any management certificate (not recommended)) can be set only on the Agent machine: it is not reported to CertIntel and is refused in an assignment (field … is set only by a local administrator on this agent and cannot be assigned). Field rules (Agent 1.4.1+: file-name, keystore-name, keystore-alias, absolute-path) gain host-name (a DNS name or IP address without scheme, port or path) and sha256-hex (64 hexadecimal digits without colons) in Agent 1.5.0.

Workflow document fields¶

The editor manages the following versioned workflows[] document. Use these same JSON names when applying a configuration with the CLI.

Each steps[] item accepts id, optional name, action, positive action_version (currently 1 for every built-in action), optional with input object (up to 128 keys), optional when condition, optional failure policy, and optional timeout_seconds. The default timeout is 300 seconds per attempt; the range is 1–3,600 when set. failure accepts mode (fail, continue, or rollback), retries (0–10), retry_delay_seconds (0–600), and backoff (boolean). Continuing leaves a partially successful run. Rollback applies only to actions that advertise rollback support; a certificate export, IIS binding, store installation, JKS write, or service restart is not automatically undone. See the rollback limits before relying on file rollback to restore an overwritten destination.

when is an object with operator, left, and, where needed, right. Supported operators are equals, notEquals, exists, notExists, true, false, greaterThan, lessThan, contains, matches (regular expression), and certificateChanged. The editor offers true/false selection for earlier boolean results, a Compare a value form, and advanced JSON for the full set. For example:

{"operator":"false","left":"${steps.check_directory.exists}"}

References may use ${workflow.id}, ${workflow.name}, ${workflow.version}, ${variables.name}, ${secrets.name}, ${steps.STEP_ID.OUTPUT}, ${certificate.thumbprint}, ${renewal.id}, and ${system.os}, ${system.arch}, ${system.date}, ${system.dateCompact}, ${system.timestamp}, or ${system.timestampUtc}. The system dates are UTC; dateCompact is YYYYMMDD and timestamp is YYYYMMDD-HHMMSS. Certificate values also include previousThumbprint (empty on first issuance), subject, issuer, serial, notBefore, notAfter, domains, and generation. A step may refer only to outputs of earlier steps.

Reference rules the validator enforces¶

• An input name that the action does not declare is rejected (step "x" action "y" has unknown input "z").
• A secret reference must be the entire input value and may appear only in inputs marked sensitive: password inputs and the environment map of process.execute. Secrets are never allowed in when conditions or in process.execute.arguments.
• Runtime-derived references (${steps.*}, ${certificate.*}, ${renewal.*}, ${system.*}) may not be used to build a target: any input of an action that changes state (export, write, install, copy, delete, restart, run a program) or a path, URL, host, port, service, store, site or name input of a read-only action. Variables and literals are fine there. The exceptions are certificate.compare (public certificate facts), windows_cert_store.cleanup.confirmed and activation_confirmed fed by a certificate.compare result, and file.backup.filename, which may use exactly ${system.dateCompact} or ${system.timestamp}.

Step action inputs¶

The following are all built-in version 1 action inputs. * means the input is required. Optional values are omitted unless needed. Use an absolute path for every path, directory, source, destination, executable, working_directory, and keytool input. These actions execute locally under the Agent service identity; remote.deploy also runs on the Agent machine, but its target is an appliance's management API.

file.backup adds a UTC timestamp to its backup filename unless filename is specified. A custom filename is one filename, not a path; an existing backup is never overwritten. File actions operate on regular files, do not follow symlinks, and copy at most 64 MiB. process.execute launches the executable directly with an argument array; secrets are allowed in environment values, but not in arguments (the remote.deploy script driver instead passes its credential only on standard input, with a minimal environment). Its captured output (the last 16 KiB of each stream in Agent 1.4.0 and later; the first 64 KiB in earlier releases) is used for the step's success check and later steps of the same run, but is saved in job results as [redacted], because arbitrary programs may print secrets. When the step fails, Agent 1.4.0 and later send the end of each stream to CertIntel with the failure report, after replacing every secret the Agent knows of; that redaction is best effort, and report_step_output: false turns it off (see Reporting failed step output). http.check does not follow redirects, reads at most 64 KiB, and requires the expected status and, when supplied, body text to match. On Windows, service.reload stops and starts the named service; on Linux it uses systemctl reload.

Saved job results are bounded. A very large result is replaced by a summary with step outputs dropped and "diagnostics_truncated": true; the workflow is still recorded as completed and is not re-run.

For the current machine's exact field types, supported values, and action versions, inspect the local registry and template catalog:

certintel --json workflows capabilities
certintel --json workflows templates
certintel workflows preflight WORKFLOW-ID
certintel secret set workflow WORKFLOW-ID:SECRET-NAME

Preflight validates a saved workflow and checks what its actions can check without running its installation steps. Set a secret from an elevated local session; the CLI prompts without echoing it, and --stdin is available for protected automation. Execution history appears under Edit workflow… → Application steps, Jobs, and local Activity. Platform outages do not prevent local workflow execution; reports are queued for later delivery.