> 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/fr/automatisation/runbooks/runbook-customization.md). # Personnalisation des runbooks ## Aperçu L’implémentation du runbook RealmJoin offre des possibilité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/tenant * Proposer des éléments d’interface utilisateur comme des sélecteurs d’utilisateurs ou des listes déroulantes * Présenter des explications lisibles par l’humain des paramètres * Masquer les éléments d’interface utilisateur inutiles
Les personnalisations peuvent être incluses dans le runbook lui-même et/ou stockées dans l’instance RealmJoin Portal du client. Par défaut, nous essaierons de proposer des valeurs par défaut pertinentes dans les runbooks proposés sur [GitHub](https://github.com/realmjoin/realmjoin-runbooks). 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 JSON dans [les paramètres de RealmJoin Portal](https://portal.realmjoin.com/settings/runbooks-customizations), remplaçant le comportement par défaut du runbook * Bloc JSON dans l’en-tête d’un runbook En plus (avec la priorité la plus faible) * par paramètre dans l’en-tête du runbook * par paramètre dans le bloc param du runbook (en utilisant le module d’assistance 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 qu’en spécifiant un type de données dans le bloc param. Vous pouvez combiner plusieurs types de personnalisations pour obtenir de meilleurs résultats. ## Bloc Param du runbook RealmJoin Portal 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]` - affichera un interrupteur binaire * `[string]` - affichera une zone de texte pour saisir n’importe quelle entrée alphanumérique * `[int]` - affichera une zone de texte, n’autorisant que les saisies numériques * `[DateTime]`, `[DateTimeOffset]` - affichera un sélecteur de date/heure Vous pouvez appliquer les modificateurs PowerShell standard aux paramètres. RealmJoin Portal, en particulier, comprendra si vous spécifiez `[Parameter(Mandatory = $true)]` pour indiquer un paramètre obligatoire et imposer que ces paramètres soient renseignés. Lorsque cela est possible, RealmJoin Portal lira et affichera également les valeurs par défaut fournies dans l’interface utilisateur. Attention, les valeurs par défaut du runbook peuvent être remplacées par des personnalisations. De plus, les paramètres peuvent être complètement masqués par des personnalisations. ### Personnalisation des paramètres Pour pouvoir personnaliser les paramètres, veillez à inclure le module PS d’assistance Runbook de RealmJoin dans votre runbook : `#Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" }` Vous pouvez ensuite inclure `[ValidateScript( { Use-RJInterface ... } )]` des instructions dans les définitions de paramètres. Par exemple, l’exemple suivant créera un sélecteur d’utilisateur, permettant de choisir un utilisateur Entra ID et transmettra son ID d’objet sous forme de chaîne au runbook. ```powershell param( [ValidateScript( { Use-RJInterface -DisplayName "Affecter cet appareil à cet utilisateur (facultatif)" -Type Graph -Entity User } )] [string] $AssignedUserId = "" ) ``` Décomposons cela pas à pas. `[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 [RealmJoin Runbook Helper](https://github.com/realmjoin/RealmJoin.RunbookHelper) module PowerShell. Il vous permet de spécifier le type d’entrée attendu 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 à RealmJoin Portal une invite / description lisible par l’humain pour ce paramètre. #### 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 spécifier le type de ressource attendu. Les entités disponibles sont `utilisateurs`, `Group`, `Device`. Cela produira un sélecteur pour les utilisateurs, les groupes ou les appareils dans l’Entra ID donné. Le sélecteur inclut une recherche rapide, pour localiser facilement la ressource requise. ![Exemple de sélecteur](/files/5a3a3234a99853f7ceb7ac920fb5dcb5c6d01c33) Actuellement, aucune sélection multiple n’est possible à l’aide d’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 d’utilisateur à la place, veillez à inclure "name" comme suffixe dans le nom de votre variable. Donc, en résumé, 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 également spécifier `-Filter` et utiliser un [filtre ODATA](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) pour limiter les objets proposés dans le sélecteur. L’exemple suivant ne listera que les groupes de l’Entra ID commençant par "LIC\_". ```powershell 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 de données central](#graph-filters). Dans ce cas, il suffit de référencer le filtre par son nom en utilisant `-Filter "ref:LicenseGroup"`, où `ref:` indique qu’il faut rechercher un filtre stocké. ```powershell param( [Parameter(Mandatory = $true)] [ValidateScript( { Use-RJInterface -Type Graph -Entity Group -Filter "ref:LicenseGroup" } )] [String] $GroupID_License ) ``` Cet exemple précis `ref:LicenseGroup` est disponible par défaut sans configuration supplémentaire. ![filtre ODATA](/files/bcff9526e60d459a63630fbb24f7eef0c70827f4) ## En-tête du runbook Le Portal peut analyser la section [aide basée sur des commentaires](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-5.1) d’un runbook, si elle est présente. Voici un exemple : ```powershell <# .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 de groupes séparés par des virgules à attribuer. par ex. "DL Sales,LIC Internal Product" .NOTES Permissions : MS Graph (API) : - User.Read.All - GroupMember.ReadWrite.All - Group.ReadWrite.All .INPUTS RunbookCustomization: { "Parameters": { "UserName": { "Hide": true }, "Remove": { "DisplayName": "Attribuer ou supprimer une licence", "SelectSimple": { "Attribuer une licence à l’utilisateur": false, "Supprimer la licence de l’utilisateur": true } } } } #> ``` `.SYNOPSIS` - Donnez une description très brève de la fonction de votre runbook. Elle sera affichée 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 elle sera affichée dans la boîte de dialogue d’exécution / de paramètres du runbook. `.PARAMETER` - Doit être suivi du 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é / affiché. Veuillez utiliser cet espace pour noter quelles permissions et quelles exigences existent pour votre runbook. `.EXAMPLE` - N’est pas analysé / affiché. Peut contenir un exemple de personnalisation basée sur JSON à utiliser dans le datastore RealmJoin de votre tenant. Il peut s’agir d’exemples de création de modèles, par exemple pour différents flux de travail ou classes d’utilisateurs. ## personnalisation basée sur JSON ### Magasin de données central Chaque tenant Azure peut héberger un magasin de données "Runbook Customizations", disponible à . Le format est du JSON avec commentaires, autorisant les virgules finales. Actuellement, il existe trois sections pertinentes, `Paramètres`, `Modèles`, `Runbooks`. ```json { "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 l’interface affichée à l’utilisateur. Supposons le runbook de démonstration simple suivant, appelé `rjgit-device_demo-runbook-customizing`. ```powershell <# .SYNOPSIS Démontrer la personnalisation d’un runbook .DESCRIPTION Démontrer la personnalisation d’un runbook, comme une liste déroulante / de sélection #> #Requires -Modules @{ModuleName = "RealmJoin.RunbookHelper"; ModuleVersion = "0.6.0" } param( [string] $DeviceId, [bool] $ExtraWorkflow = $true, [int] $ExtraWorkflowTime = 15 ) "## Effectuer des opérations sur l’appareil '$DeviceID'" # Flux de travail compliqué hautement facultatif if ($ExtraWorkflow) { "## Exécution de la méditation..." Start-Sleep -Seconds $ExtraWorkflowTime } ``` S’il n’est pas personnalisé, il sera présenté comme ceci dans l’interface : ![Démo - avant](/files/cdb573623597d7e760cbfbf1d2fa5ddd578773dd) Réflexions : * Comme ce runbook est lancé depuis le contexte d’un appareil dans le portal, 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 "Flux de travail supplémentaire" ? Dois-je penser au "Temps de flux de travail supplémentaire" si je désactive le "Flux de travail supplémentaire" ? Améliorons cela. L’exemple JSON suivant dans le magasin de données central modifiera l’interface du runbook. ```json { "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 (facultatif)", "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 / les mêmes fonctionnalités dans votre [en-tête du runbook](#runbook-header). #### ParameterList Chaque paramètre a sa propre section dans `ParameterList`. [Les modificateurs](#modifiers) permettent de changer le comportement de ce paramètre. Le résultat ressemblera à ceci : ![Démo - après masquage](/files/b30764968714e87b81d08b86a13f13945c82cdae) Le choix du flux de travail supplémentaire affichera (fera réapparaître) davantage de paramètres : ![Démo - après réaffichage](/files/8a5383b94f7f4eb54256ee7a7735fb18d4cd18bd) Cela montre moins d’encombrement par rapport à avant l’application de la personnalisation. En même temps, davantage d’informations sur les alternatives de "Flux de travail supplémentaire" sont disponibles pour l’utilisateur. De plus, un utilisateur ne se souciera désormais du "Temps de flux de travail supplémentaire" que si cela est pertinent. Modifier la visibilité de ce champ a été fait en utilisant un `"Customization"` bloc à l’intérieur de l’une des options `"Select"` 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é. Cela est fait en définissant le `"Hide": true` pour ce paramètre. Les paramètres peuvent avoir un `DisplayName`. Nous avons proposé un `DisplayName` lisible par l’humain pour remplacer `$ExtraWorkflowTime` dans l’interface. Voir les autres [modificateurs](#modifiers) pour plus de détails. Vous pouvez insérer des paramètres "sans nom" (en l’absence de l’instruction `Nom` comme la section "Exécuter le flux de travail supplémentaire", si vous souhaitez proposer des éléments d’interface utilisateur sans renvoyer directement une valeur. Cela n’est normalement utilisé qu’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` du texte, ou déclencher un `Personnalisation`, comme la définition de `Hide` ou d’une `Par défaut` valeur sur d’autres paramètres. Dans notre exemple, nous l’avons utilisé pour (dés)masquer `$ExtraWorkflowTime` et remplacer `$ExtraWorkflow`sa valeur. `$ExtraWorkflowTime` n’est donc affiché que lorsque c’est pertinent et l’interrupteur binaire `$ExtraWorkflow` est maintenant remplacé par des alternatives significatives du point de vue de l’utilisateur. Dans le cas d’une `Sélectionnez` pour un paramètre nommé, chaque option doit avoir un `"ParameterValue": "..."` à transmettre au runbook. Vous pouvez placer un `"ShowValue: false"` dans le `Sélectionnez` bloc afin d’afficher uniquement la liste déroulante et non un champ pour la valeur du paramètre résultant. Exemple de paramètre nommé : ```json { "Name": "ExtraWorkflow", "DefaultValue": true, "DisplayName": "Exécuter le flux de travail supplémentaire", "DisplayBefore": "ExtraWorkflowTime", "Select": { "Options": [ { "Display": "Exécuter la méditation (facultatif)", "ParameterValue": true }, { "Display": "Ignorer la pleine conscience de l’appareil", "ParameterValue": false, "Customization": { "Hide": [ "ExtraWorkflowTime" ] } } ], "ShowValue": false } } ``` Le `Par défaut` / `DefaultValue` instruction dans le paramètre spécifie également l’état initial de la liste déroulante. Dans le cas d’un paramètre sans nom, utilisez le `DisplayName` de l’option souhaitée, sinon fournissez 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` à la place de `ParameterList`. Pour un exemple, voir SelectSimple #### SelectSimple Si toute la puissance d’un `Sélectionnez` n’est pas nécessaire et que vous souhaitez simplement proposer 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 : ```json { "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": { "Exécuter la méditation (facultatif)": true, "Ignorer la pleine conscience de l’appareil": false } }, "ExtraWorkflowTime": { "DisplayName": "Combien de temps méditer ?" } } } } } ``` La plus grande différence (en dehors du fait d’être beaucoup plus court) par rapport à notre exemple précédent est que `$ExtraWorkflowTime` est toujours visible. #### Les modificateurs Chaque paramètre peut avoir un ou plusieurs des modificateurs suivants : * `"DisplayName": "texte"` - Afficher "texte" comme nom du paramètre dans l’interface * `"Hide": true / false` - Masquer ce paramètre * `"Mandatory": true / false` - Exiger que ce paramètre soit renseigné * `"ReadOnly": true / false` - Empêcher que ce paramètre soit modifié par rapport à sa valeur par défaut * `"DefaultValue": "..."` - Définir une valeur par défaut pour ce paramètre. (Vous pouvez aussi utiliser `Par défaut` à la place.) * `"GraphFilter": "startswith(DisplayName, 'LIC_')"` - voir [Filtrage Graph](#graph-filtering) * `"AllowEdit": true / false` - Empêcher la modification manuelle de ce paramètre. (à combiner avec des modèles) ### Paramètres `Paramètres` vous permet de stocker des données de configuration comme les noms de Azure Storage Account à un emplacement central, tout en les gardant séparées de vos runbooks. Vous pouvez accéder à des valeurs individuelles depuis le bloc param d’un runbook en utilisant `Use-RJInterface`. Prenons cet exemple de bloc param d’un runbook : ```powershell 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 Portal essaiera de préremplir chaque paramètre avec les valeurs du magasin de données central - si elles sont présentes. Cela fonctionne aussi si le paramètre a été masqué dans l’interface. Un JSON possible dans le magasin de données pour ce runbook serait : ```json { "Settings": { "CaPoliciesExport": { "ResourceGroup": "rj-runbooks-01", "StorageAccount": { "Name": "rjrbexports01", "Location": "Europe de l’Ouest", "Sku": "Standard_LRS" } } } } ``` L’élément `Container` manquant ne sera simplement pas prérempli dans l’interface. ### Modèles `Modèles` utilisez des références JSON pour importer des données - par exemple une longue liste d’emplacements de bureau - lors de l’utilisation d’une `Sélectionnez` instruction. 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 pour les départements ou les emplacements de bureau, où l’attribution d’un emplacement de bureau impose également une certaine adresse, un pays, un État, etc. L’exemple suivant de personnalisation de runbook utilise la `$ref` dans le `Runbooks` section pour référencer/importer un sous-arbre depuis la `Modèles` section. Faites attention aux mots-clés `$id`/`$values` . Sachez que `$id`/`$values` doivent être définis avant d’être référencés à l’aide de `$ref`. C’est pourquoi `Modèles` est défini avant `Runbooks` dans cet exemple. Dans cet exemple, nous indiquons au portail de récupérer le sous-arbre avec le `$id` appelé `LocationOptions` et y inclure ses `$values`, en remplaçant la `$ref` instruction. Ainsi, le portail affichera un `Sélectionnez` comme décrit dans le `Runbooks` section, mais inclure les options réelles de `Modèles`. Un modèle peut contenir n'importe quelle instruction prise en charge à l'emplacement de référence. Dans cet exemple, nous utilisons une `Personnalisation` instruction pour modifier d'autres paramètres comme `StreetAddress`. Nous pouvons donc avoir une personnalisation spécifique au runbook dans `Runbooks` réutilisable dans plusieurs environnements, tout en conservant les données réelles séparées. ```json { "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": "Hamburg", "Country": "Allemagne" } } }, { "Display": "FI-HS", "Customization": { "Default": { "StreetAddress": "Quelque part 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 Office", "DisplayAfter": "CompanyName", "Select": { "Options": { "$ref": "LocationOptions" } } }, { "Name": "CompanyName", "Select": { "Options": { "$ref": "CompanyOptions" }, "AllowEdit": false } } ], "ReadOnly": [ "StreetAddress", "PostalCode", "City", "Country" ] } } } ``` Cela créera l'interface utilisateur suivante : ![Démo - ref-location](/files/b0f7f9ee7674861e4a7c0404e28e7fda4a8916a2) ![Démo - ref-address](/files/026485322c9b1cc7e200390ae5d0b1c13db13bf9) ### Filtres Graph Vous pouvez préparer [Filtres Graph ODATA](https://docs.microsoft.com/en-us/graph/query-parameters?context=graph%2Fapi%2F1.0\&view=graph-rest-1.0#filter-parameter) à utiliser dans plusieurs runbooks. Stockez-les dans une section appelée `GraphFilters`. L'exemple suivant filtre un certain préfixe dans le `DisplayName` d'un groupe, afin d'afficher uniquement les groupes liés à la licence dans un sélecteur de groupe. ```json "GraphFilters": { "LicenseGroup": "startswith(DisplayName, 'LIC_')" // également inclus comme valeur par défaut dans le code RJ } ``` Voir [Filtrage Graph](#graph-filtering) sur la manière de l'utiliser depuis un 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.realmjoin.com/fr/automatisation/runbooks/runbook-customization.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.