Benutzer-Werkzeuge

Webseiten-Werkzeuge


engine:procedures:pm_setpropertyofoneperson_pu

pm_SetPropertyOfOnePerson_Pu

„public“-Prozedur, um eine Eigenschaft einer Person zu setzen ohne daß die übliche Identifizierung (wie etwa bei pm_ModifyPersonData_Pu) durchgeführt wird.

Allgemein Erläuterungen :

Sofern zum Typ „PersonTypeID“ EINDEUTIG eine Person mit der Eigenschaft „IdentifyingValue“ zum Merkmal „IdentifyingCharacteristicID“ gefunden wird UND der richtige „SecretKey“ übergeben wird, setzt diese Prozedur die Eigenschaft der identifizierten Person zum Merkmal „SetValueForCharacteristicID“ auf den Wert „NewValue“.

Hintergrund für diese Prozedur sind Anwendungen, in denen die Identifizierung z.B. durch „eMail“ und „Paßwort“ erfolgt, und man es ermöglichen möchte, daß (falls die Person ihr Paßwort vergessen hat) ein neues Paßwort gesetzt und dann an die eMail-Adresse geschickt wird.

Anmerkung zum Parameter „SecretKey“ :

Der „SecretKey“ wird durch „_mi_VerifySecretKey“ überprüft. In dieser Prozedur ist ein zufälliger String „hart codiert“, mit dem „SecretKey“ übereinstimmen muß. „_mi_VerifySecretKey“ muß durch den „sa“-Benutzer mit Hilfe von „_mi_Create_mi_VerifySecretKey“ neu erstellt werden (per default wird nämlich immer „-500“ zurückgegeben).
Der „sa“-Benutzer ist dann der einzige, der den Schlüssel kennt, und bestimmt dann, wer bzw. welche Applikation diesen Schlüssel verwenden und somit diese Prozedur hier ausführen kann.

Anmerkung zum Parameter „NewValue“ :

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

A) Ist das Merkmal vom Basis-Typ „Zahl“, muß „NewValue“ 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. „NewValue“ 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ß „NewValue“ 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 „SetValueForCharacteristicID = 17“ und „ NewValue = '-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 „SetValueForCharacteristicID = 19“ und „ NewValue = '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 „SetValueForCharacteristicID = 20“ und „ NewValue = '-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
HTTP-MethodPOST
HTTP-AuthOptional
Tags
Engine-Kategorieperson management
Engine-TypDaten-Änderung
Letzte Aktualisierung6.5.2 (2013-02-26)

Parameter

Name 1) Standard-Wert Beschreibung 2) SQL-Datentyp3) ab Version
PersonTypeID ID des Personen-Typs dem die zu identifizierende Person (für die eine Eigenschaft geändert werden soll) angehört
tinyint4.0.4
IdentifyingCharacteristicID ID eines Merkmals, auf das sich „IdentifyingValue“ bezieht. Vorraussetzung ist, daß es sich um ein „eindeutiges“ („IsUnique = 1“ in „PersonCharacteristics“) Merkmal handelt, das außerdem dem Personen-Typ „PersonTypeID“ zugeordnet sein muß !
smallint4.0.4
IdentifyingValue Eigenschaft (zum Merkmal „IdentifyingCharacteristicID“), die EINDEUTIG eine Person (des Typs „PersonTypeID“) identifiziert
varchar(100)4.0.4
CaseSensitive1 „0“ : „IdentifyingValue“ ist bis auf Groß- und Kleinschreibung richtig
„1“ : „IdentifyingValue“ ist EXAKT angegeben
bit4.0.4
SecretKey Der „SecretKey“ wird durch „_mi_VerifySecretKey“ überprüft. In dieser Prozedur ist ein zufälliger String „hart codiert“, mit dem „SecretKey“ übereinstimmen muß - sonst gibt es den Fehler „-500“. (siehe Beschreibung)
char4.0.4
SetValueForCharacteristicID ID eines Merkmals, auf das sich die (neu zu setzende) Eigenschaft „NewValue“ bezieht. Die ID muß im „PersonTypeSettings“-Eintrag „CharacIDsFor_pm_SetPropertyOfOnePerson_Pu“ zur „PersonTypeID“ konfiguriert sein !
smallint4.0.4
NewValue Die neue Eigenschaft (zum Merkmal „SetValueForCharacteristicID“), die für die identifizierte Person gesetzt werden soll. Falls es sich um einen Datums-Wert handelt, gibt „Country“ an, in welchem Format der Wert ist.
varchar(100)4.0.4
Country'german' Nur relevant, falls es sich bei „NewValue“ um einen Datums-Wert handelt. Gibt an, in welchem Format der Wert ist (Groß- und Kleinschreibung wird nicht beachtet) :
„german“ (oder „germany“) : Tag-Monat-Jahr
„english“ (oder „england“) : Monat-Tag-Jahr
varchar(10)4.0.4

Rückgabe

Die Prozedur hat keine Rückgaben.

Output-Parameter

Die Prozedur hat keine Output-Parameter.

Mögliche Return-Codes

Code Beschreibung Quelle 4)
-697Aktion kann nicht durchgeführt werden, da für ein Merkmal eine Zugriffsbeschränkung bestehtnur indirekt
-676Zum Merkmal sind nur vordefinierte Werte erlaubt, aber der Wert existiert noch nichtnur indirekt
-675Die Eigenschaft kann nicht gelöscht werden, da sie zu einem Pflicht-Merkmal gehörtnur indirekt
-660Identifikation fehlgeschlagennur direkt
-642Inkrementelle Änderung konnte aufgrund paralleler Änderungen nicht durchgeführt werdennur indirekt
-641Die „Unique“-Eigenschaft mindestens eines Merkmals ist verletzt - Prozedur wurde abgebrochennur indirekt
-621Fehlender oder falscher Eintrag in PersonTypeSettingsnur indirekt
-572Die Prozedur darf nur innerhalb einer Transaktion ausgeführt werdennur indirekt
-540Falsches Formatnur indirekt
-535Das Datum liegt nicht in der Vergangenheitnur indirekt
-530Der Wert ist nicht konvertierbarnur indirekt
-504Es ist ein Problem aufgetreten, das nicht gelöst werden kann, Prozedur wird daher abgebrochennur 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

6.5.2 2013-02-26Interne Anpassungen aufgrund des neuen features „Zugriffsbeschränkungen für Merkmale“
6.0.3 2011-09-07Unstellung der Identifizierung im Fall „CaseSensitive = 0“ auf die neue Tabelle „UniquePersonProperties“
5.5.0 2008-01-071. Ausgabe an die Standard-Ausgabe [via „print“] im Fehler-Fall „-500“, die nähere Informationen über die Ursache enthält
2. Bearbeitung des Quellcodes hinsichtlich neuer Konventionen
5.0.0 2004-12-21Hinweis in der Doku auf die neue Möglichkeit von „inkrementellen updates“
4.0.5 2003-10-04Verlagerung diverser „Settings“-Einträge auf entsprechende „PersonTypeSettings“-Einträge
4.0.4 2003-08-26Erstmalig 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_SetPropertyOfOnePerson_Pu?PersonTypeID=<value>&IdentifyingCharacteristicID=<value>&IdentifyingValue=<value>&SecretKey=<value>&SetValueForCharacteristicID=<value>&NewValue=<value>'

Mit xmllint 5) formatierte Ausgabe:

curl -X POST  'http://<partner>-<project>.dstore.de/default/engine/pm_SetPropertyOfOnePerson_Pu?PersonTypeID=<value>&IdentifyingCharacteristicID=<value>&IdentifyingValue=<value>&SecretKey=<value>&SetValueForCharacteristicID=<value>&NewValue=<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_SetPropertyOfOnePerson_Pu',
		array(
			'PersonTypeID' => <value>,
			'IdentifyingCharacteristicID' => <value>,
			'IdentifyingValue' => '<value>',
			'SecretKey' => <value>,
			'SetValueForCharacteristicID' => <value>,
			'NewValue' => '<value>',
			// 'CaseSensitive' => 1,
			// 'Country' => 'german'
		)
);
 
$service->execute($request);
 
			$xml_result = $request->getResponse()->getBody()->toSimpleXmlDocument();
			$ResultSet = $xml_result->getRowsAsArray();
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_SetPropertyOfOnePerson_Pu">
			<Parameters>
				<Parameter Name="PersonTypeID"><!-- tinyint value --></Parameter>
				<Parameter Name="IdentifyingCharacteristicID"><!-- smallint value --></Parameter>
				<Parameter Name="IdentifyingValue"><!-- varchar value --></Parameter>
				<Parameter Name="SecretKey"><!-- char value --></Parameter>
				<Parameter Name="SetValueForCharacteristicID"><!-- smallint value --></Parameter>
				<Parameter Name="NewValue"><!-- varchar value --></Parameter>
				<!-- <Parameter Name="CaseSensitive">1</Parameter> -->
				<!-- <Parameter Name="Country">'german'</Parameter> -->
			</Parameters>
		</Procedure>
	</Batch>
</ListOfBatches>
1)
Pflichtparameter sind unterstrichen
4)
direkt meint „von der Prozedur selber“ und indirekt meint „von intern aufgerufenen Unterprozeduren“
5)
I.d.R. auf Unix-artigen Systemen bereits installiert, Bestandteil der libxml2, siehe http://www.xmlsoft.org
engine/procedures/pm_setpropertyofoneperson_pu.txt · Zuletzt geändert: 11.01.2016 (Externe Bearbeitung)