# Notebook scheduler

{{% notice style="note" title="Limited access" icon="lock" %}}
{{% include file="include/restricted_access.md" hidefirstheading="true"  %}}
{{% /notice %}}

## What it is for

The notebooks you write in the OpenGate Data Lab are interactive by nature: you open Jupyter Lab, run cells,
look at results. The **notebook scheduler** takes a notebook out of that interactive loop and runs it
unattended — once, or on a repeating schedule — with parameters supplied from outside and an optional report
kept for a number of days.

That turns a notebook into a scheduled job: a nightly aggregation, a weekly report, a periodic model
retraining. See the [Analytics and Datalab how-to](/2-howtos/10-analytics-and-datalab/) for writing the
notebooks themselves.

Each scheduled execution becomes a cron job in the platform's Kubernetes cluster, which is why the API talks
about cron jobs and cron patterns.

## Endpoints

Authentication uses the `Authorization` header, not `X-ApiKey`.

| To | Call |
|---|---|
| List the notebooks available to you | `GET /planner/notebooks` |
| Run one notebook now | `POST /planner/notebooks/{notebookId}/execute` |
| Schedule a notebook | `POST /planner/schedulers` |
| List your scheduled executions | `GET /planner/schedulers` |
| Delete a scheduled execution | `DELETE /planner/schedulers/{cronjobId}` |
| Check the service is up | `GET /planner/health-check` |
| Read the service version | `GET /planner/nsversion` |

## Running a notebook once

The body carries the parameters the notebook needs and what to do with its report:

```json
{
  "generateReport": true,
  "reportRetentionDays": 2,
  "params": [
    { "name": "DB_URL", "value": "..." }
  ]
}
```

| Field | Meaning |
|---|---|
| `generateReport` | Whether to produce a report of the execution |
| `reportRetentionDays` | How many days to keep that report |
| `params` | Name and value pairs passed to the notebook as environment parameters |

## Scheduling a notebook

Same body plus the notebook and a **standard cron pattern**:

```json
{
  "notebookId": "12345678",
  "cronPattern": "*/5 * * * *",
  "generateReport": true,
  "reportRetentionDays": 2,
  "params": [
    { "name": "DB_URL", "value": "..." }
  ]
}
```

`*/5 * * * *` runs every five minutes. The five fields are, in order, minute, hour, day of month, month and
day of week.

## Reading your scheduled executions

`GET /planner/schedulers` returns the cron jobs belonging to the current user. Each one reports:

| Field | Holds |
|---|---|
| `id` | The cron job identifier, which is what `DELETE` takes |
| `notebook` | The notebook being run |
| `schedule` | The cron pattern |
| `lastExecutionTime` | When it last ran |
| `params` | The parameters it passes |
| `generateReport`, `reportRetentionDays` | The report settings |
| `user` | The owner |

A `204 No Content` means you have no scheduled executions, not an error.

## API specification

{{< openapi src="opengate-data-notebook-scheduler.yaml" >}}