> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-customization.md).

# Runbook-Anpassung

Passen Sie die generischen Runbooks von RealmJoin an die Anforderungen Ihrer Umgebung an.

## Übersicht

Die RealmJoin Runbook-Implementierung bietet dem Autor eines Runbooks oder einem Administrator einer Umgebung Anpassungsmöglichkeiten, sodass sie:

* kundenspezifische/Tenant-spezifische Parameter und Vorlagen hosten
* UI-Elemente wie Benutzer-Auswahllisten oder Dropdown-Auswahlen anbieten
* menschenlesbare Erklärungen von Parametern anzeigen
* nicht benötigte UI-Elemente ausblenden

<figure><img src="https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2FmVmZrDFgG1ShkZlo1Fbe%2Fimage.png?alt=media&amp;token=39876732-3578-41d2-acf1-8571bb941e68" alt=""><figcaption></figcaption></figure>

Die Anpassungen können im Runbook selbst enthalten sein und/oder in der RealmJoin Portal-Instanz des Kunden gespeichert werden. Standardmäßig werden wir versuchen, sinnvolle Standardwerte in den auf [GitHub](https://github.com/realmjoin/realmjoin-runbooks).

Einige Runbooks werden Beispiele dafür enthalten, wie kundenspezifische Vorlagen konfiguriert werden, z. B. die Angabe von Office-Standorten für das Onboarding von Benutzern.

### Formatieren

Das Customizing kann definiert werden (in absteigender Prioritätsreihenfolge)

* JSON-Block in [RealmJoin Portal-Einstellungen](https://portal.realmjoin.com/settings/runbooks-customizations), wodurch das Standardverhalten des Runbooks überschrieben wird
* 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 Module)

Einige Funktionen (wie Vorlagen) sind nur im JSON-Format verfügbar. Einige Funktionen (wie das Erstellen eines Benutzer-Auswahlfelds) sind nur verfügbar, wenn im Param-Block ein Datentyp angegeben wird. Sie können mehrere Arten von Anpassungen kombinieren, um die besten Ergebnisse zu erzielen.

## Runbook-Param-Block

Das RealmJoin Portal analysiert den PowerShell-Param-Block eines Runbooks, um zu bestimmen, welche Eingabefelder dargestellt werden sollen. Wenn möglich, validiert es die Eingaben auch anhand des für eine Variable angegebenen .NET-Typs.

Die folgenden Datentypen werden derzeit unterstützt:

* `[bool]`, `[boolean]` - zeigt einen binären Umschalter an
* `[string]` - zeigt ein Textfeld an, in das beliebige alphanumerische Eingaben eingegeben werden können
* `[int]` - zeigt ein Textfeld an, das nur numerische Eingaben zulässt
* `[DateTime]`, `[DateTimeOffset]` - zeigt eine Datum/Uhrzeit-Auswahl an

Sie können Standard-PowerShell-Modifier auf Parameter anwenden. Insbesondere das RealmJoin Portal versteht, wenn Sie angeben `[Parameter(Mandatory = $true)]` um einen Pflichtparameter anzugeben und zu erzwingen, dass diese Parameter ausgefüllt werden.

Wenn möglich, liest das RealmJoin Portal auch angegebene Standardwerte aus und zeigt sie in der UI an.

Beachten Sie, dass Standardwerte aus dem Runbook durch Anpassungen überschrieben werden können. Außerdem können Parameter durch Anpassungen vollständig ausgeblendet werden.

### Parameter anpassen

Damit Sie Parameter anpassen können, stellen Sie bitte sicher, dass Sie das RealmJoin Runbook Helper PS Module in Ihr Runbook einbinden:

`#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }`

Sie können dann `[ValidateScript( { Use-RJInterface ... } )]` Anweisungen in die Parameterdefinitionen aufnehmen. Das folgende Beispiel erstellt beispielsweise eine Benutzer-Auswahl, mit der ein Entra ID-Benutzer ausgewählt werden kann, und übergibt dessen Objekt-ID als String an das Runbook.

```powershell
param(
    [ValidateScript( { Use-RJInterface -DisplayName "Assign device to this user (optional)" -Type Graph -Entity User } )]
    [string] $AssignedUserId = ""
)
```

Gehen wir das Stück für Stück durch. `[ValidateScript...]` ist ein Modifier für den nächsten im Param-Block definierten Parameter. In diesem Fall ist die Variable `$AssignedUserId`.

`Use-RJInterface` ist Teil unseres [RealmJoin Runbook Helper](https://github.com/realmjoin/RealmJoin.RunbookHelper) PowerShell-Moduls. Es ermöglicht Ihnen anzugeben, welche Art von Eingabe Sie erwarten, indem Sie `-Type` und `-Entity`, sofern dies nicht bereits vollständig durch den Typ der Variable definiert ist.

`-DisplayName` ermöglicht es Ihnen, dem RealmJoin Portal eine menschenlesbare Eingabeaufforderung / Beschreibung für diesen Parameter zu übergeben.

#### Graph-Ressourcen

Im obigen Beispiel ist die Informationsquelle MS Graph, wie beschrieben durch `-Type Graph`. Verwenden Sie für MS Graph `-Entity` um anzugeben, welche Art von Ressource Sie erwarten. Verfügbare Entitäten sind `User`, `Gruppe`, `Gerät`. Dadurch wird eine Auswahl für Benutzer, Gruppen oder Geräte im angegebenen Entra ID erstellt.

Die Auswahl enthält eine Schnellsuche, um die benötigte Ressource leicht zu finden.

![Auswahlbeispiel](https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-0c393c4ea73a77b34da2c678b0712a6556ed3bc2%2Frunbook-customization-img2.png?alt=media)

Derzeit ist mit einer Auswahl keine Mehrfachauswahl möglich.

Standardmäßig gibt eine MS Graph-Auswahl die ID des Objekts zurück. Wenn Sie stattdessen z. B. den User Principal Name benötigen, stellen Sie sicher, dass Sie "name" als Suffix im Namen Ihrer Variable verwenden. Um also die ID eines Benutzers zu erhalten, benennen Sie den Parameter `$userid`. Wenn Sie einen UPN möchten, nennen Sie ihn `$username`.

#### Graph-Filterung

Wenn Sie eine auf MS Graph basierende Auswahl verwenden, können Sie auch `-Filter` und einen [ODATA-Filter](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) verwenden, um die in der Auswahl angebotenen Objekte einzuschränken.

Das folgende Beispiel listet nur Gruppen aus Entra ID auf, die mit "LIC\_" beginnen.

```powershell
param(
    [Parameter(Mandatory = $true)]
    [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "startswith(DisplayName, 'LIC_')" -DisplayName "License group" } )]
    [String] $GroupID_License
)
```

Sie können Filter vorbereiten und mithilfe des [zentralen Datenspeichers](#graph-filters). Verweisen Sie in diesem Fall einfach über den Namen auf den Filter, indem Sie `-Filter "ref:LicenseGroup"`, wobei `ref:` angibt, dass nach einem gespeicherten Filter gesucht werden soll.

```powershell
param(
    [Parameter(Mandatory = $true)]
    [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )]
    [String] $GroupID_License
)
```

Dieses spezielle Beispiel `ref:LicenseGroup` ist standardmäßig ohne weitere Konfiguration verfügbar.

![ODATA-Filter](https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-4913ddfbc3324fc7a3522de2bc6887e8d2745e35%2Frunbook-customization-img3.png?alt=media)

## Runbook-Header

Das Portal kann den [kommentarbasierten Hilfebereich](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1) eines Runbooks analysieren, sofern vorhanden.

Hier ist ein Beispiel:

```powershell
<#
  .SYNOPSIS
  (De-)Zuweisen einer Lizenz an einen Benutzer über die Gruppenmitgliedschaft.

  .DESCRIPTION
  (De-)Zuweisen einer Lizenz an einen Benutzer über die Gruppenmitgliedschaft. Detailliertere Beschreibung...

  .PARAMETER DefaultGroups
  Kommagetrennte Liste von Gruppen, die zugewiesen werden sollen. z. B. "DL Sales,LIC Internal Product"

  .NOTES
  Berechtigungen:
  MS Graph (API):
  - User.Read.All
  - GroupMember.ReadWrite.All 
  - Group.ReadWrite.All

  .INPUTS
  RunbookCustomization: {
        "Parameter": {
            "UserName": {
                "Hide": true
            },
            "Remove": {
                "DisplayName": "Lizenz zuweisen oder entfernen",
                "SelectSimple": {
                    "Lizenz dem Benutzer zuweisen": false,
                    "Lizenz vom Benutzer entfernen": true
                }
            }
        }
    }
#>
```

`.SYNOPSIS` - Geben Sie eine sehr kurze Beschreibung der Funktion Ihres Runbooks an. Diese wird in der Liste der verfügbaren Runbooks angezeigt.

`.DESCRIPTION` - Geben Sie eine Beschreibung der Funktion Ihres Runbooks an. Sie kann etwas detaillierter sein, da sie innerhalb des Ausführungs-/Parameterdialogs der Runbooks angezeigt wird.

`.PARAMETER` - Muss von einem Parameternamen gefolgt werden. Ermöglicht Ihnen, eine ausführliche Erklärung der erwarteten Eingabe für den betreffenden Parameter anzugeben.

`.INPUTS` - Kann einen Block mit JSON-basierter Runbook-Anpassung enthalten.

`.NOTES` - Wird nicht analysiert / gerendert. Bitte nutzen Sie diesen Bereich, um festzuhalten, welche Berechtigungen und Voraussetzungen für Ihr Runbook gelten.

`.EXAMPLE` - Wird nicht analysiert / gerendert. Kann ein Beispiel für eine JSON-basierte Anpassung enthalten, die im RealmJoin Datastore Ihres Tenant verwendet werden soll. Dies können Beispiele dafür sein, wie Vorlagen erstellt werden, z. B. für unterschiedliche Workflows oder Benutzerklassen.

## JSON Based Customizing

### Zentraler Datenspeicher

Jeder Azure Tenant kann einen Datenspeicher für "Runbook-Anpassungen" hosten, zu finden unter <https://portal.realmjoin.com/settings/runbooks-customizations> .

Das Format ist JSON mit Kommentaren und erlaubt nachgestellte Kommata. Derzeit gibt es drei relevante Abschnitte, `Einstellungen`, `Vorlagen`, `Runbooks`.

```json
{
    "Settings": {
    },
    "Templates": {
    },
    "Runbooks": {
    }
}
```

### Runbooks-Abschnitt

`Runbooks` wird vom Portal beim Starten eines Runbooks analysiert. Wenn ein Abschnitt mit dem Namen des aktuellen Azure Automation Runbooks existiert, wird dessen Inhalt verwendet, um das dem Benutzer angezeigte Frontend anzupassen.

Nehmen wir das folgende einfache Demonstrations-Runbook an, genannt `rjgit-device_demo-runbook-customizing`.

```powershell
<#
  .SYNOPSIS
  Runbook-Customizing demonstrieren

  .DESCRIPTION
  Runbook-Customizing demonstrieren, z. B. Dropdown/Auswahl
#>

#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }

param(
    [string] $DeviceId,
    [bool] $ExtraWorkflow = $true,
    [int] $ExtraWorkflowTime = 15
)

"## Arbeiten am Gerät '$DeviceID'"

# Hochgradig optionaler, komplexer Workflow
if ($ExtraWorkflow) {
    "## Meditation wird ausgeführt..."
    Start-Sleep -Seconds $ExtraWorkflowTime
}
```

Ohne Anpassung wird es im Frontend so dargestellt:

![Demo - vorher](https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-931b958f4b949268736f6ff3f174913cf56adcf7%2Frunbook-customization-img4.png?alt=media)

Gedanken:

* Da dieses Runbook aus dem Kontext eines Geräts im Portal gestartet wird, ist die `$DeviceId` für einen Benutzer redundante Information. Ich weiß bereits, an welchem Gerät ich arbeite.
* Was passiert, wenn ich den "Extra Workflow" aktiviere oder deaktiviere? Muss ich an die "Extra Workflow Time" denken, wenn ich "Extra Workflow" deaktiviere?

Verbessern wir das. Das folgende Beispiel-JSON im zentralen Datenspeicher wird die UI für das Runbook anpassen.

```json
{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "ParameterList": [
                {
                    "Name": "DeviceId",
                    "Hide": true
                }, 
                {
                    "Name": "ExtraWorkflow",
                    "Hide": true
                },
                {
                    "Name": "ExtraWorkflowTime",
                    "DisplayName": "Wie lange meditieren?",
                },
                {
                    "DisplayName": "Extra Workflow ausführen",
                    "DisplayBefore": "ExtraWorkflowTime",
                    "Select": {
                        "Options": [
                            {
                                "Display": "Meditation ausführen (optional)",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": true
                                    }
                                }
                            },
                            {
                                "Display": "Geräte-Achtsamkeit überspringen",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": false
                                    },
                                    "Hide": [
                                        "ExtraWorkflowTime"
                                    ]
                                }
                            }
                        ],
                        
                    },
                    "Default": "Geräte-Achtsamkeit überspringen"
                }
            ]
        }
    }
}
```

Sie können in Ihrem dieselbe Notation / dieselben Funktionen verwenden [Runbook-Header](#runbook-header).

#### ParameterList

Jeder Parameter hat seinen eigenen Abschnitt in `ParameterList`. [Modifier](#modifiers) ermöglichen es, das Verhalten dieses Parameters zu ändern.

Das Ergebnis sieht folgendermaßen aus:

![Demo - nach dem Ausblenden](https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-4ae4e681371ad29f076063c5f1925a0cb8113872%2Frunbook-customization-img5.png?alt=media)

Wenn Sie den zusätzlichen Workflow auswählen, werden weitere Parameter angezeigt (eingeblendet):

![Demo - nach dem Einblenden](https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-7960cf8309d8bbdf12ab1539c073714211715411%2Frunbook-customization-img6.png?alt=media)

Dies sorgt im Vergleich zu vor der Anpassung für weniger Unordnung. Gleichzeitig stehen dem Benutzer mehr Informationen über die Alternativen von "Extra Workflow" zur Verfügung. Außerdem muss sich ein Benutzer nun nur dann um "Extra Workflow Time" kümmern, wenn sie relevant ist.

Die Sichtbarkeit dieses Feldes wurde mithilfe eines `"Customization"` Blocks innerhalb einer der `"Select"` Optionen. Derzeit kann jeweils nur ein solcher `"Customization"` Block gleichzeitig aktiv sein.

Wie Sie sehen, ist der Parameter `$DeviceId` vollständig ausgeblendet. Dies geschieht durch Setzen des `"Hide": true` für diesen Parameter.

Parameter können ein `DisplayName`. Wir haben eine benutzerfreundliche `DisplayName` als Ersatz für `$ExtraWorkflowTime` in der UI angeboten. Siehe andere [Modifier](#modifiers) für weitere Informationen.

Sie können "unbenannte" Parameter einfügen (bei denen die `Name` Anweisung fehlt), wie den Abschnitt "Execute Extra Workflow", wenn Sie UI-Elemente anbieten möchten, ohne direkt einen Wert zurückzugeben. Dies wird normalerweise nur in Verbindung mit `Wählen Sie`.

#### Wählen Sie

Wir haben `Wählen Sie`, um eine Liste von `Optionen` in einem Dropdown anzuzeigen. Jede Option kann `Anzeige` Text anzeigen oder eine `Anpassung`, z. B. das Setzen eines `Hide` oder ein `Standard` Werts für andere Parameter. In unserem Beispiel haben wir es verwendet, um `$ExtraWorkflowTime` und zu überschreiben `$ExtraWorkflow`s Wert.

`$ExtraWorkflowTime` wird daher nur angezeigt, wenn es relevant ist, und der binäre Schalter `$ExtraWorkflow` ist aus Sicht des Benutzers nun durch sinnvolle Alternativen ersetzt.

Im Fall eines `Wählen Sie` für einen benannten Parameter sollte jede Option ein `"ParameterValue": "..."` zum Runbook übergeben. Sie können ein `"ShowValue: false"` in den `Wählen Sie` Block einfügen, um nur das Dropdown und kein Feld für den resultierenden Parameterwert anzuzeigen.

Beispiel für benannten Parameter:

```json
{
    "Name": "ExtraWorkflow",
    "DefaultValue": true,
    "DisplayName": "Extra Workflow ausführen",
    "DisplayBefore": "ExtraWorkflowTime",
    "Select": {
        "Options": [
            {
                "Display": "Meditation ausführen (optional)",
                "ParameterValue": true
            },
            {
                "Display": "Geräte-Achtsamkeit überspringen",
                "ParameterValue": false,
                "Customization": {
                    "Hide": [
                        "ExtraWorkflowTime"
                    ]
                }
            }
        ],
        "ShowValue": false
    }
}
```

Die `Standard` / `DefaultValue` Anweisung im Parameter gibt auch den Ausgangszustand des Dropdowns an. Im Fall eines unbenannten Parameters verwenden Sie `DisplayName` der gewünschten Option, andernfalls einen Standard-Rückgabewert wie "true" oder "false" oder einen beliebigen String.

#### Parameter

Wenn Sie nur benannte Parameter haben, können Sie das etwas kürzere `Parameter` Format anstelle von `ParameterList`.

Ein Beispiel finden Sie unter SelectSimple

#### SelectSimple

Wenn die volle Leistungsfähigkeit eines `Wählen Sie` nicht benötigt wird und Sie lediglich eine Liste möglicher Werte in einem Dropdown anbieten möchten (ohne zusätzliche Anpassungen vorzunehmen), können Sie `SelectSimple`.

`SelectSimple` nur für benannte Parameter verwenden.

Beispiel:

```json
{
    "Runbooks": {
        "rjgit-device_demo-runbook-customizing": {
            "Parameter": {
                "DeviceId": {
                    "Hide": true
                }, 
                "ExtraWorkflow": {
                    "Name": "ExtraWorkflow",
                    "DisplayName": "Extra Workflow ausführen",
                    "Default": false,
                    "SelectSimple": {
                        "Meditation ausführen (optional)": true,
                        "Geräte-Achtsamkeit überspringen": false
                    }
                },
                "ExtraWorkflowTime": {
                    "DisplayName": "Wie lange meditieren?"
                }
            }
        }
    }
}
```

Der größte Unterschied zu unserem vorherigen Beispiel – abgesehen davon, dass es viel kürzer ist – besteht darin, dass `$ExtraWorkflowTime` immer sichtbar ist.

#### Modifier

Jeder Parameter kann einen oder mehrere der folgenden Modifier haben:

* `"DisplayName": "text"` - Zeigt "text" als Namen für den Parameter in der UI an
* `"Hide": true / false` - Blendet diesen Parameter aus
* `"Mandatory": true / false` - Erfordert, dass dieser Parameter ausgefüllt wird
* `"ReadOnly": true / false` - Schützt diesen Parameter davor, von seinem Standardwert geändert zu werden
* `"DefaultValue": "..."` - Legt einen Standardwert für diesen Parameter fest. (Sie können stattdessen auch `Standard` verwenden.)
* `"GraphFilter": "startswith(DisplayName, 'LIC_')"` - siehe [Graph-Filterung](#graph-filtering)
* `"AllowEdit": true / false` - Schützt diesen Parameter vor manueller Bearbeitung. (Kombinieren Sie dies mit Vorlagen)

### Einstellungen

`Einstellungen` ermöglicht es Ihnen, Konfigurationsdaten wie Azure Storage Account-Namen an einer zentralen Stelle zu speichern und sie dennoch von Ihren Runbooks getrennt zu halten.

Sie können mithilfe von `Use-RJInterface`.

Nehmen wir diesen Beispiel-Param-Block eines Runbooks:

```powershell
param(
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.ResourceGroup" } )]
    [string] $ResourceGroupName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.StorageAccountName" } )]
    [string] $StorageAccountName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "RJReport.StorageAccount.LinkExpiryDays" } )]
    [int] $LinkExpiryDays = 6
)
```

Das Portal versucht, jeden Parameter mit Werten aus dem zentralen Datenspeicher vorab zu befüllen – falls vorhanden. Das funktioniert auch, wenn der Parameter in der UI ausgeblendet wurde.

Ein mögliches JSON im Datenspeicher für dieses Runbook wäre:

```json
{
    "Settings": {
        "RJReport": {
            "StorageAccount": {
                "ResourceGroup": "rj-runbooks-01",
                "StorageAccountName": "rjrbexports01"
            }
        }
    }
}
```

Das fehlende `LinkExpiryDays` Element wird einfach nicht in der UI vorbefüllt, sodass der Parameter seinen Standardwert von `6`.

Ein Runbook-Block im `Runbooks` Abschnitt kann seine eigene `Einstellungen`. Für jeden Wert schaut das Portal zuerst dort nach und erst dann im globalen `Einstellungen`, sodass einzelne Runbooks unterschiedliche Werte verwenden können. Siehe [Verwenden Sie für einzelne Runbooks einen anderen Storage Account](https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-report-settings.md#use-a-different-storage-account-for-individual-runbooks) für ein Beispiel.

### Vorlagen

`Vorlagen` verwenden Sie JSON-Referenzen, um Daten einzubinden – zum Beispiel eine umfangreiche Liste von Office-Standorten –, wenn Sie eine `Wählen Sie` Anweisung verwenden.

Dadurch bleibt eine Anpassung neutral/wiederverwendbar/getrennt von den eigentlichen Daten.

Nehmen wir das Beispiel des Onboardings neuer Benutzer. Sie könnten mehrere vorgegebene Optionen für Abteilungen oder Office-Standorte haben, wobei die Zuweisung eines Office-Standorts auch eine bestimmte Straßenadresse, ein Land, ein Bundesland usw. erfordert.

Das folgende Beispiel einer Runbook-Anpassung verwendet den `$ref` in den `Runbooks` Abschnitt, um einen Teilbaum aus dem `Vorlagen` Abschnitt zu referenzieren/importieren. Achten Sie auf die `$id`/`$values` Schlüsselwörter. Beachten Sie, dass `$id`/`$values` müssen, bevor Sie sie mit `$ref`verwenden. Deshalb ist `Vorlagen` vor `Runbooks` in diesem Beispiel definiert.

In diesem Beispiel weisen wir das Portal an, den Teilbaum mit dem `$id` namens `LocationOptions` und dessen `$values`, wodurch die `$ref` Anweisung ersetzt wird. Das Portal rendert also eine `Wählen Sie` wie im `Runbooks` Abschnitt beschrieben, enthält aber die tatsächlichen Optionen aus `Vorlagen`.

Eine Vorlage kann jede Anweisung enthalten, die am referenzierenden Ort unterstützt wird. In diesem Beispiel verwenden wir eine `Anpassung` Anweisung, um andere Parameter wie `StreetAddress`.

So können wir eine runbookspezifische Anpassung in `Runbooks` über mehrere Umgebungen hinweg wiederverwendbar machen und dabei die eigentlichen Daten getrennt halten.

```json
{
    "Templates": {
        "Options": [
            {
                "$id": "LocationOptions",
                "$values": [
                    {
                        "Display": "DE-OF",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Kaiserstraße 39",
                                "PostalCode": "63065",
                                "City": "Offenbach",
                                "Country": "Deutschland"
                            }
                        }
                    },
                    {
                        "Display": "DE-DEG",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Lateinschulgassse 24-26",
                                "PostalCode": "94469",
                                "City": "Deggendorf",
                                "Country": "Deutschland"
                            }
                        }
                    },
                    {
                        "Display": "DE-HH",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Hans-Henny-Jahnn-Weg 53",
                                "PostalCode": "22085",
                                "City": "Hamburg",
                                "Country": "Deutschland"
                            }
                        }
                    },
                    {
                        "Display": "FI-HS",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Somewhere 42",
                                "PostalCode": "12345",
                                "City": "Helsinki",
                                "Country": "Finnland"
                            }
                        }
                    }
                ]
            },
            {
                "$id": "CompanyOptions",
                "$values": [
                    {
                        "Id": "gkg",
                        "Display": "glueckkanja",
                        "Value": "glueckkanja AG"
                    },
                    {
                        "Id": "pp",
                        "Display": "PRIMEPULSE",
                        "Value": "PRIMEPULSE SE"
                    }
                ]
            }
        ]
    },
    "Runbooks": {
        "rjgit-org_general_add-user": {
            "ParameterList": [
                {
                    "DisplayName": "Office-Standort",
                    "DisplayAfter": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "LocationOptions"
                        }
                    }
                },
                {
                    "Name": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "CompanyOptions"
                        },
                        "AllowEdit": false
                    }
                }
            ],
            "ReadOnly": [
                "StreetAddress",
                "PostalCode",
                "City",
                "Country"
            ]
        }
    }
}
```

Dadurch wird die folgende UI erstellt:

![Demo - ref-Standort](https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-93295541748dcc12dbc72208851138efd0808d51%2Frunbook-customization-img7.png?alt=media)

![Demo - ref-Adresse](https://2298793958-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkrcM7cKOpXKri1kVrh%2Fuploads%2Fgit-blob-11e2812670e56cf10bb03fe7588059d232a8addf%2Frunbook-customization-img8.png?alt=media)

### Graph-Filter

Sie können [ODATA-Graph-Filter](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) zur Verwendung in mehreren Runbooks vorbereiten. Speichern Sie diese in einem Abschnitt namens `GraphFilters`.

Das folgende Beispiel filtert nach einem bestimmten Präfix in der `DisplayName` einer Gruppe, um in einem Gruppenauswahlfeld nur lizenzbezogene Gruppen anzuzeigen.

```json
"GraphFilters": {
    "LicenseGroup": "startswith(DisplayName, 'LIC_')" // auch im RJ-Code als Standard enthalten
  }
```

Siehe [Graph-Filterung](#graph-filtering) zur Verwendung davon aus einem Runbook.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmjoin.com/de/automatisierung/runbooks/runbook-customization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
