Pradtke.API Installationsanleitung

Die Pradtke.API muss auf einem Applikationsserver installiert werden, dessen Systemvoraussetzungen hier zu finden sind.

Zur Veranschaulichung für Adressen bzw. Pfade wird in dieser Anleitung standardmäßig der Port 5001 in den Beispielen genannt. Fügen Sie bei der Anwendung an diesen entsprechenden Stellen den Port ein, den Sie verwenden.

Installation der Pradtke.API

Zur Installation sind folgende Schritte durchzuführen.

Speicherort auf einem Webserver festlegen

Laden Sie das aktuelle Installationspaket „Pradtke API 10.x.x.msi“ herunter.
Legen Sie die Datei auf dem Webserver ab.
CODE
```
Beispiel: C:/inetpub/pradtke/api
```
Wenn Sie das aktuelle msi-Paket heruntergeladen haben, führen Sie einen Doppelklick aus, um den Installationsassistenten zu öffnen. Der Assistent führt Sie durch die Installation.
Akzeptieren Sie die Lizenzvereinbarung und drücken Sie auf Weiter.
Geben Sie Ihren Benutzernamen ein. Die Eingabe des Unternehmens ist nicht erforderlich. Drücken Sie auf Weiter.
Als Zielordner für die Installation wird der Pfad C:\inetpub\pradtke\api vorgeschlagen. Wenn Sie einen anderen Zielordner für die Installation möchten, drücken Sie auf Ändern… und folgen Sie dem Installationsassistenten.
Wenn die Installation auf den vorgeschlagenen Pfad erfolgen soll, drücken Sie auf Weiter.
Prüfen Sie im IIS-Manager, ob Sie bereits eine vorhandene Pradtke API IIS-Site betreiben und ob diese beendet worden ist.
Wählen Sie anschließend mit einem Klick die Option „Pradtke API IIIS Site ist beendet“ aus.
Erst nach diesen Schritten drücken Sie auf Weiter.
Drücken Sie auf Installieren.
Drücken Sie auf Fertig stellen.

Einrichten der Site im IIS-Webserver

Legen Sie nun bei der Erstinstallation im IIS-Manager eine neue Website unter dem Namen „pradtke.api“ an.

Wählen Sie im Kontextmenü „Webseite hinzufügen“.
Es öffnet sich nachfolgender Dialog mit weiteren Einstellungen.
Nehmen Sie Ihre Einstellung vor und beachten Sie die Hinweise zu der Konfiguration der Seite.

Konfiguration der Website und deren Bindung:

Sitename: Hier hinterlegen Sie einen Namen für die Website innerhalb des IIS-Managers. Beispiel: „pradtke.api“
Anwendungspool: Geben Sie hier den zu verwendenden Anwendungspool an.
Typ: Wählen Sie das zu verwendende Protokoll „HTTPS“ aus.
Physischer Pfad: Wählen Sie den physischen Pfad aus. Dieser Pfad entspricht dem bei der Installation genutzen Pfad. In der Abbildung ist es der Standardpfad aus der Installation: „C:\inetpub\pradtke\api“.
IP-Adresse: Nach Möglichkeit sollte keine explizite IP-Adresse angegeben werden.
Port: Wählen Sie den Port aus, über den die Site zu erreichen ist; wir empfehlen den Port 5001.
Hostname: Der Name, unter welchem die Site im Netzwerk erreichbar sein soll. Dieser Eintrag kann in der Regel ebenfalls leer gelassen werden. Der Hostname entspricht dann dem Servernamen im Netzwerk. Beachten Sie aber, dass der Hostname zu dem im Zertifikat hinterlegten Hostnamen (Authority-Teil der URI) passt, da es sonst zu Zertifikatsfehlern kommt.
TLS-Zertifikat: Hier muss ein überprüfbares, gültiges Serverzertifikat für den Betrieb hinterlegt werden, das den aktuellen Regeln entspricht.
Authentifizierung: Überprüfen Sie die eingestellten Authentifizierungen. Die Authentifizierungsmethode „Standardauthentifizierung“ muss deaktiviert sein.

Installation und Konfiguration mehrerer APIs auf einem IIS-Webserver

Wenn Sie mehrere APIs betreiben wollen, lesen Sie bitte den folgenden Abschnitt.

Betrieb mehrerer APIs

Das Installationspaket „Pradtke API 10.x.x.msi“ erkennt eine bereits vorhandene Installation. Daher wird Ihnen lediglich eine Reparaturinstallation und die Entfernung der Software im Installationsdialog angeboten.

Um dennoch eine mehrfache Installation auf demselben Server zu gewährleisten, können Sie folgendermaßen vorgehen:

Kopieren Sie den Ordner einer bestehenden Installation (z. B. "C:\inetpub\pradtke.api") und fügen Sie ihn beispielsweise im selben Unterverzeichnis (hier "inetpub") unter anderem Namen (z. B. "pradtke.api.test") ein.
Gehen Sie anschließend bei der Konfiguration der zweiten IIS-Site so vor, wie es oben im Dokument beschrieben wird. Achten Sie dabei darauf, den korrekten physischen Pfad zu verwenden.
Wenn auf einem Server mehrere Instanzen der Pradtke.Api gehostet werden sollen, muss für die Konfiguration jeder Instanz ein eindeutiger Name für dessen interne Konfgurationsdatenbank hinterlegt werden. Dazu müssen Sie nach Anlage der Website unter „Verwaltung“ den Konfigurationseditor öffnen. Im Konfigurationseditor wählen Sie nun den Abschnitt „system.webServer/aspNetCore“. Öffnen Sie die „environmentVariables“ zum Bearbeiten.
Hier müssen Sie eine Variable mit dem Namen „ConfigurationDB“ und einer eindeutigen Bezeichnung als Wert hinzufügen. Achten Sie zur Einhaltung der Eindeutigkeit darauf, dass es keine zwei Pradtke.APIs auf demselben Webserver gibt, die denselben Wert für den Schlüssel 'ConfigurationDB' haben. Sinnvoll ist es, den Namen der Site zu verwenden (s. Beispiel).
Beispiel
Wechseln Sie nun in das Verzeichnis, in das Sie die bestehende Installation kopiert haben.
Öffnen Sie dort die Datei „appsettings.json“:
Passen Sie die Einstellung „var_logdir“ unter dem Knoten „variables“ an. Hinterlegen Sie hier den Pfad, der für das Schreiben der Protokolldaten der „gedoppelten“ Instanz der Pradkte.API benötigt wird. Wählen Sie unbedingt ein anderes Verzeichnis als bei der Originalinstallation aus, da Sie ansonsten die Protokolleinträge der beiden Installationen nicht mehr differenzieren können. Beachten Sie außerdem, dass die Backslashes der Pfadangabe doppelt notiert werden müssen, wie im Beispiel abgebildet.
Speichern Sie die Änderungen an der Datei und schließen Sie diese.

Die Mehrfachinstallation ist abgeschlossen.

Initialisierung der Pradtke.API

Nach der Installation als Website im Internetinformationsdienste-Manager (IIS-Manager) muss die Pradtke.API initialisier werden..

Konfigurationszugang anlegen

Beispiel:

Die Pradtke.API wird in Ihrer Einrichtung unter der Adresse https://ihr-webserver:5001 gehostet. Dann navigieren Sie im Browser auf die Adresse https://ihr-webserver:5001/config.

Öffnen Sie im Browser die Adresse wie im Beispiel beschrieben.
Folgender Dialog öffnet sich:
Hier müssen Sie einmalig den Wartungszugang zur Pradtke.API definieren. Vergeben Sie dazu einen Benutzernamen sowie ein Passwort. Das Passwort muss mindestens acht Zeichen lang sein. Es muss Groß- und Kleinbuchstaben enthalten sowie Zahlen und Sonderzeichen.

Wichtiger Hinweis:
Dieser Wartungszugang wird fortan für die Konfiguration der Pradtke.API verwendet. Für die Wartung benötigt der technische Support der Firma Pradtke diese Zugangsdaten ebenfalls. Heben Sie daher diese Anmeldedaten sorgfältig auf, denn diese können bei Verlust nicht wiederhergestellt werden.

Beachten Sie, dass der Konfigurationszugang prinzipiell von jedem Rechner, der berechtigt ist, auf den Webserver bzw. die Website zuzugreifen, aufgerufen werden kann.

Bestätigen Sie Ihre Eingabe mit einem Klick auf die Schaltfläche :api_weiter: .

Es wird folgender Dialog angezeigt:

Wenn Sie den Link „Zur Konfiguration wechseln“ betätigen oder erneut die zuvor angesteuerte URL aufrufen, gelangen Sie zur Anmeldemaske der Konfigurationsoberfläche der Pradtke.API.

Die Neuanlage des Konfigurationszugangs ist nur möglich, solange noch kein Konfigurationszugang definiert wurde. Sobald entsprechende Anmeldedaten hinterlegt wurden, kann diese Funktion nicht mehr erreicht werden.

Eine nachträgliche Änderung des Passworts ist über die Konfigurationsoberfläche jederzeit möglich.

Erste Anmeldung an der API

Rufen Sie die Konfigurationsoberfläche auf, nachdem Sie einen Konfigurationszugang angelegt haben. Es wird Ihnen folgender Anmeldedialog angezeigt:

Geben Sie hier die zuvor festgelegten Anmeldedaten des Konfigurationszugangs ein und klicken Sie auf die Login-Schaltfläche.

Sie werden zur Pradtke Konfigurationsübersicht weitergeleitet:

Datenbankverbindung konfigurieren

Um die Datenbankverbindung zu konfigurieren, klicken Sie auf die Schaltfläche „Datenbanken“.

Es wird der Dialog zur Konfiguration der Datenbankverbindung angezeigt.

Erfassen Sie nun die für die TIMEOFFICE-Datenbank gültigen Konfigurationswerte.

Folgende Werte müssen vergeben werden:

Konfigurationswert	Erläuterung
Datenbanktyp	Der verwendete Datenbanktyp; i.d.R. Microsoft SQL Server oder SAP SQL Anywhere.
Host	Der Hostname des Datenbankservers, mit dem eine Verbindung aufgebaut werden soll. Hinweis: Sofern Ihr SQL Server auf einem anderen Port als 1433 (TCP/IP-Port des SQL Servers) erreichbar ist, können Sie den alternativen Port durch einen Doppelpunkt getrennt hinter dem Hostnamen notieren.
Name	Der Name der Datenbankinstanz.
Benutzer	Der Anmeldename des verwendeten Datenbankbenutzers.
Passwort	Das Passwort des verwendeten Datenbankbenutzers, falls sich der Benutzer vom Standardbenutzer unterscheidet.

Sollten Sie noch keinen eigenen Datenbankbenutzer hinterlegt haben, aktivieren Sie den Schalter „Standard-Anmeldung“. In diesem Fall müssen Sie weder Benutzer noch Passwort hinterlegen.

Diese Anmeldung ist nur gültig, wenn der Datenbankbenutzer noch nicht geändert wurde.

Wenn alle Pflichtfelder gefüllt sind, können Sie mit Hilfe der Überprüfen-Schaltfläche (Screenshot) testen, ob die Pradtke.API serverseitig eine Datenbankverbindung unter Verwendung der eingegebenen Verbindungsparameter aufbauen kann.

Schlägt die Verbindung fehl, wird folgende Meldung angezeigt:

Kann eine Datenbankverbindung aufgebaut werden, wird folgende Meldung angezeigt:

Haben Sie die Datenbankverbindungsparameter erfolgreich überprüft, speichern Sie die Einstellungen durch Betätigung der Bestätigen-Schaltfläche (Screenshot).

Wurden die Einstellungen erfolgreich gespeichert, wird dies durch folgende Meldung angezeigt:

Wichtig: Melden Sie sich nun mit einem Klick auf die Abmelden-Schaltfläche oben rechts ab. Starten Sie anschließend die Pradtke.API Website im Internetinformationsdienste (IIS)-Manager neu, indem Sie die Website der Pradkte.API stoppen, kurz warten und dann erneut starten.

Nutzen Sie im IIS nicht die Funktion „neu starten“, da hierüber die Website nicht immer korrekt gestartet wird.

Aufgrund der nun vorhandenen Datenbankverbindung passt sich die Pradtke.API an die in Ihrer Einrichtung vorhandenen Module automatisch an.

Grundsätzlich sollte nach jeder Anpassung der Pradtke.API-Konfiguration die Site immer neu gestartet werden. Nur so wird sichergestellt, dass alle relevanten Komponenten mit den veränderten Konfigurationsdaten operieren.

Konfigurieren der API-Jobs

Um die Lauffähigkeit der installierten API-Jobs sicherzustellen, klicken Sie auf die Schaltfläche „Jobs“; dies betrifft mindestens den Job für den Service-Connect.

Es wird der Dialog zur Konfiguration der API-Jobs angezeigt:

Prüfen Sie hier, ob im Feld „Pradtke API URL“ (überschrieben mit der Erläuterung „Die URL der API in der diese Jobs laufen“) systemseitig die URL, über welche die API in Ihrer Installation erreicht werden kann, korrekt hinterlegt wurde und passen Sie sie gegebenenfalls an.

Einbinden der Pradtke.API in TIMEOFFICE

Abschließend muss TIMEOFFICE noch mit der Pradtke.API verbunden werden. Dafür müssen Sie TIMEOFFICE öffnen und unter Administration > Stammdaten > Installation > Karteireiter "Allg. Programmeinstellungen" im Feld "Pradtke API URL" den Link auf die Pradtke.Api hinterlegen.

Achten Sie darauf, nur die Basis-URL (z.B. „https://ihr-webserver:5001“) anzugeben und keine weiterführenden Pfade anzuhängen, z.B. „/api“.

Die Erstinitialisierung ist damit abgeschlossen.

In der Folge können weiterführende Konfigurationsschritte notwendig sein. Dies hängt von den von Ihrer Organisation eingesetzten Modulen ab.

Weiterführende Konfiguration

Cross-Origin Resource Sharing (CORS)

Über die Einstellungen zu Cross-Origin Resource Sharing (CORS) können Sie Origins (Anfangsteil einer URI bis zum Pfadanteil) definieren, die Zugriff auf die Pradtke.API nehmen dürfen.

Dies ist insbesondere beim Einsatz der folgenden Module relevant:

PPPRL-Center (pradtke-web)
plan b

Diesen Komponenten muss bei Verwendung ein Zugriff auf die Pradtke.API erlaubt werden.

Um Cross-Origin Resource Sharing (CORS) zu konfigurieren, klicken Sie auf die Schaltfläche „CORS“:

Es wird ein Dialog zur CORS-Konfiguration angezeigt:

Über die Plus-Schaltfläche können Sie der Liste freigegebener Hosts neue Einträge hinzufügen.

Dazu wird Ihnen folgender Dialog angezeigt:

Sie müssen den freizugebenden „Origin“ im Feld „Host“ eintragen. Um die Freigabe in allen Konstellationen sicher zu stellen, sollten Sie für jeden „Origin“ zwei Freigaben anlegen. Geben Sie einmal nur Protokoll und den Hostname an und in einem weiteren Eintrag Protokoll, Hostname und Port.

Achten Sie bei der Eingabe eines „Origins“ darauf, diesen nicht durch einen abschließenden Schrägstrich „/“ zu beenden.

Im Feld „Bezeichnung“ können Sie eine beliebige, möglichst sprechende Bezeichnung vergeben.

Sonstige Moduleinstellungen

Neben den bisher beschriebenen Konfigurationswerten können im Bereich „Einstellungen“ auch Konfigurationen der spezifischen Funktionsmodule vorgenommen werden.

Um diese Konfigurationseinstellungen zu erreichen, klicken Sie auf die Schaltfläche „Einstellungen“:

Es wird der Einstellungsdialog angezeigt:

Die Erläuterungen der einzelnen Einstellungen entnehmen Sie bitte den entsprechenden Moduldokumentationen.