sap-btp-job-scheduling

What this skill does

# SAP BTP Job Scheduling Service

## Related Skills

- **dependency-upgrade**: Use for secure dependency and workflow hardening when your job scheduling microservices maintain npm/CLI dependency stacks

## Table of Contents

- [Overview](#overview)
- [When to Use This Skill](#when-to-use-this-skill)
- [Quick Decision Tree](#quick-decision-tree)
- [Core Concepts](#core-concepts)
- [Service Constraints](#service-constraints)
- [Quick Reference Tables](#quick-reference-tables)
  - [Schedule Formats](#schedule-formats)
  - [Cron Format (7 fields)](#cron-format-7-fields)
  - [Schedule Lifecycle States](#schedule-lifecycle-states)
  - [HTTP Methods for Jobs](#http-methods-for-jobs)
- [Best Practices](#best-practices)
  - [Scheduling Optimization](#scheduling-optimization)
  - [Asynchronous Jobs](#asynchronous-jobs)
  - [One-Time Schedules](#one-time-schedules)
- [Authentication Quick Start](#authentication-quick-start)
  - [Standard Plan (OAuth 2.0)](#standard-plan-oauth-20)
  - [xs-security.json Configuration](#xs-securityjson-configuration)
- [Create Job Example](#create-job-example)
- [Node.js Client Library](#nodejs-client-library)
- [Rate Limits](#rate-limits)
- [Service Behavior](#service-behavior)
  - [Outage Recovery](#outage-recovery)
  - [Auto-Deactivation Triggers](#auto-deactivation-triggers)
- [Bundled Resources](#bundled-resources)
- [Common Pitfalls](#common-pitfalls)
- [External Resources](#external-resources)
- [Updates and Maintenance](#updates-and-maintenance)

## Overview

SAP Job Scheduling Service is a runtime-agnostic platform service for defining and managing one-time and recurring jobs or Cloud Foundry tasks on SAP BTP. It operates across multiple hyperscalers (AWS, Azure, GCP) without requiring application modifications.

**Documentation Source**: [https://help.sap.com/docs/job-scheduling](https://help.sap.com/docs/job-scheduling)

**Last Verified**: 2025-11-27

## When to Use This Skill

Use this skill when:

- **Setting up Job Scheduling Service** on Cloud Foundry or Kyma runtime
- **Creating and managing jobs** via REST API or dashboard
- **Configuring schedules** using cron, date/time, or human-readable formats
- **Implementing asynchronous job execution** for long-running processes
- **Securing action endpoints** with OAuth 2.0 and XSUAA
- **Integrating with SAP Cloud ALM** or Alert Notification Service
- **Developing multitenant applications** with tenant-aware job scheduling
- **Troubleshooting job execution issues** and schedule failures
- **Using the Node.js client library** (@sap/jobs-client)

## Quick Decision Tree

### What Task?

```
Setup & Configuration
├─ Initial setup prerequisites → references/setup-guide.md
├─ Create service instance
│  ├─ BTP Cockpit → references/setup-guide.md#cockpit
│  ├─ CF CLI → references/setup-guide.md#cf-cli
│  └─ Kyma Dashboard → references/setup-guide.md#kyma
└─ Configure XSUAA scopes → references/security.md

Job Management
├─ Create jobs → references/rest-api.md#create-job
├─ Configure schedules → references/rest-api.md#schedules
├─ Run logs & monitoring → references/rest-api.md#run-logs
└─ Dashboard operations → references/operations.md#dashboard

Schedule Configuration
├─ One-time vs recurring → references/concepts.md#schedule-types
├─ Cron format → references/concepts.md#cron-format
├─ Date/time formats → references/concepts.md#date-formats
└─ Human-readable → references/concepts.md#human-readable

Asynchronous Execution
├─ Async mode flow → references/concepts.md#async-mode
├─ Callback implementation → references/rest-api.md#update-run-log
└─ CF tasks → references/concepts.md#cf-tasks

Security & Authentication
├─ OAuth 2.0 setup → references/security.md#oauth
├─ XSUAA configuration → references/security.md#xsuaa
└─ Credential rotation → references/security.md#rotation

Integrations
├─ SAP Cloud ALM → references/integrations.md#cloud-alm
└─ Alert Notification → references/integrations.md#alert-notification

Troubleshooting
├─ Common errors → references/troubleshooting.md#errors
├─ FAQ → references/troubleshooting.md#faq
└─ Support: BC-CP-CF-JBS

Version History & Updates
└─ What's New (2021-2025) → references/changelog.md
```

## Core Concepts

### Job
A collection of schedules with an action endpoint. Jobs invoke a configured URL at specified times synchronously (short operations) or asynchronously (long processes).

### Schedule
A one-time or recurring entity within a job. Supports multiple formats (cron, date/time, human-readable) and has three lifecycle states: SCHEDULED → RUNNING → COMPLETED.

### Action Endpoint
An HTTP/REST endpoint exposed by your application that the service invokes when schedules trigger. Must be OAuth 2.0 protected in production.

### Cloud Foundry Task
An app or script that runs independently in its own container. Always executes asynchronously with configurable memory allocation.

## Service Constraints

| Constraint | Value |
|------------|-------|
| Minimum schedule interval | 5 minutes |
| Synchronous request timeout | 15 seconds |
| Asynchronous timeout (default) | 30 minutes (configurable up to 7 days) |
| POST request body limit | 100 KB |
| Run log retention | 15 days |
| Service SLA | ~20 minutes from scheduled time |

## Quick Reference Tables

### Schedule Formats

| Format | Example | Use Case |
|--------|---------|----------|
| Cron | `* * * * 10:12 0,30 0` | Every 30 min between 10:00-12:00 |
| Date/Time | `2025-10-20T04:30:00Z` | ISO-8601 one-time execution |
| Human-readable | `tomorrow at 4pm` | Natural language scheduling |
| repeatInterval | `2 hours`, `5 minutes` | Recurring at fixed intervals |
| repeatAt | `4.40pm`, `18:40` | Daily at specific time |

### Cron Format (7 fields)

```
Year Month Day DayOfWeek Hour Minute Second
*    *     *   *         *    *      *
```

| Field | Values | Special |
|-------|--------|---------|
| Year | 4-digit (2025) | * = any |
| Month | 1-12 | */a = every a-th |
| Day | -31 to 31 | negative = from end |
| DayOfWeek | mon, tue, wed... | a.y = a-th occurrence |
| Hour | 0-23 | a:b = range |
| Minute | 0-59 | a:b/c = step in range |
| Second | 0-59 | a,b,c = multiple values |

### Schedule Lifecycle States

| Phase | States | Description |
|-------|--------|-------------|
| SCHEDULED | SCHEDULED | Queued for future run |
| RUNNING | TRIGGERED, ACK_RECVD, ACK_NOT_RECVD | Executing |
| COMPLETED | SUCCESS, ERROR, REQUEST_ERROR, UNKNOWN | Finished |

### HTTP Methods for Jobs

| Method | Endpoint | Purpose |
|--------|----------|---------|
| POST | `/scheduler/jobs` | Create job |
| GET | `/scheduler/jobs` | List all jobs |
| GET | `/scheduler/jobs/{id}` | Get job details |
| PUT | `/scheduler/jobs/{id}` | Update job |
| DELETE | `/scheduler/jobs/{id}` | Delete job |

## Best Practices

### Scheduling Optimization

**Avoid Peak Times:**
- ❌ 0th or 30th second of any minute
- ❌ 0th, 30th, or multiples of 5 minutes
- ❌ Top of each hour
- ❌ Midnight UTC (busiest time)

**Use Irregular Times:**
- ✅ `01:12:17` instead of `01:00:00`
- ✅ `01:38:37` instead of `01:30:00`

### Asynchronous Jobs

1. **Return 202 Accepted immediately** - Don't block the request
2. **Store request headers** - `x-sap-job-id`, `x-sap-job-schedule-id`, `x-sap-job-run-id`, `x-sap-scheduler-host`
3. **Update run log on completion** - Single API call with final status
4. **Handle timeouts** - Default 30 min, configurable up to 7 days

### One-Time Schedules

- Use only for testing/validation
- Auto-deactivate after execution
- Use `"time": "now"` for immediate execution

## Authentication Quick Start

### Standard Plan (OAuth 2.0)

```bash
# Get access token
curl -X POST "<uaa_url>/oauth/token" \
  -H "Authorization: Basic $(echo -n '<clientid>:<clientsecret>' | base64)" \
  -d "grant_type=client_credentials"

# Use token in API calls
curl -X GET "[https://jobscheduler-rest.<landscape>/scheduler/jobs"](https://jobscheduler-rest.<landscape>/scheduler/jobs") \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: applicat