BTP - Application Job (Exit Check)

Inhaltsverzeichnis

• Einleitung
• Anlage
• Methoden
• CHECK_AND_ADJUST
• INITIALIZE
• GET_DYNAMIC_PROPERTIES
• CHECK_AUTHORIZATIONS
• CHECK_START_CONDITION
• Weitere Methoden
• Komplettes Beispiel
• Fazit

Im letzten Artikel hatten wir uns mit der Anlage des Application Jobs beschäftigt und unseren ersten lauffähigen Job gebaut. Dabei sind uns bereits die ersten Exits im Job-Catalog aufgefallen. Diese wollen wir uns in diesem Artikel einmal genauer ansehen und was wir damit machen können.

 

Einleitung

Nach der Anlage des Job-Katalogs landen wir im Formular und das Objekt steht in den ABAP Development Tools zur Verfügung. Im oberen Abschnitt finden wir unsere Ausführungsklasse, in der die Parameter und die Ausführung definiert ist.

 

Im unteren Abschnitt stehen drei Exits zur Verfügung für Prüfungen, Wertehilfen und Benachrichtigungen. In diesem Artikel werden wir dir die Prüfungen näher vorstellen.

 

Anlage

Die Prüfungen kümmern sich um die Validierung der Eingabeparameter bei der Einplanung des Jobs und geben dem User Feedback in Form von Meldungen, wenn falsche, leere oder abweichende Werte eingegeben werden. Um nun die Prüfung zu implementieren, gibt es zwei Weg:

1. Neuanlage einer Prüfklasse
2. Hinterlegen einer bestehenden Klasse

 

Beim zweiten Weg, kann über den "Browse"-Button oder den Content Assist (STRG + Leertaste) die Klasse hinzugefügt werden. Beim ersten Weg reicht ein Klick auf den entsprechenden Exit-Namen, um den Wizard für die Anlage der Klasse zu starten.

 

Dort hinterlegen wir nun den Namen der Klasse und die Beschreibung und schließen die Generierung ab. Die Klasse wird im System angelegt, hat aber keinerlei Implementierungen oder Interfaces.

 

Daher sollte es im Job-Katalog zu einer Fehlermeldung kommen, die leider nicht sehr spezifiziert ist, sondern nur die Meldung: "Check class ... is invalid" ausgibt. Im Grunde fehlt nun das entsprechende Interface in der Klasse, um die Prüfungen zu implementieren. In der Vergangenheit wurde das Interface IF_APJ_JT_CHECK genutzt, dieses ist mittlerweile aber Deprecated.

 

Deshalb verwenden wir das neue Interface IF_APJ_JT_CHECK_20, um die Prüfungen zu implementieren. Nach der Implementierung wird dir auffallen, dass der Quick Fix (STRG + 1) für das Interface nicht funktioniert. Dies liegt daran, dass die Methoden im Interface per DEFAULT IGNORE implementiert wurden. Entsprechend sieht unsere Klasse nun auch leerer aus:

CLASS zcl_bs_demo_job_adt_chk DEFINITION PUBLIC FINAL CREATE PUBLIC.
  PUBLIC SECTION.
    INTERFACES if_apj_jt_check_20.
ENDCLASS.


CLASS zcl_bs_demo_job_adt_chk IMPLEMENTATION.
ENDCLASS.

 

Um eine Methode zu Implementieren, musst du diese nur in der Klassenimplementierung definieren und kannst diese dann mit Quellcode befüllen.

METHOD if_apj_jt_check_20~check_and_adjust.
ENDMETHOD.

 

Methoden

In diesem Abschnitt erfährst du mehr über die einzelnen Methoden, ihre Funktion und Wirkung. Dabei werden wir auf die Wichtigsten zuerst eingehen.

 

CHECK_AND_ADJUST

Die Methode kümmert sich um die Prüfung der Eingaben und kann dazu Meldungen erzeugen, die den User auf Fehler hinweisen. Es können aber auch die Eingaben des Users überschrieben oder korrigiert werden, zum Beispiel wenn bestimmte Werte in korrekt formatierte Werte umgesetzt werden sollen. Wir erhalten von Außen Informationen wie:

• Aktueller User
• Aktueller Job-Katalog
• Parameter (Meta-Informationen, Ausprägungen)

 

Dazu unsere Beispielimplementierung, um dir die Funktionsweise näher zu bringen:

DATA(ld_country) = ct_value[ KEY param parameter_name = 'R_LAND' ]-low.
DATA(lt_country) = FILTER #( ct_value USING KEY param WHERE parameter_name = CONV #( 'COUNTRY' ) ).

IF ld_country = abap_true AND lt_r_country IS INITIAL.
  INSERT VALUE #( id = 'ZBS_DEMO_JTUTORIAL' type = 'E' number = '001' ) INTO TABLE et_msg.
ELSE.
  ev_successful = abap_true.
ENDIF.

 

Wir lesen zuerst den Radiobutton R_LAND aus und filtern dann alle Eingaben zu COUNTRY, um im Anschluss diese Werte prüfen zu können. Aus Gründen der Überschaubarkeit verzichten wir auf ein Fehlerhandling, wenn keine Einträge gefunden werden. Ist der Radiobutton gewählt und sind keine Einträge als Filter vorhanden, dann wird eine Fehlermeldung in die Tabelle ET_MSG übernommen. Wurden keine Fehler gefunden, sollte der Flag EV_SUCCESSFUL auf ABAP_TRUE gesetzt werden, damit die Prüfung weiß, dass alles erfolgreich geprüft wurde.

Die Prüfung wird in der App "Application Jobs" über die Buttons "Check" und "Schedule" aufgerufen, also wenn die Prüfung explizit aufgerufen wird oder implizit durch die Einplanung des Jobs. Im Fehlerfall werden die Meldungen angezeigt und die Einplanung wird abgebrochen.

 

INITIALIZE

Wie der Name der Methode schon vermuten lässt, wird diese aufgerufen, wenn die Parameter das erste Mal für die Anzeige geladen werden. Dabei können Default-Werte aus dem Template überschrieben werden. Die Methode wird nur einmal, direkt zum Start aufgerufen und du erhältst die gleichen Informationen wie bei der Methode CHECK_AND_ADJUST. Die Werte kannst du nun entsprechend in CT_VALUE anpassen, es sind aber keine Einträge vorhanden, wenn die Werte im Template nicht vorbelegt wurden.

TRY.
    ct_value[ KEY param parameter_name = 'TEXT' ]-low = 'Init with Event'.
  CATCH cx_sy_itab_line_not_found.
    INSERT VALUE #( parameter_name = 'TEXT' sign = 'I' option = 'EQ' low = 'Init with Event' ) INTO TABLE ct_value.
ENDTRY.

TRY.
    ct_value[ KEY param parameter_name = 'TEST' ]-low = abap_false.
  CATCH cx_sy_itab_line_not_found.
    INSERT VALUE #( parameter_name = 'TEST' sign = 'I' option = 'EQ' low = abap_false ) INTO TABLE ct_value.
ENDTRY.

 

In unserem Beispielcoding wollen wir den Wert des Textes vorbelegen, dieser ist in der Standardvariante leer, sodass wir durch den ersten CATCH müssen, um den neuen Parameter zu übernehmen. Beim zweiten Parameter wollen wir das Testflag nicht mehr setzen, sodass die Checkbox beim Starten immer Leer ist. Da hier bereits ein Defaultwert gesetzt ist, muss dieser noch überschrieben werden. Es empfiehlt sich aber immer auf beide Situationen zu reagieren. Das Endergebnis sehen wir dann in der "Application Jobs" App beim Einplanen des Jobs.

 

GET_DYNAMIC_PROPERTIES

Die Methode kann dynamisch Parameter in der App anpassen, hier stehen die Optionen READ-ONLY oder HIDDEN zur Auswahl. Dabei kann abhängig von gesetzten Parametern die einzelnen Felder ausgesteuert werden. Die Methode wird bei der Initialisierung aufgerufen, aber auch nach jedem "Check". Aktuell ist es nicht möglich die Methode zu rufen, wenn ein Parameter-Wert geändert wird, deshalb sollte damit vorsichtig umgegangen werden.

DATA(ls_radiobutton_text) = VALUE #( it_value[ KEY param parameter_name = 'R_TEXT' ] OPTIONAL ).

IF ls_radiobutton_text-low = abap_false.
  INSERT VALUE #( job_parameter_name = 'TEXT' read_only_ind = abap_true ) INTO TABLE rts_dynamic_property.
ELSE.
  INSERT VALUE #( job_parameter_name = 'TEXT' read_only_ind = abap_false ) INTO TABLE rts_dynamic_property.
ENDIF.

 

Im Beispiel oben lesen wir den aktuellen Wert zum Radiobutton für den Text und prüfen im Anschluss, ob dieser gesetzt ist. Ist er nicht gesetzt, dann setzen wir das Textfeld auf Anzeige. Hier ist es wichtig, auch den Status wieder zurückzunehmen, da das System sich den aktuellen Zustand merkt. Wenn also das Feld wieder geöffnet werden soll, muss der Eintrag auf ABAP_FALSE gesetzt werden.

 

Oben steht der Radiobutton bei Country, entsprechend ist das Textfeld nun gesperrt. Setzen wir den Radiobutton nun auf Text und drücken den Button "Check", wird die Logik erneut durchlaufen und das Bild ändert sich.

 

CHECK_AUTHORIZATIONS

Hier besteht die Möglichkeit noch eine Berechtigungsprüfung durchzuführen, wenn man auf User oder Eingaben referenzieren möchte, die nicht durch die allgemeine Berechtigung auf den Job abgedeckt sind. Wie immer erhält man Zugriff auf die aktuellen Werte in der Eingabe, den aktuellen User oder den Job-Katalog zur Abgrenzung. Die Methode wird bei der Prüfung und bei der Einplanung aufgerufen.

ev_successful = abap_true.

IF iv_username = 'CB9980000000'.
  INSERT VALUE #( id = 'ZBS_DEMO_JTUTORIAL' type = 'E' number = '002' message_v1 = iv_username ) INTO TABLE et_msg.
  CLEAR ev_successful.
ENDIF.

 

Hier kannst du über verschiedene Wege Berechtigungsverprobungen durchführen, in unserem einfachen Beispiel prüfen wir, dass ein bestimmter User den Job nicht ausführen kann. Wenn die Prüfung erfolgreich war, sollte auf jeden Fall das Kennzeichen EV_SUCCESSFUL gesetzt werden oder einfach der Einfachheit zuerst setzen, wenn mehrere Prüfungen folgen. In der Einplanung erhält man dann die Fehlermeldung.

 

CHECK_START_CONDITION

Die letzte Methode prüft die Start-Konditionen bei der Einplanung des Jobs. Sie wird aber nicht beim "check" durchlaufen, sondern erst, wenn der "Schedule" durchgeführt wird. Hierbei hast du die Möglichkeiten noch einmal die Einplanungskriterien zu überprüfen und den Job an der Einplanung zu hindern.

IF is_schedule_info-periodic_granularity IS NOT INITIAL.
  INSERT VALUE #( id = 'ZBS_DEMO_JTUTORIAL' type = 'E' number = '003' ) INTO TABLE et_msg.
  ev_incorrect = abap_true.
ENDIF.

 

In diesem Beispiel erlauben wir keine wiederkehrende Einplanung, sondern nur eine einmalige Ausführung. Dazu prüfen wir in den Ausführungswerten das Feld PERIODIC_GRANULARITY, ist dort ein Wert hinterlegt, dann geben wir eine entsprechende Fehlermeldung aus und setzen das Flag EV_INCORRECT auf ABAP_TRUE.

 

Weitere Methoden

Die folgenden Methoden haben wir nicht näher beleuchtet bzw. keine Beispiele zur Verfügung gestellt, trotzdem wollen wir dir hier noch die Funktion näher bringen:

• CHECK_AND_ADJUST_PARAMETER - Wird aufgerufen, wenn der User Parameter ändert, um die Werte zu prüfen oder gegebenenfalls auch noch anzupassen.

• ADJUST_READ_ONLY - Anpassung von Werten für Felder die auf nur Anzeige geschaltet sind.

• ADJUST_HIDDEN - Anpassung der Werte bei ausgeblendeten Feldern.

 

Einiges aus der Verwendung und der Dokumentation findest du auch in ABAP Doc im Interface, falls du mal nicht weiter kommen solltest mit der Implementierung. Sonst hilft auch eine leere Implementierung, um einen Breakpoint zu setzen und sich die Variablen/Inhalte im Debugger anzuschauen.

 

Komplettes Beispiel

Hier noch einmal die komplette Prüfklasse aus dem heutigen Artikel zur Nachstellung bei dir im System.

CLASS zcl_bs_demo_job_adt_chk DEFINITION PUBLIC FINAL CREATE PUBLIC.
  PUBLIC SECTION.
    INTERFACES if_apj_jt_check_20.
ENDCLASS.


CLASS zcl_bs_demo_job_adt_chk IMPLEMENTATION.
  METHOD if_apj_jt_check_20~check_and_adjust.
    DATA(ld_country) = ct_value[ KEY param parameter_name = 'R_LAND' ]-low.
    DATA(lt_country) = FILTER #( ct_value USING KEY param WHERE parameter_name = CONV #( 'COUNTRY' ) ).

    IF ld_country = abap_true AND lt_country IS INITIAL.
      INSERT VALUE #( id = 'ZBS_DEMO_JTUTORIAL' type = 'E' number = '001' ) INTO TABLE et_msg.
    ELSE.
      ev_successful = abap_true.
    ENDIF.
  ENDMETHOD.


  METHOD if_apj_jt_check_20~initialize.
    TRY.
        ct_value[ KEY param parameter_name = 'TEXT' ]-low = 'Init with Event'.
      CATCH cx_sy_itab_line_not_found.
        INSERT VALUE #( parameter_name = 'TEXT' sign = 'I' option = 'EQ' low = 'Init with Event' ) INTO TABLE ct_value.
    ENDTRY.

    TRY.
        ct_value[ KEY param parameter_name = 'TEST' ]-low = abap_false.
      CATCH cx_sy_itab_line_not_found.
        INSERT VALUE #( parameter_name = 'TEST' sign = 'I' option = 'EQ' low = abap_false ) INTO TABLE ct_value.
    ENDTRY.
  ENDMETHOD.


  METHOD if_apj_jt_check_20~get_dynamic_properties.
    DATA(ls_radiobutton_text) = VALUE #( it_value[ KEY param parameter_name = 'R_TEXT' ] OPTIONAL ).

    IF ls_radiobutton_text-low = abap_false.
      INSERT VALUE #( job_parameter_name = 'TEXT' read_only_ind = abap_true ) INTO TABLE rts_dynamic_property.
    ELSE.
      INSERT VALUE #( job_parameter_name = 'TEXT' read_only_ind = abap_false ) INTO TABLE rts_dynamic_property.
    ENDIF.
  ENDMETHOD.


  METHOD if_apj_jt_check_20~check_authorizations.
    ev_successful = abap_true.

    IF iv_username = 'CB9980000000'.
      INSERT VALUE #( id = 'ZBS_DEMO_JTUTORIAL' type = 'E' number = '002' message_v1 = iv_username ) INTO TABLE et_msg.
      CLEAR ev_successful.
    ENDIF.
  ENDMETHOD.


  METHOD if_apj_jt_check_20~check_start_condition.
    IF is_schedule_info-periodic_granularity IS NOT INITIAL.
      INSERT VALUE #( id = 'ZBS_DEMO_JTUTORIAL' type = 'E' number = '003' ) INTO TABLE et_msg.
      ev_incorrect = abap_true.
    ENDIF.
  ENDMETHOD.
ENDCLASS.

 

Fazit

Der Prüf-Exit ist einer der umfangreichsten und benötigt daher einiges mehr an Erklärung, wir hoffen der Artikel hat dir weitergeholfen, die einzelnen Methoden und die Implementierung besser zu verstehen. Damit kannst du den Application Job noch robuster machen und die verschiedenen Funktionen besser nutzen.