Mexico 3x3 Overtime

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.

In Mexico, the Federal Labor Law states that overtime is paid at least double, or triple, the regular pay rate when certain conditions are met. This integration calculates the appropriate overtime, and then displays the hours on the Totals tab in the Timecard.

The number of regular hours depends on the shift type. Mexico Federal Labor Law sets limits on daily durations as follows:

  • Daytime Shift: Eight hours per shift — 48 hours a week.

  • Night Shift: Seven hours per shift — 42 hours a week.

  • Mixed shift: Seven and a half hours per shift — 45 hours a week.

Three conditions determine the overtime calculation.

  • Condition 1: On a daily basis, the first 3 hours of overtime are considered double overtime hours; overtime hour in excess of 3 is considered triple overtime.

  • Condition 2: On a weekly basis, the first 9 hours of overtime are considered double overtime hours. Every overtime hour in excess of 9 is considered triple overtime.

  • Condition 3: On a weekly basis, if there are 3 occurrences of overtime, every additional overtime hour is considered triple overtime, regardless of daily or weekly limits.

Note: customers can choose to configure the integration using a combination of all three conditions or conditions 1 and 2, only.

This extension:

  • Determines whether overtime exists.

  • Validates conditions for overtime distribution.

  • Distributes hours to double and triple overtime paycodes.

  • Inserts paycodes in the timecard.

Double and triple overtime hours are calculated for weekly periods, even when larger date ranges are supplied by the user. Partial week processing is allowed, provided that the date range includes the start of the week.

User experience

An employee is scheduled to work Monday—Friday, 7:00 AM—4:30 PM, with a 30-minute meal break. The employee works overtime during the week.

In the first use case, double overtime reaches 9 hours on Wednesday, satisfying condition 2. All overtime above 9 hours is considered triple time. The Totals tab displays regular, overtime, double time and triple time hours.

Use case 1
  Monday Tuesday Wednesday Thursday Friday Saturday Sunday Totals
In punch 7:00 AM 7:00 AM 7:00 AM 7:00 AM 7:00 AM 7:00 AM    
Out punch 7:30 PM 9:30 PM 9:30 PM 8:30 PM 6:30 PM 11:30 AM    
Lunch break 00:30 00:30 00:30 00:30 00:30      
Regular time 9:00 9:00 9:00 9:00 9:00     45:00
Overtime 3:00 5:00 5:00 4:00 2:00 4:30   23:30
Double time 3:00 3:00 3:00         09:00
Triple time   2:00 2:00 4:00 2:00 4:30   14:30

In the second use case, overtime occurrences fall on the first 3 days of the week, satisfying condition 3. All overtime, regardless of daily or weekly limits, is considered triple time. The Totals tab displays regular, overtime, double time and triple time hours.

Use case 2
  Monday Tuesday Wednesday Thursday Friday Saturday Sunday Totals
In punch 7:00 AM 7:00 AM 7:00 AM 7:00 AM 7:00 AM 7:00 AM    
Out punch 9:30 PM 5:30 PM 8:30 PM 8:30 PM 6:30 PM 11:30 AM    
Lunch break 00:30 00:30 00:30 00:30 00:30      
Regular time 9:00 9:00 9:00 9:00 9:00     45:00
Overtime 5:00 1:00 4:00 4:00 2:00 4:30   20:30
Double time 3:00 1:00 3:00         07:00
Triple time 2:00   1:00 4:00 2:00 4:30   13:30

Configure the Mexico 3x3 Overtime integration

  1. Configure Access to Integrations.
  2. Configure paycodes representing double overtime and triple overtime hours; see the Paycodes topic.
  3. Configure a comment that is added to the double and triple overtime paycode edits; see the Comments topic.
  4. Deploy the Mexico3x3Overtime_v1 integration.
  5. Get the URL for the APIGatewayServer for the tenant.

Select the environment

  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. Select the Manage tab > Atom Management.
  3. 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.
  3. Select the integration pack: Mexico3x3Overtime > Mexico3x3Overtime_v1.

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.

Configure connection settings

  1. Select Connection Settings.

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

    Connection Settings
    Setting Required Actions
    APIGatewayServer Required

    To change the default API gateway server:

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

      Example: <tenantURL>/api

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 Mexico3x3Overtime_v1_ProcessProperties to set process properties that must be configured before the integration can run.

    Process Properties
    Property Required Actions
    Time Period Yes

    Time period for the integration run.

    Default = Previous_Payperiod.

    To change the time period:

    1. Clear Use Default.

    2. Enter the time period.
    Individual Employee IDs No

    Default = Include all employees.

    To process data for only a limited group of employees:

    1. Clear Use Default. 
    2. Enter the person numbers, as defined in the source system, each separated by a comma (,) but no spaces.

      Example: 13997,15556,20012
    Hyperfind Name Yes

    Default = 1 (shown as blank) which indicates All Home and includes all active employees.

    To use a Hyperfind query for another group of employees:

    1. Clear Use Default.
    2. Enter the ID of the Hyperfind.
      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 employee records, divide the population into smaller Hyperfinds to run sequentially.
    Edit Sign Off Period Yes

    Default = False.

    To include the signed0off period during processing:

    1. Clear Use Default.

    2. Enter True.

    Note:

    If True, the integration processes the time period provided by the user, even if it includes a signed-off period.

    If False, the integration processes only the unsigned-off period.
    Double Overtime Pay Code Yes

    To change the paycode used to assign double overtime hours:

    1. Clear Use Default.

    2. Enter <user-defined paycode name, such as Double Time.>.
    Triple Overtime Pay Code Yes

    To change the paycode used to assign triple overtime hours:

    1. Clear Use Default.

    2. Enter <user-defined paycode name, such as Triple Time.>.
    Include Occurrences Per Week Yes

    Default = False.

    To enable all three conditions during the calculation of double and triple overtime:

    1. Clear Use Default.

    2. Enter True.

    Note:

    If True, include Conditions 1, 2, and 3 when calculating double and triple overtime hours.

    If False, include only Conditions 1 and 2 when calculating double and triple overtime hours.
    Generic Overtime Pay Code Yes

    To change the paycode used for generic overtime hours:

    1. Clear Use Default.

    2. Enter <user-defined paycode name, such as Overtime.>.

    Note: Use a comma-separated list when multiple paycodes exist.
    Week First Day Yes

    Default = Monday.

    To change the start day of the week:

    1. Clear Use Default.

    2. Enter Tuesday, Wednesday, Thursday, Friday, Saturday, or Sunday.
    Process Default Period Yes

    Default = True.

    To process only the unsigned-off period:

    1. Clear Use Default.

    2. Enter False.

    Note:

    If True, the integration processes the time period provided by the user even if it contains the signed-off period.

    If False, the integration processes only the unsigned-off period.

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.

A cross-reference table (CRT) translates parameter values in an integration as follows:

  • Organizes data values into rows and columns:
    • Maximums = 20 columns, 10,000 rows.
  • Can combine values from multiple columns to determine a single output value.
  • 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 list, select the Mexico3x3Overtime_v1_CRTConfig cross-reference table to define localized values:

Column headers and definitions:

Parameter Name, Locale Policy, Value, Description.

Parameter Name = Parameter defined in Mexico3x3Overtime_v1_Message_CRT.

Locale Policy = Locale Policy for which the label or message applies.

Value = Message shown in Additional Details, or value of the label defined in the Run Summary section.

Description = Description shown in Additional Details; (optional) allows configuration of dynamic values.

Note:

  • Localization of integration extensions remains optional, but is supported.

  • The cross-reference table (CRT) 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 CRT.

  • Names of the parameters in the CRT 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 CRT with the appropriate Locale Policy, and then add the localized values in the Message (or Value) and Description CRT columns.

  • Do not enter values in the CRT column "Description" if it is blank.

  • Do not modify placeholders (<>) or the configurable values that are included in the CRT column "Message" (or "Value").

Select Override to:

  • Download the tables when you run the integration
  • Edit the table cells in Extensions

Click Tap OK.

Install the Mexico 3x3 Overtime integration

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. Enter a unique Integration Name.
  4. (Optional) Enter a Description.

    5. Note: Do not select API Integration.

  5. In File Access, select None to not select a connection.
  6. (Optional) If the person who runs the integration does not 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.

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

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

    9. Note: Do not select Allow Minute Interval.

  9. Integration template and parameters
    1. In Integration Template, select Mexico3x3Overtime_v1.
    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 Tap Save.

      Repeat this step for each Integration Parameter that supports the Mexico 3x3 overtime process.

       

      (Required) Specify the time period for the integration run.

      Time Period
      Parameter Name(Required) Enter Time Period.
      Description(Optional) Select symbolic period or start and end dates.
      Template Parameter

      (Required) Select Time Period.

      Parameter Type

      (Required) Select Time Period.

      Default Value

      (Required)

      Default = Previous_Payperiod.

      User Prompted

      To prompt the person who manually runs the integration to set this parameter, select Yes.

       

      (Optional) Specify the Individual Employee IDs that the Mexico 3x3 Overtime will process.

      Individual Employee IDs
      Parameter Name(Optional) Enter Individual Employee IDs.
      Description(Optional) Provide comma-separated Person Numbers.
      Template Parameter

      (Required) Enter Individual Employee IDs.

      Parameter Type

      (Required) Select Text.

      Default Value(Optional) Enter Individual Employee IDs.
      User Prompted

      To prompt the person who manually runs the integration to set this parameter, select Yes.

       

      (Required) Specify the default hyperfind query that contains the employees.

      Hyperfind ID
      Parameter Name(Required) Enter Hyperfind ID.
      Description(Optional)
      Template Parameter(Required) Select Hyperfind ID.
      Parameter Type(Required) Select Hyperfind.
      Default Value(Optional) Enter 1 = All Home Locations.
      User Prompted

      To prompt the person who manually runs the integration to set this parameter, select Yes.

       

      (Required) Specify whether the integration includes the signed-off period.

      Process Signed Off Data
      Parameter Name(Required) Enter Process Signed Off Data.
      Description(Optional)
      Template Parameter

      (Required) Select Edit Sign Off Period.

      Parameter Type

      (Required) Select Boolean.

      Default Value

      (Required)

      Default = false.

      To use an alternative value:

      1. Clear Use Default.

      2. Enter true.

      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      (Required) Specify the paycode name used to assign double overtime hours.

      Double Overtime Pay Code
      Parameter Name(Required) Enter Double Overtime Pay Code.
      Description(Optional)
      Template Parameter

      (Required) Select Double Overtime Pay Code.

      Parameter Type

      (Required) Select Text.

      Default Value

      (Optional) Enter <name of the double overtime paycode.>

      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      (Required) Specify the paycode name used to assign triple overtime hours.

      Triple Overtime Pay Code
      Parameter Name(Required) Enter Triple Overtime Pay Code.
      Description(Optional)
      Template Parameter

      (Required) Select Triple Overtime Pay Code.

      Parameter Type

      (Required) Select Text.

      Default Value

      (Optional) Enter <name of the triple overtime paycode.>

      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      (Required) Specify whether the integration calculates double and triple overtime paycodes.

      Include Occurrences Per Week
      Parameter Name(Required) Enter Include Occurrences Per Week.
      Description(Optional)
      Template Parameter

      (Required) Select Include Occurrences Per Week.

      Parameter Type

      (Required) Select Boolean.

      Default Value

      (Required)

      Default = false.

      To use an alternative value:

      1. Clear Use Default.

      2. Enter true.

      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      (Required) Specify generic overtime paycode name.

      Generic Overtime Pay Code
      Parameter Name(Required) Enter Generic Overtime Pay Code.
      Description(Optional) Provide comma-separated generic overtime paycodes.
      Template Parameter

      (Required) Enter Generic Overtime Pay Code.

      Parameter Type

      (Required) Select Text.

      Default Value

      (Optional) Enter <name of the generic overtime paycode.>

      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      (Required) Specify start day of week.

      Week first day
      Parameter Name(Required) Enter Week first day.
      Description(Optional)
      Template Parameter

      (Required) Enter Week start day.

      Parameter Type

      (Required) Select Text.

      Default Value

      (Optional)

      Default = Monday.

      To use an alternative value:

      1. Clear Use Default.

      2. Enter Tuesday, Wednesday, Thursday, Friday, Saturday, or Sunday.

      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

      (Required) Specify default processing period.

      Process Default Period
      Parameter Name(Required) Enter Process Default Period.
      Description(Optional)
      Template Parameter

      (Required) Select Default Processing Period.

      Parameter Type

      (Required) Select Boolean.

      Default Value

      (Required)

      Default = true.

      To use an alternative value:

      1. Clear Use Default.

      2. Enter false.

      User Prompted

      If the value does not need to be changed when the integration runs, select No.

       

  10. Click Tap Save.
  11. Ensure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. Select Administration > Application Setup > Integrations Setup > Access Profiles; 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 Mexico3x3Overtime_v1 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 system assigns a default name, which ends with a date and time stamp.
  2. Set parameters as follows:
    • Time Period: Select a pay period.
    • 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

    • Hyperfind: Select a hyperfind query of employees.

  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:

  1. 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 ensure 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.

APIs

API details
API name Section Type Resource path Location Description
Retrieve Paycodes Timekeeping POST v1/timekeeping/setup/pay_codes/multi_read _ValidatePayCodes Retrieve paycodes.
Update Integration Execution Details Platform POST v1/platform/integrations/update_status _WFD Callback Provide summary of integration run.
Execute Hyperfind Query Commons POST /v1/commons/hyperfind/execute _ExecuteHyperfind Retrieve employee by Hyperfind.
Retrieve Signoffs as Manager Timekeeping GET /v1/timekeeping/timecard_signoffs _RetrieveDefaultTimePeriodSpan Retrieve timecard signoffs as a Manager.
Retrieve Timecard Data for Multiple Employees Timekeeping POST v1/timekeeping/timecard_metrics/multi_read?partial_success=true _RetrieveTimecardData Retrieve timecard actual totals without corrections.
Bulk Enable Edits Timekeeping POST v1/timekeeping/enable_edits/import _BulkEnableEdits Enable timecard editing for signed-off timecard.
Update Timecard as Manager Timekeeping POST v1/timekeeping/timecard _UpdateTimecardData Add or update timecard paycode.