Flexible Break Adjustment

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.

The Flexible Break Adjustment integration adjusts breaks to allow employees flexibility when they take breaks and improve compliance with local rules.

This integration compares the actual worked hours (worked hours — all punched breaks) to the shift segments for breaks and the minimum-break threshold in the cross-reference table.

This topic describes how to configure the Flexible Break Adjustment integration.

  • Work rules no longer include standard break and deduction rules; instead, the integration imports those rules.
  • If an employee does not take a required break, the integration inserts a break adjustment with a work-rule transfer. This symbolic work rule does not affect the configuration, while the transfer stops the time for the calculated duration. The transfer is inserted in the shift so that it adjusts for premium or overtime zones, or transfers that are in effect. The system inserts a break or extends an existing break for the calculated duration.
  • The integration inserts an exception and comment to indicate and explain the adjustment.
  • After the break adjustment, the previously worked transfer string is restored: work rule > labor category > cost center > job.
  • Employees punch their breaks as usual.​
  • The integration imports the break parameters from a cross-reference table.​
  • The integration summarizes all breaks and compares the actual breaks with the total allowed breaks and legislative restrictions.​
  • When breaks are shorter than required, a work rule transfer makes the adjustments, and the integration processes only the exceptions.​
  • The integration correctly places the adjustments in the shifts honoring premium or overtime zones or transfers.​

Before you configure this integration, you must do the following:

Hyperfind: Configure a Hyperfind or Location query that includes only employees for whom the Flexible Break Adjustments are applicable. See the Hyperfind queries topic.

Comments: Configure a comment, such as Adjustment by Integration, that the integration adds to the timecard along with the employee's break adjustment information. The punches category must be selected during configuration. See the Comments topic.

Combined paycode: Create a combined paycode that includes all paycodes that this integration excludes. See the Combined Paycodes topic.

Name: Break Adjustment Override

Select Hours in Summarize In.

Select Visible in Report Options and Report Totals.

Select Visible on Totals tab in Timecard.

Select the ANNUAL LEAVE, PERSONAL LEAVE UNPAID, and Sick paycodes in Available Paycodes, and move them to Selected Paycodes.

Deduction rule: Create a deduction rule that includes the deduction amount for the Exception work rule. See the Bonus and Deductions topic.

Name: Total Break Deduction

Amount: -1:30

Caution: Use one amount for the entire organization; that is, the maximum amount of breaks as specified in the legislation.​

Applies On: select all days

Select Is Exception.

Allow cancellation in timecard: Yes

Select Do not use shift restriction in Shift Restriction.

Leave Pay code and Cancel if break taken at the default settings.

Use rounded shift boundary times: Yes

Short break exception disqualifies break: No

Break rule: Create break rules that will be assigned to work rules specific to the integration. See the Breaks topic.

Name: Total Break Segment

In Break Lengths, enter:

  • Normal Length = 0:15

  • Medium Length = 0:00

  • Max Length = 2:00

In Break Settings, Relative to, select Scheduled Start.

Name: Total Break Rule

In Break Lengths, enter:

  • Normal Length = 0:00

  • Medium Length = 0:00

  • Max Length = 1:30

Caution: Use one amount for the entire organization; that is, the maximum amount of breaks as specified in the legislation.​

In Break Settings, Relative to, select 12 Midnight.

Punch interpretation rule: Create a punch interpretation rule that will be assigned to the employee's pay rule. See the Punch Interpretation Rules topic.

Name: Standard

Select Full in Punch Restrictions.

Select Yes in Allow Overrides.

In Schedule Start, enter:

  • Early Start Margin = 4:00

  • Early Start Restriction = 24:00

  • Late Start Restriction = 24:00

  • Late Start Margin = 4:00

In Missed In, enter End Margin = 1:00.

In Breaks, enter:

  • Maximum Out = 0:30

  • Minimum Meal = 0:30

  • Enforce Breaks = No

  • Early Start Break Margin = 0:15

  • Late Start Break Margin = 0:15

  • Late End Break Margin = 0:15

In Schedule End, enter:

  • Begin Early End Restriction = 24:00

  • Lift Early End Restriction = 24:00

  • Late End Restriction = 24:00

In Missed Out, enter Missed Out Margin = 16:30

In Unscheduled, enter:

  • Restrict unscheduled in-punches = No

  • Unscheduled Shift Length = 8:00

Schedule deviations: Configure the schedule deviations that are assigned to the employee's work rule. See the Schedule Deviations topic.

Insert a new row.

Select Before Shift, After Shift, Not Scheduled, and Requires Approval.

Work rules: Create two work rules that apply the adjustments or exceptions. See the Work Rules topic.

Name: Flexible Breaks

Note: This work rule will be visible in the Timecard.

In Breaks, move Total Break segment to Selected Breaks.

Name: Break Adjustment

Note: This work rule is used for the adjustment and will be visible in the Timecard. Assign this break rule to employees for whom the Flexible Break Adjustments are applicable.

In Breaks, move Total Break Rule to Selected Breaks.

In Bonuses/Deductions, move Total Break Deduction to Selected Bonuses/Deductions.

In Paycode for Unapproved Overtime, select Unapproved Overtime.

In Paycode for Denied Overtime, select Overtime to be approved.

Leave Core Hours blank.

Version history
Version Description
1

Initial release.

Calculates break adjustment based on worked hours and threshold values defined in the CRT.
2

Enhanced to support:

  • Re-runnability.

  • Phantom punches and inactive employees.
3

Performance optimization.

Addressed an issue related to the incremental break placement when total worked hours are more than required hours, but less than total worked hours+break required.
4 Performance optimization.
5

Enhanced to support:

  • Rounded punch consideration.

  • Break adjustment according to overtime approved by manager.

  • Localization.
5.1 Addressed an issue related to a duplicate API punch request
5.2

Addressed an issue related to break adjustment.
5.3

Addressed an issue to fix duplicate timecard data.

  1. Configure Access to Integrations.

  2. Deploy the FlexibleBreakAdjustment_v5.3 integration. See the Deploy Integrations topic.
  3. 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. Scroll to and select the integration pack: FlexibleBreakAdjustment > FlexibleBreakAdjustment_v5.3.

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 dropdown list, select and configure the following:

    Connection Settings
    Setting Required Actions
    FlexibleBreakAdjustment_v5.3_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 FlexibleBreakAdjustment_v5.3_CRTConfig.

  3. For each process property, disable the Use Default option, and then provide the cross-reference table (CRT) column header value.

    Process properties
    Process property name Column header value
    _FlexibleBreakAdjustment_v5.3_ThresholdRules_CRT Work Rule,Worked Hours,Paid Amount,Total Break,Break No.
    _FlexibleBreakAdjustment_v5.3_Message_CRT Parameter Name,Locale Policy,Value,Description

  1. In the Cross Reference section, enable the override option for each CRT.

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 a FlexibleBreakAdjustment table.

  3. Select Override, which allows you to:

  • Download the tables when you run the integration
  • Edit the table cells in Extensions
  1. When you finish, click tap OK.

Repeat the steps for each of the FlexibleBreakAdjustment tables.

FlexibleBreakAdjustment_v5.3_ThresholdRules_CRT: Contains the work rule details for the employee.

Flexible Break Adjustment — Threshold Rules CRT
Column name Description
Work Rule The work rule assignment that determines how employee hours accrue.
Worked Hours The threshold of hours that the employee must work to qualify for the break.
Paid Amount Paid break amount, or duration given to the employee.
Total Break Total break amount, or duration given to the employee.
Break No. Break sequence count.

FlexibleBreakAdjustment_v5.3_Message_CRT: Allows translation of messages and labels into different languages.

Flexible Break Adjustment — Message CRT
Column name Description
Parameter Name Parameters defined in FlexibleBreakAdjustment_v5.3_Message_CRT process property.
Locale Policy

Locale Policy.

You can use an asterisk (*) as a wildcard, but put the less-restrictive locale policy names at the bottom of the table because the integration scans cross-reference tables from the top.
Value

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

Comment was not provided.

Description

The description that is shown in Additional Details.

The employee is not assigned a shift.

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").

Parameter names
Parameter name Locale Policy Value Description
_MessageInvalid * Hyperfind or Employee Id not found or invalid Hyperfind or Employee ID is not found or is invalid.
_MessageEmployeeNotFound * Employee not found. Employee not found in application.
_MessageSignedOff * Signed-off period. The time period from <STARTDATE> to <ENDDATE> is signed-off.

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 FlexibleBreakAdjustment_v5.3.
  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 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.

  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 FlexibleBreakAdjustment_v5.3.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings. Click Tap Create.
    4. Complete the configuration for each integration control parameter value.

    5. Click Tap Save.

      Repeat this step for each integration control parameter that supports the Flexible Break Adjustment process. Sample parameters listed below.

      Integration Parameters
      Parameter name Description / User prompt / Mandatory Template parameter Parameter type
      Hyperfind ID

      The default Hyperfind query that contains the employees for whom the integration is run.

      Default = 1 (All Home Locations)

      User prompt = Yes

      Mandatory = 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.

      		 Hyperfind ID Hyperfind
      Symbolic Period

      Symbolic name for the pay period or date range.

      Adjustments are made only in unsigned-off pay periods.

      Default = Auto-populated

      User prompt = Yes

      Mandatory = Yes

      		 Symbolic Period Time Period
      Break Segment Min Amount (hh:mm)

      The minimum length of time that qualifies as a break.

      Default = 00:01.

      User prompt = No

      Mandatory = Yes

      		 Break Segment Min Amount (hh:mm) Text
      Break Adjustment Override — Paycode

      The combined paycode used to override the break adjustment.

      Default = blank (No paycode is excluded)

      User prompt = No

      Mandatory = Yes

      		 Break Adjustment Override — Paycode Text
      Break Adjustment — Execution

      Controls the break adjustment execution.

      Supported values include:

      • Immediate (default)

      • Increment

      User prompt = No

      Mandatory = Yes

      		 Break Adjustment — Execution Dropdown
      Break Adjustment Override - Paycode Min Amount (hh:mm)

      The minimum amount of time that must exist in the combined override paycode (hh:mm).

      Default = 00:01 (Required only when Break Adjustment Override — Paycode is not blank.)

      User prompt = No

      Mandatory = Yes

      		 Break Adjustment Override - Paycode Min Amount (hh:mm) Text
      Break Exception Work Rule

      The work rule used for exceptions.

      User prompt = No

      Mandatory = Yes

      		 Break Exception Work Rule Text
      Break Placement - No Break Taken

      Defines the position in the shift of the break placement when no break is taken.

      Supported values include:

      • Threshold

      • Threshold + Previous Break (default)

      User prompt = No

      Mandatory = Yes

      		 Break Placement - No Break Taken Dropdown
      Break Adjustment - Comment Selection

      The comment that the timecard displays when punches are updated.

      User prompt = No

      Mandatory = Yes

      		 Break Adjustment - Comment Selection Text
      Break Adjustment - Include Prior Deductions in Totals

      Controls whether to consider prior deductions in totals.

      Supported values include:

      • true

      • false (default)

      User prompt = No

      Mandatory = Yes

      		 Break Adjustment - Include Prior Deductions in Totals Dropdown
      Break Adjustment - Back Tracking Notes

      Defines notes to separate backtrack punches from normal punches.

      Default = blank

      User prompt = No

      Mandatory = Yes

      		 Break Adjustment - Back Tracking Notes Text
      Break Placement - Short Total Break

      Controls the break placement when breaks have been taken that exceed the threshold.

      Default = Last Break Segment

      User prompt = No

      Mandatory = No

      		 Break Placement - Short Total Break Text
      FlexibleBreak Overtime

      Controls whether to consider worked overtime duration.

      Supported values include:

      • true (default)

      • false

      User prompt = Yes

      Mandatory = No

      		 FlexibleBreak Overtime Boolean
      Rounded Punches

      Controls whether to round the In and Out punches.

      Supported values include:

      • true (default)

      • false

      User prompt = Yes

      Mandatory = N

      		 Rounded Punches Boolean
  2. Make sure 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 FlexibleBreakAdjustment_v5.3 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:
    • Hyperfind: Select a Hyperfind query of employees.
    • FlexibleBreak Overtime: Select whether to consider worked overtime duration.
    • Rounded Punches: Select whether to round the punches.

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

API details
API name Type Resource path Description
Retrieve Timecards—Manager POST /v1/timekeeping/timecard/multi_read Retrieves all punch details.
Retrieve Comments GET v1/commons/comments Returns a filtered list of comments.
Add Timecard POST /v1/timekeeping/timecard Performs add or update on a timecard.
Status update POST /v1/platform/integrations/update_status Logs integration execution information.
Retrieve All Integration Executions POST /v1/platform/integration_executions/ Returns integration details including start and end time, parameter settings, integration status, and which employee ran the integration.
Retrieve Symbolic period POST /v1/commons/symbolicperiod/read Returns a locale date span, or symbolic period. The data can include location ID, employee ID, person number, current user, and current tenant.
Retrieve Signoff date POST /v1/commons/persons/extensions/multi_read Returns multiple person records based on search criteria. Search criteria included personID, person number, job assignment ID, user name, user account ID, and badge number.
Get Timecard Data POST /v1/timekeeping/timecard_metrics/multi_read Returns timecard data for a set of employees or locations.
Retrieve Employees from Hyperfind POST /v1/commons/hyperfind/execute Executes a Hyperfind query by ID or qualifier, and returns the results.
Get Symbolic Period GET /v1/commons/symbolicperiod Returns all symbolic periods in the system.
Retrieve Current User Locale GET /v1/commons/user_preferences/locale_policy?userCurrent=true Returns user's current locale policy.