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 :
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 :
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 :
Die Error-Codes in „ImportPersonData_Modify_Errors“ haben jeweils folgende Bedeutung :
Mögliche Ursachen für „ErrorCode = 255“ :
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 :
HTTP-Method | POST |
HTTP-Auth | Optional |
Tags | |
Engine-Kategorie | person management |
Engine-Typ | Daten-Änderung |
Letzte Aktualisierung | 7.0.7 (2015-01-29) |
Name 1) | Standard-Wert | Beschreibung 2) | SQL-Datentyp3) | ab Version |
---|---|---|---|---|
PersonTypeID | 1 | ID eines Personen-Typs, zu dem Personendaten importiert werden sollen | tinyint | 3.5.0 |
HowManyCharacteristics | NULL | Anzahl der (verschiedenen) Merkmale („PersonCharacteristicID“s) zu denen Eigenschaften in der Import-Tabelle „ImportPersonData_New“ stehen (siehe Beschreibung) | tinyint | 3.5.0 |
DumpTransaction | 0 | Wird „1“ angegeben, führt die Schnittstelle - vor jedem Lauf des Einfügens NEUER Personen und - (einmalig) vor dem Abarbeiten der ÄNDERUNGEN von Personen-Eigenschaften die Prozedur mi_DumpTransactionLog_Ad aus | bit | 4.0.0 |
Country | 'german' | Gibt an, in welchem Format Datums-Eigenschaften (Spalte „Value“ in „ImportPersonData_New“ bzw. „…_Modify“) angegeben sind (Groß-/Kleinschreibung wird nicht beachtet) : 'german', 'germany' : Tag-Monat-Jahr 'english', 'england' : Monat-Tag-Jahr | varchar(10) | 4.0.5 |
IdentifyingCharacteristicID | 1 | Bei den „…Modify“- bzw. „…NewOrModify“-Tabellen wird eine Person durch die „IdentifyingValue“-Eigenschaft zum durch diese ID angegebenen Merkmal referenziert. „0“ bedeutet, daß „PersonID“s angegeben wurden. (s. a. Beschreibung !) | smallint | 4.0.6 |
VerifyChanges | 0 | „1“ angeben, um überprüfen zu lassen, ob die (durchführbaren, also nicht fehlerhaften) Änderungen anhand der Daten aus „ImportPersonData_Modify“ auch wirklich ausgeführt wurden (s.a. Beschreibung : „Die Error-Codes in „ImportPersonData_Modify_Errors“…“) | bit | 4.0.6 |
LogErrors | 1 | Ist „1“ angegeben, werden fehlerhafte Daten in „ImportPersonData_New_Errors“ bzw. „ImportPersonData_Modify_Errors“ eingetragen. Den Zeitpunkt, zu dem die Daten eingefügt wurden, kann man den beiden „ErrorDateAndTime…“-Ausgabeparametern entnehmen. | bit | 4.0.6 |
IdentValuesAreCaseSensitive | 1 | Nur relevant, falls „IdentifyingCharacteristicID“ ungleich „0“ ist ! Gibt an, ob die „IdentifyingValue“-Werte„ in den Schnittstellen-Tabellen exakt (sprich „case-sensitiv“) angegeben sind („1“) oder nur bis auf Groß- und Kleinschreibung stimmen („0“). | bit | 4.0.16 |
EmptyStringToDeleteDetails | 0 | Ist hier „1“ angegeben, bedeutet der sogenannte „leere string“ ('') in der Spalte „Details“ von „ImportPersonDetails_Modify“, daß ein evtl. vorhandener „Detail“-Wert gelöscht wird | bit | 5.0.3 |
IgnEmptStrInNOrMTabForNewPers | 0 | Gibt an, wie der „leere string“ ('') in einer der “…NewOrMod…„-Tabellen interpretiert werden soll, falls eine NEUE Person angelegt wird : - „0“ : '' als Eigenschaft/„Detail“ zuweisen - „1“ : KEINE Eigenschaft/„Detail“ anlegen | bit | 6.0.3 |
Die Prozedur hat keine Rückgaben.
ErrorDateAndTime_New | siehe „LogErrors“ |
ErrorDateAndTime_Modify | siehe „LogErrors“ |
Code | Beschreibung | Quelle 4) |
---|---|---|
-642 | Inkrementelle Änderung konnte aufgrund paralleler Änderungen nicht durchgeführt werden | nur indirekt |
-641 | Die „Unique“-Eigenschaft mindestens eines Merkmals ist verletzt - Prozedur wurde abgebrochen | nur indirekt |
-621 | Fehlender oder falscher Eintrag in PersonTypeSettings | nur indirekt |
-610 | Fehlende oder falsche Daten in PersonMetaInformation | nur indirekt |
-599 | Lizenz ist ungültig oder abgelaufen | nur indirekt |
-572 | Die Prozedur darf nur innerhalb einer Transaktion ausgeführt werden | nur indirekt |
-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 |
-565 | Die „Objekt-ID“ der Prozedur konnte nicht ermittelt werden | nur indirekt |
-564 | Der Status in BatchJobs konnte nicht gesetzt werden | nur indirekt |
-562 | Die Prozedur ist nicht in BatchJobs registriert | nur indirekt |
-560 | Prozedur konnte nicht gestartet werden | nur indirekt |
-550 | Fehlender oder falscher Eintrag in Settings | nur indirekt |
-540 | Falsches Format | nur indirekt |
-535 | Das Datum liegt nicht in der Vergangenheit | nur indirekt |
-530 | Der Wert ist nicht konvertierbar | nur indirekt |
-518 | Es ist eine bestimte ASE-Rolle erforderlich, die der Benutzer aber nicht besitzt | nur indirekt |
-510 | Der Benutzer ist nicht registriert | nur indirekt |
-505 | Es existiert ein anderer Prozeß, der ein „dump“ ausführt, Prozedur wird daher abgebrochen | 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.7 | 2015-01-29 | Interne Änderung : Datentyp-Erweiterung des „ReferenceKey“ [für „_mi_StartProcedure“-Aufruf] |
7.0.4 | 2014-03-19 | „set forceplan off“-Anweisung fehlte an einer Stelle |
6.5.2 | 2013-02-26 | 1. Doku-Änderung aufgrund des neuen features „Zugriffsbeschränkungen für Merkmale“ [⇒ neue mögliche „ErrorCodes“] 2. Interne Anpassungen wg. UTF8-Unterstützung |
6.0.5 | 2011-12-13 | Aufruf von „_pm_ImportPersons_New“ um den neuen Parameter „CheckRequiredInCatProps“ erweitert |
6.0.3 | 2011-09-07 | 1. Überarbeitung der Doku 2. Neuer Parameter „IgnEmptStrInNOrMTabForNewPers“ 3. Anpassung „print“-Ausgaben (u.a. Zeitausgaben nun in Millisek.) 4. Interne Anpassungen (u.a. Verw. von neuer Tabelle „UniquePersonProperties“) |
6.0.0 | 2010-03-26 | workaround für einen Bugs im ASE 15 bzgl. cursor, die „for update“ deklariert sind |
5.5.0 | 2008-01-07 | 1. Die intern verwendete Prozedur „_mi_TryToStartBatchJob“ unterstützt nun auch ein anderes Trennzeichen für die Parameter-Werte - wichtig bzgl. des „Country“-Parameters 2. Ausgabe via „print“ im Fehler-Fall “-500„ (mit Informationen über die Ursache) |
5.0.3 | 2005-06-07 | Neuer Parameter „EmptyStringToDeleteDetails“ |
5.0.1 | 2005-03-29 | Fehler : Wenn das Starten des Batch-Jobs fehlschlug wurde trotzdem „_mi_TryToFinishBatchJob“ aufgerufen, d.h. der Status wurde auf “-560„ gesetzt ! |
5.0.0 | 2004-12-21 | 1. Hinweis in der Doku auf die neue Möglichkeit von „inkrementellen updates“ 2. Änderungen/Erweiterungen der Error-Codes in „ImportPersonData_Modify_Errors“ 3. Fehler bei der Verteilung der Daten in “…NewOrModify„ |
4.0.16 | 2004-08-31 | 1. Ab jetzt kann über die „PersonID“ referenziert werden 2. Neuer Parameter „IdentValuesAreCaseSensitive“ 3. Daten können in „ImportPersonData_NewOrModify“ übergeben werden 4. Neue Möglichkeit „PersonDetails“ zu importieren |
4.0.15 | 2004-07-30 | 1. Aufruf der Prozeduren „_mi_StartProcedure“, „_mi_FinishProcedure“ und „_mi_ChooseParamValueSeperator“ 2. Ausführen von „set transaction isolation level 1“ und „set rowcount 0“ zu Beginn der Prozedur |
4.0.8 | 2004-02-20 | Interne Änderungen |
4.0.7 | 2004-01-16 | 1. Verwendung der neuen Prozedur „_mi_TryToFinishBatchJob“ zum Setzen des Status am Schluß 2. Neue Möglichkeit von „_mi_TryToStartBatchJob“ die Parameter-Werte automatisch in „BatchJobParameters“ einfügen zu lassen |
4.0.6 | 2003-11-14 | Komplette Umstrukturierung der Schnittstelle |
4.0.5 | 2003-10-04 | 1. Verlagerung diverser „Settings“-Einträge auf entsprechende „PersonTypeSettings“-Einträge 2. Die Parameter „HowManyCharacteristics“ und „DumpTransaction“ wurden bisher nicht in „BatchJobParameters“ festgehalten 3. Neuer Parameter „Country“ |
4.0.0 | 2003-04-03 | 1. Neuer Parameter „DumpTransaction“ 2. „_pm_ImportPersons“ bzw. „_pm_ModifyPersons“ nur aufrufen, wenn auch Daten in „ImportPersonData“ bzw. „ModifyPersonData“ vorhanden sind ! 3. Verwendung von „_mi_TryToStartBatchJob“ 4. Überarbeitung der Doku |
3.5.0 | 2000-11-23 | 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/pm_ImportPersonData_Ad'
Mit xmllint 5) 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>