Personnalisation des runbooks

Adaptez les runbooks génériques de RealmJoin aux besoins de votre environnement.

Aperçu

L’implémentation de 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/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.

Certains runbooks seront livrés avec des exemples montrant comment configurer des 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, remplaçant le comportement par défaut du runbook

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

En outre (avec la priorité la plus faible)

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

• par paramètre dans le bloc param des runbooks (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 qu’en spécifiant un type de données dans le bloc param. Vous pouvez combiner plusieurs types de personnalisations pour obtenir les meilleurs résultats.

Bloc de paramètres du runbook

RealmJoin Portal analyse le bloc param PowerShell d’un runbook afin de déterminer quels champs de saisie afficher. Dans la mesure du possible, il validera également les entrées selon le type .NET donné pour une variable.

Les types de données suivants sont actuellement pris en charge :

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

• [string] - présentera une zone de texte pour saisir n’importe quelle entrée alphanumérique

• [int] - présentera une zone de texte, n’autorisant que des entrées 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.

Dans la mesure du possible, RealmJoin Portal lira et affichera également les valeurs par défaut données dans l’interface utilisateur.

Gardez à l’esprit que 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, veuillez vous assurer d’inclure le module PS d’aide aux runbooks 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, ce qui suit 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.

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

Décortiquons cela, point par point. [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 module PowerShell. Il vous permet de spécifier le type d’entrée attendu à l’aide de -Type et -Entity, si cela n’est pas déjà entièrement défini par le type de la 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 l’indique -Type Graph. Pour MS Graph, utilisez -Entity pour spécifier le type de ressource attendu. Les entités disponibles sont utilisateurs, 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 retrouver facilement la ressource requise.

Exemple de sélecteur

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 gros, 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 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 "License group" } )]
    [String] $GroupID_License
)

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

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

En-tête du runbook

Le portail peut analyser le aide basée sur les commentaires d’un 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 de groupes séparée par des virgules à attribuer, par 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": "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 des runbooks.

.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 les autorisations et les exigences de votre runbook.

.EXAMPLE - N’est pas analysé / affiché. Peut contenir un exemple de personnalisation basée sur JSON à utiliser dans le magasin de données RealmJoin de votre Tenant. 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 Tenant Azure peut héberger un magasin de données "Runbook Customizations", accessible à https://portal.realmjoin.com/settings/runbooks-customizations .

Le format est du JSON avec commentaires, permettant des virgules finales. Actuellement, trois sections sont pertinentes, Paramètres, Modèles, Runbooks.

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

section des runbooks

Runbooks est analysée par le portail lors du démarrage d’un runbook. Si une section portant le nom du 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électeur
#>

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

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

"## Faire des choses 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 le frontend :

Démo - avant

Réflexions :

• Comme ce runbook est lancé 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 "Flux de travail supplémentaire" ? Dois-je penser au "Temps du 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 utilisateur du 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 (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.

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 masquage

Le choix du flux de travail supplémentaire affichera (démasquera) davantage de paramètres :

Démo - après démasquage

Cela montre moins d’encombrement par rapport à avant l’application de la personnalisation. En même temps, davantage d’informations sur les alternatives au "Flux de travail supplémentaire" sont disponibles pour l’utilisateur. De plus, un utilisateur ne se préoccupera du "Temps du flux de travail supplémentaire" que s’il est pertinent.

La modification de la visibilité de ce champ a été effectuée à l’aide d’un "Customization" bloc à l’intérieur de l’une des "Select" options. Vous ne pouvez actuellement avoir qu’un seul bloc de ce type actif à la fois. "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 équivalent DisplayName pour remplacer $ExtraWorkflowTime dans l’interface utilisateur. Voir les autres modificateurs pour en savoir plus.

Vous pouvez insérer des paramètres « sans nom » (en omettant la Nom instruction) comme la section "Exécuter le flux de travail supplémentaire", si vous voulez 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 définir Masquer ou une Par défaut valeur sur d’autres paramètres. Dans notre exemple, nous l’avons utilisé pour (dé)masquer $ExtraWorkflowTime et remplacer $ExtraWorkflowsa valeur.

$ExtraWorkflowTime n’est donc affiché que lorsqu’il est pertinent et l’interrupteur binaire $ExtraWorkflow est désormais remplacé par des alternatives pertinentes du point de vue de l’utilisateur.

Dans le cas d’un Sélectionnez pour un paramètre nommé, chaque option doit 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 de 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 (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 donnez une valeur de retour par défaut, comme "true" ou "false" ou une chaîne.

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 voulez 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 :

{
    "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) avec 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’interface utilisateur

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

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

• "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 Par défaut à la place.)

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

• "AllowEdit": true / false - Protéger ce paramètre de l’édition manuelle. (à combiner avec les modèles)

Paramètres

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

Vous pouvez accéder aux valeurs individuelles d’un bloc param d’un runbook à l’aide de 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 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 utilisateur.

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 Conteneur manquant ne sera simplement pas prérempli dans l’interface utilisateur.

Modèles

Modèles utiliser des références JSON pour intégrer des données - par exemple une longue liste d’emplacements de bureau - lors de l’utilisation d’une Sélectionnez instruction.

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

Prenons l’exemple de l’intégration de nouveaux utilisateurs. Vous pourriez 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, un pays, un État, etc.

L’exemple suivant d’une personnalisation de runbook utilise la $ref à l’intérieur du 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 d’inclure ses $values, en remplaçant l’instruction $ref Ainsi, le portail affichera un Sélectionnez comme décrit dans la 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 Adresse postale.

Nous pouvons donc avoir une personnalisation spécifique au runbook dans Runbooks réutilisable sur plusieurs environnements, tout en conservant 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": "Hamburg",
                                "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 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

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 selon un certain préfixe dans le DisplayName d'un groupe, afin d'afficher uniquement les groupes liés aux licences dans un sélecteur de groupes.

"GraphFilters": {
    "LicenseGroup": "startswith(DisplayName, 'LIC_')" // également inclus dans le code RJ par défaut
  }

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