Stessa persona, due ID diversi, e lo storico dei ticket rimasto legato alla vecchia identità, come già scritto qualche parola fa.

Nella versione Cloud di ServiceDesk Plus non ho trovato – almeno in interfaccia grafica – niente di equivalente al Merge User che avevo e sfruttavo (e sfrutto ancora, in realtà) con le installazioni on-prem. Ho dato una sbirciata alla documentazione e messo in moto ChatGPT per darmi una mano con le API v3 di SDP in Cloud, passando da PowerShell per facilitarmi la vita.

Perciò, lista della spesa:

1. identificare e mappare correttamente vecchio e nuovo richiedente;
2. verificare i  ticket legati al vecchio account;
3. spostarli / riassegnarli al nuovo;
4. controllare che sul vecchio non rimanga più nulla;
5. eliminare l’account non più necessario;
6. ripetere la stessa procedura sugli altri utenti, in blocco.

Qui di seguito trovi solo degli esempi: domini, utenti, ID, URL del portale e credenziali vanno sostituiti con quelli che appartengono alla tua installazione. Prima di partire sul serio, però, è d’obbligo rispolverare il messaggio di servizio:

Il mio ambiente

Ho usato PowerShell 7 e un Self Client OAuth creato nella Zoho API Console del proprio data center.
Per il data center europeo, gli endpoint sono questi:

https://accounts.zoho.eu
https://sdpondemand.manageengine.eu

Nel mio caso il portale ServiceDesk Plus è:

https://sdpondemand.manageengine.eu/app/itdesk

itdesk è solo un esempio (anche se spesso corrisponde alla realtà, è il predefinito suggerito da ServiceDesk Plus Cloud per la tua prima installazione / istanza di SDP), tu sostituiscilo con il nome reale del tuo portale (o mantienilo se non lo hai mai cambiato).

Scope OAuth

Per l’intero processo ho autorizzato gli scope necessari a lettura utenti, lettura/modifica ticket e cancellazione richiedenti.
Gli scope che ti servono davvero dipendono da cosa vuoi fare: nel mio caso il Self Client copriva lettura, aggiornamento e cancellazione, che poi è quello che usano gli script che ti propongo qui di seguito.

Da Grant a Refresh Token

Il Grant Token generato dal Self Client è temporaneo e monouso.
Va scambiato – manco fosse una figurina dei calciatori – con un Refresh Token, perché questo lo puoi conservare e riutilizzare per far generare agli script nuovi Access Token in autonomia.

get-refreshtoken.ps1:

#requires -Version 7.0

# OAuth Self Client credentials
$ClientId     = "YOUR_CLIENT_ID"
$ClientSecret = "YOUR_CLIENT_SECRET"
$GrantToken   = "YOUR_GRANT_TOKEN"

$Body = @{
    grant_type    = "authorization_code"
    client_id     = $ClientId
    client_secret = $ClientSecret
    code          = $GrantToken
}

$Response = Invoke-RestMethod `
    -Method Post `
    -Uri "https://accounts.zoho.eu/oauth/v2/token" `
    -ContentType "application/x-www-form-urlencoded" `
    -Body $Body

$Response

$RefreshToken = $Response.refresh_token

if ($RefreshToken) {
    Write-Host "Refresh token successfully obtained." -ForegroundColor Green
}
else {
    Write-Host "No refresh token returned." -ForegroundColor Red
}

Il valore da conservare è – mi ripeto – refresh_token. Il Grant Token non serve più dopo lo scambio, mentre l’Access Token è temporaneo e viene rigenerato al volo usando il Refresh Token.

Occhio: Client Secret, Grant Token, Access Token e Refresh Token sono a tutti gli effetti credenziali. Non lasciarli sul disco se non ti servono, non perderne il controllo.

1. Verifica i due richiedenti

Prima di toccare qualsiasi dato, ti conviene verificare l’esistenza delle due identità e contare i ticket associati a ciascuna, così cerchi di capire se tutto ti torna rispetto a una semplice ricerca (identica nel risultato finale) via interfaccia grafica di SDP (ti basta fare una ricerca avanzata nella schermata delle richieste includendo i filtri adatti a mostrarti quanti ticket appartengono al richiedente vecchio).

check-merge.ps1:

#requires -Version 7.0

<#
.SYNOPSIS
    Audits two ServiceDesk Plus Cloud requester accounts.

.DESCRIPTION
    The script:
    - Generates a fresh OAuth access token using a refresh token
    - Finds two SDP users by email address
    - Retrieves requests associated with each requester
    - Displays a comparison
    - Makes no changes to ServiceDesk Plus
#>

$ClientId     = "YOUR_CLIENT_ID"
$ClientSecret = "YOUR_CLIENT_SECRET"
$RefreshToken = "YOUR_REFRESH_TOKEN"

$AccountsUrl = "https://accounts.zoho.eu"
$BaseUrl     = "https://sdpondemand.manageengine.eu/app/itdesk"

$OldEmail = "a.rossi@example.org"
$NewEmail = "alberto.rossi@example.org"

function Get-SdpAccessToken {
    $Body = @{
        refresh_token = $RefreshToken
        client_id     = $ClientId
        client_secret = $ClientSecret
        grant_type    = "refresh_token"
    }

    $Response = Invoke-RestMethod `
        -Uri "$AccountsUrl/oauth/v2/token" `
        -Method Post `
        -Body $Body `
        -ContentType "application/x-www-form-urlencoded"

    if (-not $Response.access_token) {
        throw "OAuth response did not contain an access_token."
    }

    return $Response.access_token
}

function Invoke-SdpGet {
    param (
        [Parameter(Mandatory)]
        [string]$Uri,

        [hashtable]$Query
    )

    if ($Query) {
        $QueryString = (
            $Query.GetEnumerator() |
            ForEach-Object {
                "$([uri]::EscapeDataString($_.Key))=$([uri]::EscapeDataString([string]$_.Value))"
            }
        ) -join "&"

        $Uri = "$Uri`?$QueryString"
    }

    return Invoke-RestMethod `
        -Uri $Uri `
        -Method Get `
        -Headers $Script:SdpHeaders
}

function Get-SdpUserByEmail {
    param (
        [Parameter(Mandatory)]
        [string]$EmailAddress
    )

    $InputData = @{
        list_info = @{
            row_count       = 100
            start_index     = 1
            get_total_count = $true
            search_fields   = @{
                email_id = $EmailAddress
            }
        }
    } | ConvertTo-Json -Depth 10 -Compress

    $Response = Invoke-SdpGet `
        -Uri "$BaseUrl/api/v3/users" `
        -Query @{
            input_data = $InputData
        }

    if (-not $Response.users) {
        return $null
    }

    return $Response.users |
        Where-Object {
            $_.email_id -ieq $EmailAddress
        } |
        Select-Object -First 1
}

function Get-SdpRequestsByRequester {
    param (
        [Parameter(Mandatory)]
        [string]$RequesterId
    )

    $AllRequests = [System.Collections.Generic.List[object]]::new()

    $StartIndex = 1
    $RowCount   = 100

    do {
        $InputData = @{
            list_info = @{
                row_count       = $RowCount
                start_index     = $StartIndex
                get_total_count = $true
                search_criteria = @{
                    field     = "requester.id"
                    condition = "is"
                    value     = $RequesterId
                }
            }
        } | ConvertTo-Json -Depth 10 -Compress

        $Response = Invoke-SdpGet `
            -Uri "$BaseUrl/api/v3/requests" `
            -Query @{
                input_data = $InputData
            }

        if ($Response.requests) {
            foreach ($Request in $Response.requests) {
                $AllRequests.Add($Request)
            }
        }

        $HasMoreRows = [bool]$Response.list_info.has_more_rows
        $StartIndex += $RowCount

    } while ($HasMoreRows)

    return $AllRequests
}

function Show-SdpUser {
    param (
        [Parameter(Mandatory)]
        [string]$Label,

        [Parameter(Mandatory)]
        $User,

        [Parameter(Mandatory)]
        $Requests
    )

    Write-Host ""
    Write-Host "===== $Label =====" -ForegroundColor Cyan

    [PSCustomObject]@{
        ID           = $User.id
        Name         = $User.name
        Email        = $User.email_id
        LoginName    = $User.login_name
        Site         = $User.site.name
        Department   = $User.department.name
        JobTitle     = $User.jobtitle
        IsTechnician = $User.is_technician
        Requests     = $Requests.Count
    } | Format-List
}

Write-Host ""
Write-Host "Generating OAuth access token..." -ForegroundColor Yellow

$AccessToken = Get-SdpAccessToken

$Script:SdpHeaders = @{
    Authorization = "Zoho-oauthtoken $AccessToken"
    Accept        = "application/vnd.manageengine.sdp.v3+json"
}

Write-Host "OAuth token obtained." -ForegroundColor Green

$OldUser = Get-SdpUserByEmail -EmailAddress $OldEmail

if (-not $OldUser) {
    throw "Old requester not found: $OldEmail"
}

$NewUser = Get-SdpUserByEmail -EmailAddress $NewEmail

if (-not $NewUser) {
    throw "New requester not found: $NewEmail"
}

$OldRequests = @(
    Get-SdpRequestsByRequester -RequesterId $OldUser.id
)

$NewRequests = @(
    Get-SdpRequestsByRequester -RequesterId $NewUser.id
)

Show-SdpUser `
    -Label "OLD USER" `
    -User $OldUser `
    -Requests $OldRequests

Show-SdpUser `
    -Label "NEW USER" `
    -User $NewUser `
    -Requests $NewRequests

$Summary = @(
    foreach ($Request in $OldRequests) {
        [PSCustomObject]@{
            Account     = "OLD"
            RequestId   = $Request.id
            Subject     = $Request.subject
            Status      = $Request.status.name
            Requester   = $Request.requester.name
            Email       = $Request.requester.email_id
            CreatedTime = $Request.created_time.display_value
        }
    }

    foreach ($Request in $NewRequests) {
        [PSCustomObject]@{
            Account     = "NEW"
            RequestId   = $Request.id
            Subject     = $Request.subject
            Status      = $Request.status.name
            Requester   = $Request.requester.name
            Email       = $Request.requester.email_id
            CreatedTime = $Request.created_time.display_value
        }
    }
)

$Summary |
    Sort-Object Account, RequestId |
    Format-Table -AutoSize

Write-Host ""
Write-Host "Audit completed. No changes were made." -ForegroundColor Yellow

Nel mio test il risultato era concettualmente questo:

OLD USER
Email    : a.rossi@example.org
Requests : 2

NEW USER
Email    : alberto.rossi@example.org
Requests : 0

Questo ti permette di capire quale ID far sopravvivere.

2. Sposta i ticket sull’utente ‘nuovo‘

Il secondo script usa l’ID del nuovo richiedente per aggiornare il campo requester dei ticket ancora legati alla vecchia identità. Quando lo lanci senza parametri parte sempre in simulazione così da evitare di modificare dati e fare potenziali danni, le modifiche scattano solo includendo -Apply.

move-sdp-requests.ps1:

#requires -Version 7.0

param (
    [switch]$Apply
)

$ClientId     = "YOUR_CLIENT_ID"
$ClientSecret = "YOUR_CLIENT_SECRET"
$RefreshToken = "YOUR_REFRESH_TOKEN"

$AccountsUrl = "https://accounts.zoho.eu"
$BaseUrl     = "https://sdpondemand.manageengine.eu/app/itdesk"

$OldUserId = "OLD_REQUESTER_ID"
$NewUserId = "NEW_REQUESTER_ID"

$OldEmail = "a.rossi@example.org"
$NewEmail = "alberto.rossi@example.org"

function Get-SdpAccessToken {
    $Body = @{
        refresh_token = $RefreshToken
        client_id     = $ClientId
        client_secret = $ClientSecret
        grant_type    = "refresh_token"
    }

    $Response = Invoke-RestMethod `
        -Uri "$AccountsUrl/oauth/v2/token" `
        -Method Post `
        -Body $Body `
        -ContentType "application/x-www-form-urlencoded"

    if (-not $Response.access_token) {
        throw "OAuth response did not contain an access token."
    }

    return $Response.access_token
}

function Get-SdpRequestsByRequester {
    param (
        [Parameter(Mandatory)]
        [string]$RequesterId
    )

    $AllRequests = [System.Collections.Generic.List[object]]::new()
    $StartIndex = 1
    $RowCount   = 100

    do {
        $InputData = @{
            list_info = @{
                row_count       = $RowCount
                start_index     = $StartIndex
                get_total_count = $true
                search_criteria = @{
                    field     = "requester.id"
                    condition = "is"
                    value     = $RequesterId
                }
            }
        } | ConvertTo-Json -Depth 10 -Compress

        $EncodedInputData = [uri]::EscapeDataString($InputData)
        $Uri = "$BaseUrl/api/v3/requests?input_data=$EncodedInputData"

        $Response = Invoke-RestMethod `
            -Uri $Uri `
            -Method Get `
            -Headers $Script:SdpHeaders

        if ($Response.requests) {
            foreach ($Request in $Response.requests) {
                $AllRequests.Add($Request)
            }
        }

        $HasMoreRows = [bool]$Response.list_info.has_more_rows
        $StartIndex += $RowCount

    } while ($HasMoreRows)

    return $AllRequests
}

function Set-SdpRequestRequester {
    param (
        [Parameter(Mandatory)]
        [string]$RequestId,

        [Parameter(Mandatory)]
        [string]$RequesterId
    )

    $InputData = @{
        request = @{
            requester = @{
                id = $RequesterId
            }
        }
    } | ConvertTo-Json -Depth 10 -Compress

    $Body = @{
        input_data = $InputData
    }

    Invoke-RestMethod `
        -Uri "$BaseUrl/api/v3/requests/$RequestId" `
        -Method Put `
        -Headers $Script:SdpHeaders `
        -ContentType "application/x-www-form-urlencoded" `
        -Body $Body
}

Write-Host ""
Write-Host "Generating OAuth access token..." -ForegroundColor Yellow

$AccessToken = Get-SdpAccessToken

$Script:SdpHeaders = @{
    Authorization = "Zoho-oauthtoken $AccessToken"
    Accept        = "application/vnd.manageengine.sdp.v3+json"
}

$Requests = @(
    Get-SdpRequestsByRequester -RequesterId $OldUserId
)

Write-Host "Found $($Requests.Count) request(s)." -ForegroundColor Cyan

$Requests |
    Select-Object `
        id,
        subject,
        @{Name = "Status"; Expression = { $_.status.name } },
        @{Name = "Requester"; Expression = { $_.requester.email_id } } |
    Format-Table -AutoSize

if (-not $Apply) {
    Write-Host ""
    Write-Host "SIMULATION MODE" -ForegroundColor Yellow
    Write-Host "No changes were made."
    Write-Host ""
    Write-Host "To apply the changes, run:"
    Write-Host ".\move-sdp-requests.ps1 -Apply"
    exit
}

foreach ($Request in $Requests) {
    Write-Host "Updating request $($Request.id): $($Request.subject)"

    $Result = Set-SdpRequestRequester `
        -RequestId $Request.id `
        -RequesterId $NewUserId

    if ($Result.response_status.status -eq "success") {
        Write-Host "  Success" -ForegroundColor Green
    }
    else {
        Write-Host "  API returned an unexpected status." -ForegroundColor Yellow
        $Result.response_status | Format-List
    }
}

Write-Host ""
Write-Host "Verifying remaining requests on old requester..." -ForegroundColor Yellow

$RemainingRequests = @(
    Get-SdpRequestsByRequester -RequesterId $OldUserId
)

if ($RemainingRequests.Count -eq 0) {
    Write-Host "Old requester has no remaining requests." -ForegroundColor Green
}
else {
    Write-Host "$($RemainingRequests.Count) request(s) still reference the old requester." -ForegroundColor Red
}

Prima:

.\move-sdp-requests.ps1

Dopo (dopo aver controllato l’elenco):

.\move-sdp-requests.ps1 -Apply

Il controllo finale qui è fondamentale: il vecchio richiedente non deve più avere ticket aperti a suo nome, altrimenti fermati e non andare avanti, c’è qualcosa di sbagliato o presumibilmente ‘saltato‘ durante i precedenti passaggi.
Ritenta, sarai più fortunato.

3. Controlla il richiedente ‘vecchio‘

A questo punto fai un controllo (quindi anche stavolta in sola lettura) sul vecchio richiedente.
Più uno scrupolo che altro.

audit-sdp-requester.ps1:

#requires -Version 7.0

$ClientId     = "YOUR_CLIENT_ID"
$ClientSecret = "YOUR_CLIENT_SECRET"
$RefreshToken = "YOUR_REFRESH_TOKEN"

$AccountsUrl = "https://accounts.zoho.eu"
$BaseUrl     = "https://sdpondemand.manageengine.eu/app/itdesk"

$OldUserId = "OLD_REQUESTER_ID"
$OldEmail  = "a.rossi@example.org"

function Get-SdpAccessToken {
    $Body = @{
        refresh_token = $RefreshToken
        client_id     = $ClientId
        client_secret = $ClientSecret
        grant_type    = "refresh_token"
    }

    $Response = Invoke-RestMethod `
        -Uri "$AccountsUrl/oauth/v2/token" `
        -Method Post `
        -Body $Body `
        -ContentType "application/x-www-form-urlencoded"

    if (-not $Response.access_token) {
        throw "OAuth response did not contain an access token."
    }

    return $Response.access_token
}

function Invoke-SdpGet {
    param (
        [Parameter(Mandatory)]
        [string]$Uri
    )

    Invoke-RestMethod `
        -Uri $Uri `
        -Method Get `
        -Headers $Script:SdpHeaders `
        -ErrorAction Stop
}

function Get-SdpRequestsByRequester {
    param (
        [Parameter(Mandatory)]
        [string]$RequesterId
    )

    $AllRequests = [System.Collections.Generic.List[object]]::new()
    $StartIndex = 1
    $RowCount   = 100

    do {
        $InputData = @{
            list_info = @{
                row_count       = $RowCount
                start_index     = $StartIndex
                get_total_count = $true
                search_criteria = @{
                    field     = "requester.id"
                    condition = "is"
                    value     = $RequesterId
                }
            }
        } | ConvertTo-Json -Depth 10 -Compress

        $EncodedInputData = [uri]::EscapeDataString($InputData)

        $Response = Invoke-SdpGet `
            -Uri "$BaseUrl/api/v3/requests?input_data=$EncodedInputData"

        if ($Response.requests) {
            foreach ($Request in $Response.requests) {
                $AllRequests.Add($Request)
            }
        }

        $HasMoreRows = [bool]$Response.list_info.has_more_rows
        $StartIndex += $RowCount

    } while ($HasMoreRows)

    return $AllRequests
}

Write-Host ""
Write-Host "Generating OAuth access token..." -ForegroundColor Yellow

$AccessToken = Get-SdpAccessToken

$Script:SdpHeaders = @{
    Authorization = "Zoho-oauthtoken $AccessToken"
    Accept        = "application/vnd.manageengine.sdp.v3+json"
}

Write-Host "Auditing old requester:" -ForegroundColor Cyan
Write-Host "$OldEmail [$OldUserId]"

$UserResponse = Invoke-SdpGet `
    -Uri "$BaseUrl/api/v3/users/$OldUserId"

$User = $UserResponse.user

[PSCustomObject]@{
    ID         = $User.id
    Name       = $User.name
    Email      = $User.email_id
    Site       = $User.site.name
    Department = $User.department.name
} | Format-List

$Requests = @(
    Get-SdpRequestsByRequester -RequesterId $OldUserId
)

Write-Host ""
Write-Host "Requests: $($Requests.Count)"

if ($Requests.Count -eq 0) {
    Write-Host "No requests remain associated with the old requester." -ForegroundColor Green
}

Write-Host ""
Write-Host "Audit completed. No changes were made." -ForegroundColor Yellow

Per eventuali associazioni non esposte da questa API vale la pena fare anche un controllo dall’interfaccia grafica di SDP, tramite View Associations, prima della cancellazione definitiva.

4. Elimina il vecchio richiedente

Una volta verificato che l’identità vecchia non serve più, puoi eliminata tramite l’endpoint /api/v3/requesters/{id}. Anche questo script parte in sola lettura fino a quando non lo rilanci con il parametro per applicare davvero la modifica.

delete-sdp-requester.ps1:

#requires -Version 7.0

param (
    [switch]$Apply
)

$ClientId     = "YOUR_CLIENT_ID"
$ClientSecret = "YOUR_CLIENT_SECRET"
$RefreshToken = "YOUR_REFRESH_TOKEN"

$AccountsUrl = "https://accounts.zoho.eu"
$BaseUrl     = "https://sdpondemand.manageengine.eu/app/itdesk"

$RequesterId    = "OLD_REQUESTER_ID"
$RequesterEmail = "a.rossi@example.org"

function Get-SdpAccessToken {
    $Body = @{
        refresh_token = $RefreshToken
        client_id     = $ClientId
        client_secret = $ClientSecret
        grant_type    = "refresh_token"
    }

    $Response = Invoke-RestMethod `
        -Uri "$AccountsUrl/oauth/v2/token" `
        -Method Post `
        -Body $Body `
        -ContentType "application/x-www-form-urlencoded"

    if (-not $Response.access_token) {
        throw "OAuth response did not contain an access token."
    }

    return $Response.access_token
}

Write-Host ""
Write-Host "Generating OAuth access token..." -ForegroundColor Yellow

$AccessToken = Get-SdpAccessToken

$Headers = @{
    Authorization = "Zoho-oauthtoken $AccessToken"
    Accept        = "application/vnd.manageengine.sdp.v3+json"
}

Write-Host "Requester scheduled for deletion:"
Write-Host "$RequesterEmail [$RequesterId]"

if (-not $Apply) {
    Write-Host ""
    Write-Host "SIMULATION MODE" -ForegroundColor Yellow
    Write-Host "No changes were made."
    Write-Host ""
    Write-Host "To delete the requester, run:"
    Write-Host ".\delete-sdp-requester.ps1 -Apply" -ForegroundColor Cyan
    exit
}

$Response = Invoke-RestMethod `
    -Uri "$BaseUrl/api/v3/requesters/$RequesterId" `
    -Method Delete `
    -Headers $Headers `
    -ErrorAction Stop

Write-Host ""
Write-Host "Requester deleted successfully." -ForegroundColor Green

if ($Response) {
    $Response | ConvertTo-Json -Depth 10
}

Prima:

.\delete-sdp-requester.ps1

e solo dopo aver verificato che va a eliminare chi ti aspetti, lo rilanci:

.\delete-sdp-requester.ps1 -Apply

A questo punto il hai concluso, sei passato al nuovo richiedente e fatto piazza pulita del vecchio.

5. Ora ripeti, ma con tutti gli altri

Quando il giro per singolo utente ha sortito l’effetto desiderato sono passato a farlo per gli altri tutti insieme. In una migrazione reale ci sono sempre eccezioni, alias e omonimie che rovinano qualsiasi logica automatica, quindi valuta bene quello che fai, non pensare di dare tutto in pasto agli script, non presidiare e andarti a prendere un caffè sperando di non trovare sbavature al rientro.

Per la sicurezza e tranquillità della tua pausa caffè, preparati un file di mappatura in un CSV, così facendo hai la certezza di mettere vecchio e nuovo richiedente sul giusto livello, senza scherzi, senza “dedurre il nuovo dal vecchio”.

requester-mapping.csv:

OldEmail,NewEmail
a.verdi@example.org,andrea.verdi@example.org
d.bianchi@example.org,daniela.bianchi@example.org
e.neri@example.org,eleonora.neri@example.org
f.gialli@example.org,fabio.gialli@example.org

Script “bulk” (in un colpo solo)

bulk-merge-sdp-requesters.ps1:

#requires -Version 7.0

param (
    [Parameter()]
    [string]$MappingFile = ".\requester-mapping.csv",

    [switch]$Apply,

    [switch]$DeleteOld
)

$ClientId     = "YOUR_CLIENT_ID"
$ClientSecret = "YOUR_CLIENT_SECRET"
$RefreshToken = "YOUR_REFRESH_TOKEN"

$AccountsUrl = "https://accounts.zoho.eu"
$BaseUrl     = "https://sdpondemand.manageengine.eu/app/itdesk"

$Timestamp  = Get-Date -Format "yyyyMMdd-HHmmss"
$ReportFile = ".\sdp-merge-report-$Timestamp.csv"

function Get-SdpAccessToken {
    $Body = @{
        refresh_token = $RefreshToken
        client_id     = $ClientId
        client_secret = $ClientSecret
        grant_type    = "refresh_token"
    }

    $Response = Invoke-RestMethod `
        -Uri "$AccountsUrl/oauth/v2/token" `
        -Method Post `
        -Body $Body `
        -ContentType "application/x-www-form-urlencoded" `
        -ErrorAction Stop

    if (-not $Response.access_token) {
        throw "OAuth response did not contain an access token."
    }

    return $Response.access_token
}

function Invoke-SdpGet {
    param (
        [Parameter(Mandatory)]
        [string]$Uri
    )

    Invoke-RestMethod `
        -Uri $Uri `
        -Method Get `
        -Headers $Script:SdpHeaders `
        -ErrorAction Stop
}

function Get-SdpUserByEmail {
    param (
        [Parameter(Mandatory)]
        [string]$EmailAddress
    )

    $InputData = @{
        list_info = @{
            row_count       = 100
            start_index     = 1
            get_total_count = $true
            search_fields   = @{
                email_id = $EmailAddress
            }
        }
    } | ConvertTo-Json -Depth 10 -Compress

    $EncodedInputData = [uri]::EscapeDataString($InputData)

    $Response = Invoke-SdpGet `
        -Uri "$BaseUrl/api/v3/users?input_data=$EncodedInputData"

    $Matches = @(
        $Response.users |
        Where-Object {
            $_.email_id -ieq $EmailAddress
        }
    )

    if ($Matches.Count -eq 0) {
        return $null
    }

    if ($Matches.Count -gt 1) {
        throw "Multiple SDP users found with email address $EmailAddress."
    }

    return $Matches[0]
}

function Get-SdpRequestsByRequester {
    param (
        [Parameter(Mandatory)]
        [string]$RequesterId
    )

    $AllRequests = [System.Collections.Generic.List[object]]::new()
    $StartIndex = 1
    $RowCount   = 100

    do {
        $InputData = @{
            list_info = @{
                row_count       = $RowCount
                start_index     = $StartIndex
                get_total_count = $true
                search_criteria = @{
                    field     = "requester.id"
                    condition = "is"
                    value     = $RequesterId
                }
            }
        } | ConvertTo-Json -Depth 10 -Compress

        $EncodedInputData = [uri]::EscapeDataString($InputData)

        $Response = Invoke-SdpGet `
            -Uri "$BaseUrl/api/v3/requests?input_data=$EncodedInputData"

        if ($Response.requests) {
            foreach ($Request in $Response.requests) {
                $AllRequests.Add($Request)
            }
        }

        $HasMoreRows = [bool]$Response.list_info.has_more_rows
        $StartIndex += $RowCount

    } while ($HasMoreRows)

    return $AllRequests
}

function Set-SdpRequestRequester {
    param (
        [Parameter(Mandatory)]
        [string]$RequestId,

        [Parameter(Mandatory)]
        [string]$RequesterId
    )

    $InputData = @{
        request = @{
            requester = @{
                id = $RequesterId
            }
        }
    } | ConvertTo-Json -Depth 10 -Compress

    $Body = @{
        input_data = $InputData
    }

    Invoke-RestMethod `
        -Uri "$BaseUrl/api/v3/requests/$RequestId" `
        -Method Put `
        -Headers $Script:SdpHeaders `
        -ContentType "application/x-www-form-urlencoded" `
        -Body $Body `
        -ErrorAction Stop
}

function Remove-SdpRequester {
    param (
        [Parameter(Mandatory)]
        [string]$RequesterId
    )

    Invoke-RestMethod `
        -Uri "$BaseUrl/api/v3/requesters/$RequesterId" `
        -Method Delete `
        -Headers $Script:SdpHeaders `
        -ErrorAction Stop
}

if (-not (Test-Path $MappingFile)) {
    throw "Mapping file not found: $MappingFile"
}

$Mappings = @(Import-Csv $MappingFile)

if ($Mappings.Count -eq 0) {
    throw "Mapping file contains no entries."
}

foreach ($Mapping in $Mappings) {
    if (-not $Mapping.OldEmail -or -not $Mapping.NewEmail) {
        throw "Every CSV row must contain OldEmail and NewEmail."
    }

    if ($Mapping.OldEmail -ieq $Mapping.NewEmail) {
        throw "OldEmail and NewEmail are identical: $($Mapping.OldEmail)"
    }
}

Write-Host ""
Write-Host "Generating OAuth access token..." -ForegroundColor Yellow

$AccessToken = Get-SdpAccessToken

$Script:SdpHeaders = @{
    Authorization = "Zoho-oauthtoken $AccessToken"
    Accept        = "application/vnd.manageengine.sdp.v3+json"
}

if (-not $Apply) {
    Write-Host "SIMULATION MODE" -ForegroundColor Yellow
    Write-Host "No changes will be made."
}
elseif (-not $DeleteOld) {
    Write-Host "APPLY MODE" -ForegroundColor Cyan
    Write-Host "Requests will be reassigned."
    Write-Host "Old requester accounts will NOT be deleted."
}
else {
    Write-Host "APPLY + DELETE MODE" -ForegroundColor Red
    Write-Host "Requests will be reassigned and empty old requester accounts will be deleted."
}

$Results = [System.Collections.Generic.List[object]]::new()
$Index = 0

foreach ($Mapping in $Mappings) {
    $Index++

    $OldEmail = $Mapping.OldEmail.Trim()
    $NewEmail = $Mapping.NewEmail.Trim()

    Write-Host ""
    Write-Host "============================================================"
    Write-Host "[$Index/$($Mappings.Count)] $OldEmail"
    Write-Host "                     -> $NewEmail"
    Write-Host "============================================================"

    $Result = [ordered]@{
        OldEmail          = $OldEmail
        NewEmail          = $NewEmail
        OldUserId         = $null
        NewUserId         = $null
        RequestsFound     = 0
        RequestsMoved     = 0
        RequestsRemaining = $null
        OldUserDeleted    = $false
        Status            = $null
        Error             = $null
    }

    try {
        $OldUser = Get-SdpUserByEmail -EmailAddress $OldEmail

        if (-not $OldUser) {
            $Result.Status = "Old user not found"
            $Results.Add([PSCustomObject]$Result)
            continue
        }

        $Result.OldUserId = $OldUser.id

        $NewUser = Get-SdpUserByEmail -EmailAddress $NewEmail

        if (-not $NewUser) {
            $Result.Status = "New user not found"
            $Results.Add([PSCustomObject]$Result)
            continue
        }

        $Result.NewUserId = $NewUser.id

        if ($OldUser.id -eq $NewUser.id) {
            $Result.Status = "Same SDP user"
            $Results.Add([PSCustomObject]$Result)
            continue
        }

        $Requests = @(
            Get-SdpRequestsByRequester -RequesterId $OldUser.id
        )

        $Result.RequestsFound = $Requests.Count

        if ($Requests.Count -gt 0) {
            $Requests |
                Select-Object `
                    id,
                    subject,
                    @{Name = "Status"; Expression = { $_.status.name } } |
                Format-Table -AutoSize
        }

        if (-not $Apply) {
            $Result.Status = "Simulation"
            $Results.Add([PSCustomObject]$Result)
            continue
        }

        foreach ($Request in $Requests) {
            Write-Host "Moving request $($Request.id)..." -NoNewline

            $Response = Set-SdpRequestRequester `
                -RequestId $Request.id `
                -RequesterId $NewUser.id

            if ($Response.response_status.status -eq "success") {
                $Result.RequestsMoved++
                Write-Host " OK" -ForegroundColor Green
            }
            else {
                throw "Unexpected API status while moving request $($Request.id)."
            }
        }

        $RemainingRequests = @(
            Get-SdpRequestsByRequester -RequesterId $OldUser.id
        )

        $Result.RequestsRemaining = $RemainingRequests.Count

        if ($RemainingRequests.Count -gt 0) {
            $Result.Status = "Requests remain"
            $Results.Add([PSCustomObject]$Result)
            continue
        }

        if ($DeleteOld) {
            Write-Host "Deleting old requester..." -NoNewline

            Remove-SdpRequester -RequesterId $OldUser.id

            Write-Host " OK" -ForegroundColor Green

            $Result.OldUserDeleted = $true
            $Result.Status = "Merged and deleted"
        }
        else {
            $Result.Status = "Requests merged"
        }
    }
    catch {
        Write-Host ""
        Write-Host "FAILED: $($_.Exception.Message)" -ForegroundColor Red

        $Result.Status = "Failed"
        $Result.Error  = $_.Exception.Message
    }

    $Results.Add([PSCustomObject]$Result)
}

$Results |
    Export-Csv `
        -Path $ReportFile `
        -NoTypeInformation `
        -Encoding UTF8

Write-Host ""
Write-Host "============================================================"
Write-Host "SUMMARY" -ForegroundColor Cyan
Write-Host "============================================================"

$Results |
    Format-Table `
        OldEmail,
        NewEmail,
        RequestsFound,
        RequestsMoved,
        RequestsRemaining,
        OldUserDeleted,
        Status `
        -AutoSize

Write-Host ""
Write-Host "Report:"
Write-Host $ReportFile -ForegroundColor Cyan

Consiglio spassionato

La modalità più prudente è affrontarla in tre passaggi.

1. Sola lettura, pura simulazione

.\bulk-merge-sdp-requesters.ps1

Non modifica nulla. Verifica tutte le corrispondenze e mostra i ticket trovati, così puoi ancora verificare che tutto corrisponda, in sola lettura, senza danni collaterali.

2. Spostamento dei ticket

.\bulk-merge-sdp-requesters.ps1 -Apply

Sposta i ticket, ma lascia intatti i vecchi richiedenti.

3. Eliminazione delle vecchie identità

Dopo aver verificato il report:

.\bulk-merge-sdp-requesters.ps1 -Apply -DeleteOld

Lo script ricontrolla che il vecchio richiedente non abbia più ticket prima di eliminarlo. Al termine viene mostrato (e salvato) in automatico un report CSV simile a questo:

OldEmail              NewEmail                     RequestsFound RequestsMoved RequestsRemaining OldUserDeleted Status
--------              --------                     ------------- ------------- ----------------- -------------- ------
a.verdi@example.org    andrea.verdi@example.org                 7             7                 0           True Merged and deleted
d.bianchi@example.org  daniela.bianchi@example.org              3             3                 0           True Merged and deleted
e.neri@example.org     eleonora.neri@example.org                0             0                 0           True Merged and deleted

In conclusione

La parte più importante di questa procedura non è la DELETE, è tutto quello che viene prima. Cancellare gli utenti è solo l’operazione ultima per non lasciare sporco in giro. Un utente di ServiceDesk Plus non lo elimini semplicemente perché il suo indirizzo e-mail è diventato obsoleto: prima identifichi l’account che lo sostituisce, trasferisci lo storico necessario e poi verifichi che non siano rimaste tracce su quello che andrai a spazzare via.

Per pochi account puoi procedere uno alla volta senza problemi, se lo preferisci e ti fa sentire più sicuro di quello che stai per fare. In una migrazione di dominio, però, il mapping CSV e lo script bulk rendono il processo più corretto, privo di sbavature (a meno di averle fatte durante la preparazione di script e file di corrispondenza), lo scopo è cercare di portare a zero (o per lo meno alla minima cifra possibile) gli errori manuali.

Con un minimo di pianificazione e la maggiore attenzione possibile (ed ecco perché gli script che ti ho proposto sopra prevedono di lavorare sempre in sola lettura a meno di essere lanciati con uno specifico parametro), le API v3 di SDP in Cloud diventano l’unico strumento efficace per questo tipo di operazioni amministrative che da interfaccia grafica non hai a disposizione nonostante tu si amministratore dell’istanza.

L’area commenti è a tua disposizione se ti sei trovato in una situazione simile, se hai bisogno di delucidazioni sullo script o di chiedere banalmente una mano, nei limiti del possibile e del fattibile da qui :-)

#KeepItSimple

Immagine di copertina Israel Andrade on Unsplash

ServiceDesk Plus Cloud: merge “fai-da-te” dei richiedenti è stato scritto da Gioxx per Gioxx.org.

Nella pratica, almeno nel mio caso, il remapping automatico ha fatto solo metà del lavoro. L’organizzazione e il progetto sono sopravvissuti bene al cambio di directory, insieme a repository, board e storico. Alcune identità, però, sono rimaste appese ai vecchi account, e a quel punto mi è toccato rimboccarmi le maniche, prendere un due di picche su un potenziale ticket a pagamento verso il supporto di Microsoft (nonostante in documentazione venga consigliata quella come unica via per risolvere questo tipo di magagne), lucidare la PowerShell e mettere sul piede di guerra ChatGPT che mi ha seguito durante tutto l’iter per evitare di dimenticarmi qualche passaggio.

In questo post metto giù la procedura che ho seguito per arrivare a una situazione pulita:

• nuove identità presenti e corrette in Azure DevOps;
• nessun Work Item ancora assegnato ai vecchi account;
• membership dei nuovi utenti verificate;
• vecchi utenti rimossi dall’organizzazione;
• storico di revisioni e commenti preservato così com’è;
• repository, branch, policy e ACL Git controllati;
• nessun permesso Git esplicito ancora legato alle identità legacy.

L’obiettivo non era cancellare ogni traccia dei vecchi utenti (avrebbe voluto dire alterare l’audit trail, e no grazie), ma assicurarmi che nessuna identità legacy fosse ancora necessaria per far girare il progetto oggi. Gli esempi che segui sono ovviamente anonimizzati: ID, UPN, organizzazione e progetto vanno adattati al tuo ambiente.

Prima di partire sul serio, ci vuole il giusto disclaimer:

Lo scenario

Tenant sorgente
└── oldtenant.onmicrosoft.com
    ├── a.rossi-cutover@oldtenant.onmicrosoft.com
    └── m.bianchi-cutover@oldtenant.onmicrosoft.com

Azure DevOps
└── MyOrganization
    └── MyProject

Tenant destinazione
└── newtenant.onmicrosoft.com
    ├── andrea.rossi@example.com
    └── marco.bianchi@example.com

Gli utenti del tenant sorgente non dovevano restare come guest: esistevano già identità native nel tenant di destinazione, ed erano quelle che volevo vedere usate da Azure DevOps.Il cambio di directory dell’organizzazione è filato liscio (come ti avevo già scritto poco sopra), il problema è saltato fuori dopo, controllando cosa fosse effettivamente successo al remapping delle identità.

Il remapping di Microsoft si è fermato a metà strada

Dopo lo switch, alcune identità risultavano collegate correttamente, altre erano rimaste in uno stato un po’ anomalo.
Una identità nuova e collegata bene a Entra ID si presentava così:

principalName : andrea.rossi@example.com
origin         : aad
originId       : <Entra Object ID>
descriptor     : aad....

Alcune vecchie identità, invece, così:

principalName : a.rossi-cutover@oldtenant.onmicrosoft.com
origin         : aad
originId       :
descriptor     : bnd....

L’assenza di originId e il descriptor bnd.* sono stati il campanello: lo switch della directory era riuscito, ma non potevo considerare il lavoro finito solo per quello. Ho anche provato ad aspettare qualche ora nell’inutile (con il senno di poi) speranza che Microsoft ci mettesse più tempo del previsto a rimettere le cose a posto (ho lasciato passare la notte dopo la migrazione), ma nulla da fare. Ho quindi gestito a mano le parti che restavano: nuove identità, assegnazioni correnti, membership e infine la rimozione dei vecchi utenti dall’organizzazione.

Preparare la sessione PowerShell

REST API di Azure DevOps e PowerShell 7. Inizia a prepararti le variabili che ti serviranno più volte, nei passaggi successivi.

$Organization = "MyOrganization"
$Project      = "MyProject"

Vai a crearti un PAT (Personal Access Token) sul DevOps, io ne ho tirato in piedi uno della durata di un giorno, così da evitare poi di dimenticarmelo lì attivo e potenzialmente “dannoso“.
Per farlo digerire e gestire dagli script PowerShell ho evitato di scriverlo in chiaro da qualche parte, l’ho fatto richiedere direttamente “live“:

$Pat = Read-Host "Azure DevOps PAT" -AsSecureString

$Ptr = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($Pat)

try {
    $PlainPat = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($Ptr)

    $Token = [Convert]::ToBase64String(
        [Text.Encoding]::ASCII.GetBytes(":$PlainPat")
    )
}
finally {
    [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($Ptr)
}

$Headers = @{
    Authorization = "Basic $Token"
}

Gli scope del PAT dipendono da cosa devi fare: per l’audit bastano quelli di lettura sulle aree coinvolte, per modifiche e rimozioni servono i relativi permessi di gestione, io ammetto di aver preso la scorciatoia e creato un PAT con FullAccess dopo aver inizialmente perso tempo con un PAT limitato.

Recuperare il progetto

Prima tappa: recupero l’ID del progetto, che mi serve in praticamente tutte le chiamate successive.

$ProjectUri = "https://dev.azure.com/$Organization/_apis/projects/${Project}?api-version=7.1"

$ProjectInfo = Invoke-RestMethod `
    -Uri $ProjectUri `
    -Headers $Headers `
    -Method Get

$ProjectInfo |
    Select-Object id,name,state |
    Format-List

$ProjectId = $ProjectInfo.id

Nota PowerShell da tenere a mente: quando una variabile è seguita subito da ? in una URL, delimitala con ${...}, altrimenti PowerShell la interpreta come vuole lui, chiediti perché te lo sto scrivendo qui (sì, pur sapendolo ho fatto il classico errore da principiante al primo giro).

Inventario degli utenti dell’organizzazione

Punto di partenza: chi ha accesso oggi all’organizzazione, con licenza e nome visualizzato (il displayName) così da avere un riferimento da confrontare con quello che troverai più avanti.

$EntitlementsUri = "https://vsaex.dev.azure.com/$Organization/_apis/userentitlements?api-version=7.1"

$Entitlements = Invoke-RestMethod `
    -Uri $EntitlementsUri `
    -Headers $Headers `
    -Method Get

$OrgUsers = $Entitlements.items

$OrgUsers |
    Select-Object `
        id,
        @{N="DisplayName";E={$_.user.displayName}},
        @{N="PrincipalName";E={$_.user.principalName}},
        @{N="License";E={$_.accessLevel.accountLicenseType}} |
    Format-Table -AutoSize

Dettaglio che mi ha fatto perdere un po’ di tempo: l’ID dell’entitlement è id a livello principale, non user.id. Segnati bene chi è chi, ti tornerà utile più avanti.

$OrgUsers |
    Select-Object `
        id,
        @{N="DisplayName";E={$_.user.displayName}},
        @{N="PrincipalName";E={$_.user.principalName}},
        @{N="License";E={$_.accessLevel.accountLicenseType}} |
    Export-Csv `
        -Path ".\AzureDevOps-Users-BeforeCleanup.csv" `
        -NoTypeInformation `
        -Encoding UTF8

Inventario Azure DevOps Graph

Stesso discorso, ma lato Graph: qui trovi origin e descriptor, cioè i due campi che ti dicono se un’identità è collegata bene a Entra ID oppure no.

$GraphUsersUri = "https://vssps.dev.azure.com/$Organization/_apis/graph/users?api-version=7.1-preview.1"

$GraphUsersResult = Invoke-RestMethod `
    -Uri $GraphUsersUri `
    -Headers $Headers `
    -Method Get

$GraphUsers = $GraphUsersResult.value

$GraphUsers |
    Select-Object `
        displayName,
        principalName,
        origin,
        originId,
        descriptor |
    Sort-Object displayName |
    Format-Table -AutoSize

Dal risultato della tabella che ti comparirà a video, otterrai una matrice esplicita vecchio/nuovo utente:

Vecchia identità                                    Nuova identità
-------------------------------------------------   ------------------------------
a.rossi-cutover@oldtenant.onmicrosoft.com           andrea.rossi@example.com
m.bianchi-cutover@oldtenant.onmicrosoft.com         marco.bianchi@example.com

Prima di rimuovere un account legacy (quindi appartenente al vecchio DevOps), devi sapere con certezza quale identità lo sostituisce. Sembra ovvio scritto così, ma è il punto dove è più facile fare confusione (e io mi sono fatto due giri con esportazione CSV giusto per non fare danni stupidi da distrazione).

Recuperare tutti i Work Item

Serve l’elenco completo degli ID: da qui in poi ogni controllo (Assigned To, revisioni, commenti) scandisce questa lista uno per uno.

$WiqlUri = "https://dev.azure.com/$Organization/${Project}/_apis/wit/wiql?api-version=7.1"

$WiqlBody = @{
    query = @"
SELECT [System.Id]
FROM WorkItems
WHERE [System.TeamProject] = '$Project'
ORDER BY [System.Id]
"@
} | ConvertTo-Json

$WiqlResult = Invoke-RestMethod `
    -Uri $WiqlUri `
    -Headers $Headers `
    -Method Post `
    -ContentType "application/json" `
    -Body $WiqlBody

$WorkItemIds = @($WiqlResult.workItems.id)

Write-Host "Work items found: $($WorkItemIds.Count)"

E una funzione di lettura riutilizzabile per i passaggi successivi:

function Get-AdoWorkItem {
    param(
        [Parameter(Mandatory)]
        [int]$Id
    )

    $Uri = "https://dev.azure.com/$Organization/${Project}/_apis/wit/workitems/${Id}?`$expand=fields&api-version=7.1"

    Invoke-RestMethod `
        -Uri $Uri `
        -Headers $Headers `
        -Method Get
}

Trovare gli Assigned To legacy

Scandisco ogni Work Item e tengo solo quelli ancora assegnati a uno dei vecchi UPN.

$LegacyUpns = @(
    "a.rossi-cutover@oldtenant.onmicrosoft.com",
    "m.bianchi-cutover@oldtenant.onmicrosoft.com"
)

$LegacyAssignments = foreach ($Id in $WorkItemIds) {

    $WorkItem = Get-AdoWorkItem -Id $Id
    $Assigned = $WorkItem.fields.'System.AssignedTo'

    if ($null -ne $Assigned) {

        $AssignedUpn = $Assigned.uniqueName

        if ($AssignedUpn -in $LegacyUpns) {
            [pscustomobject]@{
                Id          = $Id
                Title       = $WorkItem.fields.'System.Title'
                AssignedTo  = $Assigned.displayName
                AssignedUpn = $AssignedUpn
            }
        }
    }
}

$LegacyAssignments |
    Group-Object AssignedUpn |
    Select-Object Name,Count |
    Sort-Object Count -Descending |
    Format-Table -AutoSize

Rimappare gli Assigned To a mano

Con un array di UserMapping vado a dichiarare esplicitamente chi sostituisce chi, poi applico il mapping ai Work Item trovati nel passaggio precedente.

$UserMapping = @{
    "a.rossi-cutover@oldtenant.onmicrosoft.com" = "andrea.rossi@example.com"
    "m.bianchi-cutover@oldtenant.onmicrosoft.com" = "marco.bianchi@example.com"
}

Così:

function Set-AdoWorkItemAssignedTo {
    param(
        [Parameter(Mandatory)]
        [int]$Id,

        [Parameter(Mandatory)]
        [string]$NewAssignedTo
    )

    $Uri = "https://dev.azure.com/$Organization/${Project}/_apis/wit/workitems/${Id}?api-version=7.1"

    $Patch = @(
        @{
            op    = "replace"
            path  = "/fields/System.AssignedTo"
            value = $NewAssignedTo
        }
    ) | ConvertTo-Json

    Invoke-RestMethod `
        -Uri $Uri `
        -Headers $Headers `
        -Method Patch `
        -ContentType "application/json-patch+json" `
        -Body $Patch
}

E applicazione del mapping:

$Successful = 0
$Skipped    = 0
$Failed     = 0

foreach ($Assignment in $LegacyAssignments) {

    $OldUpn = $Assignment.AssignedUpn

    if (-not $UserMapping.ContainsKey($OldUpn)) {
        $Skipped++
        continue
    }

    $NewUpn = $UserMapping[$OldUpn]

    try {
        Set-AdoWorkItemAssignedTo `
            -Id $Assignment.Id `
            -NewAssignedTo $NewUpn

        $Successful++
    }
    catch {
        Write-Warning "Failed Work Item $($Assignment.Id): $($_.Exception.Message)"
        $Failed++
    }
}

Write-Host "Successful: $Successful"
Write-Host "Skipped:    $Skipped"
Write-Host "Failed:     $Failed"

Occhio a testare il mapping su un singolo Work Item prima, verificando il risultato dalla UI, e solo dopo lanciarlo su tutto il resto.
Su una migrazione di identità non è il campo dove vuoi scoprire un errore di mapping dopo averlo già applicato a 300 elementi. Meglio un’operazione “ripetuta almeno un paio di volte” che testare il brivido sull’intero contenitore, rifatti un po’ ai consigli della nonna quando ti suggeriva di provare il nuovo detersivo su un lembo non visibile della maglia o della camicia

Verificare gli Assigned To

Stesso controllo di prima, ma dopo il mapping: serve a confermare che non sia rimasto nulla assegnato ai vecchi account.

$OldCurrentAssignments = foreach ($Id in $WorkItemIds) {

    $WorkItem = Get-AdoWorkItem -Id $Id
    $Assigned = $WorkItem.fields.'System.AssignedTo'

    if (
        $null -ne $Assigned -and
        $Assigned.uniqueName -in $LegacyUpns
    ) {
        [pscustomobject]@{
            Id          = $Id
            AssignedUpn = $Assigned.uniqueName
        }
    }
}

Write-Host "Old current assignments: $($OldCurrentAssignments.Count)"

Il risultato che vuoi vedere è:

Old current assignments: 0

Lo storico: cosa NON ho toccato

Durante l’audit sono saltati fuori riferimenti ai vecchi utenti anche in altri campi:

Microsoft.VSTS.Common.ActivatedBy
Microsoft.VSTS.Common.ClosedBy
System.AuthorizedAs
System.CreatedBy
System.ChangedBy

Qui la distinzione è tutto. System.AssignedTo è uno stato operativo corrente, il “chi lavora su questa cosa adesso”. CreatedBy, ChangedBy, ActivatedBy, ClosedBy e simili raccontano invece chi ha fatto davvero un’azione nel passato.

Riscriverli avrebbe voluto dire attribuire alle nuove identità operazioni compiute dai vecchi account, cioè falsificare la storia del progetto. Li ho lasciati esattamente dove stavano.

Audit delle revisioni

Stesso principio del punto precedente, ma applicato allo storico: qui non guardo lo stato attuale, guardo chi ha modificato cosa nel tempo.

$RevisionLegacyUsers = [System.Collections.Generic.List[object]]::new()

foreach ($Id in $WorkItemIds) {

    $Uri = "https://dev.azure.com/$Organization/${Project}/_apis/wit/workitems/${Id}/revisions?api-version=7.1"

    $Revisions = (Invoke-RestMethod `
        -Uri $Uri `
        -Headers $Headers `
        -Method Get).value

    foreach ($Revision in $Revisions) {

        $ChangedBy = $Revision.fields.'System.ChangedBy'

        if (
            $null -ne $ChangedBy -and
            $ChangedBy.uniqueName -in $LegacyUpns
        ) {
            $RevisionLegacyUsers.Add(
                [pscustomobject]@{
                    WorkItemId = $Id
                    Revision   = $Revision.rev
                    ChangedBy  = $ChangedBy.uniqueName
                }
            )
        }
    }
}

$RevisionLegacyUsers |
    Group-Object ChangedBy |
    Select-Object Count,Name |
    Sort-Object Count -Descending |
    Format-Table -AutoSize

Trovare risultati qui non è un errore: è semplicemente lo storico che fa il suo mestiere.

Audit degli autori dei commenti

Stesso identico controllo, stavolta sugli autori dei commenti ai Work Item.

$LegacyCommentAuthors = [System.Collections.Generic.List[object]]::new()

foreach ($Id in $WorkItemIds) {

    $Uri = "https://dev.azure.com/$Organization/${Project}/_apis/wit/workItems/${Id}/comments?api-version=7.1-preview.4"

    try {
        $Comments = (Invoke-RestMethod `
            -Uri $Uri `
            -Headers $Headers `
            -Method Get).comments
    }
    catch {
        continue
    }

    foreach ($Comment in $Comments) {

        $AuthorUpn = $Comment.createdBy.uniqueName

        if ($AuthorUpn -in $LegacyUpns) {
            $LegacyCommentAuthors.Add(
                [pscustomobject]@{
                    WorkItemId = $Id
                    CommentId  = $Comment.id
                    Author     = $AuthorUpn
                }
            )
        }
    }
}

$LegacyCommentAuthors |
    Group-Object Author |
    Select-Object Count,Name |
    Sort-Object Count -Descending |
    Format-Table -AutoSize

Anche questi, lasciati dove stavano.

Controllare le membership

Prima di cancellare qualsiasi account, voglio sapere a quali gruppi appartiene ogni utente: elenco prima i gruppi dell’organizzazione, poi le membership vere e proprie.

$GroupsUri = "https://vssps.dev.azure.com/$Organization/_apis/graph/groups?api-version=7.1-preview.1"

$Groups = (Invoke-RestMethod `
    -Uri $GroupsUri `
    -Headers $Headers `
    -Method Get).value

$Groups |
    Select-Object displayName,principalName,descriptor |
    Sort-Object displayName |
    Format-Table -AutoSize

Funzione per leggere le membership:

function Get-AdoMembership {
    param(
        [Parameter(Mandatory)]
        [string]$Descriptor
    )

    $EncodedDescriptor = [System.Uri]::EscapeDataString($Descriptor)

    $Uri = "https://vssps.dev.azure.com/$Organization/_apis/graph/memberships/${EncodedDescriptor}?direction=up&depth=1&api-version=7.1-preview.1"

    (Invoke-RestMethod `
        -Uri $Uri `
        -Headers $Headers `
        -Method Get).value
}

E il report vero e proprio:

foreach ($User in $GraphUsers) {

    $Memberships = Get-AdoMembership -Descriptor $User.descriptor

    foreach ($Membership in $Memberships) {

        $Group = $Groups |
            Where-Object descriptor -eq $Membership.containerDescriptor |
            Select-Object -First 1

        [pscustomobject]@{
            User  = $User.principalName
            Group = $Group.principalName
        }
    }
}

Questo controllo va fatto prima di eliminare gli account precedenti, non dopo. Azure DevOps usa membership transitive: un utente può avere permessi ricevuti dal team o dai gruppi padre, non solo da assegnazioni dirette, e se non lo controlli prima rischi di scoprirlo nel modo sbagliato.

Rimuovere gli utenti legacy

A questo punto isolo gli utenti legacy ancora presenti nell’organizzazione, prima di passare alla cancellazione vera e propria.

$LegacyOrgUsers = $OrgUsers |
    Where-Object {
        $_.user.principalName -in $LegacyUpns
    }

$LegacyOrgUsers |
    Select-Object `
        id,
        @{N="DisplayName";E={$_.user.displayName}},
        @{N="PrincipalName";E={$_.user.principalName}} |
    Format-Table -AutoSize

E la rimozione vera:

$Removed = 0
$Failed  = 0

foreach ($User in $LegacyOrgUsers) {

    $Uri = "https://vsaex.dev.azure.com/$Organization/_apis/userentitlements/$($User.id)?api-version=7.1"

    try {
        Invoke-RestMethod `
            -Uri $Uri `
            -Headers $Headers `
            -Method Delete

        Write-Host "Removed: $($User.user.principalName)"
        $Removed++
    }
    catch {
        Write-Warning "Failed: $($User.user.principalName)"
        Write-Warning $_.Exception.Message
        $Failed++
    }
}

Write-Host ""
Write-Host "Removed: $Removed"
Write-Host "Failed:  $Failed"

Anche qui: l’identificativo giusto è $User.id, non $User.user.id. Lo stesso dettaglio dell’inventario iniziale, e lo stesso punto dove è facile inciampare due volte.

Verifica finale degli utenti

Richiamo di nuovo l’inventario degli utenti per essere sicuro che i vecchi account non ci siano più.

$Entitlements = Invoke-RestMethod `
    -Uri $EntitlementsUri `
    -Headers $Headers `
    -Method Get

$OrgUsers = $Entitlements.items

$LegacyStillPresent = $OrgUsers |
    Where-Object {
        $_.user.principalName -in $LegacyUpns
    }

Write-Host "Users remaining: $($OrgUsers.Count)"
Write-Host "Legacy users still present: $($LegacyStillPresent.Count)"

Anche qui, il risultato voluto è secco:

Legacy users still present: 0

Esportazione finale, per avere una fotografia dello stato pulito:

$OrgUsers |
    Select-Object `
        @{N="DisplayName";E={$_.user.displayName}},
        @{N="PrincipalName";E={$_.user.principalName}},
        @{N="License";E={$_.accessLevel.accountLicenseType}} |
    Export-Csv `
        -Path ".\AzureDevOps-FinalUsers.csv" `
        -NoTypeInformation `
        -Encoding UTF8

Perché le vecchie identità possono restare in Graph

Dopo la rimozione dagli entitlement, alcune identità legacy possono continuare a comparire nelle risposte di Azure DevOps Graph. Da solo, questo non significa che abbiano ancora accesso: nel mio caso erano ancora referenziate da revisioni, commenti e campi storici come ChangedBy, CreatedBy e ClosedBy, esattamente quelli che avevo deciso di preservare.

Per questo ho usato gli User Entitlements per stabilire chi avesse davvero accesso corrente, mentre Graph è rimasto uno strumento per analizzare identità e riferimenti storici, non per decidere chi può ancora entrare.

Audit dei repository

Chiuso il fronte utenti, passo a un altro fronte: i repository Git dell’organizzazione.

$ReposUri = "https://dev.azure.com/$Organization/${Project}/_apis/git/repositories?api-version=7.1"

$Repos = (Invoke-RestMethod `
    -Uri $ReposUri `
    -Headers $Headers `
    -Method Get).value

$Repos |
    Select-Object id,name,defaultBranch,isDisabled |
    Sort-Object name |
    Format-Table -AutoSize

Write-Host "Repositories found: $($Repos.Count)"

Enumerare i branch

Per ogni repository elenco i branch: mi serve più avanti, quando incrocio i token delle ACL con i repository ancora esistenti.

$BranchReport = foreach ($Repo in $Repos) {

    $RefsUri = "https://dev.azure.com/$Organization/${Project}/_apis/git/repositories/$($Repo.id)/refs?filter=heads/&api-version=7.1"

    $Refs = (Invoke-RestMethod `
        -Uri $RefsUri `
        -Headers $Headers `
        -Method Get).value

    foreach ($Ref in $Refs) {

        $BranchName = ($Ref.name -replace '^refs/heads/', '')

        [pscustomobject]@{
            Repository = $Repo.name
            Branch     = $BranchName
            ObjectId   = $Ref.objectId
        }
    }
}

$BranchReport |
    Sort-Object Repository,Branch |
    Export-Csv `
        -Path ".\AzureDevOps-Branches.csv" `
        -NoTypeInformation `
        -Encoding UTF8

Verificare le branch policy

Controllo anche le policy sui branch, per essere sicuro che nessuna faccia ancora riferimento agli account legacy.

$PoliciesUri = "https://dev.azure.com/$Organization/${Project}/_apis/policy/configurations?api-version=7.1"

$Policies = (Invoke-RestMethod `
    -Uri $PoliciesUri `
    -Headers $Headers `
    -Method Get).value

Write-Host "Branch policies found: $($Policies.Count)"

Nel mio scenario non c’erano branch policy da migrare o correggere, ma il controllo va fatto comunque: è un minuto di script contro il rischio di scoprire dopo che una policy puntava a un account che non esiste più.

Audit delle ACL Git

Il namespace di sicurezza Git è fisso:

2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87

$GitNamespaceId = "2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87"

$ProjectGitToken = "repoV2/$ProjectId"
$EncodedProjectGitToken = [System.Uri]::EscapeDataString($ProjectGitToken)

$AclUri = "https://dev.azure.com/$Organization/_apis/accesscontrollists/${GitNamespaceId}?token=$EncodedProjectGitToken&recurse=true&includeExtendedInfo=true&api-version=7.1"

$GitAclResult = Invoke-RestMethod `
    -Uri $AclUri `
    -Headers $Headers `
    -Method Get

Estrazione delle ACE:

$AclDescriptors = foreach ($Acl in $GitAclResult.value) {

    foreach ($Property in $Acl.acesDictionary.PSObject.Properties) {

        [pscustomobject]@{
            Token      = $Acl.token
            Descriptor = $Property.Name
            Allow      = $Property.Value.allow
            Deny       = $Property.Value.deny
        }
    }
}

$AclDescriptors |
    Format-Table Token,Descriptor,Allow,Deny -AutoSize

I descriptor delle ACL non sono quelli di Graph

Nelle ACL Git ho trovato descriptor di questo tipo:

Microsoft.TeamFoundation.Identity;S-1-9-...

mentre Graph usa valori come:

aad....
bnd....
vssgp....

Non sono confrontabili direttamente, e la prima volta che li vedi affiancati viene da pensare di aver sbagliato qualcosa. Prima estrai i descriptor relativi alle identity:

$IdentityDescriptors = $AclDescriptors |
    Where-Object {
        $_.Descriptor -like "Microsoft.TeamFoundation.Identity;*"
    } |
    Select-Object -ExpandProperty Descriptor -Unique

Poi li risolvi tramite l’API Identities:

$ResolvedIdentities = [System.Collections.Generic.List[object]]::new()

$BatchSize = 20

for (
    $Offset = 0;
    $Offset -lt $IdentityDescriptors.Count;
    $Offset += $BatchSize
) {

    $LastIndex = [Math]::Min(
        $Offset + $BatchSize - 1,
        $IdentityDescriptors.Count - 1
    )

    $Batch = @(
        $IdentityDescriptors[$Offset..$LastIndex]
    )

    $DescriptorList = $Batch -join ","

    $EncodedDescriptors = [System.Uri]::EscapeDataString(
        $DescriptorList
    )

    $Uri = "https://vssps.dev.azure.com/$Organization/_apis/identities?descriptors=$EncodedDescriptors&queryMembership=None&api-version=7.1"

    $Result = Invoke-RestMethod `
        -Uri $Uri `
        -Headers $Headers `
        -Method Get

    foreach ($Identity in $Result.value) {

        $ResolvedIdentities.Add(
            [pscustomobject]@{
                Descriptor          = $Identity.descriptor
                ProviderDisplayName = $Identity.providerDisplayName
                SubjectDescriptor   = $Identity.subjectDescriptor
                IsActive            = $Identity.isActive
                IsContainer         = $Identity.isContainer
                Id                  = $Identity.id
            }
        )
    }
}

$ResolvedIdentities |
    Sort-Object ProviderDisplayName |
    Format-Table `
        ProviderDisplayName,
        IsActive,
        IsContainer,
        SubjectDescriptor `
        -AutoSize

Nel mio caso le ACL Git facevano riferimento solo a gruppi Azure DevOps, tra cui:

[Organization]\Project Collection Administrators
[Organization]\Project Collection Build Service Accounts
[Organization]\Project Collection Service Accounts
[Project]\Build Administrators
[Project]\Contributors
[Project]\Project Administrators
[Project]\Readers

Nessuna ACE Git esplicitamente intestata ai vecchi utenti. Bene così.

ACL legate a repository che non esistono più

Ultimo giro: confrontare i token ACL con i repository correnti, per beccare eventuali residui orfani.

$CurrentRepoIds = @(
    $Repos.id |
        ForEach-Object {
            $_.ToString().ToLowerInvariant()
        }
)

$RepositoryAclReport = foreach ($Acl in $GitAclResult.value) {

    if ($Acl.token -match '^repoV2/[^/]+/([^/]+)$') {

        $RepoId = $Matches[1].ToLowerInvariant()

        $Repo = $Repos |
            Where-Object {
                $_.id.ToString().ToLowerInvariant() -eq $RepoId
            } |
            Select-Object -First 1

        [pscustomobject]@{
            RepositoryId = $RepoId
            Repository   = $Repo.name
            Exists       = [bool]$Repo
            Token        = $Acl.token
        }
    }
}

$RepositoryAclReport |
    Where-Object Exists -eq $false |
    Format-Table RepositoryId,Repository,Exists,Token -AutoSize

Nel mio ambiente è rimasto un token ACL relativo a un repository non più esistente. Non l’ho considerato un blocco per la migrazione delle identità, visto che le sue ACE non contenevano riferimenti agli utenti legacy: resta housekeeping da fare a parte, non un problema di identità.

Checklist finale

A fine giro, ecco il riepilogo secco di tutto quello controllato:

[OK] Directory Azure DevOps collegata al nuovo tenant
[OK] Nuove identità presenti
[OK] Mapping vecchio -> nuovo verificato
[OK] AssignedTo legacy = 0
[OK] Membership delle nuove identità verificate
[OK] Utenti legacy attivi nell'organizzazione = 0
[OK] Revisioni storiche preservate
[OK] Autori storici dei commenti preservati
[OK] Repository correnti verificati
[OK] Branch verificati
[OK] Branch policy verificate
[OK] ACL Git verificate
[OK] ACE Git esplicite associate a utenti legacy = 0

Solo a questo punto ho considerato davvero conclusa la migrazione delle identità.

In conclusione

La cosa più importante che mi porto a casa da questa storia è che cambiare la directory di Azure DevOps e rimappare gli utenti non sono la stessa cosa, anche se Microsoft te la vende un po’ come se lo fossero. Nel mio caso lo switch del tenant è riuscito, ma il remapping automatico ha lasciato alcune identità a metà strada. E cercare di cancellare ogni traccia delle vecchie identità sarebbe stato un errore uguale e contrario: la distinzione che conta davvero è tra stato operativo corrente e storico del progetto.

Gli utenti legacy non devono più avere accesso, membership o assegnazioni attive. Ma devono poter continuare a comparire come autori di una modifica fatta in passato, di un commento, della chiusura di un Work Item: quella è storia, non uno stato da “correggere“.

Il risultato giusto non è “Azure DevOps non conosce più le vecchie identità“, è piuttosto: le vecchie identità non hanno più alcun ruolo operativo, ma Azure DevOps conserva correttamente ciò che hanno fatto. Ed è questa, nel mio caso, la verifica che mi ha permesso di dire davvero conclusa la migrazione.

L’area commenti è a tua disposizione se ti sei trovato in uno scenario simile o se hai un pezzo di script da confrontare. Ma anche per riprenderti dalla depressione che ti è venuta se hai letto fino a qui: il caffè lo offro io. Alcuni dei passaggi qui sopra li ho dovuti studiare (e in alcuni casi farmeli pure spiegare meglio dal povero agente AI di turno) perché mi erano totalmente sfuggiti, non c’è peccato nell’ammettere dei limiti, era la prima volta che mi ritrovavo in una situazione simile.

#KeepItSimple

Immagine di copertina: Rui Silvestre on Unsplash

Azure DevOps e il cambio di tenant Entra ID: quando il remapping automatico non basta è stato scritto da Gioxx per Gioxx.org.

Dimmi se la casella esiste

Il confronto viene quindi molto semplice: esiste la casella di posta elettronica? Se la risposta è no, allora molto probabilmente ho un account di Dropbox ancora attivo sul tenant, che consuma inutilmente un posto a sedere (e mi fa spendere i soldi per la licenza), e che va perciò cessato. Data una lista di indirizzi di posta elettronica (classico file CSV a singola colonna, con intestazione account, giusto per fare un esempio che mi fa da base per questo articolo), lo script di PowerShell non è poi così complicato:

$ProgressPreference = 'Continue'
$ConfirmPreference = 'None'

Import-Csv .\check_utenti.csv | % {
    $email = $_.account.Trim()

    Write-Progress -Activity "Loading" -Status $email

    try {
        $destinatario = Get-Recipient `
            -Identity $email `
            -ErrorAction Stop `
            -WarningAction SilentlyContinue

        Write-Progress -Activity "Loading" -Status $destinatario.DisplayName
    }
    catch {
        [PSCustomObject]@{
            Email  = $email
            Esiste = $false
            Errore = $_.Exception.Message
        }
    }
}

Prendo l’account, per sicurezza tolgo eventuali spazi vuoti, poi riporto a video l’avanzamento (giusto per non far pensare che lo script sia rimasto inchiodato lì in attesa del nulla cosmico) e inizio a popolare un oggetto che alla fine presenterò agli occhi dell’utilizzatore, a tre colonne, riportando indirizzo e-mail analizzato, se esiste (ovviamente questa condizione sarà sempre falsa) e l’errore riscontrato sul tenant Microsoft (banalmente dovresti sempre ottenere il messaggio per casella di posta elettronica non trovata).

Nulla di più semplice, ma che ha risolto l’esigenza spicciola di non dover stare lì a confrontare centinaia di indirizzi di posta elettronica che avevo in pancia al tenant di Dropbox.

Domande? Dubbi? Tu l’avresti fatta meglio con cinquemila lire? Ne sono convinto (non fosse anche solo per le due colonne “potenzialmente inutili” riguardo la condizione di inesistenza e l’errore riscontrato sul tenant Microsoft). L’area commenti è al solito posto, usala!

Se sei proprio pignolo e vuoi sapere perché ho mantenuto quelle due colonne, è perché all’inizio avevo usato uno script un po’ più verboso:

$ProgressPreference = 'Continue'
$ConfirmPreference = 'None'

$righe = Import-Csv .\check_utenti.csv

$risultati = foreach ($riga in $righe){
    $email = $riga.account.Trim()

    Write-Progress -Activity "Loading" -Status $email

    try {
        $destinatario = Get-Recipient `
            -Identity $email `
            -ErrorAction Stop `
            -WarningAction SilentlyContinue

        [PSCustomObject]@{
            Email       = $email
            Esiste      = $true
            DisplayName = $destinatario.DisplayName
            Tipo        = $destinatario.RecipientTypeDetails
            Errore      = $null
        }

        Write-Progress -Activity "Loading" -Status $destinatario.DisplayName
    }
    catch {
        [PSCustomObject]@{
            Email       = $email
            Esiste      = $false
            DisplayName = $null
            Tipo        = $null
            Errore      = $_.Exception.Message
        }
    }
}

Write-Progress `
    -Activity "Verifica destinatari Exchange" `
    -Completed

$risultati | Format-Table -AutoSize

Ne hai davvero bisogno? No, a meno che non ti serva una situazione davvero completa e non solo gli account da ripulire.

#KeepItSimple

Immagine di copertina Mimi Thian on Unsplash

PowerShell: verificare l’esistenza di una serie di indirizzi di posta è stato scritto da Gioxx per Gioxx.org.

Sarà stata la stanchezza, sarà che quella sera ero semplicemente poco lucido, fatto sta che ho tirato in piedi un tunnel di test con cui giocare e rompere cose in santa pace.
Peccato che poi, volendo sperimentare sul serio, ho dato a DockFlare la conferma per prendere possesso del tunnel principale, quello che tiene in piedi buona parte dei servizi di casa. Quello che non avevo capito è che nell’intervallo di tempo tra il mio clic e l’esecuzione dell’operazione avrei perso tutte le configurazioni, dalla prima all’ultima, nessuna route sopravvissuta, vuoto pneumatico.

Sia chiaro: non è colpa di DockFlare, la conferma l’ho data io e la distrazione era tutta mia. Però intanto ho buttato giù il monitor del Mac, ho imprecato quanto serviva e ho rimandato tutto al giorno dopo. Ricostruire era fattibile, ma significava buttare via un mucchio di tempo. Quando l’ho fatto, ho anche provato a salvarmi la configurazione da qualche parte, un export da poter reimportare velocemente in caso di nuovo disastro, e non ho trovato niente che facesse al caso mio.

Il nome

In quella chat che alimentiamo a pane, cazzate e lamentele ogni giorno si stava parlando di India, di supporto, di call center e di non ricordo neanche più cos’altro. E a me era pure venuta fame senza apparente motivo. È in quel contesto, mentre con l’aiuto di Claude Code mettevo in piedi le prime righe di questo progetto, che ho scelto un nome provvisorio: Tikka Masala. Mi fa sorridere ancora oggi, il provvisorio è diventato definitivo, e il software esiste per rimediare a una mia disattenzione: ne ho avuto bisogno in prima persona e l’ho reso pubblico nella speranza che eviti ad altri la stessa situazione (o per lo meno l’idea è quella di provarci, stile raccomandazione della nonna su cosa devi fare per non prendere freddo).

Cosa fa

Il sottotitolo che ho scelto per il progetto è “backup and restore Cloudflare Tunnels, without the spreadsheet”, e riassume abbastanza bene le intenzioni.

Gli dai un API token di Cloudflare, lui verifica che sia valido, ti elenca i tunnel che vede sull’account e ti permette di salvarne uno snapshot: un file JSON con la configurazione del tunnel così come la restituiscono gli endpoint di configurazione dei Cloudflare Tunnel (regole di ingress, hostname pubblici), più i metadati che servono a ritrovarla (data dell’export, account, ID e nome del tunnel, eventuali note). I metadati e lo storico stanno in un piccolo database SQLite, gli snapshot veri e propri sono file su disco.

Il perimetro è quello e solo quello: la configurazione dei tunnel. Non tocca le impostazioni Cloudflare a livello di account, e non salva – al momento – Access (Applications e Policies), per cui trovi solo delle scorciatoie che ti portano dritto alla sezione giusta della dashboard. Quando serve, gli chiedi di ripristinare: prende lo snapshot e sovrascrive la configurazione remota del tunnel con quella salvata. Puoi rimetterla sul tunnel di origine, su un altro tunnel o su un altro account, e ogni ripristino resta tracciato nello storico (quando, su quale account, su quale tunnel).

I backup li fai partire a mano oppure li lasci a uno scheduler interno (con cron e possibilità di scegliere il fuso orario). Qui la parte che uso di più: per ogni tunnel scegli una frequenza, a ogni esecuzione, una volta a settimana o una volta al mese, e decidi se coprirli tutti o solo un sottoinsieme. Nel mio caso i tunnel che tocco spesso girano a ogni ciclo, quelli fermi da mesi si accontentano del giro mensile. C’è una retention (BACKUP_RETENTION_DAYS, io la tengo a 90 giorni) che dopo ogni nuovo backup fa piazza pulita di quelli più vecchi della soglia, snapshot e relativo storico compresi.

Occhio a una cosa sui permessi del token: per far girare anche i ripristini, Tikka Masala avrà necessità del permesso Cloudflare Tunnel in scrittura (più DNS sulla zona), ma se ti interessa solo il backup puoi tenerlo al guinzaglio e sola lettura. Il token viene cifrato, non resta in chiaro sul disco.

Sotto il cofano è un’applicazione FastAPI in Python, niente di esotico, con un sistema di notifiche via webhook o Telegram per farti sapere quando un backup o un ripristino va storto. L’ho rilasciato pronto per Docker (immagine gfsolone/tikkamasala su Docker Hub o in alternativa ghcr.io/gioxx/tikkamasala via GitHub, con un docker-compose di esempio disponibile sul repository): lo metti in piedi accanto agli altri servizi di casa, lo configuri la prima volta e te ne dimentichi (sempre però rispettando la regola che uno strumento di backup è definibile funzionante solo quando sei in grado di ripristinare senza il minimo errore, quindi provalo prima di metterti comodo sul tuo cuscino).

I numeri, i miei

Lo uso da marzo, senza interruzioni, e nel frattempo siamo arrivati alla versione 1.3.8.
A oggi che scrivo queste righe la mia installazione personale mi restituisce questa situazione:

Unique tunnels     5
Routes archived    5095
Restores           12
Scheduled runs     170
Oldest backup      2026-05-31T03:00:04+00:00
Latest backup      2026-08-29T03:00:04+00:00

Archive retention  90 day(s)
Backups kept       127
Backup storage     1.1 MB
Database size      112.0 KB

Cinque tunnel sotto controllo, 170 cicli di backup programmati, poco più di un mega di spazio occupato per mesi di storico e un database che sta in 112 KB. Il campo dei ripristini segna dodici ma si tratta dei miei test che ogni tanto lancio a tradimento, per fortuna non ho più dovuto usarlo per davvero (anche se i test hanno comunque sovrascritto tunnel di produzione), è il motivo per cui oggi mi fido a lasciarlo lì a lavorare da solo.

Dovrei prevedere anche delle conservazioni più a lungo termine (mensili, annuali), ma è una caratteristica che non è ancora disponibile, mi sono già promesso di tornarci sopra e lavorarci.

In conclusione

È un software piccolo e per certi versi banale, ma per come lavoro io è ormai fondamentale.
Non fa niente di spettacolare: è un’assicurazione contro la tua stessa distrazione.

Trovi tutto su tikkamasala.gioxx.org e sul repo github.com/gioxx/TikkaMasala. Se lo provi, se ci trovi un bug o se hai idee per migliorarlo, le Issue su GitHub sono il canale più rapido per arrivare a me. Per tutto il resto, l’area commenti qui sotto è a tua disposizione, come sempre.

#KeepItSimple

Immagine di copertina: mia, prodotta con l’aiuto dell’intelligenza artificiale che ha lavorato allo sfondo che c’è alle spalle del logo ufficiale di Cloudflare.

Tikka Masala: metti al sicuro i tuoi tunnel Cloudflare è stato scritto da Gioxx per Gioxx.org.

Spoiler: nessun attacco.
Ma per arrivarci mi è servita un’oretta di log, e la spiegazione è abbastanza istruttiva da meritare un post, soprattutto se anche tu tieni attivo, come me, un plugin che avevi installato e dimenticato lì.

La caccia all’intruso che non c’era

Prima cosa, accesso SSH all’hosting e giù dentro i log di Apache.
Cosa cercavo: richieste alla API di YOURLS (yourls-api.php), POST all’area admin/, qualunque cosa somigliasse a una cancellazione pilotata da fuori.

Niente. Zero chiamate alla API in tutto il log. Un solo POST all’admin nella giornata: il mio, fatto dopo aver ricevuto l’allarme per andare a controllare. Il filesystem era pulito: nessuna webshell, nessun file PHP modificato di recente, ~/.ssh/authorized_keys vuoto, nessun utente aggiunto all’array degli amministratori in config.php. Eppure i link sparivano davvero: me lo confermava il database, le righe non c’erano più, le notifiche ricevute dal mio Change Notifier erano la conferma ultima a mezzo posta elettronica (maledettamente comodo, diversamente non me ne sarei accorto per tempo e chissà quanti altri link avrei lasciato per la strada).

Un’azione che tocca il database di YOURLS ma non lascia traccia nei log web è il tipo di contraddizione che di solito significa che stai guardando nel posto sbagliato.

L’indizio era nella mia stessa mail

Come ti dicevo poco sopra, quelle notifiche me le manda un plugin che ho scritto io, YOURLS-ChangeNotifier: invia una mail a ogni creazione, modifica o cancellazione di uno short URL. Dando un’occhiata più approfondita al corpo del messaggio di uno dei messaggi di cancellazione, saltava fuori questo:

Event:   DELETE
When:    2026-08-29T08:26:27+00:00
By:      user: (authenticated)
IP:      34.10.46.191

Due dettagli che prima avevo letto di sfuggita. Il campo By: diceva user: (authenticated) senza nome utente: è l’ultima spiaggia del mio plugin, quello che scrive quando yourls_is_valid_user() dice “sì” ma non riesce a tirare fuori né un login, né un cookie di sessione, né un header di autenticazione. Tradotto: nessun accesso vero all’area riservata.

E l’IP: cambiava a ogni mail. In un caso era quello di un monitor esterno che mi passa a controllare i redirect ogni mattina alla stessa ora.
Non un attaccante: solo chi, per caso, stava visitando quel link nel momento esatto della cancellazione.

Il che restringeva parecchio il campo: qualcosa dentro YOURLS cancellava i link quando venivano visitati.

Il colpevole: un plugin antispam del 2012

user/plugins/antispam/. Il plugin Anti spam di Ozh, uno dei più vecchi dell’ecosistema YOURLS. Attivo da anni sulla mia istanza, mai toccato, completamente uscito dai radar. Fa due cose. Alla creazione di uno short URL controlla la destinazione contro alcune DNS blacklist e rifiuta se è elencata: legittimo. Ma poi c’è la seconda parte, agganciata all’evento redirect_shorturl, cioè eseguita a ogni click:

// Has the remote link become compromised lately? Check on redirection
yourls_add_action( 'redirect_shorturl', 'ozh_yourls_antispam_check_redirect' );
function ozh_yourls_antispam_check_redirect( $url, $keyword = false ) {
    // ...
    if( $chances == mt_rand( 1, $chances ) ) {
        if( ozh_yourls_antispam_is_blacklisted( $url ) != false ) {
            // Delete link & die
            yourls_delete_link_by_keyword( $keyword );
            yourls_die( 'This domain has been blacklisted. This short URL has been deleted from our record.', 'Domain blacklisted', '403' );
        }
    }
}

Con probabilità 1 su 5 (link creato da meno di tre giorni) o 1 su 15, a ogni visita interroga la URL di destinazione contro cinque blacklist:

'zen.spamhaus.org',
'multi.surbl.org',
'bl.spamcop.net',
'combined.abuse.ch',
'dnsbl.sorbs.net',

Se una sola risponde positivo, il link non viene sospeso, non finisce in quarantena, non ti manda un avviso: yourls_delete_link_by_keyword(). Cancellato.
E l’utente si becca un 403, quella pagina da 866 byte che nel frattempo avevo visto passare decine di volte nei log senza dargli peso.

Perché proprio adesso

Perché quelle blacklist, nel 2026, sono in buona parte inaffidabili se non le usi nel modo giusto:

• SORBS (dnsbl.sorbs.net) è stata spenta a giugno 2024. La zona DNS non è garantito che risponda in modo sensato.
• SpamCop e SURBL degradano di proposito le risposte quando le query arrivano da resolver pubblici o ad alto volume, cioè esattamente lo scenario di un hosting condiviso, dove il resolver è in comune con centinaia di altri account.

Il risultato è falsi positivi a raffica. Il readme del plugin, va detto, non nasconde niente:

Checking against DNS blacklists may or may not work for you […] It may even result in all domains being blacklisted from your server. Try and see.

L’ho provato: ha deciso che Reddit, Amazon, un blog tecnico di Microsoft e il mio canale Twitch erano tutti “domini blacklistati”, e li ha rimossi.

Il fix

Disattivazione del plugin: rimosso da active_plugins nel database e cartella rinominata in .antispam.disabled, solo per scrupolo, giuro che poi dopo passo pure a cancellare definitivamente.
Da quel momento nessun link è stato più toccato.

Se anche tu tieni attivo questo plugin, il consiglio è di andare a vedere subito se ti sta erodendo lo storico: cerca i 403 anomali nei log e le eventuali mail di cancellazione. Come protezione antispam ci sono alternative che almeno non distruggono dati: Google Safe Browsing per YOURLS (ma occhio, che pure questo è stato archiviato e non viene più aggiornato da quattro anni), o più banalmente un captcha sull’interfaccia pubblica. Io sto seriamente pensando di mettermi alla ricerca di un sostituto mantenuto ancora oggi o – in alternativa – tirare in piedi qualcosa di nuovo che svolga però questo vecchio mestiere.

Il recupero: le statistiche erano ancora tutte lì

Qui la notizia buona.
Quando YOURLS cancella uno short URL rimuove la riga dalla tabella yourls_url, ma non tocca yourls_log, dove vive lo storico dei click.
Le statistiche c’erano ancora tutte, riga per riga, per ognuno dei link cancellati.

Ho recuperato destinazione, titolo e data di creazione dal dump notturno del database (Server Plan ne tiene uno automatico e non mi costringe così ad andare a recuperare il backup che mi porto in casa con cPanelVault), ho reinserito le righe con un INSERT mirato e ho rimesso i contatori clicks allineandoli al conteggio reale dei record ancora presenti nel log.

Verifica finale con un curl per keyword, per controllare che ogni redirect puntasse di nuovo dove doveva:

/r        301 -> https://www.reddit.com/r/Gioxx/
/shopping 301 -> https://www.amazon.it/shop/gioxx
/ee4li    301 -> https://techcommunity.microsoft.com/.../ba-p/3851357
/twitch   301 -> https://www.twitch.tv/gioxx85

Come se non fosse successo niente, con un’unica eccezione: twitch era stato cancellato prima che partisse il backup della notte, quindi la sua destinazione non era in nessun archivio e ho dovuto ricostruirla a memoria (non che fosse così complicato, ma è giusto dirlo, altrimenti mi sarebbe andato a tirare fuori dall’armadio il backup di qualche giorno fa).

In conclusione

Il giudizio è netto: per come è scritto, cancellazione automatica e irreversibile al primo hit di una qualunque blacklist, per giunta durante il redirect, cioè nel percorso più caldo e meno sorvegliato, questo plugin non ha senso su un’installazione viva e usata nel 2026, e ancora meno su hosting condiviso. Il controllo in fase di creazione è un’altra storia e ci può stare; è l’azione distruttiva a runtime il problema.

Due cose che mi porto a casa.

• La prima: le notifiche via mail su creazione/modifica/cancellazione degli short URL, che tenevo più che altro per curiosità, si sono rivelate l’unico motivo per cui me ne sono accorto in tempo. Se hai un sistema di alert simile, quelle mail vanno lette quando arrivano, non archiviate.
• La seconda: tenere YOURLS aggiornato all’ultima versione (oggi la 1.10.5) resta buona regola a prescindere, il mio YOURLS-diff serve proprio a rendere la cosa meno noiosa, anche se stavolta la versione non c’entrava niente (ma per coincidenza, essendo stata pubblicata una manciata di ore prima rispetto all’accaduto, mi ha fatto sorgere il dubbio di uno 0-day corretto che però mieteva vittime into the wild).

L’area commenti è a tua disposizione, soprattutto se ti è capitato di ritrovarti con dei link spariti e non sapevi da dove partire

#KeepItSimple

Immagine di copertina: Mick Haupt on Unsplash

YOURLS: il plugin antispam che cancellava i miei short URL è stato scritto da Gioxx per Gioxx.org.

Ho quindi fatto qualche ricerca per capire cosa offrisse il mercato del self-hosting, evitando però di tenere in considerazione l’idea e possibilità di ospitare il tutto in casa. Avevo bisogno di qualcosa che si integrasse con il mondo serverless.

Prima scelta: Cusdis (e doccia fredda)

Il primo nome che mi era saltato all’occhio era Cusdis, presentato proprio come “alternativa leggera e privacy-friendly a Disqus”. Sulla carta perfetto: piccolo, self-hostabile, pensato apposta per blog e siti statici.

Poi sono andato a controllare il repository su GitHub, per abitudine, prima di adottare qualsiasi cosa guardo sempre lo stato di manutenzione, e djyde/cusdis risulta archiviato. Un progetto che ha avuto il suo pubblico, ma da metà luglio 2026 non riceve più commit e la repository è chiusa in sola lettura. Nessun annuncio ufficiale che spieghi il perché, semplicemente: fine corsa.

Occhio, non sto dicendo che sia stata una scelta sbagliata a monte, magari l’autore ha semplicemente deciso di chiudere un capitolo, succede. Ma per un progetto pubblico che è sempre esposto su Internet, e che deve restare in piedi per anni e magari ricevere patch di sicurezza, adottare qualcosa di già archiviato il primo giorno sarebbe stato un rischio che non valeva la pena correre.

Waline

Incrociando ulteriori ricerche sono arrivato a Waline, altro sistema di commenti self-hosted, e la differenza si vede subito: repository attiva (commit praticamente ogni giorno), community viva e un set di feature parecchio più ricco rispetto al necessario: supporto Markdown nei commenti, notifiche via email/Telegram/Discord/WeChat e altri canali ancora, pannello di amministrazione integrato, supporto per un bel po’ di database (Postgres, MySQL, SQLite, MongoDB …).

Deploy semplice, tra l’altro: il pacchetto @waline/vercel lo rende pronto per girare come funzione serverless su Vercel, con Neon come Postgres gestito dietro. Repository dedicata (ne ho messa in piedi una sul mio account personale), un index.cjs di poche righe che carica Waline, un vercel.json per i build, e in pochi minuti hai un endpoint di commenti collegato al frontend Docusaurus della KB.

Se vuoi provarlo, ti consiglio di iniziare da qui: waline.js.org/it/guide/get-started.

Le personalizzazioni

Che poi è il classico vaso di pandora rispetto al “set & forget”, quel frangente dello spazio-tempo dove la teoria del “lo metto in piedi in 5 minuti” incontra la pratica di un progetto vero e con alcuni ritocchi sotto al cofano praticamente necessari.

Favicon statiche, per silenziare i log

Prima cosa: ogni browser richiede automaticamente /favicon.ico e /favicon.png quando apre il sito. Waline, non avendoli, li trattava come richieste non gestite e ogni volta finiva un NotFoundError nei log di produzione. Innocuo, ma fastidioso da leggere quando stai cercando altro nei log. Basta aggiungere due file statici e dire a Vercel di servirli direttamente, senza passare dalla funzione Node:

{
  "builds": [
    { "src": "favicon.ico", "use": "@vercel/static" },
    { "src": "favicon.png", "use": "@vercel/static" }
  ],
  "rewrites": [
    { "source": "/((?!favicon\\.ico$|favicon\\.png$).*)", "destination": "index.cjs" }
  ]
}

Le notifiche Telegram (e il template che non ne voleva sapere)

Questa è stata quella più tosta. Volevo essere avvisato su Telegram ogni volta che arriva un commento in attesa di moderazione, così non devo tenere aperta la dashboard tutto il giorno. Waline lo supporta nativamente: bastano tre variabili d’ambiente su Vercel (TG_BOT_TOKEN, TG_CHAT_ID, ed eventualmente un TG_TEMPLATE per personalizzare il messaggio).

Peccato che, appena personalizzato il template, la notifica smettesse di arrivare, e senza errori evidenti. Ci ho girato attorno un bel po’: token giusto (verificato a mano con una chiamata curl diretta all’API di Telegram), chat ID giusto, tutto giusto, eppure niente.
Alla fine, spulciando i log runtime di Vercel riga per riga, è saltato fuori il vero colpevole:

Telegram Notification Failed:{"ok":false,"error_code":400,"description":"Bad Request: can't parse entities: Character '.' is reserved and must be escaped with the preceding '\\'"}

Telegram, quando usi il parse_mode: MarkdownV2, pretende che caratteri come . - _ * [ ] ( ) ~ # + = | { } ! vengano “escapati” ovunque compaiano fuori da un blocco di codice o dalla parte URL di un link. Il mio template ci infilava l’URL del post e il nome del sito in punti non protetti, e ogni dominio ha un punto, ogni tanto un trattino: bastava questo per far cadere l’intero messaggio.

Ho provato a correggere il template più volte, ma affidarsi a un campo di testo multiriga su un pannello web per gestire un fence di codice ``` si è rivelato fragile: a ogni copia/incolla qualcosa andava storto tra a-capo reali e letterali. Alla fine ho spostato tutto nel codice: index.cjs costruisce il messaggio da sé, con una funzione di escaping scritta in JavaScript, e lo invia solo per i commenti con stato “in attesa di moderazione”, esattamente il caso che mi interessava:

function escapeMarkdownV2(text = '') {
  return String(text).replace(/[_*[\]()~`>#+=|{}.!\\-]/g, '\\$&');
}

module.exports = Application({
  plugins: [],
  async postSave(comment) {
    if (comment.status !== 'waiting') return;
    // costruzione messaggio + fetch verso l'API Telegram
  },
});

Per evitare la doppia notifica (quella integrata di Waline più la mia), ho disattivato la prima con DISABLE_AUTHOR_NOTIFY=true, lasciando intatte le email di risposta a chi commenta, che passano da un altro percorso.

Versione bloccata e Dependabot

Ultima rifinitura, più che altro una lezione imparata sul momento: il package.json puntava @waline/vercel sulla versione più aggiornata (latest), comodo perché a ogni deploy scarichi automaticamente l’ultima versione, ma anche un rischio silenzioso, un aggiornamento con un comportamento diverso può arrivare in produzione senza che tu lo sappia. Ho quindi scelto di utilizzare una versione precisa di Waline e ho aggiunto un dependabot.yml che apre una pull request quando viene pubblicata una nuova versione, così l’aggiornamento resta una scelta, non un evento a sorpresa.

In conclusione

La lezione più generale, al di là di Waline in sé: prima di adottare qualcosa, anche uno strumento piccolo come un sistema di commenti, vale sempre la pena guardare lo stato reale del progetto. Un repository archiviato oggi potrebbe risorgere domani con un fork, ma nel dubbio meglio partire da qualcosa di vivo. E il self-hosting, anche via serverless, resta assolutamente sostenibile, basta mettere in conto che i primi giorni si passano più a leggere log che a scrivere codice.

Se vuoi vedere il risultato, la sezione commenti la trovi in fondo a qualsiasi post della KB di Marvellous Codeworks.
Se invece ti va di parlarne o dirmi a che software ti sei affidato tu per gestire commenti su un sito web statico, l’area commenti è a tua disposizione anche qui di seguito, come sempre :-)

#KeepItSimple

Immagine di copertina: Thought Catalog on Unsplash

Waline: un sistema di commenti adatto a Docusaurus è stato scritto da Gioxx per Gioxx.org.

Sia chiaro: so benissimo che è una scelta by-design, la pulizia dei vecchi moduli è a tuo carico, la maggior parte delle volte puoi “ignorarla“. Con Microsoft.Graph il problema è però amplificato dal fatto che non stiamo parlando di un modulo singolo, ma di una quarantina di sub-moduli (Microsoft.Graph.Users, Microsoft.Graph.Groups, Microsoft.Graph.Applications e così via). Se aggiorni e basta, ti ritrovi con due, tre, a volte più versioni della stessa libreria installate in parallelo su C:\Program Files\PowerShell\Modules (o nella tua cartella personale dei PowerShell Modules). Bello per chi ama fare ordine, pessimo per chi deve gestire ambienti di produzione dove ogni versione fantasma è un potenziale problema da capire poi, magari alle 2 di notte durante un incident.

Il problema in pratica

Dopo un aggiornamento mi ritrovo tipicamente così: nuova versione installata, ma la precedente ancora lì, con tutti i suoi sub-moduli:

PS> Update-Module Microsoft.graph -Scope AllUsers
PS> Get-Module Microsoft.Graph* -ListAvailable |
>> Where-Object Version -ne '2.39.0' |
>> Select-Object Name, Version, Path

Name                                             Version Path
----                                             ------- ----
Microsoft.Graph                                 2.38.1  C:\Program Files\PowerShell\Modules\Microsoft.Graph\2.38.1\Mic…
Microsoft.Graph.Applications                    2.38.1  C:\Program Files\PowerShell\Modules\Microsoft.Graph.Applicatio…
Microsoft.Graph.Authentication                  2.38.1  C:\Program Files\PowerShell\Modules\Microsoft.Graph.Authentica…
[...]

Quaranta righe, tutte con la stessa versione vecchia (2.38.1 nel caso oggi analizzato e buttato qui sul blog), tutte da rimuovere. A mano sarebbe una tortura, e infatti un Uninstall-Module Microsoft.Graph -RequiredVersion 2.38.1 da solo non basta: quel cmdlet toglie solo il modulo “ombrello“, non i sub-moduli che dipendono da lui.

La pulizia (quella vera)

La strada che mi ha portato a un risultato pulito è stata questa: prendo tutti i moduli della versione da buttare, li ordino mettendo per ultimo Microsoft.Graph.Authentication (da cui dipendono tutti gli altri, quindi va tolto per ultimo) e per primo Microsoft.Graph (l’ombrello, va tolto per primo):

$targetVersion = '2.38.1'

$oldGraph = Get-Module -Name 'Microsoft.Graph*' -ListAvailable |
    Where-Object Version -eq ([version]$targetVersion) |
    Sort-Object Name -Unique

$uninstallOrder = @(
    $oldGraph | Where-Object Name -eq 'Microsoft.Graph'

    $oldGraph | Where-Object {
        $_.Name -notin @(
            'Microsoft.Graph',
            'Microsoft.Graph.Authentication'
        )
    }

    $oldGraph | Where-Object Name -eq 'Microsoft.Graph.Authentication'
)

foreach ($module in $uninstallOrder) {
    Write-Host "Removing $($module.Name) $targetVersion ..."

    Uninstall-Module `
        -Name $module.Name `
        -RequiredVersion $targetVersion `
        -Force `
        -ErrorAction Stop
}

Il -Force serve perché, senza, PowerShell si impunta se trova dipendenze ancora “in uso” secondo il suo registro interno (anche quando in realtà non c’è nessun processo che le sta usando). L’ordine di rimozione (ombrello prima, Authentication per ultimo) evita gli errori di dipendenza mancante che altrimenti PowerShell ti tira dietro a metà pulizia.

A operazione conclusa, una verifica veloce conferma che è rimasta una sola versione installata:

Get-Module -Name 'Microsoft.Graph*' -ListAvailable |
    Group-Object Version |
    Sort-Object Name |
    Select-Object Name, Count

Name   Count
----   -----
2.39.0 40

In conclusione

Il modulo Microsoft.Graph per PowerShell è potente ma non fa mai pulizia da solo: ogni Update-Module lascia dietro di sé la versione precedente, moltiplicata per una quarantina di sub-moduli. Se lavori su più macchine o gestisci ambienti condivisi, questo accumulo diventa presto un problema reale, spazio sprecato, tempi di caricamento del modulo più lunghi, e il rischio concreto di caricare per sbaglio la versione sbagliata di un cmdlet.

Lo script sopra non è elegantissimo ma fa il suo lavoro in modo ripetibile: prendi la versione vecchia, rispetta l’ordine di dipendenza, disinstalla tutto con -Force. Vale la pena tenerlo a portata di mano (magari come funzione riutilizzabile) ogni volta che aggiorni Graph.

In caso di errori, dubbi, boiate riportate in articolo sai già cosa fare, l’area commenti è a tua totale disposizione :-)

#KeepItSimple

Graph: pulizia delle vecchie versioni del modulo dopo un update è stato scritto da Gioxx per Gioxx.org.

La verifica

Prima cosa: escludere che fosse un cambiamento arrivato da un qualche comportamento mio, di uno dei plugin che utilizzo o un aggiornamento di WordPress (dato che ultimamente ne sono arrivati almeno un paio per mettere al sicuro WP 7). Ho controllato wp-config.php per le costanti dichiarate in documentazione:

define( 'WP_AUTO_UPDATE_CORE', 'false' );

Presente, ma quella riguarda solo gli aggiornamenti del core di WordPress, non i plugin, non è la causa. DISALLOW_FILE_MODS assente. Poi ho controllato via wp-cli se i dati di auto-update fossero comunque popolati nel database:

$ wp plugin list --status=active
name           status  update  version  auto_update
akismet        active  none    5.7      on
wordfence      active  none    8.2.2    on
...

I dati c’erano, tutti popolati correttamente. Quindi non era un problema di database: la funzione esisteva ancora, semplicemente la UI per gestirla era sparita.

Il colpevole: un mu-plugin che non ho mai chiesto

A quel punto sono andato a guardare dentro wp-content/mu-plugins/. Cartella che, lo ricordo, WordPress carica sempre, senza possibilità di disattivazione dalla dashboard (da lì il nome: must-use). E lì, tra i miei file, ne spunta uno che non ho mai scritto io:

<?php
/*
  Plugin Name: WordPress automation by Installatron
  Description: Management of this WordPress site is provided by Installatron.
*/

// Turn off WordPress automatic updates since these are managed externally.
add_filter( 'automatic_updater_disabled', '__return_true', -9999 );

Installatron è il tool che molti hosting (incluso il mio, Serverplan) offrono per installare/gestire applicazioni web in un click. Non l’ho mai usato per questo blog, e sospetto che nemmeno tu lo utilizzi consapevolmente, se sei atterrato su questo articolo cercando la stessa colonna sparita. Eppure quel mu-plugin era lì, silenzioso, a filtrare automatic_updater_disabled forzandolo a true con priorità altissima (-9999, giusto per essere sicuri che nessun altro filtro potesse scavalcarlo). Risultato: WordPress disattiva tutto il sistema di auto-update: core, plugin, temi, e nasconde pure la UI corrispondente, colonna compresa.

Il commento nel file suggerisce un modo “ufficiale” per disattivarlo:

To block this plugin, create an empty file in the same directory named: block-automation-by-installatron.php

Peccato che il codice del plugin non controlli mai l’esistenza di quel file. È una convenzione pensata per essere letta (e rispettata) dall’automazione di Installatron stessa quando rigenera i suoi file, non da WordPress. Creare quel file vuoto, quindi, non serve a niente: il filtro resta attivo lo stesso.

La soluzione

L’unico modo efficace è intervenire direttamente sul file. Io ho scelto la via più pulita e reversibile: rinominarlo togliendogli l’estensione .php, così la cartella mu-plugins smette di caricarlo ma il file resta lì, intatto, nel caso servisse tornare indietro:

mv wp-content/mu-plugins/automation-by-installatron.php \
   wp-content/mu-plugins/automation-by-installatron.php.disabled

Verifica rapida via wp-cli per confermare che il filtro non sia più attivo:

$ wp eval 'var_dump(apply_filters("automatic_updater_disabled", false));'
bool(false)

Colonna auto-update tornata al suo posto nella pagina Plugin, tutto come previsto.

In conclusione

Se anche a te manca quella colonna e non ricordi di averla tolta, il primo posto dove guardare è wp-content/mu-plugins/, non la lista plugin normale, perché i must-use plugin non compaiono lì e non sono disattivabili dalla dashboard. Se trovi un file simile a automation-by-installatron.php (o comunque riconducibile al tuo hosting), sai già cosa cercare al suo interno e come toglierlo di mezzo.

Il punto che mi lascia più perplesso resta un altro: nessun avviso, nessuna nota nel pannello Serverplan, niente. Un mu-plugin che disattiva silenziosamente una funzione di sicurezza/manutenzione del sito è il genere di cosa che vorrei sapere prima, non scoprire per caso mesi dopo controllando una colonna mancante. Se gestisci un sito su hosting che offre Installatron (o strumenti simili), vale la pena dare un’occhiata preventiva a quella cartella, anche se non hai scelto consapevolmente di attivarlo.

L’area commenti è a tua disposizione in caso di ulteriori dubbi o magari per segnalare la medesima situazione su hosting differenti rispetto a quello da me utilizzato.

#KeepItSimple

Colonna auto-update plugin sparita? Controlla mu-plugins, potrebbe essere colpa di Installatron è stato scritto da Gioxx per Gioxx.org.

Cinque settimane fa avevo dato il via a una serie di articoli ad-hoc per parlarti del nuovo look per una nuova era di The Marvellous Suspender, avevo usato direttamente il blog di Marvellous Codeworks e l’inglese come lingua principale per raggiungere quanti più lettori e utilizzatori possibili (non pensavo avrebbe avuto senso ospitare il tutto, in italiano, anche qui sul mio blog personale). Poche ore fa Google ha dato il via libera alla pubblicazione della v9.0.0 e, a partire da lunedì mattina, 3 agosto, la nuova versione comincerà a essere distribuita sul Chrome Web Store. È l’ultima tappa di questo percorso, e te la racconto volentieri (con 40°C fuori e la voglia di mettere la testa sott’acqua, ma questo è un altro discorso).

TMS 9: cosa c’è di nuovo sotto al cofano

• Backup e ripristino delle sessioni (forse tra le feature più richieste in assoluto, dalla notte dei tempi), in locale o su Google Drive, programmabile o su richiesta, con supporto multi-dispositivo.
• Una pagina di Tab Health che scansiona le schede sospese e ripara da sola il bug dei Tab Groups che si perdono al riavvio di Chrome, Edge e Brave (bug ormai risolto, ma considerato che non si sa mai, le funzioni sono state conservate e rese disponibili su richiesta / necessità).
• Un feed di notizie che pesca direttamente dal blog di Marvellous Codeworks (che rimane l’unico ufficiale del progetto, in inglese, mentre qui sul mio blog personale continuerò a proporre articoli in italiano, talvolta traducendoli direttamente) raggiungibile tramite la barra laterale delle impostazioni dell’estensione.
• Un redesign visivo completo che finalmente fa sembrare tutte le pagine delle impostazioni parte dello stesso prodotto.
• 16 lingue riportate in pari dopo essere rimaste indietro per chissà quanto tempo.

Niente di tutto questo è arrivato per caso, e niente è arrivato da solo.

Le chiacchierate con Rob

Io e Rob non lavoriamo nello stesso ufficio, nello stesso Paese, e nemmeno vicini come fuso orario, per buona parte del tempo. Gran parte delle decisioni su TMS 9 sono state avviate in un gruppo Slack in orari che non avevano senso per nessuno dei due, discutendo se un permesso fosse troppo invasivo, se un’impostazione avesse bisogno di un tooltip, se “Ripristina da backup” dovesse stare sotto Sessioni o sotto Backup. Domande piccole, ma di quelle che decidono se un’estensione sembra curata o semplicemente pubblicata.

The Great-er Tab Discarder (TGD) e The Marvellous Suspender (TMS) sono due progetti distinti, con codebase separate, ma Marvellous Codeworks funziona solo perché siamo in due a tirare nella stessa direzione, a controllarci i punti ciechi a vicenda e, ogni tanto, a dirci l’un l’altro che un’idea fa schifo prima che finisca in produzione. TMS 9 ne guadagna, eccome, e speriamo di poter fare la stessa cosa con TGD, presto.

La community che si è fatta sentire

Nel changelog di TMS 9 ci sono anche due contributor al debutto: @MatrixNeoKozak, che ha rifattorizzato il livello di storage eliminando serializzazioni JSON inutili, e @iGhost, che ha aggiunto l’opzione per mantenere la posizione di riproduzione di YouTube quando una scheda viene sospesa. Una feature piccola, richiesta e costruita da chi il problema lo ha vissuto sul serio (io per esempio non avevo mai avuto necessità di questa caratteristica). È esattamente così che dovrebbe crescere un progetto open source: non solo bug report, ma pull request di persone che hanno deciso di sistemare la cosa di persona.

In più, sedici lingue hanno ricevuto un passaggio di traduzione assistita da AI (qui Claude ha avuto carta bianca) per colmare buchi che si trascinavano da diverse versioni. Non sono perfette: se usi TMS nella tua lingua e qualcosa suona storto, Crowdin è aperto, e le correzioni dei madrelingua sono esattamente ciò che serve per chiudere il cerchio.

Segnalare un problema senza account GitHub

Per anni l’unico modo per dirci che qualcosa non andava era aprire una segnalazione su GitHub, il che significava avere un account GitHub, spesso visto come un muro che molti semplicemente non erano disposti a scavalcare solo per segnalare un bug. I problemi ci arrivavano di riflesso, nelle recensioni, nei thread di Reddit, mai dove potevamo davvero intervenire.

marvellouscode.works/tms/report proverà a risolvere la cosa. Si compila un form, senza registrazione, senza account, e viene aperta in automatico una issue GitHub corretta, etichettata bene, con i campi che ci servono davvero per riprodurre il problema. Chi segnala riceve un link per seguire lo stato, noi riceviamo un report vero e utilizzabile invece di una recensione da una stella che dice solo “non funziona più”.

E a proposito: leggiamo tutto, comprese le recensioni lasciate direttamente sul Chrome Web Store. Stelline, recensioni scritte, richieste di supporto in quel piccolo box, tutto viene letto. Teniamo d’occhio in particolare le segnalazioni GitHub perché è lì che tracciamo e agiamo davvero, verificando comportamenti strani, seguendo le richieste, chiudendo le cose una volta risolte, ma una recensione lasciata sullo Store non è comunque gridare nel vuoto.

Un sito di documentazione costruito da zero

Il vecchio wiki di TMS viveva sul repo GitHub, mezzo incompleto, datato in alcuni punti, e onestamente non il tipo di posto dove mandare qualcuno se volevate che capisse davvero l’estensione. Ora è disattivato.

Al suo posto: kb.marvellouscode.works/docs, popolato da zero sfruttando Docusaurus come base, pagina per pagina, specialmente per TMS 9 (anche se in realtà pensato per tutti i lavori che trovano spazio sotto l’ala di Marvellous Codeworks). Ogni pagina delle impostazioni ha il suo articolo: Impostazioni, Sessioni, Backup, Tab Health, Azioni Rapide, Scorciatoie da Tastiera, Notizie, Informazioni, che spiega cosa fa davvero ogni pulsante, non solo come si chiama. C’è una pagina dedicata ai permessi che spiega perché TMS chiede quello che chiede e cosa è cambiato con lo scope Drive più ristretto in questa release. FAQ incluse. Niente nascosto in una pagina wiki stantia che nessuno aggiornava dal 2019.

L’abbiamo costruito pagina per pagina, decidendo cosa aveva davvero bisogno di essere spiegato e cosa era abbastanza ovvio da saltare. Il dominio marvellouscode.works era registrato e fermo da quasi un anno: ci sono volute settimane di riorganizzazione e riscrittura per trasformarlo nel sito, nella documentazione e nel flusso di segnalazione che puoi sfruttare oggi.

Cambia tutto (ma non cambia niente)

TMS 9 ha un aspetto diverso, è organizzato diversamente, permette di effettuare il backup diversamente, e parla più lingue di prima. Questa è la parte “cambia tutto”, ed è costata una riscrittura completa delle pagine di impostazioni, un nuovo sistema di backup e parecchie scambi in chat.

La parte “non cambia niente” è più semplice: TMS esiste ancora per prendere le schede che il browser accumula in memoria e metterle a dormire finché non servono davvero. Era vero il giorno in cui The Great Suspender è stato salvato, lo è stato durante la riscrittura per Manifest V3, e lo è ancora nella v9.0.0. Ogni feature di questa release, Tab Health, backup, redesign, esiste per proteggere quel singolo compito, non per sostituirlo.

Non piacerà a tutti, e va bene così

Siamo perfettamente consapevoli che non tutti saranno entusiasti del nuovo look. Il cambiamento raramente è visto di buon occhio, e un redesign di queste dimensioni – nuovi font, nuovi colori, nuovo layout su ogni singola pagina – è esattamente il tipo di cosa per cui alcuni avranno bisogno di tempo per abituarsi, o semplicemente non gli piacerà affatto. Fa parte della crescita di un progetto, fa parte del gioco.

Restiamo convinti che la “ritinteggiatura” fosse necessaria, e pensiamo sia solo il primo passo importante. Ci sono altre idee in cantiere, e ci sono già parecchi problemi e richieste di feature su GitHub che intendiamo affrontare per continuare a spingere TMS avanti. Ascoltiamo, prendiamo sul serio feedback e critiche costruttive: è tutto il senso dell’open source, in fondo.

Cosa succede ora

La revisione di Google è conclusa, il changelog è definitivo, e il rilascio parte lunedì mattina, 3 agosto. Gli aggiornamenti sul Chrome Web Store vengono distribuiti gradualmente e non a tutti insieme, quindi non allarmarti se non vedi la v9.0.0 nel secondo esatto in cui andrai a controllare: arriverà entro la normale finestra di aggiornamento. Questa serie di articoli si chiude ufficialmente qui. Grazie per averla seguita fino in fondo, per aver testato i feature branch, per le issue aperte, per le pull request, e per la pazienza.

Ci vediamo dall’altra parte, nella v9.0.0. L’area commenti è a tua disposizione, come sempre, per domande o per raccontarmi la tua personale esperienza con TMS 9.

#KeepItSimple (e buone vacanze!)

Immagine di copertina: Growtika on Unsplash

TMS 9: ce l’abbiamo fatta, da lunedì si va in scena! è stato scritto da Gioxx per Gioxx.org.

Sul blog ufficiale di Nightly è comparso un post di annuncio piuttosto scarno (New Firefox Design), di quelli che dicono poco e lasciano parlare gli screenshot: giusto due righe di presentazione e via, senza un vero e proprio changelog o una spiegazione del perché di questa scelta proprio ora.

Nightly resta il mio Firefox di tutti i giorni, non a caso: mi piace sperimentare, dare un contributo (quando posso) alle idee che magari un domani arriveranno anche nelle versioni stabili. È rimasto quel poco che riesco ancora a fare dopo vent’anni e passa in Mozilla Italia, di cui i primi da contributor piuttosto attivo. Chi segue Firefox da un po’ di anni sa che non è la prima volta che il browser cambia pelle: Australis, Photon, Proton sono nomi che a chi ha vissuto quelle transizioni diranno qualcosa, e ognuna ha portato con sé lo stesso copione: entusiasmo di facciata, malumori sotto traccia, e alla fine ci si abitua tutti (o quasi). Project Nova sembra volersi inserire in questa tradizione, solo che stavolta la reazione è arrivata più rumorosa e più in fretta del solito.

Project Nova me lo sono trovato in faccia da subito, senza nemmeno cercarlo, aggiornando Nightly come faccio ogni giorno, ed è giusto perché chi usa Nightly accetta di fare da cavia per queste sperimentazioni.

Cosa dice la community

Su Mozilla Connect è partito un thread dedicato, Take Project Nova for a spin in Nightly, e “nutrito” è dire poco: pagine e pagine di commenti (caricarle tutte richiede un attimo di pazienza), e il tono generale non è esattamente da standing ovation. Ho lasciato anche il mio contributo al thread, qui, e riassumendo: il “gioco” del nuovo aspetto grafico può anche essere divertente da provare per qualche giorno, ma a conti fatti resta un esercizio di stile che toglie più di quanto aggiunge a chi usa il browser per lavorarci, non per ammirarlo.

Quello che mi ha colpito, scorrendo il thread, non è tanto il dissenso in sé (succede a ogni redesign, fa quasi parte del rito), quanto il volume e la rapidità con cui è arrivato. Di solito ci vogliono settimane prima che un cambiamento grafico venga metabolizzato dalla community, qui in pochi giorni si è già accumulata una mole di feedback che normalmente si vede solo dopo un rilascio stabile, non su un canale sperimentale che nasce apposta per essere rotto e discusso.

Come tornare indietro

Se anche a te Nova non convince e vuoi il vecchio aspetto “più umano”, il salvagente c’è ed è semplice:

• Apri about:config (il solito avviso: sai cosa stai facendo, ma occhio comunque a cosa tocchi, un flag sbagliato e ti ritrovi a chiederti perché qualcos’altro ha smesso di funzionare).
• Cerca browser.nova.enabled.
• Impostalo su false

Fatto, il browser torna all’interfaccia che conosci, senza bisogno di reinstallare nulla o tornare a un canale diverso da Nightly, senza neanche riavviare Firefox che di solito è necessario per applicare le modifiche operate da about:config. Tieni presente che, trattandosi di un flag sperimentale, non è garantito che sopravviva tale e quale ai prossimi aggiornamenti: se un giorno lo cerchi e non lo trovi più (o si comporta diversamente), la causa più probabile è che nel frattempo Project Nova sia stato integrato più a fondo nel browser, magari con un meccanismo di disattivazione diverso.

Comprendo, non condivido

Capisco la logica dietro Project Nova. Ogni tanto un browser ha bisogno di rinfrescarsi, e Nightly è esattamente il posto giusto dove provare queste cose prima che arrivino (se arrivano) nelle versioni stabili. Ma tra provarlo e tenerlo attivo di default anche su un canale già di per sé instabile fa una bella differenza, e il thread su Connect lo dimostra piuttosto bene. Per ora resto con browser.nova.enabled a false, e aspetto di vedere dove va a parare questo esperimento: se Mozilla ascolterà davvero quello che sta emergendo da Connect o se, come già successo in passato, si andrà avanti dritti per la propria strada aggiustando solo i dettagli più urlati.
Magari tra qualche tempo (neanche tanto esagerato) torno ad attivarlo e vedere quali passi in avanti sono stati fatti.

#KeepItSimple

Project Nova per Firefox Nightly: bello il gioco, però ora basta. è stato scritto da Gioxx per Gioxx.org.