Domino / Notes Anbindung

Server Komponente für IBM Domino

Die Server-Komponente für Raum für Raum unterstützt den RFR-Server durch Bereitstellung zweier über HTTP-Protokoll nutzbarer Dienste:

Ermittlung der Busy-Times
Der Dienst ermittelt Termine und generelle Abwesenheiten eines per Parameter festgelegten Notes/Domino-Benutzers aus dessen Maildatenbank für einen spezifizierten Zeitraum.
Pflege der Eingangspost des technischen RFR-Benutzers
Der Dienst ermöglichst das Abfragen angekommener und im ics-Format vorliegender Terminbestätigungen und –absagen. Geliefert wird der Textinhalt von ics-Email-Dateianhängen an Emails zuzüglich ausgewählter Metadaten der Emails selbst, wie z.B. dem Zustellungszeitpunkt, Absender und Betreff.

Installation

Die Server-Komponente wird als Notes/Domino-Datenbank (NSF) bereitgestellt. Sie ist lauffähig ab Domino-Version 8.5.1.

Einrichtung Server-Komponente

Folgende Schritte sind zum Einrichten der Server-Komponente erforderlich:

Kopieren Sie nun die angehängte NTF-Datei in das Datenverzeichnis des Domino- Servers, also z.B. nach "C:\Program Files\IBM\Lotus\Domino\data".NTF ist eine Datenbankschablone und keine vollständige Datenbank. Mit Datenbankschablonen lässt sich in Notes/Domino die Gestaltung einer bestehenden Datenbank aktualisieren (Gestaltung = UI-Elemente und Code), ohne ggf. erstellte Datendokumente zu überschreiben.
Signieren der Schablone
Die Datenbankschablone wurde mit unserer Notes-ID signiert, die auf Ihrem Server keine Ausführungsrechte für Code hat. Damit die neue Version ordnungsgemäß verwendet werden kann, muss die Schablone daher zunächst von Ihnen mit der Server-ID signiert werden. Über einen Rechtsklick auf die Schablone und "Sign..." können Sie dann signieren. Wählen Sie "Active Server's ID" aus und bestätigen Sie mit "OK":
Anlage einer neuen RFR-Datenbank
Nun muss eine neue Datenbank über "File/Application/New..." angelegt werden. In dem nun folgenden Dialog vergeben Sie einen beliebigen Datenbanktitel sowie den Pfad relativ zum Datenverzeichnis (entspricht dem späteren Aufrufpfad im Web). Als Datenbankschablone (Template) wählen Sie die RFR-Datenbankschablone aus und bestätigen mit "OK".

Die Option "Inherit future design changes" ist vorausgewählt. Dadurch wird der Name der Datenbankschablone in der neu anzulegenden Datenbank hinterlegt, sodass später beim Gestaltungsupdate (d.h. einer neuen Version von mir) nur die Schablonendatei ausgetauscht und signiert werden muss zzgl. dem Kommando, dass die Live-Datenbank ihre Gestaltung aktualisieren soll (geschieht im Standardsetup des Servers automatisch jede Nacht um 2 Uhr; alternativ kann dies manuell über "File/Application Refresh Design..." ausgeführt werden).
Anpassung der Zugriffskontrollliste der Server-Komponente
In der Zugriffskontrollliste der Server-Komponenten-Datenbank ist ein Benutzer mit mindestens Leseberechtigungen einzutragen (unten im Beispiel abgebildet „rfruser“), über den per Web auf die verfügbaren Dienste zugegriffen werden soll. Anonymer Zugriff (Benutzername „Anonymous“) ist zu unterbinden (Stufe „NoAccess“). Der Eintrag -Default- sollte maximal leseberechtigt sein, da hierdurch sämtliche Notes-Benutzer auf die Datenbank zugreifen können. Weitere ACL-Einträge mit Manager-Berechtigungen sind anzulegen für Personen,die die Konfiguration pflegen sollen (z.B. Gruppe „Administrators“).
Festlegung des technischen RFR-Benutzers
Zur Konfiguration der Server-Komponente ist diese im IBM Notes Client zu öffnen. In der folgenden Konfigurationsmaske ist der technischen RFR-Nutzer festzulegen, dessen Eingangspost nach Emails mit angehängten ics-Dateien durchsucht werden soll.
Optional: Setzen weiterer Konfigurationsoptionen
Weitere Konfigurationsoptionen dienen dem Aktivieren des Debug-Modus, bei dem zur Fehleranalyse umfangreichere Protokolleinträge erzeugt werden sowie zur Festlegung des maximalen Alters dieser Protokolleinträge. Ältere Einträge werden über einen periodischen Notes-Agenten automatisch aus der Datenbank entfernt.

Anzeige der Protokolleinträge

Über die oben rechts in der Konfigurationsmaske angezeigte Schaltfläche „Protokolle anzeigen“ lassen sich die Protokolldokumente betrachten.

Ein Protokolleintrag umfasst eine Qualifizierung der Schwere des Fehlers (z.B. reine Infomeldung, Warnung oder schwerwiegender Fehler), eine Datumsangabe, den Agenten, der die Meldung geschrieben hat sowie den Fehlertext selbst. Im Falle von Java-Ausführungsfehlern wird darüber hinaus der Java-Stacktrace dokumentiert.

Verfügbare Dienste im Detail

Nachfolgend werden die zur Verfügung stehenden Webdienste genauer beschrieben. Diese sind technisch durch eine Reihe von so genannten Webagenten umgesetzt.

Auslesen der ics-Mails

Der Agent "readqueue" liest die Inbox des technischen Benutzers aus. Hierbei können wahlweise alle
Emails mit angehängten ics-Dateien gelesen werden oder eine Teilmenge, die über Start/Enddatum und die Angabe der maximalen Rückgabeeinträge eingeschränkt wird. Basis-URL-Beispiel: https://hostname/rfr/api.nsf/readqueue?open ("?open" muss aus technischen Gründen immer der erste Parameter sein)

Parameterübersicht:

Parameter	Pflicht	Default	Beschreibung
start	nein	1900-01-01T00:00:00	Startdatum im ISO8601-Format des zu lesenden Zeitraums (Emailempfangsdatum gemäß Inbox-Ansicht)
end	nein	2100-12-31T23:59:59	Enddatum im ISO8601-Format des zu lesenden Zeitraums (Emailempfangsdatum gemäß Inbox-Ansicht)
limit	nein	Integer.MAX_VALUE	Maximale Anzahl der zu liefernden Dokumente (für Paging)

Rückgabebeispiel

 <Terminantworten>
<Eintrag>
<Id>B8E4293667944917C1257C860039DAFA</Id>
<Sender>CN=Karsten Lehmann/O=Mindoo</Sender>
<Betreff>ics via Notes-Mail</Betreff>
<Erstellt>21.02.2014 11:32:50</Erstellt>
<ICS>
<![CDATA[
BEGIN:VCALENDAR METHOD:PUBLISH VERSION:2.0 X-WR-CALNAME:Arbeit
PRODID:-//Apple Inc.//Mac OS X 10.9.1//EN X-APPLE-CALENDARCOLOR:#
0E61B9 X-WR-TIMEZONE:Europe/Berlin CALSCALE:GREGORIAN
BEGIN:VTIMEZONE TZID:Europe/Berlin BEGIN:DAYLIGHT
TZOFFSETFROM:+0100 RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
DTSTART:19810329T020000 TZNAME:MESZ TZOFFSETTO:+0200 END:DAYLIGHT
BEGIN:STANDARD TZOFFSETFROM:+0200
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU DTSTART:19961027T030000
TZNAME:MEZ TZOFFSETTO:+0100 END:STANDARD END:VTIMEZONE BEGIN:VEVENT
CREATED:20140221T103054Z UID:9CE6DB08-4B04-49DD-93FB-23BA1025F5A0
DTEND;TZID=Europe/Berlin:20140223T100000 TRANSP:OPAQUE
SUMMARY:Testtermin DTSTART;TZID=Europe/Berlin:20140223T090000
DTSTAMP:20140221T103058Z SEQUENCE:2 END:VEVENT END:VCALENDAR
]]>
</ICS>
</Eintrag>
<Eintrag>
<Id>D0C5DD7EF7E2CEC5C1257C88007D9C19</Id>
<Sender>CN=Karsten Lehmann/O=Mindoo</Sender>
<Betreff>Test</Betreff>
<Erstellt>23.02.2014 23:52:23</Erstellt>
<ICS>
<![CDATA[
BEGIN:VCALENDAR METHOD:PUBLISH VERSION:2.0 X-WR-CALNAME:Arbeit
PRODID:-//Apple Inc.//Mac OS X 10.9.1//EN X-APPLE-CALENDARCOLOR:#
0E61B9 X-WR-TIMEZONE:Europe/Berlin CALSCALE:GREGORIAN
BEGIN:VTIMEZONE TZID:Europe/Berlin BEGIN:DAYLIGHT
TZOFFSETFROM:+0100 RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=-1SU
DTSTART:19810329T020000 TZNAME:MESZ TZOFFSETTO:+0200 END:DAYLIGHT
BEGIN:STANDARD TZOFFSETFROM:+0200
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=-1SU DTSTART:19961027T030000
TZNAME:MEZ TZOFFSETTO:+0100 END:STANDARD END:VTIMEZONE BEGIN:VEVENT
CREATED:20140221T103054Z UID:9CE6DB08-4B04-49DD-93FB-23BA1025F5A0
DTEND;TZID=Europe/Berlin:20140223T100000 TRANSP:OPAQUE
SUMMARY:Testtermin DTSTART;TZID=Europe/Berlin:20140223T090000
DTSTAMP:20140221T103058Z SEQUENCE:2 END:VEVENT BEGIN:VEVENT
CREATED:20140221T103309Z UID:5D2CF0E0-A36B-488E-8F67-60A26F197862
DTEND;TZID=Europe/Berlin:20140224T140000 TRANSP:OPAQUE
SUMMARY:Testtermin 2 DTSTART;TZID=Europe/Berlin:20140224T130000
DTSTAMP:20140221T103317Z SEQUENCE:3 END:VEVENT BEGIN:VEVENT
CREATED:20140221T103327Z UID:95662BF3-DF6B-48E4-B31F-D1A5C2A96676
RRULE:FREQ=WEEKLY;INTERVAL=1;COUNT=3
DTEND;TZID=Europe/Berlin:20140225T100000 TRANSP:OPAQUE
SUMMARY:Wiederholtesttermin
DTSTART;TZID=Europe/Berlin:20140225T090000 DTSTAMP:20140221T103359Z
SEQUENCE:6 DESCRIPTION:Testnotiz END:VEVENT BEGIN:VEVENT
CREATED:20140221T103410Z UID:20FA30A2-5A51-42B8-B77F-8565B718A519
DTEND;VALUE=DATE:20140227 TRANSP:TRANSPARENT
SUMMARY:Testganztagstermin DTSTART;VALUE=DATE:20140226
DTSTAMP:20140221T103420Z SEQUENCE:3 BEGIN:VALARM X-WRALARMUID:
5B502883-E074-4C20-BD64-1F3B6912DF77 UID:5B502883-E074-
4C20-BD64-1F3B6912DF77 TRIGGER:-PT15H X-APPLE-DEFAULT-ALARM:TRUE
ATTACH;VALUE=URI:Basso ACTION:AUDIO END:VALARM END:VEVENT
END:VCALENDAR
]]>
</ICS>
</Eintrag>
</Terminantworten>

Löschen von ics-Mails

Der Agent "cleanupqueue" löscht wahlweise sämtliche Emails mit ics-Anhängen innerhalb eines spezifizierten Zeitraums oder eine Liste von Emails, die per ID übergeben wird. Basis-URL-Beispiel: https://hostname/rfr/api.nsf/cleanupqueue?open ("?open" muss aus technischen Gründen immer der erste Parameter sein)

Parameterübersicht

Parameter

Pflicht

Default

Beschreibung

start

nein

1900-01-01T00:00:00

Startdatum im ISO8601-Format des zu löschenden Zeitraums (Emailempfangsdatum gemäß Inbox-Ansicht)

end

nein

2100-12-31T23:59:59

Enddatum im ISO8601-Format des zu löschenden Zeitraums (Emailempfangsdatum gemäß Inbox- Ansicht)

id

nein

Liste der IDs zu löschender ics-Emails. Um mehrere Dokumente zu löschen, muss der Parameter mehrfach in der URL vorkommen: id=docid1&id=docid2&id=docid3

Bei Angabe des id-Parameters zur Löschung haben start/end keine Wirkung.

Rückgabebeispiel

<Loeschbestaetigung>
<Eintrag>
<Id>B8E4293667944917C1257C860039DAFA</Id>
<Sender>CN=Karsten Lehmann/O=Mindoo</Sender>
</Eintrag>
<Eintrag>
<Id>783AA462D00226E0917B928C1AEAE466</Id>
<Sender>"Karsten Lehmann" <klehmann@gmx.net></Sender>
</Eintrag>
</Loeschbestaetigung>

Lesen der Busy-Times

Der Agent "busytimes" gibt die Busy-Times für einen Notes-Benutzer in einem Zeitraum zurück. Dabei werden sowohl vorhandene Termine ausgewertet als auch die Angaben zur Verfügbarkeit in den Eigenschaften der Maildatenbank (Vorgaben / Kalender / Planen)

Basis-URL-Beispiel: https://hostname/rfr/api.nsf/busytimes?open ("?open" muss aus technischen Gründen immer der erste Parameter sein)

Parameterübersicht:

Parameter	Pflicht	Default	Beschreibung
start	ja		Startdatum im ISO8601-Format (z.B. 2014-03- 01T00:00:00) des zu lesenden Zeitraums (Emailempfangsdatum gemäß Inbox-Ansicht)
end	ja		Enddatum im ISO8601-Format (z.B. 2014-03- 31T23:59:59) des zu lesenden Zeitraums (Emailempfangsdatum gemäß Inbox-Ansicht)
user	ja		Benutzername, dessen Kalender ausgelesen werden soll; wahlweise Emailadresse, Notesname oder Namensbestandteile (z.B. Vorname oder Nachname). Falls Name nicht eindeutig ist oder nicht aufgelöst werden kann, wird ein Fehler ausgegeben. Beispielsweise nutzbare Werte sind: jmueller, hschmidt, jutta.mueller@mindoo.de, herbert.schmidt@mindoo.de, Jutta Müller, Herbert Schmidt, Jutta Müller/Mindoo, Herbert Schmidt/Mindoo
limit	nein	nteger.MAX_VALUE	Maximale Anzahl der zu liefernden Dokumente (für Paging)
noaway	nein	false	Flag, um das Berechnen der Abwesenheiten zu überspringen

Rückgabebeispiel

<Terminliste>
<Termin>
<Start>28.02.2014 00:00:00</Start>
<Ende>28.02.2014 08:00:00</Ende>
<Status>3</Status>
<Type>0</Type>
</Termin>
<Termin>
<Start>28.02.2014 20:00:00</Start>
<Ende>28.02.2014 23:59:59</Ende>
<Status>3</Status>
<Type>0</Type>
</Termin>
<Termin>
<Start>01.03.2014 00:00:00</Start>
<Ende>01.03.2014 23:59:59</Ende>
<Status>3</Status>
<Type>2</Type>
</Termin>
</Terminliste>

Status:

1=Termin wurde mit "Mark available" markiert, 2=Fester Termin, 3=Abwesend, d.h Eintrag aus Abwesenheitszeiten hergeleitet

Type:

0=Termin, 2=Ganztägige Veranstaltung, 3=Besprechung

Lesen der Logmeldungen

Über den Agenten "readlog" lassen sich die Protokolldokumente aus der RFR-Datenbank lesen. Basis-URL-Beispiel: https://hostname/rfr/api.nsf/readlog?open ("?open" muss aus technischen Gründen immer der erste Parameter sein)

Parameter	Pflicht	Default	Beschreibung
start	nein	1900-01-01T00:00:00	Startdatum im ISO8601-Format des zu lesenden Zeitraums (alle Logs zu demselben Http-Request haben dasselbe Datum)
end	nein	2100-12-31T23:59:59	Enddatum im ISO8601-Format des zu lesenden Zeitraums (alle Logs zu demselben Http-Request haben dasselbe Datum)
limit	nein	Integer.MAX_VALUE	Maximale Anzahl der zu liefernden Dokumente (für Paging)

Rückgabebeispiel

 <Protokoll>
<Eintrag>
<Datum>23.02.2014 23:32:25</Datum>
<Einstufung>SCHWERWIEGEND</Einstufung>
<Meldung>Error computing busytimes</Meldung>
<Agent>busytimes</Agent>
<Details>
<![CDATA[
NotesException: User CN=Karsten Lehmann/O=Mindoo cannot open
database mail\jmüller.nsf at
lotus.domino.local.Session.getDatabase(Unknown Source) at
de.mediadialog.rfr.notes.busytimes.BusyTimesAgent.NotesMain(BusyTim
esAgent.java:130) at lotus.domino.AgentBase.runNotes(Unknown
Source) at lotus.domino.NotesThread.run(Unknown Source)
]]>
</Details>
</Eintrag>
</Protokoll>

Allgemeine Hinweise

Nachfolgend sine generelle Informationen dokumentiert, die alle zur Verfügung stehenden Webagenten betreffen.

Fehlercodes

Bei Laufzeitfehlern und falscher Parametersyntax wird ein XML-Dokument mit einem technischen Fehlercode und einem Grund in deutscher Sprache zurückgeliefert:

Fehlercodes

<Fehler>
<Id>usernamenotfound:xxxx</Id>
<Grund>Der Benutzer xxxx konnte nicht gefunden werden.</Grund>
</Fehler>

Folgende Fehlercodes sind bislang hinterlegt:

package de.mediadialog.rfr.notes.logs;
/**
* Error codes and localized texts
*
* @author Karsten Lehmann
*/
public class Errors {
public static final String RUNTIMEERROR_ID="runtimeerror";
public static final String RUNTIMEERROR_MESSAGE="Fehler bei der
Programmausführung. Der Fehler wurde protokolliert.";
public static final String MISSINGARGUMENT_ID="missingargument:{0}";
public static final String MISSINGARGUMENT_MESSAGE="Das Feld {0}
wurde nicht übergeben";
public static final String
INVALIDGARGUMENTFORMAT_ID="invalidargumentformat:{0}";
public static final String INVALIDGARGUMENTFORMAT_MESSAGE="Das Feld
{0} hat ein ungültiges Format: {1}";
public static final String
USERNAMENOTUNIQUE_ID="usernamenotunique:{0}";
public static final String USERNAMENOTUNIQUE_MESSAGE="Für den
Benutzernamen {0} wurden mehrere Treffer gefunden: {1}";
public static final String
USERNAMENOTFOUND_ID="usernamenotfound:{0}";
public static final String USERNAMENOTFOUND_MESSAGE="Der Benutzer {0}
konnte nicht gefunden werden.";
public static final String MAILDBNOTFOUND_ID="maildbnotfound:{0}";
public static final String MAILDBNOTFOUND_MESSAGE="Die Maildatenbank
für Benutzer {0} ({1}!!{2}) konnte nicht geöffnet werden oder ist nicht
vorhanden";
public static final String
RFRTECHUSERNAMENOTFOUND_ID="rfrusernotfound";
public static final String RFRTECHUSERNAMENOTFOUND_MESSAGE="Der
technische RFR-Benutzer wurde noch nicht in der Konfiguration festgelegt.";
public static final String
MAILDBINVALIDFORMAT_ID="maildbinvalidformat:{0}";
public static final String MAILDBINVALIDFORMAT_MESSAGE="Der
Maildatenbank für Benutzer {0} ({1}!!{2}) fehlen notwendige
Gestaltungselemente. Details wurden protokolliert.";
}

Identifikation von ics-Emails

Derzeit werden von den Agenten "readqueue" und "cleanupqueue" nur Dokumente verarbeitet, die Anhänge mit Dateierweiterung ".ics" haben (Prüfung ohne Beachtung von Groß- und Kleinschreibung). Andere ggf. vorhandenen Emails werden ignoriert.

Gelesene Termine

Die Agenten lesen Besprechungen, Termine und Ganztagesveranstaltungen. Erinnerungen und Jahrestage werden nicht verarbeitet.