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.
CODEBeispiel: 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.
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.