This is a test message to test the length of the message box.
Login
BTP Application Job
Created by Software-Heroes

BTP - Application Jobs (External API)

818

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.

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


Included topics:
BTPApplication JobABAP EnvironmentAPI
Comments (0)



And further ...

Are you satisfied with the content of the article? We post new content in the ABAP area every Friday and irregularly in all other areas. Take a look at our tools and apps, we provide them free of charge.


RAP - Deep Action in OData v4

Category - ABAP

In this article we will look at actions with deep structures, how we can create them and pass data to an API endpoint.

05/24/2024

BTP - Business Configuration (Adaptation)

Category - ABAP

What do adjustments to the RAP business object actually look like in the context of the business configuration? More information in this article.

05/17/2024

BTP - Business Configuration (without Transport)

Category - ABAP

How do you actually use the Business Configuration without the transport recording? In this article we clarify whether it is possible.

05/07/2024

BTP - Business Configuration (Usage)

Category - ABAP

Today it's about using the various apps and transporting the business configuration in the ABAP environment.

05/03/2024

BTP - Business Configuration (Creation)

Category - ABAP

This article is about creating maintenance views in the ABAP environment to maintain data and later transport the settings.

04/26/2024