使用 PowerShell 管理与 UKG Pro 劳动力管理的排班连接

项目
08/30/2024
适用于:

Microsoft Teams, Microsoft 365 for frontline workers

概述

使用适用于 UKG Pro 劳动力管理的 Microsoft Teams 排班连接器，可以将 Microsoft Teams 中的排班应用与 UKG Pro 劳动力管理 (UKG Pro WFM) 集成。一线员工可以在 UKG Pro WFM 中从班次中无缝查看和管理他们的日程安排。

可以使用 Microsoft 365 管理中心或 PowerShell 中的排班连接器向导来设置连接。设置连接后，可以使用 Shifts 连接器 PowerShell cmdlet 对其进行管理。

本文介绍如何使用 PowerShell 执行以下操作：

检查连接设置状态
查看连接的错误报告
解决连接错误
更改连接设置
从一个连接中取消映射团队并将其映射到另一个连接
禁用连接同步

本文假定你已使用向导或 PowerShell 设置与 UKG Pro WFM 的连接。

注意

还可以在 Microsoft 365 管理中心管理连接。例如，可以检查运行状况并访问向导以更改连接设置。若要了解详细信息，请参阅使用 Microsoft 365 管理中心管理与 UKG Pro 劳动力管理的排班连接。

开始之前

你必须是 Microsoft 365 全局管理员或排班连接器管理员才能完成本文中的步骤。

Shifts 连接器管理员角色是在 Entra ID Microsoft中创建并分配给用户的自定义角色。角色的名称必须是“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
```
出现提示时，请使用管理员凭据登录。现在你已设置完成，可以运行本文中的脚本和排班连接器 cmdlet 了。

检查连接设置状态

若要使用电子邮件中收到的操作 ID 检查设置的连接的状态，请执行以下步骤：

设置环境（如果尚未设置）。
运行以下命令：此命令提供连接团队映射的总体状态。
```
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 系统与排班之间同步的计划数据。计划数据在以下参数中定义，可以通过运行 Get-CsTeamsShiftsConnectionConnector 来查看这些参数。

enabledConnectorScenarios 参数定义从 WFM 系统同步到排班的数据。选项包括 Shift、、SwapRequest、UserShiftPreferencesOfferShiftRequest、OpenShiftOpenShiftRequest、TimeOff、、 TimeOffRequest。
enabledWfiScenarios 参数定义从排班同步到 WFM 系统的数据。选项包括 SwapRequest、OfferShiftRequest、、TimeOffRequestOpenShiftRequest、UserShiftPreferences。

注意

如果选择不同步排班、打开排班请求、交换请求或班次与 WFM 系统之间的休假请求，则需要执行另一个步骤来隐藏排班中的功能。运行此脚本后，请确保按照本文后面的 “禁用打开排班”、“打开排班请求”、“交换请求”和“休假请求”部分中的步骤操作。

重要

对于不想更改的设置，需要在脚本提示时重新输入原始设置。

设置环境（如果尚未设置），然后运行以下脚本。

#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 中的功能。如果没有第二步，用户仍会在 Shifts 中看到该功能，如果尝试使用该功能，则会收到“不受支持的操作”错误消息。

若要在排班中隐藏打开的班次、交换请求和休假请求，请使用 Graph 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。

禁用连接同步

使用此脚本禁用连接的同步。请记住，此脚本不会删除连接。它会关闭同步，以便在排班和 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 脚本。
无法对 Graph 进行身份验证。	身份验证失败。确保已为指定的执行组件输入有效凭据并具有所需的权限。	确保Microsoft 365 系统帐户 (也称为指定参与者) 添加为团队所有者。或者，在连接设置中更新 Microsoft 365 系统帐户凭据。
某些用户无法正确映射	某些用户的映射失败： <X> 成功、 <X> 失败的 AAD 用户 () 和 <X> 失败的劳动力管理系统用户 () 。	使用 Get-CsTeamsShiftsConnectionSyncResult cmdlet 或此 PowerShell 脚本标识映射失败的用户。确保映射团队中的用户与 WFM 实例中的用户匹配。
无法映射此批中的团队。	此指定参与者配置文件不具有团队所有权特权。	确保Microsoft 365 系统帐户 (也称为指定参与者) 添加为团队所有者。如果已更改 Microsoft 365 系统帐户，请将该帐户添加为团队所有者，并更新连接设置以使用该帐户。
	此团队已映射到现有连接器实例。	使用 Remove-CsTeamsShiftsConnectionTeamMap cmdlet 从现有连接器实例取消映射团队。或者，创建一个新连接来重新映射团队。
	此时区无效。传入的时区未使用 tz 数据库格式。	确保时区正确，然后重新映射团队。
	找不到此连接器实例。	将团队映射到现有连接。
	找不到此 AAD 团队。	确保团队存在或创建新团队。

排班连接器 cmdlet

有关排班连接器 cmdlet 的帮助，请在 Teams PowerShell cmdlet 参考中搜索 CsTeamsShiftsConnection。下面是一些常用 cmdlet 的链接。

通过

使用 PowerShell 管理与 UKG Pro 劳动力管理的排班连接

概述

开始之前

设置环境

检查连接设置状态

查看连接的错误报告

解决连接错误

用户映射错误

帐户授权错误

更改连接设置

禁用打开排班、打开排班请求、交换请求和休假请求

从一个连接中取消映射团队并将其映射到另一个连接

禁用连接同步

错误消息列表

排班连接器 cmdlet

反馈

其他资源

通过

使用 PowerShell 管理与 UKG Pro 劳动力管理的排班连接

概述

开始之前

设置环境

检查连接设置状态

查看连接的错误报告

解决连接错误

用户映射错误

帐户授权错误

更改连接设置

禁用打开排班、打开排班请求、交换请求和休假请求

从一个连接中取消映射团队并将其映射到另一个连接

禁用连接同步

错误消息列表

排班连接器 cmdlet

相关文章

反馈

其他资源