BWScheduler über REST-API steuern

Überblick

Über die REST-API können mehrere BWScheduler-Installationen verschlüsselt miteinander verbunden werden. Eine Installation übernimmt die Rolle des Servers, die übrigen Installationen arbeiten als Clients.

Eine Installation kann immer nur eine Rolle besitzen:

Server: Nimmt Verbindungen an und kann Aufträge für Clients bereitstellen.
Client: Verbindet sich mit dem Server, sendet Aufträge an den Server und fragt Aufträge für sich selbst ab.

Damit können Aufgaben in beide Richtungen ausgelöst werden:

Client startet eine Aufgabe auf dem Server.
Server startet eine Aufgabe auf einem oder mehreren Clients.

Es werden keine SchedulerXX.RUN-Dateien benötigt.

Voraussetzungen

Alle beteiligten BWScheduler müssen über das Netzwerk erreichbar sein.
Auf dem Server muss der eingestellte TCP-Port freigegeben sein. Standard ist Port 9443.
Die Uhren der beteiligten Windows-Systeme sollten korrekt eingestellt sein.
Die auszuführende Zielaufgabe muss auf der Gegenstelle vorhanden und aktiviert sein.
Zielaufgaben müssen Hauptaufgaben sein. Unteraufgaben können nicht direkt über die REST-API gestartet werden.
Das Konto des BWSchedulers benötigt weiterhin alle Rechte, die von der Zielaufgabe benötigt werden.
ERP-Scheduler ab Version 5.31

Verschlüsselung und Zertifikate

Der gesamte Datenverkehr wird über TLS 1.2 verschlüsselt.

Internes Zertifikat

Wenn unter SSL-PFX Zertifikat keine Datei angegeben wird, erstellt und verwendet der Server automatisch ein internes Zertifikat. Dieses Zertifikat dient ausschließlich zur Verschlüsselung der Verbindung zwischen den BWSchedulern.

Für die Standardverbindung zwischen BWScheduler-Installationen muss daher kein Zertifikat bereitgestellt werden.

Eigenes PFX-Zertifikat

Optional kann auf dem Server ein eigenes PFX-Zertifikat hinterlegt werden:

SSL-PFX Zertifikat: vollständiger Pfad zur PFX-Datei
SSL-PFX Zertifikat Kennwort: Kennwort der PFX-Datei

Das PFX-Zertifikat muss einen privaten Schlüssel enthalten. Der im Zertifikat verwendete Name sollte zur eingestellten Serveradresse passen. Bei einem von einer vertrauenswürdigen Zertifizierungsstelle ausgestellten Zertifikat ist auf den Clients keine Ausnahme erforderlich.

Ungültige Zertifikate erlauben

Die Einstellung Erlaube ungültige SSL-Zertifikate betrifft die Prüfung auf der Clientseite.

Deaktiviert: Zertifikat und Servername müssen gültig sein. Das automatisch verwendete interne BWScheduler-Zertifikat wird ebenfalls akzeptiert.
Aktiviert: Zertifikatsfehler werden ignoriert.

Sicherheitshinweis: Aktivieren Sie diese Option nur in einem kontrollierten und vertrauenswürdigen Netzwerk.

Server einrichten

Öffnen Sie die Einstellungen und wechseln Sie zum Bereich REST-API.

Einstellung	Wert
Aktiv	aktiviert
Betriebsart	Server
IP-Adresse des REST-Servers	kann auf dem Server leer bleiben
Port	`9443` oder ein eigener freier Port
SSL-PFX Zertifikat	optional
SSL-PFX Zertifikat Kennwort	nur bei Verwendung einer PFX-Datei
Erlaube ungültige SSL-Zertifikate	auf dem Server ohne Bedeutung

Speichern Sie die Einstellungen und starten Sie den BWScheduler neu beziehungsweise laden Sie die Einstellungen neu.

Der Server nimmt verschlüsselte Verbindungen auf allen lokalen Netzwerkadressen über den eingestellten Port an. Stellen Sie sicher, dass die Windows-Firewall eingehende Verbindungen für diesen Port erlaubt.

Client einrichten

Öffnen Sie auf jedem Client den Bereich REST-API.

Einstellung	Wert
Aktiv	aktiviert
Betriebsart	Client
IP-Adresse des REST-Servers	IP-Adresse oder DNS-Name des Servers
Port	derselbe Port wie auf dem Server
SSL-PFX Zertifikat	normalerweise leer
SSL-PFX Zertifikat Kennwort	normalerweise leer
Erlaube ungültige SSL-Zertifikate	nur bei Bedarf aktivieren

Beispiele für die Serveradresse:

192.168.1.20
scheduler.firma.local
https://scheduler.firma.local

Der Client baut ausschließlich eine ausgehende Verbindung zum Server auf. Auf dem Client muss deshalb kein eingehender REST-Port geöffnet werden.

Als Clientname wird automatisch der Windows-Rechnername verwendet. Dieser Name wird benötigt, wenn der Server einen Auftrag nur an einen bestimmten Client senden soll.

Aufgabe auf der Gegenstelle ausführen

Erstellen Sie über Neu die Aufgabe:

REST-API Aufgabe auf Gegenstelle ausführen

Die Aufgabe wird mit folgenden Werten vorbereitet:

Einstellung	Wert
Aufgabenart	Funktionsaufruf
App	`$RESTAPI-EXECUTE`
AppParameter	`Execute=22`
AppParameter2	leer
Intervall	0

Passen Sie die Aufgabennummer, Ausführungszeit, Wochentage und das erlaubte Zeitfenster an den gewünschten Ablauf an.

Client startet eine Aufgabe auf dem Server

Auf dem Client wird eine Aufgabe mit folgendem AppParameter angelegt:

Execute=22

Wird diese Aufgabe auf dem Client ausgeführt, sendet er den Auftrag verschlüsselt an den Server. Der Server plant dort die aktivierte Hauptaufgabe mit der Scheduler-ID 22 ein.

Die Zielaufgabe auf dem Server benötigt selbst keine besondere REST-Einstellung. Sie muss lediglich vorhanden, aktiviert und als Hauptaufgabe eingerichtet sein.

Server startet eine Aufgabe auf allen Clients

Auf dem Server wird eine Aufgabe mit folgendem AppParameter angelegt:

Execute=22

Der Server stellt den Auftrag allen Clients bereit, die sich seit dem Start des Servers bei ihm gemeldet haben. Jeder dieser Clients plant seine lokale Aufgabe mit der Scheduler-ID 22 ein.

Die Scheduler-ID bezeichnet immer die Aufgabe auf der jeweiligen Gegenstelle. Die Aufgaben dürfen auf Server und Clients unterschiedliche Bezeichnungen oder Inhalte besitzen.

Server startet eine Aufgabe auf einem bestimmten Client

Soll nur ein bestimmter Client angesprochen werden, wird dessen Windows-Rechnername ergänzt:

Client=PC-BUCHHALTUNG&Execute=22

Damit wird die Aufgabe 22 ausschließlich für den Client PC-BUCHHALTUNG bereitgestellt.

Der Clientname muss dem Windows-Rechnernamen des Zielsystems entsprechen. Groß- und Kleinschreibung sind dabei nicht relevant.

Mehrere Clients

Mehrere Clients können denselben Server verwenden. Dabei gibt es zwei Möglichkeiten:

Nur Execute=22: Auftrag wird an alle beim Server bekannten Clients verteilt.
Client=RECHNERNAME&Execute=22: Auftrag wird nur für den angegebenen Client bereitgestellt.

Ein Auftrag für einen bestimmten Client kann bereits bereitgestellt werden, bevor dieser wieder verbunden ist. Er wird beim nächsten erfolgreichen Abruf übernommen, solange der Server zwischenzeitlich nicht neu gestartet wurde.

Direkter REST-Aufruf am Server

Der Server nimmt einen Ausführungsauftrag unter folgender Adresse entgegen:

https://SERVER:9443/api/scheduler/execute?Execute=22

Alternativ kann Execute=22 als formularcodierter Inhalt an dieselbe Adresse gesendet werden.

Zur Verfügbarkeitsprüfung steht folgende Adresse bereit:

https://SERVER:9443/api/scheduler/status

Eine erfolgreiche Prüfung liefert OK zurück.

Sicherheitshinweis: Begrenzen Sie den Zugriff auf den REST-Port über die Windows-Firewall auf die vorgesehenen Clientsysteme beziehungsweise das interne Netzwerk.

Verhalten der Zielaufgabe

Ein angenommener REST-Auftrag verhält sich weitgehend wie ein Auftrag über eine SchedulerXX.RUN-Datei:

Die Zielaufgabe wird beim nächsten Scheduler-Durchlauf eingeplant.
Die Aufgabe muss aktiviert sein.
Unteraufgaben können nicht direkt gestartet werden.
Die eingestellte modale Gruppe und der Doppelstartschutz bleiben wirksam.
Eine bereits laufende oder bereits eingeplante Aufgabe wird nicht nochmals parallel gestartet.
Eine aktive Wartungs- oder NoLock-Sperre kann die Ausführung weiterhin zurückhalten.

Die Zeitplanung der sendenden $RESTAPI-EXECUTE-Aufgabe bestimmt, wann der Auftrag übertragen wird. Die feste Ausführungszeit der Zielaufgabe wird durch den angenommenen Remote-Auftrag nicht abgewartet.

Typischer Einrichtungsablauf

Eine BWScheduler-Installation als Server konfigurieren.
Port 9443 oder den gewählten Port in der Server-Firewall freigeben.
Weitere Installationen als Clients konfigurieren.
Verbindung im Protokoll kontrollieren.
Auf der Gegenstelle eine ungefährliche Testaufgabe anlegen und aktivieren.
Auf der sendenden Seite eine $RESTAPI-EXECUTE-Aufgabe mit der entsprechenden Scheduler-ID erstellen.
Auftrag zunächst manuell ausführen.
Ausführung und Ergebnis auf beiden Seiten kontrollieren.
Erst danach die gewünschte Zeitplanung aktivieren.

Fehlerprüfung

Server ist nicht erreichbar

Prüfen Sie:

REST-API ist auf beiden Seiten aktiviert.
Server verwendet die Betriebsart Server.
Client verwendet die Betriebsart Client.
Serveradresse und Port stimmen überein.
Windows-Firewall erlaubt den Port.
Der Serverprozess läuft.

Zertifikatsfehler

Prüfen Sie:

Stimmt der DNS-Name mit dem eigenen Zertifikat überein?
Ist das Zertifikat noch gültig?
Ist die Zertifikatskette auf dem Client vertrauenswürdig?
Ist das PFX-Kennwort korrekt?

Die Option zum Ignorieren von Zertifikatsfehlern sollte nur vorübergehend zur Eingrenzung des Problems verwendet werden.

Aufgabe wird nicht ausgeführt

Prüfen Sie:

Ist die angegebene Scheduler-ID auf der Gegenstelle vorhanden?
Ist die Zielaufgabe aktiviert?
Handelt es sich um eine Hauptaufgabe?
Läuft die Aufgabe bereits oder wartet sie auf ihre modale Gruppe?
Ist eine Wartungs- oder NoLock-Sperre aktiv?
Ist im AppParameter tatsächlich Execute=Zahl eingetragen?

Bestimmter Client erhält den Auftrag nicht

Prüfen Sie:

Entspricht der Wert hinter Client= exakt dem Windows-Rechnernamen?
Hat sich der Client bereits erfolgreich beim Server gemeldet?
Wurde der Server nach dem Bereitstellen des Auftrags neu gestartet?