Makros
Makros verwalten
Makros bieten die Möglichkeit Funktionsketten zu kapseln und wiederzuverwenden. Das erlaubt den kompakten Einsatz von Funktionsketten und eine zentrale Pflege dieser.
Änderungen an einem Makro wirken sich auf alle Profile aus, die dieses Makro verwenden. Makros können systemweit oder mandantenspezifisch definiert werden.
Über das Zielstruktur-Menü in der unteren Leiste des Funktionsbereichs können Sie den Makro-Dialog öffnen mit Option "Makros verwalten". Entweder um die vorhandene Funktionskette als neues Makro zu erstellen oder um die Übersicht aller Makros anzeigen zu lassen. Hinweis: Die ID eines Makros können Sie im geöffneten Makro kopieren.
Kontextmenü
|
Option |
Beschreibung |
|
Makro exportieren/importieren Makro mit Import ersetzen |
Hier können Makros exportiert (.macro) und auch wieder importiert werden. |
|
Makro-Verwendung finden |
Hier können Sie sich auflisten lassen, in welchen Profilen dieses Makro verwendet wird. |
|
Makro bearbeiten Makro duplizieren Makro löschen Neues Makro erstellen |
Bearbeiten, Duplizieren, Löschen oder Erstellen eines neues Makros. |
|
REST-Variablen für Makros anlegen |
Es werden die Variablen var__restapi_macro01 bis var__restapi_macro20 angelegt (alle vom Typ "String" und ohne Reset bei einem neuen Datenblatt) und die Variable var__restapi_macro_resultJSON . Siehe Abschnitt "Makro per HTTP aufrufen (REST)" unten. |
Neues Makro erstellen
Gehen wir von folgender Funktionskette aus.
Wenn Sie diese Funktionskette als neues Makro erstellen wollen, erhalten Sie folgenden Dialog.
(1) ID: Die ID des Makros. Kann hier kopiert werden.
(2) Beschreibung: Beschreibungstext, der später als Tooltip angezeigt wird.
(3) Zugriff: Das Makro ist entweder systemweit oder mandantenweit sichtbar. Hinweis: Kann nach dem ersten Speichern nicht mehr geändert werden.
(4) Im Export exkludieren: Mit dieser Option können Sie entscheiden, ob das Makro beim Export von Profilen oder bei der Übertragung von Profilen mit dem Transport Manager ignoriert werden soll.
(5) Funktionen: Hier können Sie in die Funktionskette (6) weitere Funktionen einfügen. Um das Beispiel einfach zu halten, werden wir das aber hier nicht tun.
(6) Enthaltene Funktionen des Makros: Die bisherige Funktionskette mit den einzelnen Funktionen. Wenn Sie eine Funktion markieren, werden Ihnen (wie bisher) die Parameter der Funktion angezeigt.
(7) Makro testen: Hier kann das Makro getestet werden. Wurden Eingabe-Parameter verwendet, siehe (8), können Sie für diese Testwerte angeben.
(8) Index, Beschreibung, Testwert: Optionale Eingabe-Parameter (linkes Fenster). Siehe folgenden Abschnitt.
Eingabe-Parameter für das Makro anlegen
Wenn Sie das oben erstellte Makro abspeichern, können Sie dieses bereits auf Feldern und Knoten verwenden. Das Beispiel oben ist allerdings sehr einfach und in dieser Form nur bedingt hilfreich. Oft möchten Sie, wie Sie das von den meisten Funktionen gewöhnt sind, auch Eingangsparameter verwenden.
Für diese Aufgabe gibt es einen speziellen Eingabeparametertyp "Parameter" nur für Makros, den Sie anstelle jedes Eingabeparameters in der Funktionskette auswählen können. Siehe folgendes Beispiel.
Beispiel
Markieren Sie Parameter a der ersten Funktion in der Kette und ändern Sie den Typ auf "Parameter" und stellen Sie den Wert von "4" auf "1". Der Wert ist der Parameter-Index. Damit dieser verwendet werden kann, muss er aber erst noch ein Eingabe-Parameter angelegt werden.
Verwenden Sie im linken Fenster (9) das Kontextmenü und legen Sie einen neuen Eingabe-Parameter an. Dieser hat den Index "1". Das ist der Wert, den Sie oben eingegeben haben. Geben Sie den Testwert "5" ein. Dieser Testwert wird dann als Eingabewert für diesen Parameter verwendet, wenn Sie Button "Makro testen" (7) klicken.
Als Ergebnis des Makro-Tests sollten Sie nun "23" erhalten.
Verwendung des Makros
Wenn Sie nun das Makro auf einem Knoten oder Feld verwenden, sieht das folgendermaßen aus. Sie sehen, dass das Makro einen Parameter hat (10). Das ist der Parameter, den Sie gerade angelegt hatten.
Makro per HTTP aufrufen (REST)
Sie können für jedes Makro definieren, ob es per HTTP aufrufbar ist. Im HTTP-Request müssen dann die Makro-ID und die Makro-Parameter angegeben werden. Siehe folgendes Beispiel.
Gehen wir von folgendem Makro aus:
Wir sehen, die ID des Makros ist "-948283363". Zudem hat das Makro zwei Parameter "Date" und "Template". Hinweis: Die Parameter sind hier nummeriert, beginnend mit "1". Im HTTP-Request werden die Parameter mit Buchstaben angegeben, beginnend mit "a".
Klicken Sie auf den Button "Standard HTTP-Zugang für Makros konfigurieren". Es öffnet sich danach der folgende Dialog (diese Einstellungen können in individuellen Makros überschrieben werden):
Wie Sie sehen ist der formale Aufbau der URL:
|
https://<your-server>:<your-port>/dw/macro/v1/<macro-id>?<cid><weitere optionale Parameter> |
Parameter
|
Parameter |
Beschreibung |
|
macro-id |
(Pflicht) Die ID des Makros. |
|
cid |
(Pflicht) Die Mandanten-ID. -1 ist der Default Mandant. |
|
ttl sid rs |
(optional) Warum Sessions nutzen? Sessions ermöglichen eine Art "Gedächtnis" zwischen mehreren API-Aufrufen. Sie machen komplexe oder mehrstufige Datenverarbeitungen effizienter, weil man nicht bei jedem Aufruf alle Daten neu übergeben oder berechnen muss. ttl (time to live): sid (session ID): rs (remove session): |
Beispiel-Request (GET)
|
https://localhost/dw/macro/v1/-948283363?a=24-10-03&b=yy-MM-dd&ttl=10&cid=-1 |
Hinweis: Sie sehen die Angabe der Makro-ID und der zwei Makro-Parameter als Request-Parameter. Verwenden Sie für den Request-Parameter "cid" fix den Wert "-1".
Beispiel-Response (immer mit MIME-Type application/json):
{ "sid": "-2a757ec1:192571c4108:-18fe.a61aa22d82067d80:-2a757ec1:192571c1cd5:-8000", "cid": "-1", "expiresAt": "Fri Oct 04 12:40:26 CEST 2024", "result": "Thu"}Das Ergebnis des Makros finden Sie im Feld "result", hier also "Thu" (der ermittelte Tag).
Beispiel-Request (POST)
|
https://localhost/dw/macro/v1/-275832567 |
Die Daten müssen bei POST als JSON im Body angegeben werden. Body-Daten:
{ "ttl" : "60", "a": "hello", "b" : "world", "cid": "-1"}Beispiel-Response (immer mit MIME-Type application/json):
{ "sid": "-437190e:19253af2f0e:-6de.16a4526421da288d:-437190e:19253af0b75:-8000", "cid": "-1", "expiresAt": "Thu Oct 03 21:12:09 CEST 2024", "result": "hello-world"}Fehler
Bei einem Fehler wird mit HTTP-Status-Code 400 und folgender JSON geantwortet.
{ "error" : "Error message..."}REST-Variablen
Wenn Sie im Makro Variablen verwenden möchten, dann können Sie dort keine "normalen" Variablen verwenden, da Sie sich bei einem REST-Aufruf des Makros nicht in einem Profil befinden. Es können aber spezielle Variablen angelegt werden, die Sie dafür verwenden können. Siehe den entsprechenden Kontextmenü-Eintrag oben.
Wichtiger Hinweis: Beachten Sie bitte, dass Sie das Makro dann zwar "eigenständig" per REST rufen können, aber die Variablen leben in einem spezifischen Profil. D. h. um die Variablen in REST-Aufrufen verwenden zu können, muss das Profil weiterhin bestehen und die Variablen müssen dort angelegt bleiben.
Spezialfall
Wird im Makro die Variable "var__restapi_macro_resultJSON" auf "true" gesetzt mit der Funktion save variable a(b) type-safe, wird in der JSON-Response im Feld "result" das Ergebnis "as it is" eingefügt, also als valides JSON angesehen und nicht als String gesetzt.
Beispiel:
Nehmen wir an, das Makro liefert den folgenden Rückgabewert: ["Ford", "BMW", "Fiat"]
Response bei var__restapi_macro_resultJSON=true:
{ ... "result": ["Ford", "BMW", "Fiat"]}Response bei var__restapi_macro_resultJSON=false:
{ ... "result": "[\u0022Ford\u0022, \u0022BMW\u0022, \u0022Fiat\u0022]"}