UPDATENOW
EmpirumAPI-CSV-Task-Interface
Autor: Frank Dethlefsen
Datum: 28.08.2024
Version: 2.4.8.28
Beschreibung
Von dem Empirum Automation Interface kurz EAI genannt wurde 2022 aus Sicherheitsgründen das EAI-XML-Interface vom Hersteller Matrix42 abgeschaltet. Kunden können das EAI-XML-Interface auf eigene Gefahr wieder einschalten. Matrix42 wird aber die EAI-Funktion in einer der nächsten Empirum Versionen endgültig entfernen. Die bisherige EAI-Funktion wird durch das neuere EmpirumAPI-Interface ersetzt.
Das EmpirumAPI-Interface nutzt den „Empirum Interface Hosting Service“, kurz EmpirumAPI-Dienst genannt, für die Verarbeitung. Die Verarbeitung erfordert zwingend einen direkten Netzwerkzugriff auf den Haupt-EmpirumServer, auf dem der EmpirumAPI-Dienst installiert ist. Das EmpirumAPI-Interface bietet in dieser Hinsicht keine Alternative für das bisherige EAI-XML-Interface, das offline bzw. ohne direkten Netzwerkzugriff auf dem Haupt-EmpirumServer genutzt werden konnte.
Zudem muss dem EmpirumAPI-Interface für die Autorisierung im PowerShell-Skript/.NET-Code ein Benutzer und ein verschlüsseltes Passwort mitgegeben werden. Wer Zugriff auf das PowerShell-Skript/.NET-Code hat, kann den Benutzer und das verschlüsselte Passwort entnehmen und damit ein neues PowerShell-Skript/.NET-Code erstellen und ausführen.
Das upDateNow EmpirumAPI-CSV-Task-Interface schließt die Lücke der fehlenden Offline-Funktion des EmpirumAPI-Interfaces und zudem wird auch kein PowerShell-Skript/.NET-Code auf der Client-Seite benötigt. Es werden nur CSV-Dateien mit Auftragsinformationen vom Client an den Haupt-EmpirumServer zurückgeliefert. Die CSV-Dateien mit den Auftragsinformationen werden dann von einem speziell server-seitig vorbereitetem Aufgaben-EmpirumSDK-PowerShell-Skript verarbeitet, um z.B. einen Computer einer Zuweisungsgruppen hinzuzufügen und zu aktivieren.
Bei der Erstellung der Aufgabe wird eine einzigartige umgebungsspezifische TaskID (GUID) für die Verarbeitung generiert, die bekannt sein muss. Sie sind so in der Lage, nur maßgeschneiderte Aufgaben für die Verarbeitung freizugeben und können die Missbrauchsmöglichkeiten auf ein kalkulierbares Minimum reduzieren.
upDateNow liefert zwei Aufgaben mit Softwarepaketen von Haus aus mit:
· Task - Remove computer from OS-Installationgroup
Ein wichtiger Punkt im Rahmen einer EmpirumServer-Sicherheitshärtung ist die Vermeidung von dauerhaften sicherheitsrelevanten Benutzern und Passwörtern in den Empirum-Meta-Daten (Computer.ini) wie z.B. das verschlüsselte DomainJoin-Benutzer- und lokale Administratorpasswort. Wird ein Computer temporär für die Betriebssysteminstallation in eine OS-Installation-Zuweisungsgruppe hinzugefügt, stehen ihm die sicherheitsrelevanten Benutzer und Passwörter zu Verfügung, bis dieser wieder aus der OS-Installation-Zuweisungsgruppe entfernt wird. Die automatische Entfernung des Computers aus der OS-Installation-Zuweisungsgruppe wird mit dem client-seitigem Softwarepaket Remove computer from OS-Installationgroup und der server-seitigen Aufgabe durchgeführt.
· Task - Add-remove computer to-from Kiosk Assigned Software Packages Group
Installiert sich ein Anwender Softwarepakete aus dem Softwaredepot-Kiosk, dann ergeben sich zwei Nachteile.
1. Wenn der Computer des Anwenders neu installiert wird, werden die selbst installierten Softwarepakete nicht automatisch wieder installiert.
2. Aus Sicherheitsgründen müsste ein Anwender selbst installierte Softwarepakete aus dem Softwaredepot-Kiosk zeitnah updaten. Das wird häufig vergessen.
Die Lösung: Installiert sich ein Anwender auf seinem Computer selbst Softwarepakete aus dem Softwaredepot-Kiosk, wird am Ende der Installation eine CSV-Datei mit den entsprechenden Auftragsinformationen erzeugt, zum Haupt-EmpirumServer transferiert und dort von einem server-seitigen Aufgaben-EmpirumSDK-PowerShell-Skript verarbeitet. Der Computer wird dann zu der entsprechenden Softwareprodukt-Zuweisungsgruppe hinzugefügt und aktiviert. Wird der Computer anschließend neu installiert, wird auch das Softwarepaket automatisch wieder installiert. Im Fall, dass das Softwarepaket aus Sicherheitsgründen zeitnah aktualisiert werden muss, kann der Empirum-Admin in der entsprechenden Softwareprodukt-Zuweisungsgruppe die alte Softwarepaketversion durch eine neue ersetzen und aktivieren. Auf dem Anwendercomputer wird dann die neue Softwarepaketversion automatisch aktualisiert.
Mit den mitgelieferten Aufgaben bekommen Sie nach unserer Erfahrung sehr gute praxisnahe Beispielvorlagen an die Hand, um weitere Aufgaben-EmpirumSDK-PowerShell-Skripte selbst zu entwickeln.
Darüber hinaus können Sie aus dem Aufgaben-EmpirumSDK-PowerShell-Skript auch auf andere Systeme wie z.B. Active Directory, EntraID, SQL-Server oder Macmon zugreifen und Daten verarbeiten.
Die upDateNow GmbH ist ein spezialisierter premium Berater, Dienstleister und Trainer rundum das Produkt Matrix42 Empirum. Das upDateNow Tool EmpirumAPI-CSV-Task-Interface wird Kunden im Rahmen einer kostenpflichtigen Beratung, Dienstleistung oder Workshop kostenfrei bereitgestellt. Sollten Sie Fragen, Probleme, Anregungen oder möchten Sie ein Angebot haben, stehen wir Ihnen gerne per E-Mail Frank.Dethlefsen@updatenow.de zu Verfügung.
Voraussetzungen
· Das Matrix42 Empirum-SDK 1.3.12.0 oder höher (kann aus dem Matrix42 Marketplace kostenfrei bezogen werden), muss auf dem Haupt-EmpirumServer installiert sein.
· Der EmpirumAPI-Dienst muss auf dem Haupt-EmpirumServer installiert und mit dem Protokoll HTTP bzw. HTTPS konfiguriert sein.
· Gute PowerShell-Scripting-Kenntnisse
Setup
Melden Sie sich auf dem Haupt-EmpirumServer per Remotedesktop administrativ an und führen die „upDateNow EmpirumAPI-CSV-Task-Interface 2024.08.exe“ aus. Es erscheinen die Eingabemasken für den EmpirumAPI-Benutzer und -Passwort. Übernehmen Sie die Benutzervorgabe oder geben Sie einen administrativen Empirum-Service-Benutzer an. Stellen Sie für einen AD-Benutzer die Domäne bzw. für einen lokalen Benutzer den Computernamen des Haupt-EmpirumServer vorne an, z.B. DOMAIN\EmpService oder SERVER\EmpService. Falls Sie einen SQL-Benutzer verwenden wollen, geben Sie nur den Benutzername z.B. EmpService an. Abschließend erscheint ein Bestätigungsdialog, ob die Installation durchgeführt werden soll. Wählen Sie „continue“ für fortsetzen aus. Das Setup hat nun folgendes eingerichtet:
Es wurde ein Verzeichnis \Empirum\upDateNow\EmpirumAPI-CSV-Task-Interface erstellt, in dem sich folgende Dateien und Ordner befinden:
· Datei: \EmpirumAPI-CSV-Task-Interface.htm
Diese Anleitung
· Datei: \EmpirumAPI-CSV-Task-Interface.exe
Hauptprogramm, das die CSV-Dateien einliest und die Aufgaben verarbeitet.
· Datei: \EmpirumAPI.json
Konfigurationsdatei, dass die Anmeldeinformationen für den EmpirumAPI-Dienstzugriff beinhaltet.
· Ordner: \Log
Log-Ordner
· Ordner: \Log\Error
Unterordner für die Ablage von Import-CSV-Dateien, die ungültig sind oder keiner Aufgabe zugeordnet werden konnten.
· Datei: \Log\EmpirumAPI-CSV-Task-Interface.log
Zentrale Logdatei von der Anwendung EmpirumAPI-CSV-Task-Interface
· Ordner: \Tasks
Hauptordner für die Aufgaben
· Datei: \Tasks\Create-new-Task.ps1
PowerShell-Skript, mit dem Sie einen neuen Aufgabenordner \Tasks\Library\<einzigartig generierter TaskID-Ordner> mit verweisender Verknüpfung \Tasks\Task - <neuer Aufgabenname>.lnk erstellen können.
· Ordner: \Tasks\Library
In dem Unterordner befinden sich die Aufgabenbibliothek.
· Datei: \Tasks\Library\Task.ps1.template
EmpirumSDK-PowerShell-Skript-Vorlage für neue Aufgaben
· Datei: \Tasks\Library\<einzigartig generierte TaskID-Ordner>\Task.ps1
EmpirumSDK-PowerShell-Skript für die jeweilige Aufgabe
· Ordner: \Tasks\Library\<einzigartig generierte TaskID-Ordner>\Error
Aufgaben-Unterordner, in dem die Aufgaben-CSV-Dateien kopiert werden, die fehlerhaft verarbeitet wurden.
· Ordner: \Tasks\Library\<einzigartig generierte TaskID-Ordner>\Success
Aufgaben-Unterordner, in dem die Aufgaben-CSV-Dateien kopiert werden, die erfolgreich verarbeitet wurden.
· Datei: \Tasks\Task - Add-remove software package to-from Kiosk Assigned Software Packages Group.lnk
Verknüpfung, die auf den Unterordner \Tasks\Library\<einzigartig generierter TaskID-Ordner> für die Aufgabe verweist.
· Datei: \Tasks\Task - Remove computer from OS-Installationgroup.lnk
Verknüpfung, die auf den Unterordner \Tasks\Library\<einzigartig generierter TaskID-Ordner> für die Aufgabe verweist.
Folgende Softwarepakete wurden unter \Empirum\Configurator\Packages\upDateNow kopiert:
· Ordner: \Remove computer from OS-Installationgroup\1.0
Das Softwarepaket kann nach Bedarf eingebunden und verwendet werden.
· Ordner: \EmpirumAPI-CSV-Task_Example-Package\1.0
Das Softwarepaket kann als KIOSK-Test-Softwarepaket eingebunden und/oder als Anpassungsvorlage für weitere KIOSK-Softwarepakete verwendet werden.
Folgende Verknüpfungen wurden im Startmenü\Programme\upDateNow\EmpirumAPI-CSV-Task-Interface angelegt:
· EmpirumAPI-CSV-Task-Interface - Tutorial
Diese Anleitung kann damit aufgerufen werden.
· Log
Öffnet mit dem Windows-Explorer den Log-Ordner \Empirum\upDateNow\EmpirumAPI-CSV-Task-Interface\Log
· Tasks
Öffnet mit dem Windows-Explorer den Tasks-Ordner \Empirum\upDateNow\EmpirumAPI-CSV-Task-Interface\Tasks
· Create-New-Task
Öffnet eine PowerShell-Console für die Erstellung einer neuen Aufgabe
· Uninstall
Deinstalliert das Werkzeug EmpirumAPI-CSV-Task-Interface auf dem EmpirumServer
Es wurde ein Windows Aufgabenplan „EmpirumAPI-CSV-Task-Interface“ für den CSV-Datei-Import und -Verarbeitung erstellt. Der Aufgabenplan startet das Hauptprogramm EmpirumAPI-CSV-Task-Interface.exe permanent. Alle 10 Minuten prüft der Windows Aufgabenplan, ob das Hauptprogramm noch gestartet ist. Falls nicht, wird es wieder gestartet. Das Hauptprogramm selbst prüft alle 5 Sekunden, ob neue CSV-Dateien im Ordner \Empirum\Configurator\Log\API-Tasks verfügbar sind. Falls ja, werden diese umgehend eingelesen, verarbeitet und verschoben.
Erstellung einer neuen Aufgabe
Melden Sie sich administrativ auf dem Haupt-EmpirumServer per RDP an. Starten Sie die Verknüpfung im Startmenü upDateNow\EmpirumAPI-CSV-Task-Interface\Create-new-Task als Administrator.
Geben Sie einen aussagekräftigen Aufgabennamen an, wie zum Beispiel: “Move computer from the W10 to the W11 configuration group and remove computer from the W11 inplace upgrade group”.
Nach Eingabe und Bestätigung wird Ihnen für die Aufgabe in der \Empirum\upDateNow\EmpirumAPI-CSV-Task-Interface\Tasks\Library ein neuer einzigartiger TaskID-Ordner mit einer neuen Task.ps1 erstellt. Die Task.ps1 wird abschließend für die weitere Bearbeitung mit der PowerShell-ISE geöffnet.
Da man sich den neuen einzigartigen TaskID-Ordner nur
schwer merken kann, wurde zusätzlich eine aussagekräftige Verknüpfung
\Empirum\upDateNow\EmpirumAPI-CSV-Task-Interface\Tasks\Task - Move computers
from the W10 to the W11 configuration group and remove computers from the W11
inplace upgrade groups.lnk erstellt. Wenn Sie die Verknüpfung auswählen, wird
Ihnen der entsprechende einzigartige TaskID-Ordner mit dem Windows-Explorer
geöffnet.
Leere Task.ps1-Vorlage
# Following variables could be used:
# $TaskNo [String]
# $TaskID [String]
# $TaskComputername [String]
# $TaskDomainname [String]
# $TaskComputer [Object]
# Optional, if provided: $TaskPackageID [String]
# Optional, if provided: $TaskPackage [Object]
# Optional, if provided: $TaskAction=1, 0 or -1 (1=Add, 0=Nothing Remove=-1) [String]
# Optional, if provided: $TaskMisc [String]
$TaskName = "Move computer from the W10 to the W11 configuration group and remove computer from the W11 inplace upgrade group";
Write-LogText ("$TaskNo : Task name is $TaskName.");
# Here your scripting code begin >>>
# <<< Here your scripting code finish
Exit 0;
CSV-Datei-Format
TaskID,Computername,Domainname,SoftwarepaketID,Aktion,Sonstiges
Die roten Datenfelder sind zwingend erforderlich.
Die grünen Datenfelder sind optional.
TaskID: Der TaskID muss eine gültige GUID sein und auf eine bestehende Aufgabe verweisen.
Computername/Domainname: Der Computer mit dem Namen und der Domäne/Arbeitsgruppe muss in der Empirum-Verwaltungsdatenbank existieren.
SoftwarepaketID: Jedes Empirum-Softwarepaket hat eine interne GUID als ID, die aus der Datei Swdepot.dds entnommen werden kann. Siehe Beispiel-Softwarepaketskript \Packages\upDateNow\EmpirumAPI-CSV-Task_Example-Package\1.0\Install\Setup.inf
Aktion: 1 = ADD, 0 = NOTHING, -1 = REMOVE
Sonstiges: In dem Datenfeld können Sie alle sonstigen Daten übergeben. Bei mehreren Daten dürfen Sie kein Komma als Separatorzeichen nutzen. Nehmen Sie anstatt dessen das | Zeichen. Beispiel: MAC|UUID|SERIALNUMBER. Sie müssen die PowerShell-Variable $TaskMisc in Ihrem Aufgaben-EmpirumSDK-PowerShell-Skript Task.ps1 anhand des Separatorzeichens | wieder zerlegen und die Unterdaten entsprechend weiterverarbeiten.
Beispiel:
197C77D8-FDA5-4052-8B58-2DB5B93650C8,CLIENT4711,UPDATENOW,ADB7A209-939B-4E4B-ABB5-E5EB2A3BFBFA,1,00155DB23E00| 5500EC98-01EC-410D-A1A5-9AA7AD569813|PE2SJPLQ
CSV-Datei Ablage und Benennung
Haupt-EmpirumServer: \\<Haupt-EmpirumServer>\Configurator$\Log\API-Tasks
Lokal auf dem Computer: C:\EmpirumAgent\Log\API-Tasks
Benennung: TaskID_Computername_Domainname_YYYY-MM-DD_HH-MM-SS.csv
Z.B. 197C77D8-FDA5-4052-8B58-2DB5B93650C8_CLIENT4711_UPDATENOW_2024-08-25_18-27-12.csv
Siehe Beispiel-Softwarepaketskript \Packages\upDateNow\EmpirumAPI-CSV-Task_Example-Package\1.0\Install\Setup.inf
Change-Log
2.4.8.28 / 28.08.2024 Erstversion freigegeben
Copyright © 2024 upDateNow GmbH
Diese Dokumentation ist urheberrechtlich geschützt. Alle Rechte liegen bei der upDateNow GmbH. Jede andere Nutzung, insbesondere die Weitergabe an Dritte, Speicherung innerhalb eines Datensystems, Verbreitung, Bearbeitung, Vortrag, Aufführung und Vorführung sind untersagt. Dies gilt sowohl für das gesamte Dokument als auch für Teile davon. Änderungen sind vorbehalten. Nachdruck, auch auszugsweise, ist nur mit schriftlicher Genehmigung der upDateNow GmbH gestattet.
Matrix42 und Empirum sind registrierte Markennamen der Matrix42 GmbH.
upDateNow GmbH
Wacholderweg 7
44869 Bochum
Germany
+49 2327 689 9977
