Compartir a través de

Uso de PowerShell para administrar la conexión de Shifts a UKG Pro Workforce Management

  • Artículo
  • Se aplica a:
    Microsoft Teams, Microsoft 365 for frontline workers

Información general

El conector Turnos de Microsoft Teams para UKG Pro Workforce Management le permite integrar la aplicación Shifts en Microsoft Teams con UKG Pro Workforce Management (UKG Pro WFM). Los trabajadores de primera línea pueden ver y administrar sin problemas sus programaciones en UKG Pro WFM desde shifts.

Puede usar el Asistente para conectores Shifts en el Centro de administración de Microsoft 365 o PowerShell para configurar una conexión. Una vez configurada una conexión, puede administrarla mediante los cmdlets de PowerShell del conector Shifts.

En este artículo, se describe cómo hacer lo siguiente:

En este artículo se supone que ya ha configurado una conexión a UKG Pro WFM, ya sea mediante el asistente o PowerShell.

Nota:

También puede administrar la conexión en el Centro de administración de Microsoft 365. Por ejemplo, puede comprobar el estado de mantenimiento y acceder al asistente para cambiar la configuración de conexión. Para más información, consulte Uso del Centro de administración de Microsoft 365 para administrar la conexión de Turnos a UKG Pro Workforce Management.

Antes de empezar

Debe ser administrador global de Microsoft 365 o administrador de conectores de turnos para completar los pasos de este artículo.

El rol de administrador del conector Shifts es un rol personalizado que se crea en Microsoft Entra ID y se asigna a un usuario. El nombre del rol debe ser "Administrador de conector de Turnos". No es necesario que el rol tenga permisos específicos, aunque se debe establecer al menos un permiso al crearlo. El servicio se basa en la presencia del rol en el usuario y no en sus permisos.

Para obtener más información, consulte Creación y asignación de un rol personalizado en Microsoft Entra ID y Asignación de roles de Microsoft Entra a los usuarios. Tenga en cuenta que el rol puede tardar hasta 24 horas en crearse y aplicarse a un usuario.

Importante

Microsoft recomienda utilizar roles con la menor cantidad de permisos. Esto ayuda a mejorar la seguridad de la organización. Administrador global es un rol con privilegios elevados que debe limitarse a escenarios de emergencia cuando no se puede usar un rol con menos privilegios.

Configurar el entorno

Nota:

Asegúrese de seguir estos pasos para configurar el entorno antes de ejecutar cualquiera de los comandos o scripts de este artículo.

  1. Instale PowerShell versión 7 o posterior. Para obtener instrucciones paso a paso, consulte Instalar PowerShell en Windows.

  2. Ejecute PowerShell en modo de administrador.

  3. Instalar el módulo de PowerShell de Microsoft Graph.

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

    Compruebe que es la versión 1.6.1 o posterior.

    Get-InstalledModule Microsoft.Graph

  4. Instalar el módulo de PowerShell de Teams en versión preliminar.

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

    Compruebe que es al menos la versión 4.7.0 y contiene los cmdlets del conector Shifts.

    Get-Command -Module MicrosoftTeams -Name *teamsshiftsconnection*

  5. Establezca PowerShell para salir si se produce un error al ejecutar el script.

    $ErrorActionPreference = "Stop"

  6. Habilitación de la ejecución de scripts en Windows.

    Set-ExecutionPolicy bypass

  1. Conectarse a Teams

    Connect-MicrosoftTeams

    Cuando se le solicite, inicie sesión con sus credenciales de administrador. Ahora está configurado para ejecutar los scripts de este artículo y los cmdlets del conector Turnos.

Comprobar el estado de la configuración de la conexión

Para comprobar el estado de la conexión que configuró mediante el identificador de operación que recibió en el correo electrónico, siga estos pasos:

  1. Configure el entorno (si aún no lo ha hecho).

  2. Ejecuta el siguiente comando. Este comando proporciona el estado general de las asignaciones de equipo para la conexión.

    Get-CsTeamsShiftsConnectionOperation -OperationId <YourOperationId>

Para obtener más información, consulte Get-CsTeamsShiftsConnectionOperation.

Visualizar un informe de errores para una conexión

Puede ejecutar un informe que muestre los detalles del error de una conexión. En el informe se enumeran las asignaciones de usuario y de equipo que se realizaron correctamente y con errores. También proporciona información sobre los problemas relacionados con las cuentas asociadas a la conexión.

  1. Configure el entorno (si aún no lo ha hecho).

  2. Obtener una lista de informes de errores para una conexión.

    Get-CsTeamsShiftsConnectionErrorReport -ConnectorInstanceId <ConnectorInstanceId>

  3. Para ver un informe de errores específico, ejecute el siguiente comando:

    Get-CsTeamsShiftsConnectionErrorReport -ErrorReportId <ErrorReportId>

Para obtener más información vea Permisos.

Nota:

Para obtener una lista completa de mensajes de error, consulte Lista de mensajes de error más adelante en este artículo.

Resolver errores de conexión

Errores de asignación de usuarios

Pueden producirse errores de asignación de usuarios si uno o varios usuarios de una instancia de WFM no son miembros del equipo asignado en Teams. Para resolver este problema, asegúrese de que los usuarios del equipo asignado coincidan con los usuarios de la instancia de WFM.

Para ver los detalles de los usuarios sin asignar, configure el entorno (si aún no lo ha hecho) y, a continuación, ejecute el siguiente 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
}

Errores de autorización de la cuenta

Pueden producirse errores de autorización de cuenta si las credenciales de la cuenta de servicio de WFM o de la cuenta del sistema de Microsoft 365 son incorrectas o no tienen los permisos necesarios.

Para cambiar la cuenta de servicio de WFM o las credenciales de la cuenta del sistema de Microsoft 365 para la conexión, puede ejecutar el cmdlet Set-CsTeamsShiftsConnectionInstance o usar el script de PowerShell en la sección Cambiar configuración de conexión de este artículo.

Cambiar la configuración de conexión

Use este script para cambiar la configuración de conexión. La configuración que puede cambiar incluye la cuenta de servicio y la contraseña de WFM, la cuenta del sistema de Microsoft 365, las asignaciones de equipo y la configuración de sincronización.

La configuración de sincronización incluye la frecuencia de sincronización (en minutos) y los datos de programación que se sincronizan entre el sistema WFM y los turnos. Los datos de programación se definen en los parámetros siguientes, que puede ver mediante la ejecución de Get-CsTeamsShiftsConnectionConnector.

  • El parámetro enabledConnectorScenarios define los datos que se sincronizan desde el sistema WFM con Shifts. Las opciones son Shift, SwapRequest, OfferShiftRequest, UserShiftPreferences, OpenShift, OpenShiftRequest, , TimeOffTimeOffRequest.

  • El parámetro enabledWfiScenarios define los datos que se sincronizan desde Shifts con el sistema WFM. Las opciones son SwapRequest, OfferShiftRequest, OpenShiftRequest, TimeOffRequest, UserShiftPreferences.

    Nota:

    Si decide no sincronizar los turnos abiertos, las solicitudes de turnos abiertos, las solicitudes de intercambio o las solicitudes de tiempo de expiración entre turnos y el sistema WFM, hay otro paso que debe realizar para ocultar la funcionalidad en Turnos. Después de ejecutar este script, asegúrese de seguir los pasos de la sección Deshabilitar turnos abiertos, solicitudes de turnos abiertos, solicitudes de intercambio y solicitudes de tiempo de expiración más adelante en este artículo.

    Importante

    Para la configuración que no desea cambiar, tendrá que volver a escribir la configuración original cuando se le solicite el script.

Configure el entorno (si aún no lo ha hecho) y, a continuación, ejecute el siguiente 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"

Deshabilitar turnos abiertos, solicitudes de turnos abiertos, solicitudes de intercambio y solicitudes de tiempo de expiración

Importante

Siga estos pasos solo si eligió deshabilitar turnos abiertos, solicitudes de turnos abiertos, solicitudes de intercambio o solicitudes de tiempo de expiración mediante el script de la sección Cambiar configuración de conexión anteriormente en este artículo o mediante el cmdlet Set-CsTeamsShiftsConnectionInstance. Al completar este paso, se oculta la funcionalidad en Turnos. Sin este segundo paso, los usuarios seguirán viendo la funcionalidad en Turnos y recibirán un mensaje de error de “operación no admitida” si intentan usarlo.

Para ocultar turnos abiertos, solicitudes de intercambio y solicitudes de tiempo de espera en Turnos, use el tipo de recurso de programación de Graph API para establecer los parámetros false siguientes en para cada equipo que haya asignado a una instancia de WFM:

  • Abrir turnos: openShiftsEnabled
  • Solicitudes de intercambio: swapShiftsRequestsEnabled
  • Solicitudes de tiempo de expiración: timeOffRequestsEnabled
  • Solicitudes de turnos de oferta: offerShiftRequestsEnabled

Para ocultar las solicitudes de turnos abiertos en Turnos, vaya a Configuración en Turnos y, a continuación, desactive la opción Abrir turnos.

Desajustar un equipo de una conexión y asignarlo a otra conexión

Nota:

La cuenta del sistema de Microsoft 365 debe ser la misma para ambas conexiones. Si no es así, recibirá un mensaje de error "Este perfil de actor designado no tiene privilegios de propiedad de equipo".

Si desea desajustar un equipo de una conexión y asignarlo a otra conexión:

  1. Configure el entorno (si aún no lo ha hecho).

  2. Vea una lista de todas las asignaciones de equipo para una conexión.

    Get-CsTeamsShiftsConnectionTeamMap -ConnectorInstanceId <ConnectorInstanceId>

  3. Quite una asignación de equipo de la conexión.

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

  4. Asigne el equipo a otra conexión.

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

Para obtener más información, consulte Get-CsTeamsShiftsConnectionTeamMap, Remove-CsTeamsShiftsConnectionTeamMap y New-CsTeamsShiftsConnectionTeamMap.

Deshabilitar la sincronización para una conexión

Use este script para deshabilitar la sincronización de una conexión. Tenga en cuenta que este script no quita ni elimina una conexión. Desactiva la sincronización para que no se sincronice ningún dato entre Shifts y el sistema WFM para la conexión que especifique.

Configure el entorno (si aún no lo ha hecho) y, a continuación, ejecute el siguiente 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 mensajes de error

Esta es la lista de mensajes de error que puede encontrar e información para ayudarle a resolverlos.

Tipo de error Detalles del error Solución
No se puede autenticar el sistema de administración de la fuerza de trabajo. Las credenciales de la cuenta del sistema de administración del personal que ha proporcionado no son válidas o esta cuenta no tiene los permisos necesarios. Actualice las credenciales de la cuenta de servicio de WFM en la configuración de conexión. Para ello, siga uno de estos procedimientos:
No se puede autenticar Graph. Error de autenticación. Asegúrese de que ha escrito credenciales válidas para el actor designado y que tiene los permisos necesarios. Asegúrese de que la cuenta del sistema de Microsoft 365 (también conocida como actor designado) se agrega como propietario del equipo.
O bien, actualice las credenciales de la cuenta del sistema de Microsoft 365 en la configuración de conexión.
Algunos usuarios no se han asignado correctamente Error de asignación para algunos usuarios: <X> se ha realizado correctamente, <X> ha producido errores en los usuarios de AAD y <X> ha producido un error en los usuarios del sistema de administración de la fuerza de trabajo. Use el cmdlet Get-CsTeamsShiftsConnectionSyncResult o este script de PowerShell para identificar a los usuarios para los que se produjo un error en la asignación. Asegúrese de que los usuarios del equipo asignado coincidan con los usuarios de la instancia de WFM.
No se puede asignar un equipo o equipos en este lote. Este perfil de actor designado no tiene privilegios de propiedad de equipo. Asegúrese de que la cuenta del sistema de Microsoft 365 (también conocida como actor designado) se agrega como propietario del equipo.
Si ha cambiado la cuenta del sistema de Microsoft 365, agregue esa cuenta como propietario del equipo y actualice la configuración de conexión para usarla.
Este equipo ya está asignado a una instancia de conector existente. Quite el mapa del equipo de la instancia del conector existente mediante el cmdlet Remove-CsTeamsShiftsConnectionTeamMap . O bien, cree una nueva conexión para volver a asignar el equipo.
Esta zona horaria no es válida. La zona horaria pasada no usa el formato de base de datos tz. Asegúrese de que la zona horaria es correcta y, a continuación, vuelva a asignar el equipo.
No podemos encontrar esta instancia del conector. Asigne el equipo a una conexión existente.
No se encontró este equipo de AAD. Asegúrese de que el equipo existe o cree un nuevo equipo.

Cmdlets del conector Turnos

Para obtener ayuda con los cmdlets del conector Turnos, incluidos los cmdlets usados en los scripts, busque CsTeamsShiftsConnection en la referencia de cmdlets de PowerShell de Teams. Estos son los vínculos a algunos cmdlets que se usan habitualmente.