Personnalisation des runbooks

Adaptez les runbooks génériques de RealmJoin aux besoins de vos environnements.

onglet Vue d'ensemble

L'implémentation du runbook RealmJoin offre des capacités de personnalisation à l'auteur d'un runbook ou à l'administrateur d'un environnement, afin qu'ils puissent :

• Héberger des paramètres et des modèles spécifiques au client/locataire

• Offrir des éléments d'interface utilisateur comme des sélecteurs d'utilisateur ou des listes déroulantes

• Présenter des explications lisibles par des humains des paramètres

• Masquer les éléments d'interface inutiles

Les personnalisations peuvent être incluses dans le runbook lui-même et/ou stockées dans l'instance du portail RealmJoin du client. Par défaut, nous essaierons d'offrir des valeurs par défaut sensées dans les runbooks proposés sur GitHub.

Certains runbooks seront fournis avec des exemples de configuration de modèles spécifiques au client, comme la spécification des emplacements de bureau pour l'intégration des utilisateurs.

Formater

La personnalisation peut être définie (par ordre décroissant de priorité)

• Bloc de JSON dans les paramètres du portail RealmJoin, remplaçant le comportement par défaut du runbook

• Bloc de JSON dans l'en-tête d'un runbook

De plus (avec la plus faible priorité)

• par paramètre dans l'en-tête du runbook

• par paramètre dans le bloc param du runbook (en utilisant le module d'aide RJRb)

Certaines fonctionnalités (comme les modèles) ne sont disponibles qu'au format JSON. Certaines fonctionnalités (comme la création d'un sélecteur d'utilisateur) ne sont disponibles que si un type de données est spécifié dans le bloc param. Vous pouvez combiner plusieurs types de personnalisations pour de meilleurs résultats.

Bloc de paramètres du runbook

Le portail RealmJoin analyse le bloc param PowerShell d'un runbook pour déterminer quels champs de saisie afficher. Lorsque cela est possible, il validera également les entrées selon le type .NET donné pour une variable.

Les types de données suivants sont actuellement compris :

• [bool], [boolean] - présentera un basculement binaire

• [string] - présentera une zone de texte pour taper toute saisie alphanumérique

• [int] - présentera une zone de texte acceptant uniquement des saisies numériques

• [DateTime], [DateTimeOffset] - présentera un sélecteur de date/heure

Vous pouvez appliquer des modificateurs PowerShell standard aux paramètres. Le portail RealmJoin, en particulier, comprendra si vous spécifiez [Parameter(Mandatory = $true)] pour indiquer un paramètre obligatoire et faire respecter que ces paramètres soient remplis.

Lorsque cela est possible, le portail RealmJoin lira également et présentera les valeurs par défaut données dans l'interface utilisateur.

Sachez que les valeurs par défaut du runbook peuvent être remplacées par des personnalisations. De plus, des paramètres peuvent être entièrement masqués par des personnalisations.

Personnalisation des paramètres

Pour pouvoir personnaliser les paramètres, assurez-vous d'inclure le module PS RealmJoin Runbook Helper dans votre runbook :

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

Vous pouvez ensuite inclure [ValidateScript( { Use-RJInterface ... } )] dans les définitions de paramètres. Par exemple, ce qui suit créera un sélecteur d'utilisateur, permettant de choisir un utilisateur Entra ID et transmettra son identifiant d'objet en tant que chaîne au runbook.

param(
    [ValidateScript( { Use-RJInterface -DisplayName "Assigner l'appareil à cet utilisateur (optionnel)" -Type Graph -Entity User } )]
    [string] $AssignedUserId = ""
)

Décomposons cela morceau par morceau. [ValidateScript...] est un modificateur du paramètre suivant défini dans le bloc param. Dans ce cas la variable $AssignedUserId.

Use-RJInterface fait partie de notre module d'aide RealmJoin Runbook PowerShell. Il vous permet de préciser quel type d'entrée vous attendez en utilisant -Type et -Entity, si cela n'est pas déjà entièrement défini par le type de variable.

-DisplayName vous permet de transmettre une invite / description lisible par l'humain pour ce paramètre au portail RealmJoin.

Ressources Graph

Dans l'exemple ci-dessus, la source d'information est MS Graph, comme décrit par -Type Graph. Pour MS Graph, utilisez -Entity pour préciser quel type de ressource vous attendez. Les entités disponibles sont Après authentification sur notre plateforme en utilisant vos identifiants Microsoft, il vous sera demandé des informations supplémentaires, telles que le, Groupe, Appareil. Cela produira un sélecteur pour des utilisateurs, des groupes ou des appareils dans l'Entra ID donné.

Le sélecteur inclut une recherche rapide, pour trouver facilement la ressource requise.

Exemple de sélecteur

Actuellement, aucune sélection multiple n'est possible avec un sélecteur.

Par défaut, un sélecteur MS Graph renverra l'ID de l'objet. Si vous avez besoin par exemple du nom principal de l'utilisateur à la place, assurez-vous d'inclure "name" en suffixe dans le nom de votre variable. Donc, pour obtenir l'id d'un utilisateur, nommez le paramètre $userid. Si vous voulez un UPN, nommez-le $username.

Filtrage Graph

Si vous utilisez un sélecteur basé sur MS Graph, vous pouvez aussi spécifier -Filter et utiliser un Filtre ODATA pour limiter les objets proposés dans le sélecteur.

L'exemple suivant listera uniquement les groupes d'Entra ID commençant par "LIC_".

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

Vous pouvez préparer des filtres et les réutiliser dans plusieurs scripts en utilisant le magasin central de données. Dans ce cas, référencez simplement le filtre par son nom en utilisant -Filter "ref:LicenseGroup", où ref: indique de rechercher un filtre stocké.

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

Cet exemple spécifique ref:LicenseGroup est disponible par défaut sans configuration supplémentaire.

Filtre ODATA

En-tête du runbook

Le portail peut analyser la aide basée sur les commentaires du runbook, si elle est présente.

Voici un exemple :

<#
  .SYNOPSIS
  (Dés)attribuer une licence à un utilisateur via l'appartenance à un groupe.

  .DESCRIPTION
  (Dés)attribuer une licence à un utilisateur via l'appartenance à un groupe. Description plus détaillée...

  .PARAMETER DefaultGroups
  Liste séparée par des virgules des groupes à attribuer. ex. "DL Sales,LIC Internal Product"

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

  .INPUTS
  RunbookCustomization : {
        "Parameters" : {
            "UserName" : {
                "Hide" : true
            },
            "Remove" : {
                "DisplayName" : "Assigner ou supprimer la licence",
                "SelectSimple" : {
                    "Assign License to User" : false,
                    "Remove License from User" : true
                }
            }
        }
    }
#>

.SYNOPSIS - Donnez une description très brève de la fonction de votre runbook. Cela sera affiché dans la liste des runbooks disponibles.

.DESCRIPTION - Donnez une description de la fonction de votre runbook. Peut contenir un peu plus de détails, car ceci sera affiché dans la boîte de dialogue d'exécution/paramètres du runbook.

.PARAMETER - Doit être suivi par le nom d'un paramètre. Vous permet de donner une explication détaillée de l'entrée attendue pour le paramètre en question.

.INPUTS - Peut contenir un bloc de personnalisation de runbook basé sur JSON.

.NOTES - N'est pas analysé / rendu. Veuillez utiliser cet espace pour indiquer quelles autorisations et exigences existent pour votre runbook.

.EXAMPLE - N'est pas analysé / rendu. Peut contenir un exemple de personnalisation basée sur JSON à utiliser dans le magasin de données RealmJoin de votre locataire. Ceux-ci peuvent être des exemples de création de modèles, par ex. pour différents flux de travail ou classes d'utilisateurs.

Personnalisation basée sur JSON

Magasin de données central

Chaque locataire Azure peut héberger un magasin de données "Runbook Customizations", trouvé à https://portal.realmjoin.com/settings/runbooks-customizations .

Le format est JSON avec commentaires, autorisant les virgules finales. Actuellement, il y a trois sections pertinentes, Paramètres, Modèles, Runbooks.

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

Section Runbooks

Runbooks est analysée par le portail lors du démarrage d'un runbook. Si une section nommée comme le runbook Azure Automation actuel existe, son contenu sera utilisé pour personnaliser le frontend affiché à l'utilisateur.

Supposons le runbook de démonstration simple suivant, appelé rjgit-device_demo-runbook-customizing.

<#
  .SYNOPSIS
  Démontrer la personnalisation du runbook

  .DESCRIPTION
  Démontrer la personnalisation du runbook, comme une liste déroulante/sélection
#>

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

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

"## Faire des opérations sur l'appareil '$DeviceID'"

# Flux de travail compliqué fortement optionnel
if ($ExtraWorkflow) {
    "## Exécution de la méditation..."
    Start-Sleep -Seconds $ExtraWorkflowTime
}

Si non personnalisé, il sera présenté ainsi dans le frontend :

Démo - avant

Remarques :

• Comme ce runbook est démarré depuis le contexte d'un appareil dans le portail, le $DeviceId est une information redondante pour un utilisateur. Je sais déjà sur quel appareil je travaille.

• Que se passe-t-il si j'active ou désactive le "Extra Workflow" ? Dois-je penser au "Extra Workflow Time" si je désactive le "Extra Workflow" ?

Améliorons cela. L'exemple JSON suivant dans le magasin de données central modifiera l'UI pour le runbook.

{
    "Runbooks" : {
        "rjgit-device_demo-runbook-customizing": {
            "ParameterList": [
                {
                    "Name": "DeviceId",
                    "Hide" : true
                }, 
                {
                    "Name": "ExtraWorkflow",
                    "Hide" : true
                },
                {
                    "Name": "ExtraWorkflowTime",
                    "DisplayName": "Combien de temps méditer ?",
                },
                {
                    "DisplayName": "Exécuter le flux de travail supplémentaire",
                    "DisplayBefore": "ExtraWorkflowTime",
                    "Select": {
                        "Options": [
                            {
                                "Display": "Exécuter la méditation (optionnel)",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": true
                                    }
                                }
                            },
                            {
                                "Display": "Ignorer la pleine conscience de l'appareil",
                                "Customization": {
                                    "Default": {
                                        "ExtraWorkflow": false
                                    },
                                    "Hide": [
                                        "ExtraWorkflowTime"
                                    ]
                                }
                            }
                        ],
                        
                    },
                    "Default": "Ignorer la pleine conscience de l'appareil"
                }
            ]
        }
    }
}

Vous pouvez utiliser la même notation / fonctionnalités dans votre en-tête du runbook.

ParameterList

Chaque paramètre a sa propre section dans ParameterList. Modificateurs permettent de changer le comportement de ce paramètre.

Le résultat ressemblera à ceci :

Démo - après masqué

Choisir le flux de travail additionnel présentera (démasquera) plus de paramètres :

Démo - après démasqué

Ceci montre moins d'encombrement comparé à avant l'application de la personnalisation. En même temps, plus d'informations sur les alternatives de "Extra Workflow" sont disponibles pour l'utilisateur. De plus, un utilisateur ne se souciera de "Extra Workflow Time" que si cela est pertinent.

Changer la visibilité de ce champ a été fait en utilisant un "Customization" bloc à l'intérieur de l'une des "Select" options. Vous pouvez actuellement avoir au maximum un tel "Customization" bloc actif à la fois.

Comme vous pouvez le voir, le paramètre $DeviceId est complètement masqué. Ceci est réalisé en définissant le "Hide" : true pour ce paramètre.

Les paramètres peuvent avoir un DisplayName. Nous avons proposé une version conviviale DisplayName pour remplacer $ExtraWorkflowTime dans l'UI. Voir d'autres modificateurs pour plus d'informations.

Vous pouvez insérer des paramètres "non nommés" (manquant la Nom déclaration) comme la section "Exécuter le flux de travail supplémentaire", si vous voulez offrir des éléments d'interface sans retourner directement une valeur. Ceci est normalement utilisé seulement en conjonction avec Sélectionnez.

Sélectionnez

Nous avons utilisé Sélectionnez, pour afficher une liste de Options dans une liste déroulante. Chaque option peut Affichage texte, ou déclencher un Personnalisation, comme définir Masquer ou un Défaut valeur sur d'autres paramètres. Dans notre exemple, nous l'avons utilisé pour (dé)masquer $ExtraWorkflowTime et remplacer la valeur de$ExtraWorkflow

$ExtraWorkflowTime est donc seulement affiché quand pertinent et l'interrupteur binaire la valeur de est maintenant remplacé par des alternatives significatives du point de vue de l'utilisateur.

Dans le cas d'un Sélectionnez pour un paramètre nommé, chaque option devrait avoir un "ParameterValue": "..." à transmettre au runbook. Vous pouvez placer un "ShowValue: false" à l'intérieur du Sélectionnez bloc pour n'afficher que la liste déroulante et pas un champ pour la valeur du paramètre résultant.

Exemple de paramètre nommé :

{
    "Name": "ExtraWorkflow",
    "DefaultValue": true,
    "DisplayName": "Exécuter le flux de travail supplémentaire",
    "DisplayBefore": "ExtraWorkflowTime",
    "Select": {
        "Options": [
            {
                "Display": "Exécuter la méditation (optionnel)",
                "ParameterValue": true
            },
            {
                "Display": "Ignorer la pleine conscience de l'appareil",
                "ParameterValue": false,
                "Customization": {
                    "Hide": [
                        "ExtraWorkflowTime"
                    ]
                }
            }
        ],
        "ShowValue": false
    }
}

et un Défaut / DefaultValue la déclaration dans le paramètre spécifie également l'état initial de la liste déroulante. Dans le cas d'un paramètre non nommé, utilisez la DisplayName de l'option désirée, sinon donnez une valeur de retour par défaut, comme "true" ou "false" ou une chaîne quelconque.

Paramètres

Si vous n'avez que des paramètres nommés, vous pouvez utiliser le format légèrement plus court Paramètres au lieu de ParameterList.

Pour un exemple, voir SelectSimple

SelectSimple

Si toute la puissance d'un Sélectionnez n'est pas nécessaire et que vous voulez juste offrir une liste de valeurs possibles dans une liste déroulante (sans appliquer de personnalisation supplémentaire), vous pouvez utiliser SelectSimple.

SelectSimple n'est utilisable que pour les paramètres nommés.

Exemple :

{
    "Runbooks" : {
        "rjgit-device_demo-runbook-customizing": {
            "Parameters" : {
                "DeviceId": {
                    "Hide" : true
                }, 
                "ExtraWorkflow": {
                    "Name": "ExtraWorkflow",
                    "DisplayName": "Exécuter le flux de travail supplémentaire",
                    "Default": false,
                    "SelectSimple" : {
                        "Execute Meditation (optional)": true,
                        "Skip Device Mindfulness": false
                    }
                },
                "ExtraWorkflowTime": {
                    "DisplayName": "Combien de temps méditer ?"
                }
            }
        }
    }
}

La plus grande différence (autre que d'être beaucoup plus court) par rapport à notre exemple précédent est que $ExtraWorkflowTime est toujours visible.

Modificateurs

Chaque paramètre peut avoir un ou plusieurs des modificateurs suivants :

• "DisplayName": "texte" - Afficher "texte" comme nom du paramètre dans l'UI

• "Hide": true / false - Masquer ce paramètre

• "Mandatory": true / false - Exiger que ce paramètre soit rempli

• "ReadOnly": true / false - Protéger ce paramètre contre toute modification de sa valeur par défaut

• "DefaultValue": "..." - Définir une valeur par défaut pour ce paramètre. (Vous pouvez aussi utiliser Défaut à la place.)

• "GraphFilter": "startswith(DisplayName, 'LIC_')" - voir Filtrage Graph

• "AllowEdit": true / false - Protéger ce paramètre contre la modification manuelle. (combiner ceci avec des modèles)

Paramètres

Paramètres vous permet de stocker des données de configuration comme des noms de comptes de stockage Azure en un endroit central, tout en les gardant séparés de vos runbooks.

Vous pouvez accéder aux valeurs individuelles d'un bloc param d'un runbook en utilisant Use-RJInterface.

Prenons cet exemple de bloc param d'un runbook :

param(
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.Container" } )]
    [string] $ContainerName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.ResourceGroup" } )]
    [string] $ResourceGroupName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Name" } )]
    [string] $StorageAccountName,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Location" } )]
    [string] $StorageAccountLocation,
    [ValidateScript( { Use-RJInterface -Type Setting -Attribute "CaPoliciesExport.StorageAccount.Sku" } )]
    [string] $StorageAccountSku
)

Le portail tentera de préremplir chaque paramètre avec des valeurs provenant du magasin de données central - si elles sont présentes. Cela fonctionne aussi si le paramètre a été masqué dans l'UI.

Un JSON possible dans le magasin de données pour ce runbook serait :

{
    "Settings" : {
        "CaPoliciesExport": {
            "ResourceGroup": "rj-runbooks-01",
            "StorageAccount": {
                "Name": "rjrbexports01",
                "Location": "Europe de l'Ouest",
                "Sku": "Standard_LRS"
            }
        }
    }
}

L'élément manquant Container ne sera tout simplement pas prérempli dans l'UI.

Modèles

Modèles utilisez des références JSON pour importer des données - par exemple une longue liste d'emplacements de bureau - lorsque vous utilisez une Sélectionnez déclaration.

Cela permet de garder une personnalisation neutre/réutilisable/séparée des données réelles.

Prenons l'exemple de l'intégration de nouveaux utilisateurs. Vous pouvez avoir plusieurs options données pour les départements ou les emplacements de bureau, où l'attribution d'un emplacement de bureau impose également une certaine adresse, pays, état, etc.

L'exemple suivant d'une personnalisation de runbook utilise la section $ref à l'intérieur du Runbooks pour référencer/importer un sous-arbre depuis la section Modèles . Faites attention aux $id/$values mots-clés. Sachez que $id/$values doivent être définis avant de les référencer en utilisant $ref. C'est pourquoi Modèles est défini avant Runbooks dans cet exemple.

Dans cet exemple, nous demandons au portail de récupérer le sous-arbre avec le $id appelé LocationOptions et d'inclure ses $values, en remplaçant la déclaration $ref Ainsi, le portail rendra un Sélectionnez comme décrit dans la section Runbooks mais inclura les options réelles de Modèles.

Un modèle peut contenir toute déclaration prise en charge à l'emplacement de référence. Dans cet exemple, nous utilisons une déclaration Personnalisation pour modifier d'autres paramètres comme StreetAddress.

Ainsi, nous pouvons avoir une personnalisation spécifique au runbook dans Runbooks réutilisable à travers plusieurs environnements, tout en gardant les données réelles séparées.

{
    "Templates" : {
        "Options": [
            {
                "$id": "LocationOptions",
                "$values": [
                    {
                        "Display": "DE-OF",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Kaiserstraße 39",
                                "PostalCode": "63065",
                                "City": "Offenbach",
                                "Country": "Allemagne"
                            }
                        }
                    },
                    {
                        "Display": "DE-DEG",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Lateinschulgassse 24-26",
                                "PostalCode": "94469",
                                "City": "Deggendorf",
                                "Country": "Allemagne"
                            }
                        }
                    },
                    {
                        "Display": "DE-HH",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Hans-Henny-Jahnn-Weg 53",
                                "PostalCode": "22085",
                                "City": "Hambourg",
                                "Country": "Allemagne"
                            }
                        }
                    },
                    {
                        "Display": "FI-HS",
                        "Customization": {
                            "Default": {
                                "StreetAddress": "Somewhere 42",
                                "PostalCode": "12345",
                                "City": "Helsinki",
                                "Country": "Finlande"
                            }
                        }
                    }
                ]
            },
            {
                "$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": "Emplacement du bureau",
                    "DisplayAfter": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "LocationOptions"
                        }
                    }
                },
                {
                    "Name": "CompanyName",
                    "Select": {
                        "Options": {
                            "$ref": "CompanyOptions"
                        },
                        "AllowEdit": false
                    }
                }
            ],
            "ReadOnly": [
                "StreetAddress",
                "PostalCode",
                "City",
                "Country"
            ]
        }
    }
}

Ceci créera l'interface suivante :

Démo - ref-location

Démo - ref-address

Filtres Graph

Vous pouvez préparer filtres Graph ODATA à utiliser dans plusieurs runbooks. Stockez-les dans une section appelée GraphFilters.

L'exemple suivant filtre un certain préfixe dans le DisplayName du groupe, pour n'afficher que les groupes liés aux licences dans un sélecteur de groupe.

"GraphFilters": {
    "LicenseGroup": "startswith(DisplayName, 'LIC_')" // aussi contenu dans le code RJ comme valeur par défaut
  }

Voir Filtrage Graph sur la façon d'utiliser cela depuis un runbook.