Introduction

• The JITL SAPS4HANAJob and SAPS4HANAScheduleJob template implements an interface to the SAP Job Scheduling Service REST API.

Authentication and Authorization

• The JITL job template makes use of token based SAP authentication with XSUAA.
• This includes the tokens generated covering the scope required to call individual SAP application endpoints. 
  • Required permissions and roles are determined by the SAP application.
  • Calls to different SAP applications and endpoints can require different accounts and credential sets to be used.
• The JITL job template reads SAP authentication tokens from a credential store, preferably using KeePass.

Jobs and Schedules

Jobs and Schedules are managed with JS7.

• A 1:1 mapping applies between a JS7 job & schedule objects and the SAP job & schedule objects.
• SAPS4HANAJob
  • SAP jobs are created on-the-fly by the JS7 JITL job at the point in time of job execution. Accordingly an SAP schedule is created for job parameterization and for immediate one-time execution.
  • SAP jobs and schedules are removed after execution of the JS7 job.
• SAPS4HANAScheduleJob
  • SAP jobs that have already been configured with deactivated schedules are used as templates. The schedules of the SAP jobs contains the job parameterization.
  • SAP schedules are created on-the-fly by the JS7 JITL job at the point in time of job execution as a copy of template schedules.
  • SAP schedules are removed after execution of the JS7 job.

Job Management

• Users can create any number of JS7 jobs and schedules based on the JITL SAPS4HANAJob or SAPS4HANAScheduleJob template.
• Such JS7 jobs can be used in the same workflow and in different workflows.
• A JS7 workflow can include a single job or any number of jobs and additional JS7 - Workflow Instructions.

Operation

• Network
  • JS7 jobs are executed with Agents. For use with SAP jobs the Agent requires an HTTP network connection to SAP S/4 HANA.

  • Network connections can be secured by HTTPS.

    SAP certificates have to be made available to the Agent's truststore.

    Applicability of Mutual Authentication certificates has to be clarified.

• Starting Jobs
  • JS7 jobs are started from JS7 - Orders assigned to the JS7 - Workflows that include the jobs.
    • Orders are created from JS7 - Schedules, typically a few days ahead of execution and are added to the JS7 - Daily Plan.
    • Orders can be added manually from the JOC Cockpit and by use of the JS7 - REST Web Service API.
  • The start of the JS7 job indicates that the corresponding SAP job is running.
• Stopping Jobs
  • JS7 orders can be suspended and cancelled, optionally killing the running process of a job, e.g. by user intervention. For the JS7 JITL SAPS4HANAJob and SAPS4HANAScheduleJob template no kill option applies when cancelling as SAP jobs cannot be killed.
• Parallelism
  • Any number of JS7 jobs based on the JITL SAPS4HANAJob and SAPS4HANAScheduleJob template can be executed at the same time.
  • Parallelism of JS7 jobs based on the JITL SAPS4HANAJob and SAPS4HANAScheduleJob template includes running a number of job instances with the same or with different Agents.
• Mutual Exclusion
  • JS7 offers JS7 - Resource Locks to limit parallel execution of specific jobs. This applies accordingly to jobs based on the JITL SAPS4HANAJob and SAPS4HANAScheduleJob template.

Job Processing

General Processing

• JS7 Jobs and SAP Jobs
  • The JS7 JITL job creates an SAP job on-the-fly with a single schedule for immediate execution.
  • The SAP application specified with the Action Endpoint can be executed synchronously or asynchronously. Both execution modes are handled by the JS7 JITL job in a similar way.
• Job Start
  • An SAP job is started using the SAP REST API request POST /scheduler/jobs that returns a unique jobId and scheduleId.
  • The JS7 JITL job creates a job status file <workflow-name>.<job-label><order-id>.json in the Agent's file system with processing information of the SAP job including the jobId and scheduleId.
    • An additional JITL job SAPS4HANARecoverJob runs periodically and checks any remaining job status files to determine if SAP jobs are still running without a corresponding JS7 JITL job being active.
      • Such a situation can occur if the network connection between Agent and SAP system is interrupted or if the Agent is restarted and the JS7 SAPS4HANAJob is killed.

      • In a situation when a running SAP job is found without a corresponding JS7 JITL job then the SAPS4HANARecoverJob job will remain active until the SAP job has completed and will add the SAP job execution status and log messages to the JS7 job history.

        Update of the JS7 History has to be clarified.

• Check of SAP Job Execution Status
  • The JS7 JITL job repeatedly executes the GET /scheduler/jobs/{jobId}/schedules/{scheduleId}/runs SAP REST API call to retrieve the execution status of the job.
    • If the job is in a running status then checking the job status is repeated within a configurable interval.
    • If the job is completed then the JS7 JITL job retrieves the final execution status and log messages of the SAP job and adds them to the JS7 job history.
  • This check is completed if the SAP system returns the HTTP 404 response code or if the SAP job's runStatus is COMPLETED or UNKNOWN.
  • Once the SAP job been completed:
    • the job execution result and log messages are added to the JS7 JITL job log.
      • A job is considered successful (returnCode 0) unless:
        • the POST /scheduler/jobs SAP REST API call returns a response code different from HTTP 201.
        • the POST /scheduler/jobs SAP REST API call results in a Connection Timeout or Socket Timeout.
    • the SAP job is removed by use of the DELETE /scheduler/jobs/{jobId}) SAP REST API call provided that the previous check results in an HTTP 200 response code.
    • the job status file is removed.

Parameterization

Parameter Types

The following parameter types are available:

1. Parameters required by the JS7 JITL Job:
   • These parameters use the js7 prefix with the corresponding JS7 order variable name.
   • Parameters include:
     • the interval (in seconds) for repeated checks of the SAP job execution status.
2. Parameters required by the SAP Job:
   • These parameters use the js7 prefix with the JS7 order variable name.
   • Parameters include:
     • the name of the SAP job: the job name is created from the JS7 workflow name, Order ID and the label of the JS7 - Job Instruction.
       • JS7 allows a larger scope of Unicode characters for job names, see JS7 - Object Naming Rules.
       • The SAP REST API documentation does not provide details about applicable characters: "Name must not contain special characters or only numbers"
       • Users therefore have to check with their SAP system to determine what characters to use for the JS7 Order Name (freely accessible part of the Order ID) and for the job label in the workflow.
     • the Action Endpoint of the SAP job.
     • the HTTP verb for the Action Endpoint.

       • Possible values include DELETE, PUT, POST, GET

         The JS7 Job Wizard should allow to selection of a value from a list of values.

     • the description of the SAP job (optional).

       Ideally the JS7 job title is used for the SAP job description. This requires clarification as job titles are not forwarded to Agents.

3. Parameters used by the SAP application
   • Such parameters do not use a prefix. The JS7 variable names have to correspond to parameter names used by the SAP application.
   • Parameters are handed over to the SAP REST API as key/value pairs. The prefix js7 must not be used as a key prefix.

Parameter Assignment

• Order Variables
  • The JS7 workflows require order variables to be declared. 
  • Any order variables are available to all jobs in a JS7 workflow.
• Node Arguments
  • Such arguments are used for the occurrence of a job in a JS7 workflow.
    • For constant values, e.g. the HTTP verbs DELETE, PUT, POST, GET a constant assignment can be used.
    • For dynamic values an order variable is assigned the Node Argument.
  • This allows more than one SAPS4HANAJob to be available with the same workflow as Node Arguments are specified from individual order variable assignments.
• As a consequence parameters to an SAP job are assigned by Node Arguments in a JS7 workflow exclusively. The following applies to the above parameter types for SAP jobs:
  • Parameter type 2)
    • Users add constant values to Node Arguments of SAP jobs. Any such arguments use the js7 prefix.
  • Parameter type 3)
    • Users map the names of order variables to the names of Node Arguments.
      • The name of the Node Argument corresponds to the parameter name expected by the SAP application.
      • This excludes use of the js7 prefix for Node Arguments.
  • The only data type supported by SAP for both of the above parameter types is "string". JS7 offers additional data types such as number and Boolean, that cannot be used.