New York City (NYC) Overtime Cap

Note: This extension, a combined integration and workflow model, is developed outside the normal release schedule to meet specific customer needs. To request one of these extensions, you must submit a Salesforce Service Request to UKG. After the extension is delivered to your tenant, you can edit it accordingly.

In New York City, the Citywide Agreement limits overtime cash payments for certain employees when their annual gross salary exceeds a cap amount. Employees receive compensatory time off in lieu of cash.

When an employee is exempt from the Citywide Agreement, the employee can request a waiver that provides overtime cash payments for the entire calendar year or for a specified number of hours in the calendar year — instead of time-compensated overtime. The New York City Overtime Cap (NYCOTCAP) extension delivers an integration and workflow that support employees who qualify for overtime waivers.

The integration checks an employee's earnings on a daily basis, and initiates a workflow when a configurable warning limit is reached. The warning limit is usually configured as a percentage of the employee’s annual gross salary. The workflow assigns the employee the task of selecting how overtime hours are paid:

  • Compensatory time off.

  • Cash for the remainder of the year.

  • Cash for a specified number of hours.

When the employee chooses either of the cash options, the workflow assigns a task to the manager, which requires the manager to take action on the employee's preferred overtime pay method:

  • Accept the employee's request to pay overtime hours with cash.

  • Reject the employee's cash request, and instead pay the overtime with compensatory hours.

  • Return the request to the employee, if, for example, the specified number of hours needs adjustment. The manager can add the return reason in a comment, and the employee can then resubmit the updated request.

An employee is allowed only one manager-approved waiver in a calendar year. When the waiver period ends, the employee automatically returns to time-compensated overtime.

The overtime calculation is processed by a pay rule or employment term change in the People Record on the day that the salary cap is crossed; the change is made only during unsigned-off pay periods.

  • Employee earnings must be checked on a daily basis. You should schedule the Boomi integration frequency to automatically run every day.

  • Employees can choose their overtime compensation only one time during a calendar year. You can create an ample window of time for employees to consider their one-time option when you define the warning limit percentage.

  • If any changes, such as a mid-year salary cap adjustment, occur after an employee has already chosen an overtime compensation for the calendar year, the employee will not be offered a second overtime waiver choice during the same calendar year.

  • Employment terms that are assigned to employees in the People Record must be configured to include a pay rule.

  • The NYCOTCap extension does NOT support historical corrections or changes in signed-off periods.

  • Department notifications are sent only when a requested waiver is approved by the manager. The workflow routes the department notifications to the Recipient selected in the Also Notify section of the Reviewer List.

  • The NYCOvertimeCap_v1 workflow process must be initiated by the integration; manual initiation of the process is NOT supported.

  • When viewing the comment note attached to the informational paycode edit in the timecard for an employee with an approved waiver for the remainder of the year, the earning limit reached date always displays blank.

Policy at a NYC hospital states that any overtime worked after crossing the gross salary cap amount of $96,000 is paid with compensatory time off. A particular organization sets the warning limit at 80% of actual salary, or $76,800.

Use case 1 — Time-compensated overtime

Employee A crosses the warning limit in October, which initiates a task assignment in the control center. An automatic approval date and time indicate the time frame by which the employee must select an option.

The employee selects the compensatory time-off option. Both the employee and manager receive task response notifications.

Later in the calendar year, when the employee crosses the actual salary cap, the pay rule is automatically changed by the integration. The integration adds an informational paycode edit, comment, and note to the timecard describing the NYCOTCap details.

Use case 2 — Waiver (rest of the year)

Employee B crosses the warning limit in September, which initiates a task assignment in the control center. An automatic approval date and time indicate the time frame by which the employee must select an option.

The employee selects the entire year overtime cash payment option. Both the employee and manager receive task response notifications. The manager approves the waiver request.

Later in the calendar year, when the employee crosses the actual salary cap, the pay rule is automatically changed by the integration. The integration adds an informational paycode edit, comment, and note to the timecard describing the NYCOTCap details.

Use case 3 — Waiver (number of hours)

Employee C crosses the warning limit in November, which initiates a task assignment in the control center. An automatic approval date and time indicate the time frame by which the employee must select an option.

The employee selects the specific number of hours option, and then enters 50:00 overtime hours. Both the employee and manager receive task response notifications. The manager approves the waiver request.

Later in the calendar year, when the employee crosses the actual salary cap, the employee’s pay rule is automatically changed by the extension. The integration adds an informational paycode edit, comment, and note to the timecard describing the NYCOTCap details.

When the employee crosses the 50:00 overtime hours, the integration automatically switches the pay rule to the time-compensated version. Once again, the integration adds an informational paycode edit, comment, and note to the timecard describing the NYCOTCap details.

  1. Comment: Configure a comment that the integration adds to the timecard along with the employee's adjustment information. The punches category must be selected during configuration. This comment must be used exclusively by the NYC Overtime Cap extension. See the Comments topic.
  2. Paycode: Configure a paycode that the integration adds to the timecard to store the employee's adjustment information. The paycode must be used exclusively by the NYCOTCap extension. See the Paycode definition topic.
  3. Pay Rule: Configure pay rules that the integration assigns to employees to change overtime compensation from time to cash. Each pay rule assigned to employees who elect compensation waivers must have an alternative version whose name contains the suffix defined in the Compensatory Pay Rule Suffix integration parameter. See the Pay Rules topic.
  4. Employment Terms: Configure employment terms that the integration assigns to employees to change overtime compensation from time to cash. Each employment term assigned to employees who elect compensation waivers must have an alternative version whose name contains the suffix defined in the Compensatory Employment Term Suffix integration parameter. See the Employment Terms topic.
  5. Hyperfind: Configure a Hyperfind or Location query that includes only employees who qualify under the New York Citywide Agreement. See the Hyperfind queries topic.
  6. Reviewer List: Configure a reviewer list dedicated to the NYCOTCap extension. Select one or more Reviewers from Step 1. See the Reviewer Lists topic.
  7. Workflow Notifications: Configure generic workflow notifications that facilitate the NYC Overtime Cap process. Design the notifications by combining free text with available custom tags. Examples include:

Name: NYCOvertimeCap Acknowledgment Notification

Select Trigger the Business Process , and then select the System User button.

Custom Tag options:
Tag Description
<Acknowledgement_Notification_Subject > Notification subject.
<Acknowledgement_Notification_Message> Notification message.

Name: NYCOvertimeCap Employee Information

Custom Tag options:
Tag Description
<<EMP_Message_InformationForWaiverSubject> > Notification subject.
<<EMP_Message_InformationForWaiver>> Notification message.
<CapAmount> Cap amount.

Name: NYCOvertimeCap Error Notification

Custom Tag options:
Tag Description
<<displayErrorMessage>> Error message.

Name: NYCOvertimeCap Manager Approval

Custom Tag options:
Tag Description
<MGR_Message_ManagerApprovalForWaiverSubject> Notification subject.
<MGR_Message_ManagerApprovalForWholeYear>> Entire year waiver approval message.
<MGR_Message_ManagerApprovalForWaiverHours> Specific number of hours waiver approval message.
<EmployeeFullName> Employee's full name.
<ReviewerFullName> Reviewer's full name.
<EmployeePersonId> Employee's person ID.
<ReviewerPersonId> Reviewer's person ID.
<WaiverHours> Waiver hours.
<TotalHours> Employee's total worked hours.
<OvertimeHours> Employee's total worked overtime hours.
<TotalWage> Employee's total wage for a selected date range.

Name: NYCOvertimeCap Manager Approval For Employee

Custom Tag options:
Tag Description
<EMP_Message_ManagerApprovalForWaiverSubject> Notification subject.
<EMP_Message_ManagerApprovalForWholeYear> Entire year waiver approval message.
<EMP_Message_ManagerApprovalForWaiverHours> Specific number of hours waiver approval message.
<EmployeeFullName> Employee's full name.
<ReviewerFullName> Reviewer's full name.
<EmployeePersonId> Employee's person ID.
<ReviewerPersonId> Reviewer's person ID.
<WaiverHours> Waiver hours.
<TotalHours> Employee's total worked hours.
<OvertimeHours> Employee's total worked overtime hours.
<TotalWage> Employee's total wage for a selected date range.

Name: NYCOvertimeCap Manager Approval For Revenue Department

Note: This notification is initiated when the manager approves a waiver. Notification routing is dependent upon the selected Recipient in the Also Notify section of the Reviewer List.
Custom Tag options:
Tag Description
<Message_RevDeptNotificationSubject> Notification subject.
<Message_RevDeptNotificationMessageForEntireYear> Entire year waiver approval message.
<Message_RevDeptNotificationMessageForWaiverHours> Specific number of hours waiver approval message.
<EmployeeFullName> Employee's full name.
<ReviewerFullName> Reviewer's full name.
<EmployeePersonId> Employee's person ID.
<ReviewerPersonId> Reviewer's person ID.
<WaiverHours> Waiver hours.
<TotalHours> Employee's total worked hours.
<OvertimeHours> Employee's total worked overtime hours.
<TotalWage> Employee's total wage for a selected date range.

Name: NYCOvertimeCap Manager Information

Custom Tag options:
Tag Description
<MGR_Message_InformationForWaiverSubject> Notification subject.
<MGR_Message_InformationForWaiver> Waiver information.
<EmployeeFullName> Employee's full name.
<CapAmount> Cap amount.

Name: NYCOvertimeCap Manager Rejection

Custom Tag options:
Tag Description
<MGR_Message_ManagerRejectionForWaiverSubject> Notification subject.
<MGR_Message_ManagerRejectionForWaiver> Waiver information.
<EmployeeFullName> Employee's full name.
<ReviewerFullName> Reviewer's full name.
<ReviewerPersonId> Reviewer's person ID.
<CapAmount> Cap amount.

Name: NYCOvertimeCap Manager Rejection for Employee

Custom Tag options:
Tag Description
<EMP_Message_ManagerRejectionForWaiverSubject > Notification subject.
<EMP_Message_ManagerRejectionForWaiver> Waiver information.
<EmployeeFullName> Employee's full name.
<ReviewerFullName> Reviewer's full name.
<ReviewerPersonId> Reviewer's person ID.
<CapAmount> Cap amount.
    • Version history — Integration
    Tag options
    Tag Description
    <Acknowledgement_Notification_Subject> Contains the notification subject.
    <Acknowledgement_Notification_Message> Contains the notification message body.
    Version Description 1 Initial release.
    When the sum of an employee's annual gross salary in a calendar year exceeds the cap amount, the integration initiates the NYC Overtime Cap workflow.

    1. Configure Access to Integrations.

    2. Deploy the NYCOvertimeCap_v1 integration. See the Deploy Integrations topic.

    3. Get the URL for the APIGatewayServer for the tenant.

    Select the environment

    1. Open the Integration Template Designer: Select Main Menu  > Administration > Application Setup > Integrations Setup > Design Integration Templates.

      Note: If prompted, enter your Username and Password. Click Tap Log in.

    2. Select the Manage tab > Atom Management.
    3. Select your environment.

    Select environment extensions

    1. In Administration, click tap Environment Extensions.
    2. In Process Filter, click tap the magnifying glass Search button. It can take several seconds before the button becomes active.
    3. Scroll to and select the integration pack: NYCOvertimeCap > NYCOvertimeCap_v1.

    Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

    Configure connection settings

    1. Select Connection Settings.

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

      Connection Settings
      Setting Required Actions
      APIGatewayServer Required

      To change the default API gateway server:

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

        Example: <tenantURL>/api
      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:

      1. For each field, clear Use Default.
      2. 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.

    Configure process properties

    1. Select Process Properties.

      Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

    2. Select NYCOvertimeCap_v1_CRTConfig.

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

    Process Properties
    Process property name Column header value
    _NYCOvertimeCap_v1_EligibilityCriteria_CRT Location, WaiverApplicable, CapAmount, WarningPercentage
    _NYCOvertimeCap_v1_Localization_CRT Parameter Name, Locale Policy, Value, Description

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

    Configure cross-reference tables

    Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

    • If more than one row matches a reference value, the first match is the output value.
    • If no match is found, the output value can be null, or the integration can produce errors.
    1. Select Cross Reference.
    2. From the Cross Reference dropdown list, select a NYCOvertimeCap table.
    3. Select Override, which allows you to:
    • Download the tables when you run the integration.
    • Edit the table cells in Extensions.
    1. When you finish, click tap OK.

    Repeat the steps for each of the NYCOvertimeCap tables.

    NYCOvertimeCap_v1_EligibilityCriteria_CRT: Identifies the criteria that an employee must meet before qualifying for NYC Overtime Cap.

    NYC Overtime Cap — Eligibility Criteria CRT structure
    Column name Description
    Version

    A sequential numeric value, within a range of 1—20, that identifies the version associated with a unique combination of CapAmount, Effective Date and Expiry Date.

    When a new CapAmount is announced, add a new row to this CRT, and then increment the Version by 1. Add the corresponding Effective Date and Expiry Date.
    Location

    The location for which the eligibility criteria applies.

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

    Determines whether the process automatically assigns a task to an employee to capture their preferred action when crossing the warning limit.

    Yes — Generate the task.

    No — Do not generate the task; automatically change the pay rule or employment term when the cap amount is reached.
    CapAmount

    The annual gross salary overtime cap.
    Effective Date The effective start date of the employee's year-to-date annual gross salary overtime cap.
    Expiry Date The effective end date of the employee's year-to-date annual gross salary overtime cap.
    WarningPercentage The percentage of actual year-to-date salary that the employee must earn before generating the task assignment.

    NYCOvertimeCap_v1_Localization_CRT: Allows translation of messages and labels into different languages.

    NYC Overtime Cap — Localization CRT structure
    Column header Description
    Parameter Name Parameters defined in NYCOvertimeCap_v1_Localization_CRT process property.
    Locale Policy Locale Policy.

    You can use an asterisk (*) as a wildcard, but put the less-restrictive locale policy names at the bottom of the table because the integration scans cross-reference tables from the top.
    Value Message shown in Additional Details, or value of the label defined in the Run Summary section.

    Example: Comment was not provided.
    Description The description that is shown in Additional Details.

    Example: 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 Localization CRT

    Parameter name

    Value

    _CommentNoteCap

    Cap Amount — <CapAmount>

    _CommentNoteCapReach_Date

    Cap Amount Reach Date — <CapAmountReachDate>

    _CommentNoteEmpInput

    Employee Input — <EmployeeInput>

    _CommentNoteManApproval

    Manager Approval - <ManagerApproval>

    _CommentNoteOTHours

    OT Hours — <OTHours>

    _CommentNoteTotalHours

    Total Hours — <TotalHours>

    _CommentNoteTotalWage

    Total Wage — <TotalWage>

    _CommentNoteWaiver

    Waiver Amount — <WaiverAmount>

    _MessageAckNotificationBody

    Compensatory pay rule or employment term is assigned to you.

    _MessageAckNotificationSubject

    The pay rule or employment term changed.

    _MessageAcknowledgementNotification

    NYCOTCapAcknowledgementNotification is not configured.

    _MessageAnnualWageCombinedPayCode

    Overtime Combined Pay Code is not configured.

    _MessageBPName

    NYCOTCapBPName is not configured.

    _MessageBusinessProcessNotInitiated

    Business process could not be initiated for the employee.

    _MessageCapNotReached

    Annual cap limit not reached for the employee.

    _MessageCompEmploymentTermSuffix

    Compensatory Employment Term Suffix is not configured.

    _MessageCompPayRuleSuffix

    Compensatory Pay Rule Suffix is not configured.

    _MessageCompRuleNotFound

    Compensatory time pay rule not found for the employee.

    _MessageEmployeeNeverSignedOff

    Employee sign-off date is invalid or the timecard is not signed-off.

    _MessageHyperfindEmployee

    Neither Hyperfind nor employee are provided.

    _MessageInactiveEmployee

    Employee is inactive.

    _MessageInvalidAcknowledgementNotification

    NYCOTCapAcknowledgementNotification <NYCOTCapAcknowledgementNotification> is not configured.

    _MessageInvalidAnnualWageCombinedPayCode

    Total Worked Hours Combined Paycode <Total Worked Hours Combined Paycode> is not configured.

    _MessageInvalidBPName

    NYCOTCapBPName <NYCOTCapBPName> not found in UKG Pro Workforce Management™.

    _MessageInvalidNYCInformationComment

    NYCOvertimeCap Comment <Comment> is not configured.

    _MessageInvalidNYCInformationPayCode

    NYCOvertimeCap Information Paycode <NYCOTInformationPayCode> is not configured.

    _MessageInvalidOTCombinedPayCode

    Overtime Combined Pay Code <CombinedpaycodeOThours> is not configured.

    _MessageNotificationNotFound

    Notification <notification> is not configured.

    _MessageNoWage

    Employee does not have a wage assignment.

    _MessageNYCInformationComment

    NYCOvertimeCap Comment is not configured.

    _MessageNYcInformationPayCode

    NYCOvertimeCap Information Pay Code is not configured.

    _MessageOTCombinedPayCode

    Overtime Combined Pay Code is not configured.

    _MessageOvertimeWaiverApplyDay

    Overtime Waiver Apply Day is not configured.

    _MessagePayruleAlreadyAdjusted

    Employee's Compensatory Time Pay Rule or Compensatory Employment Term was previously adjusted.

    _MessagePayruleApplyDay

    Pay Rule Apply Day is not configured.

    _MessagePersonDetailsNotUpdated

    Person details could not be updated for the employee.

    _MessagePrimaryJobNotFound

    Employee's primary job not found in the CRT.

    _MessageTaskPending

    Business Process task pending for the employee.

    _MessageWaiverNotReached

    Employee's earnings do not meet the waiver limit.

    _MessageWarningNotReached

    Employee's earnings do not meet the warning limit.

    _MessageWrongOvertimeWaiverApplyDay

    Provide the correct value for the Overtime Waiver Apply Day.

    _MessageWrongPayruleApplyDay

    Provide correct value for the Pay Rule Apply Day.

    _MessageNoCompTimePayruleApplicable

    Employee requests overtime waiver for the entire year.

    _MessageDisqualifiedEmployee

    Employee is disqualified.
    _MessageInvalidCompPayrule Compensatory Pay rule does not exist. <PayruleName>
    _MessageInvalidEmployee Employee was not found in UKG Pro Workforce Management™.

    Custom tags used in the comment notes are replaced with actual values as described in the custom tags comment notes table; do not change.

    Custom tags — Comment notes
    Tag Description
    <CapAmount> Annual gross salary cap amount limit.
    <CapAmountReachDate> Date on which the annual gross salary cap amount limit is reached.
    <CombinedpaycodeOThours> Combined paycode used to calculate the employee's total overtime hours worked.
    <CombinedPaycodeworkedhours> Combined paycode used to calculate the employee's total worked hours.
    <Comment> Comment added to the paycodes on employee’s timecard.
    <EmployeeInput>

    The employee's selection on the task form. Options include:

    Yes

    No: For entire year

    No: For specific number of hours.

    Auto Approval — meaning that no options were selected.
    <ManagerApproval>

    The manager's response to EmployeeInput. Options include:

    Accept: allow cash compensation

    Reject: switch to compensatory time

    Send back to employee
    <notification> Contains the notification name.
    <NYCOTCapAcknowledgementNotification> Notification sent to employee when the pay rule or employment terms change.
    <NYCOTCapBPNotification> Notification that initiates the business process workflow.
    <NYCOTInformationPayCode> The paycode that stores integration information related to the employee in the timecard.
    <OTHours> Overtime hours worked by the employee.
    <PayruleName> Displays the employee's pay rule name.
    <TotalHours> Total number of hours worked by the employee.
    <TotalWage> Total wage earned by the employee.
    <WaiverAmount> Number of waiver hours requested by employee after reaching annual gross salary cap amount limit.

     

    After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.

    Note:
    • An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
    • An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.
    1. Select Main Menu  > Administration > Application Setup > Integrations Setup > Install Integrations.
    2. Click Tap Create .
    3. In Integration Name, enter a unique name, such as NYCOvertimeCap_v1.
    4. (Optional) Enter a Description.

    Note: Do not select API Integration.

    1. In File Access, select None to not select a connection.
    2. (Optional) If the person who runs the integration does not have full access to integrations, select Execute Integration with System Account. This allows the integration access to all APIs in the FAP, and the relevant permissions and data, regardless of the FAP and GDAP of the person who runs the integration.

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

    4. Email Notifications

      (Optional)

      1. Select Yes to send email and control center notifications for integration runs.
      2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces:

        In Progress — The integration run started and has not finished.

        Completed — The integration ran successfully without errors.

        Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.

        Completed with Errors — The integration run has errors or could not run.

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

    Note: Do not select Allow Minute Interval.

    1. Integration template and parameters
      1. In Integration Template, select NYCOvertimeCap_v1.
      2. Click Tap Assign .
      3. In Integration Parameters, you can override default settings. Click Tap Create .

      4. Complete the configuration for each integration control parameter value.

      5. Click Tap Save.

        Repeat this step for each integration control parameter that supports the NYC Overtime Cap process.

        Integration Parameters
        Parameter name Description / User prompt / Mandatory Template parameter Parameter type
        Locations & Hyperfinds

        The default Hyperfind or Location 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.

        		 Locations&Hyperfinds Hyperfind
        Employee IDs

        A comma-separated list of specific employees for whom the integration is run.

        When no value is entered, the integration defaults to the Locations & Hyperfinds 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 = No

        		 EmployeeIDs Text
        Pay Rule Apply Day

        The day on which compensatory pay rule applies.

        Supported values include:

        • Effective day (default)

        • Effective day+1

        User prompt = Yes

        Mandatory = No

        		 PayRuleApplyDay Boolean
        Total Worked Hours Combined Paycode

        A combined pay code, such as NYCOvertimeCap Annual Wage, that the process uses to calculate the employee's total worked hours.

        User prompt = No

        Mandatory = Yes

        		 TotalWorkedHoursCombinedPaycode Text
        Overtime Combined Paycode

        A combined pay code, such as NYCOvertimeCap Overtime Hours, that the process uses to calculate the employee's total overtime hours worked.

        User prompt = No

        Mandatory = Yes

        		 OvertimeCombinedPaycode Text
        NYCOvertimeCap Information Paycode

        The paycode, such as NYCOvertimeCapInformationPaycode, that the integration puts in the timecard to represent the NYC Overtime Cap information.

        User prompt = No

        Mandatory = Yes

        		 NYCOvertimeCap Information Paycode Text
        NYCOvertimeCap Comment

        The comment, such as Adjusted by NYCOTCap, that the integration attaches to the NYCOvertimeCap Information Pay Code.

        Information in the comment includes: Employee Input, Manager Approval Status, Waiver Amount, Cap amount reach date, Cap Amount, Total Wage, Total hours.

        User prompt = No

        Mandatory = Yes

        		 NYCOvertimeCapComment Text
        NYCOvertimeCap Business Process

        The deployed business process name associated with NYC Overtime Cap integration.

        Default value = NYCOvertimeCap Business Process

        User prompt = No

        Mandatory = Yes

        		 NYCOvertimeCapBusinessProcess Text
        Overtime Waiver Apply Day

        The day from which overtime hours calculation begins.

        Supported values include:

        • Effective day (default)

        • Effective day+1

        User prompt = No

        Mandatory = Yes

        		 Effective day Boolean
        Compensatory Pay Rule Suffix

        The suffix, such as -Comp, which is added to the pay rule name that identifies the appropriate pay rule to calculate compensation.

        User prompt = No

        Mandatory = Yes

        		 CompensatoryPayRuleSuffix Text
        Compensatory Employment Term Suffix

        The suffix, such as -Comp, which is added to the employment term name that identifies the appropriate employment term to calculate compensation.

        User prompt = No

        Mandatory = Yes

        		 CompensatoryEmploymentTermSuffix Text
        Employee Acknowledgement

        The name of the notification, such as NYCOvertimeCap Acknowledgment Notification, which is sent to employee when the pay rule or employment term changes.

        User prompt = No

        Mandatory = Yes

        		 EmployeeAcknowledgementNotification Text
    1. Make sure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. Select Administration > Application Setup > Integrations Setup > Access Profiles; see Configure Access to Integrations.

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

    Run the integration

    1. Select the integration:
      1. Select Main Menu  > Maintenance > Integrations. 
      2. Click Tap Run an Integration . 
      3. Select the NYCOvertimeCap_v1 integration from the list. Click Tap Select. 
      4. (Optional) Enter a unique Integration Run Name to make it easier to identify the run of the integration. Otherwise, the system assigns a default name, which ends with a date and time stamp.
    2. Set parameter as follows:
      • Location: Select a location query of employees.
      • Employee IDs: 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

    3. Select the following:

      • Run Integration: If this is the first time this integration is being run.
      • Re-Run: If this integration has been run before, and the status is not In-Progress, you can run the integration again without entering the parameter values again. Click Tap Yes to continue, or No to not run the integration and to return to the parameter settings.

    4. Wait for the confirmation that the integration completed or failed. Close the panel.
    5. Click Tap Refresh . 
    6. To see details, select the integration run. Select Run Summary.

    Check the results

    Status indicators

    •  In-Progress: The run of this integration has not yet completed.
    •  Completed: The integration ran successfully without errors.
    •  Scheduled: This integration is scheduled to run later or repeatedly.
    • (Grayed out) Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
    •  Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed. If Abort on Failure is configured in an integration set, the integration set stops.
    •  Failed: The integration run has errors or could not run.
    • To troubleshoot and resolve errors, do the following:

      Check the Run Summary for details.

      • To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
      • (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant.

    To check the results in more detail:

    1. Click Tap the tile for the integration run.
    2. Click Tap Run Summary to see the results of the integration run.

      Example Run Summary details

      Note: The available details vary by integration and configuration.

      • Integration Run Name: Name of this run of the integration.
      • Process Name: Name of any integration set that includes this integration.
      • Integration Name: Name of the installed integration.
      • Integration Reference ID: Unique identifier for this integration run (to help in troubleshooting errors).
      • User: The person or user account that ran the integration.
      • Integration Type: Import, Export, or None
      • Start Date: Date and time when the integration run started.
      • End Date: Date and time when the integration run finished.
      • Status: In-Progress, Completed, Completed with Errors, or Failed.
      • Records Processed: Number of records that were processed.
      • Records Created: Number of records that were created.
      • Errors: Number of records that failed.
      • Source Files, Output File, and Error Files: For file-based import integrations, use Manage SFTP to access the source and output files on the inbound (source) and outbound (destination) SFTP folders. See the Manage SFTP topic.
    3. Log in to the destination system and ensure that the data has been correctly updated.

    Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the topic.

    Version history — Process model
    Version Description
    1 Initial release.
    The workflow assigns tasks to employees whose cap amount warning limit is reached. The employee chooses the method of handling overtime compensation which is then acted upon by a reviewer.

    Migrate the business process model to the tenant

    Migrate the NYC Overtime Cap process model to the customer tenant using Setup Data Manager (SDM).

    1. Log in to the appropriate tenant.

    2. Go to Main Menu > Administration > Setup Data Manager.

    3. Select the Source tenant where the Process Model resides, and select the template to copy. It is a .zip file. A message appears in the Source column: Source: Import from <filename>.zip.

    4. Click Tap Review and Publish. The Publish Summary panel appears.

    5. Review the Publish Summary panel. It lists the items that were extracted from the migration file. If you approve, click tap Publish with Comment or just Publish.

    6. Click Tap Go to Publish History at the bottom of the panel to view the status of the data transfer. The Publish History page contains a table that lists the items you have published. If there were errors during the transfer, the button under the Errors column for that row is black.

    7. To view details, click tap the appropriate row and click tap View Selected.

    8. On the History for publish run page, click tap Show all to view the setup data that you published, and the errors that occurred, if any, listed by item type and name.

    Configure the decision tables

    Configure the NYC Overtime Cap decision tables.

    1. Go to Main Menu > Administration > Application Setup > Business Process setup > Process Models.

    2. Select the NYCOvertimeCap process and click tap Edit. The process model enters edit mode.

    3. Select the Decision Tables tab.

    4. Click Tap Everyone's, and then select the decision table to edit.

    5. Click Tap Decision Table Editor to add or update the rows in the table.

    6. Click Tap Save and close.

    Caution:

    • Values entered in the decision tables are case-sensitive, and must match configured values in UKG Pro Workforce Management™.

    • Do not remove variables, variable names, or variable types from any decision table.

    Edit the following decision tables:

    NYCOvertimeCap_v1_InternalParameters — Controls internal workflow parameters.

    Warning:

    Do not change parameters or values in the _InternalParameters decision table.
    NYC Overtime Cap Internal Parameters decision table structure
    Parameter Description
    Admin

    Internal user; do not change.

    Default value: SERVICES-LEVEL3
    EmployeePersonNumber Employee person number.
    NYCOvertimeCapPaycode NYC Overtime Cap information paycode.
    NYCOvertimeCapComment Comment associated with NYCOvertimeCapPaycode.
    Notes Notes added to the information paycode in the employee's timecard.

    NYCOvertimeCap_v1_Parameters — Controls the NYC overtime cap process.

    NYC Overtime Cap Parameters decision table structure
    Parameter Description
    ManagerInformationNotification Task response notification sent to the manager.
    EmployeeInformationNotification Pay rule or employment term change notification sent to the employee.
    ManagerApprovalNotification Manager task approval notification.
    ManagerRejectionNotification Manager task rejection notification.
    EmployeeApprovalNotification Manager approval notification sent to the employee.
    EmployeeRejectionNotification Manager rejection notification sent to the employee.
    DepartmentNotification Revenue department notification.
    ErrorNotification Process failure error notification.
    SilentlyApproveBy Automatic approval time when no action is taken on task.

    NYCOvertimeCap_v1_Reviewer_List — Controls the reviewer list associated with a location.

    NYC Overtime Cap Reviewer List decision table structure
    Parameter Description
    PrimaryJobLocation Identifies the location path for which the reviewers list has been created.
    ReviewerListName The location's reviewer list.

    NYCOvertimeCap_v1_Locale — Allows customization of the text in the workflow form and notifications for different locales.

    NYC Overtime Cap Locale decision table structure
    Variable name Variable type Description
    Key Text Internal field label; do not change.
    Locale Policy Text

    Name of the locale policy for which the text applies.

    When the text applies to all locales, retain the empty value.
    Message Text Text displayed in the workflow form or notification.
    Description Text (Optional) Additional information.
    Note:

    • Localization of business process workflows remains optional, but is supported.

    • The decision table 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 decision table. Text within tags ("<>") must not be changed.

    • Names of the parameters in the decision table 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 decision table with the appropriate Locale Policy, and then add the localized values in the Message column.

    • The last row in the decision table must remain empty ("!=empty".)

    Sample Locale decision table

    Parameter

    Description

    Message_ReviewerListError

    The Reviewer List has more than one reviewer or more than one review steps defined.

    Message_NoAttendanceAdmin

    The Reviewer List is configured with Attendance Administrator and the employee does not have an assigned attendance administrator.

    Message_NoLeaveAdmin

    The Reviewer List is configured with Leave Administrator and the employee does not have an assigned leave administrator.

    Message_LocationNotFound

    The employee's primary location does not match a Primary Job Location defined in NYCOvertimeCap_v1_Reviewer_List DT.

    Message_InvalidSilentApprovalFormat

    The SilentlyApproveBy parameter is not configured using hh:mm format.

    Message_AutoApproval

    Message that indicates automatic task approval.

    Message_InvalidNotification

    Message that indicates invalid notification configuration.

    EMP_Label_AnnualSalaryLimitText

    Employee form label that displays when the employee is approaching the annual salary limit.

    EMP_Label_EarningLimitText

    Employee form label that displays next to the earning limit.

    EMP_Label_TotalEarningText

    Employee form label that displays next to the total earnings.

    EMP_Label_CompensatoryTimeText

    Employee form label that indicates the employee will receive compensatory hours upon reaching cap limit.

    EMP_Label_AcceptText

    Employee form label that displays next to the task acceptance options.

    EMP_Label_AutoApproveText

    Employee form label that indicates the automatic approval time.

    EMP_Label_CommentText

    Employee form label that prompts for a comment.

    EMP_Label_RequestReassignText

    Employee form label that indicates the approver reassigned the request.

    EMP_Label_ReasonText

    Employee form label that displays the approver's request reassignment reason.

    EMP_Label_InputOption1

    Employee form label that displays next to the option to pay with compensatory time-off.

    EMP_Label_InputOption2

    Employee form label that displays next to the option to pay all overtime hours with cash.

    EMP_Label_InputOption3

    Employee form label that displays next to the option to pay cash for a specified number of overtime hours, followed with compensatory time-off hours for additional overtime hours.

    MGR_Label_WaiverForYearText

    Reviewer form label that displays when the employee requests waiver for the entire year.

    MGR_Label_WaiverForHoursText

    Reviewer form label that displays when the employee requests waiver for a specific number of hours.

    MGR_Label_ChooseOptionText

    Reviewer form label that displays next to reviewer options.

    MGR_Label_AutoApproveText

    Reviewer form label that indicates the automatic approval time.

    MGR_Label_EmployeeCommentText

    Reviewer form label that displays employee comments.

    MGR_Label_CommentText

    Reviewer form label that prompts for a comment.

    MGR_Label_Response1

    Reviewer form label that displays next to the pay overtime with cash response.

    MGR_Label_Response2

    Reviewer form label that displays next to the pay overtime with compensatory time-off response.

    MGR_Label_Response3

    Reviewer form label that displays next to the allow employee to resubmit waiver response.

    MGR_Message_ManagerApprovalForWholeYear

    Manager Approval Notification message that shows the reviewer's approval of the entire year waiver request.

    EMP_Message_ManagerApprovalForWholeYear

    Employee Approval Notification message that shows the reviewer's approval of the entire year waiver request.

    MGR_Message_ManagerApprovalForWaiverHours

    Manager Approval Notification message that shows the reviewer's approval of the specific hours waiver request.

    EMP_Message_ManagerApprovalForWaiverHours

    Employee Approval Notification message that shows the reviewer's approval of the specific hours waiver request.

    MGR_Message_ManagerApprovalForWaiverSubject

    Manager Approval Notification Subject content that shows the reviewer's waiver request approval.

    EMP_Message_ManagerApprovalForWaiverSubject

    Employee Approval Notification Subject content that shows the reviewer's waiver request approval.

    EMP_Message_ManagerRejectionForWaiver

    Employee Rejection Notification message that shows the reviewer's waiver request rejection.

    MGR_Message_ManagerRejectionForWaiver

    Manager Rejection Notification message that shows the reviewer's waiver request rejection.

    EMP_Message_ManagerRejectionForWaiverSubject

    Employee Rejection Notification Subject content that shows the reviewer's waiver request rejection.

    MGR_Message_ManagerRejectionForWaiverSubject

    Manager Rejection Notification Subject content that shows the reviewer's waiver request rejection.

    MGR_Message_InformationForWaiver

    Manager Information Notification that informs the reviewer about the employee's compensatory hours selection.

    MGR_Message_InformationForWaiverSubject

    Manager Information Notification Subject content that informs the reviewer about the employee's compensatory hours selection.

    EMP_Message_InvalidInputFormat

    Employee message that shows the employee entered incorrectly formatted waiver hours on the employee form.

    EMP_Message_WaiverAmountNotProvided

    Employee message that shows the employee did not enter waiver hours on the employee form.

    Message_RevDeptNotificationSubject

    Revenue Department Notification Subject content that shows reviewer's waiver request approval.

    Message_RevDeptNotificationMessageForEntireYear

    Revenue Department Notification that shows reviewer's waiver request approval for the entire year.

    Message_RevDeptNotificationMessageForWaiverHours

    Revenue Department Notification that shows reviewer's waiver request approval for specific hours.

    EMP_Message_InformationForWaiver

    Employee Information Notification that informs the employee about their waiver selection.

    EMP_Message_InformationForWaiverSubject

    Employee Information Notification Subject content that informs the employee about their waiver selection.

    MGR_Label_Submit

    Reviewer form Submit label.

    EMP_Label_Submit

    Employee form Submit label.

    Custom tags used in the notifications are replaced with actual values as described in the custom tags notifications table.

    Custom tags — Notifications
    Tag Description
    <EMP_Message_ManagerApprovalForWaiverSubject>

     

    The manager approval notification subject content that is sent to the revenue department.
    <Message_RevDeptNotificationMessageForEntireYear>

    The entire year waiver approval message that is sent to the revenue department.
    <Message_RevDeptNotificationMessageForWaiverHours> The hours waiver approval message that is sent to the revenue department.
    <EmployeeFullName> Employee's full name.
    <ReviewerFullName> Reviewer's full name.
    <ReviewerPersonId>

    Reviewer's person ID.
    <EmployeePersonId>

    Employee's person ID
    <WaiverHours> Waiver hours.
    <TotalHours> Total hours worked by an employee..
    <OvertimeHours> Overtime hours worked by an employee.
    <TotalWage> Total wage for a selected date range.
    <LocationName> Reviewer list location.
    <NotificationName> Notification name.
    <Year> The current year.

    Deploy the updated business process model

    Process models must be redeployed every time changes are made to an existing model. Re-deployment is not required for decision table changes.

    Follow these steps to deploy the process model. For detailed information, see the online help topic Deploy Business Process Models.

    1. Go to Main Menu > Administration > Application Setup > Business Process Setup > Process Models.

    2. Select the NYCOvertimeCap_v1 model.

    3. Click Tap Edit, and then configure the deployment dates, and required parameters, such as Hide from the Action List, Tile List, and GoTo List.

      Caution: Do not make a selection from the Template Categories list.

    4. Click Tap Save, and then select Return to deploy.

    Note:

    Assign the process model to workflow notifications initiated by the business process, such as:

    • NYCOvertimeCap Employee Information

    • NYCOvertimeCap Error Notification

    • NYCOvertimeCap Manager Approval

    • NYCOvertimeCap Manager Approval For Employee

    • NYCOvertimeCap Manager Approval for Revenue Department

    • NYCOvertimeCap Manager Information

    • NYCOvertimeCap Manager Rejection

    • NYCOvertimeCap Manager Rejection for Employee

    API Details

    API Name

    Type

    Resource Path

    Description

    User Preferences

    GET

    /v1/commons/user_preferences/locale_policy

    Allows access to locale policy user preferences.

    Retrieve All Extensions

    POST

    /v1/commons/persons/extensions

    Returns all extensions data for a person record based on person number.

    Retrieve Paycodes

    POST

    /v1/timekeeping/setup/pay_codes/multi_read

    Returns one or more paycodes available to the logged-in manager by object references.

    Timecard operations

    GET

    /v1/timekeeping/timecard?person_number=employee&start_date=yesterday&end_date=today&select=PAYCODE_EDITS

    Calls the Timecard operation using the GET HTTP method to view an employee's punches.

    Update Timecard as Manager

    POST

    /v1/timekeeping/timecard

    Updates a timecard for an employee as a manager. Add, update, or delete punches, paycode edits, hours worked, and exception Comments.

    Retrieve Reviewer List by Criteria

    GET

    /v1/commons/reviewer_lists?name=ReviewerListName

    Returns a reviewer list by name, type, and active status.

    Retrieve Leave Admin by Person Number

    GET

    /v1/commons/persons/leave_admin

    Returns the administrator assigned to a Leave employee by person number.

    Retrieve Attendance Admin by Person Number

    GET

    /v1/commons/persons/attendance_admin

    Returns the administrator assigned to an Attendance employee by person ID.

     

    Retrieve Time zone by ID

    GET

    /v1/commons/setup/timezones/{id}

    This operation returns a time zone by ID.

    Retrieve Generic Notifications

    POST

    /v1/commons/generic_notifications/multi_read

    This operation returns a list of Generic Notifications by object references.

    Execute Business Process

    POST

    /v1/platform/workflow/business_processes/execute

    Performs operations on the business processes. Business processes are organized flows of business activities or tasks that achieve a business goal.