Using SAP Job Scheduling Service in SAP BTP [1]: First Simple Scenario

[CarlosRoggan]

This series of blogs intends to show in an easy step-by-step way how to use the SAP Job Scheduling service in SAP Business Technology Platform (SAP BTP).

Quick links:
Intro Blog
Project Files

Overview

In this first blog, we’re going to go through a sample scenario to cover the basic steps.
It is meant to be executed by anybody. Really, no coding skills are required.

Scenario

We’re creating a small Node.js application, which starts an express server.
This little app does nothing more than exposing a REST endpoint.
When this endpoint is invoked, it writes a log and returns a string.
The only reason for doing this: the endpoint can be invoked automatically by the Job Scheduling service.

As such, the second small thing we’re creating is a little job in the Job Scheduling service dashboard
The only reason for doing this: the job invokes the REST endpoint of our small Node.js app.

The scenario is meant to be executed in a Trial account of SAP BTP.

Note: There's only one small difference when working in a productive environment. For more information, please refer to the next blog in the series.

Steps

We’re going to cover the following steps:
1. Create service instances.
2. Create a sample app.
3. Use the Job Scheduling service dashboard to define a job and view the result.

Although the scenario is pretty simple, let’s have a look at the involved components:



Explanation:
Our app is bound to 2 service instances.
Our app exposes a REST endpoint, whose URL is used by the job when the job is created in the dashboard.
We assume that our app contains any application logic, although it isn’t true in this sample.

Note: Since our current scenario is designed for a Trial account, there’s no OAuth flow required/supported.

Prerequisites

We're creating a Node.js application so Node.js must be installed on your machine. To install Node.js, see Appendix 1: Install Node.js.

The Cloud Foundry command line client (CF CLI) is not mandatory, but it makes life easier. To install the CF CLI, see Appendix 2: Install CLI.

Preparation

1. Create a Job Scheduling service instance.
Follow the description in the previous blog to create an instance with name jobschedulerinstance.

2. Create an XSUAA service instance.
In the Service Marketplace, navigate to Authorization & Trust Management and create the following instance:

Service plan: “broker”
Parameters: leave empty
Instance name: xsuaaforsimplejobs

 

Create Application

Now we can create our app.
This app will be triggered by the Job Scheduling service.
For this example, we're using Node.js, it is the easiest way of exposing an endpoint.

We're dealing with only 3 files, so let's start:

Create the project files and folders.
This is the project structure we want to create:


1. To start, let's create the project root folder:

C:\tmp

manifest.yml

Inside the root folder, create a file called manifest.yml and paste the following content:

---

applications:

- name: jobapp

  path: app

  memory: 128M

  buildpacks:

    - nodejs_buildpack

  services:

    - xsuaaforsimplejobs

    - jobschedulerinstance

Make sure to change the name to any unique name.

Explanation:
Apart from the usual descriptor information, it contains references to the 2 service instances created earlier.
Make sure to adapt the service names so that they match the names of your instances.
Also, you might need to adapt the name of the app if you get an error during deployment.

Note: The order of binding is relevant! First, bind the XSUAA service instance to the app. Only then bind the Job Scheduling service instance to the app.

In case you forget, don't worry. During deployment, when binding the Job Scheduling service instance, you'll get an error if the Job Scheduling service doesn't find an XSUAA binding.

Nevertheless, don't forget: bind XSUAA first!

In case you tend to forget, you can use this (silly) mnemonic: "Bind xs-USA first again"
(sorry for that...)

At this point in time, we have the root folder and the manifest.yml file.

2. Now create the application folder inside the root folder:

C:\tmp\app

Inside the app folder, create a file with name package.json:

package.json

Paste the content below into the package.json file:

{

  "main": "server.js",

  "dependencies": {

    "express": "^4.16.3"

  }

}

Explanation:
The descriptor file for the Node.js runtime declares the dependency
and it also states which javascript file should be executed upon startup of the app.

server.js

3. In the same app folder, next to the package.json, create a file with name server.js.
This is the executable program:

const express = require('express');

const app = express();



app.get('/runjob', function(req, res){

   console.log('==> [APP JOB LOG] Job is running . . .');

   res.send('Finished job');

});



const port = process.env.PORT || 3000;

app.listen(port, function(){

   console.log('listening');

})

Explanation:
When this little program is executed, it starts a little server (using the express module).
It also defines an endpoint "runjob".
When this endpoint is invoked by an HTTP GET request, then the code above is executed.

This is all we want to demonstrate in this blog:
A sample app with REST endpoint to be triggered by the Job Scheduling service.

Deploy Application

To build the application, open command prompt, navigate to the app folder C:\tmp\app
then execute npm install

To deploy the application, after a successful build, navigate to the root folder C:\tmp
and execute cf push. If you don't like the command line, check Appendix 4: Deploying Applications.

During deployment, you can observe how:

1. First, the Authorization & Trust Management service (XSUAA) is bound.
2. Afterwards, the Job Scheduling service is bound.


After deployment, we can test our endpoint:
1. Get the app URL from the command prompt, or from the app details in the cockpit.
2. Append the endpoint segment.
3. Then, invoke the endpoint in the browser.
In my example: https://jobapp.cfapps.eu10.hana.ondemand.com/runjob
As a result, the browser window should print the text as coded in our little app.

That's it.
We’re done with the first part.
Next part is to work with the Job Scheduling service.

Job Scheduling Service

Our little app is meant to simulate a productive application.
After successful deployment, we can now learn how to use the Job Scheduling service.

Open Dashboard

To open the dashboard:

1. Go to your subaccount.

2. Go to your space.

3. Go to Service Instances.

4. Find the instance created above (jobschedulerinstance) and choose View Dashboard.

Example:


Note: To open the dashboard, you might need to enter your cloud user credentials.

Note: In case you're finding it difficult to display the Job Scheduling service dashboard, are you using an old Microsoft browser? Newer UI5 versions (from 1.88) don’t support the legacy browsers IE11 and Edge Legacy (Edge HTML) anymore (more info). To solve the problem, you should use a more modern browser.

Create Job

First thing we do – after enjoying the beautiful UI – is to create a job.
1. Hence, choose Jobs on the left-hand menu.
2. Then, choose Create Job.
3. In the creation dialog, specify the required information:

Explanation:

Name:
A name of your choice, so you can find the job later in the list

Description:
The usual description

Action:
here the full URL of the endpoint has to be entered. That’s the URL we’ve tried above, the app’s root URL and appended the endpoint segment
In my example:
https://jobapp.cfapps.eu10.hana.ondemand.com/runjob

HTTP Method:
This depends on how you’ve implemented your endpoint.
In our example, it is a simple GET request (remember, we wrote app.get).

Start Time / End Time:
This is not the schedule, this is the duration of the created job.
You can leave it empty.

Activate Job:
Should be a YES, we want to let it run.

After you choose Save, the job is added to the list.
But it is marked with a warning, which is a polite hint to tell us that:
This job is useless as long as we don’t define a schedule.

Create Schedule

1. Click the job name.
2. Then, choose Schedules on the left menu.
3. Choose Create Schedule.
In the dialog, enter some meaningful values.
In my example:
To keep the example short, I’ve configured to run just one time in the near future:


This dialog looks self-explanatory. However, there's one little possible pitfall.

Explanation:

Description:
No explanation required

Pattern:
Basically, there are 2 choices:

• Run once
• Run repeatedly

For the second option, there are a couple of possibilities.
In our example, we choose the simplest configuration.

Value:
This refers to the chosen pattern.
Clicking the icon on the right side of the field opens the help page, which is indeed helpful.
In our simple example, we enter the text “in 10 seconds”.

Start Time (UTC):
This entry makes rather sense in conjunction with a recurring pattern, however:
Important: If you don’t enter a value here, I assume that the dialog enters the current time as default.
But the current time in my time zone is not the current time in the cloud.
Luckily, the dialog has stated the relevant time zone in the label: it is UTC.
As such, if you’re not located in UTC, like me, you have to adapt the current time, proposed by the dialog, to the current time in UTC.
Otherwise, the scheduled job won’t start as expected.
Bottom line: you might always need to enter a value here.

End Time (UTC):
Same as Start Time (UTC)

Data:
This is relevant for REST endpoints which are executed via a POST request and expect a request payload.

After choosing Save, the countdown starts and we have to hurry to view the result.

View Result

1. First, we see if the created schedule is active.
2. Click the Description (link). Then, Run logs.
3. We see the status SCHEDULED/SCHEDULED.
We might need to refresh the browser window
4. After the job has finished, we see the green status COMPLETED/SUCCESS.

View Run Log

Click the spectacles icon to open a dialog containing the details of the execution



Check:
List of Schedules: we can see: our created schedule is red and inactive
List of Jobs, to realize that the warning has gone
Note:
Although the job run is finished, the status of the Job itself doesn’t change as long as the jobs "active" period is not over

Want a Negative Test?

The above job run has shown the happy path, it completed with green success status.
To view a red result, we can either change the code of our app, or follow these easy steps:

1. Stop your deployed app (cockpit or command line via cf stop jobapp).
2. Then create a schedule to run once (or just re-activate the existing schedule) and see the result as red status COMPLETED/ERROR.
3. Run Log shows the HTTP response of the call to a non-existing endpoint.

Summary

In this blog, we've learnt the basics about the SAP Job Scheduling service.

1) We've created an application to simulate a real-world app.
The app exposes a REST endpoint.
The app is bound to the Job Scheduling service and the Authorization & Trust Management service.

2) We've created a job, and a schedule which invokes that endpoint.

Remember: Order of Binding

First, bind the Authorization & Trust Management service
------>
then, bind the Job Scheduling service.

In other words: "Bind XS-USA first again"

Next Steps

Example in productive landscape with security: Using Job Scheduler in SAP Cloud Platform [2]: simple OAuth scenario
To keep the correct order and avoid errors, explain the flow with an existing app and service instances.

Links

See Using Job Scheduler in SAP Cloud Platform [0]: Intro and Prep.

Appendix 1: Install Node.js

Go to the Node.js home page, download the stable release (“Recommended for most users”) and follow the installation instructions. You might need to restart your computer.

After the installation, you can verify if Node.js is up and running:
Open a command prompt and type:  <span style="color: #0000ff; font-family: Courier New;">node -v</span>
It should respond with a version information and no error message:

Appendix 2: Install CLI

Installation of Cloud Foundry CLI, the official command line client for Cloud Foundry is simple and no cryptic configuration is required.

Just:
Download -> Unzip -> Install

Download the zip from here: https://github.com/cloudfoundry/cli#downloads
I would choose the installer. Direct link

After downloading the zip, unzip it.
Right-click the installer.exe file and choose "Run as administrator".
That's it.

The installer installs the binary file to C:\Program Files\Cloud Foundry
If you look into that directory, you'll see a cf.exe file.
This is "THE TOOL".

Verify the installation:
Open your command shell and type cf, then press enter.
As a result, the version of "Cloud Foundry command line tool" is printed, along with the usual usage instructions.

Note: In case of proxy issues, see http://docs.cloudfoundry.org/cf-cli/http-proxy.html.

Note: I've copied from this great blog, there are useful examples for beginners

How to Log On to the Cloud Foundry Environment

cf login -a <api> -u <user> -p <pwd> -o <org> -s <space>

Example:
cf login -a api.cf.eu10.hana.ondemand.com -u usr@mail.com -p abc -o P123trial -s dev

From where do I get the info?
In the cockpit, navigate to the your subaccount and see:

Appendix 3: All Project Files

In this appendix you can find all files required to run the described sample application.
For your convenience, see here again the folder structure:



Find below the content of all 3 requried files

manifest.yml

Don't forget to adapt the name and the service instances.

---

applications:

# make sure to adapt the name to a unique name, otherwise deploy might fail

- name: jobapp

  path: app

  memory: 128M

  buildpacks:

    - nodejs_buildpack

  services:

    - xsuaaforsimplejobs

    - jobschedulerinstance

package.json

{

  "main": "server.js",

  "dependencies": {

    "express": "^4.16.3"

  }

}

server.js

const express = require('express');

const app = express();





app.get('/runjob', function(req, res){

   console.log('==> [APP JOB LOG] Job is running . . .');

   res.send('Finished job');

});





const port = process.env.PORT || 3000;

app.listen(port, function(){

   console.log('Server is running');

})

Appendix 4: Deploying Applications

For the sake of completeness, in case you aren't familiar, find below the 2 ways of deploying an app to SAP BTP, Cloud Foundry environment.

Using the Cloud Cockpit

If you don't want to install the CLI, you can use the SAP BTP cockpit, which offers a user interface for deployment of local applications.

Prerequisite:
You need to have a zip file with the application on root level.
I mean, the zip doesn't contain a folder which contains the app.
The app must be directly zipped.
The manifest.yml file is located on the file system, not in the zip.

Go to your subaccount and space and click on Applications in the left menu.
On top of the list of applications, there's the Deploy button.
Press the button.
In the Deploy Application dialog, enter the path to the zip file and to the manifest.yml file.
After deploying the app, click the app-name-link to go into the application details screen.
There, you can see the Logs menu entry on the left side, which allows access to the application logs.

Using the CLI

Using the command line client is recommended as it is faster (and you'll anyways need it, once you have to update a service).

Deploy:
Use cf push if you have a manifest.yml file and it is at the same level as your command prompt.

Logs:
To stream the logs: cf logs my App
Otherwise: cf logs my App --recent