# Jobs

Streams JobRunr job records across all six lifecycle states (`ENQUEUED`, `SCHEDULED`, `PROCESSING`, `SUCCEEDED`, `FAILED`, `DELETED`). Works with both **JobRunr Community** (open source) and **JobRunr Pro**, running locally or self-hosted. Useful for operational visibility and security monitoring of background work scheduled through JobRunr.

**Sync Type: Incremental**

## Requirements

Before connecting Monad to JobRunr, you need:

1. **A JobRunr dashboard that Monad can reach**
   - Any JobRunr edition that exposes the `/api/jobs` endpoint (Community or Pro)
   - Must be reachable from the Monad host running the pipeline:
     - **Monad SaaS**: the dashboard needs to be exposed on the public internet (or via an allowlisted tunnel). 
     - **Monad On-Prem**: the dashboard needs to be reachable from wherever your Monad deployment runs (same VPC, VPN, corporate network, or a routable IP)
   - **HTTPS is required.** Plain `http://` URLs are rejected — even for local instances.

2. **HTTP Basic Auth credentials**
   - Username and password with permission to read the dashboard API — both are required
   - JobRunr Community ships with the dashboard unauthenticated by default; you must enable Basic Auth on the dashboard before connecting Monad
   - Instructions: [JobRunr dashboard authentication](https://www.jobrunr.io/en/guides/authentication/basic-authentication/)

### Enabling Basic Auth on the JobRunr dashboard

1. In your JobRunr configuration, enable dashboard authentication (`org.jobrunr.dashboard.username` / `org.jobrunr.dashboard.password`, or the equivalent Spring Boot / Micronaut / Quarkus properties)
2. Restart the JobRunr process so the new credentials take effect
3. Verify you can reach `<base_url>/api/jobs?state=ENQUEUED&limit=1` from a browser or `curl` with those credentials

**Important**: Dashboard credentials grant read access to job history - including payloads and exception details. Store them securely and never commit them to version control.

## Configuration

The following configuration defines the input parameters. Each field's specifications, such as type, requirements, and descriptions, are detailed below.

#### Settings

| Setting | Type | Required | Default | Description |
|---------|------|----------|---------|-------------|
| Base URL | string | Yes | - | Base URL of your JobRunr dashboard (e.g. `https://jobrunr.example.com`). |
| Backfill Start Time | string | No | Current time | The date to start fetching data from (RFC3339). If not specified, no past records will be fetched. |

#### Secrets

| Secret | Type | Required | Description |
|--------|------|----------|-------------|
| Username | Secret | Yes | HTTP Basic Auth username for the JobRunr dashboard. |
| Password | Secret | Yes | HTTP Basic Auth password for the JobRunr dashboard. |

## Troubleshooting

### Authentication Failures (401 Unauthorized)

If the connector fails with a 401 from `/api/jobs`:

1. Load `<base_url>/api/jobs?state=ENQUEUED&limit=1` in a browser with the same credentials to confirm they work
2. Confirm the JobRunr dashboard has Basic Auth enabled (Community ships unauthenticated by default)
3. Update the Monad secret if the credentials were rotated on the JobRunr side

### Connection Refused / DNS Failures

If the connector fails with `no such host`, `connection refused`, or `i/o timeout`:

1. Verify `base_url` matches exactly what a browser uses to reach the dashboard (scheme + host, no trailing slash)
2. Ensure the dashboard is reachable from Monad's egress IPs (public internet for SaaS; your VPC/VPN for On-Prem)
3. Add the required allowlist entries on any intermediate firewalls or security groups

### Rate Limits / Timeouts

If you see 429 responses or slow syncs against a busy dashboard:

1. The connector self-limits to 5 requests per second and retries transient errors with backoff - no action needed for occasional 429s
2. Consider running the dashboard on its own process/host so it doesn't compete with the app scheduling the jobs
3. Move `backfill_start_time` forward to reduce initial history

### No Data Appearing

If the connector runs successfully but no records are collected:

1. Set `backfill_start_time` to an explicit RFC3339 timestamp - with the field blank, only jobs updated *after* the connector started are captured
2. Confirm the dashboard shows jobs in the same window
3. Check your JobRunr retention configuration if records seem to disappear over time

### Same Job Appears More Than Once

This is expected. JobRunr jobs are mutable and move through multiple states over their lifetime (e.g. `ENQUEUED → PROCESSING → SUCCEEDED`, or `ENQUEUED → PROCESSING → FAILED → SCHEDULED → PROCESSING → SUCCEEDED` after a retry). The connector emits a fresh record on every state transition so you capture the full lifecycle rather than just the final outcome. To see what changed between two records with the same `id`, compare their `jobHistory` arrays - the newer record will have additional entries appended, and the last entry describes the most recent transition. If two records with the same `id` have *identical* `jobHistory` arrays, that's a genuine duplicate - please reach out to Monad support with the pipeline ID and record IDs.

### Invalid Backfill Start Time

If you see a validation error about backfill time format:

1. Use RFC3339: `2025-01-01T00:00:00Z` (or with an offset like `+05:00`)
2. Leave the field blank to start from "now" and only capture new activity

## Related Articles

- [JobRunr Pro Documentation](https://www.jobrunr.io/en/documentation/pro/)
- [JobRunr Pro Dashboard Authentication](https://www.jobrunr.io/en/documentation/pro/dashboard/authentication/)
- [JobRunr Job Lifecycle](https://www.jobrunr.io/en/documentation/background-methods/states/)

## Sample Record

```json
{
  "id": "b09f4ce9-4c4c-4a3e-9c88-2e6c8f4e1a2b",
  "version": 3,
  "jobDetails": {
    "className": "com.example.OrderProcessor",
    "methodName": "processOrder",
    "jobParameters": [
      { "className": "java.lang.Long", "object": "48219" },
      { "className": "java.lang.String", "object": "HIGH" }
    ],
    "cacheable": true,
    "staticFieldName": null
  },
  "jobName": "Process Order 48219",
  "recurringJobId": null,
  "jobHistory": [
    {
      "state": "ENQUEUED",
      "createdAt": "2026-07-15T14:32:11.104Z",
      "scheduledAt": "2026-07-15T14:32:11.104Z",
      "recurringJobId": null,
      "reason": "triggered-by-api"
    },
    {
      "state": "PROCESSING",
      "createdAt": "2026-07-15T14:32:12.400Z",
      "serverId": "server-node-2",
      "serverName": "worker-02.example.com"
    },
    {
      "state": "SUCCEEDED",
      "createdAt": "2026-07-15T14:32:13.221Z"
    }
  ],
  "metadata": {
    "jobRunrDashboardLog": "2026-07-15T14:32:11.104Z Processing started",
    "retryCount": 0
  },
  "updatedAt": "2026-07-15T14:32:13.221Z"
}
```