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

Anmerkungen zum Identifizierungs-Vorgang :

Anhand der „IdentificationValues“ und der „PersonTypeID“ versucht die Prozedur, eine gültige „PersonID“ zu ermitteln.

Es gibt grundsätzlich zwei Arten von Identifizierungsdaten : Einmal die Personentyp abhängigen (die sogenannten „PersonIdentificationValues“), zum anderen die Personentyp UNabhängigen (die sogenannten „PersonGrantAccessValues“).
Der Sinn für diese Unterscheidung liegt darin, daß man für bestimmte Aktionen eine Identifizierung haben möchte, die nur sehr schwer vorzutäuschen ist. Für eine Bestellung wird meistens lediglich eine Kundennummer sowie der Nachname gefordert. An diese Daten kann ein Dritter allerdings relativ leicht gelangen. Soll es hingegen z.B. möglich sein, daß ein Kunde auch seine persönlichen Daten (Lieferanschrift etc.) ändern kann, wie durch diese Prozedur, ist es durchaus sinnvoll, hierfür einen stärkeren Authentifizierungs-Mechanismus zu fordern (so etwas wie eine PID und/oder ein Passwort z.B.).

Der Parameter „PersonGrantAccessIDs“ entscheidet nun, welche der beiden Identifizierungs-Wege gewählt wird. Da es sich hierbei um einen Parameter der Prozedur handelt, bietet der „dStore“ natürlich KEINE GEWÄHR, daß die Identifizierung auf dem einen und nicht auf dem anderen Wege stattfindet - dies muß in der Client-Anwendung sichergestellt werden !

Anmerkungen zum Parameter „ValueList“ :

1. Soll eine Eigenschaft zu einem Merkmal gelöscht werden, ist in der Werte-Liste an der entsprechenden Stelle „nichts“ anzugeben. Beispiel : 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.

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 „Zahl“ 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 entsprich

Anmerkung zum Parameter „PersonID“ :

Im Normalfall braucht dieser Parameter nicht angegeben zu werden, es sei denn, es soll zum Beispiel eine „Lieferanschrift“ geändert werden, also Daten zu einer ANDEREN Person als die, die sich aus den Identifizierungsdaten ergibt. Natürlich klappt dies nur, wenn eine bestimmte „Beziehung“ der identifizierten Person zur „PersonID“ besteht :
1. Zugriff ist erlaubt, wenn die identifizierte Person Auftraggeber eines Auftrags ist, bei dem „PersonID“ die Lieferanschrift („DeliveryPersonID“) ist UND der „PersonTypeSettings“-Eintrag zum Schlüssel „UnlimitedAccessToDeliveryPersonData“ (zur „PersonTypeID = 0“) auf „1“ konfiguriert ist. In diesem Fall besteht schreibender Zugriff auf Eigenschaften zu ALLEN Merkmalen.
2. Andernfalls ist der Zugriff nur erlaubt, wenn aktuell eine Beziehung der identifizierten Person zur „PersonID“ besteht, deren „AccessLevel“ (s. gleichnamige Rückgabespalte von pm_GetPersonRelationships_Pu) dies erlaubt. Zu welchen Merkmalen aber Eigenschaften geändert werden dürfen, regelt ein „RelationshipSettings“-Eintrag zum Schlüssel „AllowedCharacIDs_Write“ (siehe auch „Hinweis“ in pm_GetRelationshipSettingEntry).

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_Pu im Engine Playground öffnen

Unformatierte Ausgabe:

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

Mit xmllint ⁶⁾ formatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_ModifyPersonData_Pu?CharacteristicIDList=<value>&ValueList=<value>&IdentificationValues=<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_Pu',
		array(
			'CharacteristicIDList' => '<value>',
			'ValueList' => '<value>',
			'IdentificationValues' => '<value>',
			// 'PersonID' => NULL,
			// 'PersonTypeID' => 1,
			// 'PersonGrantAccessIDs' => 1,
			// 'PersonCharacCategoryID' => 1,
			// 'DeleteCharacCategoryID' => 0,
			// 'ResultInErrorIDList' => 1,
			// 'ValueIDsForPredefinedCharacs' => 1,
			// 'ChangeAllOrNothing' => 1,
			// 'CaseSensitive' => 1,
			// 'Country' => 'german',
			// 'SeparatorInValueList' => '¶',
			// 'SeparatorForIdentValues' => '¶'
		)
);
 
$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_Pu">
			<Parameters>
				<Parameter Name="CharacteristicIDList"><!-- varchar value --></Parameter>
				<Parameter Name="ValueList"><!-- varchar value --></Parameter>
				<Parameter Name="IdentificationValues"><!-- varchar value --></Parameter>
				<!-- <Parameter Name="PersonID">NULL</Parameter> -->
				<!-- <Parameter Name="PersonTypeID">1</Parameter> -->
				<!-- <Parameter Name="PersonGrantAccessIDs">1</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="CaseSensitive">1</Parameter> -->
				<!-- <Parameter Name="Country">'german'</Parameter> -->
				<!-- <Parameter Name="SeparatorInValueList">'¶'</Parameter> -->
				<!-- <Parameter Name="SeparatorForIdentValues">'¶'</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>