Tutorial: Schedule an XS Job

The xsjob file enables you to run a service (for example, an XS JavaScript or an SQLScript) at a scheduled interval.

Prerequisites

• You have access to an SAP HANA system
• You have the privileges granted in the SAP HANA user role sap.hana.xs.admin.roles::JobAdministrator
• You have the privileges granted in the SAP HANA user rolesap.hana.xs.admin.roles::HTTPDestAdministrator

NoteThis tutorial combines tasks that are typically performed by two different roles: the application developer and the database administrator. The developer would not normally require the privileges granted to the  JobAdministratoruser role, the  sap.hana.xs.admin.roles::HTTPDestAdministrator user role, or the  SAP HANA administrator.

Context

In this tutorial, you learn how to schedule a job that triggers an XS JavaScript application that reads the latest value of a share price from a public financial service available on the Internet. You also see how to check that the XS job is working and running on schedule.

To schedule an XS job to trigger an XS JavaScript to run at a specified interval, perform the following steps:

Procedure

1. Create the application package structure that contains the artifacts you create and maintain in this tutorial.
   Create a root package called  yahoo. You use the new  yahoo package to contain the files and artifacts required to complete this tutorial.

   /yahoo/
          .xsapp               // application descriptor
          yahoo.xsjob          // job schedule definition
          yahoo.xshttpdest     // HTTP destination details
          yahoo.xsjs           // Script to run on schedule

2. Write the XS JavaScript code that you want to run at the interval defined in an XS job schedule.
   The following XS JavaScript connects to a public financial service on the Internet to check and download the latest prices for stocks and shares.
   Create an XS JavaScript file called  yahoo.xsjs and add the code shown in the following example:

   function readStock(input) {
       var stock = input.stock;
       
       var dest = $.net.http.readDestination("yahoo", "yahoo");
       var client = new $.net.http.Client();
       var req = new $.web.WebRequest($.net.http.GET, "/d/quotes.csv?f=a&s=" + stock);
   
       client.request(req, dest);
       var response = client.getResponse();
   
       var stockValue;
       if(response.body)
           stockValue = parseInt(response.body.asString(), 10);
   
       var sql = "INSERT INTO stock_values VALUES (NOW(), ?)";
       var conn = $.db.getConnection();
       var pstmt = conn.prepareStatement(sql);
       pstmt.setDouble(1, stockValue);
       pstmt.execute();
       conn.commit();
       conn.close();
   }
   

   Save and activate the changes in the SAP HANA Repository.

   NoteSaving a file in a shared project automatically commits the saved version of the file to the repository, To explicitly commit a file to the repository, right-click the file (or the project containing the file) and choose   Team  Commit  from the context-sensitive popup menu.
3. Create an HTTP destination file using the wizard to provide access to the external service (via an outbound connection).
   Since the financial service used in this tutorial is hosted on an external server, you must create an HTTP destination file, which provides details of the server, for example, the server name and the port to use for HTTP access.

   NoteTo maintain the runtime configuration details using the Web-based  XS Administration Tool you need the privileges granted in the  SAP HANA user role  sap.hana.xs.admin.roles::HTTPDestAdministrator.
   Create a file called  yahoo.xshttpdest and add the following content:

   host = "download.finance.yahoo.com"; 
   port = 80; 

   Save and activate the changes in the SAP HANA Repository.

4. Create the XS job file using the wizard to define the details of the schedule at which the job runs.
   The XS job file uses a  cron-like syntax to define the schedule at which the XS JavaScript must run. This job file triggers the script  yahoo.xsjs on the 59th second of every minute and provides the name  “SAP.DE” as the parameter for the stock value to check.
   Create a file called  yahoo.xsjob and add the following code:

   {
       "description": "Read stock value",
       "action": "yahoo:yahoo.xsjs::readStock",
       "schedules": [
          {
             "description": "Read current stock value",
             "xscron": "* * * * * * 59",
             "parameter": {
                "stock": "SAP.DE"
                }
          }
       ]
   }
   

   Save and activate the changes in the SAP HANA Repository.

5. Maintain the XS job's runtime configuration.
   You maintain details of an XS Job's runtime configuration in the  XS Job Dashboard.
   1. Start the SAP HANA XS Administration Tool.
      The  SAP HANA XS Administration Tool is available on the  SAP HANA XS Web server at the following URL:  http://<WebServerHost>:80<SAPHANAinstance>/sap/hana/xs/admin/.
   2. Maintain the details of the XS job.
      NoteTo maintain details of an XS job using the Web-based  XS Administration Tool you need the privileges granted in the  SAP HANA user role  sap.hana.xs.admin.roles::JobAdministrator.

      You need to specify the following details:

      • User

        The user account in which the job runs, for example, SYSTEM

      • Password

        The password required for user, whose account is used to run the job.

      • Locale

        The language encoding required for the locale in which the job runs, for example, en_US

      • Start/Stop time

        An optional value to set the period of time during which the job runs. Enter the values using the syntax used for the SAP HANA data type LocalDate and LocalTime, for example, 2014-11-05 00:30:00 (thirty minutes past midnight on the 5th of November 2014).

      • Active

        Enable or disable the job schedule

   3. Save the job.
      Choose  Save Job to save and activate the changes to the job schedule.
6. Enable the job-scheduling feature in SAP HANA XS.
   This step requires the permissions granted to the  SAP HANA administrator.

   NoteIt is not possible to enable the scheduler for more than one host in a distributed  SAP HANA XS landscape.
   1. In the XS Job Dashboard set the Scheduler Enabled toggle button to YES.
   Toggling the setting for the  Scheduler Enabled button in the  XS Job Dashboard changes the value set for the  SAP HANA configuration variable   xsengine.ini  scheduler  enabled , which is set in the Configuration tab of the  SAP HANA studio's  Administration perspective.
7. Check the job logs to ensure the XS job is active and running according to the defined schedule.
   You can view the  xsjob logs in the  XS Job Dashboard tab of the  SAP HANA XS Administration Tool.

   NoteTo maintain details of an XS job using the Web-based  XS Administration Tool you need the privileges granted in the  SAP HANA user role  sap.hana.xs.admin.roles::JobAdministrator.

   If the job does not run at the expected schedule, the information displayed in the xsjob logs includes details of the error that caused the job to fail.