Utilizar o PowerShell para gerir a sua ligação de Turnos à Gestão da Força de Trabalho do UKG Pro

Visão Geral

O conector Microsoft Teams Shifts para UkG Pro Workforce Management permite-lhe integrar a aplicação Shifts no Microsoft Teams com a UkG Pro Workforce Management (UKG Pro WFM). Os seus trabalhadores de primeira linha podem ver e gerir facilmente os seus horários no UKG Pro WFM a partir dos Turnos.

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 de configurar uma ligação, pode geri-la com os cmdlets do PowerShell do conector Shifts.

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

Este artigo pressupõe que já configurou uma ligação ao UKG Pro WFM através do assistente ou do PowerShell.

Observação

Também pode gerir a sua ligação no centro de administração do Microsoft 365. Por exemplo, pode verificar o estado de funcionamento e aceder ao assistente para alterar as definições de ligação. Para saber mais, consulte Utilizar o centro de administração do Microsoft 365 para gerir a sua ligação shifts à UkG Pro Workforce Management.

Antes de começar

Tem de ser um Administrador Global do Microsoft 365 ou um administrador do conector do Shifts para concluir os passos neste artigo.

A função de administrador do conector Shifts é uma função personalizada que cria no Microsoft Entra ID e atribui a um utilizador. 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, consulte Criar e atribuir uma função personalizada no Microsoft Entra ID e Atribuir funções do Microsoft Entra aos utilizadores. Lembre-se de que pode levar até 24 horas para que a função seja criada e aplicada a um usuário.

Importante

A Microsoft recomenda que você use funções com o menor número de permissões. Isto ajuda a melhorar a segurança da sua organização. O Administrador Global é uma função altamente privilegiada que deve ser limitada a cenários de emergência quando não pode utilizar uma função com menos privilégios.

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 verificar o estado da ligação que configurou com o ID da operação que recebeu por e-mail, siga estes passos:

  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 das mensagens de erro, consulte Lista de mensagens de erro mais à frente neste artigo.

Resolver erros de conexão

Erros de mapeamento de usuário

Podem ocorrer erros de mapeamento de utilizadores se um ou mais utilizadores numa instância do WFM não forem membros da equipa mapeada no Teams. Para resolver este problema, certifique-se de que os utilizadores na equipa mapeada correspondem aos utilizadores na instância do 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

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

Para alterar a conta de serviço do WFM ou as credenciais da conta de sistema do Microsoft 365 para a ligação, pode executar o cmdlet Set-CsTeamsShiftsConnectionInstance ou utilizar o script do PowerShell na secção Alterar definições de ligação deste artigo.

Alterar configurações de conexão

Use este script para alterar as configurações de conexão. As definições que pode alterar incluem a sua conta de serviço WFM e palavra-passe, conta de sistema do Microsoft 365, mapeamentos de equipa e definições de sincronização.

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

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

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

    Observação

    Se optar por não sincronizar turnos abertos, pedidos de turno abertos, pedidos de troca ou pedidos de folga entre Turnos e o seu sistema WFM, tem de efetuar outro passo para ocultar a capacidade 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, pedidos de troca e pedidos de folga em Turnos, utilize o tipo de recurso de agendamento da Graph API para definir os seguintes parâmetros para false cada equipa que mapeou para uma instância do WFM:

  • Vagas abertas de turnos: openShiftsEnabled
  • Pedidos de troca: swapShiftsRequestsEnabled
  • Pedidos de folga: timeOffRequestsEnabled
  • Pedidos 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. Desativa a sincronização para que não sejam sincronizados dados entre Shifts e o seu sistema WFM para a ligação que especificar.

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

Eis a lista de mensagens de erro que pode encontrar e informações para o ajudar a resolvê-las.

Tipo de erro Detalhes do erro Resolução
Não é possível autenticar o sistema de gestão da força de trabalho. As credenciais da conta do sistema de gestão da força de trabalho que forneceu são inválidas ou esta conta não tem as permissões necessárias. Atualize as credenciais da conta de serviço do WFM nas definições de ligação. Para fazer isso, siga um destes procedimentos:
Não é possível autenticar o Graph. Falha na autenticação. Certifique-se de que introduziu credenciais válidas para o ator designado e tem as permissões necessárias. Certifique-se de que a sua conta de sistema do Microsoft 365 (também conhecida como ator designado) é adicionada como proprietária da equipa.
Em alternativa, atualize as credenciais da conta de sistema do Microsoft 365 nas definições de ligação.
Alguns utilizadores não conseguiram mapear corretamente Falha no mapeamento para alguns utilizadores: <X> com êxito, <X> utilizadores falhados do AAD e <X> utilizadores do sistema de gestão da força de trabalho com falha. Utilize o cmdlet Get-CsTeamsShiftsConnectionSyncResult ou este script do PowerShell para identificar os utilizadores para os quais o mapeamento falhou. Certifique-se de que os utilizadores na equipa mapeada correspondem aos utilizadores na instância do WFM.
Não é possível mapear uma equipa ou equipas neste lote. Este perfil de ator designado não tem privilégios de propriedade de equipa. Certifique-se de que a sua conta de sistema do Microsoft 365 (também conhecida como ator designado) é adicionada como proprietário da equipa.
Se tiver alterado a sua conta de sistema do Microsoft 365, adicione essa conta como proprietário da equipa e atualize as definições de ligação para utilizar essa conta.
Esta equipa já está mapeada para uma instância de conector existente. Anule o mapa da equipa da instância do conector existente com o cmdlet Remove-CsTeamsShiftsConnectionTeamMap . Em alternativa, crie uma nova ligação para remapear a equipa.
Este fuso horário é inválido. O fuso horário transmitido não está a utilizar o formato de base de dados tz. Certifique-se de que o fuso horário está correto e, em seguida, remapeia a equipa.
Não conseguimos encontrar esta instância do conector. Mapear a equipa para uma ligação existente.
Não foi possível localizar esta equipa do AAD. Certifique-se de que a equipa existe ou crie uma nova equipa.

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.