Optimized Modulation

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 Optimized Modulation integration provides an automated way to optimize scheduled hours of contractual employees based on the forecasted demand while still adhering to the minimum and maximum working hours of each employee.

In some countries, employees are paid based on fixed contracts. Regardless of whether or not there is workload, they are paid their contractual hours. During the year, employees modulate their hours. For example:

In weeks where the workload is low, they are scheduled a reduced number of hours.
In weeks where the workload is high, they are scheduled an increased number of hours.

The objective is to break even at the end of the year with no variance between contracted and actual hours, limiting the need to pay overtime or for shortfall hours. This concept is called Modulation.

Schedule rules, with minimum and maximum weekly limits, create a band of hours to control the number of hours an employee can flex up and down. The Optimized Modulation integration uses expected weekly weight, representing the seasonal long-term volume forecast, as a parameter to define and assign the appropriate band of hours which applies to the employee for that week.

This extension does the following:

References customer-provided weightage data up to 52 weeks in the future.
Evaluates the expected weekly weightage data by location or job.
Adjusts the employee’s weekly scheduled hours minimum and maximum limits.
Can insert schedule tags into the Schedule Planner to identify the weight of the week.
Can use work rule transfers to align with weekly weight.
Remodulates upon contract changes.

As a result of this extension, the scheduling process performed by the engine or self-scheduling more closely aligns with the operational need.

Weekly weightage data

Customer-provided weekly weightage data is uploaded in a CSV file to the tenant’s SFTP inbound folder. The weekly weightage data file must contain the following information:

Location – The organizational path of the location for which the weight applies. Granularity down to the job level, and the use of wildcards, are supported.

Start – Start date of the forecasted weightage period.

End – End date of the forecasted weightage period. The Start and End Dates must span a minimum of 1 week and align with the weekly schedule period. Multiple weeks with the same Location and Weight values can be combined.

Weight – High or Low. There is no need to provide the medium weeks because this weight is the default for all employees.

Refer to the table below for a sample of the weightage data CSV content.

Sample weightage data CSV content
Location	Start	End	Weight
/Administration/Manufacturing Manager	18-08-2021	25-07-2021	High
/Administration/Manufacturing Manager	26-07-2021	02-08-2021	Low
/Administration/Manufacturing Manager	03-08-2021	10-08-2021	High
/Machine Shop	18-07-2021	25-07-2021	Low
Organization/France/Metropolitan Plan/Receiving/Warehouse Clerk	26-07-2021	10-08-2021	High
Organization/France/Metropolitan Plan/Assembly/Mechanic	05-08-2021	20-08-2021	Low
/Assembly/	05-08-2121	20-08-2021	High

Note: Sample dates are presented in dd-MM-yyyy format.

Schedule rule override

Note:

The rules engine uses the following logic when validating weekly rule overrides:

When the date range covers the entire week, the engine uses the override value.
When the date range covers only a portion of the week, the engine uses the most restrictive value configured for the rule set and the override values.

For example, if the week ranges from Monday to Sunday, setting the expiration date to Sunday means that the rule is not in effect on the Sunday. In other words, the expiration date always needs to be the last day of the active period +1 day.

Note: The Optimized Modulation integration includes an automated script that adds 1 day to the expiration date, allowing customers to continue providing the last day as the expiration date.

Example:

The schedule rule is configured with a maximum hours per week = 40:00.

The first week of August, which ranges from Monday August 1 to Sunday August 7 requires an override of 44:00 hours.

Effective date = Monday August 1 and Expiration date = Sunday August 7. (The integration automatically adjusts the expiration date by setting it to August 8).

The expiration date can overlap with the effective date of the next period — this is not considered an error.

Band of hours

Schedule rule overrides data, defining a high or low week representation in terms of band of hours, must be provided in a CSV file that is uploaded to the tenant’s SFTP inbound folder. Four fields in the file are combined to match the employee with the correct band of hours; these fields also define the minimum and maximum schedule hour values. The combination of multiple fields is considered an AND condition; therefore, the employee needs to qualify against all fields to determine a match. The schedule rule overrides file must contain the following information:

Person number — Individual Person Number. This is the most restrictive option, which allows the definition of specific limits by employee .

Employment terms — All employees assigned to this employment term during the specific week are matched.

Pay rule — All employees assigned to this pay rule during the specific week are matched.

Location — All employees working in this location during the specific week are matched.

High Week Min — The schedule rule override hours for High forecast minimum value.

High Week Max — The schedule rule override hours for High forecast maximum value.

Low Week Min — The schedule rule override hours for Low forecast minimum value.

Low Week Max — The schedule rule override hours for Low forecast maximum value.

Refer to the table below for a sample of the schedule rule overrides data CSV content.

Sample schedule rule overrides data CSV content
Person number	Employment terms	Pay Rule	Location	HighWeekMin	HighWeekMax	LowWeekMin	LowWeekMax
10001	French Employees	Full Time	Organization/Germany/	32	36	24	28
10002	Manufacturing	USDC-RT-PT	Organization/Australia/	36	40	26	30
10003	California Employees	Manufacturing Intern	Organization/Human Resource/	28	32	22	26
	Healthcare Employment Terms			30	36	20	26
		California		30	34	22	26
		USNY-RT-FT		34	38	26	30

Optional functionality

Schedule tags

When enabled, the integration inserts schedule tags in the Schedule Planner identifying the weight of the week. Tags are only for visualization purposes.

Work rule override

When weekly weight deviates from the standard weight, the integration optionally allows an override to the employee’s work rule for that week. For example, different overtime thresholds or entitlements could apply if the weekly weight is high or low. If enabled, the integration automatically scans for the _Low or _High version of the employee’s work rule and inserts the appropriate work rule transfer. For example, during a high week, the employee’s default work rule of Supermarket FT will be overridden with work rule Supermarket FT_High.

Use cases

The integration is typically performed for a group of employees selected from a Hyperfind or Location. Optionally, the integration will process single or multiple persons.

Three modulation actions are provided:

Schedule Rule Override

Schedule Rule Override is the main process. This action reads the Weekly Weightage Data and Schedule Rule Overrides Data from the SFTP site defining the optimized modulation for the selected time frame and employees. Effective dated minimum and maximum weekly limit overrides are created for each employee. Optionally, this action inserts schedule tags in the Schedule Planner. This action is executed before schedule generation.

Schedule Rule Override — Changed Employees

Schedule Rule Override — Changed Employees is used as a scheduled process typically executed on a daily basis. This action monitors the Primary Job, Pay Rule and Employment Terms to detect employees who had a contract change impacting the already rolled-out modulation. Updates to previously added Schedule Rule overrides and Schedule Tags reflect the new situation. This action is executed before schedule generation.

Work Rule Override

Work Rule Override is intended to run after schedule creation. This action inserts the _High or _Low version of the employee's work rule as a transfer for shifts present in the schedule.

Modulation Period options include:

Provided Weightage Data

This action modulates all weeks that are found in the provided Weekly Weightage Data source file. Modulation always starts in the future; that is, run date + 1 day. Although the action can be initiated mid-week, modulation never applies to past days, including today, even if the current week is part of the weightage data.

As a best practice, the source file should only contain future weeks data.

Date Range

This action only modulates between the provided Start and End Dates. If the weightage data source file contains additional weeks, the system only considers weeks that fall within the date range; all other weeks are disregarded.

Configure the Optimized Modulation integration

Before you configure the integration:

Configure Access to Integrations.
Configure schedule rule sets; see the Configure schedule rule sets topic.
(Optional) Configure schedule tags; see the Tag Definitions topic.
(Optional) Configure work rules; see the Work Rules topic.
Configure a workflow notification to notify the manager that modulization needs to be executed for an edited employee; see the Create workflow notifications topic.
Create an extension table that specifies the DDL commands for the integration template; see the Extension Tables topic.
Get the URL for the APIGatewayServer for the tenant.
Deploy the OptimizedModulation_v1 integration; see the Deploy Integrations topic.
Get the URL for the APIGatewayServer for the tenant.

Select the environment

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.
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: OptimizedModulation > OptimizedModulation_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

Select Connection Settings.

From the Connection list, select and configure the following:

Connection Settings
Setting	Required	Actions
APIGatewayServer	Required	To change the default API gateway server: Clear Use Default. Enter the URL to the server. Example: <tenantURL>/api
SFTP Server	Required	The SFTP server setting defines the connection to the folder that contains the source data files. Integrations access only the internal SFTP account. For each field, clear Use Default. Enter the following values: Name of the internal Host. 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 Apply.

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

Control properties
Parameter name	Description	Template parameter	Parameter type	Default value	User prompt	Install parameter required
Person Number	Allows running the modulation for a selection of employees. Specify a single person number or multiple person numbers separated by commas (,).	Person Number	Text		true	Mandatory
Hyperfind	Select the group of employees to modulate.	Hyperfind ID	Hyperfind	All Home	true	Optional
Hyperfind ID Type	Type of Hyperfind — Location or Hyperfind	HyperfindID
Modulation Type	Defines which type of modulation is executed.	Modulation Type	Dropdown	Schedule Rule Override	true	Mandatory
Insert Schedule Tags	Controls whether schedule tags are inserted in the Schedule Planner.	Insert Schedule Tags	Boolean	false	false	Optional
High Week Schedule Tag	Defines the label used for the tag indicating high weeks.	High Week Schedule Tag	Text	High	false	Mandatory
Low Week Schedule Tag	Defines the label used for the tag indicating low weeks.	Low Week Schedule Tag	Text	Low	false	Mandatory
Modulation Period	Defines which period will be modulated.	Modulation Start Date	Dropdown	Integration Run Date+1	true	Mandatory
Date Format	Defines the date format used for the weightage data source file.	Date Format	Text	dd-MM-yyyy	false	Mandatory
Suffix High Week Work Rule	Define the suffix used for the alternate work rules for high weeks.	Suffix High Week Work Rule	Text	_High	false	Mandatory
Suffix Low Week Work Rule	Define the suffix used for the alternate work rules for low weeks.	Suffix Low Week Work Rule	Text	_Low	false	Mandatory
Weekly Weight High Definition	Defines the label used in the weightage data source file for high weeks.	Weekly Weight High Definition	Text	High	false	Mandatory
Weekly Weight Low Definition	Defines the label used in the weightage data source file for low weeks.	Weekly Weight Low Definition	Text	Low	false	Mandatory
Schedule Hours Type	Defines the format of the minimum and maximum amounts in the source files.	Schedule Hours Type	Text	Hours (hh:mm)	false	Mandatory
Start Date	Start date when using a range of dates.	Start Date	Date		true	Mandatory
End Date	End date when using a range of dates.	End Date	Date		true	Mandatory
Check Shifts Required for Work Rule Override	Internal parameter — do not change.	Check Shifts Required for Work Rule Override	Boolean	false	false	Optional
Append Timestamp in Export File	Adds a date time stamp to the output file.	Append Timestamp in Export File	Text	dd-MM-yyyy'T'hhmmSSS	false	Mandatory
Sender Email Address	Email address used by the Boomi™ application for notifications.	Sender Email Address	Text	[email protected]	false	Mandatory
Send Audit -Initiator	Send overview to initiating user with changed employees (changed records modulation only).	Send Audit-Initiator	Text	Enter Email	true	Mandatory
Send Audit - Report To	Send overview to Reports To with changed employees (changed records modulation only).	Send to Audit Report To	Boolean	True	true	Mandatory
SFTP File Name for Weightage Data	Defines the name of the source file for weightage data		Text	SFTP File Name for Weightage Data – Weightage Data.csv
SFTP File Name for Schedule Rule Overrides Data	Defines the name of the source file for schedule rules data (band of hours)		Text	SFTP File Name for Schedule Rule Override Data – Schedule Rule Overrides Data.csv
SFTP Directory for Weightage Data	SFTP directory where the weightage data source file is posted.		Text	/Inbound
SFTP Directory for Schedule Rule Overrides Data	SFTP directory where the schedule rule override data source file is posted.		Text	/Inbound
Output Directory	SFTP directory where the output file is posted.		Text	/Outbound

Note:

Modulation Type supports three actions:
- Schedule Rule Override
- Schedule Rule Override - Changed Employees
- Work Rule Override

Date Format supports the following formats:
- MM/dd/yyyy
- MM-dd-yyyy
- dd/MM/yyyy
- dd-MM-yyyy
- yyyy/MM/dd
- yyyy-MM-dd

Schedule Hours Type supports the use of colon(:), period (.), and comma (,).

Append Timestamp in Export File supports the following formats:
- MM-dd-yyyyThhmmSSS
- dd-MM-yyyyThhmmSSS

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.

Select Cross Reference.
From the Cross Reference list, select the following tables:

OptimizedModulation_v1_Localization_CRT: Maps the messages configured for different regional language requirements with locale policy in the integration.

Localization_CRT: Maps the configurable message to a parameter.

Column headers:

Parameter Name, Locale Policy, Value, Description

Parameter Name = Parameters defined in _OptimizedModulation_v1_Localization process property.
Locale Policy = Locale Policy.
Value = Message shown in Additional Details or value of the label defined in the Run Summary section.
Description = Detailed description that will display in Additional Details.

Note:

Localization of integration extensions is supported.

A Cross Reference Table holds all messages with the standard English label, which applies to all locales when using a wildcard (*).

Localization remains optional. Some or all messages can be translated by adding additional lines in the table with their preferred translation for a specific locale.

When the integration finds a match before a wildcard match, that label is shown.

Note that all messages need to remain configured with at least the wildcard locale policy or the integration will fail.

The least restrictive Local Policy must be defined at the very bottom in CRT data because the Boomi™ application scans the CRT from top to bottom. All the parameters need to be, by default, configured with locale policy as * in the CRT.

Names of the parameters in the column Parameter Name must be used AS-IS. If any parameter value needs to be localized for a different local policy, you need to copy the exact "Parameter Name" with the * Locale policy and add a new row to the CRT with respective locale policy, and localized values in Value and Description CRT columns.

CRT column Description must be set as blank for Labels, Messages for Run Integrations and Notes.

Localization example
Parameter Name	Locale Policy	Value	Description (optional)
_MessageNoLocation	English UK	Location not found	Employee location not matched with Uploaded File Location

Select Override to:
- Download the tables when you run the integration
- Edit the table cells in Extensions
Click Tap OK.

Configurable Message Parameter List
Parameter name	Default value	Usage
_MessageIncorrectWeekValue	Week Value not in correct format	When install parameters Weekly Weight High Definition or Weekly Weight Low Definition values differ from CRT or CSV weightage value, the process displays Entered week value not matched with Uploaded File Week Value.
_MessageIncorrectDateFormat	Effective Start/End date not in correct format	When install parameter Date Format value differs from CRT or CSV date format, the process displays Selected Date format not matched with Uploaded File Format.
_MessageNoLocation	Location not found	When employee location does not match with CRT or CSV location, the process displays Employee location not matched with Uploaded File Location.
_MessageEmployeeNotFound	Employee(s) not found	When the integration is running for an individual employee and that employee is not found in the system, the process displays Employee not found/defined in WFD.
_MessageInvalid	Hyperfind or Employee Id not found or invalid	When the integration is running for a Hyperfind and that Hyperfind is not found in the system, the process displays Hyperfind not found.
_MessageIncorrectWeight	Weight not in correct match	When install parameters Weekly Weight High Definition or Weekly Weight Low Definition values differ from CRT or CSV weightage value, the system displays Entered Weight value does not match with Uploaded File Weight.
_MessageWorkRuleInvalid	WorkRule not found in UKG Pro Workforce Management™:	When a work rule is not defined based on weightage with suffix as _high or _low, the process displays Work Rule is not configured in UKG Pro Workforce Management™.
_MessageNoFileName	Source file <File Name> not found in SFTP directory.	When the provided file name from install parameter does not match or is not in .CSV, the process displays The provided File Name to fetch from SFTP was not using .csv extension.
_MessageWorkRuleNotFound	Work Rule Not Found	When an employee does not have a Work Rule assigned in the system, the process will display in Work Rule overrides as Employee has no WorkRule assigned.
_MessageDatabaseEmpty	Database has no records	When Database has no records.
_MessageEmployeeNotFoundInDB	Database has no records	When an employee has no records available in database, the process displays Employee information is not available in DB for comparison.
_MessageNoShiftsAvailable	Employee has no shifts	When an employee has no shift available on Schedule Planner, the process displays No shifts available for the employee for the date range.
_LabelFileHeaderPersonNumber	PersonNumber	Output file header when there is change in employee records to notify managers.
_LabelFileHeaderPersonName	PersonName	Output file header when there is change in employee records to notify managers.
_LabelFileHeaderEmploymentTerms	EmploymentTerms	Output file header when there is change in employee records to notify managers.
_LabelFileHeaderEmploymentTermsChangedDate	EmploymentTermsChangedDate	Output file header when there is change in employee records to notify managers.
_LabelFileHeaderLocation	Location	Output file header when there is change in employee records to notify managers.
_LabelFileHeaderLocationChangedDate	LocationChangedDate	Output file header when there is change in employee records to notify managers.
_LabelFileHeaderPayRule	PayRule	Output file header when there is change in employee records to notify managers.
_LabelFileHeaderPayRuleChangedDate	PayRuleChangedDate	Output file header when there is change in employee records to notify managers.
_LabelIntegrationType	Integration Type	Text displayed in Run Summary section of Integration Run Details for Integration Type.
_LabelProcessedSourceRecords	Processed Records	Text displayed in Run Summary section of Integration Run Details for Processed Source Records.
_LabelFailedTransactions	Failed Transactions	Text displayed in Run Summary section of Integration Run Details for Failed Transactions.
_LabelDisqualifiedTransactions	Disqualified Transactions	Text displayed in Run Summary section of Integration Run Details for Disqualified Transactions.
_LabelInvalidEmployee	Invalid Employee	Text displayed in Run Summary section of Integration Run Details for Invalid Employee.
_LabelTagsInserted	Tags Inserted	Text displayed in Run Summary section of Integration Run Details for Tag inserted.
_LabelSuccessfulTransactions	Successful Records	Text displayed in Run Summary section of Integration Run Details for Successful Transactions.
_EmailSubject	Remodulate Changed Employees List	Subject displayed to employee’s manager when receiving email about any changes in employee records with attachment.
_EmailText	Attached is list of employees for whom remodulation has changed schedule rule overrides. Please regenerate schedule for them.	Text displayed to employee’s manager when receiving email about any changes in employee records with attachment.
_ChangedEmployeesFileNameManager	Changed Employees Data <TIMESTAMP>	Attached file name while receiving the notification via email about change employee records as Changed Employees Data MANAGERID TIMESTAMP.
_MessageDisqualifyTag	Employee is disqualified	When a manager wants to disqualify any employee for work rule override, put a disqualified tag on their schedule planner.
_LabelFileHeaderFirstName		Output file header to notify managers when there is change in employee records.
_LabelFileHeaderLastName		Output file header to notify managers when there is change in employee records.
_MessageValidateNoLowTag	Low Week Tag not provided	When no low tag is defined in the system.
_MessageValidateNoHighTag	High Week Tag not provided	When no high tag is defined in the system.
_MessageValidateNoStartDate	Start Date not provided	When integration is running on selected date but no start date is provided.
_MessageValidateNoEndDate	End Date not provided	When integration is running on selected date but no end date is provided.
_MessageValidateInvalidDateSelection	Start Date should not be equal to the End Date	Selected start date should not be equal or greater than the End Date.
_MessageValidateIncorrectSelectedDate	Selected Dates should be greater than the Current Date	Selected Dates should be greater than the Current Date.
_MessageValidateNoInsertTagValue	Insert Schedule Tags parameter not provided	When install parameter Insert Schedule Tags value not provided, the process displays Insert Schedule Tags parameter not provided.
_MessageValidateNoHyperfindOrPersonNumber	Hyperfind or Person Number not provided	When there is no Hyperfind, or person number provided from integration run, the process displays Hyperfind, or Person Number not provided.
_MessageValidateIncorrectFileFormat	<File Name> extension should be .csv	The SFTP file name is not defined in correct format as .CSV.
_MessageNoEmployeeFound	Hyperfind Selected returned no Employees	When Hyperfind has no employee configured in the system, the process displays Hyperfind selected returned no Employees.
_MessageWithoutErrors	Integration has completed without errors.	Text displayed when Integration has completed without errors.
_MessageWithoutTransactionErrors	Integration has completed without transaction errors. Additional details, such as disqualifications, may be accessible using the button below.	Text displayed when Integration has completed without transaction errors. Additional details, such as disqualifications, may be accessible using the button below.
_MessageTransactionEnabled	Process completed with transaction errors. If Transaction Assistant is enabled, failed records can be re-submitted through Transaction Assistant.	Text displayed when Process completed with transaction errors. If Transaction Assistant is enabled, failed records can be re-submitted through Transaction Assistant.
_MessageAdditionalDetails	Process completed with transaction errors. Additional details, such as disqualifications, may be accessible using the button below.	Text displayed when Process completed with transaction errors. Additional details, such as disqualifications, may be accessible using the button below.
_LabelFileHeaderModulationStartDate	ModulationStartDate	Output file header to notify managers when there is a change in employee records.
_LabelFileHeaderModulationEndDate	ModulationEndDate	Output file header to notify managers when there is a change in employee records.
_ChangedEmployeesFileNameInitiator	Changed Employees Data <TIMESTAMP>	Attached file name while receiving the notification via email about change employee records as Changed Employees Data TIMESTAMP.
_MessageManagerMailIDNotAvailable	Manager MailID Not Available	Manager <MANAGERID> MailID Not Available.
_MessageNoChangesEmployee	Employee has no changes	No changes found in employee's record.
_MessageNoScheduleRuleOverrideValue	Employees has no ScheduleRule Override value	No Week Value available for the Employee to override Schedule Rule.
_MessageOverlappingDate	Overlapping Dates present in CSV	When source weightage csv has overlapping dates present for employee to qualify for forecast.

Source file formats

Weightage Data.csv format
Field	Field name	Example	Help text
1	Location	Org/India/Associate	Primary location assigned to the user.
2	Start	30-11-2021	Start date for the forecasted weightage.
3	End	31-12-2021	End date for the forecasted weightage.
4	Weight	High or Low	Weightage of the forecasted week or month.

Note:

Start and End columns must adhere to the date format defined in the control property Date Format.
The date range of the Start and End values must span a minimum of one week. If the date span breaks mid-week, the integration will apply overrides and tags accordingly.
Location supports the use of wildcards, such as Org/India/*. The least restrictive location should be defined at the lowest rows in the CSV file.

Schedule Rule Overrides Data.csv
Field	Field name	Example	Help Text
1	PersonNumber	20210	Individual Person Number
2	EmploymentTerms	Full Time	Employment Term assigned to the employee
3	PayRule	Manufacturing	PayRule assigned to the employee
4	Location	Org/India/Associate	Location or Primary Job of employee
5	HighWeekMin	36	Schedule Rule override hours for High forecast min value
6	HighWeekMax	40	Schedule Rule override hours for High forecast max value
7	LowWeekMin	24	Schedule Rule override hours for Low forecast min value
8	LowWeekMax	28	Schedule Rule override hours for Low forecast max value

Note:

To determine the appropriate override to assign to a person, this integration matches fields in the Schedule Rule Overrides Data CSV file to fields in the employee’s people record. The first match takes precedence.
- If the first row of the cross-reference table has only one field, this integration matches it to the people records and does not consider matched employees in further processing.
- If the first row has multiple fields, this integration matches the combination of these fields to the people records and does not consider matched employees in further processing.
Examples: If the first row of the CSV contains Location = Org/India/Associate, people who match this Location are no longer included in the comparison. If the first row of the CSV contains EmploymentTerm = Full Time and Location = Org/India/Associate, people who match both values are no longer included in the comparison.
The following columns are used to select schedule hours values for an employee based on High or Low weightage associated with the date range: HighWeekMin, HighWeekMax, LowWeekMin, and LowWeekMax.
Separators supported for schedule hours include colon (:), period (.), and comma (,). Values presented in HH:mm format, by default, are considered as hours and minutes. Values presented in HH,mm or HH.mm formats are changed into hours and minutes.

APIs

API details
API name	Section	Type	Resource path	Location	Description
Execute Hyperfind	Commons	POST	/v1/commons/hyperfind/execute	_Retrieve Source Data	Get person records for the specified Hyperfind.
Retrieve Employees	Commons	POST	/v1/commons/persons/extensions/multi_read	_Retrieve Source Data	Get person data including hire date, seniority date, accrual profile.
Retrieve Employee Shifts and Tags	Scheduling	POST	v1/scheduling/schedule/multi_read	_WorkRule Update	Get shift details and tags.
Retrieve Tenant Default Locale	Commons	GET	/v1/commons/user_preferences/locale_policy?tenantDefault=true	_Non-Dynamic Cache	Get tenant default locale details.
Retrieve Current User Locale	Commons	GET	/v1/commons/user_preferences/locale_policy?userCurrent=true	_Non-Dynamic Cache	Get locale for system user.
Delete Tags	Scheduling	POST	/v1/scheduling/schedule/multi_update?partial_success=true	_ScheduleRule Update	Delete employee schedule tag.
Insert Tags	Scheduling	POST	/v1/scheduling/schedule/schedule_tags/multi_create	_ScheduleRule Update	Create employee schedule tag.
Integration Details	Platform	POST	/v1/platform/integration_executions/	_Submit Integration Details	Send additional details
Process Callback	Platform	POST	/v1/platform/integrations/update_status	_WFD Callback	Update integration status details.
Retrieve All Work Rule	Timekeeping	GET	/v1/timekeeping/setup/full_work_rules	_Non-Dynamic Cache	Get all work rules.
Retrieve Tag Color	Scheduling	GET	/v1/scheduling/setup/tag_definitions	_Non-Dynamic Cache	Get tag color.
Schedule Rule Override	Commons	POST	/v1/commons/persons/schedule_rule_overrides/multi_upsert	_Core Processing	Update schedule rule override.
Work rule Multi Update	Scheduling	POST	/v1/scheduling/schedule/shifts/multi_update	_Core Processing	Update the employee work rule in schedule.
Update Tags	Scheduling	POST	/v1/scheduling/schedule/multi_update?partial_success=true	_ScheduleRule Update	Update employee tag in Schedule Planner.

Install the Optimized Modulation 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 .
Enter a unique Integration Name.
(Optional) Enter a Description.
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)
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.
Do not select Allow Minute Interval.

Integration template and parameters

In Integration Template, select OptimizedModulation_v1.
Click Tap Assign .
In Integration Parameters, you can override default settings.

Specify the following parameters:

(Required) Specify the default Hyperfind query that contains the employees to modulate:

Click Tap Create .

Hyperfind Name
Parameter Name	(Required) Enter Hyperfind Name.
Description	(Optional)
Template Parameter	(Required) Select Hyperfind Name.
Parameter Type	(Required) Select Hyperfind.
Default Value	(Optional) Enter 1 = All Home.
User Prompted	If the value does not need to be changed when the integration runs, select No.

Click Tap Save.

(Optional) Specify the employees whose records to modulate:

Click Tap Create .

Person Number
Parameter Name	(Required) Enter Person Number.
Description	(Optional)
Template Parameter	(Required) Select Person Number.
Parameter Type	(Required) Select Text.
Default Value	(Optional) Default = Include all employees. To process data for only a limited group of employees: Clear Use Default. Enter the person numbers, as defined in the source system, each separated by a comma (,) but no spaces. Example: 13997,15556,20012
User Prompted	If the value does not need to be changed when the integration runs, select No.

Click Tap Save.

(Required) Specify the modulation period that the integration processes:

Click Tap Create .

Modulation Period
Parameter Name	(Required) Enter Modulation Period.
Description	(Optional)
Template Parameter	(Required) Select Modulation Period.
Parameter Type	(Required) Select Text.
Default Value	(Optional) Select one of the following: Provided Weighted Data Date Range
User Prompted	If the value does not need to be changed when the integration runs, select No.

Click Tap Save.

(Required) Specify the modulation type that the integration processes:

Click Tap Create .

Modulation Type
Parameter Name	(Required) Enter Modulation Type.
Description	(Optional)
Template Parameter	(Required) Select Modulation Type.
Parameter Type	(Required) Select Text.
Default Value	(Optional) Enter one of the following: Schedule Rule Override Schedule Rule Override — Changed Employees Work Rule Override
User Prompted	If the value does not need to be changed when the integration runs, select No.

Click Tap Save.

(Optional) Specify the email address of the initiator:

Click Tap Create .

Initiator Email Address
Parameter Name	(Required) Enter Initiator Email Address.
Description	(Optional)
Template Parameter	(Required) Select Initiator Email Address.
Parameter Type	(Required) Select Text.
Default Value	(Optional) Enter Email.
User Prompted	If the value does not need to be changed when the integration runs, select No.

Click Tap Save.

Click Tap Save.
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 and test the Optimized Modulation integration

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

Run the Optimized Modulation integration

Select the integration:
1. Select Main Menu > Maintenance > Integrations.
2. Click Tap Run an Integration .
3. Select the OptimizedModulation_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 default name ends with a date and time stamp.
Set parameters as follows:
- Hyperfind: Select a Hyperfind query of employees.
- 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
- Modulation Period: Select Provided Weightage Data or a date range.
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.

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