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

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.

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

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.

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:

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