2.5.3. Erzeugen einer neuen Telefonnotiz im Posteingang
Dieses Beispiel demonstriert das Anlegen einer Telefonnotiz im Posteingang. Die RPC Funktion, die Elemente erzeugt, ist die Methode "New_()" des Dienstes GhRpcItemslibRpcItems aus der Unit rpc_itemslib.
Der Unterstrich am Ende des Methodennamens wurde angefügt, da in PHP die Bezeichnung "new" unabhängig von Groß- und Kleinschreibung ein reserviertes Schlüsselwort ist (die Original RPC Funktion heißt "New" ohne Unterstrich).
Die Methode "New_()" verlangt zwei Parameter. Der erste sind die Daten des zu erzeugenden Elements (vom Typ GhRpcItemslibRpcDetailedItem), der zweite Parameter gibt an, ob das Element in gesperrtem Zustand erzeugt werden soll oder nicht.
Das Datenobjekt wird in diesem Beispiel über die Hilfsmethode "rpc_itemslib::newRpcDetailedItem()" erzeugt, der Parameter "true" gibt dabei an, dass das Datenobjekt bereits mit leeren Arrays bzw. leeren untergeordneten Datenobjekten in den Objekteigenschaften befüllt sein soll. Das vereinfacht den Quellcode, da dann beispielsweise nicht für den Inhalt des Elements ("$call->Properties->Call->EditorData") die Objekteigenschaften jeweils mit manuell erzeugten leeren Objekten befüllt werden müssen.
Einige Werte des Datenobjekts müssen gesetzt werden, beispielsweise der Typ des Elements. Da eine Telefonnotiz erzeugt werden soll, wird die Eigenschaft "Kind" auf die Konstante "rpc_itemslib::ikCall" gesetzt (der Prefix "ik..." steht hier für "item kind").
Analog zu diesem Beispiel können auf gleichem Weg auch andere Element-Typen (z.B. Notizen) erzeugt werden. In dem Fall wird die Objekteigenschaft "Kind" mit einem anderen Elementtyp belegt (z.B. "rpc_itemslib::ikNote" für Notizen).
Der Status der Telefonnotiz soll "offen" sein, daher wird die Eigenschaft "State" auf die Konstante "rpc_itemslib::isOpen" gesetzt (hier steht der Prefix "is..." für "item state"). Der Inhalt der Telefonnotiz soll als HTML-Seite angegeben werden, daher wird in dem Set "Flags" des Elements die Option "ifUseHtml" gesetzt ("if..." steht hier für "item flag"). Die Priorität wird ebenfalls explizit auf "rpc_itemslib::ipNormal" ("ip..." steht hier für "item priority") gesetzt. Würde dies unterlassen, so würde für diese Eigenschaft der Wert 0 verwendet, was der Priorität "sehr niedrig" entspricht.
Die Gruppe, in der das Element angelegt werden soll, muss ebenfalls festgelegt werden. Hier wird im Beispiel die ID 1 eingetragen. Falls in den Profileinstellungen für den Benutzer der RPC Schnittstelle (in diesem Beispiel ist das der Benutzername "tester") eine Themenzuweisungspflicht für Telefonnotizen festgelegt wurde, so wird das Erzeugen des Elements fehlschlagen wenn nicht zusätzlich die Eigenschaft "TopicRef" mit der ID des gewünschten Themas befüllt wird. In diesem Beispiel wird kein Thema festgelegt, die Eigenschaft "TopicRef" also nicht befüllt.
Weiterhin werden der Betreff (Eigenschaft "Subject") und der Absender festgelegt. Der Absender wird in der Eigenschaft "From" gespeichert und muss ein Objekt vom Typ GhRpcItemslibRpcAddressItem sein. Da das Objekt "$call" mit "leeren" Objekten befüllt wurde, kann hier direkt die Eigenschaft "Text" dieses untergeordneten Objekts gesetzt werden. Bei Telefonnotizen muss beim Absender und beim Empfänger eine Telefonnummer in spitzen Klammern angegeben werden. In diesem Beispiel verwenden wir stellvertretend die Nummer "000" als Telefonnummer.
Da als Empfänger mehrere Adressen angegeben werden können, wurde die Objekteigenschaft "Recipients" mit einem leeren Array vorbelegt. Im Beispiel wird ein Empfänger als Objekt vom Typ GhRpcItemslibRpcAddressItem erzeugt, die Telefonnummer in der Eigenschaft "Text" gesetzt und das Objekt dem Array in der Eigenschaft "Recipients" hinzugefügt. Der Datentyp für Empfänger und Absender ist also identisch, ein Element kann einen Absender, aber mehrere Empfänger haben.
Zuletzt wird der Inhalt der Telefonnotiz festgelegt. In diesem Beispiel wird dazu ein einfacher HTML-String zusammengesetzt. Hier ist zu beachten, dass der Inhalt von Elementen (die Eigenschaft "EditorData" in den entsprechenden Elementtyp-Properties) immer in der Zeichencodierung "windows-1252" vorliegt (siehe hierzu auch den Abschnitt Serververbindung). Das Beispiel geht davon aus, dass die PHP Datei in der Zeichencodierung "UTF-8" vorliegt, daher wird der Inhalt über die PHP Funktion iconv von "UTF-8" nach "windows-1252" umgewandelt.
Schließlich wird die Methode "New_()" des Item-Dienstes aufgerufen, die die ID des neu erzeugten Elements zurück liefert.
index.php - Erzeugen einer Telefonnotiz:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<?php
require_once 'ghrpc/ghrpc.php';
$client = new GhRpcClient('localhost', 80, false, 'tester', 'test123'); // Client-Objekt
$client->setUniqueClientIdCookieName('ghrpcexample7'); // eindeutige Client-ID
$itemService = rpc_itemslib::newRpcItems($client); // Dienst für Elemente
$call = rpc_itemslib::newRpcDetailedItem(true); // Element erzeugen (Eigenschaften "leer" vorbefüllen)
$call->Kind = rpc_itemslib::ikCall; // Element vom Typ "Telefonnotiz"
$call->State = rpc_itemslib::isOpen; // Status "offen"
$call->Flags = GhRpcUtils::newSet(rpc_itemslib::ifUseHtml); // Telefonnotiz mit HTML Inhalt
$call->Priority = rpc_itemslib::ipNormal; // normale Priorität
$call->GroupRef = 1; // In Gruppe mit ID 1 ablegen
$call->Subject = 'Fehlendes Dokument'; // Betreff
$call->From->Text = 'Thorsten Tester <000>'; // Absender
$recipient = rpc_itemslib::newRpcAddressItem();
$recipient->Text = 'Tanja Tester <000>'; // Empfänger
$call->Recipients = array($recipient); // Empfänger hinzufügen
$content = '<html>';
$content .= '<head>';
$content .= '<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">'; // Zeichencodierung festlegen
$content .= '</head>';
$content .= '<body>';
$content .= '<p>Hallo Tanja,<br><br>';
$content .= 'kannst Du mir noch einmal das Dokument von letzter Woche zusenden? Ich finde das nicht mehr.<br><br>';
$content .= 'Grüße,<br>';
$content .= 'Thorsten</p>';
$content .= '</body>';
$content .= '</html>';
$content = iconv('UTF-8', 'windows-1252//IGNORE//TRANSLIT', $content); // In windows-1252 Zeichencodierung umwandeln
$call->Properties->Call->EditorData = $content; // Inhalt
try
{
$callId = $itemService->New_($call, false); // Telefonnotiz auf dem Server erzeugen (und nicht sperren)
echo 'Die Telefonnotiz wurde erzeugt. Die ID des neuen Elements ist: ' . $callId;
}
catch(Exception $exception)
{
die('Die Telefonnotiz konnte nicht erstellt werden (Fehler: ' . $exception->getMessage() . ').');
}