Automatizza l’impostazione dei valori dei campi personalizzati nei sistemi IT con PowerShell

Punti chiave

• Automazione con PowerShell: Lo script utilizza PowerShell per una gestione efficiente dei dati nei sistemi IT, in particolare negli ambienti MSP.
• Gestione dei campi personalizzati: È stato progettato per impostare i valori dei campi personalizzati in NinjaOne, dimostrando l’adattabilità a strumenti IT specifici.
• Privilegi amministrativi: L’esecuzione richiede i diritti di amministratore locale, sottolineando la necessità di sicurezza nelle operazioni a livello di sistema.
• Gestione del tipo di campo: Include la logica per la gestione di vari tipi di dati, come ‘Checkbox’, ‘Date’ e ‘Dropdown’, garantendo un inserimento accurato dei dati.
• Gestione degli errori: Incorpora la gestione degli errori per individuare e segnalare i problemi, migliorando l’affidabilità.
• Efficienza rispetto ai metodi manuali: Offre un’alternativa più efficiente agli aggiornamenti manuali dei dati, riducendo gli errori umani e risparmiando tempo.
• Considerazioni sulla sicurezza: Implica la necessità di un rigoroso controllo degli accessi e di una verifica per evitare l’uso improprio e le violazioni dei dati.
• Il potere dell’automazione nell’IT: Evidenzia l’impatto trasformativo dell’automazione nelle attività IT, migliorando l’accuratezza e l’efficienza operativa.

La personalizzazione dei sistemi IT è fondamentale per l’efficienza e l’accuratezza delle operazioni. Questo è importante soprattutto per i fornitori di servizi gestiti (MSP) e i reparti IT, dove gli script, come quello descritto qui, vengono utilizzati per impostare i valori dei campi personalizzati. Sfruttando PowerShell, un potente linguaggio di scripting, i professionisti IT possono automatizzare e semplificare attività complesse, ottimizzando le prestazioni e riducendo gli errori umani. 

Background

Lo script fornito è un classico esempio di come PowerShell possa interagire con specifici strumenti di gestione IT, in questo caso NinjaOne (un popolare software di monitoraggio e gestione remota). La possibilità di impostare i valori dei campi personalizzati in modo automatico è fondamentale per gli MSP e gli amministratori IT che devono gestire grandi quantità di dati su numerosi dispositivi e documenti. Questo script è uno strumento per semplificare la gestione dei dati e garantire la coerenza dell’infrastruttura IT.

Lo script per impostare i valori dei campi personalizzati:

#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 {

 

Analisi dettagliata

• Struttura dello script per impostare i valori dei campi personalizzati: Lo script inizia con una sinossi e una descrizione, seguita dai parametri per i nomi dei campi personalizzati, i tipi, i nomi dei documenti e i valori.
• Inizializzazione: Nel blocco ‘begin’, rileva e convalida i parametri forniti, assicurandosi che sia specificato un nome di campo personalizzato. Se sono selezionati i campi “Date” o “Date and Time”, il formato viene impostato su “Date or Date Time”.
• Controllo dei diritti di amministratore: Lo script include una funzione per verificare se è in esecuzione con privilegi amministrativi locali, un requisito essenziale per modificare le impostazioni del sistema.
• Impostazione dei campi personalizzati: La funzione principale, Set-NinjaProperty, accetta vari parametri e gestisce diversi tipi di campo, compresa una gestione speciale per i campi “Checkbox”, “Date or Date Time” e “Dropdown”.
• Gestione degli errori: Nel blocco “processo”, lo script utilizza un’istruzione try-catch per gestire gli errori durante l’operazione di impostazione del campo, assicurando che qualsiasi problema venga individuato e segnalato chiaramente.
• Flusso di esecuzione: Lo script si conclude applicando le modifiche e visualizzando un messaggio di successo.

Casi d’uso potenziali

Considera un MSP che gestisce l’infrastruttura IT del cliente. Hanno bisogno di aggiornare lo stato di conformità su numerosi dispositivi. Utilizzando lo script per impostare i valori dei campi personalizzati, possono automatizzare il processo, assicurando che il campo personalizzato di ogni dispositivo venga aggiornato in modo accurato ed efficiente, risparmiando tempo e riducendo gli errori.

Confronti

I metodi tradizionali possono comportare aggiornamenti manuali attraverso un’interfaccia grafica, che sono soggetti a errori umani e richiedono molto tempo. Lo script, tuttavia, automatizza il processo, fornendo una soluzione più veloce, affidabile e scalabile.

Domande frequenti

• In che modo questo script gestisce diversi tipi di campi?
  • Lo script include una logica specifica per gestire i vari tipi di campo, garantendo la corretta formattazione dei dati.

• È necessario disporre di diritti amministrativi per eseguire questo script?
  • Sì, per modificare le impostazioni del sistema sono necessari i diritti amministrativi locali.

• Questo script può gestire gli errori durante l’esecuzione?
  • Sì, utilizza i blocchi try-catch per catturare e segnalare gli errori in modo efficace.

Implicazioni

Se da un lato questo script aumenta l’efficienza, dall’altro comporta implicazioni per la sicurezza informatica. L’uso non autorizzato potrebbe portare a un trattamento non corretto dei dati o a violazioni. Pertanto, si raccomanda un controllo rigoroso degli accessi e una verifica.

Raccomandazioni

• Convalida l’input: Assicurati che tutti gli input dello script siano convalidati per evitare errori.
• Gestisci le autorizzazioni: Limita l’uso degli script al solo personale autorizzato.
• Utilizzo dell’audit: Conserva i log dell’esecuzione degli script per garantire la responsabilità.

Considerazioni finali

In un’era in cui i dati sono sovrani, una loro gestione efficiente e accurata è fondamentale. NinjaOne, combinato con lo scripting PowerShell, offre una soluzione efficace per gli MSP e i professionisti IT. Lo script esemplifica come l’automazione possa trasformare attività banali in processi efficienti, favorendo un’infrastruttura IT più resiliente e reattiva.