Semplificare l’invio di notifiche toast importanti con uno script PowerShell 

Introduzione

Una comunicazione efficace con gli utenti finali è una pietra angolare delle operazioni IT, soprattutto per i fornitori di servizi gestiti (MSP) e i professionisti IT che gestiscono ambienti su larga scala. Garantire che i messaggi critici vengano visualizzati tempestivamente può fare la differenza tra una risoluzione senza problemi e un’interruzione dell’operatività. Questo script PowerShell offre un modo efficiente per inviare notifiche toast urgenti direttamente all’utente connesso in un sistema Windows.

Contesto

Le notifiche toast sono diventate un punto fermo nei moderni flussi di lavoro IT, in quanto offrono un modo non intrusivo ma immediato di fornire informazioni. Che si tratti di avvisare gli utenti di un aggiornamento critico, di una modifica dei criteri di sicurezza o di un’imminente finestra di manutenzione, queste notifiche garantiscono visibilità senza interrompere il flusso di lavoro. Gli approcci tradizionali prevedono spesso l’invio di e-mail o finestre pop-up, che sono troppo fastidiose o facili da ignorare. Lo script affronta queste limitazioni sfruttando il sistema di notifiche nativo di Windows per una messaggistica mirata e personalizzabile.

Lo script per semplificare le notifiche toast:

#Requires -Version 5.1

<#
.SYNOPSIS
    Sends an important toast notification to the currently signed in user. Please run as the Current Logged-on User.
.DESCRIPTION
    Sends an important toast notification to the currently signed in user. Please run as 'Current Logged on User'.
    You can also specify the "ApplicationId" to any string.
    The default ApplicationId is your company name found in the NINJA_COMPANY_NAME environment variable, but will fallback to "NinjaOne RMM" if it happens to not be set.

    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).

.EXAMPLE
    -Title "My Title Here" -Message "My Message Here"
    Sends the title "My Title Here" and message "My Message Here" as a Toast message/notification to the currently signed in user.
.EXAMPLE
    -Title "My Title Here" -Message "My Message Here" -ApplicationId "MyCompany"
    Sends the title "My Title Here" and message "My Message Here" as a Toast message/notification to the currently signed in user.
        ApplicationId: Creates a registry entry for your toasts called "MyCompany".
.OUTPUTS
    None
.NOTES
    If you want to change the defaults then with in the param block.
    If you want to customize the application name to show your company name,
        then look for $ApplicationId and change the content between the double quotes.

    Minimum OS Architecture Supported: Windows 10 (IoT editions are not supported due to lack of shell)
    Release Notes: Initial Release
#>

[CmdletBinding()]
param
(
    [string]$Title,
    [string]$Message,
    [string]$ApplicationId
)

begin {
    # Set the default ApplicationId if it's not provided. Use the Company Name if available, otherwise use the default.
    $ApplicationId = if ($env:NINJA_COMPANY_NAME) { $env:NINJA_COMPANY_NAME } else { "NinjaOne RMM" }

    Write-Host "[Info] Using ApplicationId: $($ApplicationId -replace '\s+','.')"

    if ($env:title -and $env:title -notlike "null") { $Title = $env:title }
    if ($env:message -and $env:message -notlike "null") { $Message = $env:message }
    if ($env:applicationId -and $env:applicationId -notlike "null") { $ApplicationId = $env:applicationId }

    if ([String]::IsNullOrWhiteSpace($Title)) {
        Write-Host "[Error] A Title is required."
        exit 1
    }
    if ([String]::IsNullOrWhiteSpace($Message)) {
        Write-Host "[Error] A Message is required."
        exit 1
    }

    if ($Title.Length -gt 42) {
        Write-Host "[Warn] The Title is longer than 42 characters. The title will be truncated by the Windows API to 42 characters."
    }
    if ($Message.Length -gt 254) {
        Write-Host "[Warn] The Message is longer than 254 characters. The message might get truncated by the Windows API."
    }

    function Test-IsSystem {
        $id = [System.Security.Principal.WindowsIdentity]::GetCurrent()
        return $id.Name -like "NT AUTHORITY*" -or $id.IsSystem
    }

    if (Test-IsSystem) {
        Write-Host "[Error] Please run this script as 'Current Logged on User'."
        Exit 1
    }

    function Set-RegKey {
        param (
            $Path,
            $Name,
            $Value,
            [ValidateSet("DWord", "QWord", "String", "ExpandedString", "Binary", "MultiString", "Unknown")]
            $PropertyType = "DWord"
        )
        if (-not $(Test-Path -Path $Path)) {
            # Check if path does not exist and create the path
            New-Item -Path $Path -Force | Out-Null
        }
        if ((Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore)) {
            # Update property and print out what it was changed from and changed to
            $CurrentValue = (Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore).$Name
            try {
                Set-ItemProperty -Path $Path -Name $Name -Value $Value -Force -Confirm:$false -ErrorAction Stop | Out-Null
            }
            catch {
                Write-Host "[Error] Unable to Set registry key for $Name please see below error!"
                Write-Host "$($_.Exception.Message)"
                exit 1
            }
            Write-Host "[Info] $Path\$Name changed from:"
            Write-Host " $CurrentValue to:"
            Write-Host " $($(Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore).$Name)"
        }
        else {
            # Create property with value
            try {
                New-ItemProperty -Path $Path -Name $Name -Value $Value -PropertyType $PropertyType -Force -Confirm:$false -ErrorAction Stop | Out-Null
            }
            catch {
                Write-Host "[Error] Unable to Set registry key for $Name please see below error!"
                Write-Host "$($_.Exception.Message)"
                exit 1
            }
            Write-Host "[Info] Set $Path\$Name to:"
            Write-Host " $($(Get-ItemProperty -Path $Path -Name $Name -ErrorAction Ignore).$Name)"
        }
    }

    function Show-Notification {
        [CmdletBinding()]
        Param (
            [string]
            $ApplicationId,
            [string]
            $ToastTitle,
            [string]
            [Parameter(ValueFromPipeline)]
            $ToastText
        )

        # Import all the needed libraries
        [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
        [Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
        [Windows.System.User, Windows.System, ContentType = WindowsRuntime] > $null
        [Windows.System.UserType, Windows.System, ContentType = WindowsRuntime] > $null
        [Windows.System.UserAuthenticationStatus, Windows.System, ContentType = WindowsRuntime] > $null
        [Windows.Storage.ApplicationData, Windows.Storage, ContentType = WindowsRuntime] > $null

        # Make sure that we can use the toast manager, also checks if the service is running and responding
        try {
            $ToastNotifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("$ApplicationId")
        }
        catch {
            Write-Host "$($_.Exception.Message)"
            Write-Host "[Error] Failed to create notification."
        }

        # Create a new toast notification
        $RawXml = [xml] @"
<toast scenario='urgent'>
    <visual>
    <binding template='ToastGeneric'>
        <text hint-maxLines='1'>$ToastTitle</text>
        <text>$ToastText</text>
    </binding>
    </visual>
</toast>
"@

        # Serialized Xml for later consumption
        $SerializedXml = New-Object Windows.Data.Xml.Dom.XmlDocument
        $SerializedXml.LoadXml($RawXml.OuterXml)

        # Setup how are toast will act, such as expiration time
        $Toast = $null
        $Toast = [Windows.UI.Notifications.ToastNotification]::new($SerializedXml)
        $Toast.Tag = "PowerShell"
        $Toast.Group = "PowerShell"
        $Toast.ExpirationTime = [DateTimeOffset]::Now.AddMinutes(1)

        # Show our message to the user
        $ToastNotifier.Show($Toast)
    }
}
process {
    # Create an object to store the ApplicationId and DisplayName
    $Application = [PSCustomObject]@{
        DisplayName = $ApplicationId
        # Replace any spaces with a period in the ApplicationId
        AppId       = $($ApplicationId -replace '\s+', '.')
    }
    Write-Host "Display Name: $($Application.DisplayName)"
    Write-Host "Application ID: $($Application.AppId)"

    Set-RegKey -Path "HKCU:\SOFTWARE\Classes\AppUserModelId\$($Application.AppId)" -Name "DisplayName" -Value $Application.DisplayName -PropertyType String
    Set-RegKey -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Notifications\Settings\$($Application.AppId)" -Name "AllowUrgentNotifications" -Value 1 -PropertyType DWord

    try {
        Write-Host "[Info] Attempting to send message to user..."
        $NotificationParams = @{
            ToastTitle    = $Title
            ToastText     = $Message
            ApplicationId = $Application.AppId
        }
        Show-Notification @NotificationParams -ErrorAction Stop
        Write-Host "[Info] Message sent to user."
    }
    catch {
        Write-Host "[Error] Failed to send message to user."
        Write-Host "$($_.Exception.Message)"
        exit 1
    }
    exit 0
}
end {
    
    
    
}

 

Analisi dettagliata

Questo script è stato creato per inviare notifiche toast urgenti all’utente attualmente connesso. Ecco una spiegazione passo per passo:

1. Impostazione dei valori predefiniti dell’applicazione 

Lo script per semplificare le notifiche toast verifica la presenza di una variabile d’ambiente NINJA_COMPANY_NAME per impostare l’ApplicationId predefinito. Se non è disponibile, torna a “NinjaOne RMM”. Questa flessibilità consente agli MSP di personalizzare le notifiche.

2. Parametri in ingresso 

Lo script per semplificare le notifiche toast accetta tre parametri chiave:

a. Title: Il titolo della notifica.

b. Message: Il testo del corpo della notifica.

c. ApplicationId: Un identificatore opzionale per il branding o il tracciamento.

3. Convalida dell’input

Lo script per semplificare le notifiche toast convalida gli input per verificare che Title e Message non siano vuoti. Se le lunghezze superano i limiti delle API di Windows (42 caratteri per il titolo e 254 per il messaggio), vengono emessi degli avvisi.

4. Controllo del sistema

Lo script per semplificare le notifiche toast include una protezione per garantire che venga eseguito dall’utente attualmente collegato e non come processo a livello di sistema, situazione in cui non verrebbero visualizzate le notifiche.

5. Configurazione del registro

Vengono create voci di registro personalizzate per il nome visualizzato della notifica e per abilitare le notifiche urgenti. Queste modifiche garantiscono il corretto funzionamento e un’esperienza dell’utente corrispondente alle attese.

6. Creazione della notifica

Sfruttando l’API Notifiche dell’interfaccia utente di Windows, lo script per semplificare le notifiche toast costruisce e visualizza una notifica toast. Il messaggio viene etichettato e raggruppato per una migliore tracciabilità.

7. Gestione degli errori

La gestione completa degli errori assicura che i problemi di configurazione o di esecuzione vengano registrati, rendendo semplice il troubleshooting.

Casi d’uso potenziali

Caso di studio: avvisi IT per i tempi di inattività pianificati

Immagina un MSP che gestisce l’infrastruttura IT di un’azienda di medie dimensioni. Il team IT prevede di eseguire una manutenzione del sistema che richiede agli utenti di salvare il lavoro prima di un’interruzione pianificata. Utilizzando questo script per semplificare le notifiche toast, invia una notifica toast intitolata “Avviso di manutenzione pianificata” con il messaggio “Per favore, salva il tuo lavoro. La manutenzione inizierà alle 20.”

Questo approccio garantisce agli utenti di ricevere una notifica immediata, senza affidarsi alle e-mail, che potrebbero non essere lette in tempo.

Confronti

Confronto con i metodi di notifica tradizionali:

• E-mail: Dipendono dal controllo della posta in arrivo da parte degli utenti, cosa che potrebbe ritardare le azioni critiche.
• Pop-Up: Spesso viene percepito come invadente e viene chiuso rapidamente.
• Lo script per semplificare le notifiche toast: Fornisce una via di mezzo ottimale: notifiche urgenti, visibili, ma che non interrompono le attività e che sfruttano l’ecosistema Windows.

Domande frequenti

D: Questo script per semplificare le notifiche toast può funzionare su Windows 7?

No, il sistema operativo minimo supportato è Windows 10 a causa della sua dipendenza dalle moderne API di notifica.

D: Cosa succede se lo script per semplificare le notifiche toast viene eseguito come SISTEMA?

Lo script lo rileva e impedisce l’esecuzione in un contesto di sistema, richiedendo che venga eseguito dall’utente attualmente connesso.

D: La notifica è persistente?

No, la notifica di toast scade dopo un minuto, a meno che non venga annullata prima dall’utente.

D: L’ApplicationId può essere personalizzato?

Sì, tramite il parametro ApplicationId o modificando il valore predefinito all’interno dello script.

Implicazioni

L’uso di questo script per semplificare le notifiche toast migliora la comunicazione informatica, garantendo che le notifiche critiche vengano visualizzate tempestivamente. Tuttavia, un uso eccessivo di notifiche urgenti potrebbe portare a uno “stress da avviso”, riducendone l’efficacia. I team IT devono utilizzare questo strumento con giudizio per mantenere il suo impatto significativo.

Raccomandazioni

• Test: Testa sempre lo script per semplificare le notifiche toast in un ambiente non di produzione per confermarnee la funzionalità.
• Esperienza utente: Evita i titoli e i messaggi troppo lunghi; mantienili concisi e chiari.
• Personalizzazione: Utilizza un ApplicationId significativo per creare fiducia e riconoscimento tra gli utenti.
• Sicurezza: Limita l’accesso agli script per semplificare le notifiche toast al personale autorizzato per evitare usi impropri.

Considerazioni finali

Questo script PowerShell per semplificare le notifiche toast è una potente aggiunta al kit di strumenti di un professionista IT, poiché offre funzionalità di notifica precise, personalizzabili ed efficienti. Per gli MSP e i team IT che utilizzano NinjaOne, l’integrazione di questo script in flussi di lavoro più ampi si inserisce nel quadro della gestione IT semplificata e proattiva offerta dalla piattaforma.