Using the Job Scheduling Service

Objectives
After completing this lesson, you will be able to:

After completing this lesson, you will be able to:

  • Understand the Job Scheduling service

Initialization of Job Scheduling Service

Why Should You Use a Job Scheduling Service ?

Maybe we start thinking about a Cloud Foundry application. This application, with its different duties (e.g. persisting hierarchy models-, generating reports on a regular basis-, informing send out by signaling if thresholds are passed on the datamodel) has a variety of business processes to service. A certain degree of these processes might be routines that have to be executed either synchronously or asynchronously on a regular basis. Wouldn't it be good to have these results without the necessity to execute the actions that create them ? At this point the great SAP Business Technology Platform Job Scheduling Service comes into play.

Some words and explanations of the terms we are using in Job Scheduling Service try to clear up things and make it easier to get speed up when you start working with the documentation:

  • Job Scheduling Service

    This service has to be created as an instance as the basis for your jobs. You can select this Cloud Service from the Service Marketplace within your BTP Trial account.

  • Job

    A job is a logical structure that manages one ore more schedules and finally executes the defined action endpoints. It is implemented as an URL. Jobs run according to a schedule synchronously or asynchronously. Jobs can also be configured with a Cloud Foundry task.

  • Action

    An action is the atom of work what it is all about. An action works on your data so as to execute processes according to its schedule assigned to jobs.

  • Dashboard

    The Job Scheduling Service Dashboard lets you define jobs and the assigned actions belonging to them. Moreover it allows to create schedules and execute other administrative work.

  • REST endpoint

    The REST endpoint of your SAP BTP application is used by your Job Scheduling Service invoking HTTPS Calls.

  • Instance

    An Instance of Job Scheduling Service and additionally XSUAA Service has to be created. The binding with the App(s) has to follow the correct sequence. First you are to bind XSUAA Service.

  • XSUAA

    The XSUAA Service brings security aspects into the Job Scheduling Service. XSUAA means Authorization and Trust Management. The correct privileges have to be in place to set up the Job Scheduling Service.

  • Service Plan

    A service plan is a particular type of service. Next to lite, there are plans like: Standard, Default, Securestore, hdi-shared, lite, space, application, s3-standard and apiaccess. Service is deprecated.

  • Lite

    The service plan lite guarantees basic authentication (username and password) for REST API calls.

What are the prerequisites for using the Job Scheduling Service ?

Having talked about the terminology we can approach now the practical integration of the SAP Job Scheduling Service.

Let us point out the prerequisites in detail. You can take it as a kind of checklist.

  • BTP Account

    BTP access, global account- and subaccount has to be set up appropriately.

  • Role

    For this kind of Service the Global Account Administrator role is necessary.

  • Quota

    The contract with SAP has to allow the usage of this service.

  • Space

    The location of the Job Scheduling Service with all applications is the level Space.

  • Space Role

    For binding the service instance to your applications you need to have the Space Developer or alternatively-the Space Manager Role.

  • Application

    The SAP Job Scheduling Service does not take care of applications. This has to be set up before it is possible to use this service.

  • Endpoint

    Accordingly to applications also its endpoints have to be configured and tested positively before using the Scheduling Service.

  • Location

    It is compulsory to have Applications and the Job Scheduling Service Instance in the same space.

Configure and operate the Job Scheduling Service

Once you've completed the subscribed to the SAP Job Scheduling service, you have to create a service instance and bind it to your application to use the service.

In the Cloud Foundry environment the binding between services and applications can take place in two different ways:

  1. SAP BTP Cockpit
  2. CLI - Cloud Foundry command line interface

    In this introduction we will use the SAP BTP Cockpit for setting up the SAP Job Scheduling Service.

Create a Service Instance in SAP BTP Cockpit - SAP Help Portal

Create a Service Instance Using CF CLI - SAP Help Portal

As shown in the image above the steps should be followed in the given order for the SAP Job Scheduling service to work.

In this example we are showing the scenario when using new application

  1. Create an instance of the SAP job Scheduling service
  2. Create an xsuaa service instance.
    Note
    If you already have an xsuaa service instance, remember to update it first with the updated xs-security.json file.
  3. Deploy the application.
  4. Bind the xsuaa service instance to your application
    Note
    During the Binding process remember to bind xsuaa first.
    .
  5. Bind the SAP Job Scheduling service instance to your application.
    Note
    If you don't bind your application to the SAP Job Scheduling service instance, you can't call the SAP Job Scheduling service from your own application.

In case of existing applications

  1. Create an instance of the SAP job Scheduling service
  2. Update your xsuaa service instance.

    This is necessary as the content in the xs-security.json where the scope is granted to the SAP Job Scheduling service with the grant-as-authority-to-apps has changed.

  3. Bind the SAP Job Scheduling service instance to your application.

Understand the Job Execution Modes

Watch this video to learn more about the job execution modes.

Synchronous Mode Process Overview

  • When the scheduler invokes the endpoint, the application must return the response with an appropriate HTTP status code, indicating success or failure.

  • To indicate success, the application must use a suitable standard status code between 200 and 399, except 202-ACCEPTED.

  • To indicate an execution failure, the application must use one of the server error codes as outlined in the HTTP protocol specification.

Asynchronous Mode Process Overview

  • When the scheduler invokes the endpoint, it passes the request headers values for the Job ID, Job Schedule ID, Job Run ID, and the SAP Job Scheduling service Host URI, respectively.
    • x-sap-job-id- Job ID
    • x-sap-job-schedule-id - Job Schedule ID,
    • x-sap-job-run-id- Job Run ID
    • x-sap-scheduler-host- SAP Job Scheduling service Host URI
    The application must extract the header values and store them using a suitable mechanism, such as in-memory storage that uses caches or libraries, or persistent storage that uses a database.
  • The application must return an acknowledgment response with the HTTP status code 202-ACCEPTED.

    The response indicates to the scheduler that the application has accepted and is processing the request. If the application returns a server error code, the scheduler interprets it as a failure of the job run.

  • After the application completes the job processing, it must invoke the Update of Job Run Log API to indicate success or failure and (optionally) create log text for the job run.
  • If the application doesn't invoke the Update of Job Run Log API, the scheduler isn't notified of the status of the job run and, after a configurable time interval, reverts the job to the status UNKNOWN.
Note

Cloud Foundry tasks always run asynchronously.

Understand Job and Schedule Relationship

Watch this video to learn about the Job and Schedule relationship.

Create a Job

To create a Job follow the steps as shown on the left side of the above image.

  1. Navigate to the Jobs section
  2. Click Create Job
  3. In the next window provide the details
    • Name- Name of the job. Name must not contain special characters or only numbers.
    • Description-Provides more details about a job.
    • Target application- The deployed application.
    • Action - The fully qualified URL endpoint to be called when the job runs.
    • HTTP Method- The HTTP method to be used to call the job action endpoint URL. Allowed values are "GET", "POST" , "PUT", and "DELETE".
    • Start Time- Start time for the job. The scheduler checks if a start time for a schedule is available apart from the start time available for a job. The schedule start time is used for determining the start of the schedule run. If the schedule start time is not available, the start time of the job is used.
    • End Time- End time for the job. The scheduler checks if an end time for a schedule is available apart from the end time available for a job. The schedule end time is used for determining the end of the schedule run. If the schedule end time is not available, the end time of the job is used.
    • Active- Activation status of the job (default value is false).

After we have created a job, we navigate into that job and we can begin creating schedules for it. Follow the below steps.

  1. Navigate to the Schedules section
  2. Click Create Schedule
  3. In the next window provide the details
    • Description-Provides more details about a job.
    • Pattern- Chose one from the available options(cron, time, repeatInterval, and repeatAt) .
    • Value- The value depending on the format you want to use..
    • Note
      This is the only mandatory field during creation of Job Schedule however it is best practise to have an input for all of the fields provided.
    • Start Time- Start time for the job schedule.
    • End Time- End time for the job.
    • Data (JSON)- Data value is passed to the job action endpoint when invoked by Job Scheduler.

      For the HTTP method "PUT" or "POST", the data parameters are sent in the request body while invoking the endpoint. For the HTTP method "GET" or "DELETE", the data parameters are sent as query strings .

    • Active- Activation status of the job schedule. The allowed values are true or false.

Following section covers the different Scheduling options.

Watch this video to learn about the different Scheduling options.

Schedule Formats - SAP Help Portal

Understand Security for SAP Job Scheduling service

Below steps will cover the steps taken to create an authentication method so that our endpoint is protect with oAuth 2.0

In the previous section we saw the steps to create the Job Scheduler instance and xsuaa Instance, now we will see how we can enable the Security components. We will follow the same sequence.

  • During the creation of the Job Scheduler service instance include the XSUAA support when configuring it with the service plan standard .

    This will allow our job scheduler privileges to be able to call REST endpoint with a JWT token

  • During the creation of the xsuaa instance include the JSON shown, this requires the callee to have the right authorizations to call it.

    Code snippet
    {
     "xsappname": "<app name>",
     "scopes": [{
     "name": "$XSAPPNAME.Jobs",
     "description": "SAP Job Scheduling
     service Scope",
     "grant-as-authority-to-apps": [
     "$XSSERVICENAME(<jobscheduler instance name>)"
     ]
     }]
    }
    Expand

.When we are granting these authorizations to a user, normally we grant the scope by putting it into a role and assigning the role to the user

Since our job scheduler is not a user but a service, our application grants this scope to the job scheduler at creation instead.

  • Next we can deploy our app and then bind the XSUAA instance first to our app

  • At the time of binding the XSUAA instance passes the credentials to our app and also gets to know that we are also granting some permissions to a Job Scheduler instance

  • Finally when we bind the Job Scheduler instance to our application the Job Scheduler will accept the granted authority and will be ready to invoke our protected REST endpoint as a trusted client

Note
As mentioned previously the sequence is very important. This will allow the credential exchanges to execute successfully to grant our job scheduler instance the dummy scope and execute the apps endpoint

Secure Access - SAP Help Portal

Create and Schedule Jobs

Log in to track your progress & complete quizzes