Schedule Changes Import File

At a Glance

File name: ScheduleChanges-[YYMMDD][HHMM].xml, where [YYMMDD] is the date in YYMMDD format, and [HHMM] is the time in HHMM format.

File type: XML

Schedule Changes import data files allow you to update agent schedules in IEX WFM Integrated. You can also add to or overwrite an existing schedule, create or delete Future Activity records, or delete Schedule Event records. The schedule changes can come from an IVR system, a web browser, a third-party platform, and so on.

Key Facts about Schedule Changes Data Import Files

• Use the Schedule Changes Document Type Definition and follow standard XML best practices.

• Update agent schedules by adding an Activity Code for the specified date and time.

• Date and time elements should use the agent’s MU time zone.

• Some elements used in Schedule Changes import files have legacy names.

• If errors occur during file processing, the data may not import properly. Check file formatting before contacting your IEX WFM Integrated account representative.

• File names must be 30 or fewer characters.

• StopTime can be earlier than StartTime. This happens when the time range crosses midnight. The time range from midnight to the StopTime applies to the schedule indicated by the [StartTime].

  Anne Shirley, an agent at Classics Inc., works from 20:00 on Wednesday to 6:00 on Thursday. There is a record for her with a time range of 01:00 - 03:00 on Thursday. Even though the 01:00 - 03:00 time range occurred on Thursday, it is applied to the schedule with the Wednesday date.

  Jane Andrews was not scheduled to work on Monday. She was scheduled on Tuesday from 3:00 until 12:00. Jane agreed to cover part of Gilbert Blythe's shift, so she came in early and worked from 23:00 on Monday until 05:00 on Tuesday when she logged out for a break. This means she has a record with Monday's date for the time range of 23:00 to 05:00. This record will not be processed. The record date is Monday, so this time range would only apply to a Monday schedule. Because Jane was not scheduled on Monday, there is no Monday record for this range to apply to.

Activity Code Mapping

You must map a schedule event in a Schedule Changes data file to an activity code attribute in IEX WFM Integrated. Doing this allows data import to apply schedule events to the right activity code in IEX WFM Integrated.

1. Define an activity code attribute in IEX WFM Integrated.

   1. In Administrator, click Activity Code Attributes.

   2. Create an Activity Code Attribute for each customer partition on each IEX WFM Integrated server.  You can name the activity code attribute SchedExImport or you can use a custom name.
   3. For each schedule event included in the import file, add an Attribute Value to the Activity Code Attribute you created. For example, if the import file has scheduled events that are trainings, meetings, and vacation, you would add values of Training, Meeting, and Vacation. Do not assign a value for the Unscheduled activity code.

2. Assign attribute values to activity codes in IEX WFM Integrated.

   1. In Administrator, click Attribute Assignment.
   2. Select one Activity Code for each attribute value that you defined.

Activity Type

IEX WFM Integrated determines which icon to display for an imported future activity based on activity type. It determines activity type as follows:

• Partial Day: If both starttime and endtime are provided and the otcreatesched field or element is omitted.

• Partial Day Sched Start: If the endtime is provided and the starttime is not provided.

• Partial Day Sched End: If the starttime is provided and the endtime is not provided.

• All Day: If both starttime and endtime are not provided.

• OT Partial Day: If both starttime and endtime are provided and the otcreatesched field is present.

• OT Before Schedule: Not supported.

• OT After Schedule: Not supported.

General Processing Information

Start and Stop Times

StartTime and EndTime are optional.

• If StartTime is omitted, the activity is applied from the start of the schedule up to the provided EndTime.

• If EndTime is omitted, the activity is applied from the indicated StartTime until the end of the schedule.

• If both StartTime and EndTime are omitted, the exception is applied to the entire schedule for the provided Date. Activity Code priorities are still honored.

When start or stop times in the imported record fall partially outside of the agent's scheduled start and stop time range, only the portion of the record that overlaps the existing scheduled time is processed.

When start or stop times in the imported record fall completely outside of the agent's scheduled start and stop time range, the record is not processed.

IEX WFM Integrated uses the presence or absence of start and stop times to determine each record's activity type.

Activity Code Priorities

Data import honors activity code priorities. It overwrites equal- and lower-priority activities, but not higher-priority activities. This processing differs from the Apply Future Activities processing method. That method reverts to an internal ID as the tie-breaker when attempting to overwrite an activity with an equal-priority activity.

Partial records will be applied. For example, if the record indicates a Tardy activity from 8:00 to 10:00 in the morning, but a higher-priority activity already exists from 9:00 -10:00, only 8:00 - 9:00 is overwritten with the Tardy activity.

Shortening or Extending  Records

Schedules cannot be shortened or extended when records contain an Unscheduled activity. If a data file contains records that would shorten or extend the schedule with an Unscheduled activity, data import does not apply the record. Other activities, such as Time Off or Meeting will shorten or extend a schedule.

Data import does not create schedules on days where schedules don't exist for an agent's MU. If the date of a record is not within the valid schedule range for the MU associated with the agent in that record, data import does not process the record.

Agent Does Not Have Schedule for Specified Date

If an agent does not have a schedule for the specified date, data import does not process the record. 

Special Processing for Open and Unscheduled Activities

Open and Unscheduled activities require special processing. This refers to the predefined Open activity code, not to activities with the open attribute. Unscheduled activities indicate the absence of an activity.

As long an import record is valid, data import creates Future Activity records for all activities in the import record. It creates them even if an activity contained in the record cannot be added to the agent's schedule. Activities can be valid but data import is not able to import them due to reasons such as the agent not having a schedule for the time range listed in the activity or because the existing activity has a higher priority than the imported one.

Elements in Future Activity Records

The following elements are specific to Future Activity records. They do not affect any changes made to schedules unless otherwise noted. These elements are optional.

• modifiedBy
• note (you can use note for schedule changes as well as future activities)
• otcreatesched
• requestedBy
• timeRequested
• vacationGroup

• vacationYear

Vacation Future Activities

The vacationGroup or vacationYear elements must appear in records together. If you use one, you must include the other as well. If you include only one of these elements, data import will not process the record.

A vacation Future Activity cannot also be an overtime activity. If the vacationGroup and vacationYear elements are included in a record together with otcreatesched, data import will not create the Future Activity record.

When data import creates or deletes a Future Activity record that contains vacationGroup and vacationYear, it automatically updates the Vacation Bidding screen.

Delete Schedule Event and Future Activity Records

You can only delete schedule events and future activities when you use in pipe-delimited files. Include the delete field in the record you want to delete.

Schedule Event Records

When data import deletes a schedule event, it replaces the activity code specified in the imported record with the base schedule code. The activity code must exist on the agent's schedule for the delete to work. The activity can be present during any part of the specified time range. The time when the base schedule code is placed on the agent's schedule will not necessarily be the exact time range specified in the import record.

Future Activity Records

Data import will delete Future Activity records if all of these conditions are met: 

• You include the delete element in an import file for a future activity.
• The Future Activity record exists for the agent and the activity code for the exact time range specified in the import record.

If one or more of these conditions isn't met, or if data import doesn't find an exact match for the import record, data import will not delete any Future Activity records. When determining if a record is an exact match, data import uses these criteria: 

• The otcreatesched element does not have to match the Future Activity record's Overtime Create Schedule setting for the future activity to be deleted.

• If a Future Activity import record does not have a specified starttime, data import will consider an existing Future Activity record as an exact match if it doesn't have a defined Start Time setting.

• If a Future Activity import record does not have a specified endtime, data import will consider an existing Future Activity as an exact match if it doesn't have a defined End Time setting.

View Imported Future Activity Records

You can view imported Future Activity records on the Agent Future Activity screen. When viewing records, note that: 

• The icon is determined by the Exception Code that IEX WFM Integrated maps the imported record to, using the Exception Code Attribute you specify.

• The activity Type is determined by the combination of starttime, endtime, and otcreatesched elements.

• For the Start Date and End Date fields, the date can cross midnight if you imported the record using a pipe-delimited file.

• The Overtime Length, Overtime Offset, and Overtime Limit fields will be empty.

• The Overtime Create Schedule field will be enabled if starttime and endtime are provided, and the otcreatesched element is present.

Lock File for Unprocessed Import Records

Data import creates a lock file in the same directory as the input file and copies records that it could not process due to locked tables into the lock file. It attempts to process the records in the lock file until the it reaches timeout time. The default timeout is 120 minutes.

The lock file has the same name as the original import file, but the extension is LCK. The contents of the file are the same as in the original file, except that it contains only those records that data import was not able to process. The lock file is always in XML format, even if the original file was in pipe-delimited format.

Document Type Definition

The Document Type Definition (DTD) is a template for building XML import files. You do not need to create a DTD in your environment.

<?xml version="1.0" encoding="UTF-8" ?>
<!ELEMENT agentScheduleList (agent+)>
<!ELEMENT agent (id, schedule)>
<!ELEMENT schedule (schedid?, day, month, year, (exception+ | offexception))>
<!ELEMENT exception (startdate, starttime?, endtime?, code, vacationGroup?, vacationYear?, note?, agentAllowedViewNote?,
modifiedBy?, requestedBy?, timeRequested?, delete?, otcreatesched?)>
<!ELEMENT offexception EMPTY>
<!ELEMENT startdate (day, month, year)>
<!ELEMENT starttime (hour, min)>
<!ELEMENT endtime (hour, min)>
<!ELEMENT id (#PCDATA)>
<!ELEMENT schedid (#PCDATA)>
<!ELEMENT code (#PCDATA)>
<!ELEMENT vacationGroup (#PCDATA)>
<!ELEMENT vacationYear (#PCDATA)>
<!ELEMENT note (#PCDATA)>
<!ELEMENT agentAllowedViewNote (#PCDATA)>
<!ELEMENT modifiedBy (#PCDATA)>
<!ELEMENT requestedBy (#PCDATA)>
<!ELEMENT timeRequested (day, month, year, hour, min)>
<!ELEMENT delete EMPTY>
<!ELEMENT otcreatesched EMPTY>
<!ELEMENT day (#PCDATA)>
<!ELEMENT month (#PCDATA)>
<!ELEMENT year (#PCDATA)>
<!ELEMENT hour (#PCDATA)>
<!ELEMENT min (#PCDATA)>

DTD Element Type Considerations

When using the Document Type Definition (DTD) to create a file, keep in mind these considerations about element type declarations: 

<!ELEMENT elementName (childElement, childElement, ...)>

When an element is defined with a list of child elements separated by commas, the children must appear in the same order in the import file. Otherwise, the element will not be valid.

<!ELEMENT elementName (#PCDATA)>

Elements with the #PCDATA type may contain any text string. Data import validates the text as necessary.

Attribute Qualifiers

The DTD uses standard XML element qualifiers:

• ?—Elements with this qualifier are not required. If you include them, you can only specify them one time per element.
• *—Elements with this qualifier are not required. You can include more than one of these for each element.
• +—At least one of the elements with this qualifier is required. You can include more than one of each element.
• [no qualifier]—Elements not marked with a qualifier are required and you can only be specify them one time per element.

File Contents: Field Specifications

This section includes all elements for use in muOpens import files. Use the schedule change DTD as the template to structure the data in your import file.

Root Element

The root element is agentScheduleList. This element can contain zero or more agent children.

Child Elements

Elements are indented based on their level in the DTD.