Prozedur zur Verwaltung der Bedingungen für einen Arbeitsschritt eines „TRI-Trigger“.
Hintergrund : „TRI-Trigger“ sind Objekte, die innerhalb der Engine bei bestimmten Datenänderungen ausgelöst werden (z.B. dem Status-Wechsel von Auftragspositionen). Die Definition eines solchen Triggers besteht aus Arbeitsschritten, zu denen optional eine Bedingung hinterlegt sein kann und zu denen immer eine bestimmte Reihe von Anweisungen (derzeit Prozedur-Aufrufen) konfiguriert ist. Außerdem kann für jeden einzelnen Arbeitsschritt und jede einzelne Anweisung ein „Iterator“ definiert werden.
Hinweise :
1. Sofern der Trigger schon zugewiesen ist (s. Rückgabespalte „TriggerStatus“ von mi_GetTrigger_Ad), kann NICHTS mehr geändert werden !
2. Egal, WAS durch diesen Aufruf geändert wird (neue Bedingung anlegen oder bestehende ändern/löschen), wir gehen sicherheitshalber davon aus, daß der Trigger dadurch erstmal unbrauchbar wird, weswegen er als fehlerhaft gekennzeichnet wird (s. Rückgabespalte „TriggerStatus“ von mi_GetTrigger_Ad). Um den Trigger (wieder) verwendbar zu machen, muß mi_ValidateTRITrigger_Ad aufgerufen werden !
Erläuterungen zu® Bedingung(en) selbst :
1. Grundsätzlich gilt, daß mehrere Bedingungen zur gleichen „WorkStepNo“ (eindeutige Kennzeichnung eines Arbeitsschrittes) mit „AND“ verknüpft werden - eine „ODER“-Funktionalität gibt es (derzeit) nicht wirklich (etwas Abhilfe schafft der „LikeIn“-Operator, dazu gleich mehr). Die Bedingungen sind eindeutig durch eine „ConditionNumber“ gekennzeichnet, wobei diese mit 1 beginnen und lückenlos bis maximal 255 aufsteigen (es sind theoretisch also maximal 255 Bedingungen möglich).
2. Eine Bedingung besteht immer aus einer „StrToCompare“-Zeichenkette, die einem „Operator“ entsprechend mit einer „Condition“-Zeichenkette verglichen wird und je nach der „NegateCondition“-Einstellung entweder wahr („0“) oder falsch („1“) werden muß, damit die Anweisungen des Arbeitsschrittes (s. mi_GetTRITriggerToDos_Ad) ausgeführt werden. Ein weiteres Kriterium bei der Prüfung der Bedingung ist, ob sie für ALLE IDs, die vom Trigger betroffen sind, geprüft wird („CheckEachAffectedID = 1“) oder ob die IDs durchlaufen werden, bis bei einer die Bedingung greift („CheckEachAffectedID = 0“) - letzteres ist also eine Art „If exists“.
3.) Zur Bedingung selbst : Sowohl „StrToCompare“ als auch „Condition“ sind sogenannte „TRI-Ausdrücke“, d.h. sie dürfen „Platzhalter-Funktionen“ enthalten - s. mi_GetTRITriggerReplFuncts_Ad - die zur Laufzeit ausgewertet werden. Die beiden so (zur Laufzeit) entstehenden Zeichenketten werden je nach eingestelltem „Operator“ dann miteinander verglichen, und zwar IMMER
als „string“s ! Um letztlich aber doch Zahlen oder Datumsangaben miteinander vergleichen zu können, gibt es spezielle Platzhalter- Funktionen wie z.B. „numtocompstr“.
Es stehen genau drei Operatoren zur Verfügung : „LikeIn“ (s. 4.), „>“ und „>=“. Das sieht auf den ersten Blick sehr mager aus, da z.B. „<“ und „⇐“ fehlen. Letztere Funktionalität kann man aber ja mit der „NegateCondition“-Einstellung erreichen : beispielsweise stellt „Operator = '⇐'“ und „NegateCondition = 1“ einen „>“-Vergleich dar !
4.) Zum speziellen „LikeIn“-Operator : Es wird IMMER der „LIKE“-Operator verwendet, was einem „=“ entspricht, sofern KEINE „wildcards“ in den zu vergleichenden Zeichenketten enthalten sind. Der „In“-Teil im Namen „LikeIn“ soll andeuten, daß der in „Condition“ angegebene Ausdruck auch eine LISTE von Werten ergeben darf - bei TRI-Ausdrücken sind diese Werte durch „;;;“ getrennt. Dies stellt dann eine kleine „ODER“-Funktinalität dar, weil „StrToCompare“ mindestens EINEM der Werte aus der Liste entsprechen muß (mit „LIKE“ verglichen), damit die Bedingung erfüllt ist (sofern „NegateCondition = 0“ ist natürlich).
Beispiele :
1.) Ist „TriggerID“ ein sogenannter „ChangeOrderStateTrigger“ (Rückgabespalte „TriggerTypeID“ von mi_GetTRITrigger_Ad enthält den Wert „2“) und gibt man für „StrToCompare“ den Wert …
'#iteratorvalue(condition)##columnvalue(OrderContent,OrderContentID,OrderID)##columnvalue(Orders,OrderID,PaymentTypeID)#'
… an und wird in „Condition“ der Wert '1;;;2' angegeben, formuliert man damit im Fall „Operator = 'LikeIn'“ und „NegateCondtion = 0“ die folgende Bedingung :
Falls die „PaymentTypeID“ (also die Zahlungsart) des zur Position („#iteratorvalue(condition)#“ ergibt immer eine vom Trigger betroffene „OrderContentID“) zugehörigen Auftrags („OrderID“) entweder „1“ oder „2“ ist.
2.) Sei „TriggerID“ ein sogenannter „ChangeOrderStateTrigger“ (Rückgabespalte „TriggerTypeID“ von mi_GetTRITrigger_Ad enthält den Wert „2“) und sei für den Arbeitsschritt der folgende Iterator (s. Rückgabespalte „IterationList“ von mi_GetTRITriggerWorkflow_Ad) definiert :
'#affectedids(trigger)##columnvalue(OrderContent,OrderContentID,OrderID)##distinct()#'
Damit ergibt sich eine Iteration über alle VERSCHIEDENEN Aufträge („OrderIDs“), zu denen die vom Status-Wechsel betroffenen Auftragspositionen gehören. Eine typische Bedingung wäre daher dann :
Somit würden dann die Anweisungen des Arbeitsschrittes nur für die „OrderContentID“s eines Auftrags ausgeführt.
HTTP-Method | POST |
HTTP-Auth | Optional |
Alias | mi_ModifyTRITriggerConditions_Ad |
Tags | |
Engine-Kategorie | system administration |
Engine-Typ | Daten-Änderung |
Letzte Aktualisierung | 7.0.8 (2015-08-21) |
Name 1) | Standard-Wert | Beschreibung 2) | SQL-Datentyp3) | ab Version |
---|---|---|---|---|
TriggerID | ID eines „TRI-Trigger“, zu dem eine Bedingung (zum Arbeitsschritt „WorkStepNo“) verwaltet werden soll | smallint | 7.0.3 | |
WorkStepNo | Eindeutige Nummer eines Arbeitsschrittes für den Trigger „TriggerID“ (bestimmt die Reihenfolge des Arbeitsschritts innerhalb aller Arbeitsschritte des Triggers), zu dem eine Bedingung verwaltet werden soll | tinyint | 7.0.3 | |
ConditionNumber | NULL | X-te Bedingung („1“ bis „255“) zum Arbeitsschritt „WorkStepNo“ des Triggers „TriggerID“, die je nach „DeleteCondition“ geändert/gelöscht werden soll. „NULL“ übergeben, um eine neue Bedingung anzulegen (Nummer wird dann automatisch vergeben). | tinyint | 7.0.3 |
StrToCompare | „TRI-Ausdruck“, der anhand des in „Operator“ angegebenen Operators mit „Condition“ verglichen werden soll (bei Auswertung/Prüfung der Bedingung) - s.a. Beschreibung ! | varchar(1000) | 7.0.3 | |
Operator | Wie „StrToCompare“ und „Condition“ verglichen werden sollen (bei Auswertung/Prüfung der Bedingung) - s.a. Beschreibung ! Mögliche Werte : „LikeIn“, “>„ und “>=„. | varchar(10) | 7.0.3 | |
Condition | „TRI-Ausdruck“ mit dem „StrToCompare“ anhand des in „Operator“ angegebenen Operators verglichen werden soll (bei Auswertung/Prüfung der Bedingung) - s.a. Beschreibung ! | varchar(2000) | 7.0.3 | |
NegateCondition | 0 | Gibt an, ob der Vergleich von „StrToCompare“ und „Condition“ wahr sein muß („0“) oder nicht („1“), damit die Bedingung „ConditionNumber“ als erfüllt gilt | bit | 7.0.3 |
CheckEachAffectedID | 0 | Soll die Bedingung für ALLE IDs, die vom Trigger betroffen sind, geprüft werden („1“) oder sollen die IDs durchlaufen werden, bis bei einer die Bedingung erfüllt ist („0“). | bit | 7.0.3 |
DeleteCondition | 0 | Wird nur beachtet, wenn „CondionNumber“ angegeben ist ! Entscheidet, ob die bestehende Bedingung geändert („0“) oder gelöscht („1“) werden soll. | bit | 7.0.3 |
Die Prozedur hat keine Rückgaben.
Die Prozedur hat keine Output-Parameter.
Code | Beschreibung | Quelle 4) |
---|---|---|
-569 | Der Benutzer hat kein Ausführungsrecht für die Prozedur | nur indirekt |
-567 | Die Prozedur darf z. Zt. nicht ausgeführt werden | nur indirekt |
-566 | Die Prozedur darf mit den übergebenen Parametern nicht ausgeführt werden | nur indirekt |
-535 | Das Datum liegt nicht in der Vergangenheit | nur indirekt |
-530 | Der Wert ist nicht konvertierbar | nur indirekt |
-510 | Der Benutzer ist nicht registriert | nur indirekt |
-508 | Ungültiger TRI-Ausdruck | nur indirekt |
-504 | Es ist ein Problem aufgetreten, das nicht gelöst werden kann, Prozedur wird daher abgebrochen | nur indirekt |
-502 | Die Parameter-Werte der Prozedur können nicht verarbeitet werden (kein passendes Trennzeichen) | nur indirekt |
-500 | Falsche Parameter | direkt und indirekt |
Die Rückgabe erfolgt als XML-Dokument welches gegen das Schema Response/EngineProcedure_v1_0.xsd validiert.
7.0.8 | 2015-08-21 | Ab jetzt wird der Fehler, daß NULL für „StrToCompare“ bzw. „Condition“ angegeben wird, geprüft und mit “-500„ beantwortet [vorher gab es einen „attempt to insert null…“-Fehler] |
7.0.7 | 2015-01-29 | Interne Änderung : Datentyp-Erweiterung des „ReferenceKey“ [für „_mi_StartProcedure“-Aufruf] |
7.0.3 | 2013-12-13 | Erstmalig in dieser Version erstellt |
Der folgende Link öffnet in einem separaten Fenster den Engine Playground der fest mit dem dbap-demo System verbunden ist:
Unformatierte Ausgabe:
curl -X POST 'http://<partner>-<project>.dstore.de/default/engine/mi_ModifyTRITriggerConds_Ad?TriggerID=<value>&WorkStepNo=<value>&StrToCompare=<value>&Operator=<value>&Condition=<value>'
Mit xmllint 5) formatierte Ausgabe:
curl -X POST 'http://<partner>-<project>.dstore.de/default/engine/mi_ModifyTRITriggerConds_Ad?TriggerID=<value>&WorkStepNo=<value>&StrToCompare=<value>&Operator=<value>&Condition=<value>' | xmllint --format -
use dStore_php\WebService; $service = new WebService\Service( WebService\Scheme::HTTP,'<partner>-<project>.dstore.de', 80); $request = new WebService\Requests\Engine\Procedure\Request( new WebService\Requests\AccessData('default'), 'mi_ModifyTRITriggerConds_Ad', array( 'TriggerID' => <value>, 'WorkStepNo' => <value>, 'StrToCompare' => '<value>', 'Operator' => '<value>', 'Condition' => '<value>', // 'ConditionNumber' => NULL, // 'NegateCondition' => 0, // 'CheckEachAffectedID' => 0, // 'DeleteCondition' => 0 ) ); $service->execute($request); $xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument(); $ResultSet = $xml_result->getRowsAsArray();
XML zur Ausführung mit der Methode engine/execute, z.B. per
curl --header 'Content-Type: application/xml' -X POST 'http://<partner>-<kunde>.dstore.de/default/engine/execute' -d '<xml-daten>'
<?xml version="1.0" encoding="UTF-8"?> <ListOfBatches> <Batch No="0"> <Procedure Name="mi_ModifyTRITriggerConds_Ad"> <Parameters> <Parameter Name="TriggerID"><!-- smallint value --></Parameter> <Parameter Name="WorkStepNo"><!-- tinyint value --></Parameter> <Parameter Name="StrToCompare"><!-- varchar value --></Parameter> <Parameter Name="Operator"><!-- varchar value --></Parameter> <Parameter Name="Condition"><!-- varchar value --></Parameter> <!-- <Parameter Name="ConditionNumber">NULL</Parameter> --> <!-- <Parameter Name="NegateCondition">0</Parameter> --> <!-- <Parameter Name="CheckEachAffectedID">0</Parameter> --> <!-- <Parameter Name="DeleteCondition">0</Parameter> --> </Parameters> </Procedure> </Batch> </ListOfBatches>