Zarządzanie połączeniem shifts z rozwiązaniem UKG Pro Workforce Management przy użyciu programu PowerShell

Omówienie

Łącznik Microsoft Teams Shifts dla rozwiązania UKG Pro Workforce Management umożliwia integrację aplikacji Shifts w usłudze Microsoft Teams z rozwiązaniem UKG Pro Workforce Management (UKG Pro WFM). Twoi pracownicy pierwszej linii mogą bezproblemowo wyświetlać swoje harmonogramy i zarządzać nimi w usłudze UKG Pro WFM z poziomu usługi Shifts.

Aby skonfigurować połączenie, możesz użyć kreatora łącznika Shifts w centrum administracyjnym platformy Microsoft 365 lub programie PowerShell . Po skonfigurowaniu połączenia można nim zarządzać przy użyciu poleceń cmdlet programu PowerShell łącznika Shifts.

W tym artykule opisano sposób używania programu PowerShell do wykonywania następujących czynności:

• Sprawdzanie stanu konfiguracji połączenia
• Wyświetlanie raportu o błędach dla połączenia
• Rozwiązywanie problemów z błędami połączenia
• Zmienianie ustawień połączenia
• Usuń mapowanie zespołu z jednego połączenia i mapowanie go na inne połączenie
• Wyłączanie synchronizacji dla połączenia

W tym artykule przyjęto założenie, że połączenie z usługą UKG Pro WFM zostało już skonfigurowane przy użyciu kreatora lub programu PowerShell.

Przed rozpoczęciem

Aby wykonać kroki opisane w tym artykule, musisz być administratorem globalnym platformy Microsoft 365 lub administratorem łącznika shifts.

Rola administratora łącznika Shifts to rola niestandardowa, którą tworzysz w identyfikatorze Microsoft Entra i przypisujesz do użytkownika. Nazwa roli musi być "Shifts connector admin". Rola nie musi mieć żadnych określonych uprawnień, chociaż podczas jej tworzenia należy ustawić co najmniej jedno uprawnienie. Usługa opiera się na obecności roli na użytkowniku, a nie na jego uprawnieniach.

Aby dowiedzieć się więcej, zobacz Create and assign a custom role in Microsoft Entra ID (Tworzenie i przypisywanie roli niestandardowej w identyfikatorze Microsoft Entra ) oraz Assign Microsoft Entra roles to users (Przypisywanie ról microsoft entra do użytkowników). Pamiętaj, że utworzenie i zastosowanie roli do użytkownika może potrwać do 24 godzin.

Konfigurowanie środowiska

1. Zainstaluj program PowerShell w wersji 7 lub nowszej. Aby uzyskać szczegółowe wskazówki, zobacz Instalowanie programu PowerShell w systemie Windows.

2. Uruchom program PowerShell w trybie administratora.

3. Zainstaluj moduł Programu PowerShell programu Microsoft Graph.

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

   Sprawdź, czy jest to wersja 1.6.1 lub nowsza.

   Get-InstalledModule Microsoft.Graph 
   

4. Zainstaluj moduł Programu PowerShell w wersji zapoznawczej aplikacji Teams.

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

   Sprawdź, czy jest to co najmniej wersja 4.7.0 i czy zawiera polecenia cmdlet łącznika Shifts.

   Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection* 
   

5. Ustaw program PowerShell, aby zakończyć działanie, jeśli wystąpi błąd podczas uruchamiania skryptu.

   $ErrorActionPreference = "Stop" 
   

6. Włącz uruchamianie skryptów w systemie Windows.

   Set-ExecutionPolicy bypass 
   

7. Połącz się z usługą Teams.

   Connect-MicrosoftTeams
   

   Po wyświetleniu monitu zaloguj się przy użyciu poświadczeń administratora. Teraz skonfigurowano uruchamianie skryptów w tym artykule i poleceń cmdlet łącznika Shifts.

Sprawdzanie stanu konfiguracji połączenia

Aby sprawdzić stan połączenia skonfigurowanego przy użyciu identyfikatora operacji otrzymanego w wiadomości e-mail, wykonaj następujące kroki:

1. Skonfiguruj środowisko (jeśli jeszcze tego nie zrobiono).

2. Uruchom następujące polecenie: To polecenie zapewnia ogólny stan mapowań zespołu dla połączenia.

   Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>
   

Aby dowiedzieć się więcej, zobacz Get-CsTeamsShiftsConnectionOperation.

Wyświetlanie raportu o błędach dla połączenia

Możesz uruchomić raport zawierający szczegóły błędu dla połączenia. Raport zawiera listę mapowań zespołu i użytkowników, które zakończyły się powodzeniem i niepowodzeniem. Zawiera również informacje o wszelkich problemach związanych z kontami skojarzonymi z połączeniem.

1. Skonfiguruj środowisko (jeśli jeszcze tego nie zrobiono).

2. Pobierz listę raportów o błędach dla połączenia.

   Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>
   

3. Aby wyświetlić określony raport o błędach, uruchom następujące polecenie:

   Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>
   

Aby dowiedzieć się więcej, zobacz Get-CsTeamsShiftsConnectionErrorReport.

Rozwiązywanie problemów z błędami połączenia

Błędy mapowania użytkowników

Błędy mapowania użytkowników mogą wystąpić, jeśli co najmniej jeden użytkownik w wystąpieniu programu WFM nie jest członkiem zamapowanego zespołu w usłudze Teams. Aby rozwiązać ten problem, upewnij się, że użytkownicy w zamapowanym zespole pasują do użytkowników w wystąpieniu programu WFM.

Aby wyświetlić szczegóły niezamapowanych użytkowników, skonfiguruj środowisko (jeśli jeszcze tego nie zrobiono), a następnie uruchom następujący skrypt.

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

Błędy autoryzacji konta

Błędy autoryzacji konta mogą wystąpić, jeśli konto usługi WFM lub poświadczenia konta systemowego platformy Microsoft 365 są nieprawidłowe lub nie mają wymaganych uprawnień.

Aby zmienić konto usługi WFM lub poświadczenia konta systemowego platformy Microsoft 365 dla połączenia, możesz uruchomić polecenie cmdlet Set-CsTeamsShiftsConnectionInstance lub użyć skryptu programu PowerShell w sekcji Zmienianie ustawień połączenia w tym artykule.

Zmienianie ustawień połączenia

Użyj tego skryptu, aby zmienić ustawienia połączenia. Ustawienia, które można zmienić, obejmują konto usługi WFM i hasło, konto systemowe platformy Microsoft 365, mapowania zespołów i ustawienia synchronizacji.

Ustawienia synchronizacji obejmują częstotliwość synchronizacji (w minutach) i dane harmonogramu synchronizowane między systemem programu WFM i funkcją Shifts. Dane harmonogramu są definiowane w następujących parametrach, które można wyświetlić, uruchamiając polecenie Get-CsTeamsShiftsConnectionConnector.

• Parametr enabledConnectorScenarios definiuje dane synchronizowane z systemu WFM do funkcji Shifts. Opcje to Shift, SwapRequest, OfferShiftRequest, UserShiftPreferences, OpenShift, OpenShiftRequest, TimeOff, . TimeOffRequest

• Parametr enabledWfiScenarios definiuje dane synchronizowane z funkcji Shifts do systemu WFM. Opcje to SwapRequest, OfferShiftRequest, OpenShiftRequest, TimeOffRequest, UserShiftPreferences.

  Uwaga

  Jeśli nie chcesz synchronizować otwartych zmian, żądań open shift, żądań zamiany lub żądań limitu czasu między zmianami a systemem WFM, musisz wykonać kolejny krok, aby ukryć tę funkcję w usłudze Shifts. Po uruchomieniu tego skryptu upewnij się, że wykonaj kroki opisane w sekcji Wyłączanie otwartych zmian, otwieranie żądań przesunięć, żądania zamiany i żądania dotyczące limitu czasu w dalszej części tego artykułu.

  Ważna

  W przypadku ustawień, których nie chcesz zmieniać, musisz ponownie wprowadzić oryginalne ustawienia po wyświetleniu monitu przez skrypt.

Skonfiguruj środowisko (jeśli jeszcze tego nie zrobiono), a następnie uruchom następujący skrypt.

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

Wyłączanie otwartych zmian, żądań otwartych zmian, żądań zamiany i żądań czasu wolnego

Aby ukryć otwarte zmiany, żądania zamiany i żądania dotyczące limitu czasu w usłudze Shifts, użyj typu zasobu harmonogramu interfejsu API programu Graph, aby ustawić następujące parametry false dla każdego zespołu zamapowanego na wystąpienie programu WFM:

• Otwarte zmiany: openShiftsEnabled
• Żądania zamiany: swapShiftsRequestsEnabled
• Żądania dotyczące limitu czasu: timeOffRequestsEnabled
• Żądania zmiany oferty: offerShiftRequestsEnabled

Aby ukryć żądania otwartych zmian w obszarze Zmiany, przejdź do pozycji Ustawienia w obszarze Zmiany, a następnie wyłącz ustawienie Otwórz zmiany .

Usuń mapowanie zespołu z jednego połączenia i mapowanie go na inne połączenie

Jeśli chcesz odmapować zespół z jednego połączenia i zamapować go na inne połączenie:

1. Skonfiguruj środowisko (jeśli jeszcze tego nie zrobiono).

2. Wyświetl listę wszystkich mapowań zespołu dla połączenia.

   Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>
   

3. Usuń mapowanie zespołu z połączenia.

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

4. Zamapuj zespół na inne połączenie.

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

Aby dowiedzieć się więcej, zobacz Get-CsTeamsShiftsConnectionTeamMap, Remove-CsTeamsShiftsConnectionTeamMap i New-CsTeamsShiftsConnectionTeamMap.

Wyłączanie synchronizacji dla połączenia

Użyj tego skryptu, aby wyłączyć synchronizację dla połączenia. Pamiętaj, że ten skrypt nie usuwa ani nie usuwa połączenia. Powoduje to wyłączenie synchronizacji, dzięki czemu żadne dane nie są synchronizowane między funkcją Shifts i systemem WFM dla określonego połączenia.

Skonfiguruj środowisko (jeśli jeszcze tego nie zrobiono), a następnie uruchom następujący skrypt.

#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"
}

Lista komunikatów o błędach

Oto lista komunikatów o błędach, które mogą wystąpić, oraz informacje ułatwiające ich rozwiązanie.

Przesunięcia poleceń cmdlet łącznika

Aby uzyskać pomoc dotyczącą poleceń cmdlet łącznika shifts, wyszukaj ciąg CsTeamsShiftsConnection w dokumentacji polecenia cmdlet programu PowerShell usługi Teams. Poniżej przedstawiono linki do niektórych często używanych poleceń cmdlet.

• Get-CsTeamsShiftsConnectionOperation
• New-CsTeamsShiftsConnectionInstance
• Get-CsTeamsShiftsConnectionInstance
• Set-CsTeamsShiftsConnectionInstance
• Update-CsTeamsShiftsConnectionInstance
• Remove-CsTeamsShiftsConnectionInstance
• Test-CsTeamsShiftsConnectionValidate
• New-CsTeamsShiftsConnectionTeamMap
• Get-CsTeamsShiftsConnectionTeamMap
• Remove-CsTeamsShiftsConnectionTeamMap
• Get-CsTeamsShiftsConnectionConnector
• Get-CsTeamsShiftsConnectionSyncResult
• Get-CsTeamsShiftsConnectionWfmUser
• Get-CsTeamsShiftsConnectionWfmTeam
• Get-CsTeamsShiftsConnectionErrorReport
• Remove-CsTeamsShiftsScheduleRecord

Artykuły pokrewne

• Łączniki aplikacji Zmiany
• Używanie kreatora łącznika Shifts do łączenia funkcji Shifts z rozwiązaniem UKG Pro Workforce Management
• Łączenie funkcji Shift z rozwiązaniem UKG Pro Workforce Management przy użyciu programu PowerShell
• Zarządzanie połączeniem shifts z usługą UKG Pro Workforce Management przy użyciu centrum administracyjnego platformy Microsoft 365
• Zarządzanie aplikacją Zmiany
• Omówienie programu PowerShell w usłudze Teams