Sdílet prostřednictvím


Použití PowerShellu ke správě připojení směn ke službě UKG Pro Workforce Management

Přehled

Konektor Microsoft Teams Shifts pro správu pracovních sil UKG Pro umožňuje integrovat aplikaci Směny v Microsoft Teams s UKG Pro Workforce Management (UKG Pro WFM). Pracovníci v první linii můžou bez problémů zobrazovat a spravovat své plány ve službě UKG Pro WFM v rámci směn.

K nastavení připojení můžete použít průvodce konektorem Směny v Centru pro správu Microsoftu 365 nebo v PowerShellu . Po nastavení připojení ho můžete spravovat pomocí rutin PowerShellu konektoru Shifts.

Tento článek popisuje, jak pomocí PowerShellu provést následující akce:

Tento článek předpokládá, že jste už nastavili připojení k UKG Pro WFM, a to buď pomocí průvodce, nebo PowerShellu.

Poznámka

Připojení můžete také spravovat v Centru pro správu Microsoftu 365. Můžete například zkontrolovat stav a získat přístup k průvodci a změnit nastavení připojení. Další informace najdete v tématu Použití Centra pro správu Microsoftu 365 ke správě připojení směn ke službě UKG Pro Workforce Management.

Než začnete

Abyste mohli provést kroky v tomto článku, musíte být globálním správcem Microsoftu 365 nebo správcem konektoru Shifts.

Role správce konektoru Shifts je vlastní role, kterou vytvoříte v ID Microsoft Entra a přiřadíte ji uživateli. Název role musí být "Správce konektoru Směny". Role nemusí mít žádná konkrétní oprávnění, i když při jejím vytváření musí být nastaveno alespoň jedno oprávnění. Služba spoléhá na přítomnost role u uživatele, nikoli na její oprávnění.

Další informace najdete v tématech Vytvoření a přiřazení vlastní role v Microsoft Entra ID a Přiřazení rolí Microsoft Entra uživatelům. Mějte na paměti, že vytvoření role a použití role pro uživatele může trvat až 24 hodin.

Důležité

Microsoft doporučuje používat role s co nejmenším počtem oprávnění. To pomáhá zlepšit zabezpečení vaší organizace. Globální správce je vysoce privilegovaná role, která by měla být omezená na nouzové scénáře, když nemůžete použít roli s nižšími oprávněními.

Nastavení prostředí

Poznámka

Před spuštěním některého z příkazů nebo skriptů v tomto článku nezapomeňte prostředí nastavit podle těchto kroků.

  1. Nainstalujte PowerShell verze 7 nebo novější. Podrobné pokyny najdete v tématu Instalace PowerShellu ve Windows.

  2. Spusťte PowerShell v režimu správce.

  3. Nainstalujte modul Microsoft Graph PowerShellu.

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

    Ověřte, že je verze 1.6.1 nebo novější.

    Get-InstalledModule Microsoft.Graph 
    
  4. Nainstalujte modul PowerShellu pro Teams Preview.

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

    Ověřte, že je aspoň verze 4.7.0 a obsahuje rutiny konektoru Shifts.

    Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection* 
    
  5. Nastavte PowerShell tak, aby se ukončil, pokud při spuštění skriptu dojde k chybě.

    $ErrorActionPreference = "Stop" 
    
  6. Povolte spouštění skriptů ve Windows.

    Set-ExecutionPolicy bypass 
    
  1. Připojte se k Teams.

    Connect-MicrosoftTeams
    

    Po zobrazení výzvy se přihlaste pomocí přihlašovacích údajů správce. Teď máte nastavené spouštění skriptů v tomto článku a rutinách konektoru Shifts.

Kontrola stavu nastavení připojení

Pokud chcete zkontrolovat stav připojení, které jste nastavili pomocí ID operace, které jste dostali e-mailem, postupujte takto:

  1. Nastavte prostředí (pokud jste to ještě neudělali).

  2. Spusťte tento příkaz: Tento příkaz vám poskytne celkový stav mapování týmu pro připojení.

    Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>
    

Další informace najdete v tématu Get-CsTeamsShiftsConnectionOperation.

Zobrazení zprávy o chybách připojení

Můžete spustit sestavu, která zobrazí podrobnosti o chybě připojení. Sestava obsahuje mapování týmů a uživatelů, která byla úspěšná a neúspěšná. Poskytuje také informace o všech problémech souvisejících s účty přidruženými k připojení.

  1. Nastavte prostředí (pokud jste to ještě neudělali).

  2. Získejte seznam zpráv o chybách pro připojení.

    Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>
    
  3. Pokud chcete zobrazit konkrétní zprávu o chybách, spusťte následující příkaz:

    Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>
    

Další informace najdete v tématu Get-CsTeamsShiftsConnectionErrorReport.

Poznámka

Úplný seznam chybových zpráv najdete v části Seznam chybových zpráv dále v tomto článku.

Řešení chyb připojení

Chyby mapování uživatelů

K chybám mapování uživatelů může dojít, pokud jeden nebo více uživatelů v instanci WFM není členem mapovaného týmu v Teams. Pokud chcete tento problém vyřešit, ujistěte se, že uživatelé v mapovaném týmu odpovídají uživatelům v instanci WFM.

Pokud chcete zobrazit podrobnosti o nemapovaných uživatelích, nastavte prostředí (pokud jste to ještě neudělali) a spusťte následující skript.

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

Chyby autorizace účtu

K chybám autorizace účtu může dojít v případě, že účet služby WFM nebo přihlašovací údaje účtu systému Microsoft 365 nejsou správné nebo nemají požadovaná oprávnění.

Pokud chcete změnit účet služby WFM nebo přihlašovací údaje účtu systému Microsoft 365 pro připojení, můžete spustit rutinu Set-CsTeamsShiftsConnectionInstance nebo použít skript PowerShellu v části Změna nastavení připojení tohoto článku.

Změna nastavení připojení

Pomocí tohoto skriptu můžete změnit nastavení připojení. Mezi nastavení, která můžete změnit, patří účet a heslo služby WFM, systémový účet Microsoft 365, mapování týmu a nastavení synchronizace.

Nastavení synchronizace zahrnují frekvenci synchronizace (v minutách) a data plánu, která se synchronizují mezi systémem WFM a službami Shifts. Data plánu jsou definována v následujících parametrech, které můžete zobrazit spuštěním rutiny Get-CsTeamsShiftsConnectionConnectionConnector.

  • Parametr enabledConnectorScenarios definuje data, která se synchronizují ze systému WFM do služby Shifts. Možnosti jsou Shift, SwapRequest, OfferShiftRequest, UserShiftPreferences, OpenShift, OpenShiftRequest, , , TimeOff. TimeOffRequest

  • Parametr enabledWfiScenarios definuje data, která se synchronizují z shifts do vašeho systému WFM. Možnosti jsou SwapRequest, OfferShiftRequest, OpenShiftRequest, , TimeOffRequest, . UserShiftPreferences

    Poznámka

    Pokud se rozhodnete nesynchronizovat otevřené směny, žádosti o otevřené směny, žádosti o výměnu nebo žádosti o volno mezi službami Shifts a vaším systémem WFM, je potřeba udělat další krok, abyste tuto funkci ve směnách skryli. Po spuštění tohoto skriptu se ujistěte, že postupujete podle kroků v části Zákaz otevřených směn, požadavků na otevřené směny, prohození požadavků a žádostí o volno dále v tomto článku.

    Důležité

    U nastavení, která nechcete změnit, budete muset po zobrazení výzvy skriptu znovu zadat původní nastavení.

Nastavte prostředí (pokud jste to ještě neudělali) a spusťte následující skript.

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

Zákaz otevřených směn, žádostí o otevřené směny, žádostí o prohození a žádostí o volno

Důležité

Tento postup použijte pouze v případě, že jste se rozhodli zakázat otevřené směny, žádosti o otevření směn, žádosti o odhození nebo žádosti o volno pomocí skriptu v části Změna nastavení připojení výše v tomto článku nebo pomocí rutiny Set-CsTeamsShiftsConnectionInstance . Dokončením tohoto kroku skryjete funkci ve směnách. Bez tohoto druhého kroku se uživatelům tato funkce ve směnách stále zobrazí a pokud se ji pokusí použít, zobrazí se chybová zpráva o nepodporované operaci.

Pokud chcete ve směnách skrýt otevřené směny, žádosti o odhození a žádosti o volno, použijte typ prostředku plánu rozhraní Graph API a nastavte následující parametry false pro každý tým, který jste namapovali na instanci WFM:

  • Otevřené směny: openShiftsEnabled
  • Prohození požadavků: swapShiftsRequestsEnabled
  • Žádosti o volno: timeOffRequestsEnabled
  • Žádosti o směnu nabídek: offerShiftRequestsEnabled

Pokud chcete skrýt žádosti o otevřené směny ve Směnách, přejděte na Nastavení ve Směnách a vypněte nastavení Otevřít směny .

Zrušení mapování týmu z jednoho připojení a jeho mapování na jiné připojení

Poznámka

Systémový účet Microsoft 365 musí být pro obě připojení stejný. Pokud tomu tak není, zobrazí se chybová zpráva "Tento určený profil aktéra nemá oprávnění k vlastnictví týmu".

Pokud chcete zrušit mapování týmu z jednoho připojení a namapovat ho na jiné připojení:

  1. Nastavte prostředí (pokud jste to ještě neudělali).

  2. Zobrazení seznamu všech mapování týmů pro připojení

    Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>
    
  3. Odeberte mapování týmu z připojení.

    Remove-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId> -TeamId <TeamId>
    
  4. Namapujte tým na jiné připojení.

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

Další informace najdete v tématech Get-CsTeamsShiftsConnectionTeamMap, Remove-CsTeamsShiftsConnectionTeamMap a New-CsTeamsShiftsConnectionTeamMap.

Zakázání synchronizace pro připojení

Pomocí tohoto skriptu zakážete synchronizaci připojení. Mějte na paměti, že tento skript neodebere ani neodstraní připojení. Vypne synchronizaci, aby se mezi službami Shifts a vaším systémem WFM nesynchronizují žádná data pro vámi zadané připojení.

Nastavte prostředí (pokud jste to ještě neudělali) a spusťte následující skript.

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

Seznam chybových zpráv

Tady je seznam chybových zpráv, se kterými se můžete setkat, a informace, které vám pomůžou je vyřešit.

Typ chyby Podrobnosti o chybě Řešení
Nelze ověřit systém správy pracovních sil. Přihlašovací údaje k účtu systému správy pracovníků, které jste zadali, jsou neplatné nebo tento účet nemá požadovaná oprávnění. V nastavení připojení aktualizujte přihlašovací údaje účtu služby WFM. Abyste to udělali, použijte některý z následujících postupů:
Graph nejde ověřit. Ověření se nezdařilo. Ujistěte se, že jste zadali platné přihlašovací údaje pro určeného objektu actor a že máte požadovaná oprávnění. Ujistěte se, že je váš systémový účet Microsoft 365 (označovaný také jako určený aktér) přidaný jako vlastník týmu.
Nebo aktualizujte přihlašovací údaje k účtu systému Microsoft 365 v nastavení připojení.
Některým uživatelům se nepodařilo správně namapovat. U některých uživatelů se mapování nezdařilo: <X> se nezdařilo, <X> selhalo(a) uživatelů AAD a X> selhalo(a<) u uživatelů systému pro správu pracovních sil. Pomocí rutiny Get-CsTeamsShiftsConnectionSyncResult nebo tohoto skriptu PowerShellu identifikujte uživatele, pro které mapování selhalo. Ujistěte se, že uživatelé v mapovaném týmu odpovídají uživatelům v instanci WFM.
Nelze namapovat tým nebo týmy v této dávce. Tento určený profil aktéra nemá oprávnění k vlastnictví týmu. Ujistěte se, že je váš systémový účet Microsoft 365 (označovaný také jako určený aktér) přidaný jako vlastník týmu.
Pokud jste změnili systémový účet Microsoft 365, přidejte tento účet jako vlastníka týmu a aktualizujte nastavení připojení tak, aby se tento účet používal.
Tento tým je již namapovaný na existující instanci konektoru. Pomocí rutiny Remove-CsTeamsShiftsConnectionTeamMap zrušte mapování týmu z existující instance konektoru. Nebo vytvořte nové připojení pro přemapování týmu.
Toto časové pásmo není platné. Předané časové pásmo nepoužívá formát databáze tz. Ujistěte se, že je časové pásmo správné, a pak přemapujte tým.
Tuto instanci konektoru nemůžeme najít. Namapujte tým na existující připojení.
Tento tým AAD se nepodařilo najít. Ujistěte se, že tým existuje, nebo vytvořte nový tým.

Rutiny konektoru Shifts

Pokud potřebujete pomoc s rutinami konektoru Shifts, vyhledejte CsTeamsShiftsConnection v referenčních informacích k rutinám PowerShellu pro Teams. Tady jsou odkazy na některé běžně používané rutiny.