Job: Definition & Format

Audience: IT admins who create, edit, or troubleshoot jobs on the agent.

A job is a defined set of tasks that run when a trigger fires. Jobs power policy controls, 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 — for example, C:\Program Files\KeeperPrivilegeManager\Jobs or {approot}/Jobs

• File name: {job-id}.json — the id field inside the JSON must match the filename without the .json extension

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

Job JSON Structure

{
  "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": { ... }
}

Property

Type

Description

id	string	Unique job identifier. Must match the filename.
name	string	Display name shown in logs and admin views.
description	string	Optional description.
enabled	boolean	When false, the job does not run regardless of triggers.
priority	number	1–10. Higher values take priority when multiple jobs are eligible simultaneously.
schedule	object	Timer-based trigger — interval, cron, one-time, or calendar. Omit if the job is event-driven only.
events	array	Event names that trigger this job — for example, PolicyEvaluationPending or Startup.
parameters	array	Input parameters with name, type, default value, and required flag. Used for substitution in task arguments.
tasks	array	Ordered list of tasks to execute.
condition	object	Optional condition. When not met, the job skips or runs alternateJobId.
alternateJobId	string	Optional. Job to run when condition fails.
osFilter	object	Optional. Restricts the job to specific platforms — windows, linux, and/or macOS.

Triggers

A job runs when any of its declared triggers fires. A job may combine schedule and event triggers — either can independently cause execution.

Events

The events array lists event names. When the agent publishes a matching event — from MQTT, an internal policy action, or a custom event — the job is queued. Common event types include Startup, PolicyEvaluationPending, and custom MQTT event names.

Schedule

Only one schedule mode may be active per job.

• Interval — Runs every N minutes from when the scheduler starts:

  "schedule": { "intervalMinutes": 30 }

• Cron — Standard five-field cron expression (minute, hour, day-of-month, month, day-of-week):

  "schedule": { "cronExpression": "0 16 * * 2" }

• One-time — Runs once at a specific UTC datetime:

  "schedule": { "runAt": "2025-01-15T10:00:00Z" }

• Calendar — Runs at specific times on specific days:

  "schedule": { "calendar": [ { "daysOfWeek": [1], "time": "09:00" } ] }

Tasks

The tasks array defines what the job does. Tasks run in order — if a task fails and continueOnFailure is not set, the job stops. Output from one task can be passed into subsequent tasks via parameters or output references.

Each task typically includes:

• id — Unique within the job.

• command or executablePath — What to run.

• arguments — Command-line arguments. Supports variable substitution using job parameters and built-in tokens such as {KeeperApiBaseUrl}.

• ExecutionType — The execution context for the task.

• timeoutSeconds — Optional maximum run time before the agent kills the task.

• continueOnFailure — When true, the job continues even if this task exits with a non-zero code.

Execution Types

ExecutionType

How It Runs

Service	Runs in the agent service context — no user desktop. Default for background and security tasks.
User	Runs in the current user's session.
UserElevated	Runs with elevation in the user session.
UserDesktop	Runs in the interactive user desktop session.
Http	Makes an HTTP or HTTPS request to an endpoint rather than launching a process.

Tasks can also execute scripts — PowerShell, Bash, Python, and Batch are supported where scriptType is set. Check your agent version's schema for the exact available values.

Conditions and Platform Filtering

condition — A job-level condition that is evaluated before the tasks run. When the condition is not met, the job either skips or runs the job identified by alternateJobId.

osFilter — Restricts the job to matching operating systems. When a job's osFilter excludes the current platform, the job does not run on that agent and binary existence checks are skipped during validation.

"osFilter": {
  "windows": true,
  "linux": false,
  "macOS": false
}

Validation and Loading

• Validation — Use POST /api/Jobs/validate with the job JSON as the request body to check the structure before saving. The validator confirms that referenced executables exist on the validating host for any platform that matches osFilter.

• Loading — The agent loads jobs from the Jobs/ directory at startup and rescans when files change. Invalid JSON causes the job to be skipped and an error logged.

• Registration and deployment — See Plugin & Job Registration for how jobs are discovered and registered. For deploying custom job task binaries end to end, see the Custom Job Integration Guide.