Prozedur um Eigenschaften einer Person hinzuzufügen, zu ändern oder zu löschen.

Anmerkungen zum Parameter „ValueList“ :

1. Soll eine Eigenschaft zu einem Merkmal gelöscht werden, ist in der Werte-Liste an der entsprechenden Stelle „nichts“ (im Sinne von „NULL“) anzugeben.
Beispiel (falls „SeparatorInValueList = '¶' ist) :
Die Angabe von „CharacteristicIDList = '2¶3¶15'“ und „ValueList = 'irgendetwas¶¶anderes'“ würde dazu führen, daß die Eigenschaft zum Merkmal mit der ID „3“ gelöscht wird (sofern es sich hierbei nicht um ein Pflicht-Merkmal handelt) und die Eigenschaften zu den Merkmal-IDs „2“ und „15“ den Angaben entsprechend geändert werden. Möchte man die Eigenschaft zu genau einem Merkmal löschen, ist „ValueList = NULL“ anzugeben, nicht '' ! Letzteres würde nämlich dazu führen, daß die Eigenschaft auf den Wert (o.a. „string“) '' gesetzt würde.

2. Man kann auch „relative Änderungen“ (o.a. „inkrementelle updates“) durchführen - um z.B. eine „Zahl-Eigenschaft“ um einen Wert zu erhöhen oder zu erniedrigen. Dazu übergibt man die NEGATIVE Merkmal-ID in „CharacteristicIDList“ an, wobei je nach Datentyp des Merkmals der entsprechende Wert in „ValueList“ unterschiedliche Formen annehmen muß und entsprechend unterschiedlich interpretiert wird :

A) Ist das Merkmal vom Basis-Typ „Zahl“, muß der entsprechende Wert in „ValueList“ die Form “<Zahl-Wert inkl. Vorzeichen vom Datentyp des Merkmals>„ besitzen. Ist kein explizites Vorzeichen angegeben, wird dies als positiver Wert interpretiert. Dieser Zahl-Wert wird dann einfach zur bestehenden Eigenschaft (ebenfalls eine Zahl) hinzuaddiert.
B) Handelt es sich um ein „Text“-Merkmal, wird eine relative Änderung als „string“-Konkatenation ausgeführt, d.h. der entsprechende Wert in „ValueList“ sieht so aus : “<Vorzeichen><String>„
Das bedeutet, daß die “<String>„-Zeichenkette entweder VOR (falls “<Vorzeichen>„ gleich “-„ ist) die bestehende Eigenschaft gesetzt oder HINTEN (“<Vorzeichen„ gleich “+„) an die Eigenschaft angehängt wird.
C) Beim Basis-Typ „Datum“ schließlich muß der entsprechende Wert in „ValueList“ diese Form haben : “<datepart><integer-Wert>„. Ist kein explizites Vorzeichen im “<integer-Wert>„ angegeben, wird dies als positiver Wert interpretiert. “<datepart>„ muß - angelehnt an die T-SQL-Funktion „dateadd“ - einen der folgenden Werte annehmen :

• „yy“ → Änderung der Datums-Eigenschaft um die angegebene Anzahl (“<integer-Wert>„) JAHRE
• „mm“ → Änderung der Datums-Eigenschaft um die angegebene Anzahl (“<integer-Wert>„) MONATE
• „dd“ → Änderung der Datums-Eigenschaft um die angegebene Anzahl (“<integer-Wert>„) TAGE
• „hh“ → Änderung der Datums-Eigenschaft um die angegebene Anzahl (“<integer-Wert>„) STUNDEN
• „mi“ → Änderung der Datums-Eigenschaft um die angegebene Anzahl (“<integer-Wert>„) MINUTEN
• „ss“ → Änderung der Datums-Eigenschaft um die angegebene Anzahl (“<integer-Wert>„) SEKUNDEN
• „ms“ → Änderung der Datums-Eigenschaft um die angegebene Anzahl (“<integer-Wert>„) MILLISEKUNDEN

D) Für „Ja/Nein“-Merkmale ist keine „relative Änderung“ möglich

Beispiele :
1.) Ist „17“ eine ID eines Merkmals, zu dem 2-stellige Zahlen als Eigenschaften hinterlegt werden können, würde “ CharacteristicIDList = '17' „ und “ ValueList = '-5' „ dazu führen, daß die aktuelle Eigenschaft der „PersonID“ zum Merkmal „17“ um „5“ ERNIEDRIGT wird.
2.) Stellt „19“ die ID eines „Datum-Merkmals“ dar, und besitzt „PersonD“ aktuell als Eigenschaft den Wert „01.04.1968“, würde “ CharacteristicIDList = '19' „ und “ ValueList = 'yy+2' „ dazu führen, daß 2 Jahre auf das Datum „01.04.1968“ hinzuaddiert würden, und somit die Eigenschaft auf „01.04.1970“ gesetzt werden würde.
3.) Bei einem Aufruf mit “ CharacteristicIDList = '20' „ und “ ValueList = '-not ' „ würde, wenn „PersonID“ zu diesem Merkmal beispielsweise die „Text“-Eigenschaft „valid“ besäße, die neue Eigenschaft „not valid“ lauten.

Weiterer Hinweis zu „inkrementellen updates“ :
Hat die Person noch KEINE Eigenschaft zum Merkmal, passiert je nach Basis-Datentyp folgendes :

• bei Zahlen „addieren“ wir den Wert zur Zahl „0“ - was quasi dem direkten Setzen der Eigenschaft auf den Wert entspricht
• bei Datumsangaben „addieren“ wir den Wert zum '01.01.1970'
• bei „strings“ konkatenieren wir den Wert zu „NULL“ - was quasi dem direkten Setzen der Eigenschaft auf den Wert entspricht

Anmerkung zur Rückgabespalte „ResultCode“ :
Folgende Codes können derzeit zurückgegeben werden :
„2“ : Die Eigenschaft existiert bereits, aber das zugehörige Merkmal ist eindeutig („IsUnique = 1“) !
„3“ : Es handelt sich um ein Merkmal mit vordefinierten Werten, aber die übergebene Eigenschaft existiert nicht
„4“ : Die Eigenschaft gehört zu einem Merkmal, das nicht dem Informationstyp („PersonCharacCategoryID“) zugeordnet ist.
„5“ : Das Merkmal darf aufgrund von Zugriffsbeschränkungen nicht editiert werden
„6“ : Der Wert ist ungültig, d.h. entspricht nicht dem Feldtyp des zugehörigen Merkmals
„8“ : Pflichtmerkmal in der Kategorie „PersonCharacCategoryID“, zu dem keine Eigenschaft angegeben wurde bzw. dessen Eigenschaft fehlerhaft ist (im letzteren Fall taucht das Merkmal ein zweites Mal in der Ergebnismenge auf, und zwar mit dem Code 2, 3 oder 6)
„9“ : Pflichtmerkmale können nicht gelöscht werden
„10“ : Der vordefinierte Wert ist zwar angelegt, aber entweder nicht mehr oder noch nicht gültig

Hinweis zum Dubletten-Check :

1. Beim Ändern von Personendaten kann ein Dubletten-Check durchgeführt werden. Vorraussetzung dafür ist zum einen, daß der „PersonTypeSettings“-Eintrag „CharacteristicsForDuplicateSearch“ für den entsprechenden Personen-Typ konfiguriert ist oder „_ac_ExecuteDuplicateCheck“ (individuell) implementiert ist. Standardmäßig ist die Prozedur „_ac_ExecuteDuplicateCheck“ so codiert, daß eine „Action“ angelegt wird, die als Parameter die betroffene „PersonID“ (zur „KeyVariable = AffectedPersonID“) sowie zur „KeyVariable = ActionInsertedByProcedure“ den Prozedurnamen „_ac_ExecuteDuplicateCheck“ besitzt.
Es ist dann noch ein entsprechendes Skript/Programm einzurichten, das diese Actions abarbeitet, d.h. letztlich die Prozedur pm_UpdatePossibleDuplicates_Ad aufruft. Die Prozedur „_ac_ExecuteDuplicateCheck“ legt diese Action aber nur an, wenn der besagte „PersonTypeSettings“-Eintrag vorhanden ist. Diese Prozedur kann natürlich (wie alle „ac“-Prozeduren) individuell angepaßt werden.

2. Soll ein Dubletten-Check ohne Verzögerung durchgeführt werden, d.h. transaktionssicher zusammen mit dem Ändern der Personendaten, ist der „PersonTypeSettings“-Eintrag „ExecDuplicateCheckImmediately“ für den entsprechenden Personen-Typ auf „1“ zu setzen. In diesem Fall wird eine interne Prozedur aufgerufen, die den Dubletten-Check durchführt und dazu den bereits erwähnten Eintrag aus „PersonTypeSettings“ zum Schlüssel „CharacteristicsForDuplicateSearch“ ZWINGEND benötigt (ansonsten gibt es zwar keinen Fehler, es wird aber auch nichts weiter ausgeführt) !

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:

• pm_ModifyPersonData_Ad im Engine Playground öffnen

Unformatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_ModifyPersonData_Ad?PersonID=<value>&CharacteristicIDList=<value>&ValueList=<value>'

Mit xmllint ⁶⁾ formatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_ModifyPersonData_Ad?PersonID=<value>&CharacteristicIDList=<value>&ValueList=<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'),
	'pm_ModifyPersonData_Ad',
		array(
			'PersonID' => <value>,
			'CharacteristicIDList' => '<value>',
			'ValueList' => '<value>',
			// 'PersonCharacCategoryID' => 1,
			// 'DeleteCharacCategoryID' => 0,
			// 'ResultInErrorIDList' => 1,
			// 'ValueIDsForPredefinedCharacs' => 1,
			// 'ChangeAllOrNothing' => 1,
			// 'Country' => 'german',
			// 'SeparatorInValueList' => '¶'
		)
);
 
$service->execute($request);
 
			$xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument();
			$ResultSet = $xml_result->getRowsAsArray();
 
$OutputParams = $xml_result->getOutputParametersAsArray();

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="pm_ModifyPersonData_Ad">
			<Parameters>
				<Parameter Name="PersonID"><!-- integer value --></Parameter>
				<Parameter Name="CharacteristicIDList"><!-- varchar value --></Parameter>
				<Parameter Name="ValueList"><!-- varchar value --></Parameter>
				<!-- <Parameter Name="PersonCharacCategoryID">1</Parameter> -->
				<!-- <Parameter Name="DeleteCharacCategoryID">0</Parameter> -->
				<!-- <Parameter Name="ResultInErrorIDList">1</Parameter> -->
				<!-- <Parameter Name="ValueIDsForPredefinedCharacs">1</Parameter> -->
				<!-- <Parameter Name="ChangeAllOrNothing">1</Parameter> -->
				<!-- <Parameter Name="Country">'german'</Parameter> -->
				<!-- <Parameter Name="SeparatorInValueList">'¶'</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>