Usare PowerShell per gestire la connessione turni a UKG Pro Workforce Management

  • Articolo
  • Si applica a:
    Microsoft Teams, Microsoft 365 for frontline workers

Panoramica

Il connettore Turni di Microsoft Teams per UKG Pro Workforce Management consente di integrare l'app Turni in Microsoft Teams con UKG Pro Workforce Management (UKG Pro WFM). I dipendenti in prima linea possono visualizzare e gestire facilmente le pianificazioni in UKG Pro WFM dall'interno di Turni.

È possibile usare la procedura guidata del connettore Turni nell’interfaccia di amministrazione di Microsoft 365 o PowerShell per configurare rapidamente una connessione. Dopo aver configurato una connessione, è possibile gestirla usando i cmdlet powershell del connettore Turni.

In questo articolo viene descritto come usare PowerShell per eseguire quanto segue:

Questo articolo presuppone che sia già stata configurata una connessione a UKG Pro WFM, usando la procedura guidata o PowerShell.

Nota

È anche possibile gestire la connessione nel interfaccia di amministrazione di Microsoft 365. Ad esempio, è possibile controllare lo stato di integrità e accedere alla procedura guidata per modificare le impostazioni di connessione. Per altre informazioni, vedere Usare il interfaccia di amministrazione di Microsoft 365 per gestire la connessione turni a UKG Pro Workforce Management.

Prima di iniziare

Per completare la procedura descritta in questo articolo, è necessario essere un amministratore globale di Microsoft 365 o un amministratore del connettore Turni.

Il ruolo di amministratore del connettore Turni è un ruolo personalizzato creato in Microsoft Entra ID e assegnato a un utente. Il nome del ruolo deve essere "Amministratore connettore turni". Il ruolo non deve avere autorizzazioni specifiche, anche se è necessario impostare almeno un'autorizzazione al momento della creazione. Il servizio si basa sulla presenza del ruolo sull'utente e non sulle relative autorizzazioni.

Per altre informazioni, vedere Creare e assegnare un ruolo personalizzato in Microsoft Entra ID e Assegnare ruoli Microsoft Entra agli utenti. Tenere presente che la creazione e l'applicazione del ruolo a un utente possono richiedere fino a 24 ore.

Configurare l'ambiente

Nota

Assicurarsi di seguire questa procedura per configurare l'ambiente prima di eseguire uno dei comandi o degli script in questo articolo.

  1. Installare PowerShell versione 7 o successiva. Per istruzioni dettagliate, vedere Installazione di PowerShell in Windows.

  2. Esegui Powershell in modalità Amministratore.

  3. Installare il modulo Microsoft Graph PowerShell.

    Install-Module Microsoft.Graph
Import-Module Microsoft.Graph

    Verificare che sia la versione 1.6.1 o successiva.

    Get-InstalledModule Microsoft.Graph

  4. Installare il modulo PowerShell di anteprima di Teams.

    Install-Module -Name MicrosoftTeams -AllowPrerelease -Force
Import-Module MicrosoftTeams

    Verificare che sia almeno la versione 4.7.0 e che contenga i cmdlet del connettore Turni.

    Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection*

  5. Impostare PowerShell in modo che venga chiuso se si verifica un errore durante l'esecuzione dello script.

    $ErrorActionPreference = "Stop"

  6. Abilitare l'esecuzione degli script in Windows.

    Set-ExecutionPolicy bypass

  1. Connettersi a Teams.

    Connect-MicrosoftTeams

    Quando viene richiesto, accedere usando le credenziali di amministratore. È ora possibile configurare l'esecuzione degli script in questo articolo e nei cmdlet del connettore Turni.

Controllare lo stato di configurazione della connessione

Per controllare lo stato della connessione configurata usando l'ID operazione ricevuto tramite posta elettronica, seguire questa procedura:

  1. Configurare l'ambiente (se non è già stato fatto).

  2. Esegui il comando seguente: Questo comando fornisce lo stato complessivo dei mapping del team per la connessione.

    Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>

Per altre informazioni, vedere Get-CsTeamsShiftsConnectionOperation.

Visualizzare un report degli errori per una connessione

È possibile eseguire un report che mostra i dettagli dell'errore per una connessione. Il report elenca i mapping di team e utenti che hanno avuto esito positivo e negativo. Fornisce inoltre informazioni su eventuali problemi relativi agli account associati alla connessione.

  1. Configurare l'ambiente (se non è già stato fatto).

  2. Ottenere un elenco di report degli errori per una connessione.

    Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>

  3. Per visualizzare un report degli errori specifico, eseguire il comando seguente:

    Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>

Per altre informazioni, vedere Get-CsTeamsShiftsConnectionErrorReport.

Nota

Per un elenco completo dei messaggi di errore, vedere Elenco dei messaggi di errore più avanti in questo articolo.

Risolvere gli errori di connessione

Errori di mapping utente

È possibile che si verifichino errori di mapping degli utenti se uno o più utenti in un'istanza di WFM non sono membri del team mappato in Teams. Per risolvere questo problema, assicurarsi che gli utenti del team mappato corrispondano agli utenti nell'istanza di WFM.

Per visualizzare i dettagli degli utenti non mappati, configurare l'ambiente (se non è già stato fatto) ed eseguire lo script seguente.

#View sync errors script
Write-Host "View sync errors"
Start-Sleep 1

#Ensure Teams module is of version x
Write-Host "Checking Teams module version"
try {
    Get-InstalledModule -Name "MicrosoftTeams" -MinimumVersion 4.7.0
} catch {
    throw
}

#List connection instances available
Write-Host "Listing connection instances"
$InstanceList = Get-CsTeamsShiftsConnectionInstance
write $InstanceList

#Get an instance
if ($InstanceList.Count -gt 0){
    $InstanceId = Read-Host -Prompt 'Input the instance ID that you want to retrieve user sync results from'
}
else {
    throw "Instance list is empty"
}

#Get a list of the mappings
Write-Host "Listing team mappings"
$mappings = Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId $InstanceId
write $mappings

#For each mapping, retrieve the failed mappings
ForEach ($mapping in $mappings){
    $teamsTeamId = $mapping.TeamId
    $wfmTeamId = $mapping.WfmTeamId
    Write-Host "Failed mapped users in the mapping of ${teamsTeamId} and ${wfmTeamId}:"
    $userSyncResult = Get-CsTeamsShiftsConnectionSyncResult -ConnectorInstanceId $InstanceId -TeamId $teamsTeamId
    Write-Host "Failed AAD users:"
    write $userSyncResult.FailedAadUser
    Write-Host "Failed WFM users:"
    write $userSyncResult.FailedWfmUser
}

Errori di autorizzazione dell'account

È possibile che si verifichino errori di autorizzazione dell'account se l'account del servizio WFM o le credenziali dell'account di sistema di Microsoft 365 non sono corrette o non dispongono delle autorizzazioni necessarie.

Per modificare le credenziali dell'account del servizio di WFM o dell'account di sistema di Microsoft 365 per la connessione, è possibile eseguire il cmdlet Set-CsTeamsShiftsConnectionInstance o usare lo script di PowerShell nella sezione Modificare le impostazioni di connessione di questo articolo.

Modificare le impostazioni di connessione

Usare questo script per modificare le impostazioni di connessione. Le impostazioni che è possibile modificare includono l'account del servizio WFM e la password, l'account di sistema di Microsoft 365, i mapping dei team e le impostazioni di sincronizzazione.

Le impostazioni di sincronizzazione includono la frequenza di sincronizzazione (in minuti) e i dati di pianificazione sincronizzati tra il sistema WFM e Turni. I dati di pianificazione sono definiti nei parametri seguenti, che è possibile visualizzare eseguendo Get-CsTeamsShiftsConnectionConnector.

  • Il parametro enabledConnectorScenarios definisce i dati sincronizzati dal sistema WFM a Turni. Le opzioni sono Shift, SwapRequest, OfferShiftRequest, UserShiftPreferences, OpenShiftRequestOpenShift, TimeOff, . TimeOffRequest

  • Il parametro enabledWfiScenarios definisce i dati sincronizzati da Turni al sistema WFM. Le opzioni sono SwapRequest, OfferShiftRequest, OpenShiftRequest, TimeOffRequest, UserShiftPreferences.

    Nota

    Se si sceglie di non sincronizzare i turni aperti, le richieste di turno, le richieste di scambio o le richieste di time off tra Turni e il sistema WFM, è necessario eseguire un altro passaggio per nascondere la funzionalità in Turni. Dopo aver eseguito questo script, assicurarsi di seguire i passaggi descritti nella sezione Disabilitare i turni aperti, le richieste di turni aperti, le richieste di scambio e le richieste di permesso più avanti in questo articolo.

    Importante

    Per le impostazioni che non si vuole modificare, è necessario immettere nuovamente le impostazioni originali quando viene richiesto dallo script.

Configurare l'ambiente (se non è già stato fatto) ed eseguire lo script seguente.

#Update connector instance and mapping script
Write-Host "Update Connector instance and mapping"
Start-Sleep 1

#Ensure Teams module is at least version x
Write-Host "Checking Teams module version"
try {
    Get-InstalledModule -Name "MicrosoftTeams" -MinimumVersion 4.7.0
} catch {
    throw
}

#Connect to MS Graph
Connect-MgGraph -Scopes "User.Read.All","Group.ReadWrite.All"

#List connector types available (comment out if not implemented for preview)
Write-Host "Listing connector types available"
$UkgId = "95BF2848-2DDA-4425-B0EE-D62AEED4C0A0"
$connectors = Get-CsTeamsShiftsConnectionConnector
write $connectors
$Ukg = $connectors | where {$_.Id -match $UkgId}

#List connection instances available
Write-Host "Listing connection instances available"
$InstanceList = Get-CsTeamsShiftsConnectionInstance | where {$_.ConnectorId -match $UkgId}
write $InstanceList

#Prompt for the WFM username and password
$WfmUserName = Read-Host -Prompt 'Input your WFM user name'
$WfmPwd = Read-Host -Prompt 'Input your WFM password' -AsSecureString
$plainPwd =[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($WfmPwd))

#Get the instance ID
$InstanceId = Read-Host -Prompt 'Input the instance ID that you want to update'
$Instance = Get-CsTeamsShiftsConnectionInstance -ConnectorInstanceId $InstanceId
$Etag = $Instance.etag

#Change sync setting
$designatorName = Read-Host -Prompt "Input designated actor's user name"
$designator = Get-MgUser -UserId $designatorName
$teamsUserId = $designator.Id
$UpdatedInstanceName = Read-Host -Prompt 'Input new connection instance name'
$updatedConnectorScenarioString = Read-Host -Prompt 'Input new enabled connector scenarios'
$updatedWfiScenarioString = Read-Host -Prompt 'Input new enabled WFI scenarios'
$Delimiters = ",", ".", ":", ";", " ", "`t"
$updatedConnectorScenario = $updatedConnectorScenarioString -Split {$Delimiters -contains $_}
$updatedConnectorScenario = $updatedConnectorScenario.Trim()
$updatedConnectorScenario = $updatedConnectorScenario.Split('',[System.StringSplitOptions]::RemoveEmptyEntries)
$updatedWfiScenario = $updatedWfiScenarioString -Split {$Delimiters -contains $_}
$updatedWfiScenario = $updatedWfiScenario.Trim()
$updatedWfiScenario = $updatedWfiScenario.Split('', [System.StringSplitOptions]::RemoveEmptyEntries)
$apiUrl = $Instance.ConnectorSpecificSettingApiUrl
$ssoUrl = $Instance.ConnectorSpecificSettingSsoUrl
$clientId = $Instance.ConnectorSpecificSettingClientId
$syncFreq = Read-Host -Prompt 'Input new sync frequency'
$AppKey = Read-Host -Prompt 'Input your app key' -AsSecureString
$plainKey =[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($AppKey))
$ClientSecret = Read-Host -Prompt 'Input your client secret' -AsSecureString
$plainSecret =[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($ClientSecret))

#Read admin email list
[psobject[]]$AdminEmailList = @()
while ($true){
$AdminEmail = Read-Host -Prompt "Enter admin's email to receive error report"
$AdminEmailList += $AdminEmail
$title    = 'Adding another email'
$question = 'Would you like to add another admin email?'
$choices  = '&Yes', '&No'
$decision = $Host.UI.PromptForChoice($title, $question, $choices, 1)
if ($decision -eq 1) {
    break
}
}
$UpdatedInstance = Set-CsTeamsShiftsConnectionInstance `
    -ConnectorInstanceId $InstanceId `
    -ConnectorId $UkgId `
    -ConnectorAdminEmail $AdminEmailList `
    -DesignatedActorId $teamsUserId `
    -EnabledConnectorScenario $updatedConnectorScenario `
    -EnabledWfiScenario $updatedWfiScenario `
    -Name $UpdatedInstanceName `
    -SyncFrequencyInMin $syncFreq `
    -ConnectorSpecificSettings (New-Object Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Models.ConnectorSpecificUkgDimensionsSettingsRequest `
        -Property @{
            apiUrl = $apiUrl
            ssoUrl = $ssoUrl
            appKey = $plainKey
            clientId = $clientId
            clientSecret = $plainSecret
            LoginUserName = $WfmUserName
            LoginPwd = $plainPwd
        }) `
    -IfMatch $Etag
if ($UpdatedInstance.Id -ne $null) {
    Write-Host "Success"
}
else {
    throw "Update instance failed"
}
#Get a list of the mappings
Write-Host "Listing mappings"
$TeamMaps = Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId $InstanceId
write $TeamMaps

#Modify a mapping
#Remove a mapping
Write-Host "Removing a mapping"
$TeamsTeamId = Read-Host -Prompt 'Input the Teams team ID that you want to unlink'
$WfmTeamId = Read-Host -Prompt 'Input the WFM team ID that you want to unlink'
Remove-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId $InstanceId -TeamId $TeamsTeamId
Write-Host "Success"

#Add a mapping
Write-Host "Adding a mapping"
$TeamsTeamId = Read-Host -Prompt 'Input the Teams team ID that you want to link'
$WfmTeamId = Read-Host -Prompt 'Input the WFM team ID that you want to link'
New-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId $InstanceId -TeamId $TeamsTeamId -TimeZone "America/Los_Angeles" -WfmTeamId $WfmTeamId
Write-Host "Success"

Disabilitare i turni aperti, le richieste di turni aperti, le richieste di scambio e le richieste di permesso

Importante

Seguire questa procedura solo se si è scelto di disabilitare i turni aperti, le richieste di spostamento, le richieste di scambio o le richieste di time off usando lo script nella sezione Modificare le impostazioni di connessione più indietro in questo articolo o usando il cmdlet Set-CsTeamsShiftsConnectionInstance. Il completamento di questo passaggio nasconde la funzionalità in Turni. Senza questo secondo passaggio, gli utenti vedranno ancora la funzionalità in Turni e riceveranno un messaggio di errore "operazione non supportata" se tentano di usarla.

Per nascondere turni aperti, richieste di scambio e richieste di time off in Turni, usare il tipo di risorsa pianificazione API Graph per impostare i parametri false seguenti su per ogni team mappato a un'istanza di WFM:

  • Turni aperti: openShiftsEnabled
  • Richieste di scambio: swapShiftsRequestsEnabled
  • Richieste di permesso: timeOffRequestsEnabled
  • Richieste di spostamento dell'offerta: offerShiftRequestsEnabled

Per nascondere le richieste di turni aperti in Turni, passare a Impostazioni in Turni e quindi disattivare l'impostazione Turni aperti.

Annullare il mapping di un team da una connessione e mapparlo a un'altra connessione

Nota

L'account di sistema di Microsoft 365 deve essere lo stesso per entrambe le connessioni. In alternativa, verrà visualizzato il messaggio di errore "Il profilo dell'attore disegnato non dispone dei privilegi del proprietario del team".

Se si vuole annullare il mapping di un team da una connessione e mapparlo a un'altra connessione:

  1. Configurare l'ambiente (se non è già stato fatto).

  2. Visualizzare un elenco di tutti i mapping del team per una connessione.

    Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>

  3. Rimuovere un mapping del team dalla connessione.

    Remove-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId> -TeamId <TeamId>

  4. Eseguire il mapping del team a un'altra connessione.

    New-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId> -TeamId <TeamId> -WfmTeamId <SiteId> -TimeZone <TimeZone>

Per altre informazioni, vedere Get-CsTeamsShiftsConnectionTeamMap, Remove-CsTeamsShiftsConnectionTeamMap e New-CsTeamsShiftsConnectionTeamMap.

Disabilitare la sincronizzazione per una connessione

Usare questo script per disabilitare la sincronizzazione per una connessione. Tenere presente che questo script non rimuove o elimina una connessione. Disattiva la sincronizzazione in modo che non venga sincronizzato alcun dato tra Turni e il sistema WFM per la connessione specificata.

Configurare l'ambiente (se non è già stato fatto) ed eseguire lo script seguente.

#Disable sync script
Write-Host "Disable sync"
Start-Sleep 1

#Ensure Teams module is at least version x
Write-Host "Checking Teams module version"
try {
    Get-InstalledModule -Name "MicrosoftTeams" -MinimumVersion 4.7.0
} catch {
    throw
}

#List connection instances available
$UkgId = "95BF2848-2DDA-4425-B0EE-D62AEED4C0A0"
Write-Host "Listing connection instances"
$InstanceList = Get-CsTeamsShiftsConnectionInstance | where {$_.ConnectorId -match $UkgId}
write $InstanceList

#Get an instance
if ($InstanceList.Count -gt 0){
    $InstanceId = Read-Host -Prompt 'Input the instance ID that you want to disable sync'
    $Instance = Get-CsTeamsShiftsConnectionInstance -ConnectorInstanceId $InstanceId
    $Etag = $Instance.etag
    $InstanceName = $Instance.Name
    $DesignatedActorId = $Instance.designatedActorId
    $apiUrl = $Instance.ConnectorSpecificSettingApiUrl
    $ssoUrl = $Instance.ConnectorSpecificSettingSsoUrl
    $clientId = $Instance.ConnectorSpecificSettingClientId
    $ConnectorAdminEmail = $Instance.ConnectorAdminEmail
}
else {
    throw "Instance list is empty"
}

#Remove scenarios in the mapping
Write-Host "Disabling scenarios in the team mapping"
$UpdatedInstanceName = $InstanceName + " - Disabled"
$UkgId = "95BF2848-2DDA-4425-B0EE-D62AEED4C0A0"
$WfmUserName = Read-Host -Prompt 'Input your WFM user name'
$WfmPwd = Read-Host -Prompt 'Input your WFM password' -AsSecureString
$plainPwd =[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($WfmPwd))
$AppKey = Read-Host -Prompt 'Input your app key' -AsSecureString
$plainKey =[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($AppKey))
$ClientSecret = Read-Host -Prompt 'Input your client secret' -AsSecureString
$plainSecret =[Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($ClientSecret))

$UpdatedInstance = Set-CsTeamsShiftsConnectionInstance `
    -ConnectorInstanceId $InstanceId `
    -ConnectorId $UkgId `
    -ConnectorAdminEmail $ConnectorAdminEmail `
    -DesignatedActorId $DesignatedActorId `
    -EnabledConnectorScenario @() `
    -EnabledWfiScenario @() `
    -Name $UpdatedInstanceName `
    -SyncFrequencyInMin 10 `
    -ConnectorSpecificSettings (New-Object Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Models.ConnectorSpecificUkgDimensionsSettingsRequest `
        -Property @{
            apiUrl = $apiUrl
            ssoUrl = $ssoUrl
            appKey = $plainKey
            clientId = $clientId
            clientSecret = $plainSecret
            LoginUserName = $WfmUserName
            LoginPwd = $plainPwd
        }) `
    -IfMatch $Etag

if ($UpdatedInstance.Id -ne $null) {
    Write-Host "Success"
}
else {
    throw "Update instance failed"
}

Elenco dei messaggi di errore

Di seguito è riportato l'elenco dei messaggi di errore che potrebbero verificarsi e le informazioni che consentono di risolverli.

Tipo di errore Dettagli dell'errore Risoluzione
Impossibile autenticare il sistema di gestione della forza lavoro. Le credenziali dell'account del sistema di gestione della forza lavoro specificate non sono valide o questo account non dispone delle autorizzazioni necessarie. Aggiornare le credenziali dell'account del servizio WFM nelle impostazioni di connessione. A tale scopo, utilizzare uno dei metodi descritti di seguito:
Impossibile autenticare Graph. Autenticazione non riuscita. Assicurarsi di aver immesso credenziali valide per l'attore designato e di avere le autorizzazioni necessarie. Assicurarsi che l'account di sistema di Microsoft 365 (noto anche come attore designato) venga aggiunto come proprietario del team.
In alternativa, aggiornare le credenziali dell'account di sistema di Microsoft 365 nelle impostazioni di connessione.
Alcuni utenti non sono riusciti a eseguire correttamente il mapping Mapping non riuscito per alcuni utenti: <X> ha avuto esito positivo, <X> ha avuto esito negativo utenti AAD e <X> utenti del sistema di gestione della forza lavoro non riusciti. Usare il cmdlet Get-CsTeamsShiftsConnectionSyncResult o questo script di PowerShell per identificare gli utenti per cui il mapping non è riuscito. Assicurarsi che gli utenti del team mappato corrispondano agli utenti nell'istanza di WFM.
Impossibile eseguire il mapping di un team o di un team in questo batch. Questo profilo di attore designato non dispone di privilegi di proprietà del team. Assicurarsi che l'account di sistema di Microsoft 365 (noto anche come attore designato) venga aggiunto come proprietario del team.
Se è stato modificato l'account di sistema di Microsoft 365, aggiungere tale account come proprietario del team e aggiornare le impostazioni di connessione per usare tale account.
Questo team è già mappato a un'istanza del connettore esistente. Rimuovere il mapping del team dall'istanza del connettore esistente usando il cmdlet Remove-CsTeamsShiftsConnectionTeamMap . In alternativa, creare una nuova connessione per modificare il mapping del team.
Questo fuso orario non è valido. Il fuso orario passato in non usa il formato di database tz. Assicurarsi che il fuso orario sia corretto e quindi modificare il mapping del team.
Non è possibile trovare questa istanza del connettore. Eseguire il mapping del team a una connessione esistente.
Non è stato possibile trovare questo team di AAD. Assicurarsi che il team esista o creare un nuovo team.

Cmdlet del connettore Turni

Per informazioni sui cmdlet del connettore Turni, cercare CsTeamsShiftsConnection nelle informazioni di riferimento sui cmdlet di Teams PowerShell. Di seguito sono riportati i collegamenti ad alcuni cmdlet di uso comune.