New York City (NYC) Overtime Cap

The New York City Overtime Cap (NYCOTCAP) extension delivers an integration and workflow that support employees who qualify for overtime waivers.

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.

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

Considerations and limitations

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

Use cases

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.

NYC Overtime Cap integration

Before you start

Before you configure the NYC Overtime Cap integration, you must do the following:

  1. Configure Access to Integrations.

  2. Configure the following:
    • Comment: Configure a comment that the integration adds to the timecard along with the employee's adjustment information. The pay codes category must be selected during configuration. This comment must be used exclusively by the NYC Overtime Cap extension.

      See the Comments topic.

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

    • Combined Paycode: Configure combined paycodes. The integration uses one combined paycode to calculate the employee's total worked hours; and the second to calculate the employee's total worked overtime hours.

      See the Combined Paycodes topic.

      Examples: NYCOvertimeCap Annual Wage and NYCOvertimeCap Overtime Hours

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

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

    • Hyperfind: Configure a Hyperfind or Location query that includes only employees who qualify under the New York Citywide Agreement.

      See the Hyperfind Queries topic.

    • Workflow Notifications: Configure a generic workflow notification that facilitate the NYC Overtime Cap integration. 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:

      Custom tag options

      Tag

      Description

      < Acknowledgement_Notification_Subject>

      Notification subject.

      < Acknowledgement_Notification_Message>

      Notification message.

  3. Get the URL, User, and Password for the APIGatewayServer.

Configure the NYC Overtime Cap integration

  1. Deploy the NYC Overtime Cap integration
    Note: For more information, see the Deploy Integration Packs to your Atom topic.
    1. Open the Integration Template Designer: Select Main Menu Administration > Application Setup > Integrations Setup > Design Integration Templates.

      Note: If prompted, enter your Username and Password. Click Tap Log in.
    2. Make sure that the Account is correct. If not, select the right account.

    3. Select the Deploy tab > Integration Packs.
      1. From the list in the left column, search for and select the Pro WFM NYC Overtime Cap Extension integration.
        Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.
      2. Click Tap Install.

      3. From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button
        Select items
        .
  2. Configure the NYC Overtime Cap integration settings
    1. Select the environment
      1. Select the Manage tab > Atom Management.
      2. Select your environment.
    2. Select environment extensions
      1. In Administration, click tap Environment Extensions.
      2. In Process Filter, click tap the magnifying glass
        Search button
        . It can take several seconds before the button becomes active.
      3. Scroll to and select the integration pack: NYC Overtime Cap > NYCOvertimeCap_iPack_v2.
  3. Configure connection settings
    Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.
    1. Select Connection Settings.
    2. From the Connection dropdown list, select and configure the following:

      Connection Settings

      Connection Settings for the integration

      Setting

      Required

      Actions

      NYCOvertimeCap_iPack_v2_APIGatewayServer

      Required

      To change the default API gateway server:

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

        Example: <tenantURL>/api

      NYCOvertimeCap_iPack_v2_EligibilityCriteria_CRT

      Required

      Enable Override.

      NYCOvertimeCap_iPack_v2_Locale_CRT

      Required

      Enable Override.

  4. 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_iPack_v2_CRTConfig to set process properties that must be configured before the integration can run. This main process starts the integration process and handles errors.

    Process properties

    Process properties

    Process property name

    Column header value

    _NYCOvertimeCap_iPack_v2_EligibilityCriteria_CRT

    Location,WaiverApplicable,CapAmount,WarningPercentage

    _NYCOvertimeCap_iPack_v2_Locale_CRT

    Parameter Name,Locale Policy,Value,Description

  5. 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 list, select a NYCOvertimeCap_iPack_v2 table.
    3. Select Override, which allows you to:
      • Download the tables when you run the integration
      • Edit the table cells in Extensions
    4. When you finish, click tap OK.
    5. Repeat the steps for each of the NYCOvertimeCap tables.
      • NYCOvertimeCap_iPack_v2_EligibilityCriteria_CRT: Identifies the criteria that an employee must meet before qualifying for NYC Overtime Cap.

        NYC Overtime Cap — Eligibility Criteria CRT structure

        NYC Overtime Cap — Eligibility Criteria CRT structure

        Column name

        Description

        Version

        A sequential numeric value, within a range of 1—20, which 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_iPack_v2_Locale_CRT: Allows translation of messages and labels into different languages.

        NYC Overtime Cap — Locale CRT structure

        NYC Overtime Cap — Locale CRT structure

        Column name

        Description

        Parameter Name

        Key for which localization is defined.

        Locale Policy

        Locale Policy.

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

        Value

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

        Example: Comment was not provided.

        Description

        The description that is shown in Additional Details, or value of the label defined in the Run Summary section.

        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 Locale CRT content

        Sample Locale CRT content

        Parameter name

        Value

        Comment_NoteCap

        Earnings Limit — < CapAmount>

        Comment_NoteCapReach_Date

        Earnings Limit Reach Date — < CapAmountReachDate>

        Comment_NoteEmpInput

        Employee Response — < EmployeeInput>

        Comment_NoteManApproval

        Manager Response — < ManagerApproval>

        Comment_NoteOTHours

        OT Hours (YTD) — < OTHours>

        Comment_NoteTotalHours

        Total Hours (YTD) — < TotalHours>

        Comment_NoteTotalWage

        Total Wage (YTD) — < TotalWage>

        Comment_NoteWaiver

        Waiver Amount — < WaiverAmount>

        Message_AckNotificationBody

        Compensatory pay rule or employment term is assigned to you.

        Message_AckNotificationSubject

        The pay rule or employment term changed.

        Message_AcknowledgementNotification

        NYCOTCapAcknowledgementNotification is not configured.

        Message_AnnualWageCombinedPayCode

        Overtime Combined Pay Code is not configured.

        Message_BPName

        NYCOTCapBPName is not configured.

        Message_BusinessProcessNotInitiated

        Business process could not be initiated for the employee.

        Message_BusinessProcessInitiatedWithError

        API encountered an unexpected server error.

        Message_CapNotReached

        Annual cap limit not reached for the employee.

        Message_CompEmploymentTermSuffix

        Compensatory Employment Term Suffix is not configured.

        Message_CompPayRuleSuffix

        Compensatory Pay Rule Suffix is not configured.

        Message_CompRuleNotFound

        Compensatory time pay rule not found in CRT for the employee.

        Message_DisqualifiedEmployee

        Employee is disqualified.

        Message_EmployeeNeverSignedOff

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

        Message_HyperfindEmployee

        Neither Hyperfind nor employee are provided.

        Message_InactiveEmployee

        Employee is inactive.

        Message_InvalidAcknowledgementNotification

        NYCOTCapAcknowledgementNotification< NYCOTCapAcknowledgementNotification> is not configured.

        Message_InvalidAnnualWageCombinedPayCode

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

        Message_InvalidBPName

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

        Message_InvalidCompPayrule

        Compensatory Pay rule does not exist. < PayruleName>

        Message_InvalidEmployee

        Employee was not found in UKG Pro Workforce Management.

        Message_InvalidNYCInformationComment

        NYCOvertimeCap Comment< Comment> is not configured.

        Message_InvalidNYCInformationPayCode

        NYCOvertimeCap Information Paycode< NYCOTInformationPayCode> is not configured.

        Message_InvalidOTCombinedPayCode

        Overtime Combined Pay Code< CombinedpaycodeOThours> is not configured.

        Message_InvalidTrackingPayCode

        NYCOTTrackingPayCode< NYCOTTrackingPayCode> is not configured.

        Message_NoCompTimePayruleApplicable

        Employee requests overtime waiver for the entire year.

        Message_NotificationNotFound

        Notification < notification> is not configured.

        Message_NoWage

        Employee does not have a wage assignment.

        Message_NYCInformationComment

        NYCOvertimeCap Comment is not configured.

        Message_NYCInformationPayCode

        NYCOvertimeCap Information Pay Code is not configured.

        Message_OTCombinedPayCode

        Overtime Combined Pay Code is not configured.

        Message_OvertimeWaiverApplyDay

        Overtime Waiver Apply Day is not configured.

        Message_PayruleAlreadyAdjusted

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

        Message_PayruleApplyDay

        Pay Rule Apply Day is not configured.

        Message_PersonDetailsNotUpdated

        Person details could not be updated for the employee.

        Message_PrimaryJobNotFound

        Employee's primary job not found in the CRT.

        Message_TaskPending

        Business Process task pending for the employee.

        Message_TackingPaycode

        Tracking paycode is not configured.

        Message_TackingPaycodeNotAdded

        Tracking paycode could not be added for the employee.

        Message_WaiverNotReached

        Employee's earnings do not meet the waiver limit.

        Message_WarningNotReached

        Employee's earnings do not meet the warning limit.

        Message_WrongOvertimeWaiverApplyDay

        Provide the correct value for the Overtime Waiver Apply Day.

        Message_WrongPayruleApplyDay

        Provide correct value for the Pay Rule Apply Day.

        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

        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.

Install the NYC Overtime Cap 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.
  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_iPack_v2.
  4. (Optional) Enter a Description.
    Note: Do not select API Integration.
  5. In File Access, select None to not select a connection.
  6. (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.
  7. (Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.

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

  9. 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.
  10. Integration template and parameters
    1. In Integration Template, select NYCOvertimeCap_iPack_v2.
    2. Click Tap Assign .
    3. In Integration Parameters, you can override default settings.
    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

      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 that the process uses to calculate the employee's total worked hours.

      Default = NYCOvertimeCap Annual Wage

      User prompt = No

      Mandatory = Yes

      TotalWorkedHoursCombinedPaycode

      Text

      Overtime Combined Paycode

      A combined paycode that the process uses to calculate the employee's total overtime hours worked.

      Default = NYCOvertimeCap Overtime Hours

      User prompt = No

      Mandatory = Yes

      OvertimeCombinedPaycode

      Text

      NYCOvertimeCap Information Paycode

      The paycode that the integration puts in the timecard to represent the NYC Overtime Cap information.

      Default = NYCOvertimeCap Information

      User prompt = No

      Mandatory = Yes

      NYCOvertimeCap Information

      Text

      NYCOvertimeCap Comment

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

      Default = Adjusted by NYCOTCap

      User prompt = No

      Mandatory = Yes

      NYCOvertimeCapComment

      Text

      Business Process Name

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

      Default value = NYCOvertimeCap Business Process

      User prompt = No

      Mandatory = Yes

      BusinessProcessName

      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

      OvertimeWaiverApplyDay

      Boolean

      Compensatory Pay Rule Suffix

      The suffix which is added to the pay rule name that identifies the appropriate pay rule to calculate compensation.

      Default = -CompTime

      User prompt = No

      Mandatory = Yes

      CompensatoryPayRuleSuffix

      Text

      Compensatory Employment Term Suffix

      The suffix which is added to the employment term name that identifies the appropriate employment term to calculate compensation

      Default = -CompTime

      User prompt = No

      Mandatory = Yes

      CompensatoryEmploymentTermSuffix

      Text

      Employee Acknowledgement

      The name of the notification which is sent to employee when the pay rule or employment term changes.

      Default = NYCOvertimeCap Acknowledgment Notification

      User prompt = No

      Mandatory = Yes

      EmployeeAcknowledgementNotification

      Text

  11. Make sure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations.

    See Configure Access to Integrations .

Run and test the NYC Overtime Cap integration

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

  1. Run the integration
    1. Select the integration:
      1. Select Main Menu Maintenance > Integrations.
      2. Click Tap Run an Integration .
      3. Select the NYCOvertimeCap_iPack_v2 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.
  2. 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 Schedule Integrations topic.

APIs

API Details — NYC Overtime Cap integration

API Details — NYC Overtime Cap integration

API Name

Type

Resource Path

Description

Retrieve User Preferences for Current User

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 as Manager

POST

/v1/timekeeping/setup/pay_codes/multi_read

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

Retrieve Timecard as Manager

GET

/v1/timekeeping/timecard

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

NYC Overtime Cap process model

Before you start

Before you configure the NYC Overtime Cap business process, you must do the following:

  • Reviewer List: Configure a reviewer list dedicated to the NYCOTCap extension. Select one or more Reviewers from Step 1.

    See the Reviewer Lists topic.

  • Workflow Notifications: Configure generic workflow notifications that facilitate the NYC Overtime Cap business process. Design the notifications by combining free text with available custom tags.

    See the Generic notifications topic.

    Examples include:

    Name: NYCOvertimeCap Employee Information

    Custom Tag options:

    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:

    Custom Tag options

    Tag

    Description

    < displayErrorMessage>

    Error message.

    Name: NYCOvertimeCap Manager Approval

    Custom Tag options:

    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:

    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:

    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:

    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:

    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:

    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.

Configure the NYC Overtime Cap business process model

Note: The process for configuring and deploying this and other Business Process Extensions is the same as all Business Process models .
  1. Migrate the NYC Overtime Cap 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.

  2. Configure the NYC Overtime Cap decision tables
    Note: Decision tables are configurable based on user requirements and can be changed accordingly. These tables are dynamic and can be updated at any time without redeployment of the process model.
    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.

    7. Edit the following decision tables:
      Caution:
      • Values entered in the decision tables are case-sensitive, and must match configured values in the application.

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

      • 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

        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

        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

        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

        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.​
        • You can translate some or all messages by adding lines to the table in their preferred translation for specific locales. Decision tables are scanned from top to bottom; therefore, place messages for the most commonly used Locale Policy at the top of the decision table and less-restrictive locale policies at the bottom.
        • Text within tags ("<>") must not be changed.
        • The decision table holds all messages represented with standard English labels; these apply to all locales when the Locale Policy is set to !=empty.
        • 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 !=empty ​Locale Policy, add a new row to the decision table with the appropriate Locale Policy, and then add the localized value in the Message column.​
        • Decision tables support operators like "Contains," "Starts with," "Ends with," and "Is Not Empty." You can achieve your preferred results by following these examples:
          • To match any non-empty or any string (like *), use the "Is Not Empty" operator.
          • To match a string starting with "ABC" (like "ABC*"), use the "Starts with" operator and set the value to "ABC".
          • To match a string containing "English" as substring, use the "Contains" operator with the value "English".
        • The last row in the decision table must remain empty ("!=empty".)

        Sample Locale decision table content

        Sample Locale decision table

        Parameter

        Description

        EMP_Label_AcceptText

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

        EMP_Label_AnnualSalaryLimitText

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

        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_CompensatoryTimeText

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

        EMP_Label_EarningLimitText

        Employee form label that displays next to the earning limit.

        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.

        EMP_Label_ReasonText

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

        EMP_Label_RequestReassignText

        Employee form label that indicates the approver reassigned the request.

        EMP_Label_Submit

        Employee form Submit label.

        EMP_Label_TotalEarningText

        Employee form label that displays next to the total earnings.

        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.

        EMP_Message_InvalidInputFormat

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

        EMP_Message_ManagerApprovalForWaiverHours

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

        EMP_Message_ManagerApprovalForWaiverSubject

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

        EMP_Message_ManagerApprovalForWholeYear

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

        EMP_Message_ManagerRejectionForWaiver

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

        EMP_Message_WaiverAmountNotProvided

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

        Message_AutoApproval

        Message that indicates automatic task approval.

        Message_InvalidNotification

        Message that indicates invalid notification configuration.

        Message_InvalidSilentApprovalFormat

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

        Message_LocationNotFound

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

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

        Message_RevDeptNotificationSubject

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

        Message_ReviewerListError

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

        MGR_Label_AutoApproveText

        Reviewer form label that indicates the automatic approval time.

        MGR_Label_ChooseOptionText

        Reviewer form label that displays next to reviewer options.

        MGR_Label_CommentText

        Reviewer form label that prompts for a comment.

        MGR_Label_EmployeeCommentText

        Reviewer form label that displays employee comments.

        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_Label_Submit

        Reviewer form Submit label.

        MGR_Label_WaiverForHoursText

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

        MGR_Label_WaiverForYearText

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

        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.

        MGR_Message_ManagerApprovalForWaiverHours

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

        MGR_Message_ManagerApprovalForWholeYear

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

        MGR_Message_ManagerRejectionForWaiver

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

        MGR_Message_ManagerRejectionForWaiverSubject

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

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

    Custom tags — Notifications

    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.

  3. Deploy the updated NYC Overtime Cap 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_iPack_v2 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

APIs

API Details — NYC Overtime Cap business process model

API Details — NYC Overtime Cap business process model

API Name

Type

Resource Path

Description

Retrieve User Preferences for Current User

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 as Manager

POST

/v1/timekeeping/setup/pay_codes/multi_read

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

Retrieve Timecard as Manager

GET

/v1/timekeeping/timecard

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

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 Generic Notifications

POST

/v1/commons/generic_notifications/multi_read

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

Version history

NYC Overtime Cap integration

Version history — NYC Overtime Cap integration

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.

iPack_v2

The NYC Overtime Cap integration delivery is now by way of an iPack.

NYC Overtime Cap business process model

Version history — NYC Overtime Cap business 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.