Flexible Break Adjustment
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.
Total break concept
- 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.
How it works
- 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 start
Before you configure this integration, you must do the following:
- Configure 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.
-
Get the URL, User, and Password for the APIGatewayServer.
Configure the Flexible Break Adjustment integration
- Deploy the Flexible Break Adjustment integration
Note: For more information, see the Deploy Integration Packs to your Atom topic.
-
Open the Integration Template Designer: Select Main Menu
. Note: If prompted, enter your Username and Password. Click Tap Log in. -
Make sure that the Account is correct. If not, select the right account.
- Select the Deploy tab > Integration Packs.
- From the list in the left column, search for and select the Pro WFM Flexible Break Adjustment Extension integration. Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.
-
Click Tap Install.
-
From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button
.
-
- Configure the Flexible Break Adjustment integration settings
- Select the environment
- Select the Manage tab > Atom Management.
- Select your environment.
- Select environment extensions
- In Administration, click tap Environment Extensions.
- In Process Filter, click tap the magnifying glass
. It can take several seconds before the button becomes active.
- Scroll to and select the integration pack: .
- Select the environment
- 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.
- Select Connection Settings.
-
From the Connection list, select and configure the following:
Connection Settings
Connection Settings for the integration
Setting
Required
Actions
FlexibleBreakAdjustment_iPack_v6_APIGatewayServer
Required
To change the default API gateway server:
- Clear Use Default.
- Enter the URL to the server.
Example:
<tenantURL>/api
FlexibleBreakAdjustment_iPack_v6_ThresholdRules_CRT
Required
Enable Override.
FlexibleBreakAdjustment_iPack_v6_Locale_CRT
Required
Enable Override.
- Configure process properties
- 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.
-
Select FlexibleBreakAdjustment_iPack_v6_CRTConfig 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
Process properties
Process property name
Column header value
_FlexibleBreakAdjustment_iPack_v6_ThresholdRules_CRT
Work Rule,Worked Hours,Paid Amount,Total Break,Break No.
_FlexibleBreakAdjustment_iPack_v6_Locale_CRT
Parameter Name,Locale Policy,Value,Description
- Select Process Properties.
- 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.
Note:- 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.
- Select Cross Reference.
-
From the Cross Reference dropdown list, select a FlexibleBreakAdjustment_iPack_v6 table.
-
Select Override to:
- Download the tables when you run the integration
- Edit the table cells in Extensions
-
When you finish, click tap OK.
- Repeat the steps for each of the FlexibleBreakAdjustment_iPack_v6 tables.
- FlexibleBreakAdjustment_iPack_v6_ThresholdRules_CRT: Contains the work rule details for the employee.
Flexible Break Adjustment — Threshold Rules CRT
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_iPack_v6_Locale_CRT: Allows translation of messages and labels into different languages.
Flexible Break Adjustment — Locale CRT
Flexible Break Adjustment — Locale CRT
Column name
Description
Parameter Name
Key for which localization is defined.
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").
Sample Locale CRT content
Sample Locale CRT content
Parameter name
Locale Policy
Value
Description
Error_EmployeeNotFound
*
Employee not found.
Employee not found in application.
Error_Invalid
*
Hyperfind or Employee Id not found or invalid
Hyperfind or Employee ID is not found or is invalid.
Error_InvalidComment
*
Invalid comment category assigned or not found.
Error_NoPersonNumber
*
Hyperfind and Person Number was not provided.
Error_SignedOffDate
*
Signoff-Date retrieval
Label_AdditionalDetails
*
Process completed with transaction errors. Additional details, such as disqualifications, may be accessible using the button below.
Label_BreakNotRequired
*
Break Not Required
Label_ExcludedPaycode
*
Exclude Paycode
Label_ExcludedRecords
*
Excluded Records
Label_FailedRecords
*
Failed Records
Label_PhantomPunch
*
Phantom Punch
Label_ProcessedShifts
*
Processed Shifts
Label_ProcessedSourceEmployees
*
Processed Source Employees
Label_IntegrationType
*
Integration Type
Label_IntegrationTypeValue
*
Import
Label_TransactionEnabled
*
Process completed with transaction errors. If Transaction Assistant is enabled, failed records can be re-submitted through Transaction Assistant.
Label_WithoutErrors
*
Integration completed without errors.
Label_WithoutTransactionErrors
*
Integration completed without transaction errors. Additional details, such as disqualifications, may be accessible using the button below.
Message_BatchRun
*
Batch Run
Message_BreakStatus
*
Either the employee has already taken the required break or total worked hours are less than eligible hours.
Message_DataRetrieval
*
Data Retrieval
Message_FailedShifts
*
Failed Shifts
Message_IncorrectNote
*
Incorrect Note
Message_SettingDateRange
*
Setting Date range
Message_SignedOff
*
Signed-Off period
The time period from <STARTDATE> to <ENDDATE> is Signed Off.
Message_SymbolicPeriod
*
Symbolic Period
Message_TimeCardMetrics
*
Timecard Metrics
Message_WorkruleError
*
Either the employee has already taken required break or total worked hours are less than eligible hours.
-
- FlexibleBreakAdjustment_iPack_v6_ThresholdRules_CRT: Contains the work rule details for the employee.
Install the Flexible Break Adjustment 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.
-
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.
- Select Main Menu
. - Click Tap Create
. - In Integration Name enter a unique name, such as
FlexibleBreakAdjustment_iPack_v6
. - (Optional) Enter a Description.
Note: Do not select API Integration.
- In File Access, select None to not select a connection.
- (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.
-
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
-
Email Notifications
(Optional)
- Select Yes to send email and control center notifications for integration runs.
- 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.
- 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.
- Integration template and parameters
- In Integration Template, select FlexibleBreakAdjustment_iPack_v6.
- Click Tap Assign
. - In Integration Parameters, you can override default settings. Click Tap Create.
- Complete the configuration for each integration control parameter value.
-
Click Tap Save.
Repeat this step for each integration control parameter that supports the Flexible Break Adjustment process.
Integration Parameters
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.HyperfindID
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
SymbolicPeriod
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
BreakSegmentMinAmount(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
BreakAdjustmentOverride-Paycode
Text
Break Adjustment - Execution
Controls the break adjustment execution.
Supported values include:
-
Immediate
(default) -
Increment
User prompt = No
Mandatory = Yes
BreakAdjustment-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
BreakAdjustmentOverride-PaycodeMinAmount(hh:mm)
Text
Break Exception Work Rule
The work rule used for exceptions.
User prompt = No
Mandatory = Yes
BreakExceptionWorkRule
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
BreakPlacement-NoBreakTaken
Dropdown
Break Adjustment - Comment Selection
The comment that the timecard displays when punches are updated.
User prompt = No
Mandatory = Yes
BreakAdjustment-CommentSelection
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
BreakAdjustment-IncludePriorDeductionsinTotals
Dropdown
Break Adjustment - Back Tracking Notes
Defines notes to separate backtrack punches from normal punches.
Default =
blank
User prompt = No
Mandatory = Yes
BreakAdjustment-BackTrackingNotes
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
BreakPlacementShortTotalBreak
Text
Flexible Break Overtime
Controls whether to consider worked overtime duration.
Supported values include:
-
true
(default) -
false
User prompt = Yes
Mandatory = No
FlexibleBreakOvertime
Boolean
Rounded Punches
Controls whether to round the In and Out punches.
Supported values include:
-
true
(default) -
false
User prompt = Yes
Mandatory = N
RoundedPunches
Boolean
-
- Make sure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. Select Configure Access to Integrations. . See
Run and test the Flexible Break Adjustment integration
Run integrations to test that the configuration is set up correctly.
-
Run the integration
- Select the integration:
- Select
Main Menu
. -
Click Tap
Run an Integration
. - Select the FlexibleBreakAdjustment_iPack_v6 integration from the list. Click Tap Select.
- (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.
- Select
Main Menu
-
Set parameters as follows:
- Hyperfind: Select a Hyperfind query of employees.
- Symbolic Period: Select a pay period or date range.
- Flexible Break Overtime: Select whether to consider worked overtime duration.
- Rounded Punches: Select whether to round the punches.
-
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.
- Wait for the confirmation that the integration completed or failed. Close the panel.
-
Click Tap
Refresh
. - To see details, select the integration run. Select Run Summary.
- Select the integration:
-
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:
- Click Tap the tile for the integration run.
-
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.
- 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 Schedule Integrations topic.
-
APIs
API name |
Type |
Resource path |
Description |
---|---|---|---|
POST |
/v1/timekeeping/timecard/multi_read |
Retrieves all punch details. | |
GET |
v1/commons/comments |
Returns a filtered list of comments. | |
POST |
/v1/timekeeping/timecard |
Performs add or update on a timecard. | |
POST |
/v1/platform/integrations/update_status |
Logs integration execution information. | |
POST |
/v1/platform/integration_executions/ |
Returns integration details including start and end time, parameter settings, integration status, and which employee ran the integration. | |
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. | |
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. | |
POST |
/v1/timekeeping/timecard_metrics/multi_read |
Returns timecard data for a set of employees or locations. | |
POST |
/v1/commons/hyperfind/execute |
Executes a Hyperfind query by ID or qualifier, and returns the results. | |
GET |
/v1/commons/symbolicperiod |
Returns all symbolic periods in the system. | |
GET |
/v1/commons/user_preferences/locale_policy |
Returns user's current locale policy. |
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:
|
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:
|
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. |
iPack_v6 |
The Flexible Break Adjustment integration delivery is now by way of an iPack. |
The Flexible Break Adjustment integration did not apply an expected third break when the integration was configured to consider prior deductions in totals. The integration now applies the third break in accordance with configurations. |