SAP HANA XSA

Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/

Overview

This Universal Task provides the capability to schedule SAP HANA extended application services Jobs (SAP HANA XSA Jobs) from the Universal Automation Center. 

This allows HANA XSA Jobs to start in various ways, including:

  • Time-based, e.g., every business day at 6:00 PM.
  • Event-based, e.g., when a file has arrived in a directory.
  • Task-based, e.g., start the Job when another Task has been finished.

Also, HANA XSA Jobs could be part of a Workflow containing multiple HANA XSA Jobs and other Job types like SAP Tasks, Linux Tasks, Database Tasks, etc.


Process Description:

Goal is to schedule SAP HANA extended application services Jobs using Universal Controller instead of using the "Recurring - Cron" Schedule defined in the SAP HANA Web IDE.

The "Recurring - Cron" Schedule defined in the SAP HANA Web IDE should not be used anymore for scheduling.

To achieve this, the following steps need to be performed: 

  • The XSA Job will be created in the SAP HANA Web IDE in the same way as before, except that the “xscron" parameter will be set to a date in the past. As a result the "Recurring - Cron" Schedule will never be executed.
  • The new Universal Task HANA XSA will add a one-time schedule to the provided HANA XSA Job (Universal Task Parameter XSA Job Name).
  • Optionally a Parameter file can be added to the one-time schedule. The Parameter file can be provided from the Universal Controller script library or dynamically retrieved from the last Job schedule, which has not been scheduled from Universal Controller. 
  • The one-time schedule is automatically executed after launching the Universal Task in Universal Controller
  • Optionally, via the flag "Set RecurringJob Schedules to Inactive", all Job Schedules of this Job of Type "Recurring - Cron" are set to inactive. This avoid that the Job is started via a "Recurring - Cron" Schedule defined in the  SAP HANA Web IDE.
  • The Job is monitored by the Universal Task, while it is running
  • After completion of the task the log-file is available in the Task Output, containing the same information as provided by HANA "job-scheduler-service-dashboard".
  • In case an XSA Job Fails ( "runStatus": "COMPLETED", "runState": "ERROR") a re-run of the Universal Task can be performed, which will add a new one-time schedule to the XSA Job. As the result the XSA Job will run again from the start.

Version Information

Template NameVersion
SAP HANA XSA1.0.2

Refer to Changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Software Requirements for Universal Template and Universal Task

Requires Python 3.7. Tested with the Universal Agent bundled Python distribution.

Software Requirements Universal Agent

Both Windows and Linux agents are supported:

  • Universal Agent for Windows x64 Version 7.2.0.0 and later with python options installed.

  • Universal Agent for Linux Version 7.2.0.0 and later with python options installed.

Software Requirements Universal Controller

Universal Controller Version 7.2.0.0 and later.

Network and Connectivity Requirements

Universal Agent host should be able to establish a connection with:

  • The SAP HANA XSA 
  • The Universal Controller host URL (The Universal Controller Credentials provided in permissions to launch a Universal Controller Task).

Key Features

This Universal Task provides the following main features:

Actions

  • Add a one-time schedule including Parameters to an existing HANA XSA Job. The one-time schedule is to start the HANA XSA Job immediately.
  • Optionally the tasks allow setting for the HANA XSA Job in scope all Job Schedules of Type recurring to inactive  

Authentication

  • Authentication is based on the Credentials of the JobScheduler Service Instance used for the HANA Job Scheduling REST API

Logging

  • For all HANA XSA Job executions, a log file is generated with similar information as in the HANA job-scheduler-service-dashboard
  • The current job status is monitored in a configurable poll interval; e.g., every 60s

Import Universal Template

To use the Universal Template, you first must perform the following steps.

  1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

  2. To import the Universal Template into your Controller, follow the instructions here.

  3. When the files have been imported successfully, refresh the Universal Templates list. The Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the support of this integration. For more information, refer to SAP HANA XSA#Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Input Fields

The input fields for this Universal Extension are described in the following table.

Field

Input type

Default value

Type

Description

Name

RequiredTask NameText

Name of the Task

Agent

OptionalAgent NameChoice

Linux or Windows Universal Agent to execute the SAP Job Scheduler REST API commands

Agent Cluster

OptionalAgent Cluster NameChoice

Optional Agent Cluster for load balancing.

Base URL for Job Scheduler REST API

Required

Base URL of the SAP Job Scheduler REST API

https://<Domain>:<Rest API Port>

Text

The scheduler Base URL has the format: https://<Domain>:<Rest API Port>; e.g., https://hxehost:51029.

The Domain and Rest API Port can be looked up under Routes in the SAP HANA XS Advanced Cockpit.

Set RecurringJob Schedules to Inactive

OptionalTrue | FalseBoolean

If this flag is set, all Job Schedules of this Job of Type recurring are set to inactive. 

Hana XSA Job Name

RequiredName of the HANA XSA JobText

The Name of the HANA XSA Job, which should be scheduled.

The Job name can be looked up in the HANA Job Scheduler Dashboard

DataRequiredTrue | FalseBooleanIf this flag is set, a Parameter file can be selected in the Data (JSON) field.
Copy Data ParameterOptionalTrue | FalseBooleanIf this flag is set, the Job Parameters are dynamically retrieved from the last Job schedule, which has not been scheduled from Universal Controller. 
Data (JSON)Optional

Parameter File in JSON format

{
    "Parameter1": "Val1",
    "Parameter2": "Val2"
}
Script

Visible in case the Field "Copy Data Parameter" is not checked.

data to be passed to the job action endpoint in JSON format when invoked, e.g. {"dataParam": "somevalue"}

Poll Interval

Required60sChoice

[60s, 180s, 360s]

The Universal Task will provide the functionality to poll in a configurable interval the HANA Job Scheduling REST API to retrieve the current Status of the Job and the Job Log file. The Job Log file will be available as task output for further processing.

JobScheduler Credentials

RequiredCredentials of the JobScheduler Service InstanceCredential

Credentials of the JobScheduler Service Instance used to connect to the HANA Job Scheduling REST API.

The JobScheduler Credentials can be looked up under Service Instances in the SAP HANA XS Advanced Cockpit.

Universal Controller REST API Credentials

RequiredUniversal Controller Rest API CredentialsCredential

Universal Controller Rest API Credentials.

Universal Controller URL

RequiredUniversal Controller URLText

Universal Controller URL; for example, https://192.168.88.40/uc

Loglevel

RequiredINFOChoice

Universal Task logging settings [DEBUG | INFO| WARNING | ERROR | CRITICAL].

Task Example

Start a HANA XSA Job

The following Task will set all existing recurring schedules (also called cron type schedules) of the given XSA Job "hxehost_51043_myJob.xsjob" to in-active and adds a one-time schedule to the XSA Job. The one-time schedule is executed immediately. 

By setting all existing recurring schedules of the Job to in-active, it is ensured that this Job is only scheduled by Universal Controller.


Base URL for the Job Scheduler Rest API

The scheduler Base URL has the format: https://<Domain>:<Rest API Port>

The Domain and Rest API Port can be looked up under Routes in the SAP HANA XS Advanced Cockpit.

Example:

  • Mapped Applications: jobscheduler-rest
  • Domain: hxehost
  • Port: 51029



JobScheduler Credentials

The JobScheduler Credentials can be looked up under Service Instances in the SAP HANA XS Advanced Cockpit.

Example:

  • password: Cq79B...
  • user: SBSS_9594...



Universal Tasks Credential Details:

XSA Job definition in HANA WebIDE Console

The following provides an example of an existing HANA XSA Job in the HANA WebIDE Console. 

In this example the "xscron" Parameter has been set to a date in the past ( 2015 ). As a result this Job schedule will never be reached, meaning the Job will not be started anymore via the xscron definition.

Started Task

Once the Universal Task is started in Universal Controller, all existing recurring schedules are set to Inactive and a one-time schedule is added. 

In the screenshot below you can see that the Schedule with the Pattern "Recurring - Cron" has been set to Inactive. This is to avoid the Job starting via a "Recurring - Cron" Schedule.

The one-time schedule starts the Job immediately. 



Finished Task

Once the execution of the One-Time Schedule is finished the One-Time Schedule goes to Inactive. 

Task Output

  • For all HANA XSA Job executions, the Universal Task Output contains similar information as in the HANA job-scheduler-service-dashboard.
  • The current job status is monitored in a configurable poll interval, e.g., every 60s.


Log-file generated in the HANA job-scheduler-service-dashboard:


Universal Task Output

The Universal Task Output contains similar information as in the HANA job-scheduler-service-dashboard.


Exit Codes

The exit codes and related Task Output for this Universal Task are described in the following table.

Task Exit Code

Task Status

Status Classification Description

Task Output

0

Success

Successful Execution

The endpoint has successfully executed the job.

1

Failed

Wrong Jobname: 

Exit Code: 404, Job Not Found

1

Failed

Wrong JobScheduler Credentials: 401, Unauthorized

Exit Code: 401, Unauthorized

1

Failed

Wrong Base URL for Job Scheduler REST API

Exit Code: 404

1

Failed

Run State ERROR

Task Output contains the Error description.

STDOUT and STDERR

STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this Universal Task without notice. Backward compatibility is not guaranteed.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

  • Python code modifications should not be done.
  • Template Modifications
    • General Section
      • "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
    • Universal Template Details Section
      • "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
    • Result Processing Defaults Section
      • Success and Failure Exit codes should not be changed.
      • Success and Failure Output processing should not be changed.
    • Fields Restriction Section
      The setup of the template does not impose any restrictions, However with respect to "Exit Code Processing Fields" section.
      1. Success/Failure exit codes need to be respected.
      2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents:

Document LinkDescription
Universal TemplatesUser documentation for creating, working with and understanding Universal Templates and Integrations.
Universal TasksUser documentation for creating Universal Tasks in the Universal Controller user interface.
Job Scheduler REST API for XS AdvancedSAP Job Scheduler REST API for XS Advanced to the HANA XSA Application.

Changelog

ut-cs-sap-hana-xsa-1.0.2 (2023-12-21)

Support for copying Input Parameters from an existing Job Schedule definition

ut-cs-sap-hana-xsa-1.0.1

Support for Input Parameters

ut-cs-sap-hana-xsa-1.0.0

Initial Version