Developing Applications Running on SAP BTP Using SAP HANA Cloud

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.

Common Terms used in Job Scheduling

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.

Prerequisites
  • 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

Process Flow Using Job Scheduling Service

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.

Job Execution Modes

As seen in the image there are two types of job execution mode that can be configured for the job scheduling service. The SAP Job Scheduling service executes jobs that support action endpoints in a synchronous mode or in an asynchronous (or batch) mode.

Synchronous Mode Synchronous requests are used if the SAP Job Scheduling service calls the action endpoint of the application and the application logic is executed in a short span of time.

An example of this would be an exchange rate application that fetches the latest currency exchange rates frequently using scheduled jobs.

Asynchronous ModeAsynchronous requests are used for job runs with a large span of time.

We can use this type of run for uploading large amounts of data or for migrating a database.

Synchronous Mode Process Overview

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

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 acknowledgement 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.

Job and Schedule Relationship

Now, we will cover the Job Schedule relationship.

When you are ready to use Job Scheduler, you will navigate to the Job Scheduler Dashboard on BTP Cockpit.

Once in the dashboard you will work on creation of a Job.

Job is used to trigger a REST endpoint of an application and begin a task such as running a batch job or backing up data.

Each Job can be scheduled with different scheduling types that is covered later in this lesson.

The dashboard can store jobs for all kinds of applications or Cloud foundry tasks. We have the option of having one or many jobs which can have one or many schedules.

Process Flow - Create a Job and Schedule

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.

Scheduling Options

There are two schedule types that can be used for scheduling jobs:

One Time Schedule - This consists of running a job once and it becomes inactive then after.

Further within the one time schedule type we have two inputs that the schedule configuration will accept.

  • The first valid input is human readable text which is shown at the top right of the above image.
  • The second valid input are date string formats which are SO-8601 or IETF compliant and is shown at the bottom right of the above image.

The Second type is recurring schedules.

Recurring schedules - This consists of running a job once and it becomes inactive then after.

Further we have the following options.

  • The first option is repeat interval types.
  • The second option is the cron input which is compliant to its own format.
  • The third option is the repeat at input.

Schedule Formats - SAP Help Portal

Understand Security for SAP Job Scheduling service

Security

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

Business Example

Business Example

Save progress to your learning plan by logging in or creating an account