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

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

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

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

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

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

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

  Copy code

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

  Copy code

.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