Использование PowerShell для управления подключением смен к UKG Pro Workforce Management

  • Статья
  • Применяется к:
    Microsoft Teams, Microsoft 365 for frontline workers

Обзор

Соединитель Microsoft Teams Shifts для UKG Pro Workforce Management позволяет интегрировать приложение Shifts в Microsoft Teams с UKG Pro Workforce Management (UKG Pro WFM). Ваши сотрудники первой линии могут легко просматривать свои расписания и управлять ими в UKG Pro WFM из смен.

Вы можете использовать мастер соединителя приложения "Смены" в Центре администрирования Microsoft 365 или PowerShell, чтобы быстро настроить подключение. После настройки подключения вы можете управлять им с помощью командлетов PowerShell соединителя Shifts.

В этой статье описывается выполнение следующих действий с помощью PowerShell.

В этой статье предполагается, что вы уже настроили подключение к UKG Pro WFM с помощью мастера или PowerShell.

Примечание.

Вы также можете управлять подключением в Центре администрирования Microsoft 365. Например, можно проверить состояние работоспособности и получить доступ к мастеру, чтобы изменить параметры подключения. Дополнительные сведения см . в статье Использование Центра администрирования Microsoft 365 для управления подключением смен к UKG Pro Workforce Management.

Подготовка к работе

Для выполнения действий, описанных в этой статье, необходимо быть глобальным администратором Microsoft 365 или администратором соединителя Shifts.

Роль администратора соединителя Shifts — это настраиваемая роль, которую вы создаете в идентификаторе Microsoft Entra и назначаете пользователю. Роль должна иметь имя "Администратор соединителя Shifts". Роль не должна иметь каких-либо определенных разрешений, хотя при ее создании необходимо задать по крайней мере одно разрешение. Служба зависит от наличия роли для пользователя, а не от ее разрешений.

Дополнительные сведения см. в разделах Создание и назначение настраиваемой роли в Идентификаторе Microsoft Entra и Назначение ролей Microsoft Entra пользователям. Помните, что создание роли и ее применения к пользователю может занять до 24 часов.

Важно!

Microsoft рекомендует использовать роли с наименьшим количеством разрешений. Это помогает повысить безопасность вашей организации. Глобальный администратор — это роль с высоким уровнем привилегий, которая должна быть ограничена сценариями чрезвычайных ситуаций, когда вы не можете использовать менее привилегированную роль.

Настройка среды

Примечание.

Перед запуском команд или сценариев, указанных в этой статье, выполните следующие действия.

  1. Установите PowerShell версии 7 или более поздней. Пошаговые инструкции см. в разделе Установка PowerShell в Windows.

  2. Запустите PowerShell в режиме администратора.

  3. Установите модуль Microsoft Graph PowerShell.

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

    Убедитесь, что это версия 1.6.1 или более поздняя.

    Get-InstalledModule Microsoft.Graph

  4. Установите модуль Teams Preview PowerShell.

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

    Убедитесь, что версия не ниже 4.7.0 и содержит командлеты соединителя Shifts.

    Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection*

  5. Настройте PowerShell на выход, если при запуске скрипта возникает ошибка.

    $ErrorActionPreference = "Stop"

  6. Включите сценарии для выполнения в Windows.

    Set-ExecutionPolicy bypass

  1. Подключитесь к Teams.

    Connect-MicrosoftTeams

    При появлении запроса войдите в систему, используя свои учетные данные администратора. Теперь настройте запуск сценариев, описанных в этой статье, и командлетов соединителя Shifts.

Проверка состояния настройки подключения

Чтобы проверить состояние настроенного подключения с помощью идентификатора операции, полученного по электронной почте, выполните следующие действия.

  1. Настройте среду (если вы еще этого не сделали).

  2. Выполните следующую команду. Эта команда предоставляет сведения об общем состоянии сопоставлений команд для подключения.

    Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>

Подробнее см. в Get-CsTeamsShiftsConnectionOperation.

Просмотр отчета об ошибке для подключения

Вы можете запустить отчет с подробными сведениями об ошибке подключения. В отчете перечислены успешные и неудачные сопоставления команд и пользователей. В нем также содержится информация о любых проблемах, связанных с учетными записями, связанными с подключением.

  1. Настройте среду (если вы еще этого не сделали).

  2. Получите список отчетов об ошибках для подключения.

    Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>

  3. Чтобы просмотреть определенный отчет об ошибке, запустите следующую команду:

    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 или использовать сценарий PowerShell в разделе Изменение параметров подключения этой статьи.

Изменение параметров подключения

Используйте этот сценарий для изменения параметров подключения. К параметрам, которые можно изменить, относятся учетная запись службы WFM и пароль, системная учетная запись Microsoft 365, сопоставления команд и параметры синхронизации.

Параметры синхронизации включают частоту синхронизации (в минутах) и данные расписания, синхронизированные между системой WFM и shifts. Данные расписания определены в следующих параметрах, которые можно просмотреть, запустив Get-CsTeamsShiftsConnectionConnector.

  • Параметр enabledConnectorScenarios определяет данные, синхронизированные из системы WFM в shifts. Параметры: Shift, SwapRequest, OfferShiftRequest, UserShiftPreferences, OpenShift, OpenShiftRequest, TimeOff, . TimeOffRequest

  • Параметр enabledWfiScenarios определяет данные, синхронизированные из shifts в систему WFM. Параметры: SwapRequest, OfferShiftRequest, OpenShiftRequest, TimeOffRequest, UserShiftPreferences.

    Примечание.

    Если вы решили не синхронизировать открытые смены, открытые запросы на смену, запросы на переключение или запросы отгула между 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. Выполнение этого шага скрывает возможность в функции "Смены". Без этого второго шага пользователи по-прежнему будут видеть эту возможность в Shifts и получат сообщение об ошибке "неподдерживаемая операция", если попытаются ее использовать.

Чтобы скрыть открытые смены, запросы на переключение и запросы отгула в shifts, используйте тип ресурса расписания API Graph, чтобы задать следующие параметры false для каждой команды, сопоставленной с экземпляром WFM:

  • Открытые смены: openShiftsEnabled
  • Запросы на переключение: swapShiftsRequestsEnabled
  • Запросы на отгулы: timeOffRequestsEnabled
  • Запросы на смену предложения: offerShiftRequestsEnabled

Чтобы скрыть запросы на открытые смены в функции "Смены", перейдите в Настройки в сменах и отключите параметр Открывать смены.

Отмена сопоставления команды с одним подключением и сопоставление с другим подключением

Примечание.

В обоих подключениях должна использоваться одна и та же системная учетная запись Microsoft 365. Если это не так, вы получите сообщение об ошибке: "Этот профиль назначенного субъекта не имеет привилегий владельца команды".

Если вы хотите отменить сопоставление команды с одним подключением и выполнить сопоставление с другим подключением, сделайте следующее:

  1. Настройте среду (если вы еще этого не сделали).

  2. Просмотрите список всех сопоставлений команд для подключения.

    Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>

  3. Удалите сопоставление команды из подключения.

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

  4. Сопоставьте команду с другим подключением.

    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 в параметрах подключения. Для этого воспользуйтесь одним из следующих способов:
Не удается проверить подлинность Graph. Сбой проверки подлинности. Убедитесь, что вы ввели допустимые учетные данные для указанного субъекта и имеете необходимые разрешения. Убедитесь, что ваша системная учетная запись Microsoft 365 (также известная как назначенный субъект) добавлена в качестве владельца команды.
Или обновите учетные данные системной учетной записи Microsoft 365 в параметрах подключения.
Некоторые пользователи не смогли правильно сопоставить Сбой сопоставления для некоторых пользователей: <X> успешно, <пользователи AAD Сбоем X> и <пользователи системы управления персоналом X> сбоем. Используйте командлет Get-CsTeamsShiftsConnectionSyncResult или этот скрипт PowerShell , чтобы определить пользователей, для которых не удалось выполнить сопоставление. Убедитесь, что пользователи в сопоставленной команде совпадают с пользователями в экземпляре WFM.
Не удается сопоставить команду или команды в этом пакете. Этот профиль субъекта не имеет прав владения командой. Убедитесь, что ваша системная учетная запись Microsoft 365 (также известная как назначенный субъект) добавлена в качестве владельца команды.
Если вы изменили системную учетную запись Microsoft 365, добавьте ее в качестве владельца команды и обновите параметры подключения, чтобы использовать эту учетную запись.
Эта команда уже сопоставлена с существующим экземпляром соединителя. Отмените сопоставление команды из существующего экземпляра соединителя с помощью командлета Remove-CsTeamsShiftsConnectionTeamMap . Или создайте новое подключение для повторного сопоставления команды.
Этот часовой пояс недопустим. Переданный часовой пояс не использует формат базы данных tz. Убедитесь, что часовой пояс указан правильно, а затем переназначьте команду.
Не удается найти этот экземпляр соединителя. Сопоставьте команду с существующим подключением.
Не удалось найти эту команду AAD. Убедитесь, что команда существует, или создайте новую команду.

Командлеты соединителя смен

Чтобы получить справку по командлетам соединителя "Смены", выполните поиск CsTeamsShiftsConnection в справочнике по командлетам Teams PowerShell. Вот ссылки на некоторые часто используемые командлеты.