/
SAP BTP: Application Jobs

SAP BTP: Application Jobs

Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use.

Version Information

Template Name

Extension Name

Version

Status

Template Name

Extension Name

Version

Status

SAP BTP Application Jobs

ue-sap-btp-appjobs

1 (Current 1.1.0)

Fixes and new Features are introduced

‎ ‎ ‎ 

Overview

SAP Business Technology Platform (SAP BTP) is a comprehensive, cloud‑based environment that enables organizations to build, deploy, and manage modern applications with agility and scalability.

This integration enables users to schedule, trigger, and monitor their SAP BTP Application Jobs directly from UAC.

Key Features

Feature

Description

Feature

Description

Job Scheduling and Triggering

Trigger and Schedule an SAP BTP Application Job with the capability to provide optional configuration settings.

Real‑Time Job Monitoring

Provides continuous feedback displaying detailed Job and Step status updates throughout the execution lifecycle.

‎ ‎

Requirements

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

Area

Details

Area

Details

Python Version

Requires Python 3.11, Tested with Agent bundled python distribution.

Universal Agent Compatibility

Compatible with Universal Agent for Windows x64 and version >= 7.6.0.0.

Compatible with Universal Agent for Linux and version >= 7.6.0.0.

Universal Controller Compatibility

Universal Controller Version >= 7.6.0.0.

SAP BTP Compatibility

This integration depends on Communication Arrangement: External Scheduler - Application Job Scheduling Integration via BC_EXT_APPJOB_MANAGEMENT API, version 2.

‎ ‎ 

Supported Actions

Action: Run Taskflow

The “Run Job” Action allows a Job to be triggered or scheduled. To execute the Action, the necessary Credentials, Service URL, and Job Template must be provided.

Optionally, the Job’s title can be specified using the Job Name. If omitted, the title defined in the Job Template is used.

The user on whose behalf the Job will run can also be specified. If not provided, the communication user is used by default.

Additionally, you can provide parameters to customize the job execution. Parameters are configured in YAML format and can be provided either directly in a text field or via a saved Script. Use the “Get Parameter Data” Action first to discover available parameters for your job template.

You can also configure whether the task should only initiate the Job or wait until a final success or failure state is reached. The latest Job and Step status retrieved can be included in the Extension Output.

During task instance execution, the Job Name (ID), Job Run Count, Status, and Last Updated On are displayed as output fields.

Configuration examples

Example: Trigger Job

The configuration example below shows a task configuration for a Job Run with minimal configuration. The Job simply gets triggered, and upon successful triggering, the UAC Task Instance completes with success. The Task Instance will not wait for Job completion or failure.

 

Example: Run and monitor a Job

The configuration example below shows a task configuration for a Job Run, using a custom Job name and executed by a different user. Once the Job is successfully triggered, the task instance enters a wait state and monitors the Job until it either completes or fails. Upon completion, the info from the Job monitor, the status from the Job, and its individual Steps are displayed according to the selected output options.

Example: Run a Job with Parameters

The example below shows a task configuration for running a Job with parameters. Parameters are provided in YAML format, which can be obtained first by running the "Get Parameter Data" Action for your job template. Once the Job is successfully triggered, the task waits while monitoring the Job until it either completes or fails. After completion, information from the Job monitor, the overall Job status, and the status of individual Steps is displayed according to the selected output options.

 

Action Output

Output Type

Description

Examples

Output Type

Description

Examples

EXTENSION

The extension output provides the following information:

  • exit_code, status_description: General info regarding the Task Instance execution. For more information, refer to the exit code table.

  • invocation.fields: The Task Instance configuration.

  • result.job_status: Type : JSON Object. Shows the latest status and info of the Job.

  • result.step_status: Type : JSON Object. Shows the latest status and info of the Job’s Steps. The contents of this JSON Object may vary depending on the number of Steps the Job has.

  • result.errors:List of errors that might have occurred during execution.

Successful triggering and monitoring of a Job
{     "exit_code": 0,     "status_description": "Task executed successfully",     "invocation": {         "extension": "ue-sap-btp-appjobs",         "version": "1.1.0",         "fields": {             "action": "Run Job",             "sap_credential": {                 "user": "STONEBRANCH",                 "password": "****",                 "token": "****",                 "key_location": null,                 "passphrase": "****"             },           "url_service": "https://my*****.scmibp1.ondemand.com/",             "job_template": "SB_QA_Template_Step_6",             "job_name": "Lunched Job Step 6",           "job_user": "*************",             "wait_for_success_or_failure": true,             "polling_interval": 5,             "max_number_of_polls": 0,             "stdout_options": [                 "Job Status",                 "Step Status",                 "Job Monitor"             ],             "extension_output_options": [                 "Job Status",                 "Step Status"             ],             "job_name_uid": null,             "job_run_count": null         }     },     "result": {         "job_status": {             "JobName": "5D2AABB034F61FE086EDE29830DC6EBC",             "JobRunCount": "KofppKHq",             "JobStatus": "F",             "ReturnCode": 0         },         "step_status": [             {                 "StepCount": 1,                 "StepStatus": "F",                 "StepStartDateTime": "/Date(1744882437000)/",                 "StepAppRC": 0             },             {                 "StepCount": 2,                 "StepStatus": "F",                 "StepStartDateTime": "/Date(1744882444000)/",                 "StepAppRC": 0             },             {                 "StepCount": 3,                 "StepStatus": "F",                 "StepStartDateTime": "/Date(1744882450000)/",                 "StepAppRC": 0             },             {                 "StepCount": 4,                 "StepStatus": "F",                 "StepStartDateTime": "/Date(1744882456000)/",                 "StepAppRC": 0             },             {                 "StepCount": 5,                 "StepStatus": "F",                 "StepStartDateTime": "/Date(1744882461000)/",                 "StepAppRC": 0             },             {                 "StepCount": 6,                 "StepStatus": "F",                 "StepStartDateTime": "/Date(1744882466000)/",                 "StepAppRC": 0             }         ]     } }
Failed Execution
{     "exit_code": 1,     "status_description": "Execution Failed: The job has been cancelled.",     "invocation": {         "extension": "ue-sap-btp-appjobs",         "version": "1.1.0",         "fields": {             "action": "Run Job",             "sap_credential": {                 "user": "STONEBRANCH",                 "password": "****",                 "token": "****",                 "key_location": null,                 "passphrase": "****"             },           "url_service": "https://my******.scmibp1.ondemand.com/",             "job_template": "SB_QA_Template_Step_6",             "job_name": "Lunched Job Step 6",           "job_user": "************",             "wait_for_success_or_failure": true,             "polling_interval": 5,             "max_number_of_polls": 0,             "stdout_options": [                 "Job Status",                 "Step Status",                 "Job Monitor"             ],             "extension_output_options": [                 "Job Status",                 "Step Status"             ],             "job_name_uid": null,             "job_run_count": null         }     },     "result": {         "job_status": {             "JobName": "5D2AABB034F61FE086EDE7729C6E2EBC",             "JobRunCount": "bWPfATIb",             "JobStatus": "C",             "ReturnCode": 0         },         "step_status": [             {                 "StepCount": 1,                 "StepStatus": "A",                 "StepStartDateTime": "/Date(1744882500000)/",                 "StepAppRC": 0             },             {                 "StepCount": 2,                 "StepStatus": "P",                 "StepStartDateTime": null,                 "StepAppRC": 0             },             {                 "StepCount": 3,                 "StepStatus": "P",                 "StepStartDateTime": null,                 "StepAppRC": 0             },             {                 "StepCount": 4,                 "StepStatus": "P",                 "StepStartDateTime": null,                 "StepAppRC": 0             },             {                 "StepCount": 5,                 "StepStatus": "P",                 "StepStartDateTime": null,                 "StepAppRC": 0             },             {                 "StepCount": 6,                 "StepStatus": "P",                 "StepStartDateTime": null,                 "StepAppRC": 0             }         ]     } }

STDOUT

Depending on the configuration of field Output Options and type of workload running, STDOUT can provide the Job Monitor, Job Status and/or Step Status.

 

STDERR

Shows the logs from the Task Instance execution. The verbosity is controlled by the Task configuration Log Level.

 

Action: Get Parameter Data

The "Get Parameter Data" Action is used to discover the available parameters for a specific Job Template. This action queries the SAP BTP system and retrieves the parameter structure, which can then be used to configure the "Run Job" action with parameters.

This action is typically the first step before running a job with parameters. It provides you with:

  • The exact parameter IDs required for YAML configuration

  • Parameter names and types

  • The structure for multi-step jobs

  • Empty templates ready to be filled with values

To execute this action, you must provide the necessary Credentials, Service URL, and select the Job Template you want to query.

The parameter structure is returned in YAML format via STDOUT, which can be directly copied and used as a template for the "Run Job" action.

Configuration examples


Example: Get Parameter Data for a Job Template

The configuration example below shows a task configuration for retrieving parameter data. The task queries the selected Job Template and returns the parameter structure in YAML format.

‎

Action Output

Output Type

Description

Examples

Output Type

Description

Examples

EXTENSION

The extension output provides the following information:

  • exit_code, status_description: General info regarding the Task Instance execution. For more information, refer to the exit code table.

  • invocation.fields: The Task Instance configuration.

  • result: Type : JSON Object. Contains the parameter template for the selected Job Template.

  • result.errors:List of errors that might have occurred during execution.

Successful Execution
{ "exit_code": 0, "status_description": "Task executed successfully", "invocation": { "extension": "ue-sap-btp-appjobs", "version": "1.1.0", "fields": { "action": "Get Parameter Data", "sap_credential": { "user": "{user}", "password": "****", "token": "****", "key_location": null, "passphrase": "****" }, "url_service": "https://{url}.scmibp1.ondemand.com/", "job_template": "SB_QA_Template_Complex_Step_1", "job_name": null, "job_user": null, "job_parameters_type": null, "job_parameters": null, "job_parameter_script": null, "wait_for_success_or_failure": false, "polling_interval": 0, "max_number_of_polls": 0, "stdout_options": null, "extension_output_options": null, "job_name_uid": null, "job_run_count": null } }, "result": { "version": "1.0.0", "steps": [ { "step": 1, "parameters": [ { "id": "P_AREA 16619728C455C3843E3DF9E8012152", "name": "Planning Area", "kind": "Parameter", "value": "TEST" }, { "id": "P_COMM 16619728C455C3843E3DF9E8012152", "name": "Comment", "kind": "Parameter", "value": "" }, { "id": "P_CPDATE16619728C455C3843E3DF9E8012152", "name": "Date", "kind": "Parameter", "value": "00000000" }, { "id": "P_CPMETH16619728C455C3843E3DF9E8012152", "name": "Define By", "kind": "Parameter", "value": "E" }, { "id": "P_CPTIME16619728C455C3843E3DF9E8012152", "name": "Time", "kind": "Parameter", "value": "000000" }, { "id": "P_CPTZ 16619728C455C3843E3DF9E8012152", "name": "Time Zone", "kind": "Parameter", "value": "" }, { "id": "P_FLTID 16619728C455C3843E3DF9E8012152", "name": "Planning Filter", "kind": "Integer Parameter", "value": "" }, { "id": "P_JOBNO 16619728C455C3843E3DF9E8012152", "name": "Job Number", "kind": "Integer Parameter", "value": "" }, { "id": "P_OPID 16619728C455C3843E3DF9E8012152", "name": "Operator", "kind": "Integer Parameter", "value": "1" }, { "id": "P_OPTYP 16619728C455C3843E3DF9E8012152", "name": "Operator Type", "kind": "Parameter", "value": "" }, { "id": "P_SHARE 16619728C455C3843E3DF9E8012152", "name": "Share With", "kind": "Parameter", "value": "" }, { "id": "S_RCODE 16619728C455C3843E3DF9E8012152", "name": "Reason Code", "kind": "Select-Options", "values": [ { "operation": "", "value": "", "value_to": "" } ] }, { "id": "S_VERS 16619728C455C3843E3DF9E8012152", "name": "Version", "kind": "Select-Options", "values": [ { "operation": "equal to", "value": "1", "value_to": "" } ] } ] } ] } }

STDOUT

Displays the parameter template in YAML format. This output can be directly copied and used as a template for configuring job parameters.

Successful Execution
version: 1.0.0 steps: - step: 1 parameters: - id: P_AREA 16619728C455C3843E3DF9E8012152 name: Planning Area kind: Parameter value: TEST - id: P_COMM 16619728C455C3843E3DF9E8012152 name: Comment kind: Parameter value: '' - id: P_CPDATE16619728C455C3843E3DF9E8012152 name: Date kind: Parameter value: '00000000' - id: P_CPMETH16619728C455C3843E3DF9E8012152 name: Define By kind: Parameter value: E - id: P_CPTIME16619728C455C3843E3DF9E8012152 name: Time kind: Parameter value: '000000' - id: P_CPTZ 16619728C455C3843E3DF9E8012152 name: Time Zone kind: Parameter value: '' - id: P_FLTID 16619728C455C3843E3DF9E8012152 name: Planning Filter kind: Integer Parameter value: '' - id: P_JOBNO 16619728C455C3843E3DF9E8012152 name: Job Number kind: Integer Parameter value: '' - id: P_OPID 16619728C455C3843E3DF9E8012152 name: Operator kind: Integer Parameter value: '1' - id: P_OPTYP 16619728C455C3843E3DF9E8012152 name: Operator Type kind: Parameter value: '' - id: P_SHARE 16619728C455C3843E3DF9E8012152 name: Share With kind: Parameter value: '' - id: S_RCODE 16619728C455C3843E3DF9E8012152 name: Reason Code kind: Select-Options values: - operation: '' value: '' value_to: '' - id: S_VERS 16619728C455C3843E3DF9E8012152 name: Version kind: Select-Options values: - operation: equal to value: '1' value_to: ''

STDERR

Shows the logs from the Task Instance execution. The verbosity is controlled by the Task configuration Log Level.

 

Importable Configuration Examples

This integration provides importable configuration examples along with their dependencies, grouped as Use Cases to better describe end to end capabilities. 

These examples aid in allowing task authors to get more familiar with the configuration of tasks and related Use Cases. Such tasks should be imported in a Test system and should not be used directly in production. 

Initial Preparation Steps

  • STEP 1: Go to Stonebranch Integration Hub download integration with name "SAP BTP: Application Jobs" and extract the archive in a local directory.

  • STEP 2: Locate and import the "SAP BTP Application Jobs" integration to the target Universal Controller. For more information refer to the How To section in this document.

  • STEP 3: Inside directory named "configuration_examples" you will find a list of definition zip files. Upload them one by one respecting the order presented below, by using the "Upload" functionality of Universal Controller:

    1. variables.zip

    2. credentials.zip

    3. tasks.zip

    4. workflows.zip

  • The order indicated above ensures that the dependencies of the imported entities need to be uploaded first. 

  • All imported entities are prefixed with UC1.

  • STEP 4: Update the uploaded UAC Credential entity, with the proper SAP Communication User and Password.

  • STEP 5: Update the UAC global variables introduced with the "variables.zip" definition file. Their name is prefixed with "ue_sap_btp_appjobs". Review the description of the variables as they include information on how should be populated.

 

 

How "Upload" Definition Files to a Universal Controller

 The "Upload" functionality of Universal Controller allows Users to import definitions exported with the "Download" functionality.

Login to Universal Controller and:

  • STEP 1: Click on "Tasks" → "All Tasks"

  • STEP 2: Right click on the top of the column named "Name"

  • STEP 3: Click "Upload..."

In the pop-up "Upload..." dialogue:

  • STEP 1: Click "Choose File".

  • STEP 2: Select the appropriate zip definition file and click "Upload".

  • STEP 3: Observe the Console for possible errors.

Use Case 1: Trigger Job, wait to complete, and print results

Description

This workflow is designed to execute a Job on SAP Business Technology Platform (BTP) and present the results in a clear, human-readable format using a Linux-based task. It simplifies the process of interpreting job executions by automatically collecting the jobs output. The tasks configured demonstrate the following capabilities among others:

  • Integration with SAP BTP: Seamless execution of jobs on SAP Business Technology Platform from within the workflow.

  • Result Processing: Presentation of the SAP Task Instance Output in a more human readable format using:

    • Retrieval of EXTENSION Output (JSON) from SAP BTP task

    • Definition of variables as Task Instance actions. Variables are set at the scope of the Workflow. UAC functions are used as well.

    • Usage of the above variables for follow-up task instances to print information around the executed SAP Job. 

The components of this Use Case are described below:

  1. "UC1: Run SAP BTP Job" - This is the starting task of the workflow. It triggers the execution of the defined job on the target product from SAP BTP. A list of variables are set on this task that are later evaluated on (4).

  2. "Successful Job Execution" - When the exit code of "UC1: Run SAP BTP Job" is 0.

  3. "Failed Job Execution" -  When the exit code of "UC1: Run SAP BTP Job" is 1.

  4. "UC1: Print SAP BTP Job Result" - These tasks handle the formatting and printing of the results retrieved from the SAP BTP job.

How to Run

Execution Steps:

  • STEP 1: Launch Workflow "UC1: Run SAP BTP Job and Print Results".

  • STEP 2 (OPTIONAL): To simulate a failed task scenario, you may cancel the running "UC1: Run SAP BTP Job" Task Instance, which will in turn cancel the associated job. After cancellation, "Force Finish" the task instance to allow the workflow to move forward. 

  • STEP 3: Review the outputs of the task instances for "UC1: Print SAP BTP Job Result" task.

Expected Results:

  • Job has been scheduled and executed successfully (or cancelled if STEP 2 (OPTIONAL) is followed).

  • The output of "UC1: Print SAP BTP Job Result" task instance successfully reflects information related to the executed Job.

 

Input Fields

Name

Type

Description

Version Information

Name

Type

Description

Version Information

Action

Choice

The action performed upon the task execution.

  • Run Job (default)

  • Get Parameter Data

Modified in 1.1.0

SAP Credentials

 

Credential

The communication user Credentials for the specific target product (e.g., S/4HANA or IBP) in the BTP system.

The Credentials definition should be as follows:

  • User as "Runtime User".

  • User Password as "Runtime Password".

Introduced in 1.0.0

URL Service

Large Text

The service URL for the specific target product (e.g., S/4HANA or IBP).

Example URL: https://my******-api.scmibp1.ondemand.com

Introduced in 1.0.0

Job Template

Dynamic Choice

The Job Template that is used for executing the task in the target product.

This is a Dynamic Choice field populated with the names of all available Job Templates from the selected target product.

Introduced in 1.0.0

Job Name

Text

The Job Title that appears in the SAP Application Jobs UI. When used, it allows the Job to have a specific title. Otherwise, the default behavior of SAP is to set the title to the Job Template used for executing this Job.

Introduced in 1.0.0

Job User

Text

The User related to Job execution. If not provided, then the communications user provided in the SAP Credentials field will be used for the Job execution.

Introduced in 1.0.0

Job Parameters Input Type

Choice

Select how to provide job parameters:

  • "-- None --" (default) - No parameters will be provided

  • "YAML Text Field" - Enter parameters directly in YAML format

  • "Script Field" - Reference a saved Script containing YAML parameters

Note: To discover available parameters for your job template, use the "Get Parameter Data" Action first.

Introduced in 1.1.0

Job Parameters (YAML)

Large Text

The YAML structure defines parameters for each step in the job template.

Supported parameter types:

Text Parameters: Free-form text input
- id: "P_AREA 16619728C455C3843E3DF9E8012152"   name: "Planning Area"   kind: "Parameter"   value: "Sales North"
Integer Parameters: Numeric inputs (provided as strings)
- id: "P_MAX 16619728C455C3843E3DF9E8012152"   name: "Max Jobs"   kind: "Integer Parameter"   value: "10"
Checkbox Parameters: Boolean flags
- id: "P_CHK 16619728C455C3843E3DF9E8012152" name: "Enable Feature" kind: "Checkbox" value: "X" # "X" = checked, "" = unchecked
Select-Options: Multi-value parameters with operations
- id: "S_VERS 16619728C455C3843E3DF9E8012152" name: "Version" kind: "Select-Options" values: - operation: "equal to" value: "1" - operation: "between" value: "10" value_to: "20" # Supported operations: # - equal to # - not equal to # - between # - not between # - greater than # - greater than or equal to # - less than # - less than or equal to # - contains # - does not contain # - starts with # - does not start with # - not greater than # - not greater than or equal to # - not less than # - not less than or equal to

Additional data types, including dates and times, may be represented using the parameter types listed above, provided they adhere to the appropriate formatting provided by SAP.

Note for Optional parameters: If a parameter is not needed, omit it entirely from the YAML rather than leaving it with an empty value.

This field appears when Job Parameters Input Type is set to "YAML Text Field".

Introduced in 1.1.0

Job Parameter (Script)

Script

Reference to a saved Script containing YAML-formatted job parameters.

Using a Script is recommended for:

  • Reusable parameter configurations

  • Complex multi-step jobs

  • Version-controlled parameter sets

This field appears when Job Parameters Input Type is set to "Script Field".

Introduced in 1.1.0

Extension Output Options

Choice

The content of the Extension Output can be controlled with the following options:

  • “Job Status”: The latest status and info of the scheduled Job.

  • “Step Status”: The latest status and info for each of the Steps of the scheduled Job.

Multiple options can be selected.

Introduced in 1.0.0

STDOUT Options

Choice

The content of the STDOUT can be controlled with the following options:

  • “Job Monitor”: This option provides a change-status log throughout the execution of the Job that also includes Step status changes.

  • “Job Status”: The latest retrieved status and info of the scheduled Job.

  • “Step Status”: The latest retrieved status and info for each of the Steps of the scheduled Job.

Multiple options can be selected.

Introduced in 1.0.0

Wait For Success Or Failure

Boolean

If selected, the task will continue running until the Job reaches Success or Failure:

  • Success Execution States: "FINISHED"

  • Failed Execution States: “FAILED”, "ABORTED", "CANCELLED", "USER ERROR"

Introduced in 1.0.0

Polling Interval (sec)

Integer

The polling interval in seconds for the activity/status check.

Defaults to 60 seconds.

Required when Wait for Success or Failure is checked.

Introduced in 1.0.0

Max Number Of Polls

Integer

Maximum number of polls. Can be used to control the approximate expected duration of the Task Instance (along with Polling Interval (sec)).

If this field is left empty, the Task Instance will poll indefinitely, checking whether the SAP BTP Job is completed (either with success or with a failure). If the Maximum Number of Polls is reached while the Job is still running, the exit code of the task instance will be 40, completing with failure.

Available if Wait for Success or Failure is checked.

Introduced in 1.0.0

Output Fields

The following output-only fields provide better visibility during the execution of Universal Task Instances.

Field

Type

Description

Version Information

Field

Type

Description

Version Information

Job Name (ID)

Text

The unique identifier assigned to the SAP BTP Job.

Introduced in 1.0.0

Job Run Count

Text

A unique identifier associated with the specific execution instance of the Job.

Introduced in 1.0.0

Job Status

Text

The latest retrieved status of the Job.

Introduced in 1.0.0

Last Update On

Text

Date and time when the last update occurred (Agent Local Time).

Introduced in 1.0.0

‎ ‎

Environment Variables

Environment Variables can be set from the Environment Variables task definition table. The following environment variables can affect the behavior of the extension.

Environment Variable Name

Description

Version Information

Environment Variable Name

Description

Version Information

UE_HTTP_TIMEOUT

Specifies the timeout (in seconds) for HTTP requests made by the Task Instance. A higher value allows for slower responses, while a lower value enforces stricter time constraints. If not set, a default of 60 seconds is used. When a timeout happens, the Task Instance ends in failure.

Introduced in 1.0.0

‎ ‎

Cancellation and Rerun

  • If the Task Instance is cancelled, the Job is also cancelled on the specific target product in the SAP BTP system.

  • If the Task Instance is rerun, a new Job will be scheduled from the same Job Template. The Job Name (ID) and Job Run Count will be updated.

Dynamic Commands

Dynamic Command “Abort Job” is available in the “Running” state of the task instance. It is used to forcefully terminate and fail the scheduled Job.

Exit Codes

Exit Code

Status

Status Description

Meaning

Exit Code

Status

Status Description

Meaning

0

Success

“Task executed successfully.“

Successful Execution

1

Failure

“Execution Failed: <<Error Description>>”

Generic Error. Raised when not falling into the other Error Codes.

20

Failure

“Data Validation Error: <<Error Description>>“

Input fields validation error.