BTP - Application Job (Externe API)

Inhaltsverzeichnis

• Einleitung
• Konfiguration
• Communication Arrangement
• Communication System
• Communication User
• Abschluss
• Nutzung
• Autorisierung
• Token
• Einplanung
• Status
• Parameter
• Fazit

Im Artikel letzte Woche hatten wir uns die interne ABAP API angeschaut und wie wir damit Jobs im System starten können. Hast du einen zentralen externen Scheduler um Jobketten zu starten? In so einem Fall solltest du dir die externe API anschauen.

 

Einleitung

Die externe Job API wurde mittlerweile durch SAP bereitgestellt und unterstützt damit das Ökosystem des Application Jobs. Damit kann im System ein Job eingeplant werden und der Status geprüft werden. Viele Unternehmen setzen auf zentrale Scheduler, die meist nicht im SAP System setzen, damit wird eine Schnittstelle zur Einplanung von Jobs benötigt. Mehr Informationen zur Job API (BC_EXT_APPJOB_MANAGEMENT) findest du auf dem Business Accelerator Hub.

 

Konfiguration

Bevor du die API von außen aufrufen kannst, musst du zuerst die Konfiguration vornehmen. Dazu benötigen wir ein Communication Arrangement und einen technischen User, um sich von außen am System anzumelden. In der folgenden Konfiguration gehen wir dieses Mal vom Arrangement über das System zum User.

 

Communication Arrangement

In der App "Communication Arrangements" (F1763) legen wir zuerst über den "New" Button ein neues Customizing für das Szenario SAP_COM_0326 an. Den Arrangement Namen kannst du frei anpassen.

 

Communication System

Im nächsten Schritt drücken wir im Arrangement auf "New", neben dem leeren Arrangement. Weitere Felder müssen wir erst einmal nicht befüllen.

 

Auf dem nun folgenden Popup geben wir dem Communication System einen neuen Namen, der Name kann von dir befüllt werden und kann euren eigenen Regeln folgen. 

 

Im Anschluss landen wir in der App "Communication Systems" (F1762), um die weiteren Einstellungen vorzunehmen. Wichtig ist hier das Flag "Inbound Only", damit definieren wir, dass dieses System nur für die Kommunikation von außen auf das ABAP Environment definiert wird.

 

Im unteren Teil legen wir einen neuen technischen User an, der für die Kommunikation von Außen benötigt wird. Dieser User und dessen Passwort wird im Scheduler hinterlegt. Den Namen kannst du ebenfalls frei vergeben.

 

Über den Button "New User" gelangen wir zur Anlage eines neuen Communication Users.

 

Communication User

In der App "Communication Users" (F1338) definieren wir den Namen des technischen Users, sowie eine Beschreibung. Über den Button "Propose Password" können wir ein zufälliges Passwort generieren und dem User zuweisen lassen.

 

Abschluss

Um die Konfiguration abzuschließen, speichern wir den User, bestätigen den User im Communication System, Speichern das Communication System und befinden uns schließlich wieder im Communication Arrangement. Hier hast du noch die Möglichkeit zur Klassifikation der Nutzung zusätzliche Informationen zum externen Scheduler zur Verfügung zu stellen.

 

Im unteren Bereich findest du Informationen zum API Endpunkt auf deinem System.

https://<SYS-ID>.abap.eu10.hana.ondemand.com/sap/opu/odata/sap/BC_EXT_APPJOB_MANAGEMENT;v=0002

 

Nutzung

Um die API zu testen, verwenden wir die Anwendung Postman, die du kostenlos herunterladen kannst, um damit die Verbindung zu testen.

 

Autorisierung

Für die Autorisierung verwenden wir im Postman einen Ordner, wo wir nur einmal das Basic Verfahren hinterlegen müssen. Grundsätzlich muss sich bei jedem Aufruf an der API autorisiert werden.

 

Token

Bevor wir das Scheduling durchführen können, müssen wir am API Endpunkt einen Token für die POST Aktion holen. Dazu rufen wir den Endpunkt auf und setzen das Headerfeld "x-csrf-token" auf "fetch", so erhalten wir einen neuen Token, den wir für den nächsten Request verwenden können.

 

Den Token findest du im unteren Abschnitt des Postmans, unter dem Tab "Headers". Dazu musst die Anfrage aber auch ausführen.

 

Einplanung

Für das Scheduling müssen wir einige Parameter für die API befüllen.

• JobTemplateName - Hier wird das Template des zu startenden Jobs hinterlegt. Dieses identifiziert den eigentlichen Job und weitere Parameter im Template.
• JobText - Der Text wird später in der "Application Jobs" App angezeigt.
• JobUser - Business User oder technischer User, unter dem die Einplanung im System erfolgt. Ebenfalls werden die Berechtigungen des Users gezogen
• TestModeInd - Soll die Einplanung als Test erfolgen oder soll diese direkt den Job ausführen.
• JobParameterValues - Übergabe der Werte aus Schritt 3 (Parameter), ist vor allem für die Pflichtwerte relevant, die nicht im Template hinterlegt wurden. Mehr zum Aufbau im Abschnitt Parameter.

 

Hinweis: Bis auf das Test-Flag müssen alle Variableninhalte mit Anführungsstrichen übergeben werden.

 

Zum Abschluss müssen wir noch den Token aus dem letzten Schritt der API mitgeben, ansonsten wird unsere Einplanungsabfrage vom System abgelehnt. Dazu unter Headers den Eintrag anlegen und den Token befüllen (Beispielbild):

 

Als Ergebnis erhalten wir den Jobnamen und Jobcount, sowie einen aktuellen Status des Jobs im System. Die Informationen können wir im nächsten Schritt dazu verwenden, die Informationen zum Job abzurufen.

 

Wenn wir nun die App "Application Jobs" im System prüfen, dann finden wir den eingeplanten Job von letzter Woche, sowie den neuen Job der per Postman im System eingeplant und ausgeführt wurde.

 

Status

Möchtest du Informationen zum Status des Jobs im System, weil sich der Job in einer Jobkette befindet, dann solltest du regelmäßig den Endpunkt aufrufen, um den aktuellen Status des Jobs zu prüfen. Folgende Endpunkte stehen zur Verfügung:

• JobStatusGet - Lesen des aktuellen Jobstatus im System, sowie des Returncodes.
• JobinfoGet - Lesen von mehr Informationen wie Start- und Endzeit, Status des Jobs, sowie weiter Informationen zur Anzahl der Schritte im Job.

 

Der Aufruf beider Endpunkte ist recht ähnlich, deshalb hier einmal ein Beispiel für die Konfiguration des Aufrufs:

 

Parameter

Besitzt der Job eine Selektion in Schritt Drei (Parameter), dann müssen die Pflichtfelder von außen mitversorgt werden. Wie die Struktur aussieht oder wie die Felder genau versorgt werden müssen, wird leider aus der Dokumentation nicht klar. Hier hilft nur Debugging des Service Endpunktes, um die Struktur und das Mapping zu finden. Dazu ein kleines Beispielcoding mit den Daten von oben, wie du dir leicht die Übergabestruktur aufbauen kannst:

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 ).

 

Hinweis: Die Ausgabe von LD_XML können wir dann für den Aufruf des Jobs verwenden. Der Parameter erwartet also einen String in Form eines XML.

 

Folgendes XML wird dabei erzeugt, dabei haben wir aber einen Formatter genutzt, um das XML einigermaßen lesbar zu machen:

<?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>

 

Fazit

Die Einplanung von Jobs von außerhalb des Systems, ist genauso wichtig wie die interne ABAP API, aber beinahe fast genau so einfach. Mit dem Artikel solltest du die Konfiguration des Szenarios, sowie die Nutzung der API beherrschen und die grundlegende Einplanung eines Jobs durchführen können.

 

Quellen:
Business Accelerator Hub - External Scheduler
SAP Help - External Job Scheduling Service