Compartilhar via

Use o PowerShell para gerenciar sua conexão do Shifts com o UKG Pro Workforce Management

  • Artigo
  • Aplica-se a:
    Microsoft Teams, Microsoft 365 for frontline workers

Visão geral

O conector do Microsoft Teams Shifts para UKG Pro Workforce Management permite integrar o aplicativo Shifts no Microsoft Teams ao UKG Pro Workforce Management (UKG Pro WFM). Os trabalhadores da linha de frente podem exibir e gerenciar perfeitamente seus agendamentos no UKG Pro WFM de dentro do Shifts.

Você pode usar o Assistente do conector de Turnos no centro de administração do Microsoft 365 ou PowerShell para configurar uma conexão. Depois que uma conexão for configurada, você poderá gerenciá-la usando cmdlets do PowerShell do conector shifts.

Este artigo descreve como usar o PowerShell para fazer o seguinte:

Este artigo pressupõe que você já configurou uma conexão com o UKG Pro WFM, usando o assistente ou o PowerShell.

Observação

Você também pode gerenciar sua conexão no Centro de administração do Microsoft 365. Por exemplo, você pode marcar o status de integridade e acessar o assistente para alterar as configurações de conexão. Para saber mais, confira Usar o Centro de administração do Microsoft 365 para gerenciar sua conexão do Shifts com o UKG Pro Workforce Management.

Antes de começar

Você deve ser um administrador global do Microsoft 365 ou um administrador conector do Shifts para concluir as etapas deste artigo.

A função de administrador do conector Shifts é uma função personalizada que você cria em Microsoft Entra ID e atribui a um usuário. O nome da função deve ser "Administrador do conector de turnos". A função não precisa ter permissões específicas, embora pelo menos uma permissão deva ser definida ao criá-la. O serviço depende da presença da função no usuário e não de suas permissões.

Para saber mais, confira Criar e atribuir uma função personalizada em Microsoft Entra ID e Atribuir Microsoft Entra funções aos usuários. Lembre-se de que pode levar até 24 horas para que a função seja criada e aplicada a um usuário.

Configurar seu ambiente

Observação

Certifique-se de seguir estas etapas para configurar seu ambiente antes de executar qualquer um dos comandos ou scripts deste artigo.

  1. Instale o PowerShell versão 7 ou posterior. Para obter orientações passo a passo, consulte Instalando o PowerShell no Windows.

  2. Execute o PowerShell no modo administrador.

  3. Instalar o módulo PowerShell do Microsoft Graph.

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

    Verifique se é a versão 1.6.1 ou posterior.

    Get-InstalledModule Microsoft.Graph

  4. Instalar o módulo PowerShell de Visualização do Teams.

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

    Verifique se é pelo menos a versão 4.7.0 e contém os cmdlets do conector Shifts.

    Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection*

  5. Defina o PowerShell para sair se ocorrer um erro ao executar o script.

    $ErrorActionPreference = "Stop"

  6. Habilitar os scripts a serem executados no Windows.

    Set-ExecutionPolicy bypass

  1. Conectar-se ao Teams.

    Connect-MicrosoftTeams

    Quando for solicitado, entre usando suas credenciais de administrador. Agora você está configurado para executar os scripts neste artigo e nos cmdlets do conector do Shifts.

Verificar o status de configuração da conexão

Para marcar o status da conexão que você configurou usando a ID da operação recebida por email, siga estas etapas:

  1. Configure seu ambiente (se ainda não o fez).

  2. Execute o seguinte comando: Este comando lhe dá o status geral dos mapeamentos da equipe para a conexão.

    Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>

Para saber mais, consulte Get-CsTeamsShiftsConnectionOperation.

Exibir um relatório de erro para uma conexão

Você pode executar um relatório que mostra detalhes de erro para uma conexão. O relatório lista a equipe e os mapeamentos de usuários que tiveram sucesso e falharam. Ele também fornece informações sobre quaisquer questões relacionadas às contas associadas à conexão.

  1. Configure seu ambiente (se ainda não o fez).

  2. Obtenha uma lista de relatórios de erro para uma conexão.

    Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>

  3. Para exibir um relatório de erro específico, execute o seguinte comando:

    Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>

Para saber mais, consulte Get-CsTeamsShiftsConnectionErrorReport.

Observação

Para obter uma lista completa de mensagens de erro, consulte Lista de mensagens de erro mais adiante neste artigo.

Resolver erros de conexão

Erros de mapeamento de usuário

Erros de mapeamento de usuário podem ocorrer se um ou mais usuários em uma instância de WFM não forem membros da equipe mapeada no Teams. Para resolve esse problema, verifique se os usuários da equipe mapeada correspondem aos usuários na instância WFM.

Para exibir detalhes de usuários não mapeados, configure seu ambiente (se ainda não o fez) e então execute o seguinte script.

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

Erros de autorização de conta

Erros de autorização da conta podem ocorrer se as credenciais da conta de serviço WFM ou da conta do sistema do Microsoft 365 estiverem incorretas ou não tiverem as permissões necessárias.

Para alterar sua conta de serviço WFM ou as credenciais da conta do sistema do Microsoft 365 para a conexão, você pode executar o cmdlet Set-CsTeamsShiftsConnectionInstance ou usar o script do PowerShell na seção Alterar configurações de conexão deste artigo.

Alterar configurações de conexão

Use este script para alterar as configurações de conexão. As configurações que você pode alterar incluem sua conta de serviço WFM e senha, conta do sistema microsoft 365, mapeamentos de equipe e configurações de sincronização.

As configurações de sincronização incluem a frequência de sincronização (em minutos) e os dados de agendamento sincronizados entre seu sistema WFM e Shifts. Os dados de cronograma são definidos nos seguintes parâmetros, que você pode exibir executando Get-CsTeamsShiftsConnectionConnector.

  • O parâmetro EnableedConnectorScenarios define dados sincronizados do sistema de WFM para Shifts. As opções são Shift, SwapRequest, OfferShiftRequest, UserShiftPreferences, OpenShift, OpenShiftRequest, TimeOff, TimeOffRequest.

  • O parâmetro habilitadoWfiScenarios define dados sincronizados de Shifts para seu sistema WFM. As opções são SwapRequest, OfferShiftRequest, OpenShiftRequest, TimeOffRequest, UserShiftPreferences.

    Observação

    Se você optar por não sincronizar turnos abertos, abrir solicitações de turno, solicitações de troca ou solicitações de tempo limite entre Shifts e seu sistema de WFM, haverá outra etapa que você precisa fazer para ocultar a funcionalidade em Turnos. Após executar este script, certifique-se de seguir as etapas na seção Desabilitar vagas abertas de turnos, solicitações de vagas abertas de turnos, pedidos de troca de turno e pedidos de folga mais adiante neste artigo.

    Importante

    Para as configurações que você não quer alterar, você precisará entrar novamente nas configurações originais quando for solicitado pelo script.

Configure seu ambiente (se ainda não o fez), e então execute o seguinte script.

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

Desabilitar vagas abertas de turnos, solicitações de vagas abertas de turnos, pedidos de troca de turno e pedidos de folga

Importante

Siga estas etapas somente se você optar por desabilitar vagas abertas de turnos, solicitações de vagas abertas de turno, pedidos de troca de turno ou pedidos de folga usando o script na seção Alterar configurações de conexão, anteriormente neste artigo, ou usando o cmdlet Set-CsTeamsShiftsConnectionInstance. A conclusão desta etapa oculta a funcionalidade em Turnos. Sem esta segunda etapa, os usuários ainda verão a funcionalidade em Turnos, e receberão uma mensagem de erro de "operação sem suporte" se tentarem usá-la.

Para ocultar turnos abertos, solicitações de troca e solicitações de tempo limite em Turnos, use o tipo de recurso de agendamento API do Graph para definir os seguintes parâmetros para false cada equipe mapeada para uma instância de WFM:

  • Vagas abertas de turnos: openShiftsEnabled
  • Solicitações de troca: swapShiftsRequestsEnabled
  • Pedidos de folga: timeOffRequestsEnabled
  • Solicitações de turno de oferta: offerShiftRequestsEnabled

Para ocultar solicitações de vagas abertas de turnos no Turnos, vá para as Configurações em Turnos e desabilite a configuração Vagas abertas de Turnos.

Desmapear uma equipe de uma conexão e mapeá-la para outra conexão

Observação

A conta de sistema Microsoft 365 deve ser a mesma para ambas as conexões. Se não for, você receberá uma mensagem de erro "Este perfil de ator designado não tem privilégios de propriedade da equipe".

Se você quiser desmapear uma equipe a partir de uma conexão e mapeá-la para outra conexão:

  1. Configure seu ambiente (se ainda não o fez).

  2. Exibir uma lista de todos os mapeamentos da equipe para uma conexão.

    Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>

  3. Remover um mapeamento da equipe da conexão.

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

  4. Mapear a equipe para outra conexão.

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

Para saber mais, consulte Get-CsTeamsShiftsConnectionTeamMap, Remove-CsTeamsShiftsConnectionTeamMap e New-CsTeamsShiftsConnectionTeamMap.

Desabilitar sincronização para uma conexão

Use este script para desabilitar a sincronização de uma conexão. Tenha em mente que este script não remove ou exclui uma conexão. Ele desativa a sincronização para que nenhum dado seja sincronizado entre Shifts e seu sistema de WFM para a conexão especificada.

Configure seu ambiente (se ainda não o fez), e então execute o seguinte script.

#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 de mensagens de erro

Aqui está a lista de mensagens de erro que você pode encontrar e informações para ajudá-lo a resolve-las.

Tipo de erro Detalhes do erro Resolução
Não é possível autenticar o sistema de gerenciamento de força de trabalho. As credenciais da conta do sistema de gerenciamento de força de trabalho fornecidas são inválidas ou essa conta não tem as permissões necessárias. Atualize suas credenciais de conta de serviço WFM nas configurações de conexão. Para fazer isso, siga um destes procedimentos:
Não é possível autenticar o Graph. Falha na autenticação. Verifique se você inseriu credenciais válidas para o ator designado e tenha as permissões necessárias. Certifique-se de que sua conta do sistema Microsoft 365 (também conhecida como ator designado) seja adicionada como proprietário da equipe.
Ou atualize suas credenciais de conta do sistema do Microsoft 365 nas configurações de conexão.
Alguns usuários falharam ao mapear corretamente O mapeamento falhou para alguns usuários: <X> foi bem-sucedido, <x> falha dos usuários do AAD e <dos> usuários do sistema de gerenciamento de força de trabalho com falha X. Use o cmdlet Get-CsTeamsShiftsConnectionSyncResult ou este script do PowerShell para identificar os usuários para os quais o mapeamento falhou. Verifique se os usuários da equipe mapeada correspondem aos usuários na instância WFM.
Não é possível mapear uma equipe ou equipes neste lote. Este perfil de ator designado não tem privilégios de propriedade da equipe. Certifique-se de que sua conta do sistema Microsoft 365 (também conhecida como ator designado) seja adicionada como proprietário da equipe.
Se você alterou sua conta do sistema Microsoft 365, adicione essa conta como proprietário da equipe e atualize as configurações de conexão para usar essa conta.
Essa equipe já está mapeada para uma instância de conector existente. Desmarca a equipe da instância do conector existente usando o cmdlet Remove-CsTeamsShiftsConnectionTeamMap . Ou crie uma nova conexão para remapear a equipe.
Esse fuso horário é inválido. O fuso horário passado não está usando o formato de banco de dados tz. Verifique se o fuso horário está correto e, em seguida, remapee a equipe.
Não é possível localizar essa instância do conector. Mapeie a equipe para uma conexão existente.
Essa equipe do AAD não pôde ser encontrada. Verifique se a equipe existe ou crie uma nova equipe.

Cmdlets do conector Shifts

Para obter ajuda com cmdlets do conector de Turnos, pesquise por CsTeamsShiftsConnection na referência de cmdlet do PowerShell no Teams. Aqui estão links para alguns cmdlets comumente usados.