Benutzerhandbuch¶

Windows¶

Installation¶

Das connect kit wird über ein Setup-Programm ausgeliefert.

Ein Doppelklick auf dieses startet die Installation des connect kits.

Nach der optionalen Wahl des Installationsordners (1) kann man das connect kit installieren (2).

Note

Wenn bereits eine ältere Version des connect kits installiert ist, wird man darauf hingewiesen, dass dieses vorher deinstalliert wird. Das connect kit darf während eines Updates nicht gestartet sein. Wenn das connect kit als Service installiert wurde (siehe unten), muss der Service vor dem Update beendet werden.

Dateiablage¶

Die für den Betrieb des connect kits benötigten Dateien wie Konfiguration, Logs, Schlüsselpaare etc. werden unter C:\Users\USERNAME\AppData\Roaming\connectkit (“USERNAME” = Name des Benutzers) abgelegt. Die Dateien in diesem Ordner bleiben bei einer erneuten Installation oder nach einer Deinstallation erhalten. Alle Dateiangaben in den Erläuterungen der Settings beziehen sich auf diesen Basisordner als Ausgangspunkt.

Als Service installieren¶

Das connect kit kann auch als Service installiert werden, so dass es auch ausgeführt werden kann, wenn kein User auf dem System angemeldet ist. Für die Installation als Service gibt es im Startmenü einen Shortcut:

Die Installation als Service braucht Administrator Rechte. Das connect kit benötigt zum Betrieb einen Benutzer auf dem System (da die Dateiablage des connect kits einen Benutzer benötigt - siehe Dateiablage). Dieser muss bei der Installation als Service mit angegeben werden (1):

Der Name muss als Down-Level Logon Name angegeben werden, wie er z.B. über das Commandlinetool whoami bestimmbar ist.

Linux¶

sudo apt-get install mono-complete

sudo dpkg -i connectkit_0.7_amd64.deb

Windows¶

Das connect kit wird über das Startmenü von Windows gestartet.

In Abhängigkeit von der Windowsversion meldet das connect kit ggf., dass es mit Administratorrechten ausgeführt werden muss. Dies liegt daran, dass es für die Kommunikation einen Port öffnen muss. Alternativ können dem connect kit generelle Rechte für das Öffnen von Ports geben werden, die es nicht nötig machen, es als Administrator auszuführen (Befehl netsh siehe Configuring HTTP and HTTPS in der MSDN Dokumentation) .

Das connect kit läuft in einem sog. Terminalfenster in der es seine Version und die Adresse ausgibt, unter der es erreichbar ist.

Zum Beenden muss man dieses Terminalfenster auswählen und eine Taste drücken.

Wenn das connect kit als Service installiert wurde (siehe oben), muss es über den Windows-Systemdienst (services.msc) gestartet und beendet werden:

Linux¶

Unter Linux wird das connect kit mit dem Befehl

connectkitRun

gestartet.

Das connect kit gibt seine Version und die Adresse aus, unter der es erreichbar ist. Mit einer Tasteneingabe wird das connect kit wieder beendet.

connectkitService start

connectkitService stop

1. Username und Passwort des connect kit users¶

Hier muss Username und Passwort des connect kit Users im connect eingetragen werden.

2. connect Server¶

(2a) Die genutze Adresse des externen connect.

Diese Adresse kann (für z.B. Testzwecke) angepasst werden. Hierfür im DropDown (2b) “URL” auswählen und die Adresse unter (2c) einstellen. Nach dem Speichern muss das connect kit neu gestartet werden, damit die Änderung wirksam wird und die URL unter (2a) erscheint.

3. Host und Port¶

Host- und Portangabe unter dem das connect kit auf dem lokalen System angesprochen werden soll.

4. Intervall Adressbuchsynchronisation¶

Das Intervall für die Synchronisation mit dem Adressbuch des connect in Minuten.

Das Adressbuch wird in der Datei contacts.xml im Unterordner connect_contacts abgelegt.

5. Archivierung¶

Einstellungen für die Archivierung ausgehender und eingehender Dokumente. Die archivierten Daten werden im Ordner Archive abgelegt. Der Dateiname der Dokumente entspricht folgendem Benennungsschema:

ID des Empfängers/Senders + “_” + Typ der Datei + “_” + Zeit/Datum der Archivierung im Format 2013-09-30_13-00-00 + “_” + Unique ID

Bei verschlüsselt abgelegten Dateien wird die ID des Schlüsselpaars mit “_” + ID noch ergänzt, damit eine spätere Entschlüsselung einfach möglich ist.

6. Erzeugung eines Schlüssels¶

Das Austauschen von Angeboten zwischen zwei Parteien erfolgt über ein asymmetrisches Verschlüsselungsverfahren (RSA Verschlüsselung mit 1024 Bit Schlüssellänge). Hierbei wird ein Angebot an einen Empfänger mit dessen öffentlichen Schlüssel verschlüsselt und in connect abgelegt. Beim Empfang durch das connect kit wird das Angebot mit dem privaten Schlüssel entschlüsselt. Die Ver- und Entschlüsselung findet vollständig im connect kit statt (siehe Programmcode dazu). Die Verschlüsselung betrifft nur Angebotsdaten (alle API-Aufrufe, die mit send und fetch beginnen).

Damit die Kommunikation mit einem Empfänger verschlüsselt erfolgen kann, muss dieser ein gültiges Schlüsselpaar haben. Der öffentliche Schlüssel wird in connect abgelegt und kommt über die Adressbuchsynchronisation zu allen beteiligten connect kits.

Für die Erzeugung muss die Einstellungsseite (1) aufgerufen werden und unter dem zweiten Reiter (2) der Button “Schlüsselpaar erstellen” (3) angeklickt werden:

Das connect kit erzeugt dabei einen privaten und öffentlichen Schlüssel für die Kommunikation mit connect User. Der öffentliche Schlüssel wird in den Adressdaten des Users in connect abgelegt. Der private Schlüssel wird im connect kit im Unterordner “keys” abgelegt. Wenn dies Beides funktioniert hat, wird die Erzeugung mit folgender Meldung quittiert:

Wenn man nun die Settingsseite erneut aufruft, kann man sehen, dass die Verschlüsselung aktiv ist:

Lokale Ablage der privaten Schlüssel¶

Die lokalen privaten Schlüssel, die für die Entschlüsselung von Angebotsdaten benötigt werden, liegen um Unterordner “keys”:

Note

Dieser Ordner und die darin befindlichen Dateien sollten nicht entfernt werden. Das Löschen von Dateien in diesem Unterordner verhindert ggf. das verschlüsselte in connect liegende Angebote entschlüsselt werden können.

7. Automatischer Dateiversand¶

Hier kann der Pfad und das Verzeichnis für den automatischen Dateiversand (siehe unten) eingestellt werden. Der zunächst in grauer Schrift angezeigte Pfad ist die Defaulteinstellung. Dieser Pfad kann in dem Feld direkt überschrieben werden. Nach Bestätigung mit “Ordner setzen” prüft das connect kit, ob der Pfad existiert. Wenn ja, wird die Einstellungen übernommen. Nach dem erneuten Start des connect kits wird die Unterverzeichnisstruktur (siehe unten) angelegt. Existiert der angegeben Pfad oder Ordner nicht, wird eine Fehlermeldung ausgegeben.

8. center Einstellungen¶

Zeigt die Einstellungen des Users in connect an und bietet die Möglichkeit, die unterstützen Schemas für Dokumente in connect anzugeben.

1. Allgemeine Einstellungen des Users in connect. Diese Werte können nicht vom User verändert werden.
2. Der Status des Users im System. User mit “test” Status können noch nicht verbindlich kommunizieren. “pre-Live” bedeutet, dass eine verbindliche Kommunikation möglich ist, aber noch nicht alle Prozessschritte unterstützt werden. Der Status “live” besagt, dass alle Prozessschritte vollumfänglich genutzt werden können.
3. Die unterstützen Schemas der Dokumente. Siehe getDocumentSchemas

connect Webservice ansprechen¶

Die Hauptfunktion des connect kits besteht darin, Aufrufe an connect durchzureichen. Die Aufrufe werden über den Subpath /api/ an das center weitergereicht. Die Dokumentation aller Aufrufe des connect finden sich in dessen Dokumentation.

Beispiel¶

Das connect kit leitet unter dem Subpath /api/ alle Aufrufe an connect weiter.

Im obigen Beispiel werden die User von connect ausgelesen (siehe getOVKParticipants).

Unter /swagger/ (http://127.0.0.1:8888/swagger/) lassen sich die API-Aufrufe von connect live im Browser ausprobieren.

Außerdem sind unter

• /generally.wsdl (http://127.0.0.1:8888/generally.wsdl)
• /public.wsdl (http://127.0.0.1:8888/public.wsdl)
• /private.wsdl (http://127.0.0.1:8888/private.wsdl)

die WSDLs die Hauptbereiche der connect API abrufbar.

validateDocument¶

Prüft die Validität eines Dokuments gegen ein XSD Schema. Das connect kit prüft das übergebene XML gegen das im Dokument angegebene Schema und gibt ggf. eine Fehlermeldung zurück.

<CheckResponse status="1">
	<InfoText>Die angegebene XSD konnte gefunden werden</InfoText>
</CheckResponse>

checkConnectKitVersion¶

Prüft die Version des connect kits und gibt evtl. Probleme aus.

<CheckResponse status="1" expireDate="2015-01-01"/>

Versandablauf¶

Um eine Datei an einen bestimmten Empfänger zu verschicken, muss der Dateiname einem Benennungsschema entsprechen. Der Aufbau ist dabei wie folgt:

ID des Empfängers + “_” + Typ der Datei + “_” + Beliebige eigene Benennung + ”.xml”

• ID des Empfängers => Entspricht der UserID des Empfängers in connect Adressbuch (siehe getOVKParticipants)

• Typ der Datei => Kennung für den Typ. Mögliche Typen sind:

  • businesstransaction => Angebot
  • placements => Inventar
  • pricelist => Preisliste
  • advertisement => Werbeformen

Beispiel:¶

Dateiname: “2_businesstransaction_Angebot an XY zur Z Kampagne.xml“

Empfänger-ID: 2

Dateityp: businesstransaction

Sobald eine Datei im Ordner AutoFileTransfer/In ablegt wird, versucht das connect kit Empfänger und Angebotstyp aus dem Dateinamen zu bestimmen. Sofern dies eindeutig gelingt, wird die Datei zunächst in den Ordner Progress verschoben und um eine UniqueID erweitert (hierdurch kann man identisch benannte Dateien parallel verarbeiten). Im Anschluss versucht das connect kit die Datei an das zuständige connect zu verschicken. Wenn das gelingt, wird es im Ordner Sent archiviert.

Wenn Empfänger und Dateityp nicht bestimmbar sind, oder die Datei aus anderen Gründen nicht versandt werden konnte, wird es in den Ordner Error verschoben.

Sowohl bei erfolgreicher als auch fehlerhafter Verarbeitung wird eine Logdatei im jeweiligen Zielordner angelegt (Benennung wie der Dateiname der Datei + Prefix “_log.txt”), die Informationen zur Verarbeitung der Datei enthält.

Der Ablauf des Versands im Überblick:

Unterbrochene Verarbeitung¶

Sollte der Versand einer Datei durch z.B. Absturz des Rechners unterbrochen werden, wird die Verarbeitung beim nächsten Start des connect kits wieder aufgenommen. Das connect kit prüft beim Start, ob im Progress Ordner noch Dateien liegen und verarbeitet diese entsprechend.

Format¶

Die Aktionen werden zeilenweise geloggt. Die Zeilen sind spaltenweise formatiert (per Tabulator getrennt). Damit lässt sich die Datei einfach mit z.B. Excel öffnen und filtern.

Übersicht der User¶

Beim Aufruf der Portalseite wird zunächst die Userliste angezeigt. Die User kommen aus dem lokalen Userverzeichnis des connect kits (Synchronisation mit dem zentralen Adressbuch siehe Adressbuchsynchronisation).

1. ID => ID des Users in connect
2. Typ => Typ des Users (Vermarkter oder Agentur). Wenn das connect kit von einer Agentur betrieben wird, werden hier nur Vermarkter angezeigt, bei einem Vermarkter nur Agenturen.
3. Name => Der Name des connect Users

Bewegungsdaten¶

Hier werden die für den User des connect kits eingestellten Dokumente eingezeigt (siehe getDocumentsList).

1. Anzeige der neuen (= noch nicht abgerufenen) Dokumente
2. Anzeige aller Dokumente
3. Anzeige der heruntergeladenen und mit confirmFetch bestätigten Dokumente
4. Symbol Diskette: Herunterladen eines Dokumentes (fetch Aufrufe)
5. Symbol Bestätigung: confirmFetch des heruntergeladenen Documentes. Löscht das Dokument dauerhaft aus dem jeweiligen connect.
6. Symbol Entfernen: Rückgängig machen eines Fetches (undoFetch). Ist nur funktional, wenn noch kein confirmFetch stattgefunden hat

Stammdaten¶

Hier werden die Stammdaten der Vermarkter angezeigt. Man kann sie nach ihrem Typ anzeigen (1) oder einen bestimmten Vermarkter auswählen (2).

Die Möglichkeiten Stammdaten im zentralen connect einzustellen (3) ist nur möglich, wenn das connect kit von einem Vermarkter betrieben wird.

Nachrichten¶

Hier werden Nachrichten angezeigt, die über connect verschickt wurden. So wird beispielsweise beim confirmFetch eines Angebotes eine Nachricht an den Absender verschickt, dass der Empfänger das Dokument abgerufen hat.

Die Nachrichten können heruntergeladen und gelöscht werden.