Employee Managed Work Locations

The Employee Managed Work Location extension empowers employees to manage their own job transfer sets.

Note: This business process is an extension model that is developed outside the normal release schedule to meet specific customer needs. To request one of these models, you must submit a Salesforce Service Request to UKG. After the model is delivered to your tenant, you can edit it to meet your needs.

Leveraging the known locations configuration, this extension allows employees to add jobs to, or remove jobs from their Employee Job Transfer Set (EJTS). Managers only need to approve or deny the employee’s selections.

The extension offers employees the flexibility to:

  • Add jobs to their EJTS that match other jobs already in the set; or add other jobs configured within a requested location.

  • Remove existing jobs from their EJTS.

  • Conduct radius-based searches that utilize miles or kilometers to identify potential locations.

  • Control the number of business structure levels that display on task forms.

Two distinct flows make up the business process:

  • Add locations — Upon manager approval, selected jobs are added to the EJTS.

  • Remove locations - Upon manager approval, selected jobs are removed from the EJTS.

Note: You must assign a unique Employee Job Transfer Set to each employee in order to take advantage of this extension.

User experience

Employee experience

An employee wants to work at a location closer to home.

The employee initiates the My work locations business process from the home page tile.

A form opens and displays the employee’s current job set with options to add or remove locations. The employee enters a search radius, and an optional comment, before continuing to the second form.

Up to 10 locations inside the specified radius of the home location are presented to the employee. The employee selects one or more locations, chooses whether to match the primary job, and enters an optional comment, before proceeding to the third form.

Jobs corresponding to the previously selected locations appear. The employee selects the jobs to be added to the EJTS, and clicks Submit.

The business process, by way of the reviewer list, assigns the manager the task of approving the employee's request.

Manager experience

The task form sent to the manager contains all of the employee's requested work locations. The manager then decides which, if any, of the locations to approve. All of the work locations are selected by default; the manager de-selects the locations that are denied. The manager can add a comment (optional), and then clicks Approve Selected.

The business process adds all of the approved locations to the employee's job transfer set, and then sends task completion notifications to the manager and the employee.

UKG Pro Workforce Management configurations

  • Organizational Set: Create an organizational set; move all organizational groups to the Used In area. See the Organizational Sets topic.

  • Known Places: Create known places that contain the latitude and longitude of all locations, including primary jobs. Enter appropriate values for Radius and GPS Accuracy Threshold. Select Require any assigned validation(single factor) and GPS from the Validation Order list. See the Known Places topic.

    Note: As a best practice when configuring Known Places, select the node which is one level higher than the job in the business structure.
  • Workflow notifications: Configure generic workflow notifications that facilitate the Employee Managed Work Locations process. Design the notifications by combining free text with available custom tags. See the Generic notifications topic.

    Examples include:

    Name: Employee Managed Work Locations Notification — Employee

    Custom Tag options:

    Custom Tag options

    Tag

    Description

    <AddedLocation>

    All jobs added to the job transfer set.

    <RemovedLocation>

    All jobs removed from the job transfer set.

    <DeclinedLocation>

    All jobs that the reviewer declined to add or removed from the job transfer set.

    <ManagerComments>

    Reviewer comments selected during approval or rejection of the job action request.

    <EmployeeComments>

    Employee comments selected during request to add or remove jobs.

    Name: Employee Managed Work Locations Notification — Manager

    Custom Tag options:

    Custom Tag options

    Tag

    Description

    <EmployeeName>

    Employee requesting the addition or removal of jobs in the transfer set.

    <AddedLocation>

    All jobs added to the job transfer set.

    <RemovedLocation>

    All jobs removed from the job transfer set.

    <DeclinedLocation>

    All jobs that the reviewer declined to add or removed from the job transfer set.

    <ManagerComments>

    Reviewer comments selected during approval or rejection of the job action request.

    <EmployeeComments>

    Employee comments selected during request to add or remove jobs.

    Caution:
    • Custom tags are case-sensitive and must not be modified.

    • Each workflow notification should be configured with options: Recipient List will be supplied at runtime, Send to employee, and Do not suppress duplicates.

  • Reviewer List: Create a reviewer list that contains no more than one reviewer, and then assign the list to employees. See the Reviewer Lists topic.

  • Symbolic Purpose: Create a symbolic purpose with the reviewer override type. Assign it as the Reviewer Override in people information. See the Configure Reviewer Lists using Symbolic Reviewers topic.

  • Process Profile: Create a process profile. Move the business process from the Available Items to the Selected Items list. Assign the profile to the reviewer and employees. See the Process Profiles setup page topic.

Configure the Employee Managed Work Locations process model

Note: The process for configuring and deploying this and other Business Process Extensions is the same as all Business Process models .
  1. Migrate the business process model to the tenant Migrate the Employee Managed Work Locations process model to the customer tenant using Setup Data Manager (SDM).
    1. Log in to the appropriate tenant.

    2. Go to Main Menu > Administration > Setup Data Manager.

    3. Select the Source tenant where the Process Model resides, and select the template to copy. It is a .zip file. A message appears in the Source column: Source: Import from <filename>.zip.

    4. Click Tap Review and Publish. The Publish Summary panel appears.

    5. Review the Publish Summary panel. It lists the items that were extracted from the migration file. If you approve, click tap Publish with Comment or just Publish.

    6. Click Tap Go to Publish History at the bottom of the panel to view the status of the data transfer. The Publish History page contains a table that lists the items you have published. If there were errors during the transfer, the button under the Errors column for that row is black.

    7. To view details, click tap the appropriate row and click tap View Selected.

    8. On the History for publish run page, click tap Show all to view the setup data that you published, and the errors that occurred, if any, listed by item type and name.

  2. Configure the decision tables Configure the Employee Managed Work Locations decision tables.
    Note: Decision tables are configurable based on user requirements and can be changed accordingly. These tables are dynamic and can be updated at any time without redeployment of the process model.
    1. Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.

    2. Select the EmployeeManagedWorkLocations process and click tap Edit . The process model enters edit mode.

    3. Select the Decision Tables tab.

    4. Click Tap Everyone's, and then select the decision table to edit.

    5. Click Tap Decision Table Editor to add or update the rows in the table.

    6. Click Tap Save and close.

    7. Edit the following decision tables:
      Caution:
      • Values entered in the decision tables are case-sensitive, and must match configured values in the application.

      • Do not remove variables, variable names, or variable types from any decision table.

      • EmployeeManagedWorkLocations_v1_InternalParameters— Controls internal managed work locations parameters.

        Employee Managed Work Locations Internal Parameters decision table

        Employee Managed Work Locations Internal Parameters decision table

        Column

        Description

        Default value

        Admin

        Internal user; do not change.

        SERVICES-LEVEL3

        EmployePersonNumberVariableKey

        Internal Activiti variable that retrieves the initiator's person number.

        initiator

        SymbolUnicode

        Displays the Unicode character that corresponds to each location and job on the user task form.

        For additional Unicode characters, refer to https://www.w3.org/TR/xml-entity-names/025.html

        U+2022

      • EmployeeManagedWorkLocations_v1_Parameters— Controls the managed work locations process.

        EmployeeManagedWorkLocations Parameters decision table

        Employee Managed Work Locations Parameters decision table

        Parameter

        Description

        Default value

        EmployeeNotification

        Detailed notification sent to the employee upon completion of job transfer set updates.

        Employee Managed Work Locations Notification — Employee

        ReviewerNotification

        Detailed notification sent to the reviewer upon completion of job transfer set updates.

        Employee Managed Work Locations Notification — Manager

        RadiusUnit

        Radius unit definition.

        Supported values include:

        Kilometer

        Miles

        Kilometer

        DisplayAllJobs

        Determines the presentation of jobs on user task form.

        Supported values include:

        Yes: Displays all jobs in a location.

        No: Display jobs that match jobs in the employee job transfer set.

        Yes

        ReviewerOverride

        The name of the Symbolic Reviewer configuration that the process uses to determine the appropriate reviewer when the employee submits a request.

        Employee Managed Work Locations

        OrgPathLevelsToDisplay

        Determines the number of business structure levels to display.

        3

        NotificationLocationValuesDelimiter

        Identifies the separator that displays between multiple locations in notifications.

        Supported values include:

        ||

        null

        ||

      • EmployeeManagedWorkLocations_v1_Locale— Allows customization of the text in the workflow form and notifications for different locales.

        Employee Managed Work Locations Locale decision table

        Employee Managed Work Locations Locale decision table

        Variable name

        Variable type

        Description

        Key

        Text

        Internal field label; do not change.

        Locale Policy

        Text

        Name of the locale policy for which the text applies.

        When the text applies to all locales, retain the empty value.

        Message

        Text

        Text displayed in the workflow form or notification.

        Description

        Text

        (Optional) Additional information.

        Note:
        • Localization of business process workflows remains optional, but is supported.​
        • You can translate some or all messages by adding lines to the table in their preferred translation for specific locales. Decision tables are scanned from top to bottom; therefore, place messages for the most commonly used Locale Policy at the top of the decision table and less-restrictive locale policies at the bottom.
        • Text within tags ("<>") must not be changed.
        • The decision table holds all messages represented with standard English labels; these apply to all locales when the Locale Policy is set to !=empty.
        • Names of the parameters in the decision table column ​Parameter Name must be used as is. If any parameter value needs to be localized for a different Locale Policy, copy the ​Parameter Name​ with the !=empty ​Locale Policy, add a new row to the decision table with the appropriate Locale Policy, and then add the localized value in the Message column.​
        • Decision tables support operators like "Contains," "Starts with," "Ends with," and "Is Not Empty." You can achieve your preferred results by following these examples:
          • To match any non-empty or any string (like *), use the "Is Not Empty" operator.
          • To match a string starting with "ABC" (like "ABC*"), use the "Starts with" operator and set the value to "ABC".
          • To match a string containing "English" as substring, use the "Contains" operator with the value "English".
        • The last row in the decision table must remain empty ("!=empty".)

        Key parameter names

        Key parameter names

        Key parameter name value

        Description

        Label_Form1SummaryHeader

        Summary header label on the first form.

        Label_PrimaryJob

        Primary job label in the summary section on the first form.

        Label_Form1RadioHeader

        Radio button header label on the first form.

        Label_Form1Radius

        Radio button label on the first form.

        Label_Form1Button

        Next button label on the first form.

        Label_RemoveLocations

        Remove locations label on the first form.

        Label_AddLocations

        Add Locations label on the first form.

        Label_Form2LocationHeader

        Location header label on the second form.

        Label_Form2LocationMatchPrimaryJob

        Match My Primary Job check box label on the second form.

        Label_Form2LocationButton

        Next button label on the second form.

        Label_Form3AddJobHeader

        Add locations label on the third form.

        Label_Form3AddJobButton

        Submit button label during add job action on the third form.

        Label_Form4RemoveJobHeader

        Remove Job header label on the second form.

        Label_Form4RemoveJobButton

        Submit button label during remove job action on the second form.

        Label_Form1FormLoadMsg

        Load message label on the first form.

        Label_FormReviewerButton

        Reviewer button label to approve the jobs on the reviewer form.

        Label_FormReviewerAddHeader

        Add locations label on reviewer form.

        Label_FormReviewerRemoveHeader

        Remove locations label on reviewer form.

        Label_FormReviewerEmployeeComment

        Employee comment label on reviewer form.

        Label_FormReviewerComment

        Manager comment label on reviewer form.

        Label_RadiusMiles

        Miles radius label on first user form.

        Label_RadiusKilo

        Kilometer radius label on first user form.

        Label_FormEmployeeComment

        Employee comment label on each user task form.

        Label_GoBackRadioButton

        GoBack radio button label on each user task form.

        Label_ErrorFormButton

        Error label on each form.

        Message_NoRadiusForAdd

        Message that displays when radius is not provided during add locations on the first user form.

        Message_NoLocationToRemoveInEJTS

        Message that displays when location does not exist under the job transfer set on the first user form.

        Message_NoLocationSelected

        Message that displays when location is not selected on the user task form.

        Message_NoJobsAvailableToAdd

        Message that displays when jobs are not available to add on the user task form.

        Message_NoJobsSelected

        Message that displays when jobs are not selected on the user task form.

        Message_LocationSelectionThreshold

        Message that displays when the location selection exceeds the configured threshold.

        Error_MissingParameterDT

        Error message that displays when a parameter is missing from the decision table.

        Error_LocationCountThreshold

        Error message that displays when the number of known places exceeds the threshold.

        Error_PrimaryJobCoordinatesNotFound

        Error message that displays when a primary location with coordinates is not configured in known places.

        Error_ReviewerAndReportsToNotPresent

        Error message that displays when an employee does not have Reviewer and Reports To assignments.

        Error_ReviewerInvalid

        Error message that displays when the reviewer is invalid.

        Error_ReviewerCountInvalid

        Error message that displays when more than one reviewer is assigned in the Reviewer List.

        Error_InactiveReviewerList

        Error message that displays when the reviewer list is not active.

        Error_ApiFailure

        Error message that displays when the API call fails in the workflow.

        Error_ScriptFailure

        Error message that displays when the script is fails in the workflow.

        Error_NoReviewerPurpose

        Error message that displays when the reviewer override is not found.

        Error_NoEmployeeJobTransferSet

        Error message that displays when the employee job transfer set is not found.

        Error_InvalidInputParameters

        Error message that displays when invalid input parameters exist in the decision table.

        Error_IncorrectCodePoint

        Error message that displays when invalid Unicode exists in the decision table.

        Error_BlankRadiusAdd

        Error message that displays when the radius is not provided during add locations on the first user form.

        Error_EjtsBlankRemove

        Error message that displays when a location does not exist under job transfer set during remove action.

  3. Deploy the updated business process model
    Note: Process models must be redeployed every time changes are made to an existing model. Re-deployment is not required for decision table changes.
    1. Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.

    2. Select the EmployeeManagedWorkLocations_v1 model.

    3. Click Tap Edit, and then configure the deployment dates and required parameters, such as: Hide from Action List and GoTo List; Show from the Tile List.

      Caution: Do not make a selection from the Template Categories list.
    4. Click Tap Save, and then select Return to deploy.

Limitations

  • The Employee Managed Work Locations process supports a maximum configuration of 7000 known places.

  • When the employee initiates the workflow to update their EJTS, the task form displays a maximum of 10 locations from which to select.

APIs

API details

API details table

API Name

Type

Resource Path

Description

Retrieve Persons

POST

/v1/commons/persons/extensions/multi_read

Returns multiple person records based personid or personnumber.

Retrieve Location Sets by List

POST

/v1/commons/location_sets/multi_read

Returns organizational map groups (location sets) according to a list of groups data.

Retrieve Known Places

POST

/v1/commons/known_places/multi_read

Returns one or more known places by ID, name, or OrgJob (a location on the Business Structure).

Retrieve Reviewer List by ID

GET

/v1/commons/reviewer_lists/{id}

Returns a reviewer list by ID.

Create or Update Location Set

POST

v1/commons/location_sets/apply_upsert

Creates or updates a location set.

Retrieve Locations

POST

v1/commons/locations/multi_read

Returns organizational map locations. Search data includes query info, date, location set, descendants, parent, ancestors, or children.

Retrieve People Information Profile by ID

GET

/v1/commons/persons/{id}

Returns a People Information Profile by ID.

Retrieve All Known Places or by Specification

GET

v1/commons/known_places

Returns a list of all known places if no query parameter is specified, or by employee ID, person number, or persistent ID.

Retrieve User Preferences for Current User

GET

v1/commons/user_preferences

Returns user preferences for the current user.

Private API

Generic Notification Notify API

Private API

Personality Multiread API

Version history

Version history

Version history

Version

Description

1

Initial release.

With management approval, allow employees to add or remove jobs from the existing job transfer set assignment.