Staffing Level-based Open Shift Validation

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.

The Staffing Level-based Open Shift Validation business process evaluates staffing requirements to determine the appropriate action to take on open shifts that are generated by an employee's absence request approval.

This extension provides a post-process that, when hooked with time-off requests, compares the number of scheduled employees for a Location and Job against a threshold. When the staffing level falls below the threshold, no action takes place, and the open shift remains. When the staffing level matches or exceeds the threshold, the open shift is deleted.

Two types of thresholds drive the evaluation, but only one is configured during an effective-dated period for the associated Location and Job:

  • Fixed — Used for locations that always have a static number of employees on staff, and where the minimum staffing levels can be defined with a known number.

  • Percentage — Used for locations with a more dynamic number of staff for which minimum staffing levels are defined in percentages based on the Workload Plan. Percentage thresholds are evaluated by reading the planned headcount in the Workload Planner for the location. Ignoring breaks, it then calculates what the headcount represents in hours. The advantage of this threshold is that adjustments are not required when the location size changes.

Spans are an optional control that support a more granular evaluation for the Location and Job. By using spans, different thresholds can be applied for each Location and Job, and span. Alternatively, setting the span to a wildcard (*) allows the same threshold to be applied to all spans associated with the Location and Job.

Reviewer lists determine routing of the notification generated by an open shift deletion.

Fixed threshold

The staffing level threshold for a particular job is fixed to 1 for the 3:00 PM—11:00 PM shift span.

This means that as long as there is 1 person on the staff filling the job, open shifts generated for people on leave will be removed.

Three people are scheduled to work the job during the 3:00 PM—11:00 PM shift.

Scenario A

Two people receive approval to take a full day of leave. After the open shifts are generated, the post-process removes both open shifts because 1 person still remains on staff.

Scenario B

The third person receives approval to take a full day of leave. After the open shift is generated, the post-process allows the open shift to remain because otherwise no one would be on staff.

Percentage threshold

The staffing level threshold for a particular job is set to 50% for the 7:00AM — 3:00 PM shift span, and the Workload Planner specifies 3 people must be on staff.

This means that as long as there are 1.5 people on staff filling the job, open shifts generated for people on leave will be removed.

Scenario A

One person receives approval to take a full day of leave. After the open shift is generated, the post-process removes the open shift because 2 people still remain on staff.

Scenario B

A second person receives approval to take a full day of leave. After the open shift is generated, the post-process allows the open shift to remain because otherwise only 1 person would be on staff.

  • Reviewer Lists must exist, and be assigned to employees that submit absence requests. See the Reviewer Lists topic. If the Reviewer List is empty, notifications are sent to the employee's reports to manager.

  • Reviewer Purposes must exist. See the Symbolic Purposes topic.

  • Schedule Zones or Shifts Sets must be configured to measure coverage in the Schedule Planner. See the Configure coverage by zone or shift set topic.

Workflow notifications configuration

See the Configure Notifications for Business Processes topic.

  1. Go to Application Setup > Event/Notification > Workflow Notifications.

  2. Click Tap New.

  3. From the Notification Type, select Generic notification.

  4. Click Tap Ok.

  5. Complete the configuration for the workflow notification, as appropriate.

  6. Click Tap Save.

Repeat for each workflow notification.

Time-off Workflow Notification — Employee — Notify recipient of the request status.

  • Name: Enter an appropriate name, such as Time-off Employee Notification.

  • Subject: Enter an appropriate subject, such as Time-off Employee Notification.

  • Long Message: Enter an appropriate long message, such as Time-off Employee Notification.

  • Short Message: Enter an appropriate short message, such as Time-off Employee Notification.

  • Recipients: Select the Recipient List will be supplied at runtime option.

  • Select Trigger Business Process, and then select TimeOff_RequestType_v2 from the Template drop down.

  • Select Business Process will run asNotification Recipient List.

  • Control center fields: Enter appropriate control center fields, such as:
    Field Label Value
    1 Status <Approval Status>
    2 Date <Start Date>

Time-off Workflow Notification — Manager — Notify recipient of the request status.

  • Name: Enter an appropriate name, such as Time-off Workflow Notification — Manager.

  • Subject: Enter an appropriate subject, such as Time-off Manager Notification.

  • Long Message: Enter an appropriate long message, such as Time-off Manager Notification.

  • Short Message: Enter an appropriate short message, such as Time-off Manager Notification.

  • Recipients: Select the Recipient List will be supplied at runtime option.

  • Control center fields: Enter appropriate control center fields, such as:
    Field Label Value
    1 Status <Approval Status>
    2 Date <Start Date>

Staffing Level-based Open Shift Notification — Notify recipients of the open shift deletion.

  • Name: Enter an appropriate name, such as Staffing Level-based Open Shift Notification.

  • Subject: Enter an appropriate subject, such as Staffing Level-based Open Shift Notification.

  • Long Message: Enter an appropriate long message, such as:

    The following Open Shift has been deleted because the staffing level is above threshold:

    Date and Shift: <DateShift>

    Location/Job: <LocationJob>

  • Recipients: Select the Recipient List will be supplied at runtime and Send to employee options.

  • Control center fields: Enter appropriate control center fields, such as:
    Field Label Value
    1 Date and shift: <DateShift>
    2 Location and Job <LocationJob>

Staffing Level Open Shift Error Notification — Notify recipient of an error.

  • Name: Enter an appropriate name, such as Staffing Level Open Shift Error Notification.

  • Subject: Enter an appropriate subject, such as Staffing Level Open Shift Error Notification.

  • Long Message: Enter an appropriate long message, such as:

    The business process failed due to:

    Error: <Error>

  • Recipients: Select the Send to employee and Email Recipients options.

  • Control center fields: Enter appropriate control center fields, such as:
    Field Label Value
    1 Error: <Error>

Create control center mappings for all notifications

Create control center notification mappings for all workflow notifications that support staffing level-based open shift validation; see the Control Center Notification Mapping topic.

  1. From the Main Menu, go to Application Setup > Event/Notification > Control Center Notification Mapping.
  2. Click Tap New.
  3. Enter an Event Name, such as Time-off Employee Notification.
  4. From Domain, select Scheduler.
  5. From Event Type, select Time-off.
  6. From Notification, select the appropriate value, such as Time-off Workflow Notification — Employee.
  7. From Navigation Page, select Schedule.
  8. From Icon, select an appropriate property.
  9. Click Tap Save.

Create request subtype

See the Configure Request Subtypes topic.

  1. From the Main Menu, go to Application Setup > Employee Self Service > Request Subtype.
  2. Click Tap New.
  3. Enter a Name, such as PTO Hourly.
  4. (Optional) Enter a Description.
  5. From Request Type, select Time-Off.
  6. Configure remaining fields, as needed.
  7. Click Tap Save & Return.

Migrate the business process model to the tenant

Migrate the Staffing Level-based Open Shift Validation 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.

Configure the decision tables

Configure the Staffing Level-based Open Shift Validation decision tables.

  1. Go to Main Menu > Administration > Application Setup > Business Process setup > Process Models.

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

  3. Select the Decision Tables tab.

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

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

  6. Click Save and close.

Note:

  • Values entered in the decision tables are case-sensitive, and must match configured values in UKG Pro Workforce Management™.

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

TimeOff_RequestType_v2_Parameters — Controls Staffing Level-based Open Shift Validation for time-off requests.

TimeOff_RequestType_v2_Parameters
Parameter name Description Parameter type Default value
StaffingLevelValidationSwitch

The switch parameter that enables the staffing level-based open shift validation functionality.

Yes — enables the functionality.

No — does not enable the functionality.

 String Yes

TimeOff_RequestType_v2_InternalParameters — Contains internal time-off request parameters which are external to the business and functional requirements.

TimeOff_RequestType_v2_InternalParameters
Parameter name Description Default value
ApprovedStatus A comma-separated list of potential open shift state values for a request during an approved scenario. Approved
CancelledStatus A comma-separated list of potential state values in the system during a canceled scenario. Canceled; CancelApproved
Admin Internal user; do not change. Services-Level1

Users of this business process can take advantage of the enhanced cancellation request states.

Organizations that have enabled the UseNewRequestCancelSubmittedStatuses feature switch will see new states:

  • Cancel Approved — the employee's request to cancel a previously approved request is approved.

  • Cancel Refused — the employee's request to cancel a previously approved request is refused.

Existing Canceled and Approved states remain, and retain their original use.

TimeOff_RequestType_v2_StaffingLevelOpenShiftValidation_Parameters — Holds configurable parameters for staffing level-based open shift validation functionality.

TimeOff_RequestType_v2_StaffingLevelOpenShiftValidation_Parameters
Variable name Description Default value
OrgPathLevelsToDisplay Determines the number of business structure levels to display. 2
ManagerNotification (Optional) Identifies the notification that is sent to the manager. Leave blank for no notification. Staffing Level-based Open Shift Notification
ValidationErrorNotification

Identifies the notification which contains the validation failure error details.

Note:

This notification is mandatory.

 Staffing Level Open Shift Error Notification
ShiftToSpanMinimumOverlap

Shift to span ratio, represented as a percentage.

Identifies the minimum percentage a scheduled shift must overlap a span in order to count towards coverage evaluation.

Percentage value must match or exceed 80%.

 80

TimeOff_RequestType_v2_StaffingLevelOpenShiftValidation_StaffingValidationLimits — Contains effective-dated staffing level thresholds by location/job.

TimeOff_RequestType_v2_StaffingLevelOpenShiftValidation_StaffingValidationLimits
Column name Description
Location The Location\Job for which the absence request will be post-processed.
Span

(Optional) Identifies specific spans for which validation is processed.

Use a semicolon to separate multiple spans for a Location\Job.

Supports wildcard use.

Examples:

*

"8-17 Day"

"17-23 Evening"

"23-8 Night"

"8-17 Day;17-23 Evening;23-8 Night"
Staffing Level Threshold Determines whether the workflow retains or deletes the open shift.
Threshold Type

Determines the threshold type.

Fixed — static validation.

Percentage — dynamic validation.
Effective From Effective start date of the staffing level rule.
Effective To Effective end date of the staffing level rule.
Reviewer List The name of the reviewer list that identifies who is notified with open shift details.
Reviewer Purpose The name of the reviewer purpose that identifies the purpose type to associate with the Reviewer List.

TimeOff_RequestType_v2_StaffingLevelOpenShiftValidation_Locale — Contains configurable messages to support multiple locales for the staffing level-based open shift validation.

TimeOff_RequestType_v2_StaffingLevelOpenShiftValidation_Locale
Variable name Variable type Description
Key String Internal field label; do not change.
Locale String Name of the locale policy for which the message applies. When the message applies to all locales, retain the empty value.
Message String Message displayed in the Workflow form, or error message.
Note:

  • Localization of business process workflows remains optional, but is supported.

  • The decision table holds all messages represented with standard English labels; these apply to all locales when the Locale is set to a wildcard (*).

  • Some or all messages can be translated by adding lines to the table in their preferred translation for specific locales. Messages for the most commonly used Locale Policy should be defined at the top of the decision table. Text within tags ("<>") must not be changed.

  • 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 * Locale Policy, add a new row to the decision table with the appropriate Locale Policy, and then add the localized values in the Message column.

  • The last row in the decision table must remain empty ("!=empty".)

Deploy the updated business process model

Process models must be redeployed every time changes are made to an existing model. Re-deployment is not required for decision table changes.

Model deployment steps:

  1. Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.

  2. Select the TimeOff_RequestType_v2 model.

  3. Click Tap Edit, and then configure the required parameters and deployment dates. Select Notification Templates from the Template Categories list.

  4. Click Tap Save, and then select Return to deploy.

API details
API name Type Resource path Description
Person Extension POST /v1/commons/persons/extensions/multi_read Returns multiple person records based on person ID of employees for a particular location/job.
Fetching Employee schedule POST /v1/scheduling/schedule/multi_read Returns a schedule pertaining to a particular location/job within a specified date range.
Delete multiple open shifts POST /v1/scheduling/schedule/shifts/multi_delete Deletes one or more open shifts according to the parameters provided.
Time-off Multi read POST /v1/scheduling/timeoff/multi_read Returns one or more time-off requests matching to a set of employees.
Retrieve overridden shifts from Time-off Multi read GET /v1/scheduling/timeoff/{notificationid}?include_overridden_shifts=true Returns a time-off request by ID including overridden shifts.
Read Span from workload planner POST /v1/commons/data/multi_read Returns span details by name, start time, and end time for a particular location/job.
Fetch Reviewer from Retriever List GET v1/commons/reviewer_lists/{id} Returns a reviewer list by name, type, and active status.
Generic Notification Notify POST Generic Notification Notify Sends notification to the recipient with the open shift delete or error notification.
Audit API POST /v1/scheduling/audits/multi_read Returns a set of open shift audits according to a particular location/job within a specified date range.