Configure the Workforce Planner Schedule Import Integration

This topic describes how to configure this integration.

Workforce Planner is the system of record for schedules and time off (non-working time).

This is an API-based integration Initiates and delivers the payload by API calls from an application to Integration Hub, but not by way of the user interface. pack that imports schedule data from Workforce Planner; it contains two integrations that translate schedules to pay:

  • Schedule Batch integration imports schedules for multiple employees or multiple dates. Typically, you run this integration weekly or daily to synchronize the systems and time clocks. Use Workforce Planner Task Manager to run the integration on demand or on a schedule.
  • Schedule integration imports working time changes to update the timecard, and non-working time changes to update accrual balances, for one employee at a time over short time periods of one calendar day. Imports are completed quickly and in near real-time in response to transactions or events in Workforce Planner. These events include shift trades, swaps, time-off, back fill, or extra duty.
  1. Configure adjustment and combination rules.
  2. In Workforce Planner, configure work codes and categories, employee categories, tag references to schedule and segment tags in Dimensions, schedule and segment tags, no pay segment tag, securities, and access. See Configure Workforce Planner for Integrations.

Configure the integration

  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.
  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 one of the following integration packs:
    • Schedule Batch: Dimensions Workforce Planner Schedule Batch Import > WFPScheduleImport-Batch-v1
    • Schedule: Dimensions Workforce Planner Schedule Import > WFPScheduleImport-v1
  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. (Optional) From the Process Property dropdown list, select WFPAPIErrorHandlerProperties to define how to handle errors if integration runs exceed the limitations of an API.

    MaxRetry: Defines the maximum number of attempts to try again to run integrations if an API limit is exceeded.

    Default = 0 (do not try again)

    To set the maximum number of retries:

    1. Clear Use Default.
    2. From Value, select 1, 2, or 3 times to retry.

    InitialTimeToWait: If an API limit is exceeded, this property defines how long to wait before sending the API call again.

    Default = 60000 ms (1 minute)

    This property sets only the first retry. If the API call has to be sent again, each repetition adds 60,000 ms to the wait time.

    Example:

    • 1st TimetoWait = 60,000 ms (InitialTimeToWait)
    • 2nd TimetoWait = 60,000 ms + 60,000 ms = 120,000 ms
    • 3rd TimetoWait = 60,000 ms + (2 * 60,000 ms) = 180,000 ms

    To change the initial wait time:

    • Clear Use Default.
    • Enter the wait time in milliseconds (ms) up to a maximum of 180000 ms.
  3. From the Process Property dropdown list, select ProcessProperties to set process properties that must be configured before the integration can run. For this integration, these values are defined in Workforce Planner and updated when you run the integration.

    Caution: All of the property values must be the same for both the Schedule Batch and Schedule Import integrations.

    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.

    Process Properties
    PropertyRequiredActions
    FromDateNot requiredStart date to synchronize the schedule data.
    ThruDateNot requiredEnd date to synchronize the schedule data.
    PayCodeEditsOnlyNot required

    Default = false, synchronize shifts (working time) and paycode A category of time or money that employees earn, for example, Regular Hours, Bonus, or Sick. edits (non-working time).

    AdjustToCalendarDayNot required

    Workforce Planner assigns a Calendar Day to a shift. A shift is paid on the corresponding calendar day even though it can start or end on, before, or after this day.

    Default = false.

    To assign a shift to a calendar day that is before the start day of a shift set Contains a collection of shifts used to define workload (staffing) requirements for locations. Example: An organization has shifts that the majority of employees work: 7 AM-3 PM and 3 PM-11 PM.t this property to true. This creates a virtual shift segment Parts of shifts that are assigned to a job in the business structure, either primary or transfer jobs. with a NoPaySegmentTag.

    1. Clear Use Default.
    2. Select Value.

    Caution: This property must be set the same in both the Schedule Batch and Schedule Import integrations.

    NoPaySegmentTagNot required

    The segment tag for non-working time that is not paid.

    To use a different tag:

    1. Clear Use Default.
    2. In Value, enter the name of the TSG No Pay segment tag. To create the tag, see Configure Dimensions for Workforce Planner Integrations > Configure a Dimensions tag.
    MergeAdjacentShiftsNot required

    Default = false

    To merge multiple adjacent shifts into one shift:

    1. Clear Use Default.
    2. Select Value.

    Caution: This property must be set the same in both the Schedule Batch and Schedule Import integrations.

    DayDivideNot required

    Default = 0

    The virtual shift segment starts from the day divide Time that defines when one day ends and a new day begins. The day divide is defined in a pay rule. If a shift crosses the day divide, the pay rule defines how the hours are allocated: to the day before, the day after, or to the day on which the worked hour occurred. minus 1 hour on the calendar day of the shift until the start date and time of the shift.

    AdjustToCalendarDay must be set to true.

    To change the start time of the virtual shift segment:

    1. Clear Use Default.
    2. In Value, enter a positive number of hours.

    ExtraDaysBeyondPeriod

    		Not required

    Default = 1

    Expected number of day divides that a shift could cross.

    To set more than one day divide:

    1. Clear Use Default.
    2. In Value, enter a whole number of day divides.
    AtwFromDateNot required

    The start date of the active time window (ATW) in Workforce Planner.

    • No default value is assigned to this property.
    • You do not define the value of this property because it is imported.
    AtwThruDateNot required

    The end or through date of the active time window in Workforce Planner.

    • No default value is assigned to this property.
    • You do not define the value of this property because it is imported.
    SupportVirtualPayCodeEditsNot required

    You can configure the system to export virtual work codes in a schedule as paycodes. However, this configuration is not recommended because the resulting output contains duplicate paycodes.

    Example: Work codes are mapped to a paycode and the work codes are used in a shift assignment. Then, the schedule has duplicate paycodes.

    Note: Best practice: Instead, use shift segments with work-rule transfers. But if your system is configured with virtual work codes, and reconfiguration is impractical, set the SupportVirtualPayCodeEdits process property to remove the duplicate paycode edit records during schedule synchronization. This setting removes the duplications for the same persons, paycodes, start times, and durations.

    Default = false.

    To set this property to true, do the following:

    1. Clear Use Default.
    2. Select Value.
    NumberOfPeoplePerScheduleUpdateCallNot required

    The maximum number of people records that the schedule batch integration can import in a schedule-update API call.

    Default = 100.

    To change the maximum number of people:

    1. Clear Use Default.
    2. In Value, enter a whole number from 50 to 100 people.
    SupportPartialSuccessNot required

    When the schedule integration synchronizes schedules, and one record has errors, the schedule for that person is not synchronized. To prevent this, enable partial success which allows this integration to run with a status of Completed with Errors in the Run Summary.

    Default = false.

    To support partial success, do the following:

    1. Clear Use Default.
    2. Select Value.

    In Install Workforce Planner Integrations, set the SupportPartialSuccess parameter to true.

    Caution:

    This process property interacts with other settings and parameters as follows:

    • The SupportPartialSuccess process property has lowest precedence, and the SupportPartialSuccess parameter has the next lowest precedence.
    • You can leave the process property at the default value of false
    • If the Enable Batch Partial Success or Enable Low Latency Partial Success setting in Workforce Planner is selected, and the SupportPartialSuccess parameter is true, partial success is enabled.
    • If neither setting is selected, partial success is not enabled.
    • Partial success is available only for on-premises/KPC v7.5.2+ and Cloud.
    _addExtraDetailsInRunSummaryForLoggingNot required

    For the low-latency schedule import integrations, enable this property to show the following information in the Run Summary so that you can track the data flow of integration runs:

    • ScheduleUpdateResponse
    • ScheduleUpdateRequest
    • WFTSScheduleMultiReadResponse
    • ScheduleSearchResponse
    • SignedOffResponse
    • LockedDaysResponse

    Note: The Run Summary can show a maximum of 1 MB of data .

    Default = false.

    To show the data-flow details in the Run Summary, do the following:

    1. Clear User Default.
    2. Select Value.
    _addWFDCommentsInRunSummaryForLoggingNot required

    For the low-latency schedule import integrations, enable this property to show the comment data (WFDCommentsResponse) in the Run Summary in addition to the data-flow information shown by the _addExtraDetailsInRunSummaryForLogging process property.

    Default = false.

    To show the comment data in the Run Summary, do the following:

    1. The _addExtraDetailsInRunSummaryForLogging process property must be set to true.
    2. Clear User Default.
    3. Select Value.
    PayloadChangeForBetterPerformanceNot required

    To improve performance, enable this property to group and process shifts, paycode edits, and schedule tags A graphic on the schedule that identifies a specific characteristic that applies to a specific employee on a specific day. Not a shift or a pay code. Example: On call. in a single block rather than for each person.

    Note: The Enable Partial Success and Retry Batch Schedule Event on Operation Timeout process properties also must be enabled.

    Default = false.

    To enable this property:

    1. Clear Use Default.
    2. Select Value.