Dela via

Använda PowerShell för att hantera din Shifts-anslutning till UKG Pro Workforce Management

  • Artikel
  • Gäller för:
    Microsoft Teams, Microsoft 365 for frontline workers

Översikt

Med Microsoft Teams Shifts-anslutningsappen för UKG Pro Workforce Management kan du integrera Shifts-appen i Microsoft Teams med UKG Pro Workforce Management (UKG Pro WFM). Dina medarbetare i frontlinjen kan smidigt visa och hantera sina scheman i UKG Pro WFM inifrån Skift.

Du kan använda Guiden Arbetspass-koppling i Administrationscenter för Microsoft 365 eller PowerShell för att konfigurera en anslutning. När en anslutning har konfigurerats kan du hantera den med hjälp av PowerShell-cmdletar för Shifts-anslutningsappen.

I den här artikeln beskrivs hur du använder PowerShell för att göra följande:

Den här artikeln förutsätter att du redan har konfigurerat en anslutning till UKG Pro WFM, antingen med hjälp av guiden eller PowerShell.

Obs!

Du kan också hantera anslutningen i Administrationscenter för Microsoft 365. Du kan till exempel kontrollera hälsostatusen och komma åt guiden för att ändra anslutningsinställningarna. Mer information finns i Använda Administrationscenter för Microsoft 365 för att hantera din Shifts-anslutning till UKG Pro Workforce Management.

Innan du börjar

Du måste vara global administratör för Microsoft 365 eller administratör för Shifts-anslutningsappen för att kunna utföra stegen i den här artikeln.

Administratörsrollen för Shifts-anslutningsappen är en anpassad roll som du skapar i Microsoft Entra ID och tilldelar till en användare. Namnet på rollen måste vara "Administratör för Shifts-anslutningsappen". Rollen behöver inte ha några specifika behörigheter, men minst en behörighet måste anges när du skapar den. Tjänsten förlitar sig på användarens närvaro av rollen och inte dess behörigheter.

Mer information finns i Skapa och tilldela en anpassad roll i Microsoft Entra ID och Tilldela Microsoft Entra roller till användare. Tänk på att det kan ta upp till 24 timmar innan rollen skapas och tillämpas på en användare.

Konfigurera din miljö

Obs!

Se till att du följer de här stegen för att konfigurera din miljö innan du kör något av kommandona eller skripten i den här artikeln.

  1. Installera PowerShell version 7 eller senare. Stegvisa anvisningar finns i Installera PowerShell i Windows.

  2. Kör PowerShell i administratörsläge.

  3. Installera Microsoft Graph PowerShell-modulen.

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

    Kontrollera att det är version 1.6.1 eller senare.

    Get-InstalledModule Microsoft.Graph

  4. Installera PowerShell-modulen Förhandsversion av Teams.

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

    Kontrollera att den är minst version 4.7.0 och innehåller cmdletarna för Shifts-anslutningsappen.

    Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection*

  5. Ange att PowerShell ska avslutas om ett fel uppstår när skriptet körs.

    $ErrorActionPreference = "Stop"

  6. Aktivera skript för att köras i Windows.

    Set-ExecutionPolicy bypass

  1. Anslut till Teams.

    Connect-MicrosoftTeams

    När du uppmanas att göra det loggar du in med dina administratörsautentiseringsuppgifter. Du är nu konfigurerad för att köra skripten i den här artikeln och cmdletar för Shifts-anslutningsappen.

Kontrollera status för anslutningskonfiguration

Följ dessa steg för att kontrollera statusen för den anslutning som du har konfigurerat med hjälp av åtgärds-ID:t som du fick via e-post:

  1. Konfigurera din miljö (om du inte redan har gjort det).

  2. Kör följande kommando: Det här kommandot ger dig den övergripande statusen för teammappningarna för anslutningen.

    Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>

Mer information finns i Get-CsTeamsShiftsConnectionOperation.

Visa en felrapport för en anslutning

Du kan köra en rapport som visar felinformation för en anslutning. Rapporten listar team- och användarmappningar som lyckades och misslyckades. Den innehåller också information om eventuella problem som rör de konton som är kopplade till anslutningen.

  1. Konfigurera din miljö (om du inte redan har gjort det).

  2. Hämta en lista över felrapporter för en anslutning.

    Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>

  3. Om du vill visa en specifik felrapport kör du följande kommando:

    Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>

Mer information finns i Get-CsTeamsShiftsConnectionErrorReport.

Obs!

En fullständig lista över felmeddelanden finns i Lista över felmeddelanden senare i den här artikeln.

Lösa anslutningsfel

Mappningsfel för användare

Fel med användarmappning kan inträffa om en eller flera användare i en WFM instans inte är medlem i det mappade teamet i Teams. Lös problemet genom att se till att användarna i det mappade teamet matchar användarna i den WFM instansen.

Om du vill visa information om omappade användare konfigurerar du din miljö (om du inte redan har gjort det) och kör sedan följande 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
}

Kontoauktoriseringsfel

Kontoauktoriseringsfel kan inträffa om WFM tjänstkontot eller autentiseringsuppgifterna för Microsoft 365-systemkontot är felaktiga eller inte har de behörigheter som krävs.

Om du vill ändra ditt WFM tjänstkonto eller autentiseringsuppgifter för Microsoft 365-systemkontot för anslutningen kan du köra cmdleten Set-CsTeamsShiftsConnectionInstance eller använda PowerShell-skriptet i avsnittet Ändra anslutningsinställningar i den här artikeln.

Ändra anslutningsinställningar

Använd det här skriptet för att ändra anslutningsinställningar. Inställningar som du kan ändra inkluderar ditt WFM tjänstkonto och lösenord, Microsoft 365-systemkonto, teammappningar och synkroniseringsinställningar.

Synkroniseringsinställningarna omfattar synkroniseringsfrekvensen (i minuter) och schemadata som synkroniseras mellan ditt WFM-system och Skift. Schemadata definieras i följande parametrar, som du kan visa genom att köra Get-CsTeamsShiftsConnectionConnector.

  • Parametern enabledConnectorScenarios definierar data som synkroniseras från ditt WFM-system till Skifts. Alternativen är Shift, SwapRequest, OfferShiftRequest, UserShiftPreferences, OpenShift, , OpenShiftRequest, TimeOff, . TimeOffRequest

  • Parametern enabledWfiScenarios definierar data som synkroniseras från Skift till ditt WFM system. Alternativen är SwapRequest, OfferShiftRequest, OpenShiftRequest, TimeOffRequest, , UserShiftPreferences.

    Obs!

    Om du väljer att inte synkronisera öppna skift, öppna skiftbegäranden, växlingsbegäranden eller time off-begäranden mellan Skift och ditt WFM system, finns det ett annat steg du behöver göra för att dölja funktionen i Skift. När du har kört skriptet kontrollerar du att du följer stegen i avsnittet Inaktivera öppna arbetspass, öppna arbetspassbegäranden, växlingsbegäranden och ledighetsbegäranden senare i den här artikeln.

    Viktigt

    För inställningar som du inte vill ändra måste du ange de ursprungliga inställningarna igen när du uppmanas av skriptet.

Konfigurera du din miljö (om du inte redan har gjort det) och kör sedan följande 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"

Inaktivera öppna arbetspass, öppna arbetspassbegäranden, växlingsbegäranden och ledighetsbegäranden

Viktigt

Följ endast de här stegen om du har valt att inaktivera öppna arbetspass, öppna arbetspassbegäranden, växlingsbegäranden eller ledighetsbegäranden med hjälp av skriptet i avsnittet Ändra anslutningsinställningar tidigare i den här artikeln eller med hjälp av cmdleten Set-CsTeamsShiftsConnectionInstance. Om du slutför det här steget döljs funktionen i Arbetspass. Utan det här andra steget ser användarna fortfarande funktionen i Arbetspass och får felmeddelandet "åtgärden stöds inte" om de försöker använda den.

Om du vill dölja öppna skift, växla begäranden och time off-begäranden i Skift använder du resurstypen Graph API schema för att ange följande parametrar för false varje team som du har mappat till en WFM-instans:

  • Öppna arbetspass: openShiftsEnabled
  • Växlingsbegäranden: swapShiftsRequestsEnabled
  • Ledighetsbegäranden: timeOffRequestsEnabled
  • Begäranden om erbjudandeskift: offerShiftRequestsEnabled

Om du vill dölja öppna arbetspassbegäranden i Arbetspass går du till Inställningar i Arbetspass och inaktiverar sedan inställningen Öppna arbetspass.

Avmappa ett team från en anslutning och mappa den till en annan anslutning

Obs!

Det Microsoft 365 systemkontot måste vara detsamma för båda anslutningarna. Om den inte är det får du felmeddelandet "Den här utsedda aktörsprofilen har inte behörighet för teamägarskap".

Om du vill avmappa ett team från en anslutning och mappa den till en annan anslutning:

  1. Konfigurera din miljö (om du inte redan har gjort det).

  2. Visa en lista över alla teammappningar för en anslutning.

    Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>

  3. Ta bort en teammappning från anslutningen.

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

  4. Mappa teamet till en annan anslutning.

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

Mer information finns i Get-CsTeamsShiftsConnectionTeamMap, Remove-CsTeamsShiftsConnectionTeamMap och New-CsTeamsShiftsConnectionTeamMap.

Inaktivera synkronisering för en anslutning

Använd det här skriptet för att inaktivera synkronisering för en anslutning. Tänk på att det här skriptet inte tar bort eller tar bort en anslutning. Den inaktiverar synkroniseringen så att inga data synkroniseras mellan Skift och ditt WFM system för den anslutning som du anger.

Konfigurera du din miljö (om du inte redan har gjort det) och kör sedan följande 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"
}

Lista över felmeddelanden

Här är listan över felmeddelanden som du kan stöta på och information som hjälper dig att lösa dem.

Feltyp Felinformation Åtgärd
Det går inte att autentisera personalhanteringssystemet. Autentiseringsuppgifterna för personalhanteringssystemet som du har angett är ogiltiga eller så har det här kontot inte de behörigheter som krävs. Uppdatera autentiseringsuppgifterna för ditt WFM tjänstkonto i anslutningsinställningarna. Detta gör du på något av följande sätt:
Det går inte att autentisera Graph. Autentiseringen misslyckades. Kontrollera att du har angett giltiga autentiseringsuppgifter för den avsedda aktören och har de behörigheter som krävs. Kontrollera att ditt Microsoft 365-systemkonto (även kallat utsedd aktör) har lagts till som teamägare.
Eller uppdatera autentiseringsuppgifterna för ditt Microsoft 365-systemkonto i anslutningsinställningarna.
Vissa användare har inte mappas korrekt Mappningen misslyckades för vissa användare: <X> lyckades, <X-misslyckade> AAD-användare och <X> misslyckade användare av personalhanteringssystem. Använd cmdleten Get-CsTeamsShiftsConnectionSyncResult eller det här PowerShell-skriptet för att identifiera de användare som mappningen misslyckades för. Kontrollera att användarna i det mappade teamet matchar användarna i den WFM instansen.
Det går inte att mappa ett team eller team i den här batchen. Den här avsedda aktörsprofilen har inte behörighet för teamägarskap. Kontrollera att ditt Microsoft 365-systemkonto (även kallat utsedd aktör) har lagts till som teamägare.
Om du har ändrat ditt Microsoft 365-systemkonto lägger du till kontot som teamägare och uppdaterar anslutningsinställningarna så att det används.
Det här teamet är redan mappat till en befintlig anslutningsinstans. Koppla bort teamet från den befintliga anslutningsinstansen med hjälp av cmdleten Remove-CsTeamsShiftsConnectionTeamMap . Eller skapa en ny anslutning för att mappa om teamet.
Tidszonen är ogiltig. Tidszonen som skickas använder inte tz-databasformat. Kontrollera att tidszonen är korrekt och mappa sedan om teamet.
Det går inte att hitta den här anslutningsinstansen. Mappa teamet till en befintlig anslutning.
Det gick inte att hitta det här AAD-teamet. Kontrollera att teamet finns eller skapa ett nytt team.

Cmdletar för arbetspassanslutningar

Om du vill ha hjälp med cmdletar för Shifts-anslutningsprogram söker du efter CsTeamsShiftsConnection i Cmdlet-referensen för Teams PowerShell. Här är länkar till några vanliga cmdletar.