Prozedur um „Rückmeldungen“ zu Aufträgen hinterlegen zu können, die aus einem Fremdsystem (i.d.R. ein Warenwirtschafts-System) kommen (wie z.B. die erfolgreiche Annahme bzw. der Versand eines Auftrags).

Die Rückmeldung erfolgt in erster Linie durch Setzen der Status für die Auftragspositionen. Daher erwartet die Prozedur in „tempdb.dbo.TwoIDs“ :

• ID1 : Auftrags-Position (entspricht „Position“ in der Tabelle „OrderContent“)
• ID2 : OrderStateID

Hinweis :
Übergibt man eine Position, die nicht im Auftrag vorkommt, gibt es „-500“. In Fällen, wo die Ursache dafür aber die Tatsache ist, daß (wie in vielen WWS möglich) im Hauptsystem nachträglich Positionen zum betroffenen Auftrag hinzugefügt wurden, wäre es schöner, diesen Fehler zu ignorieren bzw. Positionen, die nicht vorkommen, zu ignorieren. Dies kann man erreichen, indem man den „Settings“-Eintrag zum Schlüssel „IgnoreUnknownPositionsInAcknowledgeOrder“ auf „1“ konfiguriert.
Achtung : 1. Dies sollte natürlich mit Bedacht geschehen, da „echte“ Fehler (hinsichtlich falscher Positions-Nummern) so natürlich nicht mehr auffallen !
2. Die Datensätze aus „tempdb.dbo.TwoIDs“, die zu nicht-existierenden Positionen gehören, werden entfernt (stehen dem Aufrufer also nach Ausführung dieser Prozedur nicht mehr zur Verfügung) !

Man könnte eigentlich einfach om_ChangeOrderState_Ad aufrufen; im Regelfall möchte man aber zusätzlich die Auftragsnummer sowie (im Falle eines Neukunden) evtl. die Kundennummer des Auftraggebers speichern, die in dem anderen System vergeben wurde.
U.U. muß sogar die „PersonID“ geändert werden : Das Hauptsystem stellt vielleicht z.B. fest, daß es sich bei dem vermeintlichen Neukunden um eine Dublette handelt und legt den Auftrag zu einem bereits vorhandenen Kunden an - der ebenfalls im „dStore“ existiert, aber eben unter einer anderen „PersonID“. Falls der Auftraggeber im „dStore“ keine oder eine vom „dStore“ generierte Kundennummer hat, wird die Eigenschaft zu diesem Merkmal auf die zurückgemeldete Kundennummer (→ „CustomerNo“) gesetzt.

Standardmäßig wird davon ausgegangen, daß die Lieferanschrift („Delivery_PersonID“) für den Auftrag die gleiche ist, wie der
Auftraggeber; man kann aber auch eine Kundennummer für die Lieferanschrift (→ „Delivery_CustomerNo“) zurückmelden.

Hinweis zur Kundennummer (Parameter „CustomerNo“ bzw. „Delivery_CustomerNo“) :
Die ID des Personenmerkmals für die Kundennummer wird über die Einstellung zum Personentyp („PersonTypeSetting“) zum Schlüssel „CustomerNoCharacteristicID“ konfiguriert. Gibt es zum Personentyp des Auftraggebers bzw. der Lieferanschrift keine Einstellung zu diesem Schlüssel, wird aus Abwärtskompatibilitäts-Gründen von der „PersonCharacteristicID = 1“ ausgegangen.

U.U. soll durch die Rückmeldung eines Auftrags irgendwelche Aktionen ausgelöst werden, die durch den „dStore“ standardmäßig nicht angeboten werden (Überprüfungen, Benachrichtigungen etc.). Zu diesem Zweck gibt es die Prozedur „_ac_AcknowledgeOrder“, die immer Installations-spezifisch ist (und entsprechend angepaßt werden muß, da sie, vom „dStore“ vorinstalliert, nichts tut). Möchte man, daß diese Prozedur am Ende der Ausführung von om_AcknowledgeOrders_Ad ausgeführt wird, ist „Fire_ac_AcknowledgeOrder“ auf „1“ zu setzen.

Anmerkung zum Parameter „OrderNo“:

Sind nicht alle Positionen des Auftrags in „tempdb.dbo.TwoIDs“ angegeben, wird die „OrderNo“ (falls angegeben) nur zu diesen Positionen gespeichert. Ist zum Auftrag bereits die „OrderNo“ hinterlegt, wird „OrderNo“ jedoch ignoriert; ist eine andere „OrderNo“ zum Auftrag gespeichert, gibt es allerdings den Fehler „-372“ ! Danach wird überprüft, ob zu einer der Positionen in „tempdb.dbo.TwoIDs“ bereits eine andere „OrderNo“ hinterlegt ist - in diesem Fall bricht die Prozedur ebenfalls mit dem Fehler „-372“ ab.
Dieses Verhalten (daß die „OrderNo“ nicht überschrieben werden darf) kann man aber über entsprechende Konfiguration in „Settings“ zum Schlüssel „AllowChangeOfOrderNo“ ändern.

Anmerkung zum Parameter „AddOrderInformation“ :

Möchte man irgendwelche zusätzlichen Informationen zum Auftrag (z.B. Paketnummer oder Fehlermeldung der Schnittstelle etc.) speichern, ist „1“ oder „2“ für „AddOrderInformation“ zu übergeben, und die Daten müssen dann in „tempdb.dbo.CharacteristicValues“ übergeben werden. In der Spalte „CharacteristicID“ wird dabei die „InformationTypeID“ und in „Value“ die Information selbst erwartet (um eine Informationen zu löschen, gibt man '' an).
Setzt man den Parameter-Wert für „AddOrderInformation“ auf „1“, werden die Informationen VOR den Status-Änderungen eingefügt, gibt man „2“ an, werden die Informationen NACH den Status-Änderungen gespeichert.
Hintergrund hierfür ist die Status-abhängige Überprüfung, ob Auftrags-Informationen nachträglich hinzugefügt bzw. geändert werden dürfen.
Hinweis : Werte ungleich „0“, „1“ oder „2“ für „AddOrderInformation“ führen zum Fehler „-500“ !

Anmerkung zum Parameter „AddOrderContentInformation“ :

Man kann auch zusätzliche Informationen zu den einzelnen Auftragspositionen speichern lassen. Dazu ist entweder …

• „1“ oder „2“ für „AddOrderContentInformation“ zu übergeben und vor dem Aufruf eine temporäre Tabelle zu erstellen (Definition s.u.), die mit den entsprechenden Daten zu füllen ist

oder

• „3“ oder „4“ für „AddOrderContentInformation“ zu übergeben und vorher die Daten via „if_om_AcknOrders_OContInfo_Ad“ zu übergeben.

Setzt man den Parameter-Wert für „AddOrderContentInformation“ auf „1“ bzw. „3“, werden die Informationen VOR den Status-Änderungen eingefügt, gibt man „2“ bzw. „4“ an, werden die Informationen NACH den Status-Änderungen gespeichert. Hintergrund hierfür ist die Status-abhängige Überprüfung, ob Auftragpositions-Informationen nachträglich hinzugefügt bzw. geändert werden dürfen.
Hinweis : Werte ungleich „0“, „1“, „2“, „3“ oder „4“ für „AddOrderContentInformation“ führen zum Fehler „-500“ !

Hier die Definition der temporären Tabelle für den Fall „AddOrderContentInformation IN (1, 2)“ :

CREATE TABLE #ContentInformation ( Position smallint,
InformationTypeID smallint,
Information varchar(1000)
)

Die Prozedur hat keine Rückgaben.

Die Prozedur hat keine Output-Parameter.

Die Rückgabe erfolgt als XML-Dokument welches gegen das Schema Response/EngineProcedure_v1_0.xsd validiert.

Der folgende Link öffnet in einem separaten Fenster den Engine Playground der fest mit dem dbap-demo System verbunden ist:

• om_AcknowledgeOrders_Ad im Engine Playground öffnen

Unformatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/om_AcknowledgeOrders_Ad?OrderID=<value>'

Mit xmllint ²⁾ formatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/om_AcknowledgeOrders_Ad?OrderID=<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'),
	'om_AcknowledgeOrders_Ad',
		array(
			'OrderID' => <value>,
			// 'OrderNo' => NULL,
			// 'CustomerNo' => NULL,
			// 'Delivery_CustomerNo' => NULL,
			// 'Fire_ac_AcknowledgeOrder' => 0,
			// 'AddOrderInformation' => 0,
			// 'AddOrderContentInformation' => 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="om_AcknowledgeOrders_Ad">
			<Parameters>
				<Parameter Name="OrderID"><!-- integer value --></Parameter>
				<!-- <Parameter Name="OrderNo">NULL</Parameter> -->
				<!-- <Parameter Name="CustomerNo">NULL</Parameter> -->
				<!-- <Parameter Name="Delivery_CustomerNo">NULL</Parameter> -->
				<!-- <Parameter Name="Fire_ac_AcknowledgeOrder">0</Parameter> -->
				<!-- <Parameter Name="AddOrderInformation">0</Parameter> -->
				<!-- <Parameter Name="AddOrderContentInformation">0</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>