Name: Sap Btp Job Scheduling
Author: secondsky

name	sap-btp-job-scheduling
description	This skill provides comprehensive guidance for SAP BTP Job Scheduling Service development, configuration, and operations. It should be used when creating, managing, or troubleshooting scheduled jobs on SAP Business Technology Platform. The skill covers service setup, REST API usage, schedule types and formats, OAuth 2.0 authentication, multitenancy, Cloud Foundry tasks, Kyma runtime integration, and monitoring with SAP Cloud ALM and Alert Notification Service. Keywords: SAP BTP, Job Scheduling, jobscheduler, cron, schedule, recurring jobs, one-time jobs, Cloud Foundry tasks, CF tasks, Kyma, OAuth 2.0, XSUAA, @sap/jobs-client, REST API, asynchronous jobs, action endpoint, run logs, SAP Cloud ALM, Alert Notification Service, multitenancy, tenant-aware, BC-CP-CF-JBS
license	GPL-3.0
metadata	{"version":"1.0.1","last_verified":"2025-11-27"}

SAP BTP Job Scheduling Service

Overview
When to Use This Skill
Quick Decision Tree
Core Concepts
Service Constraints
Quick Reference Tables
Best Practices
Authentication Quick Start
- Standard Plan (OAuth 2.0)
- [xs-security.json Configuration]((xs-securityjson-configuration)
Create Job Example
Node.js Client Library
Rate Limits
Service Behavior
- Outage Recovery
- Auto-Deactivation Triggers
Bundled Resources
Common Pitfalls
External Resources
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

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

Return 202 Accepted immediately - Don't block the request
Store request headers - x-sap-job-id, x-sap-job-schedule-id, x-sap-job-run-id, x-sap-scheduler-host
Update run log on completion - Single API call with final status
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)

# 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" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json"

xs-security.json Configuration

{
  "xsappname": "<app-name>",
  "scopes": [{
    "name": "$XSAPPNAME.JOBSCHEDULER",
    "description": "Job Scheduler Scope",
    "grant-as-authority-to-apps": ["$XSSERVICENAME(<jobscheduler-instance>)"]
  }]
}

Create Job Example

POST /scheduler/jobs
{
  "name": "myJob",
  "description": "Process daily reports",
  "action": "https://myapp.cfapps.eu10.hana.ondemand.com/api/process",
  "active": true,
  "httpMethod": "POST",
  "schedules": [{
    "active": true,
    "description": "Daily at 6 AM",
    "repeatAt": "6.00am",
    "startTime": {"date": "2025-01-01", "format": "YYYY-MM-DD"}
  }]
}

Node.js Client Library

Requirements: Node.js 14.x or later

npm install @sap/jobs-client@1.8.6

const JobSchedulerClient = require('@sap/jobs-client');
const scheduler = new JobSchedulerClient.Scheduler();

// Create job
scheduler.createJob({ url: vcapServices.jobscheduler[0].credentials.url }, {
  name: 'myJob',
  action: 'https://myapp.../process',
  active: true,
  httpMethod: 'GET',
  schedules: [{ cron: '* * * * 0 0 0', active: true }]
}, (err, result) => { /* handle */ });

Rate Limits

Limit Type	Response Code	Header
Client limit exceeded	429	`retry-after` (seconds)
Absolute limit exceeded	503	`throttling` (milliseconds)

Limits stack - both can apply simultaneously.

Service Behavior

Outage Recovery

Outage Duration	Behavior
< 20 minutes	All missed executions run immediately
>= 20 minutes	Only last missed execution runs

Auto-Deactivation Triggers

One-time schedule executed
No valid future dates exist
Job/schedule endTime reached
Action endpoint unreachable for 10+ days

Reference Files

Detailed Guides Available

references/concepts.md - Schedule types, formats, lifecycle, async mode, multitenancy
references/rest-api.md - Complete REST API reference with all endpoints
references/setup-guide.md - Prerequisites, service instance creation
references/security.md - OAuth 2.0, XSUAA scopes, credential rotation
references/integrations.md - Cloud ALM, Alert Notification Service
references/troubleshooting.md - FAQ, error scenarios, monitoring
references/operations.md - Dashboard, backup/restore, service behavior
references/changelog.md - Version history, feature updates (2021-2025)

Templates Available

templates/job-creation.json - Job creation request template
templates/xs-security.json - XSUAA configuration template

Common Pitfalls

Setup:

❌ Missing XSUAA binding before Job Scheduling binding
❌ Not granting scopes via grant-as-authority-to-apps
❌ Using HTTP instead of HTTPS for action endpoints

Scheduling:

❌ Using Linux cron format (service uses SAP cron)
❌ Scheduling at peak times (00:00, 00:30, etc.)
❌ Forgetting UTC timezone (only supported timezone)

Async Jobs:

❌ Not returning 202 Accepted immediately
❌ Forgetting to call Update Run Log API
❌ Multiple status updates instead of single final update

Multitenancy:

❌ Using tenantId filter with SaaS tenant tokens (returns 400)
❌ Missing Job Scheduling as application dependency

External Resources

SAP Documentation

SAP Help Portal: https://help.sap.com/docs/job-scheduling
SAP Developer Center: https://developers.sap.com/

Support

Component: BC-CP-CF-JBS
SAP Trust Center: Platform status verification
Guided Answers: Self-service troubleshooting

Updates and Maintenance

Source: SAP BTP Job Scheduling Service Documentation

To Update This Skill:

Check GitHub repository for documentation updates
Review What's New section for changes
Update affected reference files
Update templates if configurations changed
Update "Last Verified" date

Quarterly Review Recommended: Check for updates every 3 months

Next Review: 2026-02-27

Bundled Resources

Reference Files

references/concepts.md - Schedule types, formats, lifecycle, async mode, multitenancy (12K lines)
references/rest-api.md - Complete REST API reference with all endpoints (20K lines)
references/setup-guide.md - Prerequisites, service instance creation (9K lines)
references/security.md - OAuth 2.0, XSUAA scopes, credential rotation (11K lines)
references/integrations.md - Cloud ALM, Alert Notification Service (8K lines)
references/troubleshooting.md - FAQ, error scenarios, monitoring (9K lines)
references/operations.md - Dashboard, backup/restore, service behavior (8K lines)
references/changelog.md - Version history, feature updates (2021-2025) (9K lines)

Templates

templates/job-creation.json - Job creation request template with examples
templates/xs-security.json - XSUAA configuration template for OAuth scopes

Skill Version: 1.0.1 Last Updated: 2025-11-27 License: GPL-3.0 Maintainer: SAP Skills Team | https://github.com/secondsky/sap-skills

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

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

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

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

Phase

States

Description

SCHEDULED

Queued for future run

RUNNING

TRIGGERED, ACK_RECVD, ACK_NOT_RECVD

Executing

COMPLETED

SUCCESS, ERROR, REQUEST_ERROR, UNKNOWN

Finished

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

# 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" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json"

{ "xsappname": "<app-name>", "scopes": [{ "name": "$XSAPPNAME.JOBSCHEDULER", "description": "Job Scheduler Scope", "grant-as-authority-to-apps": ["$XSSERVICENAME(<jobscheduler-instance>)"] }] }

POST /scheduler/jobs { "name": "myJob", "description": "Process daily reports", "action": "https://myapp.cfapps.eu10.hana.ondemand.com/api/process", "active": true, "httpMethod": "POST", "schedules": [{ "active": true, "description": "Daily at 6 AM", "repeatAt": "6.00am", "startTime": {"date": "2025-01-01", "format": "YYYY-MM-DD"} }] }

const JobSchedulerClient = require('@sap/jobs-client'); const scheduler = new JobSchedulerClient.Scheduler(); // Create job scheduler.createJob({ url: vcapServices.jobscheduler[0].credentials.url }, { name: 'myJob', action: 'https://myapp.../process', active: true, httpMethod: 'GET', schedules: [{ cron: '* * * * 0 0 0', active: true }] }, (err, result) => { /* handle */ });

Limit Type

Response Code

Header

Client limit exceeded

429

retry-after (seconds)

Absolute limit exceeded

503

throttling (milliseconds)

Outage Duration

Behavior

< 20 minutes

All missed executions run immediately

>= 20 minutes

Only last missed execution runs

sap-btp-job-scheduling