# 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](https://docs.keeper.io/en/keeperpam/endpoint-privilege-manager/reference/plugin-and-job-registration) for how jobs are discovered and registered.