Vacation Summary Import File

At a Glance

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

File type: XML

Vacation Summary data import files allow you to import agent vacation or time off items into IEX WFM Integrated. This is helpful if you have a third-party system, such as a human resources database, from which you want to extract information about agents' vacation or PTO times. Using Vacation Summary import files can also help reduce data entry time to define agents during the initial setup of a new IEX WFM Integrated system.

Key Facts about Vacation Summary Import Data Files

Records in the data file may be sorted in any order.
Follow the general XML specifications for file contents and XML best practices.
Each file must contain the elements described in the Document Type Definition and meet the criteria described in this section.
Element tags are case-sensitive.
Date and time elements should use your IEX WFM Integrated time zone.
Field length for all entity names and user-defined data items is 64 characters unless otherwise noted.
Limit file names to 30 characters.
Maximum file size is 5 MB.
All numbers must be integers. Decimal values are not supported.
Some elements used in Vacation Summary data 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.

Earnings Types

Earnings type information is not included in Vacation Summary data import files. To account for Earnings types, data import adds each agent's earned values for activity codes that belong to the same earnings type. The total earned value is stored as the earnings type's earned value.

At Classics, Inc., vacation and personal time both belong to the PTO earnings type. Minnie May Barry currently has 48 hours of PTO. If the Vacation Summary data file includes 40 hours of Vacation and 16 hours of Personal Time for Minnie May, her PTO time in IEX WFM Integrated will be 56 hours after the import completes.

To import time off information for any code (including Wait List), the code must be assigned an earnings type. If a code does not have an earnings type, the import will fail.

General Processing Information

Data import clears the existing value in the IEX WFM Integrated database with when an element:

Contains a blank value.
Is omitted from the Vacation Summary import file.

If the Vacation Summary import file contains a record that has no corresponding record in the IEX WFM Integrated database, data import creates a record in the database. It adds the data contained in the import file to the record, including the agent, vacation group, vacation year, and vacation type.

If the Vacation Summary import file contains a record that already exists in the IEX WFM Integrated database, data import overwrites the record. If a child of the vacation element is omitted from the import file, data import does not modify the existing record. The vacYear element must be a time off rule with a calculation unit of HH:MM. data import doesn't support time off rules with a calculation unit of Days.

Vacation Summary 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 agentVacationSummary (agentVacation+)>
 
<!ELEMENT agentVacation (agent, vacation+)>
 
<!ELEMENT agent (agentID, vacGroup, vacYear)>
<!ELEMENT vacation (from?, to?, earned?, credited?, debited?, selected?, taken?, minFullWeeks?, maxPartialHours?, coFrom?, coTo?)>
 
<!ELEMENT agentID (#PCDATA)>
<!ELEMENT vacGroup (#PCDATA)>
<!ELEMENT vacYear (#PCDATA)>
 
<!ELEMENT from (day, month, year)>
<!ELEMENT to (day, month, year)>
<!ELEMENT earned (#PCDATA)>
<!ELEMENT credited (#PCDATA)>
<!ELEMENT debited (#PCDATA)>
<!ELEMENT selected (#PCDATA)>
<!ELEMENT taken (#PCDATA)>
<!ELEMENT minFullWeeks (#PCDATA)>
<!ELEMENT maxPartialHours (#PCDATA)>
<!ELEMENT coFrom (#PCDATA)>
<!ELEMENT coTo (#PCDATA)>
 
<!ELEMENT day (#PCDATA)>
<!ELEMENT month (#PCDATA)>
<!ELEMENT year (#PCDATA)>
 
<!ATTLIST vacation type CDATA #REQUIRED>
<!ATTLIST agentID acdID CDATA #IMPLIED>

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 Vacation Summary import files. Use the Vacation Summary DTD as the template to structure the data in your import file. If an element can be edited in the IEX WFM Integrated user interface, the Descriptioncolumn references the IEX WFM Integrated screen where you can edit it.

Root Element

The root element is agentVacationSummary. This element must contain one or more agentVacation children.

Child Elements

Elements are indented based on their level in the DTD.

Element	Child Element or Attribute	Description	Valid Values
agentVacation		Contains all vacation information for a single agent for one time off group and time off rule. This element contains a single agent child and one or more vacation children. If you need to import information for an agent for multiple time off groups or time off rules, use separate agentVacation elements for each time off group or rule for that agent.
	agent	Must include an agentID, a vacGroup, and a vacYear.
	agentID	Identifier used to find the agent to be modified in IEX WFM Integrated. The value you use determines the requirements of the information that populates the agentID element. The default value is T. Can be edited on screen: Agent Definition.	S value: 64 alphanumeric characters T value: 1-999999999 A value: Any printable ASCII characters except \| & and \. Maximum length is 64. E value: Any printable ASCII characters except \| & and \. Maximum length is 256.
	acdID	Attribute of agentID. Data import matches the agentID to the agent in IEX WFM Integrated who is assigned to the specified acdID on the current date (based on the IEX WFM Integrated time zone). Can be edited on screen: Agent Definition.	1-2147483647
vacGroup		ID of the agent’s Time Off Group. A record must exist for the agent in AgentMap whose vac_group_id field matches this ID. Can be edited on screen: Agent Definition.	1-2147483647
vacYear		Name of the time off year for which the agent’s summary information is to be imported. A record must exist in VacYear whose vac_group_id matches the ID in the vacGroup element, and whose vac_year_name field matches the string in the vacYear element. The vacation year ID will not be specified in the import file. Must be a time off rule with a calculation unit of HH:MM. Data import does not support time off rules with a calculation unit of Days. Can be edited on screen: Time Off Rules.	Any string. A time off rule must be defined with this name for the Time Off Group
vacation		Contains all the agent’s vacation information for the specified vacGroup and vacYear. This element will have a type attribute to indicate the type of vacation being imported as well as the following optional child elements: from, to, earned, debited,credited, selected, taken, minFullWeeks, maxPartialHours, coFrom and coTo.
	type	Attribute of the vacation element. Description of the activity code for which the VacSummary record will be added or updated. If this string is Wait List, the VacSummary record with code -1 will be updated or added. Otherwise, a record must exist in the Except table whose Description matches this string (case is sensitive) and a record must exist in VacType for the specified vacGroup and vacYear for this activity code. Can be edited on screen: Time Off Rules.	Any printable ASCII character except \| and \. Case-sensitive
	from	Earliest date for which the agent may make requests for this type of vacation. Must be a valid date, using day, month, and year children. Must fall between the vacation year’s start and end dates and must be on or before the specified to date (or the existing record’s toDate if the to element is excluded). This date will be stored in the fromDate field in VacSummary. Can be edited on screen: Agent Time Off Summary.
	day	Day of the from element.	1-31
	month	Month of the from element.	1-12
	year	Year of the from element.	Any year
	to	Latest date for which the agent may make requests for this type of vacation. Must be a valid date, using day, month, and yearchildren. Must fall between the vacation year’s start and end dates and must be on or after the specified from date (or the existing record’s fromDate if the from element is excluded). This date will be stored in the toDate field in VacSummary. Can be edited on screen: Agent Time Off Summary
	day	Day of the to element.	1-31
	month	Month of the to element.	1-12
	year	Year of the to element.	Any year
	earned	Amount of time, in minutes, the agent has earned for the vacation type in the vacation year. This value will be stored in the Earned field in VacSummary. Can be edited on screen: Agent Time Off Summary	0-479520 (999 8-hour days)
	credited	Amount of credited time, in minutes for the vacation type. This value will be stored in the credited field in VacSummary. Credited time is added to the agent’s earned time in the Time Off Manger. Can be edited on screen: Agent Time Off Summary	0-479520 (999 8-hour days)
	debited	Amount of debited time, in minutes for the vacation type. This value will be stored in the previouslyUsed field in VacSummary. Debited time is counted as taken time in Time Off Manager. Can be edited on screen: Agent Time Off Summary	0-479520 (999 8-hour days)
	selected	Not imported. It is based on future activities entered in IEX WFM Integrated.
	taken	Not imported. It is based on schedules in IEX WFM Integrated.
	minFullWeeks	Minimum number of weeks the agent is required to take in full week increments. Can be edited on screen: Agent Time Off Summary	0-78
	maxPartialHours	Maximum amount of time the agent may take in partial day increments.If agents are allowed to take all their time off in partial day increments, this value should be the same as the earned value. Can be edited on screen: Agent Time Off Summary	Must be less than or equal to the record’s earned value.
	coFrom	Amount of time, in minutes, the agent carried over from the previous year for the vacation type. This value will be stored in the coFromLastYr field in VacSummary. Can be edited on screen: Agent Time Off Summary	0-479520 (999 8-hour days)
	coTo	Amount of time, in minutes, the agent carried over into the next year for the vacation type. This value will be stored in the coToNextYr field in VacSummary. Can be edited on screen: Agent Time Off Summary	0-479520 (999 8-hour days)

Sample Import File

<?xml version="1.0" encoding="UTF-8" ?>
<agentVacationSummary>
  <agentVacation>
    <agent>
      <agentID>270</agentID>
      <vacGroup>10</vacGroup>
      <vacYear>2007</vacYear>
    </agent>
    <vacation type=”PTO”>
      <earned>2400</earned>
    </vacation>
    <vacation type=”Personal Time”>
      <earned>960</earned>
    </vacation>
    <vacation type=”Wait List”>
         <earned>2400</earned>
      </vacation>
   </agentVacation>
   <agentVacation>
      <agent>
         <agentID>275</agentID>
         <vacGroup>10</vacGroup>
         <vacYear>2007</vacYear>
      </agent>
      <vacation type=”PTO”>
      <from>
            <day>1</day> <month>1</month> <year>2007</year>
         </from>
         <to>
            day>29</day> <month>3</month><year>2008</year>
         </to>
            <earned>2400</earned>
         <credited>480</credited>
         <debited>0</debited>
         <coFrom>1440</coFrom>
         <coTo>0</coTo>
      </vacation>
      <vacation type=”Personal Time”>
         <from>
            <day>1</day> <month>1</month>< year>2007</year>
         </from>
         <to>
            <day>29</day>
            <month>3</month>
            <year>2008</year>
         </to>
         <earned>0</earned>
         <credited>0</credited>
         <debited>0</debited>
         <coFrom>0</coFrom>
         <coTo>0</coTo>
      </vacation>
      <vacation type=”Wait List”>
         <from>
            <day>1</day> <month>1</month> <year>2007</year>
         </from>
         <to>
            <day>29</day> <month>3</month> <year>2008</year>
         </to>
         <earned>3360</earned>
         <credited>0</credited>
         <debited>0</debited>
         <coFrom>0</coFrom>
         <coTo>0</coTo>
      </vacation>
   </agentVacation>
</agentVacationSummary>