Importiert Personendaten (eines Personen-Typs) aus den Schnittstellen-Tabellen „ImportPersonData_New“ (neue Personen) und „ImportPersonData_Modify“ (Änderungen von Eigenschaften bestehender Personen) sowie „Details“ aus den Schnittstellen-Tabellen „ImportPersonDetails_New“ und „ImportPersonDetails_Modify“.

Ist nicht bekannt, ob eine Person bereits im „dStore“ existiert oder nicht (kann also nicht entschieden werden, ob ein Datensatz in die „…New“- oder die „…Modify“-Tabelle gehört), können die Daten auch in die Tabelle „ImportPersonData_NewOrModify“ bzw. (für „Details“) „ImportPersonDetails_NewOrMod“ eingefügt werden.

Anmerkungen zu den Parametern „IdentifyingCharacteristicID“und „IdentValuesAreCaseSensitive“:

1. Bei den „…Modify“- bzw. „…NewOrModify“-Tabellen wird eine Person durch die Spalte „IdentifyingValue“ referenziert. Diese Eigenschaft muß sich natürlich auf ein Merkmal beziehen - daher der Parameter „IdentifyingCharacteristicID“ !
Dieses Merkmal muß „Unique“ und dem Typ „PersonTypeID“ zugeordnet sein !
„IdentValuesAreCaseSensitive“ enthält die Information, ob die „IdentifyingValue“-Werte case-sensitiv angegeben sind („1“) oder nicht („0“) - letzteres bedeutet natürlich einen gewissen Performance-Verlust !
2. Es ist möglich, über die intern vom „dStore“ verwendete „PersonID“ (die systemweit eindeutig eine Person kennzeichnet) zu referenzieren, indem man für „IdentifyingCharacteristicID“ den Wert „0“ angibt; dies bedeutet dann, daß es sich bei den „IdentifyingValue“-Werten um „PersonID“s handelt. Insbesondere hat „IdentValuesAreCaseSensitive“ in diesem Fall natürlich keine Bedeutung mehr.

Hinweise zu „ImportPersonData_New“ :
1. Die „PersonNo“s müssen zwingend „>= 1“ sein. Es SOLLTEN außerdem keine Lücken zwischen den „PersonNo“s sein. Es gibt zwar keinen Fehler, aber es werden u.U. nicht immer „MaxNumberOfPersonsToBeImportedSimultaneously“ (Eintrag in „PersonTypeSettings“ zur „PersonTypeID = 0“) Personen pro Durchlauf importiert, obwohl dies theoretisch möglich wäre.
2. Außerdem gibt es keine Gewähr, daß der Import funktioniert, wenn die Daten nicht nach „PersonNo“ gruppiert sind !

Hinweis zu „ImportPersonData_Modify“ :

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 der Spalte „PersonCharacteristicID“ von „ImportPersonData_Modify“, wobei je nach Datentyp des Merkmals der entsprechende Wert in „Value“ unterschiedliche Formen annehmen muß und entsprechend unterschiedlich interpretiert wird :

A) Ist das Merkmal vom Basis-Typ „Zahl“, muß „Value“ 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. „Value“ 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ß „Value“ 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 ein Datensatz in „ImportPersonData_Modify“ mit „PersonCharacteristicID = -17“ und „ Value = '-5' “ dazu führen, daß die aktuelle Eigenschaft der entsprechenden (sprich : durch „IdentifyingValue“ referenzierten) Person zum Merkmal „17“ um „5“ ERNIEDRIGT wird.
2.) Stellt „19“ die ID eines „Datum-Merkmals“ dar, und besitzt eine Person aktuell als Eigenschaft den Wert „01.04.1968“, würde ein Datensatz in „ImportPersonData_Modify“ zu dieser Person (durch „IdentifyingValue“ referenziert) mit „PersonCharacteristicID = -19“ und „ Value = '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 Datensatz in „ImportPersonData_Modify“ mit „PersonCharacteristicID = -20“ und „ Value = '-not ' “ würde, wenn die entsprechende (sprich : durch „IdentifyingValue“ referenzierte) Person 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

Hinweis zu „PersonDetails“ :
1. Zum Import von „PersonDetails“ stehen die drei Tabellen „ImportPersonDetails_NewOrMod“, „ImportPersonDetails_New“ und „ImportPersonDetails_Modify“ zur Verfügung, wobei für „ImportPersonDetails_New“ gilt, daß die „PersonNo“ natürlich zur „PersonNo“ von „ImportPersonData_New“ korrespondiert - insbesondere werden Datensätze mit „PersonNo“s, die überhaupt nicht in „ImportPersonData_New“ vorkommen erst gar nicht beachtet !
2. Details zu neu anzulegenden Personen, die durch „ImportPersonDetails_NewOrMod“ übergeben wurden, setzen analog voraus, daß der „IdentifyingValue“ auch in „ImportPersonData_NewOrModify“ vorkommt - ansonsten wird davon ausgegangen, daß die Details zu einer bestehenden Person gehören !

Hinweise zur Protokollierung fehlerhafter Datensätze :
1. Fehlerhafte Datensätze werden (sofern „LogErrors = 1“ angegeben wird) in „ImportPersonData_New_Errors“ bzw. „ImportPersonData_Modify_Errors“ eingetragen.
2. Für Daten aus „ImportPersonData_NewOrModify“ gibt es keine separate „Errors“-Tabelle, da diese Prozedur vor dem eigentlichen Import für jeden Datensatz aus dieser Tabelle überprüft, ob der „IdentifyingValue“ bereits existiert und dann den entsprechenden Datensatz entweder in „ImportPersonData_New“ oder „ImportPersonData_Modify“ einfügt !
3. Es gibt keine „Error“-Protokollierung für „Details“, da es keinerlei Einschränkungen gibt. Es muß lediglich eine offensichtliche Vorraussetzung gegeben sein : die „PersonCharacteristicID“ muß vorhanden sein ! Das Merkmal muß aber noch nicht einmal dem Personen-Typ zugeordnet sein…

Die Error-Codes in „ImportPersonData_New_Errors“ haben jeweils folgende Bedeutung :

• 1 : Die Eigenschaft wird nicht übernommen, da sie zu einem Merkmal gehört, das nicht dem Personentyp zugeordnet ist
• 2 : Der Wert ist ungültig, d.h. entspricht nicht dem Feldtyp des zugehörigen Merkmals
• 3 : Die Eigenschaft ist nicht eindeutig, d.h. es gibt eine Person mit dem gleichen Wert zum entsprechenden Merkmal
• 4 : Der Datensatz wurde nicht importiert, da nicht alle Pflichtmerkmale vorhanden sind
• 5 : Die Eigenschaft kann aufgrund einer Zugriffsbeschränkung nicht übernommen werden
• 6 : Die „Details“ können aufgrund einer Zugriffsbeschränkung nicht übernommen werden
• 7 : Die Details können nicht übernommen werden, da das Merkmal nicht dem Personentyp zugeordnet ist

Die Error-Codes in „ImportPersonData_Modify_Errors“ haben jeweils folgende Bedeutung :

• 0 : unbekannter Fehler, bitte an den Hersteller wenden
• 1 : Die Eigenschaft wird nicht übernommen, da sie zu einem Merkmal gehört, das nicht dem Personentyp zugeordnet ist
• 2 : Der Wert ist ungültig, d.h. entspricht nicht dem Feldtyp des zugehörigen Merkmals
• 3 : Die Eigenschaft ist nicht eindeutig, d.h. es gibt eine Person mit dem gleichen Wert zum entsprechenden Merkmal
• 4 : Eigenschaften zu Pflichtmerkmalen können nicht gelöscht werden. Auch können keine Eigenschaften zu „Kategorie-Pflichtmerkmalen“ gelöscht werden, wenn es nach dem Löschen noch andere Eigenschaften der betreffenden Kategorie gibt.
• 5 : Es sollte eine „relative Änderung“ durchgeführt werden, aber der relative Wert hat das falsche Format
• 6 : Es sollte eine „relative Änderung“ durchgeführt werden, aber der Ergebnis-Wert hat das falsche Format
• 7 : Die Eigenschaft kann aufgrund einer Zugriffsbeschränkung nicht übernommen/gelöscht werden
• 8 : Die „Details“ können aufgrund einer Zugriffsbeschränkung nicht übernommen/gelöscht werden
• 9 : Die Details können nicht übernommen werden, da das Merkmal nicht dem Personentyp zugeordnet ist
• 255 : Die Änderung dieser Eigenschaft wurde nicht durchgeführt - Ursache kann nicht eindeutig festgestellt werden.

Mögliche Ursachen für „ErrorCode = 255“ :

• Nach der Überprüfung der Daten am Anfang der Schnittstelle, aber vor dem Zuweisen der Eigenschaften in „PersonProperties“, wurde die Eigenschaft (z.B. durch den parallelen Aufruf von pm_ModifyPersonData_Ad/„…_Pu“) aus „PersonCharacteristicValues“ gelöscht
• Direkt nach der (möglicherweise durchaus erfolgreichen und richtigen) Änderung durch die Schnittstelle wurde die Eigenschaft (durch einen Aufruf von pm_ModifyPersonData_Ad/„…_Pu“) wieder geändert

Hinweis : Dieser Error-Code kann nur auftreten, wenn „VerifyChanges = 1“ angegeben wurde !

Anmerkungen zum Parameter „HowManyCharacteristics“ :
1. Er gibt an, wieviele verschiedene Merkmale („PersonCharacteristicID“s) in „ImportPersonData_New“ stehen. Dieser Wert wird intern für die Begrenzung der Datensätze, die maximal gleichzeitig importiert werden, benötigt (siehe „PersonTypeSettings“-Eintrag zur „PersonTypeID = 0“ zum Schlüssel „MaxNumberOfPersonsToBeImportedSimultaneously“). Hintergrund hierfür sind Massen-Imports, für die zum einen das Transaktions-Log nicht groß genug ist, zum anderen kann man hierdurch letztlich die Transaktions-Dauer pro Durchlauf verkürzen, was für konkurrierende Zugriffe vorteilhaft ist.
2. Übergibt man „HowManyCharacteristics = NULL“, ermittelt die Prozedur den Wert (via „SELECT COUNT(DISTINCT PersonCharacteristicID)…“) selbst.

Allgemeiner Hinweis :
Es werden folgende „Settings“- bzw. „PersonTypeSettings“-Einträge verwendet :

• „MaxNumberOfPropertiesToBeModifiedSimultaneously“ (optional, Tabelle : „PersonTypeSettings“)
• „MaxNumberOfPersonsToBeImportedSimultaneously“ (optional, Tabelle : „PersonTypeSettings“)
• „DumpPath“ (optional, Tabelle : „Settings“)

Die Prozedur hat keine Rückgaben.

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

Unformatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_ImportPersonData_Ad'

Mit xmllint ⁵⁾ formatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_ImportPersonData_Ad' | 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_ImportPersonData_Ad',
		array(
			// 'PersonTypeID' => 1,
			// 'HowManyCharacteristics' => NULL,
			// 'DumpTransaction' => 0,
			// 'Country' => 'german',
			// 'IdentifyingCharacteristicID' => 1,
			// 'VerifyChanges' => 0,
			// 'LogErrors' => 1,
			// 'IdentValuesAreCaseSensitive' => 1,
			// 'EmptyStringToDeleteDetails' => 0,
			// 'IgnEmptStrInNOrMTabForNewPers' => 0
		)
);
 
$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_ImportPersonData_Ad">
			<Parameters>
				<!-- <Parameter Name="PersonTypeID">1</Parameter> -->
				<!-- <Parameter Name="HowManyCharacteristics">NULL</Parameter> -->
				<!-- <Parameter Name="DumpTransaction">0</Parameter> -->
				<!-- <Parameter Name="Country">'german'</Parameter> -->
				<!-- <Parameter Name="IdentifyingCharacteristicID">1</Parameter> -->
				<!-- <Parameter Name="VerifyChanges">0</Parameter> -->
				<!-- <Parameter Name="LogErrors">1</Parameter> -->
				<!-- <Parameter Name="IdentValuesAreCaseSensitive">1</Parameter> -->
				<!-- <Parameter Name="EmptyStringToDeleteDetails">0</Parameter> -->
				<!-- <Parameter Name="IgnEmptStrInNOrMTabForNewPers">0</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>