Benutzer-Werkzeuge

Webseiten-Werkzeuge


engine:procedures:pm_checkpersonidentity_pu

pm_CheckPersonIdentity_Pu

Zentrale Prozedur zur Identifizierung einer Person. Wann immer (bis auf wenige Ausnahmen) eine Prozedur Identifizierungsdaten fordert (wie z.B. fo_GetPostingThread_Pu, co_LoginIntoCommunity_Pu, „au_GetAuctionItems_Pu“ usw.), wird letztlich diese Prozedur ausgeführt ! Daher sollte man unbedingt das grundlegende „Personen-Besucher-Konzept“ des „dStore“ verstanden haben. Hierzu einige Anmerkungen :

Es ist immer eine sogenannte „UniqueID“ erforderlich (→ Parameter „UniqueID“), die (eindeutig) einen Besucher (aus der Tabelle „Visitors“) kennzeichnet ! Sollte kein Datensatz in „Visitors“ zur angegebenen „UniqueID“ existieren, legt die Prozedur IMMER automatisch einen neuen Besucher an, wobei als Sprache und Währung die Werte aus „Settings“ (zu den Schlüsseln „DefaultLanguageID“ und „DefaultCurrencyID“) gewählt werden, und das Land („CountryID“) mit „0“ belegt wird.

Hintergrund hierfür sind anonyme, Besucher-bezogene Daten (z.B. der „Warenkorb“, Statistiken wie „Views“ etc.), die man möglichst immer mit einer bekannten (also ENTanonymisierten) Person in Verbindung bringen möchte. Welcher Besucher mit welcher Person in Verbindung steht, wird (immer für einen Zeitraum) in der Tabelle „VisitorPersons“ gespeichert.

Für den Identifizierungs-Vorgang gibt es nun zwei Möglichkeiten :

1. Die Parameter „PersonIdentificationValues“, „PersonTypeID“ UND „UniqueID“ werden angegeben. Anhand der „PersonIdentificationValues“ versucht die Prozedur, eine gültige „PersonID“ zu ermitteln. Gelingt dies, werden automatisch die Identifizierungsdaten in „SessionManagement“ zur „UniqueID“ zum Schlüssel „PersonIdentificationValues_Type<PersonTypeID>“ bzw. „PersonGrantAccessValues“ (je nach „GrantAccessValues“, s.u.) gespeichert.
Sofern keine der zur Identifizierung beitragenden Eigenschaften das Zeichen „¶“ enthält, wird „¶“ als Trennzeichen der Identifizierungsdaten verwendet. Andernfalls wird versucht, ein anderes Zeichen zu finden, und falls dies gelingt, wird neben den Identifizierungsdaten auch in „SessionManagement“ gespeichert, was dieses Zeichen ist - und zwar zu diesem Schlüssel :
'Separator_' + <Name des Schlüssels, zu dem die Identifizierungsdaten gespeichert wurden>

Anschließend werden die Warenkörbe aller Besucher, die der soeben identifizierten Person zugeordnet sind, „zusammengelegt“, d.h. dem Besucher „UniqueID“ zugeordnet. Das Zusammenlegen der Warenkörbe kann grundsätzlich verhindert werden, indem man den „Settings“-Eintrag „MergeTrolleys“ entsprechend konfiguriert.
Schließlich wird dieser Besucher der identifizierten Person zugeordnet.
ACHTUNG :
Man kann auch '' für „UniqueID“ übergeben (Vorrausgesetzt, es existiert eine gültige „VisitorID“ dazu), womit man signalisiert, daß nach erfolgreicher Identifizierung die Identifizierungs-Daten NICHT in „SessionManagement“ gespeichert und auch kein Abgleich der Warenkörbe durchgeführt werden soll(en).

2. Man speichert zur „UniqueID“ des Besuchers (→ „UniqueID“) in „SessionManagement“ die Identifizierungsdaten (via mi_ModifySessionManagement_Pu) und ruft diese Prozedur dann „ohne PersonIdentificationValues“ auf. In diesem Fall holt sich die Prozedur selbst die Identifizierungsdaten aus „SessionManagement“ - zum Schlüssel „PersonIdentificationValues_Type<PersonTypeID“ bzw. „PersonGrantAccessValues“ (je nach „GrantAccessValues“, s.u.) - und versucht anhand dieser Daten eine gültige „PersonID“ zu ermitteln. Anschließend wird die Prozedur beendet, es finden also keine weiteren Aktionen wie im 1. Fall statt !
Hinweis : Wir gehen davon aus, daß „¶“ als Trennzeichen der Identifizierungsdaten dient. Ist dies nicht der Fall (z.B. weil eine zur Identifizierung beitragende Eigenschaft das Zeichen „¶“ enthält), muß ein weiterer Eintrag in „SessionManagement“ gemacht werden (der als Wert logischerweise das tatsächlich gewählte Trennzeichen enthält), und zwar zu diesem Schlüssel :
'Separator_' + <Name des Schlüssels, zu dem die Identifizierungsdaten gespeichert wurden>

Nocheinmal zur Erinnerung : Wann immer eine Prozedur (fo_GetPostingThread_Pu etc.) die drei Parameter „PersonIdentificationValues“, „PersonTypeID“ (manchmal, wie etwa im Community-Modul, erübrigt sich dieser Parameter) und „UniqueID“ fordert, wird letztlich pm_CheckPersonIdentity_Pu aufgerufen und somit eine der beiden eben beschreibenen Identifizierungs-Vorgänge ausgelöst !

Anmerkungen zu den Parametern „GrantAccessValues“ und „IdentificationIDs“ :

Es gibt grundsätzlich zwei Arten von Identifizierungsdaten : Einmal die sogenannten „PersonIdentificationValues“ pro Personentyp, zum anderen gibt es Personentyp-unabhängige „PersonGrantAccessValues“ (s. Dokumentation der Schlüssel „PersonIdentificationIDs“ und „PersonGrantAccessIDs“ in „PersonTypeSettings“). Welche von den beiden verwendet werden soll, ist via „GrantAccessValues“ anzugeben.

Desweiteren gibt es zu den „PersonIdentificationIDs“ alternative IDs, die bei der Identifizierung verwendet werden sollen (wenn also „GrantAccessValues = 0“ ist) und auf die sich die „PersonIdentificationValues“ beziehen. Dazu ist (für den Personen-Typ „PersonTypeID“) der Eintrag „AlternativeIdentificationIDs“ zu konfigurieren und die Liste der IDs via „IdentificationIDs“ zu übergeben. Wenn besagter Parameter angegeben wird (also nicht „NULL“ ist), müssen die IDs also entweder exakt so in „AlternativeIdentificationIDs“ vorkommen (weil dort eine Liste von Listen konfiguriert werden kann, sprich MEHRERE Alternativen möglich sind) oder aber dem Eintrag „PersonIdentificationIDs“ entsprechen.

Anmerkung zum Parameter „CaseSensitive“ :

Hierbei ist zu bedenken, daß eine Identifizierung letztlich eine Art Personen-Suche darstellt (wie sie z.B. pm_GetPersons_Conditions_Ad bietet). Und diese Suche ist WESENTLICH effizienter, wenn vorrausgesetzt werden kann, daß die Eigenschaften EXAKT übereinstimmen.

WICHTIGE Zusatzbemerkung :

Die Reihenfolge der Merkmale, die in „PersonTypeSettings“ zum Schlüssel „PersonIdentificationIDs“ zur „PersonTypeID“ bzw. zum Schlüssel „PersonGrantAccessValues“ zur „PersonTypeID = 0“ hinterlegt sind, kann beliebig sein. Aus Performancegründen ist es jedoch DRINGEND zu empfehlen, zuerst ein „Unique“-Merkmal zu wählen !

HTTP-MethodPOST
HTTP-AuthOptional
Tags
Engine-Kategorieperson management
Engine-TypDaten-Ermittlung
Letzte Aktualisierung7.0.7 (2015-01-29)

Parameter

Name 1) Standard-Wert Beschreibung 2) SQL-Datentyp3) ab Version
PersonIdentificationValues Liste von Eigenschaften, die die Person identifizieren. Diese beziehen sich entweder auf Merkmal-IDs, die als „PersonIdentificationIDs“ oder „PersonGrantAccessIDs“ (s. „GrantAccessValues“) konfiguriert sind oder in „IdentificationIDs“ angegeben wurden.
varchar(255)3.5.0
PersonTypeID ID des Personen-Typs dem die zu identifizierende Person angehört. Dieser muß bei einer Identifizierung immer mit angegeben werden, da die Merkmale zur Identifizierung pro Personentyp variieren können. (Ausnahme : „GrantAccessValues = 1“, s. Beschreibung)
tinyint3.5.0
UniqueID Eindeutige ID eines Besuchers, die der zu identifizierenden Person zuzuordnen ist. Wenn die Identifizierungsdaten bereits in „SessionManagement“ (zur „UniqueID“) gespeichert sind, darf „PersonIdentificationValues“ „NULL“ sein bzw. den Wert '' enthalten.
varchar(50)3.5.0
SelectResult1 „0“ : Ergebnis nur über den Ausgabeparameter „PersonID“ ausgeben
„1“ : Die identifizierte Person ZUSÄTZLICH als Rückgabemenge ausgeben
bit3.5.0
GrantAccessValues0 Auf welche Merkmal-IDs sich die „PersonIdentificationValues“ beziehen :
„0“ : Zur „PersonTypeID“ konfigurierte „PersonIdentificationIDs“ oder zu „IdentificationIDs“
„1“ : Zur „PersonTypeID = 0“ konfigurierte „PersonGrantAccessIDs“
bit3.5.0
CaseSensitive1 „0“ : Der Vergleich der Identifizierungsdaten erfolgt unabhängig von der Groß- und Kleinschreibung
„1“ : Die Schreibweise der Daten muß exakt sein
(siehe auch Beschreibung !)
bit3.5.0
SeparatorInIdentVals'¶' Gibt an, durch welche Zeichenkette die Werte in „PersonIdentificationValues“ getrennt sind
varchar(4)5.5.0
IdentificationIDsNULL Liste von Merkmal-IDs (durch „¶“ getrennt), auf die sich die „PersonIdentificationValues“ im Fall „GrantAccessValues = 0“ beziehen. Falls angegeben, müssen diese als „PersonIdentificationIDs“ oder „AlternativeIdentificationIDs“ konfiguriert sein.
varchar(50)7.0.5

Rückgabe

wenn SelectResult = 1

Spaltenname Beschreibung SQL-Datentyp4) ab Version
PersonIDDie ID der ermittelten Person
integer3.5.0

Output-Parameter

PersonIDRückgabeparameter für die ID der ermittelten Person

Mögliche Return-Codes

Code Beschreibung Quelle 5)
-660Identifikation fehlgeschlagendirekt und indirekt
-621Fehlender oder falscher Eintrag in PersonTypeSettingsnur indirekt
-602Zur defaultUniqueID („VisitorID = -2“) können keinerlei Daten gespeichert oder verändert werdendirekt und indirekt
-599Lizenz ist ungültig oder abgelaufennur indirekt
-569Der Benutzer hat kein Ausführungsrecht für die Prozedurnur indirekt
-567Die Prozedur darf z. Zt. nicht ausgeführt werdennur indirekt
-566Die Prozedur darf mit den übergebenen Parametern nicht ausgeführt werdennur indirekt
-550Fehlender oder falscher Eintrag in Settingsnur indirekt
-535Das Datum liegt nicht in der Vergangenheitnur indirekt
-530Der Wert ist nicht konvertierbarnur indirekt
-510Der Benutzer ist nicht registriertnur indirekt
-504Es ist ein Problem aufgetreten, das nicht gelöst werden kann, Prozedur wird daher abgebrochennur indirekt
-502Die Parameter-Werte der Prozedur können nicht verarbeitet werden (kein passendes Trennzeichen)nur indirekt
-500Falsche Parameterdirekt und indirekt

XML-Schema

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

Historie

7.0.7 2015-01-29„Start-/Finish-Procedure“-Logik eingebaut, s. Ticket #3670
7.0.5 2014-05-26Neuer Parameter „IdentificationIDs“, s. Ticket #3624
6.5.2 2013-02-26Länge des Parameter „SeparatorInIdentVals“ wurde erweitert [von „1“ auf „4“]
6.0.6 2012-03-01Beachtung des neuen, speziellen Besuchers „defaultUniqueID“ - für den keine Daten-Speicherung/-Änderung erlaubt ist
5.5.0 2008-01-071. Implementierung des „Settings“-Eintrags „MergeTrolleys“
2. Ausgabe via „print“ im Fehler-Fall „-500“
3. Neuer Parameter „SeparatorInIdentVals“
4. Falscher Datentyp für „PersonTypeID“
5. Interne Änderungen
5.1.6 2006-09-14Verlagerung des Speicherns der [hinsichtlich Groß- und Kleinschreibung RICHTIGEN] Identifizierungsdaten in „SessionManangement“ in die neue [interne] Prozedur „_pm_SaveIdentValsInSessionMan]„
4.0.5 2003-10-04Verlagerung diverser „Settings“-Einträge auf entsprechende „PersonTypeSettings“-Einträge
4.0.0 2003-04-03Wenn Identifizierungsdaten übergeben werden, kann man durch „UniqueID = ''“ angeben, daß man (nach erfolgreicher Authentifizierung) die Identifizierungsdaten NICHT in „SessionManagemengt“ speichern möchte (bisher gab es “-500“)
3.5.16 2002-04-25
3.5.2 2001-01-28
3.5.0 2000-11-23Erstmalig in dieser Version erstellt

Code-Snippets

Engine Playground

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

cURL

Unformatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_CheckPersonIdentity_Pu?PersonIdentificationValues=<value>&PersonTypeID=<value>&UniqueID=<value>'

Mit xmllint 6) formatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_CheckPersonIdentity_Pu?PersonIdentificationValues=<value>&PersonTypeID=<value>&UniqueID=<value>' | xmllint --format -
dStore_php
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_CheckPersonIdentity_Pu',
		array(
			'PersonIdentificationValues' => '<value>',
			'PersonTypeID' => <value>,
			'UniqueID' => '<value>',
			// 'SelectResult' => 1,
			// 'GrantAccessValues' => 0,
			// 'CaseSensitive' => 1,
			// 'SeparatorInIdentVals' => '¶',
			// 'IdentificationIDs' => NULL
		)
);
 
$service->execute($request);
 
			$xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument();
			$ResultSet = $xml_result->getRowsAsArray();
 
$OutputParams = $xml_result->getOutputParametersAsArray();
engine/execute

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_CheckPersonIdentity_Pu">
			<Parameters>
				<Parameter Name="PersonIdentificationValues"><!-- varchar value --></Parameter>
				<Parameter Name="PersonTypeID"><!-- tinyint value --></Parameter>
				<Parameter Name="UniqueID"><!-- varchar value --></Parameter>
				<!-- <Parameter Name="SelectResult">1</Parameter> -->
				<!-- <Parameter Name="GrantAccessValues">0</Parameter> -->
				<!-- <Parameter Name="CaseSensitive">1</Parameter> -->
				<!-- <Parameter Name="SeparatorInIdentVals">'¶'</Parameter> -->
				<!-- <Parameter Name="IdentificationIDs">NULL</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>
1)
Pflichtparameter sind unterstrichen
5)
direkt meint „von der Prozedur selber“ und indirekt meint „von intern aufgerufenen Unterprozeduren“
6)
I.d.R. auf Unix-artigen Systemen bereits installiert, Bestandteil der libxml2, siehe http://www.xmlsoft.org
engine/procedures/pm_checkpersonidentity_pu.txt · Zuletzt geändert: 11.01.2016 (Externe Bearbeitung)