Jobs: Definition & Format

Audience: IT admins who create, edit, or troubleshoot jobs (automation and policy-control tasks) on the agent.

---

What a Job Is

A job is a defined set of tasks that run when a trigger fires. Triggers can be:

• Events — e.g. MQTT (policy evaluation pending, startup, custom events).

• Schedule — interval (every N minutes), cron, one-time run-at, or calendar.

• API — a management endpoint to run the job on demand.

Jobs are used for policy controls (e.g. launch elevation, request approval), inventory, risk assessment, configuration processing, registration, notifications, and maintenance. Each job is a single JSON file.

---

Job File Location and Naming

• Directory: Jobs/ under the application root (e.g. C:\Program Files\KeeperPrivilegeManager\Jobs or {approot}/Jobs).

• Naming: {job-id}.json. The id inside the JSON must match the filename (without .json).

• Example: Jobs/my-job.json must contain "id": "my-job".

---

Job JSON Structure (overview)

{
  "id": "unique-job-id",
  "name": "Human-readable name",
  "description": "What the job does",
  "enabled": true,
  "priority": 5,
  "schedule": { ... },
  "events": [ ... ],
  "parameters": [ ... ],
  "tasks": [ ... ],
  "condition": { ... },
  "alternateJobId": null,
  "osFilter": { ... }
}

Main properties:

Property	Type	Description
id	string	Unique job ID; must match filename.
name	string	Display name.
description	string	Optional description.
enabled	boolean	If false, job does not run.
priority	number	1–10; higher = higher priority when multiple jobs are eligible.
schedule	object	When to run (interval, cron, runAt, or calendar). Omit if job is event-only.
events	array	Event names that trigger this job (e.g. PolicyEvaluationPending, Startup).
parameters	array	Input parameters (name, type, default, required).
tasks	array	Ordered list of tasks to run.
condition	object	Optional; if not met, job can skip or run an alternate job.
alternateJobId	string	Optional; job to run if condition fails.
osFilter	object	Optional; limit to Windows, Linux, and/or macOS.

---

Triggers

Events: events lists event names (e.g. from MQTT or internal events). When that event is published, the job is queued. Examples: policy evaluation pending, startup, custom event names.

Schedule:

• Interval: "schedule": { "intervalMinutes": 30 } — every 30 minutes.

• Cron: "schedule": { "cronExpression": "0 16 * * 2" } — 5-field cron (e.g. every Tuesday 4 PM).

• One-time: "schedule": { "runAt": "2025-01-15T10:00:00Z" } — run once at that UTC time.

• Calendar: "schedule": { "calendar": [ { "daysOfWeek": [1], "time": "09:00" } ] } — e.g. every Monday at 09:00 UTC.

Only one schedule type should be used per job.

---

Tasks

tasks is an array of task objects. Each task typically has:

• id — Unique within the job.

• command or executable — What to run (path or command name).

• arguments — Command-line arguments (can use parameter substitution).

• executionType — e.g. Service, User, Elevated, Desktop, or HTTP (for HTTP request tasks).

Tasks run in order. Output of one task can be used in later tasks (e.g. via parameters or outputs). If a task fails and the job is not configured to continue on failure, the job stops.

Execution types (typical):

• Service — Run in the service context (no user desktop).

• User — Run in user context.

• Elevated — Run with elevation (under policy).

• Desktop — Interactive/user desktop when needed.

• HTTP — HTTP/HTTPS request to an endpoint (e.g. local API or external).

Tasks can also be script (PowerShell, Bash) or built-in types depending on product support. Check your job examples or schema for the exact task shape.

---

What You Can Do in a Jjob

• Run executables — Call binaries or scripts with arguments.

• Call HTTP endpoints — GET/POST to local API (e.g. /api/...) or external URLs.

• Use parameters — Pass event or trigger data into tasks (e.g. user, path, policy result).

• Conditional flow — Use condition and alternateJobId to run different jobs based on context.

• Platform filter — Use osFilter so the job only runs on Windows, Linux, or macOS.

Jobs are used for: policy controls (elevation, approval, redirect, file access), inventory, risk assessment, configuration processing (e.g. ProcessConfigurationPolicies), registration/unregistration, notifications, and maintenance (logs, cleanup, version info).

---

Validation and Loading

• Validation: Some deployments offer an API to validate job JSON (e.g. POST to /api/Jobs/validate with the JSON body) before saving.

• Loading: The agent loads jobs from the Jobs/ directory at startup and when files change (depending on product behavior). New or updated JSON is picked up; invalid JSON may cause the job to be skipped and an error logged.

• Registration: See Plugin & job registration for how jobs are discovered and registered.

Return to Reference Index