Pay Period Minimum Wage Top-Up

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

According to the Fair Labor Standards Act (FLSA) in the United States, employees are entitled to be paid a minimum wage for each pay period. At the end of the pay period, if the minimum wage is not met — such as for employees who are paid less than the minimum wage rate but earn tips — employers must top up the difference between the employees' earnings and the minimum wage.

This integration determines whether an employee’s total earned wages for a pay period are less than the minimum wage that the employee is entitled to. If so, the integration adds the difference as a top-up to the employee’s Timecard on the last day of the pay period.

You can configure whether the integration processes wage data for signed-off periods, you can set the minimum wage rate as legislated for the location, and you can run the integration for any time period.

An employee works as a server in a hotel and receives tips along with regular pay.

  • The employee's base wage is $5/hour.
  • The local minimum wage is $10/hour.

Pay-period top-up = FLSA minimum earnings — Total earnings

  • If the difference is negative, do not pay the top-up.
  • If the difference is positive, pay that amount to the employee.

The employee worked as follows:

Pay Period Minimum Wage Top-Up example schedule
Day Worked hours Base earnings Tips Total earnings FLSA minimum earnings Pay period top-up
Monday 8.00 $40 — $40 $80 —
Tuesday 8.00 $40 — $40 $80 —
Wednesday 0.00 — — — — —
Thursday 8.00 $40 — $40 $80 —
Friday 8.00 $40 $50 $90 $80 —
Saturday 8.00 $40 $100 $140 $80 —
Sunday 0.00 — — — — —
Totals 40.00 $200 $150 $350 $400 $50

After the integration runs, the Timecard shows the paycode for the top-up, and Comments and Notes provide details.

  • The employee must be assigned a base wage in the application.

  • Make sure that a standard minimum-wage top-up is not configured in the application.

  1. Configure Access to Integrations.

  2. Configure the following:

  • Paycode: Create a money-based paycode for the minimum-wage top-up. See the Paycode definition topic.

Example: $Minimum Wage Top Up

  • Combined paycode: Create a combined paycode that holds all paycodes which are considered as worked and eligible for minimum-wage top-ups. This paycode typically includes regular hours, overtime, and tips. During configuration select Visible in Report Options and Report Totals and Visible on Totals Tab in Timecard. See the Combined Paycodes topic.

Example: Minimum Wage — Worked

  • Comment: Configure a comment, such as Adjusted by Integration, to identify the paycode for the minimum-wage top-up. Select the paycodes category during configuration. See the Comments topic.

  1. Get the URL, User, and Password for the APIGatewayServer.

Version Description
1

Initial release.
iPack_v2 The Pay Period Minimum Wage Top-Up integration delivery is now by way of an iPack.

Deploy the Pay Period Minimum Wage Top Up integration

For more information, see the Deploy Integrations topic.

  1. Open the Integration Template Designer: Select Main Menu  > Administration > Application Setup > Integrations Setup > Design Integration Templates.

    Note: If prompted, enter your Username and Password. Click Tap Log in.

  2. Make sure that the Account is correct. If not, select the right account.

  3. Select the Deploy tab > Integration Packs.
  1. From the list in the left column, search for and select the Pro WFM Pay Period Minimum Wage Top Up Extension integration.

  1. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button Select items.

Configure the Pay Period Minimum Wage Top Up integration settings

Select the environment

  1. Select the Manage tab > Atom Management.
  2. Select your environment.

Select environment extensions

  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass Search button. It can take several seconds before the button becomes active.
  1. Scroll to and select the integration pack: Pro WFM Pay Period Minimum Wage Top Up Extension > PayPeriodMinimumWageTopUp_iPack_v2.

Configure connection settings

Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

  1. Select Connection Settings.

  2. From the Connection dropdown list, select and configure the following:

    Connection Settings
    Setting Required Actions
    PayPeriodMinimumWageTopUp_iPack_v2_APIGatewayServer Required

    To change the default API gateway server:

    1. Clear Use Default.
    2. Enter the URL to the server.

      Example: <tenantURL>/api

    Use the format <tenantURL>/api.
    PayPeriodMinimumWageTopUp_iPack_v2_MinimumWageByLocation_CRT Required Enable Override.

Configure process properties

  1. Select Process Properties.

    Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

  2. Select PayPeriodMinimumWageTopUp_iPack_v2 to set process properties that must be configured before the integration can run. This main process starts the integration process and handles errors.

    Process Properties
    Property Required Actions
    PayPeriodMinimumWageTopUp_iPack_v2_CRTConfig Required

    For _PayPeriodMinimumWageTopUp_iPack_v2_MinimumBaseWageByLocation_CRT:

    1. Clear Use Default.
    2. Enter VerID, Location, Minimum Wage Hourly Rate, Start Date, End Date.

Configure cross-reference tables

Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

  • If more than one row matches a reference value, the first match is the output value.
  • If no match is found, the output value can be null, or the integration can produce errors.
  1. Select Cross Reference.
  2. From the Cross Reference dropdown list, select the PayPeriodMinimumWageTopUp_iPack_v2_MinimumBaseWageByLocation_CRT table.
  3. Select Override, which allows you to:
  • Download the table when you run the integration.
  • Edit the table cells in Extensions.
  1. When you finish, click tap OK.

PayPeriodMinimumWageTopUp_iPack_v2_MinimumBaseWageByLocation_CRT: Maps the minimum wage rates to locations in the business structure.

Pay Period Minimum Wage Top Up — Minimum Base Wage By Location CRT structure
Column header Description
VerID

Version number for the minimum wage at a location; this number serves as a unique key.

Start at 1 and increment sequentially by location and effective date.

If rows for the same location have different effective dates, assign different VerIDs to the rows.
Location The business structure path for the location.
Minimum Wage Hourly Rate

The legislated minimum hourly wage.
Start Date The effective start date of the base wage rate at the location.
End Date The effective end date of the base wage rate at the location.

Example:

California\San Diego County\Hyatt Uptown\*| 12.00 |01/01/2021 | 12/31/2021 || 1

California\San Diego County\Hyatt Uptown\*|13.00|01/01/2022|12/31/2022||2

After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.

Note:
  • An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
  • An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.
  1. Select Main Menu  > Administration > Application Setup > Integrations Setup > Install Integrations.
  2. Click Tap Create .
  3. In Integration Name, enter a unique name, such as PayPeriodMinimumWageTopUp_iPack_v2.
  4. (Optional) Enter a Description.

Note: Do not select API Integration.

  1. In File Access, select None to not select a connection.
  2. (Optional) If the person who runs the integration doesn't have full access to integrations, select Execute Integration with System Account. This allows the integration access to all APIs in the FAP, and the relevant permissions and data, regardless of the FAP and GDAP of the person who runs the integration.

  3. (Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.

  4. Email Notifications

    (Optional)

    1. Select Yes to send email and control center notifications for integration runs.
    2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces:

      In Progress — The integration run started and has not finished.

      Completed — The integration ran successfully without errors.

      Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.

      Completed with Errors — The integration run has errors or could not run.

  5. In Skip Configuration, select None (default) to allow multiple integrations to run at the same time or with the same data without restrictions.

Note: Do not select Allow Minute Interval.

  1. Integration template and parameters
    1. In Integration Template, select PayPeriodMinimumWageTopUp_iPack_v2.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings. Click Tap Create.

    4. Complete the configuration for each parameter value.

    5. Click Save.

Repeat this step for each integration parameter that supports the Enhanced Staffing Dashboard process.

Pay Period Minimum Wage Top Up — Integration parameters
Parameter name Description Template parameter Parameter type
Hyperfind The default Hyperfind query that contains the employees for whom the integration is run.
Default = All Home

User prompt = Yes

Note: Ad-hoc Hyperfinds are not supported.

All Home does not include terminated and inactive employees even if they have totals during the period. To include these totals, configure a Hyperfind that includes terminated and inactive employees, and select that Hyperfind in this process property.

The maximum number of employees in a Hyperfind is 3500. To process more employees, divide the population into smaller Hyperfinds to run sequentially.

 HyperfindOrLocations Hyperfind
Employee IDs

(Optional)

A comma-separated list of specific employees for whom the integration is run.

When no value is entered, the integration defaults to the Hyperfind parameter.

To process the integration for only a limited group of employees, enter the person numbers as defined in the source system, each separated by a comma (,) but not spaces.

User prompt = Yes

 EmployeeIDs Text
Worked Paycode

The combined paycode that holds all paycodes considered as worked.

User prompt = No

 WorkedPaycode Text
Top-Up Paycode

The money-based paycode for the minimum wage top-up.

Default = $Minimum Wage Top Up

User prompt = No

 TopUpPaycode Text
Comment

(Optional)

Comment that the integration adds to the top-up paycode edit in the timecard.

Default = Adjusted by integration

User prompt = No

 Comment Text
Worked Paycode Threshold

The minimum time that is required in the Timecard for the Minimum Wage — Worked (hours) paycode to be eligible for a minimum-wage top-up

Default = 00:01

User prompt = No

 WorkedPaycodeThreshold Text
Time Period

The pay period, date range, or symbolic period for which the integration will run.

Supported values include:

  • 0 = Previous pay period
  • 1 = Current pay period
  • 2 = Next pay period
  • 3 = Previous schedule period
  • 4 = Current schedule period
  • 5 = Next schedule period
  • 6 = Week to date
  • 7 = Last week
  • 8 = Yesterday
  • 10 = Range of relative dates
  • 11 = Specific date
  • 12 = Relative specific date
  • 13 = Today

User prompt = Yes

 TimePeriod Time period
Process Signed-Off Period

Determines whether the integration processes data for signed-off time periods.

Supported values include:

  • True: Process data for signed-off pay periods.

  • False (default): Do not process data for signed-off pay periods.

User prompt = No

 ProcessSignedOffPeriod Boolean
Comment Note

(Optional)

The note that adds details to the comment attached to the paycode for the minimum-wage top-up.

Default =

Minimum Wage Adjustment:

Total Earnings #WorkedPaycodeWage#

Minimum Wage #MinimumWage#

User prompt = No

Note:

#WorkedPaycodeWage# is replaced by the actual money amount for a pay period earned in paycode Worked Paycode.

#MinimumWage# is replaced by the money amount calculated for a pay period earned as per state minimum wage defined in the PayPeriodMinimumWageTopUp_iPack_v2_MinimumBaseWageByLocation_CRT.

 CommentNote Text
CRT Date Format

(Optional)

Defines the format of dates in the MinimumBaseWageByLocation_CRT cross-reference table.

Supported values include:

  • MM-DD-YYYY

  • MM/DD/YYYY (default)

  • DD-MM-YYYY

  • DD/MM/YYYY

  • YYYY-MM-DD

  • YYYY/MM/DD

User prompt = No

 CRTDateFormat Text

  1. Ensure that the generic data access profiles (GDAP) allow access to the Pay Period Minimum Wage Top-Up integration for the people who need to run the installed integrations. See Configure Access to Integrations.

Run integrations to test that the configuration is set up correctly.

Run the integration

  1. Select the integration:
    1. Select Main Menu  > Maintenance > Integrations. 
    2. Click Tap Run an Integration . 
    3. Select the PayPeriodMinimumWageTopUp_iPack_v2 integration from the list. Click Tap Select. 
    4. (Optional) Enter a unique Integration Run Name to make it easier to identify the run of the integration. Otherwise, the default name ends with a date and time stamp.
  2. Set parameters as follows:
    • Hyperfind: Select a Hyperfind query of employees.
    • Individual Employee ID: To process data for only a limited group of employees, enter the person numbers, as defined in the source system, each separated by a comma (,) but no spaces.

      For 3 employees: 13997,15556,20012

    • Time Period: Select a pay period.

  3. Select the following:

    • Run Integration: If this is the first time this integration is being run.
    • Re-Run: If this integration has been run before, and the status is not In-Progress, you can run the integration again without entering the parameter values again. Click Tap Yes to continue, or No to not run the integration and to return to the parameter settings.

  4. Wait for the confirmation that the integration completed or failed. Close the panel.
  5. Click Tap Refresh . 
  6. To see details, select the integration run. Select Run Summary.

Check the results

Status indicators

  •  In-Progress: The run of this integration has not yet completed.
  •  Completed: The integration ran successfully without errors.
  •  Scheduled: This integration is scheduled to run later or repeatedly.
  • (Grayed out) Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
  •  Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
  •  Failed: The integration run has errors or could not run.
  • To troubleshoot and resolve errors, do the following:

    Check the Run Summary for details.

    • To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
    • (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant.

To check the results in more detail, do the following:

  1. To see detailed results, click tap the tile for the integration run.
  2. Click Tap Run Summary to see the results of the integration run.

    Example Run Summary details

    Note: The available details vary by integration and configuration.

    • Integration Run Name: Name of this run of the integration.
    • Process Name: Name of any integration set that includes this integration.
    • Integration Name: Name of the installed integration.
    • Integration Reference ID: Unique identifier for this integration run (to help in troubleshooting errors).
    • User: The person or user account that ran the integration.
    • Integration Type: Import, Export, or None
    • Start Date: Date and time when the integration run started.
    • End Date: Date and time when the integration run finished.
    • Status: In-Progress, Completed, Completed with Errors, or Failed.
    • Records Processed: Number of records that were processed.
    • Records Created: Number of records that were created.
    • Errors: Number of records that failed.
    • Source Files, Output File, and Error Files: For file-based import integrations, use Manage SFTP to access the source and output files on the inbound (source) and outbound (destination) SFTP folders. See the Manage SFTP topic.
  3. Log in to the destination system and make sure that the data has been correctly updated.

Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the topic.

API details
API title URI Method Description
Execute Hyperfind Query /v1/commons/hyperfind/execute POST Executes a Hyperfind query by ID or qualifier and returns the result.
Retrieve Persons /v1/commons/persons/extensions/multi_read POST Returns multiple person records based on search criteria.
Retrieve Paycodes /v1/timekeeping/setup/pay_codes POST Returns one or more paycodes available to the logged-in manager by object references
Retrieve Timecards as Manager /v1/timekeeping/timecard/multi_read POST Returns a list of timecards based on the employees or Hyperfind details provided.
Retrieve Timecard Data for Multiple Employees /v1/timekeeping/timecard_metrics/multi_read POST Returns timecard data for a set of employees or locations.
Bulk Paycode Edits /v1/timekeeping/pay_code_edits/import POST Allows performance of bulk import and delete operations on paycode edits, which represent a change to a schedule, timecard, or Dataview display that modifies existing punched data with a manual entry or group edit.
Bulk Delete Paycode Edits /v1/timekeeping/pay_code_edits/multi_delete POST Performs a bulk delete of paycode edits for multiple employees using a list of paycode edit IDs.
Update Timecard as Manager /v1/timekeeping/timecard POST Updates a timecard for an employee as a manager. You can add, update, or delete punches, paycode edits, hours worked, and/or exception Comments.
Retrieve Comments as Manager /v1/commons/comments GET Returns a filtered list of Comments.
Retrieve Pay Period Timespans /v1/commons/pay_period GET Returns a pay period timespan based on the pay period ID, pay rule ID, user, date, and period type.
Retrieve Symbolic Periods /v1/commons/symbolicperiod GET Returns all symbolic periods in the system.
Retrieve Locale Date Span /v1/commons/symbolicperiod/read POST Returns a locale date span, or symbolic period, according to the data provided.
Enable Edits Bulk Update /v1/timekeeping/enable_edits/import POST Returns a list of employees with enabled edits.
Retrieve Locales /v1/commons/locale_policies/multi_read POST Returns locales according to the provided request.
Retrieve User Preferences for Current User /v1/commons/user_preferences/locale_policy?tenantDefault=true GET Returns user preferences for the current user or tenant.
Update Integration Execution Details /v1/platform/integrations/update_status POST Updates and returns the callback instance against the provided integration execution details.
Submit Integration Execution Additional Details /v1/platform/integration_executions/{id}/additional_details POST Submits all additional details related to an integration execution (API or batch) into system.