Anpassung von Runbooks
Passen Sie die generischen RealmJoin-Runbooks an die Bedürfnisse Ihrer Umgebung an.
Übersicht
Die RealmJoin-Runbook-Implementierung bietet dem Autor eines Runbooks oder dem Administrator einer Umgebung Anpassungsmöglichkeiten, sodass sie:
kunden-/Mandanten-spezifische Parameter und Vorlagen hosten
UI-Elemente wie Benutzer-Auswähler oder Dropdown-Auswahlen anbieten
menschenlesbare Erklärungen zu Parametern anzeigen
nicht benötigte UI-Elemente ausblenden

Die Anpassungen können im Runbook selbst und/oder in der RealmJoin-Portal-Instanz des Kunden gespeichert werden. Standardmäßig versuchen wir, in den auf angebotenen Runbooks sinnvolle Standardwerte bereitzustellen GitHub.
Einige Runbooks enthalten Beispiele zur Konfiguration kundenspezifischer Vorlagen, z. B. zur Angabe von Bürostandorten für die Benutzer-Onboarding.
Formatieren
Die Anpassungen können definiert werden (in absteigender Prioritätsreihenfolge)
JSON-Block in RealmJoin-Portal-Einstellungen, der das Standardverhalten des Runbooks überschreibt
JSON-Block im Header eines Runbooks
Zusätzlich (mit geringster Priorität)
pro Parameter im Runbook-Header
pro Parameter im Param-Block des Runbooks (unter Verwendung des RJRb Helper-Moduls)
Einige Funktionen (wie Vorlagen) sind nur im JSON-Format verfügbar. Einige Funktionen (wie das Erstellen eines Benutzer-Auswählers) sind nur verfügbar, wenn im Param-Block ein Datentyp angegeben ist. Sie können mehrere Anpassungsarten kombinieren, um beste Ergebnisse zu erzielen.
Runbook-Param-Block
Das RealmJoin-Portal parst den PowerShell-Param-Block eines Runbooks, um zu bestimmen, welche Eingabefelder gerendert werden sollen. Wo möglich, validiert es die Eingaben auch anhand des für eine Variable angegebenen .NET-Typs.
Die folgenden Datentypen werden derzeit verstanden:
[bool],[boolean]- zeigt einen binären Umschalter an[string]- zeigt ein Textfeld zum Eingeben beliebiger alphanumerischer Eingaben an[int]- zeigt ein Textfeld an, das nur numerische Eingaben zulässt[DateTime],[DateTimeOffset]- zeigt einen Datums-/Zeitwähler an
Sie können Standard-PowerShell-Modifizierer auf Parameter anwenden. RealmJoin-Portal versteht insbesondere, wenn Sie angeben [Parameter(Mandatory = $true)] um einen Pflichtparameter zu kennzeichnen und durchzusetzen, dass diese Parameter ausgefüllt werden.
Wenn möglich, liest das RealmJoin-Portal auch angegebene Standardwerte und zeigt sie in der UI an.
Beachten Sie, dass Standardwerte aus dem Runbook durch Anpassungen überschrieben werden können. Zusätzlich können Parameter durch Anpassungen vollständig ausgeblendet werden.
Parameter anpassen
Um Parameter anpassen zu können, stellen Sie bitte sicher, dass das RealmJoin Runbook Helper PS-Modul in Ihrem Runbook eingebunden ist:
#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }
Sie können dann einfügen [ValidateScript( { Use-RJInterface ... } )] Anweisungen in die Parameterdefinitionen. Zum Beispiel erzeugt das Folgende einen Benutzer-Auswähler, der die Auswahl eines Entra ID-Benutzers erlaubt und dessen Objekt-ID als Zeichenfolge an das Runbook übergibt.
Lassen Sie uns das Stück für Stück betrachten. [ValidateScript...] ist ein Modifizierer für den nächsten im Param-Block definierten Parameter. In diesem Fall die Variable $AssignedUserId.
Use-RJInterface ist Teil unseres RealmJoin Runbook Helper PowerShell-Moduls. Es ermöglicht Ihnen anzugeben, welche Art von Eingabe Sie erwarten, mittels -Type als auch für -Entity, falls dies nicht bereits vollständig durch den Variablentyp definiert ist.
-DisplayName ermöglicht Ihnen, eine menschenlesbare Eingabeaufforderung/Beschreibung für diesen Parameter an RealmJoin Portal zu übergeben.
Graph-Ressourcen
Im obigen Beispiel ist die Informationsquelle MS Graph, wie durch -Type Graph. Für MS Graph verwenden Sie -Entity um anzugeben, welche Art von Ressource Sie erwarten. Verfügbare Entitäten sind Nutzern, Gruppe, Gerät. Dies erzeugt einen Auswähler für entweder Benutzer, Gruppen oder Geräte im angegebenen Entra ID.
Der Auswähler enthält eine Schnellsuche, um die benötigte Ressource leicht zu finden.

Derzeit ist mit einem Auswähler keine Mehrfachauswahl möglich.
Standardmäßig gibt ein MS Graph-Auswähler die Objekt-ID zurück. Wenn Sie z. B. stattdessen den User Principal Name benötigen, stellen Sie sicher, dass Sie "name" als Suffix im Namen Ihrer Variable einfügen. Also, um die ID eines Benutzers zu erhalten, benennen Sie den Parameter $userid. Wenn Sie eine UPN wollen, nennen Sie ihn $username.
Graph-Filterung
Wenn Sie einen MS Graph-basierten Auswähler verwenden, können Sie auch -Filter spezifizieren und einen ODATA-Filter
verwenden, um die im Auswähler angebotenen Objekte zu begrenzen.
[String] $GroupID_License Sie können Filter vorbereiten und sie in mehreren Skripten wiederverwenden, indem Sie denzentralen Datenspeicher verwenden. In diesem Fall referenzieren Sie den Filter einfach per Namen mit-Filter "ref:LicenseGroup" , wobei ref:
[ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )] Dieses spezielle Beispiel ref:LicenseGroup

ODATA-Filter
Runbook-Header Das Portal kann die kommentarbasierte Hilfe
Sektion eines Runbooks parsen, falls vorhanden.
Hier ist ein Beispiel: "Lizenz von Benutzer entfernen": true
(De-)Zuweisen einer Lizenz zu einem Benutzer über Gruppenmitgliedschaft. - Geben Sie eine sehr kurze Beschreibung der Funktion Ihres Runbooks. Diese wird in der Liste der verfügbaren Runbooks angezeigt.
- Geben Sie eine Beschreibung der Funktion Ihres Runbooks. Kann etwas detaillierter sein, da diese innerhalb des Ausführungs-/Parameterdialogs des Runbooks angezeigt wird. .PARAMETER
- Group.ReadWrite.All - Muss von einem Parametername gefolgt werden. Ermöglicht es Ihnen, eine detaillierte Erklärung der erwarteten Eingabe für den jeweiligen Parameter zu geben.
Kommagetrennte Liste von Gruppen zur Zuweisung. z. B. "DL Sales,LIC Internal Product" - Kann einen Block JSON-basierter Runbook-Anpassungen enthalten.
- Wird nicht geparst/gerendert. Bitte verwenden Sie diesen Bereich, um aufzuschreiben, welche Berechtigungen und Anforderungen für Ihr Runbook bestehen. .EXAMPLE
- Wird nicht geparst/gerendert. Kann ein Beispiel einer JSON-basierten Anpassung enthalten, die im RealmJoin-Datenspeicher Ihres Mandanten verwendet werden kann. Diese können Beispiele dafür sein, wie Vorlagen z. B. für verschiedene Workflows oder Benutzerklassen erstellt werden.
JSON-basierte Anpassungen
Zentraler Datenspeicher Jeder Azure-Mandant kann einen "Runbook Customizations"-Datenspeicher hosten, zu finden unter .
https://portal.realmjoin.com/settings/runbooks-customizations Einstellungen, Das Format ist JSON mit Kommentaren und erlaubt abschließende Kommas. Derzeit gibt es drei relevante Abschnitte,, Runbooks.
"Runbooks": {
Runbooks Der Runbooks-Abschnitt wird vom Portal beim Starten eines Runbooks geparst. Wenn ein Abschnitt mit dem Namen des aktuellen Azure Automation Runbooks existiert, werden dessen Inhalte verwendet, um das Frontend, das dem Benutzer angezeigt wird, anzupassen.
Angenommen, folgendes einfache Demonstrations-Runbook namens rjgit-device_demo-runbook-customizing.
Wenn nicht angepasst, wird es im Frontend wie folgt dargestellt:

Gedanken:
Da dieses Runbook im Kontext eines Geräts im Portal gestartet wird, sind die
$DeviceIdfür einen Benutzer redundante Informationen. Ich weiß bereits, an welchem Gerät ich arbeite.Was passiert, wenn ich den "Extra Workflow" aktiviere oder deaktiviere? Muss ich an "Extra Workflow Time" denken, wenn ich den "Extra Workflow" deaktiviere?
Lassen Sie uns das verbessern. Das folgende Beispiel-JSON im zentralen Datenspeicher wird die UI für das Runbook ändern.
Sie können dieselbe Notation/Funktionen auch in Ihrem Runbook-Header.
ParameterList
Jeder Parameter hat seinen eigenen Abschnitt in ParameterList. Modifizierer ermöglichen es, das Verhalten dieses Parameters zu ändern.
Das Ergebnis wird wie folgt aussehen:

Das Wählen des zusätzlichen Workflows wird mehr Parameter anzeigen (einblenden):

Dies zeigt weniger Unordnung im Vergleich zu vor der Anpassung. Gleichzeitig stehen dem Benutzer mehr Informationen über die Alternativen des "Extra Workflow" zur Verfügung. Außerdem muss sich ein Benutzer jetzt nur noch Gedanken über die "Extra Workflow Time" machen, wenn diese relevant ist.
Die Änderung der Sichtbarkeit dieses Feldes wurde mit einem "Customization" Block innerhalb einer der "Select" Optionen vorgenommen. Derzeit kann höchstens ein solcher "Customization" Block gleichzeitig aktiv sein.
Wie Sie sehen, ist der Parameter $DeviceId vollständig ausgeblendet. Dies geschieht durch Setzen des "UserName": { für diesen Parameter.
Parameter können ein DisplayNamehaben. DisplayName Wir haben einen benutzerfreundlichen angeboten, um $ExtraWorkflowTime in der UI zu ersetzen. Siehe andere Modifizierer
für mehr. Name Sie können "unnamed" Parameter (ohne die Wählen Sie.
Wählen Sie
Anweisung) einfügen, wie den Bereich "Zusätzlichen Workflow ausführen", wenn Sie UI-Elemente anbieten möchten, ohne direkt einen Wert zurückzugeben. Dies wird normalerweise nur in Verbindung mit Wählen Sieverwendet. Wir haben , verwendet, um eine Liste von Anzeige Optionen Anpassungin einem Dropdown anzuzeigen. Jede Option kann Text setzen oder einen triggern, wie z. B. das Setzen von Hide oder einen angeboten, um Default Wert für andere Parameter. In unserem Beispiel haben wir es verwendet, umein- bzw. auszublenden und
angeboten, um $ExtraWorkflow Wert für andere Parameter. In unserem Beispiel haben wir es verwendet, um 's Wert zu überschreiben.
wird somit nur angezeigt, wenn es relevant ist, und der binäre Schalter Wählen Sie ist nun aus Sicht des Benutzers durch sinnvolle Alternativen ersetzt. Im Falle eines für einen benannten Parameter sollte jede Option einen "ParameterValue": "..." haben, der an das Runbook übergeben wird. Sie können ein Wählen Sie "ShowValue: false"
innerhalb des
Der Hide / "ParameterValue": false, "ShowValue": false DisplayName DefaultValue
Parameter
Die Anweisung im Parameter legt auch den Anfangszustand des Dropdowns fest. Bei einem unbenannten Parameter verwenden Sie den Parameter der gewünschten Option, andernfalls geben Sie einen Standardrückgabewert an, wie "true" oder "false" oder eine Zeichenfolge. ParameterList.
Wenn Sie nur benannte Parameter haben, können Sie das etwas kürzere
Format anstelle von
verwenden. Wählen Sie Siehe als Beispiel SelectSimple Format anstelle von.
Format anstelle von SelectSimple
Beispiel:
"Skip Device Mindfulness": false angeboten, um "ExtraWorkflowTime": {
Modifizierer
"DisplayName": "Wie lange meditieren?"
Der größte Unterschied (abgesehen davon, dass es viel kürzer ist) zu unserem vorherigen Beispiel ist, dassimmer sichtbar ist.Jeder Parameter kann eine oder mehrere der folgenden Modifizierer haben:"DisplayName": "Text"- Zeigt "Text" als Namen des Parameters in der UI an"Hide": true / false- Blendet diesen Parameter aus"Mandatory": true / false- Erfordert, dass dieser Parameter ausgefüllt wird"ReadOnly": true / falseHide- Schützt diesen Parameter davor, von seinem Standardwert geändert zu werden"DefaultValue": "..."- Setzt einen Standardwert für diesen Parameter. (Sie können auch Graph-Filterungverwenden.)"GraphFilter": "startswith(DisplayName, 'LIC_')"
Einstellungen
Einstellungen - siehe
"AllowEdit": true / false Use-RJInterface.
- Schützt diesen Parameter vor manueller Bearbeitung. (Kombinieren Sie dies mit Vorlagen)
[string] $StorageAccountLocation,
[ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Sku" } )]
"Name": "rjrbexports01", "Location": "Westeuropa", "Sku": "Standard_LRS"
Das Format ist JSON mit Kommentaren und erlaubt abschließende Kommas. Derzeit gibt es drei relevante Abschnitte,
Das Format ist JSON mit Kommentaren und erlaubt abschließende Kommas. Derzeit gibt es drei relevante Abschnitte, Das fehlende Wählen Sie Container
Element wird einfach nicht in der UI vorausgefüllt.
verwenden JSON-Referenzen, um Daten einzubinden - zum Beispiel eine lange Liste von Bürostandorten - wenn Sie eine
Anweisung verwenden. Dies ermöglicht es, eine Anpassung neutral/wiederverwendbar/getrennt von den tatsächlichen Daten zu halten. haben, der an das Runbook übergeben wird. Sie können ein Runbooks Nehmen wir das Beispiel des Onboardings neuer Benutzer. Sie könnten mehrere vorgegebene Optionen für Abteilungen oder Bürostandorte haben, wobei die Zuweisung eines Bürostandorts auch eine bestimmte Straßenadresse, Land, Bundesland usw. vorschreibt. Das Format ist JSON mit Kommentaren und erlaubt abschließende Kommas. Derzeit gibt es drei relevante Abschnitte, Das folgende Beispiel einer Runbook-Anpassung verwendet den $ref/Abschnitt, um einen Teilbaum aus dem Abschnitt zu referenzieren/zu importieren. Achten Sie auf die $ref/Abschnitt, um einen Teilbaum aus dem $id Dies ermöglicht es, eine Anpassung neutral/wiederverwendbar/getrennt von den tatsächlichen Daten zu halten.$values Das Format ist JSON mit Kommentaren und erlaubt abschließende Kommas. Derzeit gibt es drei relevante Abschnitte, Schlüsselwörter. Beachten Sie, dass Runbooks vor dem Referenzieren mit
definiert werden müssen. Deshalb wird $ref in diesem Beispiel vor definiert. In diesem Beispiel sagen wir dem Portal, den Teilbaum mit dem Abschnitt, um einen Teilbaum aus demaufzurufen, der Dies ermöglicht es, eine Anpassung neutral/wiederverwendbar/getrennt von den tatsächlichen Daten zu halten. LocationOptions Wählen Sie genannt wird und dessen Runbooks einzuschließen und die Das Format ist JSON mit Kommentaren und erlaubt abschließende Kommas. Derzeit gibt es drei relevante Abschnitte,.
Anweisung zu ersetzen. Das Portal rendert also ein Anpassung wie im Abschnitt beschrieben, nimmt aber die tatsächlichen Optionen aus.
Eine Vorlage kann jede Anweisung enthalten, die am referenzierenden Ort unterstützt wird. In diesem Beispiel verwenden wir eine Runbooks Anweisung, um andere Parameter wie
"StreetAddress",


"Country"
Dies wird die folgende UI erzeugen: Demo - ref-location Demo - ref-address Graph-Filter.
Sie können DisplayName ODATA Graph-Filter
Siehe Das folgende Beispiel filtert nach einem bestimmten Präfix im eines Gruppennamens, um in einem Gruppen-Auswähler nur lizenzbezogene Gruppen anzuzeigen., das auch standardmäßig im RJ-Code enthalten ist: "LicenseGroup": "startswith(DisplayName, 'LIC_')" // auch im RJ-Code als Standard enthalten
Zuletzt aktualisiert
War das hilfreich?