Partilhar via


Utilizar o PowerShell para gerir a sua ligação de Turnos à Gestão da Força de Trabalho Blue Yonder

Descrição geral

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

Pode utilizar o assistente do conector Shifts no centro de administração do Microsoft 365 ou no PowerShell para configurar uma ligação. Depois de configurar uma ligação, pode geri-la com os cmdlets do PowerShell do conector Shifts.

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

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

Nota

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 de Turnos à Blue Yonder 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 tem de ser "Shifts connector admin". A função não precisa de ter permissões específicas. No entanto, pelo menos uma permissão tem de ser definida quando a criar. O serviço depende da presença da função no utilizador e não das respetivas 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. Tenha em atenção que pode demorar até 24 horas para que a função seja criada e aplicada a um utilizador.

Importante

A Microsoft recomenda que utilize 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 o seu ambiente

Nota

Certifique-se de que segue estes passos para configurar o seu ambiente antes de executar qualquer um dos comandos ou scripts neste artigo.

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

  2. Execute o PowerShell no modo de administrador.

  3. Instale o módulo do 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. Instale o módulo do PowerShell de Pré-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. Ative a execução de scripts no Windows.

    Set-ExecutionPolicy bypass 
    
  1. Ligue-se ao Teams.

    Connect-MicrosoftTeams
    

    Quando lhe for pedido, inicie sessão com as suas credenciais de administrador. Está agora configurado para executar os scripts neste artigo e os cmdlets do conector Shifts.

Verificar o estado da configuração da ligaçã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 o seu ambiente (se ainda não o fez).

  2. Execute o seguinte comando. Este comando fornece-lhe o estado geral dos mapeamentos de equipa para a ligação.

    Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>
    

Para saber mais, veja Get-CsTeamsShiftsConnectionOperation.

Ver um relatório de erros para uma ligação

Pode executar um relatório que mostra os detalhes do erro de uma ligação. O relatório lista os mapeamentos da equipa e do utilizador que foram bem-sucedidos e falharam. Também fornece informações sobre quaisquer problemas relacionados com as contas associadas à ligação.

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

  2. Obtenha uma lista de relatórios de erros para uma ligação.

    Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>
    
  3. Para ver um relatório de erros específico, execute o seguinte comando:

    Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>
    

Para saber mais, consulte Get-CsTeamsShiftsConnectionErrorReport.

Nota

Para obter uma lista completa das mensagens de erro, consulte Lista de mensagens de erro mais à frente neste artigo.

Resolver erros de ligação

Erros de mapeamento de utilizadores

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 ver detalhes de utilizadores não mapeados, configure o seu ambiente (se ainda não o fez) e, em seguida, 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 da 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 as definições de ligação

Utilize este script para alterar as definições de ligaçã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 agendamento são definidos nos seguintes parâmetros, que pode ver ao executar Get-CsTeamsShiftsConnectionConnector.

  • O parâmetro enabledConnectorScenarios define os dados sincronizados do seu sistema WFM para Shifts. As opções são Shift, SwapRequest, 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, OpenShiftRequest, TimeOffRequest, UserShiftPreferences.

    Nota

    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. Depois de executar este script, certifique-se de que segue os passos na secção Desativar turnos abertos, pedidos de turnos abertos, pedidos de troca e pedidos de folga mais à frente neste artigo.

Importante

Para definições que não pretende alterar, terá de reintroduzir as definições originais quando lhe for pedido o script.

Configure o seu ambiente (se ainda não o fez) e, em seguida, 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"
$BlueYonderId = "6A51B888-FF44-4FEA-82E1-839401E9CD74"
$connectors = Get-CsTeamsShiftsConnectionConnector
write $connectors
$blueYonder = $connectors | where {$_.Id -match $BlueYonderId}

#List connection instances available
Write-Host "Listing connection instances available"
$InstanceList = Get-CsTeamsShiftsConnectionInstance | where {$_.ConnectorId -match $BlueYonderId}
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)
$adminApiUrl = $Instance.ConnectorSpecificSettingAdminApiUrl
$cookieAuthUrl = $Instance.ConnectorSpecificSettingCookieAuthUrl
$essApiUrl = $Instance.ConnectorSpecificSettingEssApiUrl
$federatedAuthUrl = $Instance.ConnectorSpecificSettingFederatedAuthUrl
$retailWebApiUrl = $Instance.ConnectorSpecificSettingRetailWebApiUrl
$siteManagerUrl = $Instance.ConnectorSpecificSettingSiteManagerUrl
$syncFreq = Read-Host -Prompt 'Input new sync frequency'

#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 $BlueYonderId `
    -ConnectorAdminEmail $AdminEmailList `
    -DesignatedActorId $teamsUserId `
    -EnabledConnectorScenario $updatedConnectorScenario `
    -EnabledWfiScenario $updatedWfiScenario `
    -Name $UpdatedInstanceName `
    -SyncFrequencyInMin $syncFreq `
    -ConnectorSpecificSettings (New-Object Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Models.ConnectorSpecificBlueYonderSettingsRequest `
    -Property @{
        AdminApiUrl = $adminApiUrl
        SiteManagerUrl = $siteManagerUrl
        EssApiUrl = $essApiUrl
        RetailWebApiUrl = $retailWebApiUrl
        CookieAuthUrl = $cookieAuthUrl
        FederatedAuthUrl = $federatedAuthUrl
        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"

Desativar turnos abertos, pedidos de turnos abertos, pedidos de troca e pedidos de folga

Importante

Siga estes passos apenas se optar por desativar turnos abertos, pedidos de turno abertos, pedidos de troca ou pedidos de folga utilizando o script na secção Alterar definições de ligação anteriormente neste artigo ou utilizando o cmdlet Set-CsTeamsShiftsConnectionInstance . A conclusão deste passo oculta a capacidade em Turnos. Sem este segundo passo, os utilizadores continuarão a ver a capacidade em Turnos e receberão uma mensagem de erro "operação não suportada" se tentarem utilizá-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:

  • Turnos abertos: openShiftsEnabled
  • Pedidos de troca: swapShiftsRequestsEnabled
  • Pedidos de folga: timeOffRequestsEnabled

Para ocultar pedidos de turnos abertos em Turnos, aceda a Definições em Turnos e, em seguida, desative a definição Abrir turnos .

Anular o mapeamento de uma equipa de uma ligação e mapeá-la para outra ligação

Nota

A conta de sistema do Microsoft 365 tem de ser a mesma para ambas as ligações. Se não estiver, receberá uma mensagem de erro "Este perfil de ator designado não tem privilégios de propriedade da equipa".

Se quiser remover uma equipa de uma ligação e mapeá-la para outra ligação:

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

  2. Ver uma lista de todos os mapeamentos de equipa para uma ligação.

    Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>
    
  3. Remova um mapeamento de equipa da ligação.

    Remove-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId> -TeamId <TeamId>
    
  4. Mapear a equipa para outra ligação.

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

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

Desativar a sincronização para uma ligação

Utilize este script para desativar a sincronização para uma ligação. Tenha em atenção que este script não remove nem elimina uma ligaçã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 o seu ambiente (se ainda não o fez) e, em seguida, 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
$BlueYonderId = "6A51B888-FF44-4FEA-82E1-839401E9CD74"
Write-Host "Listing connection instances"
$InstanceList = Get-CsTeamsShiftsConnectionInstance | where {$_.ConnectorId -match $BlueYonderId}
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
    $adminApiUrl = $Instance.ConnectorSpecificSettingAdminApiUrl
    $cookieAuthUrl = $Instance.ConnectorSpecificSettingCookieAuthUrl
    $essApiUrl = $Instance.ConnectorSpecificSettingEssApiUrl
    $federatedAuthUrl = $Instance.ConnectorSpecificSettingFederatedAuthUrl
    $retailWebApiUrl = $Instance.ConnectorSpecificSettingRetailWebApiUrl
    $siteManagerUrl = $Instance.ConnectorSpecificSettingSiteManagerUrl
    $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"
$BlueYonderId = "6A51B888-FF44-4FEA-82E1-839401E9CD74"
$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))

$UpdatedInstance = Set-CsTeamsShiftsConnectionInstance `
    -ConnectorInstanceId $InstanceId `
    -ConnectorId $BlueYonderId `
    -ConnectorAdminEmail $ConnectorAdminEmail `
    -DesignatedActorId $DesignatedActorId `
    -EnabledConnectorScenario @() `
    -EnabledWfiScenario @() `
    -Name $UpdatedInstanceName `
    -SyncFrequencyInMin 10 `
    -ConnectorSpecificSettings (New-Object Microsoft.Teams.ConfigAPI.Cmdlets.Generated.Models.ConnectorSpecificBlueYonderSettingsRequest `
        -Property @{
            AdminApiUrl = $adminApiUrl
            SiteManagerUrl = $siteManagerUrl
            EssApiUrl = $essApiUrl
            RetailWebApiUrl = $retailWebApiUrl
            CookieAuthUrl = $cookieAuthUrl
            FederatedAuthUrl = $federatedAuthUrl
            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 tal, faça um dos seguintes:
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 os cmdlets do conector do Shifts, procure CsTeamsShiftsConnection na referência de cmdlets do PowerShell do Teams. Seguem-se ligações para alguns cmdlets utilizados frequentemente.