使用 PowerShell 管理與 UKG Pro Workforce Management 的 Shifts 連線

發行項
02/13/2024
適用於:

Microsoft Teams, Microsoft 365 for frontline workers

概觀

適用於 UKG Pro Workforce Management 的 Microsoft Teams Shifts 連接器可讓您將 Microsoft Teams 中的 Shifts 應用程式與 UKG Pro Workforce Management 整合 (UKG Pro WFM) 。您的第一線員工可以從 Shifts 中順暢地檢視及管理其在 UKG Pro WFM 中的排程。

您可以使用 Microsoft 365 系統管理中心中的班次連接器精靈或 PowerShell 來設定連線。設定連線之後，您可以使用 Shifts 連接器 PowerShell Cmdlet 來管理它。

本文描述如何使用 PowerShell 來執行下列作業：

檢查連線設定狀態
檢視連線的錯誤報告
解決連線錯誤
變更連線設定
將團隊從一個連線取消對應，並將其與另一個連線對應
停用連線的同步

本文假設您已使用精靈或 PowerShell 設定與 UKG Pro WFM 的連線。

注意事項

您也可以在 Microsoft 365 系統管理中心管理您的連線。例如，您可以檢查健康情況狀態，並存取精靈來變更連線設定。若要深入瞭解，請參閱使用 Microsoft 365 系統管理中心來管理與 UKG Pro Workforce Management 的 Shifts 連線。

開始之前

您必須是 Microsoft 365 全域管理員或 Shifts 連接器系統管理員，才能完成本文中的步驟。

Shifts 連接器系統管理員角色是您在 Microsoft Entra ID 中建立並指派給使用者的自定義角色。此角色的名稱必須是「Shifts 連接器系統管理員」。此角色不需要具備任何特定權限，不過，當您建立此角色時，必須設定至少一個權限。此服務依賴使用者身上的角色存在，而不是其權限。

若要深入瞭解，請參閱在 Microsoft Entra ID 中建立和指派自定義角色和將 Microsoft Entra 角色指派給使用者。請記住，最多可能需要 24 小時的時間才能建立角色並套用至使用者。

重要事項

Microsoft 建議您使用權限最少的角色。這有助於改善貴組織的安全性。全域管理員是高度特殊許可權的角色，當您無法使用較不具特殊許可權的角色時，應該僅限於緊急案例。

設立您的環境

注意事項

執行本文中的任何命令或指令碼之前，請務必遵循下列步驟來設定您的環境。

安裝 PowerShell 版本 7 或更新版本。如需逐步指引，請參閱安裝 Windows 版 PowerShell。
在系統管理員模式下執行 PowerShell。

安裝 Microsoft Graph PowerShell 模組。

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

確認其版本為 1.6.1 或更新版本。

Get-InstalledModule Microsoft.Graph

安裝 Teams 預覽 PowerShell 模組。

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

確認其至少為 4.7.0 版，且包含 Shifts 連接器 Cmdlet。

Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection*

如果執行指令碼時發生錯誤，請將 PowerShell 設定為結束。
```
$ErrorActionPreference = "Stop" 
```
啟用指令碼以在 Windows 中執行。
```
Set-ExecutionPolicy bypass 
```

連接至 Teams。
```
Connect-MicrosoftTeams
```
當您看到提示時，使用您的系統管理員認證進行登入。現在您已完成設定，將可執行此文章中的指令碼和班次連接器 Cmdlets。

檢查連線設定狀態

若要使用您在電子郵件中收到的作業識別碼來檢查您所設定的連線狀態，請遵循下列步驟：

設定您的環境 (如果您尚未這麼做)。
執行下列指令：此命令提供您連線的團隊對應的整體狀態。
```
Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>
```

若要深入了解，請參閱 Get-CsTeamsShiftsConnectionOperation。

檢視連線的錯誤報告

您可以執行會顯示連線的錯誤詳細資料的報告。報告會列出成功和失敗的團隊和使用者對應。它也會提供與連線相關聯帳戶相關問題的資訊。

設定您的環境 (如果您尚未這麼做)。

取得連線的錯誤報告清單。

Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>

若要檢視特定錯誤報告，請執行下列命令：

Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>

若要深入了解，請參閱 Get-CsTeamsShiftsConnectionErrorReport。

注意事項

如需錯誤訊息的完整清單，請參閱本文稍後的錯誤訊息清單。

解決連線錯誤

使用者對應錯誤

如果WFM實例中的一或多個使用者不是Teams中對應小組的成員，可能會發生用戶對應錯誤。若要解決此問題，請確定對應小組中的使用者符合WFM實例中的使用者。

若要檢視未對應使用者的詳細資訊，請設定您的環境 (如果您尚未這麼做)，然後執行下列指令碼。

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

帳戶授權錯誤

如果WFM服務帳戶或 Microsoft 365 系統帳戶認證不正確或沒有必要許可權，可能會發生帳戶授權錯誤。

若要變更 WFM 服務帳戶或Microsoft連線的 365 系統帳戶認證，您可以執行 Set-CsTeamsShiftsConnectionInstance Cmdlet，或在本文的變更連線設定一節中使用 PowerShell 腳本。

變更連線設定

使用此指令碼來變更連線設定。您可以變更的設定包括 WFM 服務帳戶和密碼、Microsoft 365 系統帳戶、小組對應和同步處理設定。

同步設定包括同步頻率 (以分鐘為單位) ，以及 WFM 系統與 Shifts 之間同步的排程數據。排程資料會於下列參數中定義，您可以執行 Get-CsTeamsShiftsConnectionConnector 來檢視它。

enabledConnectorScenarios 參數會定義從 WFM 系統同步至 Shifts 的數據。選項為Shift、SwapRequest、、、OfferShiftRequest、OpenShiftUserShiftPreferences、OpenShiftRequest、TimeOff、 TimeOffRequest。
enabledWfiScenarios 參數會定義從 Shifts 同步至 WFM 系統的數據。選項為 SwapRequest、OfferShiftRequest、OpenShiftRequest、、。UserShiftPreferencesTimeOffRequest

注意事項

如果您選擇不要在 Shifts 和 WFM 系統之間同步開啟班次、開啟班次要求、交換要求或逾時要求，則需要執行另一個步驟來隱藏 Shifts 中的功能。執行此指令碼之後，請確定您遵循本文稍後的停用待認領班次、待認領班次要求、換班要求和休假要求一節中的步驟。

重要事項

對於您不想變更的設定，當指令碼提示時，您必須重新輸入原始設定。

設定您的環境 (如果您尚未這麼做)，然後執行下列指令碼。

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

停用待認領班次、待認領班次要求、換班要求和休假要求

重要事項

只有當您選擇使用本文稍早的變更連線設定一節中的指令碼，或是使用 Set-CsTeamsShiftsConnectionInstance Cmdlet，來停用待認領班次、待認領班次要求、換班要求或休假要求時，才遵循這些步驟。完成此步驟會在班次中隱藏該空缺。如果沒有這第二個步驟，使用者仍會看到班次中的空缺，並將遇到「不支援的作業」錯誤訊息 (如果他們嘗試使用它的話)。

若要在 Shifts 中隱藏開啟的班次、交換要求和逾時要求，請使用圖形 API 排程資源類型，針對您對應至 WFM 實例的每個小組，將下列參數 false 設定為：

待認領班次: openShiftsEnabled
交換要求： swapShiftsRequestsEnabled
請假要求: timeOffRequestsEnabled
供應項目轉移要求： offerShiftRequestsEnabled

若要隱藏班次中的待認領班次要求，請前往班次中的 [設定]，然後關閉 [待認領班次] 設定。

將團隊從一個連線取消對應，並將其與另一個連線對應

注意事項

這兩個連線的 Microsoft 365 系統帳戶必須是相同的。如果不同，您就會收到「此指定執行者設定檔沒有團隊擁有者權限」錯誤訊息。

如果您想要將團隊從一個連線取消對應，並將其與另一個連線對應：

設定您的環境 (如果您尚未這麼做)。

檢視連線的所有團隊對應清單。

Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>

從連線移除團隊對應。

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

將團隊與另一個連線對應。

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

若要深入了解，請參閱 Get-CsTeamsShiftsConnectionTeamMap、Remove-CsTeamsShiftsConnectionTeamMap 和 New-CsTeamsShiftsConnectionTeamMap。

停用連線的同步

使用此指令碼來停用連線的同步。請記住，此指令碼不會移除或刪除連線。它會關閉同步處理，讓 Shifts 和 WFM 系統之間不會針對您指定的連線同步處理任何數據。

設定您的環境 (如果您尚未這麼做)，然後執行下列指令碼。

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

錯誤訊息清單

以下是您可能會遇到的錯誤訊息清單，以及可協助您解決錯誤訊息的資訊。

錯誤類型	錯誤詳細數據	解決方案
無法驗證員工管理系統。	您所提供的員工管理系統帳戶認證無效，或此帳戶沒有必要的許可權。	在連線設定中更新您的 WFM 服務帳戶認證。若要執行這項操作，請執行下列任一動作：在 Microsoft 365 系統管理中心，選擇 [連接器管理控制台] 頁面上連線旁邊的 [ 編輯 ]。使用 Set-CsTeamsShiftsConnectionInstance 或 Update-CsTeamsShiftsConnectionInstance Cmdlet。使用此 PowerShell 腳本。
無法驗證圖形。	驗證失敗。請確定您已為指定的動作專案輸入有效的認證，並具有必要的許可權。	請確定您的 Microsoft 365 系統帳戶 (也稱為指定的動作專案) 已新增為小組擁有者。或者，在聯機設定中更新Microsoft 365 系統帳戶認證。
某些用戶無法正確地對應	某些用戶的對應失敗： <X> 成功、 <X> 失敗的 AAD 使用者 () ，以及 <X> 失敗的員工管理系統使用者 () 。	使用 Get-CsTeamsShiftsConnectionSyncResult Cmdlet 或此 PowerShell 腳本來識別對應失敗的使用者。請確定對應小組中的使用者符合 WFM 實例中的使用者。
無法在此批次中對應小組或小組。	這個指定的動作專案配置檔沒有小組擁有權權。	請確定您的 Microsoft 365 系統帳戶 (也稱為指定的動作專案) 已新增為小組擁有者。如果您已變更Microsoft 365 系統帳戶，請將該帳戶新增為小組擁有者，並更新連線設定以使用該帳戶。
	此小組已對應至現有的連接器實例。	使用 Remove-CsTeamsShiftsConnectionTeamMap Cmdlet，將小組從現有的連接器實例中取消對應。或者，建立新的連線以重新對應小組。
	此時區無效。傳入的時區不是使用 tz 資料庫格式。	請確定時區正確無誤，然後重新對應小組。
	找不到此連接器實例。	將小組對應至現有的連線。
	找不到此 AAD 小組。	請確定小組存在，或建立新的小組。

班次連接器 Cmdlets

如需班次連接器 Cmdlet 的說明，請在 Teams PowerShell Cmdlet 參考中搜尋 CsTeamsShiftsConnection。以下是一些常用 Cmdlet 的連結。

共用方式為

使用 PowerShell 管理與 UKG Pro Workforce Management 的 Shifts 連線

概觀

開始之前

設立您的環境

檢查連線設定狀態

檢視連線的錯誤報告

解決連線錯誤

使用者對應錯誤

帳戶授權錯誤

變更連線設定

停用待認領班次、待認領班次要求、換班要求和休假要求

將團隊從一個連線取消對應，並將其與另一個連線對應

停用連線的同步

錯誤訊息清單

班次連接器 Cmdlets

意見反應

其他資源

共用方式為

使用 PowerShell 管理與 UKG Pro Workforce Management 的 Shifts 連線

概觀

開始之前

設立您的環境

檢查連線設定狀態

檢視連線的錯誤報告

解決連線錯誤

使用者對應錯誤

帳戶授權錯誤

變更連線設定

停用待認領班次、待認領班次要求、換班要求和休假要求

將團隊從一個連線取消對應，並將其與另一個連線對應

停用連線的同步

錯誤訊息清單

班次連接器 Cmdlets

相關文章

意見反應

其他資源