Prerequisites and requirements for the Teams Shifts connector for UKG Pro Workforce Management

Overview

The Microsoft Teams Shifts connector for UKG Pro Workforce Management enables you to integrate the Shifts app in Microsoft Teams with your UKG Pro Workforce Management (UKG Pro WFM) system. Your frontline workers can seamlessly view and manage their schedules in UKG Pro WFM from within Shifts.

You can use the Shifts connector wizard in the Microsoft 365 admin center or PowerShell to create a connection and connection instances. After they're set up, you can manage them in the Microsoft 365 admin center or by using PowerShell. There are no additional licensing fees for using the connector.

This article lists requirements, prerequisites, and configuration tasks that you must complete before you use the wizard or PowerShell to create a connection. It also gives you an overview of how to set up your teams in Teams based on your UKG Pro WFM organizational structure.

Before you begin

Before you integrate Shifts with UKG Pro WFM, your organization must have the following environment requirements already set up.

• Your UKG Pro WFM environment is configured. This means that your organization has completed the following:

  • You've established how "teams" (groupings of users) are organized to match your organizational structure and business needs, and your users are grouped by location.

    Important

    Shifts currently supports grouping users by location in UKG Pro WFM. Other user grouping types aren't supported.

  • You've set up relevant requests, such as shift requests and time off requests, according to your business needs.

    Important

    Shifts currently supports the following UKG Pro WFM request types:

    • Open shift requests. Partial shift criteria aren't supported.
    • Swap requests.
    • Requests to cover shifts. Partial shift criteria aren't supported.
    • Time off requests.
    • Availability patterns change request subtype.

• You're using Microsoft Entra ID as your identity provider.

Prerequisites

Make sure you gather the following information and complete the following configuration tasks before you use the wizard or PowerShell to create a connection.

Accounts

• You're a Microsoft 365 Global Administrator.

• You know your UKG Pro WFM account username and password, along with the following service URLs:

  • API URL
  • Application key
  • Client ID
  • Client secret
  • Single Sign On (SSO) URL

  If you don't have all this information, contact UKG Pro WFM support.

  Important

  The UKG Pro WFM account you use must have an access profile which allows full access to all API-based integrations in UKG.

Enable SSO by setting up integration between Microsoft Entra ID and UKG Pro Workforce Management

For a step-by-step tutorial, see Tutorial: Microsoft Entra SSO integration with Kronos Workforce Dimensions. If you need help or more information about setting up SSO, contact UKG Pro WFM support.

Configure federated SSO authentication in UKG Pro Workforce Management

Follow these steps to configure federated SSO authentication in your UKG Pro WFM environment.

Step 1: Change user accounts to federated accounts

Each Shifts user who you want to connect to UKG Pro WFM needs a federated account in UKG Pro WFM.

1. Sign in to UKG Pro WFM by using an admin or super user account that has access to Application Setup.
2. On the left menu, go to Maintenance > People information.
3. Open the user's profile.
4. Under the Employee section, expand Information.
5. Change the Authentication Type to Federated.
6. Save your changes and repeat the process for all Shifts users who you want to connect to UKG Pro WFM.

Step 2: Allow Shifts SSO redirection URLs

Configure the connector's redirection URL. This allows UKG Pro WFM to redirect the user to the Shifts app in Teams as part of the SSO flow.

1. Sign in to UKG Pro WFM by using an admin or super user account that has access to Application Setup.
2. On the left menu, go to Administration > Application Setup.
3. Then, go to System Configuration and choose System Settings.
4. Select Global Values.
5. In the global.oAuth.authCode.redirection.uris field, enter the value, "https://aka.ms/shifts/connector/ukgdimensions/auth".
6. In the global.oAuthToken.redirection.domain.whiteList field, enter the value, "aka.ms".
7. Select Save.

Create at least one team in Teams

Create at least one team in Teams, and add the following people and account to it:

• Frontline workers as team members.

• Frontline managers as team owners and/or schedule owners. To learn more about team owners and schedule owners in Shifts, see Use roles to define your frontline managers and workers in Shifts.

  Note

  When adding people to your teams, make sure you do the following:

  • Add frontline workers to every team that they're allowed to work at, based on their UKG Pro WFM locations.
  • Add frontline managers to every team in which they have frontline workers as direct reports. Otherwise, managers will only receive workers' requests in UKG Pro WFM and not in Shifts.

• A general account, what we call the Microsoft 365 system account, as team owner.

  The Microsoft 365 system account is a general account must be added as team owner to all teams you want to map. Create this account in the Microsoft 365 admin center and assign it a Microsoft 365 license. Then, add the account as a team owner. The Shifts connector uses this account when syncing Shifts changes from UKG Pro WFM. We recommend you create an account specifically for this purpose and not use your personal user account.

For guidance on creating frontline teams, see How to find the best frontline team solution for your organization. If you want to create more than one team, see Deploy frontline dynamic teams at scale and Deploy frontline static teams at scale.

Make sure the teams that you want to map don't have any existing schedules

If a team has an existing schedule that was created in Shifts, follow these steps to remove schedule entities from the team before you map a UKG Pro WFM location (also called a WFM instance) to it. Otherwise, you'll see duplicate shifts.

Use PowerShell to remove schedule entities from teams.

1. Install the PowerShell modules and set up your PowerShell environment (if you haven't already).

2. Run the following command:

   Remove-CsTeamsShiftsScheduleRecord -TeamId <Teams team ID> -DateRangeStartDate <start time> -DateRangeEndDate <end time> -ClearSchedulingGroup:$false -EntityType <the scenario entities that you want to remove, the format is @(scenario1, scenario2, ...)> -DesignatedActorId <Teams team owner ID>
   

   To get a list of scenarios for the EntityType parameter, run Get-CsTeamsShiftsConnectionConnector. Schedule data will be removed for the date and time range that you specify.

To learn more, see Remove-CsTeamsShiftsScheduleRecord.

Understand how your UKG Pro Workforce Management organizational structure influences Teams and Shifts setup

As mentioned earlier, Shifts supports grouping users by location in UKG Pro WFM. In UKG Pro WFM, the nodes in each location represent the hierarchy in your organizational chart. A location path reaches its endpoint when a job type is configured.

Users in UKG Pro WFM are assigned and grouped by jobs that exist within a location. This means that from a Teams and Shifts standpoint, employees who have the same location path up to the node before the job type are considered as part of the same team. The job types in the location path are synced and represented as schedule groups in Shifts.

Example

Here's an example to help you understand how your UKG Pro WFM structure influences the way you set your teams, mapping considerations, and how information syncs to Shifts.

Scenario

Contoso has hundreds of retail stores spread across the United Kingdom. Each store is located within an Area in the United Kingdom. To simplify this example, we focus on three stores in the Central London Area, to which Contoso wants to start rolling out Teams and Shifts for their frontline employees.

Assumptions:

• Each store is managed by a different manager.
• Some frontline workers are allowed to take shifts from other stores within the Central London Area. In other words, in UKG Pro WFM, these frontline workers are part of a job transfer set.

UKG Pro Workforce Management location structure

In this scenario, the UKG Pro WFM location structure looks something like this, in which the Company node represents the top-most level in the hierarchy.

Here's how frontline managers (FLM) and frontline workers (FLW) are set up in the location structure in UKG Pro WFM. The table lists each workers' primary job and who they report to.

¹FLW1 can also work as a beauty advisor in Central London/Chelsea.
²FLW5 can also work as a sales associate in Central London/Covent Garden and Central London/Chelsea.

What does this mean when I set up teams in Teams?

In this scenario, the IT admin organizes teams in Teams as follows.

1. Create three different teams in Teams for each store within the Central London area: Soho Store, Covent Garden Store, Chelsea Store.

2. Add employees that belong to the corresponding UKG Pro WFM location to each team, including managers that the employees report to. Frontline workers are added as team members and frontline managers are added as team owners and/or schedule owners.

   Here's the list of teams and the people added to each team.

   Team name	Team members	Team owners and/or schedule owners
   Soho Store	FLW1, FLW2, FLW3, FLW4, FLW5, FLW6, FLW7, FLW8, FLW9, FLW10	FLM1
   Covent Garden Store	FLW5, FLW11, FLW12, FLW13, FLW14	FLM2
   Chelsea Store	FLW1, FLW5, FLW15, FLW16, FLW17	FLM3

   Keep in mind that FLW1 and FLW5 are added to all teams for the store locations that they're allowed to work at. The other frontline workers aren't allowed to work at other stores, and are added only to the team that represents their primary job location.

   Note

   In UKG Pro WFM, if you have departments with business locations, create teams for each department (instead of for each store). As mentioned earlier in this article, to establish the mapping between platforms, we take the location path up to the node and consider that a team.

What does this mean when I run the Shifts connector wizard?

When the IT admin sets up a connection instance in the wizard, they map each store location to the relevant team, as shown in the following table.

What does this look like in Shifts?

In Shifts, the schedule groups of each team represent the jobs defined for the store location.

Within each store, in Shifts:

• Frontline managers see employees within their respective schedule groups (that is, job types).
• Frontline workers see their own schedule and their team's schedule.
• Frontline workers can communicate with coworkers in their own store through chat.
• Frontline workers and managers can request time off, swap shifts, offer shifts, and open shifts if the requests are configured in UKG Pro WFM and set to be synced in the connection instance settings that you configure in the wizard.
• Frontline workers and managers can reach other employees in their store who are on shift, if shift-based tags are enabled.

For employees who work at multiple stores, in Shifts:

• Frontline workers and managers can only make requests within a particular store. Shifts currently doesn't support workers' requests between different stores when integrated with a WFM system.
• Frontline workers can view their schedule and their team’s schedule in any store they work at.

Related articles

• Shifts connectors
• Manage the Shifts app in Teams