Automatiser le paramétrage des champs personnalisés dans les systèmes informatiques avec PowerShell

Points à retenir

• Automatisation avec PowerShell: Le script s’appuie sur PowerShell pour une gestion efficace des données dans les systèmes informatiques, en particulier dans les environnements des entreprises MSP.
• Gestion des champs personnalisés: Il est conçu pour définir des champ personnalisées dans NinjaOne, démontrant ainsi son adaptabilité à des outils informatiques spécifiques.
• Privilèges administratifs: L’exécution nécessite des droits d’administrateur local, ce qui souligne la nécessité de sécuriser les opérations au niveau du système.
• Traitement des types de champs: Comprend une logique permettant de traiter différents types de données comme les cases à cocher, les dates et les listes déroulantes, ce qui garantit une saisie précise des données.
• Gestion des erreurs: Intègre la gestion des erreurs pour détecter et signaler les problèmes, ce qui améliore la fiabilité.
• Efficacité par rapport aux méthodes manuelles: Offre une alternative plus efficace aux mises à jour manuelles des données, réduisant les erreurs humaines et permettant de gagner du temps.
• Du côté de la sécurité : Cela implique la nécessité d’un contrôle d’accès et d’un audit stricts pour éviter les abus et les violations de données.
• Le pouvoir de l’automatisation dans les technologies de l’information: Souligne l’impact transformateur de l’automatisation des tâches informatiques, en améliorant la précision et l’efficacité opérationnelle.

La personnalisation des systèmes informatiques est essentielle à l’efficacité et à la précision des opérations. Cela est particulièrement vrai pour les fournisseurs de services gérés (MSP) et les services informatiques où des scripts, comme celui décrit ici, sont utilisés pour définir les valeurs des champs personnalisés. En exploitant PowerShell, un puissant langage de script, les professionnels de l’informatique peuvent automatiser et simplifier des tâches complexes, ce qui permet d’optimiser les performances et de réduire les erreurs humaines.  

Contexte

Le script fourni est un exemple classique de la façon dont PowerShell peut interagir avec des outils de gestion informatique spécifiques – dans ce cas, NinjaOne (un logicielpopulaire de surveillance et de gestion à distance). La possibilité de définir par programme des valeurs de champs personnalisés est cruciale pour les MSP et les administrateurs informatiques qui doivent gérer de grandes quantités de données sur de nombreux appareils et documents. Ce script est un outil permettant de rationaliser la gestion des données et d’assurer la cohérence au sein d’une infrastructure informatique.

Le script :

#Requires -Version 4

<#
.SYNOPSIS
    This is an example script for setting a custom field value. Specifying a type is recommended but not required.
.DESCRIPTION
    This is an example script for setting a custom field value. Specifying a type is recommended but not required.
.EXAMPLE
    -CustomFieldName "text" -Value "Even More Text"
    
    Setting Custom Field 'text' with value 'Even More Text'....
    Success!

PARAMETER: -CustomFieldName "NameOfAcustomFieldToSet"
    The name of a custom field that you would like to set.

PARAMETER: -CustomFieldType "ReplaceMeWithFieldType"
    The type of custom field you are trying to set.
    Valid options are: "Text", "Checkbox", "Date", "Date And Time", "Decimal", "Dropdown", "Email", "Integer", "IP Address", "MultiLine", "Phone", "Secure", "URL"

PARAMETER: -NinjaDocumentName "Replace Me With A Ninja Document Name"
    Name of a Ninja Document you would like to retrieve these field values from. Leave blank to retrieve values from device custom fields.

PARAMETER: -Value "ReplaceMe"
    The value you would like to set for the custom field.
    
.OUTPUTS
    None
.NOTES
    Minimum OS Architecture Supported: Windows 10, Server 2012 R2
    Release Notes: Initial Release
By using this script, you indicate your acceptance of the following legal terms as well as our Terms of Use at https://www.ninjaone.com/terms-of-use.
    Ownership Rights: NinjaOne owns and will continue to own all right, title, and interest in and to the script (including the copyright). NinjaOne is giving you a limited license to use the script in accordance with these legal terms. 
    Use Limitation: You may only use the script for your legitimate personal or internal business purposes, and you may not share the script with another party. 
    Republication Prohibition: Under no circumstances are you permitted to re-publish the script in any script library or website belonging to or under the control of any other software provider. 
    Warranty Disclaimer: The script is provided “as is” and “as available”, without warranty of any kind. NinjaOne makes no promise or guarantee that the script will be free from defects or that it will meet your specific needs or expectations. 
    Assumption of Risk: Your use of the script is at your own risk. You acknowledge that there are certain inherent risks in using the script, and you understand and assume each of those risks. 
    Waiver and Release: You will not hold NinjaOne responsible for any adverse or unintended consequences resulting from your use of the script, and you waive any legal or equitable rights or remedies you may have against NinjaOne relating to your use of the script. 
    EULA: If you are a NinjaOne customer, your use of the script is subject to the End User License Agreement applicable to you (EULA).
#>

[CmdletBinding()]
param (
    [Parameter()]
    [String]$CustomFieldName,
    [Parameter()]
    [String]$CustomFieldType,
    [Parameter()]
    [String]$NinjaDocumentName,
    [Parameter()]
    [String]$Value
)

begin {
    # Grab parameters from dynamic script variables.
    if ($env:customFieldName -and $env:customFieldName -notlike "null") { $CustomFieldName = $env:customFieldName }
    if ($env:customFieldType -and $env:customFieldType -notlike "null") { $CustomFieldType = $env:customFieldType }
    if ($env:ninjaDocumentName -and $env:ninjaDocumentName -notlike "null") { $NinjaDocumentName = $env:ninjaDocumentName }
    if ($env:value -and $env:value -notlike "null") { $Value = $env:value }

    # A custom field name is required.
    if (-not $CustomFieldName) {
        Write-Error "No custom field was specified!"
        exit 1
    }

    # If the custom field type specified is a date or date and time, change it to "Date or Date Time" to be used by the function.
    if ($CustomFieldType -eq "Date" -or $CustomFieldType -eq "Date And Time") {
        $CustomFieldType = "Date or Date Time"
    }

    # Local Admin rights are required to read or write custom fields.
    function Test-IsElevated {
        $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        $p = New-Object System.Security.Principal.WindowsPrincipal($id)
        $p.IsInRole([System.Security.Principal.WindowsBuiltInRole]::Administrator)
    }

    # This function is to make it easier to set Ninja Custom Fields.
    function Set-NinjaProperty {
        [CmdletBinding()]
        Param(
            [Parameter(Mandatory = $True)]
            [String]$Name,
            [Parameter()]
            [String]$Type,
            [Parameter(Mandatory = $True, ValueFromPipeline = $True)]
            $Value,
            [Parameter()]
            [String]$DocumentName
        )

        # If we're requested to set the field value for a Ninja document we'll specify it here.
        $DocumentationParams = @{}
        if ($DocumentName) { $DocumentationParams["DocumentName"] = $DocumentName }

        # This is a list of valid fields we can set. If no type is given we'll assume the input doesn't have to be changed in any way.
        $ValidFields = "Attachment", "Checkbox", "Date", "Date or Date Time", "Decimal", "Dropdown", "Email", "Integer", "IP Address", "MultiLine", "MultiSelect", "Phone", "Secure", "Text", "Time", "URL"
        if ($Type -and $ValidFields -notcontains $Type) { Write-Warning "$Type is an invalid type! Please check here for valid types. https://ninjarmm.zendesk.com/hc/en-us/articles/16973443979789-Command-Line-Interface-CLI-Supported-Fields-and-Functionality" }

        # The below field requires additional information in order to set
        $NeedsOptions = "Dropdown"
        if ($DocumentName) {
            if ($NeedsOptions -contains $Type) {
                # We'll redirect the error output to the success stream to make it easier to error out if nothing was found or something else went wrong.
                $NinjaPropertyOptions = Ninja-Property-Docs-Options -AttributeName $Name @DocumentationParams 2>&1
            }
        }
        else {
            if ($NeedsOptions -contains $Type) {
                $NinjaPropertyOptions = Ninja-Property-Options -Name $Name 2>&1
            }
        }

        # If we received some sort of error it should have an exception property and we'll exit the function with that error information.
        if ($NinjaPropertyOptions.Exception) { throw $NinjaPropertyOptions }

        # The below type's require values not typically given in order to be set. The below code will convert whatever we're given into a format ninjarmm-cli supports.
        switch ($Type) {
            "Checkbox" {
                # While it's highly likely we were given a value like "True" or a boolean datatype it's better to be safe than sorry.
                $NinjaValue = [System.Convert]::ToBoolean($Value)
            }
            "Date or Date Time" {
                # Ninjarmm-cli is expecting the time to be representing as a Unix Epoch string. So we'll convert what we were given into that format.
                $Date = (Get-Date $Value).ToUniversalTime()
                $TimeSpan = New-TimeSpan (Get-Date "1970-01-01 00:00:00") $Date
                $NinjaValue = $TimeSpan.TotalSeconds
            }
            "Dropdown" {
                # Ninjarmm-cli is expecting the guid of the option we're trying to select. So we'll match up the value we were given with a guid.
                $Options = $NinjaPropertyOptions -replace '=', ',' | ConvertFrom-Csv -Header "GUID", "Name"
                $Selection = $Options | Where-Object { $_.Name -eq $Value } | Select-Object -ExpandProperty GUID

                if (-not $Selection) {
                    throw "Value is not present in dropdown"
                }

                $NinjaValue = $Selection
            }
            default {
                # All the other types shouldn't require additional work on the input.
                $NinjaValue = $Value
            }
        }

        # We'll need to set the field differently depending on if its a field in a Ninja Document or not.
        if ($DocumentName) {
            $CustomField = Ninja-Property-Docs-Set -AttributeName $Name -AttributeValue $NinjaValue @DocumentationParams 2>&1
        }
        else {
            $CustomField = Ninja-Property-Set -Name $Name -Value $NinjaValue 2>&1
        }

        if ($CustomField.Exception) {
            throw $CustomField
        }
    }
}
process {
    # If this script doesn't have Local Admin rights, error out.
    if (-not (Test-IsElevated)) {
        Write-Error -Message "Access Denied. Please run with Administrator privileges."
        exit 1
    }
    
    # These are the three default mandatory parameters. We'll 'splat' them later.
    $NinjaPropertyParams = @{
        Name        = $CustomFieldName
        Value       = $Value
        ErrorAction = "Stop"
    }

    # If either of the optional options were given, add it to the parameter list to be 'splatted' later.
    if ($CustomFieldType) { $NinjaPropertyParams["Type"] = $CustomFieldType }
    if ($NinjaDocumentName) { $NinjaPropertyParams["DocumentName"] = $NinjaDocumentName }

    # Log that we are about to attempt setting a custom field.
    Write-Host "Setting Custom Field '$CustomFieldName' with value '$Value'...."

    # Set a custom field using our function with the 'splatted' options.
    try {
        Set-NinjaProperty @NinjaPropertyParams
    }
    catch {
        # If we ran into some sort of error we'll output it here.
        Write-Error -Message $_.ToString() -Category InvalidOperation -Exception (New-Object System.Exception)
        exit 1
    }

    Write-Host "Success!"
}
end {

 

Description détaillée

• Structure du script: Le script commence par un synopsis et une description, suivis de paramètres pour les noms des champs personnalisés, les types, les noms des documents et les valeurs.
• Initialisation : Dans le bloc “begin”, il capture et valide les paramètres fournis, en s’assurant qu’un nom de champ personnalisé est spécifié. Si les champs “Date” ou “Date et heure” sont sélectionnés, le format est adapté à “Date ou Date et heure”.
• Vérification des droits d’administrateur: Le script comprend une fonction permettant de vérifier s’il s’exécute avec les privilèges d’administrateur local, condition essentielle pour modifier les paramètres du système.
• Définition des champs personnalisés: La fonction principale, Set-NinjaProperty, prend en compte différents paramètres et gère différents types de champs, notamment les champs de type “case à cocher”, “date ou heure” et “liste déroulante”.
• Gestion des erreurs: Dans le bloc “process”, le script utilise une instruction “try-catch” pour gérer les erreurs pendant l’opération de paramétrage du champ, en veillant à ce que tout problème soit détecté et signalé clairement.
• Flux d’exécution: Le script se termine par l’application des modifications et l’affichage d’un message de réussite.

Cas d’utilisation potentiels

Prenons l’exemple d’un MSP qui gère l’infrastructure informatique d’un client. Ils doivent mettre à jour le statut de conformité sur de nombreux appareils. Grâce à ce script, ils peuvent automatiser le processus et s’assurer que le champ personnalisé de chaque appareil est mis à jour de manière précise et efficace, ce qui permet de gagner du temps et de réduire les erreurs.

Comparaisons

Les méthodes traditionnelles peuvent impliquer des mises à jour manuelles par le biais d’une interface graphique, ce qui est sujet à des erreurs humaines et prend du temps. Ce script, cependant, automatise le processus, fournissant une solution plus rapide, plus fiable et plus évolutive.

FAQ

• Comment ce script gère-t-il les différents types de champs ?
  • Le script comprend une logique spécifique pour traiter les différents types de champs, garantissant ainsi un formatage correct des données.

• Est-il nécessaire d’avoir des droits d’administrateur pour exécuter ce script ?
  • Oui, des droits d’administration locale sont nécessaires pour modifier les paramètres du système.

• Ce script peut-il gérer les erreurs pendant l’exécution ?
  • Oui, il utilise des blocs try-catch pour attraper et signaler les erreurs de manière efficace.

Implications

Si ce script améliore l’efficacité, il a également des implications pour la sécurité informatique. Une utilisation non autorisée pourrait conduire à un traitement incorrect des données ou à des violations. Il est donc recommandé de mettre en place des contrôles d’accès et des audits stricts.

Recommandations

• Valider l’entrée: Veillez à ce que toutes les entrées du script soient validées afin d’éviter les erreurs.
• Gérer les autorisations: Restreignez l’utilisation des scripts aux personnes autorisées uniquement.
• Utilisation de l’audit: Conservez les journaux d’exécution des scripts à des fins de responsabilisation.

Conclusion :

À une époque où les données sont reines, une gestion efficace et précise des données est cruciale. NinjaOne, associé aux scripts PowerShell, offre une solution robuste aux MSP et aux professionnels de l’informatique. Ce script illustre la manière dont l’automatisation peut transformer des tâches banales en processus efficaces, favorisant ainsi une infrastructure informatique  plus résiliente et plus réactive.