Modular certificate workflows

Modular workflows are available in Agent 1.3 beta. 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, select a certificate on Workflows, then choose Build modular workflow. Choose a bundled template or Create blank workflow. The Agent copies a template into My modular workflows, where you can edit its steps, variables, conditions, failure behavior, and protected secrets. A certificate uses either its selected modular workflow or its storage/installation plans. Replacing the plans retains their definitions and already installed files. The bundled templates cannot be edited in place; remote templates are not supported. On Linux, use the local CLI's versioned configuration transaction: config get --json, validate --file, then config apply --file. Preserve the current revision when applying a proposal.

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.

Template	Platform	Setup fields
Windows machine certificate store	Windows	store_name* (default My), exportable (default false)
Protected PEM files	Windows, Linux	directory, name (default certificate), output_password*
PKCS#12 / PFX	Windows, Linux	directory, name (default certificate), output_password*
Java KeyStore	Windows, Linux	directory, name (default server), keytool, alias (default server), output_password*
IIS HTTPS binding	Windows	store_name (default WebHosting), site_id, host, port (default 443), sni (default false)
Windows service + PFX	Windows	directory, name (default certificate), service, host, port (default 443), output_password
NGINX + PEM	Linux	directory, name (default certificate), service, host, port (default 443), output_password
Apache + PEM	Windows, Linux	directory, name (default certificate), service, host, port (default 443), output_password
Tomcat + JKS	Windows, Linux	directory, name (default certificate), service, host, port (default 443), output_password, keytool, alias (default server)

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 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.

Workflow document fields

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

Field	Meaning
schema_version	Required; currently 1.
id	Required stable local ID: lowercase letter/digit first, then lowercase letters, digits, _ or -, at most 64 characters.
name, description	Required display name (up to 200 characters); optional description (up to 2,000).
version	Required positive document version; the editor increments it on save.
platforms	Optional array of windows and/or linux; the current Agent OS must be included when set.
variables	Optional object of values referenced as ${variables.name}; at most 128 entries.
secret_refs	Optional list of protected secret names; at most 64. A secret is set separately and referenced as ${secrets.name}.
template	Optional provenance object with id and version for a cloned template.
vendor_managed	Catalog marker; saved user workflows set this to false.
steps	Required ordered array of 1–128 steps. Each step's id must be unique.

Each steps[] item accepts id, optional name, action, positive action_version (currently 1 for every built-in action), optional with input object, optional when condition, optional failure policy, and optional timeout_seconds. The default timeout is 300 seconds; 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; an IIS binding, store installation, or JKS write is not automatically undone.

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 a simple true/false selector for earlier boolean step results, plus 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 subject, issuer, serial, notBefore, notAfter, domains, and generation. A step may refer only to outputs of earlier steps. A secret reference must be the entire input value; it cannot be embedded in a larger string.

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.

Action	Platform	with inputs
acme.obtain_certificate	Both	None; exposes the already issued certificate artifact and public facts to later steps.
certificate.export	Both	format (pem, crtkey, pfx, p7b, der, centralssl), directory, name*, password, backup_directory. password is needed for private-key formats.
keystore.jks.write	Both	directory, name, password, keytool, alias*. Use an absolute keytool path and the intended alias.
windows_cert_store.install	Windows	store_name*, exportable (default false). Use a Local Computer personal store such as My or WebHosting.
iis.bind_certificate	Windows	store_name, site_id, host*, port (default 443), ip (default *), sni (default false), create_binding (default false).
certificate.inspect_endpoint	Both	host*, port (default 443).
certificate.inspect_file	Both	path*, password, keytool, alias. Supply the protected password for PFX/JKS and keytool/alias for JKS.
certificate.compare	Both	expected_thumbprint, actual_thumbprint, old_not_after, new_not_after, expected_sans, actual_sans. Use a pair for the comparison(s) you want; SAN values are string arrays and expiration values are RFC 3339 times.
service.status, service.start, service.stop, service.restart, service.reload	Both	service* (exact Windows service or systemd unit name).
process.execute	Both	executable*, arguments (string array), working_directory, environment (object), success_exit_codes (integer array; default [0]).
file.exists	Both	path*.
file.copy, file.move	Both	source, destination, overwrite (default false).
file.delete	Both	path*, missing_ok (default false).
file.backup	Both	source, directory, filename, mode (copy by default, or move).
directory.exists, directory.create	Both	path*.
tcp.check	Both	host, port.
http.check	Both	url* (http or https), expected_status (default 200), body_contains.
workflow.wait	Both	seconds* (0–600, still bounded by the step timeout).

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 and do not follow symlinks. process.execute launches the executable directly with an argument array; secrets are allowed in environment values, but not in arguments. Its captured output is bounded and secret values are redacted in saved results. http.check does not follow redirects 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.

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

certintel-agent --json workflows capabilities
certintel-agent --json workflows templates
certintel-agent workflows preflight WORKFLOW-ID
certintel-agent 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 in My modular workflows, Jobs, and local Activity. Platform outages do not prevent local workflow execution; reports are queued for later delivery.