BTP - Application Jobs (External API)
How do I start a job from outside the system? In this article you will learn more about the Application Job's external scheduler API.
Table of contents
In last week's article we looked at the internal ABAP API and how we can use it to start jobs in the system. Do you have a central external scheduler to start job chains? In such a case, you should look at the external API.
Introduction
The external job API has now been provided by SAP and thus supports the application job ecosystem. This allows a job to be scheduled in the system and the status checked. Many companies rely on central schedulers, which are usually not in the SAP system, so an interface is required for scheduling jobs. You can find more information about the Job API (BC_EXT_APPJOB_MANAGEMENT) on the Business Accelerator Hub.
Configuration
Before you can call the API from outside, you must first configure it. To do this, we need a communication arrangement and a technical user to log in to the system from outside. In the following configuration, this time we go from the arrangement to the system to the user.
Communication Arrangement
In the “Communication Arrangements” app (F1763) we first create a new customizing for the SAP_COM_0326 scenario using the “New” button. You can freely customize the arrangement name.
Communication System
In the next step we press "New" in the arrangement, next to the empty arrangement. We don't need to fill in any other fields at first.
On the popup that follows, we give the communication system a new name. The name can be filled by you and can follow your own rules.
We then end up in the “Communication Systems” app (F1762) to make the further settings. What is important here is the “Inbound Only” flag, with this we define that this system is only defined for communication from outside to the ABAP environment.
In the lower part we create a new technical user that is required for external communication. This user and his password are stored in the scheduler. You can also assign the name freely.
Using the “New User” button we can create a new communication user.
Communication User
In the “Communication Users” app (F1338) we define the name of the technical user and a description. Using the “Propose Password” button we can generate a random password and assign it to the user.
Completion
To complete the configuration, we save the user, confirm the user in the communication system, save the communication system and finally find ourselves back in the communication arrangement. Here you also have the option of providing additional information about the external scheduler to classify usage.
In the lower area you will find information about the API endpoint on your system.
https://<SYS-ID>.abap.eu10.hana.ondemand.com/sap/opu/odata/sap/BC_EXT_APPJOB_MANAGEMENT;v=0002
Usage
To test the API, we use the Postman application, which you can download for free to test the connection.
Authorization
For authorization we use a folder in Postman where we only have to store the basic procedure once. Basically, you have to be authorized every time you call the API.
Token
Before we can do the scheduling, we need to get a token for the POST action at the API endpoint. To do this, we call the endpoint and set the header field "x-csrf-token" to "fetch", so we get a new token that we can use for the next request.
You can find the token in the bottom section of Postman, under the "Headers" tab. To do this you also have to execute the request.
Scheduling
For scheduling we need to fill some parameters for the API.
- JobTemplateName - The template of the job to be started is stored here. This identifies the actual job and other parameters in the template.
- JobText - The text will later be displayed in the "Application Jobs" app.
- JobUser - Business user or technical user under which scheduling takes place in the system. The user's authorizations are also taken into account
- TestModeInd - Should the scheduling be done as a test or should it execute the job directly.
- JobParameterValues - Transfer of the values from step 3 (parameters), is particularly relevant for the mandatory values that were not stored in the template. More about the structure in the Parameters section.
Hint: Except for the test flag, all variable contents must be passed with quotation marks.
Finally, we have to provide the token from the last step of the API, otherwise our scheduling query will be rejected by the system. To do this, create the entry under Headers and fill the token (example image):
As a result, we receive the job name and job count, as well as the current status of the job in the system. We can use the information in the next step to retrieve the information about the job.
If we now check the “Application Jobs” app in the system, we will find the scheduled job from last week, as well as the new job that was scheduled and executed in the system via Postman.
Status
If you want information about the status of the job in the system because the job is in a job chain, you should regularly call the endpoint to check the current status of the job. The following endpoints are available:
- JobStatusGet - Reading the current job status in the system as well as the return code.
- JobinfoGet - Reading more information such as start and end time, status of the job, as well as further information about the number of steps in the job.
The call of both endpoints is quite similar, so here is an example of how to configure the call:
Parameter
If the job has a selection in step three (parameters), then the mandatory fields must be supplied from outside. Unfortunately, the documentation does not make it clear what the structure looks like or exactly how the fields have to be supplied. The only thing that helps here is debugging the service endpoint to find the structure and mapping. Here is a small sample code with the data from above on how you can easily set up the transfer structure:
DATA lt_parameters TYPE cl_apj_rt_api=>tt_job_parameter_value.
DATA ld_xml TYPE string.
lt_parameters = VALUE cl_apj_rt_api=>tt_job_parameter_value(
( name = 'TEXT' t_value = VALUE #( ( sign = 'I' option = 'EQ' low = 'Planned Job' ) ) )
( name = 'COUNTRY' t_value = VALUE #( ( sign = 'I' option = 'BT' low = 'DE' high = 'EN' ) ) )
( name = 'R_TEXT' t_value = VALUE #( ( sign = 'I' option = 'EQ' low = abap_false ) ) )
( name = 'R_LAND' t_value = VALUE #( ( sign = 'I' option = 'EQ' low = abap_true ) ) )
( name = 'TEST' t_value = VALUE #( ( sign = 'I' option = 'EQ' low = abap_false ) ) ) ).
CALL TRANSFORMATION id
SOURCE values = lt_parameters
RESULT XML ld_xml.
out->write( ld_xml ).
Hint: We can then use the output of LD_XML to call the job. The parameter therefore expects a string in the form of XML.
The following XML is generated, but we used a formatter to make the XML somewhat readable:
<?xml version="1.0" encoding="utf-16"?>
<asx:abap
xmlns:asx="http://www.sap.com/abapxml" version="1.0">
<asx:values>
<VALUES>
<item>
<NAME>TEXT</NAME>
<T_VALUE>
<item>
<SIGN>I</SIGN>
<OPTION>EQ</OPTION>
<LOW>Planned Job</LOW>
<HIGH/>
</item>
</T_VALUE>
</item>
<item>
<NAME>COUNTRY</NAME>
<T_VALUE>
<item>
<SIGN>I</SIGN>
<OPTION>BT</OPTION>
<LOW>DE</LOW>
<HIGH>EN</HIGH>
</item>
</T_VALUE>
</item>
<item>
<NAME>R_TEXT</NAME>
<T_VALUE>
<item>
<SIGN>I</SIGN>
<OPTION>EQ</OPTION>
<LOW/>
<HIGH/>
</item>
</T_VALUE>
</item>
<item>
<NAME>R_LAND</NAME>
<T_VALUE>
<item>
<SIGN>I</SIGN>
<OPTION>EQ</OPTION>
<LOW>X</LOW>
<HIGH/>
</item>
</T_VALUE>
</item>
<item>
<NAME>TEST</NAME>
<T_VALUE>
<item>
<SIGN>I</SIGN>
<OPTION>EQ</OPTION>
<LOW/>
<HIGH/>
</item>
</T_VALUE>
</item>
</VALUES>
</asx:values>
</asx:abap>
Conclusion
Scheduling jobs from outside the system is just as important as the internal ABAP API, but almost as easy. With the article you should be able to configure the scenario, use the API and carry out the basic scheduling of a job.
Sources:
Business Accelerator Hub - External Scheduler
SAP Help - External Job Scheduling Service
