zhongwei/gh-secondsky-sap-skills-skills-sap-btp-job-scheduling
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3fdee31e08dcaf54fd8ee246814b86b55c546636
gh-secondsky-sap-skills-ski…/references/concepts.md
Zhongwei Li 3fdee31e08 Initial commit
2025-11-30 08:55:10 +08:00

12 KiB
Raw Blame History

SAP BTP Job Scheduling Service - Core Concepts

Source: https://github.com/SAP-docs/sap-btp-job-scheduling-service/tree/main/docs/20---Concepts Last Updated: 2025-11-22

Table of Contents

  1. Core Components
  2. Schedule Types
  3. Schedule Formats
  4. Schedule Lifecycle
  5. Asynchronous Mode
  6. Cloud Foundry Tasks
  7. Multitenancy
  8. Service Behavior

Core Components

Job

A job is a collection of schedules with an action endpoint. Jobs:

  • Invoke a configured URL at specified times
  • Execute synchronously (short operations, ≤15 seconds) or asynchronously (long processes)
  • Service plans are based on the number of schedules within a job
  • Names must not contain special characters or only numbers
  • Names must be unique per technical user

Action Endpoint

An HTTP or REST endpoint exposed by the application that the service invokes:

  • Must be OAuth 2.0 protected in production (standard plan)
  • Must use HTTPS for encrypted communication
  • Receives job execution requests with authorization headers

Schedule

A one-time or recurring entity within a job:

  • Defines when and how often a job runs
  • Supports multiple format types (cron, date/time, human-readable)
  • Has its own lifecycle states
  • Can be activated/deactivated independently

Run Log

Records of job executions:

  • Contains execution status, timestamps, and optional messages
  • Retained for 15 days before automatic deletion
  • Downloadable via API or dashboard

Schedule Types

One-Time Schedules

Execute a single time using:

Human-Readable Text:

"time": "10 hours from now"
"time": "tomorrow at 4pm"
"time": "now"  // Immediate execution
"time": "Friday at 2am"

Date String Formats:

"time": "1994-11-05T08:15:30-05:00"  // ISO-8601
"time": "Sat, 05 Nov 1994 08:15:30 GMT"  // RFC 2822

Behavior:

  • Auto-deactivate after execution (successful or failed)
  • Execute at configured time, overriding job-level startTime
  • Execute immediately if scheduled time is past but endTime is future
  • Do not execute if both time and endTime are in the past
  • Automatic Cleanup: Unused one-time schedules are deleted after 30 days of inactivity (as of May 2025)

Recurring Schedules

Run periodically at specified intervals using:

repeatInterval: Denotes interval between schedules in human-readable format:

"repeatInterval": "5 minutes"
"repeatInterval": "2 hours"
"repeatInterval": "1 day"
"repeatInterval": "2 weeks"
  • Next execution adjusts if previous execution was delayed

cron: Crontab expression determining execution times:

"cron": "* * * * 9 0 0"  // Daily at 9:00:00 AM
"cron": "* * * mon 10 0 0"  // Every Monday at 10:00
  • Service assumes 30-day months and 365-day years

repeatAt: Exact daily execution time:

"repeatAt": "4.40pm"
"repeatAt": "18.40"
"repeatAt": "6.20am"

Behavior:

  • If a job exceeds its duration, the next scheduled job still starts on time
  • Activating an inactive schedule after planned start triggers immediate execution

Schedule Formats

Cron Format (7 Fields)

SAP Job Scheduling Service uses an extended cron format with seven fields (left to right):

Year  Month  Day  DayOfWeek  Hour  Minute  Second

Field Constraints:

Field Values Description
Year 4-digit (e.g., 2025) Calendar year
Month 1-12 Calendar month
Day -31 to 31 Day of month (negative = from end)
DayOfWeek mon, tue, wed, thu, fri, sat, sun 3-letter abbreviation
Hour 0-23 Hour of day
Minute 0-59 Minute of hour
Second 0-59 Second of minute

Supported Operators:

Operator Meaning Example
* Any value * * * * 9 0 0
*/a Every a-th value * * * * */2 0 0 (every 2 hours)
a:b Range a to b * * * * 10:12 0 0 (hours 10-12)
a:b/c Every c-th in range * * * * 10:12/2 0 0
a.y a-th occurrence of weekday y * * * -1.sun 9 0 0 (last Sunday)
a,b,c Multiple values * * * mon,wed,fri 9 0 0

Examples:

* * * 10:12 */30 0     Every 30 minutes between 10:00-12:00 daily
* * * -1.sun 9 0 0     Last Sunday of each month at 09:00
* 1,4,7,10 1 * 0 0 0   First day of each quarter at midnight
* * * * 9 30 0         Daily at 9:30 AM
* * 15 * 18 0 0        15th of each month at 6 PM

Important: Service uses SAP cron format, NOT Linux cron format.

Date/Time Formats

Date Object Format:

{
  "startTime": {
    "date": "2025-10-20 04:30 +0000",
    "format": "YYYY-MM-DD HH:mm Z"
  }
}

Supported Parsing Tokens:

Token Description
YYYY 4-digit year
YY 2-digit year
M/MM Month (1-12)
MMM/MMMM Month name
D/DD Day of month
H/HH Hour (24-hour)
h/hh Hour (12-hour)
a/A AM/PM
m/mm Minute
s/ss Second
Z/ZZ Timezone offset
X UNIX timestamp (seconds)
x UNIX timestamp (milliseconds)

Date String Format:

Valid ISO-8601 or RFC 2822 representations:

1994-11-05T08:15:30-05:00     // ISO-8601
Sat, 05 Nov 1994 08:15:30 GMT // RFC 2822

Human-Readable Formats

time Parameter:

"10 hours from now"
"tomorrow at 4pm"
"now"
"Friday at 2am"
"next week"

repeatAt Parameter:

"4.40pm"
"6.20am"
"18:40"

repeatInterval Parameter:

"10 hours"
"2 days"
"5 minutes"
"3 weeks"
"1 month"

Supports: years, months, weeks, days, hours, minutes, seconds

Schedule Lifecycle

Primary States

State Description
SCHEDULED Schedule queued for future run
RUNNING Schedule actively executing
COMPLETED Schedule run finished

Detailed State Transitions

During SCHEDULED Phase:

  • SCHEDULED: Awaiting execution at future time

During RUNNING Phase:

  • TRIGGERED: Scheduler triggered request to job action endpoint
  • ACK_RECVD: Application sent 202 Accepted acknowledgment
  • ACK_NOT_RECVD: Application failed to acknowledge within timeframe

During COMPLETED Phase:

  • SUCCESS: Application executed job and replied with success status
  • ERROR: Application encountered error, sent server error code
  • REQUEST_ERROR: Error occurred invoking job endpoint
  • UNKNOWN: Application didn't invoke Update Job Run Log API

Cloud Foundry Task States

RUNNING Phase:

  • TRIGGERED: Task creation initiated
  • ACK_RECVD: Task creation successful

COMPLETED Phase:

  • SUCCESS: Task completed successfully
  • ERROR: Task encountered error
  • TIMEOUT: Execution exceeded configured timeframe

Asynchronous Mode

Overview

Asynchronous mode handles job runs with large execution times, particularly for action endpoints triggering long-running processes.

Request Flow

  1. Scheduler Invokes Endpoint with headers:

    • x-sap-job-id: Job identifier
    • x-sap-job-schedule-id: Schedule identifier
    • x-sap-job-run-id: Run identifier
    • x-sap-scheduler-host: Service host URI

  2. Application Stores Headers using suitable mechanism (in-memory or persistent storage)

  3. Application Returns 202 Accepted immediately as acknowledgment

  4. Application Processes Job asynchronously

  5. Application Updates Run Log via callback API with final status

Implementation Example

// Receive job request
app.post('/api/process', (req, res) => {
  // Extract and store headers
  const jobContext = {
    jobId: req.headers['x-sap-job-id'],
    scheduleId: req.headers['x-sap-job-schedule-id'],
    runId: req.headers['x-sap-job-run-id'],
    schedulerHost: req.headers['x-sap-scheduler-host']
  };

  // Store context for later callback
  storeJobContext(jobContext);

  // Return immediate acknowledgment
  res.status(202).send({ message: 'Accepted' });

  // Start async processing
  processJobAsync(jobContext);
});

// After job completion
async function onJobComplete(jobContext, success, message) {
  await updateRunLog(jobContext, { success, message });
}

Callback API

PUT /scheduler/jobs/{jobId}/schedules/{scheduleId}/runs/{runId}

{
  "success": true,
  "message": "Long running operation completed successfully"
}

Timeout Handling

  • Default timeout: 30 minutes
  • Configurable up to: 604,800 seconds (7 days)
  • If application fails to invoke Update API, status reverts to UNKNOWN

Important Notes

  • Cloud Foundry tasks always run asynchronously
  • Server error codes indicate job failure
  • Single callback with final status (not multiple updates)

Cloud Foundry Tasks

Definition

An app or script whose code is included as part of a deployed app but runs independently in its own container.

Characteristics

  • Designed for minimal resource consumption
  • Always execute asynchronously
  • Cannot be created via REST API (only dashboard)
  • Require Space Developer role for creation
  • Memory configurable (default 1GB)

Memory Configuration

Via dashboard JSON options:

{
  "memory_in_mb": 2048
}

Task States

Same as asynchronous jobs plus:

  • TIMEOUT: Execution exceeded configured timeframe

Multitenancy

Overview

The service enables deployed multitenant applications to create, view, edit, and delete jobs in the context of subscribed tenants.

Prerequisites

  • Application deployed to provider subaccount
  • Application bound to SaaS Provisioning service
  • Application bound to Job Scheduling service
  • Job Scheduling defined as application dependency

Tenant Isolation

Strict Data Separation:

  • Jobs and schedules created for a SaaS tenant are NOT accessible by other tenants
  • Credentials bound to a SaaS tenant access only that tenant's data
  • Each tenant maintains its own job and schedule collection

Credential Types

Provider-Level Credentials (PaaS):

  • Bound to the SAP Job Scheduling service instance
  • Can manage ALL jobs across all tenants
  • No tenant restrictions

Tenant-Specific Credentials (SaaS):

  • Bound to specific tenant
  • Access only tenant-specific data
  • tenantId query parameter returns 400 for SaaS tenant tokens

Unsubscription Behavior

Single-Instance Setup:

  • All corresponding jobs and schedules deleted when tenant unsubscribes

Multi-Application Setup:

  • Data persists until ALL subscriptions removed

Token Requirements

Use client credentials flow with XSUAA to obtain access tokens for job registration and management.

Service Behavior

Outage Recovery

Under 20 Minutes:

  • All missed executions re-executed immediately when service restores

20+ Minutes:

  • All scheduled runs except the last one are skipped
  • Prevents overwhelming target applications with excessive requests

Service Level Agreement

Scheduled jobs have approximately 20-minute latency tolerance from their scheduled execution time.

Data Retention

Run logs automatically removed 15 days after generation. Download via API or dashboard before removal.

Auto-Deactivation Triggers

Schedules auto-deactivate when:

  • One-time schedule executed (successful or failed)
  • No valid future dates exist
  • Job/schedule endTime reached
  • Action endpoint unreachable for 10+ consecutive days

Timezone

UTC Only: No other timezones supported. All schedule times are interpreted as UTC.

External References

SAP Documentation

Source Files

  • concepts-26572ad.md
  • asynchronous-mode-d9fd81c.md
  • schedule-types-9cf8c14.md
  • schedule-formats-54615f0.md
  • schedule-lifecycle-e1805f2.md
  • multitenancy-in-sap-job-scheduling-service-464b613.md
  • service-behavior-d09664b.md
Reference in New Issue View Git Blame Copy Permalink