Configure the TeleStaff Schedule Import Integration

How to configure connection settings and process properties for this integration.

This topic describes how to configure this integration.

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

This is an API-based integration pack that imports schedule data from TeleStaff; 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 Task Manager in TeleStaff 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 TeleStaff. These events include shift trades, swaps, time-off, back fill, or extra duty.

Before you start

Before you start to configure the TeleStaff Schedule Import integration.
  1. Configure adjustment and combination rules.
  2. In TeleStaff, configure work codes and categories, employee categories, tag references to schedule and segment tags, schedule and segment tags, no pay segment tag, securities, and access. See Configure TeleStaff for Integrations.

Configure the integration

How to configure this integration.

Select the environment

How to select the environment for 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.

Select environment extensions

How to select environment extensions for the TeleStaff Schedule Import integration.
  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: TeleStaff Schedule Batch Import > WFTSScheduleImport-Batch-v1
    • Schedule: TeleStaff Schedule Import > WFTSScheduleImport-v1

Configure process properties

How to configure process properties for the TeleStaff Schedule Import integration.
  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 WFTSAPIErrorHandlerProperties 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 TeleStaff 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

    Process Properties for the TeleStaff Schedule Import Integration

    Property

    Required

    Actions

    FromDate

    Not required

    Start date to synchronize the schedule data.

    ThruDate

    Not required

    Default = false, synchronize shifts (working time) and paycode edits (non-working time).

    PayCodeEditsOnly

    Not required

    Default = false, synchronize shifts (working time) and paycode edits (non-working time).

    AdjustToCalendarDay

    Not required

    TeleStaff 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 this property to true. This creates a virtual shift segment 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.

    NoPaySegmentTag

    Not 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 TeleStaff Integrations > Configure a Dimensions tag.

    MergeAdjacentShifts

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

    DayDivide

    Not required

    Default = 0

    The virtual shift segment starts from the day divide 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.

    AtwFromDate

    Not required

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

    • No default value is assigned to this property.

    • You do not define the value of this property because it is imported.

    AtwThruDate

    Not required

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

    • No default value is assigned to this property.

    • You do not define the value of this property because it is imported.

    SupportVirtualPayCodeEdits

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

    NumberOfPeoplePerScheduleUpdateCall

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

    SupportPartialSuccess

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

    _addWFDCommentsInRunSummaryForLogging

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

    PayloadChangeForBetterPerformance

    Not required

    To improve performance, enable this property to group and process shifts, paycode edits, and schedule tags 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 User Default.

    2. Select Value.