Meal Penalties

Enterprise agreements can define that when a break rule is violated, employees are entitled to extra payments that are known as meal penalties.

Note: This integration is an extension that is developed outside the normal release schedule to meet specific customer needs; it must be installed by an Integration Consultant. To request one of these extensions, you must submit a request by way of the Gateway Request Portal for BITS, accompanied by a change order.

Each enterprise agreement defines its own set of meal penalties.

Example meal penalties:

LATE MEAL PENALTY: The employee takes a break after the maximum consecutive hours someone can work without taking a break. You can configure late-penalty amounts for up to 3 breaks.
MISSED MEAL PENALTY: The employee works a long shift without taking a meal break.
EARLY MEAL PENALTY: The employee takes a break before having worked the minimum number of hours that is required to take the break.
SHORT MEAL PENALTY: The employee takes a break that is shorter than the legal length.

The Meal Penalty integration grants a meal penalty to employees who are assigned the pay rules configured in the in the Parameters Map cross-reference table when a break rule is violated. This integration applies a paycode edit to the employee’s timecard to grant the meal penalty.

The system monitors worked shifts and validates whether breaks are being taken according to the rules as follows:

Rule sets are linked to pay rules.
When a break rule is violated, the system adds a Penalty paycode to the employee’s timecard.
The monetary value of the penalties can be configured in the paycode or by adjustment or percent allocation rules.
A comment in the Penalty paycode provides information about which penalty was initiated.
Break validation is done for the current and previously unsigned off pay periods. Validation can be configured to work with the elapsed shift length for late meals, or worked length excluding already taken breaks, instead of the fixed interval.

An optional feature excludes meal penalties on days, such as public holidays, when a specifically configured combined paycode appears in the totals add-on of the employee timecard.

Considerations and limitations

Do not configure an automatic break-deduction rule when you configure and use the Meal Penalty integration.
Make sure that the employee’s work rule has only break rule because the integration generates the penalty.
Do not enable multiple penalties in the same integration. Otherwise, conflicts can occur. Example: A Late Meal or a Missed Meal can be interpreted the same way.

Use cases

Late meal

If the employer does not allow an employee to take a 60-minute meal break for a shift of more than 6 hours, the employee is paid a penalty at the rate of 150% of the hourly base rate for each hour or part of an hour from 6 hours after the employee started work until the employer gives the employee the unpaid meal break, or until the shift ends. Breaks should not be taken earlier than 3 hours, or later than 6 hours, after start of the shift.

Parameters:

IsLateMealPenaltyRequired = TRUE
FirstLate = Late Meal Penalty paycode
MealBreakAmount = 1440 to generate a penalty amount until the end of shift
MinWorkLength = 180, the minimum work length in minutes before initiating a meal penalty
MaxWorkLength = 360, the maximum work length in minutes before initiating a meal penalty
MinShiftLengthFor1stMealBreak = 360, the minimum shift length in minutes to be eligible for a first meal break

Multiple late meals

Employees are entitled to the following meal breaks according to the actual time worked. Each time an employee cannot take a break within the thresholds, the employee is awarded a late-meal penalty.

Break 1 = 15 minutes taken no later than after 4 hours of worked time.
Break 2 = 30 minutes taken no later than after 6 hours of worked time.
Break 3 = 15 minutes taken no later than after 9 hours of worked time.

An employee worked from 8 am—7 pm but could not take any of the 3 breaks on time.

The integration inserts a Late Meal Penalty for the time worked over 4, 6, and 9 hours until the employee took the breaks.

Because the penalties are configured to use actual hours worked and not the elapsed shift length, the penalties are at 12 pm, 2:15 pm, and 5:45 pm.

Example Meal Penalities Multiple Late Meals

Missed meal

If the employer does not allow an employee to take a 60-minute meal break during a shift of more than 6 hours, the employee is paid a penalty at the rate of 150% of the hourly base rate for the time of the missed break.

Parameters:

IsMissedMealPenaltyRequired = TRUE
FirstMissed = Missed Meal Penalty paycode
MealBreakAmount = 60, length of the break and penalty amount
MinWorkLength = 180, the minimum work length in minutes before initiating a meal penalty
MaxWorkLength = 360, the maximum work length in minutes before initiating a meal penalty
MinShiftLengthFor1stMealBreak = 360, the minimum shift length in minutes to be eligible for a first meal break

Early meal

Employees cannot be required to take their break earlier than 3 hours, or later than 6 hours, after the start of the shift. If the employer requires an employee to take the break earlier, the employee is paid a penalty at the rate of 50% of the hourly base rate from the start of their break until the official start time of the break.

Parameters:

IsEarlyMealPenaltyRequired = TRUE
FirstEarly = Early Meal Penalty paycode
MealBreakAmount = 180 to generate a penalty amount for a maximum of 3 hours
MinWorkLength = 180, the minimum work length in minutes before initiating a meal penalty
MaxWorkLength = 360, the maximum work length in minutes before initiating a meal penalty
MinShiftLengthFor1stMealBreak = 360, the minimum shift length in minutes to be eligible for a first meal break

Short meal

Employees are entitled to a 60-minute meal break for a shift of 6 hours and longer. If the employer requires an employee to shorten the break, the employee is paid a penalty at the rate of 150% of the hourly base rate for the length of the short break.

Parameters:

IsShortMealPenaltyRequired = TRUE
FirstShort = Short Meal Penalty paycode
MealBreakAmount = 60, the maximum penalty
MinWorkLength = 180, the minimum work length in minutes before initiating a meal penalty
MaxWorkLength = 360, the maximum work length in minutes before initiating a meal penalty
MinShiftLengthFor1stMealBreak = 360, the minimum shift length in minutes to be eligible for a first meal break

Exclude meal penalty

However, meal penalty rules do not apply on public holidays.

Parameters:

IsLateMealPenaltyRequired = TRUE
FirstLate = Late Meal Penalty paycode
MealBreakAmount = 1440 to generate a penalty amount until the end of shift
MinWorkLength = 180, the minimum work length in minutes before initiating a meal penalty
MaxWorkLength = 360, the maximum work length in minutes before initiating a meal penalty
MinShiftLengthFor1stMealBreak = 360, the minimum shift length in minutes to be eligible for a first meal break
Exclude Penalty = true
Exclusion paycode = MealPenaltyExclusionCombined

An employee worked on a public holiday from 8 am—6 pm, but could not take the first meal break on time. No meal penalty is generated because the penalty is excluded.

Boomi extension setup

Caution: Allow only qualified personnel who have training in the Boomi™ application to configure or create integrations.

Important: Professional Services will complete Boomi extension setup steps and deploy the integration.

Get the URL, User, and Password for the APIGatewayServer.
Install and attach the iPack.
Note: For more information, see the Deploy Integration Packs to your Atom 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.
4. From the list in the left column, search for and select the Pro WFM Pro WFM Meal Penalty Extension integration.
  Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.
5. Click Tap Install.
6. 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 Meal Penalty integration settings
1. Select the environment
  1. Select the Manage tab > Atom Management.
  2. Select your environment.
2. Select environment extensions
  1. In Administration, click tap Environment Extensions.
  2. In Process Filter, click tap the magnifying glass . It can take several seconds before the button becomes active.
  3. Scroll to and select the integration pack: Meal Penalty > Meal Penalty_iPack_v4.

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

Connection Settings

Setting	Required	Actions
MealPenalty_iPack_v4_APIGatewayServer	Required	To change the default API gateway server: Clear Use Default. Enter the URL to the server. Example: `<tenantURL>/api`
MealPenalty_iPack_v4_SFTPServer	Required	The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account. To change the default SFTP server parameters: For each field, clear Use Default. Enter the following values: Enter the name of the internal Host. Enter the number of the Port for the internal SFTP account. In User, enter the username for the internal SFTP account. In Password, select <Encrypted>. Enter the new password for the internal SFTP account. Click Tap Apply.
MealPenalty_iPack_v4_ParametersMapCRT	Required	Enable Override.

Setting

Required

Actions

MealPenalty_iPack_v4_APIGatewayServer

Required

To change the default API gateway server:

Clear Use Default.
Enter the URL to the server.
Example: <tenantURL>/api

MealPenalty_iPack_v4_SFTPServer

Required

The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account.

To change the default SFTP server parameters:

For each field, clear Use Default.
Enter the following values:
- Enter the name of the internal Host.
- Enter the number of the Port for the internal SFTP account.
- In User, enter the username for the internal SFTP account.
- In Password, select <Encrypted>. Enter the new password for the internal SFTP account.
- Click Tap Apply.

MealPenalty_iPack_v4_ParametersMapCRT

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 MealPenalty_iPack_v4_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

Property name	Property type	Default value	Additional information
_FormattedHistoricalCorrectionPeriodEndDate	Control		Formatted historical correction period end date.
_UploadAudit	Control	none	Audit records upload location.
_UpdateOnCompletion	Control	true	Determines whether to update UKG Pro Workforce Management upon completion.
_API Retry Max Count	Control	1	API retry maximum count.
_API Retry Timeout (ms)	Control	60000	API retry timeout in milliseconds (ms).

Configure the Meal Penalties integration

After the integration is deployed, complete the following configurations before you utilize this integration.

Note: Configuration examples are intended for illustration purposes only, and do not necessarily represent the needs of your organization. We recommend that you analyze your organization's needs before completing application setup configuration.

Application setup

Configure Access to Integrations.
Configure the following:
- Comments: Create a comment that is attached to the meal penalty paycode. Select the Pay Codes category during configuration. See the Comments topic.
  Example: PR Meal Penalty
- Hyperfind: The public Hyperfind query that contains the employees processed by the integration. See the Hyperfind Queries topic.
- Paycodes: Create a paycode which provides the meal penalties. See the Paycode definition topic.
  Example: MLPR5
- Breaks: The pay rules that are assigned to the employees must have a break assigned in the relevant work rules. See the Breaks topic.
- Pay Rules: The pay rules that are assigned to the target employees. See the Pay Rules topic.
- Extension Tables: Create the extension tables that optimize Meal Penalties processing. See the Extensions Tables topic.
  Enter the following in the Commands for execution field for each extension table definition:
  Important:
  - The integration references the extension tables only when a Hyperfind selection is made during processing. It bypasses the extension tables when a specific person number selection is made during processing or when historical corrections are enabled.
  - Only one integration execution per Hyperfind can run at a time. Multiple integration executions can run simultaneously providing that each uses a different Hyperfind.
  - For optimal performance, we recommend that you schedule integrations that use a Hyperfind which includes up to 1,000 employees, and runs every 5 minutes.
```
Create TABLE mealpenaltylastpdatedon 
(
  HyperfindId VARCHAR(255),
  CRTHash VARCHAR(255),
  lastUpdatedOn VARCHAR(255),
  payperiod VARCHAR(255)
);
```
```
Create TABLE mealpenaltyexecutionstore
(
  HyperfindId VARCHAR(255) PRIMARY KEY,
  falconExecutionId VARCHAR(255),
  status VARCHAR(255)
);
```
```
Create TABLE mealpenaltylasttotaltime
(
  person_id BIGINT PRIMARY KEY,
  last_total_time TIMESTAMP NOT NULL
);
```

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.

To make a cross-reference table available for integration processes, populate the table with data.

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.

MealPenalty_iPack_v4_ParametersMapCRT: Defines the rulesets, parameters and values for which the integration performs meal penalty processing.

Meal Penalty - Parameters Map CRT structure

Column name	Description
RuleSet	Rule set name.
Parameter	Parameter name.
Value	Parameter value
Description	Description of the parameter.

Refer to the Meal Penalty - Parameters Map CRT example for values to enter into the table:

Meal Penalty - Parameters Map CRT example

Ruleset	Parameter	Value	Description
Meal60	AllowShortMealOverlap	FALSE	When set to false, deduct early or late penalty from the short penalty for the same meal period.
Meal60	ApplyLateMealPenaltyOnExit	FALSE	When set to true, the Late Meal Penalty is calculated also if the employee goes home during the last meal break segment.
Meal60	EarlyGrace		(Optional) The restriction value applies to the early meal before the rounding process. When configured, the EarlyRound must also be configured.
Meal60	EarlyRound		(Optional) The rounding value applies to the early meal after the grace restriction. When configured, the EarlyGrace parameter must also be configured.
Meal60	EnableMaxWorkLengthVariant	TRUE	When set to true, validate the Late Meal Penalty based on the elapsed work length from start of the shift, instead of from the elapsed time between meals.
Meal60	ExcludePenaltyDuration	FALSE	When set to true, exclude the meal penalty duration from being added to the leading penalty.
Meal60	ExtraMissed	Missed Meal Penalty	The paycode name used for a second consecutive missed meal penalty.
Meal60	FirstEarly	Early Meal Penalty	The paycode name used for a first early meal penalty.
Meal60	FirstLate	Meal Penalty	The paycode name used for a first late meal penalty.
Meal60	FirstMissed	Missed Meal Penalty	The paycode name used for a first missed meal penalty.
Meal60	FirstShort	Short Meal Penalty	The paycode name used for a first short meal penalty.
Meal60	IncludeDeniedTime	TRUE	When set to true, include denied hours for the shift in the calculation.
Meal60	IncludeTransfers	TRUE	When set to true, the paycode edit for penalties includes the job, labor category and cost center transfers.
Meal60	IsEarlyMealPenaltyRequired	FALSE	When set to true, track the first early meal penalties.
Meal60	IsLateMealPenaltyRequired	TRUE	When set to true, track the first late meal penalties.
Meal60	IsMissedMealPenaltyRequired	FALSE	When set to true, track the first missed meal penalties.
Meal60	IsSecondEarlyMealPenaltyRequired	FALSE	When set to true, track the second early meal penalties.
Meal60	IsSecondLateMealPenaltyRequired	TRUE	When set to true, track the second late meal penalties.
Meal60	IsSecondMissedMealPenaltyRequired	FALSE	When set to true, track the second missed meal penalties.
Meal60	IsSecondShortMealPenaltyRequired	FALSE	When set to true, track the second short meal penalties.
Meal60	IsShortMealPenaltyRequired	FALSE	When set to true, track the first short meal penalties.
Meal60	IsThirdEarlyMealPenaltyRequired	FALSE	When set to true, track the third early meal penalties.
Meal60	IsThirdLateMealPenaltyRequired	TRUE	When set to true, track the third late meal penalties.
Meal60	IsThirdMissedMealPenaltyRequired	FALSE	When set to true, track the third missed meal penalties.
Meal60	IsThirdShortMealPenaltyRequired	FALSE	When set to true, track the third short meal penalties.
Meal60	LateGrace		(Optional) The restriction value applies to the late meal before the rounding process. When configured, the LateRound must also be configured.
Meal60	LateRound		(Optional) The rounding value applies to the late meal after the grace restriction. When configured, the LateGrace parameter must also be configured.
Meal60	LocatorFor2ndMissedMealBreak	300	The number of minutes (locator) from the start of work from which to calculate the second consecutive missed meal penalty.
Meal60	LocatorFor3rdMissedMealBreak	480	The number of minutes (locator) from the start of work from which to calculate the third consecutive missed meal penalty.
Meal60	MaxPenaltyForAMealBreak	60	The maximum meal penalty in minutes that can be accumulated for the same meal break.
Meal60	MaxWorkLength	240	The maximum work length in minutes to initiate the first or only meal penalty; this setting is used as the locator for the first penalty.
Meal60	MaxWorkLength2ndMealBreak	360	The maximum work length in minutes to initiate the second meal penalty; this setting is used as the locator for the second penalty.
Meal60	MaxWorkLength2ndMealBreakFirstSpan		The maximum work length in minutes to initiate the second meal penalty in the first span; this setting is used as the locator for the second penalty in the first span. Note: Leave empty if not required.
Meal60	MaxWorkLength3rdMealBreak	540	The maximum work length in minutes to initiate the third meal penalty; this setting is used as the locator for the third penalty.
Meal60	MealBreakAmount	60	The required length in minutes for the first or only meal break; this setting controls the maximum penalty that is awarded.
Meal60	MealPenaltyComment	Meal Penalty	The comment for the meal penalty paycode edit.
Meal60	MealPenaltyGrace	0	The meal penalty grace before the next rounding interval is awarded.
Meal60	MealPenaltyNextDayComment	Meal Penalty Next Day	The comment for the meal penalty paycode edit when the effective time is not the same day of the effective date.
Meal60	MealPenaltyRound	1	The meal penalty rounding interval.
Meal60	MinBreakLengthForAMeal	1	The maximum break length between 2 work spans that determines whether to merge the spans.
Meal60	MinShiftLengthFor1stMealBreak	180	The minimum shift length in minutes that is eligible for a first meal break.
Meal60	MinShiftLengthFor2ndMealBreak	240	The minimum shift length in minutes that is eligible for a second meal break.
Meal60	MinShiftLengthFor3rdMealBreak	480	The minimum shift length in minutes that is eligible for a third meal break.
Meal60	MinWorkLength	180	The minimum work length in minutes to initiate a meal penalty.
Meal60	MinWorkLengthFor2ndMissedMealBreak	240	The minimum consecutive work length in minutes to initiate a second missed meal break.
Meal60	MinWorkLengthFor3rdMissedMealBreak	480	The minimum consecutive work length in minutes to initiate a third missed meal break.
Meal60	NotMissedIfBreakIsLate	FALSE	When set to true, neither missed nor extra missed meals apply if a late meal is in place.
Meal60	PayRulesToProcess	_PRMP PR1, _PRMP PR2	The list of pay rules that require meal penalty checks.
Meal60	ProcessNextDayPenalty	TRUE	When set to true, process the meal penalty on the next day.
Meal60	QueryPreviousPayPeriod	TRUE	When set to true, calculate penalties for the previous pay period if not signed off.
Meal60	ReduceNextWorkShiftOnShortPenalty	FALSE	When set to true, a short penalty reduces the following work length.
Meal60	SecondEarly	Early Meal Penalty	The paycode name used for a second early meal penalty.
Meal60	SecondLate	Late Meal Penalty	The paycode name used for a second late meal penalty.
Meal60	SecondMealBreakAmount	60	The required length in minutes for the second meal break; this setting controls the maximum penalty that is awarded.
Meal60	SecondExtraMissed	Missed Meal Penalty	The paycode name used for a second extra missed meal penalty.
Meal60	SecondMissed	Missed Meal Penalty	The paycode name used for a second missed meal penalty.
Meal60	SecondShort	Short Meal Penalty	The paycode name used for a second short meal penalty.
Meal60	ShortGrace		(Optional) The restriction value applies to the short meal before the rounding process. When configured, the ShortRound must also be configured.
Meal60	ShortRound		(Optional) The rounding value applies to the short meal after the grace restriction. When configured, the ShortGrace parameter must also be configured.
Meal60	ThirdEarly	Early Meal Penalty	The paycode name used for a third early meal penalty.
Meal60	ThirdLate	Late Meal Penalty	The paycode name used for a third late meal penalty.
Meal60	ThirdMealBreakAmount	30	The required length in minutes for the third meal break; this setting controls the maximum penalty is awarded.
Meal60	ThirdMissed	Missed Meal Penalty	The paycode name used for a third missed meal penalty.
Meal60	ThirdShort	Short Meal Penalty	The paycode name used for a third short meal penalty.
Meal60	UseActualWorkedTimeForEligibility	TRUE	When set to true, the elapsed work length is based on the actual worked time excluding already taken breaks.
Meal60	UseRoundedMeal	TRUE	When set to true, calculate penalties using rounded mealtimes instead of actual mealtimes.
Meal60	UseRoundedShiftEndTime	FALSE	When set to true, calculate penalties using rounded end times instead of actual end times.
Meal60	UseRoundedShiftStartTime	FALSE	When set to true, calculate penalties using rounded start times instead of actual start times.

Note: Contents in the Value column are case-sensitive and must match configured values in UKG Pro Workforce Management.

Install the Meal Penalty 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.

Select Main Menu Administration > Application Setup > Integrations Setup > Install Integrations.
Click Tap Create .
In Integration Name enter a unique name, such as MealPenalty_iPack_v4.
(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 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.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
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.
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 MealPenalty_iPack_v4.
Click Tap Assign .
In Integration Parameters, you can override default settings. Click Tap Create.
Complete the configuration for each parameter value.

Click Tap Save.

Repeat this step for each integration parameter that supports the Meal Penalty process.

Integration parameters

Parameter name	Description / User Prompt / Mandatory	Template parameter	Parameter type
Hyperfind	The default Hyperfind that contains the employees for whom the integration is run. User prompt = Yes Mandatory = Yes	HyperfindID	Hyperfind
Person Number	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 Mandatory = Yes	EmployeeID	Text
Rule set	Determines which rule set to process. User prompt = Yes Mandatory = Yes	Ruleset	Text
Process Historical Corrections	Determines whether to process historical corrections. Default = `false` User prompt = No Mandatory = Yes	ProcessHistoricalCorrections	Boolean
Historical Corrections Start Date	Identifies the historical corrections period start date. User prompt = No Mandatory = Yes	HistoricalCorrectionsPeriodStartDate	Date
Historical Corrections End Date	Identifies the historical corrections period end date. User prompt = No Mandatory = Yes	HistoricalCorrectionsPeriodEndDate	Date
Exclude Penalty	Determines whether to exclude penalty. User prompt = No Mandatory = No	ExcludePenalty	Boolean
Exclusion Paycode	A semicolon-separated list of combined paycodes excluded from penalty. Default = `false` User prompt = No Mandatory = No	ExclusionPaycode	Text
Run with Database	Determines whether the integration references the extension tables during processing. Default = `false` User prompt = No Mandatory = Yes	RunWithDB	Boolean

Ensure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. See Configure Access to Integrations .

Run and test the Meal Penalties integration

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 MealPenalty_iPack_v4 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.
  - Person Numbers: 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
  - Ruleset: Select the break rule set to apply during the integration run.
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.

(Optional) Target file properties

Target file properties and target file layout illustrate the meal penalties audit file export functionality.

Target file properties

Name	Value
File name	meal_penalty_audit_payPeriod_currentDateTimestamp.csv
File Extension	.csv
Delimiter	comma (,)
Target Directory	/Output
Header	Yes (One line)
Footer	No

Target file layout

Target file layout for the Meal Penalty audit

Field	Description
PersonNumber	Person number for whom the meal penalty is generated.
Action	The add or remove penalty action.
PaycodeName	Meal penalty paycode.
StartDateTime	Start date and time of the meal penalty.
Amount	Meal penalty amount.
Transfer	Job, labor category, or cost center transfer, if applicable.
Comment	Meal penalty paycode comment.

Sample output file content

"PersonNumber","Action","PaycodeName","StartDateTime","Amount","Transfer","Comment","TEST123","Added","Meal Penalty","2023-04-04T13:00:00","1","","FirstMissed"

APIs

API details

APIs details

API name	Resource path	Method	Description
Execute Hyperfind Query	/v1/commons/hyperfind/execute	POST	Executes a Hyperfind query by ID or qualifier, and then returns the result.
Retrieve Timecards as Manager	/v1/timekeeping/timecard/multi_read	POST	Returns a list of timecards based on the employees or Hyperfind details provided.
Retrieve Data	/v1/commons/data/multi_read	POST	Returns aggregated data by executing an ad-hoc query.
Update Integration Execution Details	/v1/platform/integrations/update_status	POST	Updates and returns the callback instance relative to the provided integration execution details.
Update Timecard as Manager	/v1/timekeeping/timecard	POST	Updates an employee timecard as a manager.
Retrieve Comments as Manager	/v1/commons/comments	GET	Returns a filtered list of comments.
Retrieve All Timekeeping Pay Rules	/v2/timekeeping/setup/payrules	GET	Returns a list of all timekeeping pay rules.

Version history

Version	Description
1	Initial release. The Meal Penalty integration grants meal penalties to employees by way of paycode edits when the meal break is missed, short, early, or late.
1.1	Includes support for the job, labor category, and cost center transfer.
1.2	Includes support for third meal penalty.
2	Includes support to consider shift timings from the start of the shift with variable thresholds. Issue resolution for paycode deletion when replacement is not required during integration re-run.
3	Includes support to exclude meal penalties on days when the employee timecard totals contain an exclusion paycode.
3.1	The Meal Penalty integration: included the time duration from the first meal penalty when calculating a subsequent meal penalty. failed with a document cache error when it included an employee with a worked shift that spanned the previous and current pay periods.
3.2	The Meal Penalty integration returned a scripting error when the overtime hours of an employee are denied for the entire day.
iPack_v4	The Meal Penalty integration delivery is now by way of an iPack.
iPack_v4 enhancement	The Meal Penalty integration failed with a script error when more than three breaks were found in a shift. The integration now generates a more descriptive error.
	Optimization improvements to the Meal Penalties integration now reference extension tables during processing when a Hyperfind selection is made. If a customer does not take advantage of the improved optimization configuration changes, the Run Summary page displays a reminder message: "*Integration has completed. However, there is a more efficient method to execute this integration by utilizing extension tables. Please refer to the datasheet for further details.*" Coupled with performance improvements, the integration now offers a different maximum work length for the employee's second meal break locator when the meal falls within the first span of worked hours.
	The Meal Penalty integration encountered a failure due to a data-type/casting SQL error. This issue affected the processing of meal penalty data, leading to disruptions in the integration workflow.