# 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 ```json { "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: ```json "schedule": { "intervalMinutes": 30 } ``` * **Cron** — Standard five-field cron expression (minute, hour, day-of-month, month, day-of-week): ```json "schedule": { "cronExpression": "0 16 * * 2" } ``` * **One-time** — Runs once at a specific UTC datetime: ```json "schedule": { "runAt": "2025-01-15T10:00:00Z" } ``` * **Calendar** — Runs at specific times on specific days: ```json "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. ```json "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](/keeperpam/endpoint-privilege-manager/reference/plugin-and-job-registration.md) for how jobs are discovered and registered. For deploying custom job task binaries end to end, see the [Custom Job Integration Guide](/keeperpam/endpoint-privilege-manager/integrations/custom-job-guide.md). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/keeperpam/endpoint-privilege-manager/reference/jobs-definition-and-format.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.