Appendix B
Creating a Source Extractor
Microsoft Exchange Server provides source extractors for many popular systems. If a source extractor for your system does not exist, you can create one to copy information from your system to migration files.
A source extractor can export directory information, mailboxes, personal address book (PAB) entries, personal distribution lists, mail messages, attachments, calendar data, and public information. You can then use the Migration Wizard to import the information to Microsoft Exchange Server. A source extractor must create the following three types of migration files:
Packing list file
Lists primary and secondary files and specifies the code-page for all migration files.
Primary files
Contain directory information, message headers, personal address book entries, personal distribution lists, and pointers to secondary files.
Secondary files
Contain blocks of data, such as message bodies, attachments, and schedule data.

The following figure shows the relationships between the migration files.
	
Each migration file contains one or more types of objects, as described in the following table.
Objects	Purpose	
		
Custom recipient addresses	Creates custom recipients.	
Mailbox names	Creates mailboxes, replacing custom recipients when correctly configured.	
Mailbox data	Imports messages into the Microsoft Exchange Server mailbox.	
PAB data	Imported as a message in the Inbox for users to re-create their personal address book entries.	
Public data	Creates public folders, imports data, and assigns the current administrator as owner.	
Scheduling data	Creates a schedule file, attaches the file to a message, and imports the message.	

Creating and using a source extractor involves the following activities:
	Designing your source extractor
	Formatting the migration files
	Editing the migration files
	Troubleshooting errors

Designing Your Source Extractor
You must consider many issues when designing your source extractor. For example, ideally your source extractor will extract a reasonable amount of data overnight. Also, if you have international users, the source extractor should be easy to localize and should include appropriate code-pages. You should also consider these questions:
	What level of sophistication is required to install and configure the source extractor?
	Does a user-driven source extractor make sense? 
	Where are the files going to be edited after export and before import? 
	How will the files be transferred from the extract location to the import location? 
	Will file transfer modify the files?
	Is the existing system going to be in use? 

Also consider the following additional issues when creating your source extractor:
Existing data
If possible, copy, don’t move, the data from your existing system, so that you will have an additional copy of the data.
Group migration
If your existing system has account information in the directory, select accounts to migrate by department or location.
Permissions
Administrator or user authentication should be required to copy data from the source system.
Primary mailbox files
Mailbox files need to be edited if you’re changing the directory name. It is best to put all the directory entries into one primary file. 
Mailbox names
You cannot change the common or directory name of a mailbox after you create it. If you have a new naming convention, modify every primary file that contains mailbox creation information, or modify the source extractor to select the new directory names from a file.
You should also consider each of the following issues:
	Choosing the addressing conventions
	Choosing information to extract
	Configuring command-line options
	Configuring special features

Choosing the Addressing Conventions
The Migration Wizard can use three different types of addresses:
Display Name
The display name is the friendly name of a recipient. Source extractors should convert message recipients, senders, and appointment attendees to display names. The Microsoft Exchange Client compares the display name with personal and global address book entries. If it cannot find a match, it displays possible matches for the user to select from.
E-mail Address
Source extractors use unique identifiers to relate each mailbox or custom recipient in the existing system to each mailbox or custom recipient in Microsoft Exchange Server. These identifiers are known as source e-mail addresses and are stored in the following format: Migrate:TYPE:address.
This address is created in the directory section of the primary file and must be in a column with a header of secondary-proxy-addresses. You can remove the Migrate e-mail addresses after migration is complete.
E-mail addresses are also used for personal address book (PAB) entries. By default, the following address types are valid: MS, MSA, X400, and SMTP. Other gateway address types can be made available. Microsoft Exchange Server defines an address for a foreign system recipient in this format: TYPE:address. For example: SMTP:alig@eur.fab.com. When extracting addresses from foreign systems, your source extractor must create a target address, or extract the address as a direct address.
Also consider these PAB addressing issues:
	Do you remove addresses from mailboxes on the existing system? 
	Do you change the display name to include the address? 
	Do you change the addresses to route mail to the appropriate gateway?

Display Name with E-mail Address
The source extractor can use display names with e-mail addresses. Use this format only for addresses not in the Microsoft Exchange Server global address list. For example: Allison Klein[SMTP:AKlein@eur.fab.com].
Choosing Information to Extract
When planning your migration, consider which data to extract. For example, you may or may not want to extract schedule and calendar features or personal distribution lists. You may want to limit the extraction to certain ranges of data. For example, you could impose an age limit on mail. Also consider special issues related to extracting the following information:
Personal address books (PABs)
If users can create their own directory entries in PABs on your existing system, you can extract the information. If the administrator cannot access PABs, consider how users will migrate this data. You can have users compose messages to all their PAB entries, type their own names in the Copy To (Cc) fields, and send the messages before their mailboxes are moved. The messages are then migrated to Microsoft Exchange Server, where users can open the messages and add the recipients to the new PABs.
Attributes
Some existing systems have additional data about each account stored in their directory — title or department, for example. Extract this information as part of migration, or import it separately by using the Directory Import command in the Administrator program.
Attachments
Is the attachment useful after being migrated? Attachments that require an application on a host system may no longer be useful in their current format. Do any attachments need to be converted before being added to the migration file?
Configuring Command-Line Options
For automation, compatibility, and ease of use, configure the source extractor to support the following command-line options:
	Batch control file
	Accounts file
	Administrator account and password

 If the operating system of the source extractor does not support command-line options, you can design the source extractor to find batch control and accounts files with default names.
The batch control file has one required variable: the accounts file. Some optional variables are detailed in the following table. Depending on your existing system, some of these variables may be required, and others will be useful.

Variable	
Description	Suggested default value	
			
Accounts (Required)	Path and file name of the accounts file. 		
File	Path and file name of the packing list file to be created.		
Mailbox	Mailbox creation information.	TRUE	
Email	Private messages from the accounts.	TRUE	
Remote	Custom recipient information.	FALSE	
Public	Public messages and bulletin board information, if supported.	TRUE	
PAB	Personal address book entries and distribution lists.	TRUE	
Schedule	Schedule and appointment data.	TRUE	
EmailStart	Earliest date to retrieve messages. Migration file date/time format. Required if using EmailEnd.		
EmailEnd	End date to retrieve messages. Migration file date/time format. Required if using EmailStart.		
SchedStart	Earliest date to retrieve appointments. Migration file date/time format. Required if using SchedEnd. 		
SchedEnd	End date to retrieve appointments. Migration file date/time format. Required if using SchedStart. 		

The order of variables in the batch control file is not important. Mailbox and Remote are mutually exclusive. Each variable has its own line, followed by a comma and the value for that variable. Each line ends in a line feed and carriage return. The following examples illustrate the correct format.
Example of a control file that doesn't migrate schedule information and limits e-mail messages to a date range:
Schedule,FALSE
EmailEnd,19950323000000
Accounts,C:\PO7User2.txt
EmailStart,19940413171900

Example of a control file that limits schedule data, but imports all e-mail messages:
Accounts,M:\migrate\batch\user.txt
SchedStart,19940101000000
SchedEnd,19970101000000
LogLevel,Verbose
Public,FALSE

The accounts file specifies the mailboxes or accounts from which to copy data. It is useful when running in batch mode or when migrating many users. The accounts are listed by their source addresses or by a unique identifier. Each accounts file should contain accounts from only one system, postoffice, or server. The following example illustrates the correct format:
Stephanie Bourne
Karl Buhl
Paul Canniff

Configuring Special Features
You may want to configure your source extractor to perform certain activities. For example, it is advisable to configure both an error log and online Help, which can help troubleshoot problems. Also consider configuring the following features:
Mail forwarding   You can configure the source extractor to forward mail, depending on your existing system’s features.
Special migration folder
If you configure this folder, only messages in the folder and in the Inbox are migrated. 
Status file
To prevent a mailbox’s contents from being imported twice, configure your source extractor to keep a log of migrated users.
Last message configuration
This message informs users that their new mailboxes are available and tells them not to use the old mailboxes anymore.
Formatting the Migration Files
The packing list, primary, and secondary files share some common formatting rules, which help you quickly parse migration files. The packing list and primary files use comma-separated value (CSV) format. The secondary files use CSV format for header information, but raw data uses its own format. This allows you to edit the primary file, regardless of the source of the data.
You should use the file extension .PKL for packing list files, .PRI for primary files, and .SEC for secondary files. If you have multiple primary or secondary files, give similar root names to similar files. For example, you could use the names of postoffices or servers, appended with numbers. 
All files must be in the same directory as the packing list file. Names of secondary files cannot contain any of the following characters: 
# ( ) ; , \ / : * ? " < > |
Rules for Field Entries
Field entries are governed by various rules. Fields that contain any of the following characters must be enclosed in quotation marks:
# ! , \ " % .
The entire entry must be enclosed in quotation marks, not just the embedded character. The following two examples show how the entries should appear in the primary or secondary files.
Entry	Appearance in file	
		
Lee, Bill	"Lee, Bill"  	
my name is "Sherry"  	"my name is ""Sherry"""	

In the second example, two quotes represent a single quote, and the last quote shows that the entire entry is quoted. 
Any fields in a directory section of the primary file that have a backslash (\) character need to have a second \ character in addition to being enclosed in quotation marks.
For multivalued fields, such as distribution list members or e-mail addresses, each value can be quoted, but delimiters cannot be within quotes. In the following example, the semicolon (;) delimiter is not inside quotes.
"Jim_Hance@NorthWind";"Stephen Gray@NorthWind"
The following table lists other entries and their accompanying rules.
Entry	Rule	
		
Spaces	No extra spaces at the beginning of a line, or before or after field-delimiting commas, unless part of the data to be migrated.	
End of line	Each line of data ends with a carriage return and line feed.	
Blank lines	Must consist only of a carriage return and line feed. They will be ignored.	
Comment lines	Begin with an exclamation point (!). Comment lines are useful for storing information, such as when the data was extracted and what parameters were set for extracting the data.	
Continuation character	If system supports a limited number of columns in a file, use a double backslash (\\), followed by a carriage return and line feed. It will be placed anywhere in a primary file, and it signals that the next line in the file must be appended to the current line. Line continuations will not work within comments, inside quotation marks, directory sections of primary files, or secondary files.	
Code-page	No default code-page. Files can be in any code-page supported by Microsoft Windows NT Server. Only one code-page for each set of primary and secondary files. You must specify the code-page on the first line of the packing list file. UNICODE is not supported as a valid code-page.	
Case sensitivity	Header lines and parsing text are not case sensitive.	
Dates, times, and durations	Represented by 14-digit numbers: first 4 digits = year, second 2 digits = month, third 2 digits = day, fourth 4 digits = time on a 24-hour clock, fifth 2 digits = seconds. For example, May 1, 1995, at 10:00:05 P.M. = 19950501220005. One year, 4 months, 3 days, 22 hours, and 2 seconds = 00010403220002. (Local times, not Greenwich Mean Time.)	
Carriage returns without line feeds	Converts to carriage returns with line feeds. When you move the migration file from the source system to Windows NT Server, the conversion is likely to add line feeds, which may be unacceptable. 	

Formatting the Packing List File 
The packing list file reports the code-page in which the files are stored and lists all primary and secondary files. The first bytes of the packing list file specify the standard code-page number used in all of the primary and secondary files. The code-page number is on a line by itself and is followed by a blank line. The following sample packing list file illustrates the format:
850

Filename,Filetype
SALESPO1.PRI,Primary
SALESPO1.SEC,Secondary
SALESPO2.SEC,Secondary

The code-page number in this example is 850. The suggested code pages are 850 and 1252, but the code page that you use depends on your existing system, file transfer to the Microsoft Exchange Server, and the languages supported. 
Formatting the Primary Files
The primary files contain one or more sections. Each section contains one of the following types of data:
Directory information
Each line of data can create or modify any mailbox, custom recipient, or distribution list in the Microsoft Exchange Server directory. The data is in directory import format. For more information on the Directory Import command, see Chapter 3.
PAB entries and personal distribution lists
Each line of data creates a PAB or personal distribution list entry. There is one section for each mailbox. A mailbox must be created before entering this data. 
Messages and public folders
Each line of data creates a message or an item in a mailbox or public folder. Each section holds entries for one mailbox or for any number of public folders. Sections must be separated by a blank line. Messages can be imported to create a mailbox.
Each line of data has one or more comma-separated values (CSVs). If any of these values has a carriage return or line feed character, put it into a secondary file. (The same parsing rules apply in the secondary file: strings with special characters need to be in quotes.) 
Replace the value with a pointer to the secondary file and an offset to where the header of the data begins. For example:  #SALESPO2.SEC(43232). The # sign indicates that the data is stored in another file, the SALESPO2.SEC secondary file. The data is located 43232 bytes from the beginning of that file, and this offset counts end-of-line characters such as carriage returns and line feeds.

Note
It is important that transfering the secondary files from another platform or system does not introduce new characters. If this happens, the offsets in the primary file could be inaccurate.

Directory Information
Each directory import section of the primary file begins with DIRECTORY. This is followed by a header line. Each line thereafter is one object. For example:
DIRECTORY
Obj-class,Mode,Common-Name,Display-Name,Last Name,First Name,Secondary-Proxy-Addresses,Home-Server
mailbox,create,ElizaB,Elizabeth Brown,Brown,ElizabethMIGRATE:PROFS:Sydney(EBrown),~Server
mailbox,create,PatPa;Pat Parkes,Parkes,Pat,MIGRATE:PROFS:Sydney(PParkes),~Server
mailbox,create,MiguelF,Miguel Fernandez,Fernandex,MiguelMIGRATE:PROFS:Sydney(MFernan),~Server

Important
Items in the directory section cannot have pointers to data in the secondary file. All data in the directory section must be in the primary file.

The format of the directory import section in the primary file is slightly different from Directory Import in the Administrator program. In the primary file the mode header field is required and must always be set to create. If the object already exists, an error will be reported. In the Administrator program, the mode header field is optional and can be set to create, modify, or delete. For information on additional attributes, see Appendix D.
PAB Entries and Personal Distribution Lists
You can enter new PAB or personal distribution list data or you can move existing data into the migration file. The following example illustrates the formatting of each PAB data section:
PAB,migrate:PROFS:SANFRN(HOWARDS)
Obj-class,Display-Name,Email-Address,First,Last,Address,City,\\
State,Zip,Country,Title,Company,Department,Office,Assistant,\\
Bus-Num,Bus2-Num,Assist-Num,Fax-Num,Home-Num,Home2-Num,\\
Mobile-Num,Pager-Num,Note
entry,Pat Parkes,SMTP:patp@Litware.com,Pat,Parkes,,,,\\
,,,"Litware, Inc.",,,,,,,,4155551212,,,,
entry,Dad,X400:cn=ronar;p=NWTraders;a= ;c=JP,,,,,,,,,,,,,,,,,,,,
dl,My Friends,Dad;Pat Parkes,,,,,,,,,,,,,,,,,,,,,\\
Personal Distribution List of my friends

The following table describes the fields in the header line. Only the first three fields (Obj-class, Display-Name, and Email-Address) are required, but the header line must have all the fields in the order shown. Only the first three fields and the Note heading are valid for personal distribution lists. 
Heading	Description	
		
Obj-class  (Required) 	Describes the type of entry. For a single recipient, entry. For personal distribution lists, dl.	
Display-Name  (Required)    	Friendly name.	
Email-Address (Required)
	E-mail address or addresses. For personal distribution lists, use a semi-colon to separate addresses. (If the source system doesn’t support this information, put in the invalid data:  USER: Display-Name)	
First	Given name.	
Last	Surname.	
Address	Street address.	
City	City name.	
State	State or province.	
Zip	Zip or postal code.	
Country	Recipient’s country.	
Title	Position in the company.	
Company	Company name.	
Department	Department name or number.	
Office	Office location.	
Assistant	Assistant’s name.	
Bus-Num	Primary business telephone number.	
Bus2-Num	Secondary business telephone number.	
Assist-Num	Telephone number of the recipient’s assistant.	
Fax-Num	Fax number.	
Home-Num	Primary home telephone number.	
Home2-Num	Secondary home telephone number.	
Mobile-Num	Cellular telephone number.	
Pager-Num	Pager number.	
Note	Description or note for this entry or distribution list. 	

Messages and Public Folders 
The migration files can include messages, attachments, documents, and public data. Public folder data is imported as a special kind of message. The header line of each section starts with MAILMESSAGE and is followed by the source e-mail address or PublicMessage.
Messages
The following example illustrates the format of each message section: 
MAILMESSAGE,PROFS:SANFRAN(HOWARDS)
Folder,Sender,To,Cc,Bcc,Subject,Send-Date,Received-Date\\
,Priority,Unread,Unsent,Body
Inbox,Pat Parkes,Elizabeth Brown,,,"Let's make plans for this 
Friday",19950321093421,19950321093421,-1,,,#SALESPO1.SEC(50)
Phoenix Project,Pat Parkes,Ali Gobi,,,Review of Back Office\\
,19950321063321,19950321063321,,,,#SALESPO1.SEC(161)
Filed Mail\FYI,Jon Grande,Gamers[SMTP:gamers@Litware.com],\\
,,Solo Mission,19950218234539,19950218234539,,,,#SALESPO1.SEC(575)

Public Folders
The following example illustrates the public folder format:
MAILMESSAGE,PublicMessage
Folder,Sender,To,Cc,Bcc,Subject,Send-Date,Received-Date\\
,Priority,Unread,Unsent,Body
Social\Gamers,Pat Parkes,Games Groups,,,"Plans for this 
Saturday",19950320092421,19950320092421,-1,,,#SALESPO2.SEC(693)
Business\Phoenix Project,Karl Buhl,Phoenix Project,,,\\
Reviews,19950320093221,19950320093221,,,,#SALESPO2.SEC(798)

Public folder data is migrated from shared folders, bulletin board systems, and databases. If formatting will be lost or if the data would be unreadable in Microsoft Exchange Server, convert the information to text. 
The following table describes the fields in the header line for messages and public folders. All fields are required and must be in this order. 
Heading	Description	Values	
			
Folder	Path to destination folder. Use backslash to indicate subfolders.	Default = Inbox. Inbox, Deleted Items, Outbox, and Sent Items get mapped to special folder ID numbers. Displayed name of folders depends on language of client.	
Sender	Display name of sender.	Display name or display name [e-mail address].	
To	Display name of To recipients, separated by semicolons.	Display name or display name [e-mail address].	
Cc	Display name of Cc recipients, separated by semicolons.	Display name or display name [e-mail address].	
Bcc	Display name of Bcc recipients, separated by semicolons.	Display name or display name [e-mail address].	
Subject	Subject of message.	Single line of text.	
Send-Date	Date message sent. 	Date and time.	
Received-Date	Date message received.	Date and time.	
Priority	Priority of message. Default = 0.	Low priority = -1. Normal priority = 0. High priority = 1. 	
Unread	Boolean value to indicate read status of message.	TRUE if message was not read. FALSE if message was read. (Default = FALSE.)	
Unsent	Boolean value to indicate sent status of message. 	TRUE if message was not sent. FALSE if message was sent.   (Default = FALSE.)	
Body	One pointer to body of message. You must use the secondary file for message bodies and attachments. Attachments are referenced from bodies of secondary file.	#filename(offset)	

For systems that support only sent dates or only received dates, the source extractor should set the received date and sent date to appropriate date values. For systems that support neither sent nor received dates, the source extractor can leave the fields blank or substitute the current date and time.
Formatting the Secondary Files
A secondary file is a collection of one or more sections. Each section contains a description of the data, followed by the actual data. A message body and its attachments are in separate sections. 
The offset in the primary file specifies the first section in the secondary file for messages with multiple sections. Sections are separated by blank lines. The following example shows the format of secondary files:
Type,Length,Encoding,Islast,Name,Position,Format
Body,91,,TRUE,,,
Do you want to play a game of racquetball after work tonight?

Pat

Body,70,,FALSE,,,
I saw this short review of Microsoft's Back Office products.

Pat 

Attachment,205,,TRUE,backoffi.txt,0,
Microsoft BackOffice package includes Windows NT Server, Microsoft Exchange Server, SQL Server, and System Management Server.

Other,51,,TRUE,,,
leslied;sallys;marck;louisej;robinh;bobbyq;gregoryc

The following table describes the fields in the header line of secondary files.
Heading	Description	Values	
			
Type  (Required)	Type of data.	Body, Attachment, Schedule, Document, or Other.	
Length (Required) 	Length of data in bytes, including end-of-line characters. 	Integer. If message is body part of a free document, the length must = 0. 	
Encoding	Reserved field.	Leave blank.	
Islast	If TRUE, body or attachment is the last in the file for this message. If FALSE, the next section in file is either body or attachment for this message. 	TRUE or FALSE.	
Name	File name of attachment.	Required for sections that are attachments and documents, and ignored otherwise.	
Position (Optional)	Location, in bytes, where icon for attachment should be placed. Valid only for attachments. 	Default is to end of the body. Required for sections that are attachments and ignored otherwise. Must be between -1 and the number of bytes in the body.	
Format	File format of attachment.	None or Macbinary. Defaults to None. Required for sections that are attachments and ignored otherwise.	

Free Documents
Documents or files can be migrated, even if they are not associated with messages. In the primary file, they appear as standard messages. In the secondary file, the length of the body of the message = 0. The subject for this message is ignored, and the Islast field is set to FALSE. The Document section is next in the secondary file.
It is very important that the file name in the Document section include an extension. If none exists, add an extension that can launch a viewer application. Here is an example of a free document in the secondary file:
Type,Length,Encoding,Islast,Name,Position,Format
Body,0,,FALSE,,,
Document,205,,TRUE,backoffi.txt,0,
Microsoft BackOffice package includes Windows NT Server, Microsoft Exchange Server, SQL Server, and System Management Server.

Schedule Data
Schedule data is moved to the user’s mailbox as an attachment to a new mail message. The user opens the message and imports the data by double-clicking the attachment. You must install Microsoft Schedule+ to import the data.
In the primary file, the schedule data appears to be another message in the message section. In the following example, the third message in bold is the schedule message, which is placed in the Inbox. 
MAILMESSAGE,PROFS:SANFRAN(HOWARDS)
Folder,Sender,To,Cc,Bcc,Subject,Send-Date,Received-Date,Priority,Unread,Unsent,Body
,Bill Lee,Howard Snyder,,,"End of Month Report",19950321093421,,-1,,,#SALESPO1.SEC(54)
Phoenix Project,Pat Parkes,Howard Snyder,,,Back Office Review,,,,,,#SALESPO1.SEC(161)
,Howard Snyder,Howard Snyder,,,Schedule+,19951005022543,,1,TRUE,,#SALESPO1.SEC(356)

In the secondary file, set the body of the message to a length of 0. The Migration Wizard automatically adds instructions for importing the schedule file in English, German, French, or Japanese, depending on the language of your Microsoft Exchange Server.
Type,Length,Encoding,Islast,Name,Position,Format
Body,0,,FALSE,,,
Schedule,298,,True,HOWARDS.SC2,-1,
SCHEDULE+2 EXPORT VERSION 103
...

The first line in the schedule file must be a header line as follows:
SCHEDULE+2 EXPORT VERSION 103

Each line thereafter has schedule properties and values. The following table describes the differences between the schedule file format and the standard migration file format.
Property	Description	
		
Object	Starts with line that describes type of data (for example: “Projects”), followed by a colon. Next line has open brace ({). Each line thereafter has a property, followed by a colon and the value. Last line of table has close brace (}). Comparable to a header line and row of data in the migration file format.	
Object containing an object	An object can contain another object. Within open and close braces of an object, another set of braces can designate another object. For example, recurring appointments can contain exception objects to describe modified or deleted single appointments in the recurring appointment schedule. 	
Separator	Schedule file format uses a colon, instead of a comma, to separate schedule property names from values. A colon must be followed by a space.	
Space	A space after a colon and before a value are ignored. You can use spaces to make the file more readable.	
Line continuation character	Schedule file format uses a backslash (\), followed by a carriage return and line feed, to indicate that the line continues. Lines cannot exceed 80 characters. You can use two line continuation characters to make a line break in appointment or task descriptions.	
Quotation mark	Schedule file format encloses all strings and binary data in quotation marks. Quotation marks inside these values are represented by a backslash followed by a quotation mark (\”).	
Date/Time	Date = mm-dd-yyyy. Time = hh:mm, 24-hour format. You can join date and time with a space: mm-dd-yyyy hh:mm. For example, 9:00 AM on New Years Day = 01-01-1996 09:00. All times and dates are imported in the time zone of user. 	

Tip
To see examples of the schedule file format, create examples in Schedule+ and export the calendar.

The following Schedule+ objects can be created in the schedule file format.
Property	Description	
		
Projects	Table of all projects.	
Contacts	Table of contacts.	
SingleAppointments	Appointments that occur only once.	
SingleEvents	Events that occur only once.	
SingleTasks	Tasks that occur only once.	
RecurringAppointments	Recurring appointments.	
RecurringEvents	Recurring events.	
RecurringTasks	Recurring tasks.	

Each type of property can occur multiple times within the file. If objects of the same type are kept together, import performance is improved.
SCHEDULE+2 EXPORT VERSION 103
Projects:
{
	data
}
Projects:
{
	data
}
Contacts:
{
	data
}
RecurringAppointments:
{
	data
}
RecurringEvents:
{
	data
}
RecurringTasks:
{
	data
}
SingleAppointments:
{
	data
}
SingleEvents:
{
	data
}
SingleTasks:
{
	data
}

Schedule+ Projects
The following examples illustrate the projects format:
Projects: 	
{
	Priority: 	16945
	Text: 	"Colossus Project"
}
Projects: 	
{
	Priority: 	16689
	Text: 	"Region 6 Spring Sales Drive"
}

The following table describes the properties of projects. 
Property	Description	
		
Priority	Urgency of project.	
Text	Description of project.	

For more information on priorities, see “Priority Property” later in this appendix.
Schedule+ Contacts
Schedule+ contacts are separate from Microsoft Exchange Client PAB entries. There is no link between them. Depending on the configuration of your source system, contacts can be imported into Schedule+ if contact entries are created in the schedule migration file.
You can also create contacts from PAB entries in the source system. Users can delete contacts created this way, but they cannot add information from PAB entries to the contacts list.
The following example illustrates the contact format:
Contacts: 	
{
	LastName: 	"Lee"
	Department: 	"MIS"
	AddressBusiness: 	"12 Main St"
	CountryBusiness: 	"USA"
	PhoneBusiness: 	"415 555-9839"
	CityBusiness: 	"San Francisco"
	Office: 	"16/2102"
	Company: 	"Ferguson & Bardell"
	Assistant: 	"Sarah"
	ZipCodeBusiness: 	"94105"
	CurrentPhone1: 	4
	FirstName: 	"William"
	StateBusiness: 	"CA"
	JobTitle: 	"Team Manager"
}

The following table describes the properties of contacts.
Property	Description	
		
AddressBusiness	Business address.	
AddressHome	Home address.	
Assistant	Assistant of the contact.	
CityBusiness	City for the business address.	
CityHome	City for the home address.	
Company	Company.	
CountryBusiness	Country for the business address.	
CountryHome	Country for the home address.	
Department	Department.	
FirstName	First name.	
JobTitle	Job title.	
LastName	Last name.	
Notes	Miscellaneous information.	
Office	Office location.	
PhoneAssistant	Phone number of the contact’s assistant.	
PhoneBusiness	Business phone number.	
PhoneBusiness2	Second business phone number.	
PhoneFax	Fax phone number.	
PhoneHome	Home phone number.	
PhoneHome2	Second home phone number.	
PhoneMobile	Mobile phone number.	
PhonePager	Pager phone number.	
Spouse	Name of the contact’s spouse.	
StateBusiness	State/province of business address.	
StateHome	State/province of home address.	
User1	User-defined string for contact information that doesn’t fit any other field.	
User2	User-defined string for contact information that doesn’t fit any other field.	
User3	User-defined string for contact information that doesn’t fit any other field.	
User4	User-defined string for contact information that doesn’t fit any other field.	
ZipCodeBusiness	Business address postal code.	
ZipCodeHome	Home address postal code.	

Schedule+ SingleAppointments 
If attendees are invited to a migrated appointment, put their names into the Notes or Text property of the appointment. To make it easier for the user to send mail to the attendees or to add the attendees to the attendees list, use a semicolon to separate the names. The user can then copy the list of names into the To line of a message or to the attendees list and resolve them against the Address Book.
Schedule+ appointments can list outside attendees. Their unique MAPI ID is stored with the appointment and is used to verify responses to meeting requests. Without an attendee’s MAPI ID, the display name cannot be added to the attendees list.
The following example illustrates the SingleAppointment format:
SingleAppointments: 	
{
	Ring: 	T
	AlarmAmount: 	15
	Text: 	"Attend training class."
	AlarmTypeUnit: 	0
	AlarmAmountOriginal: 	15
	BusyType: 	0
	Start: 	3-5-1996 15:00
	End: 	3-5-1996 17:00
}
SingleAppointments: 	
{
	Where: 	"Rona's office"
	Text: 	"Meet with Rona about shifting contacts to new employees.\
\
Rona Rumalski"
	Ring: 	T
	AlarmAmount: 	15
	Start: 	3-5-1996 09:00
	BusyType: 	1
	End: 	3-5-1996 10:30
	AlarmTypeUnit: 	0
}

The following table describes the properties of SingleAppointments.
Property	Values	Description	
			
AlarmAmount	Integer	Amount of time before meeting date to issue alarm.	
AlarmTypeUnit	0 = Minute
1 = Hour
2 = Day
3 = Week
4 = Month	Type of unit for AlarmAmount.	
BeforeEnd	T or F
Default = F	Alarm is set relative to end rather than to start of SingleAppointment.	
BusyType	0 = Tentative
1 = Busy	If SingleAppointment should appear busy or tentative.	
End (Required)	mm-dd-yyyy hh:mm	End date and time for SingleAppointment. 	
IsRecurringInstance	T or F
Default = F	If SingleAppointment is instance of recurring series.	
Notes		Miscellaneous information. Text appears in Notes property page for appointment.	
Ring	T or F
Default = T	If alarm was set for SingleAppointment.	
Start (Required)	mm-dd-yyyy hh:mm	Start date and time for SingleAppointment. 	
Text		Description for SingleAppointment. Text appears on calendar.	
Where		Location for appointment.	

Schedule+ SingleEvents
Events are different from appointments in the following ways:
	Events appear above the day’s calendar.
	Events do not have attendees.
	Alarms for events are based on midnight.

The following example illustrates the SingleEvents format:
SingleEvents: 	
{
	Ring: 	T
	AlarmAmount: 	2
	Text: 	"River City 10 mile hike and camp. (Weather permitting.)\
Call Josh at 555-1232 to make sure it is happening."
	AlarmTypeUnit: 	2
	AlarmAmount: 	2
	StartDate: 	3-2-1996
	EndDate: 	3-3-1996
}

The following table describes the properties of SingleEvents:
Property	Values	Description	
			
AlarmAmount	Integer	Amount of time before midnight to issue alarm.	
AlarmTypeUnit	0 = Minute
1 = Hour
2 = Day
3 = Week
4 = Month	Type of unit for AlarmAmount.	
BusyType	0 = Tentative
1 = Busy	If event should appear busy or tentative.	
EndDate (Required)	mm-dd-yyyy	End date for event. 	
IsRecurringInstance	T or F
Default = F	Indicates if event is instance of recurring series.	
Notes		Miscellaneous information.	
Ring	T or F
Default = T	If alarm was set to ring for event.	
StartDate (Required)	mm-dd-yyyy hh:mm	Start date for event. 	
Text	String	Text (description) for event.	

Schedule+ SingleTasks
Schedule+ relates tasks to projects by using the ProjectID number. Without a ProjectID number, tasks are imported without being related to a project. 
The following example illustrates the SingleTask format:
SingleTasks: 	
{
	Priority: 	16672
	Text: 	"Update summer catalog."
	AmountActualEffort: 	0
	AmountEstimatedEffort: 	1
	IsTaskAutoDone: 	T
	StartDate: 	3-6-1996
	AmountStartWork: 	4
	TypeUnitStartWork: 	2
	EndDate: 	3-10-1996
	TypeUnitEstimatedEffort: 	2
	TypeUnitActualEffort: 	2
}

The following table describes the properties of SingleTasks.
Property	Values	Description	
			
AmountActualEffort	Number	Amount of time of actual effort, in units set by TypeUnitActualEffort.	
TypeUnitActualEffort	0 = Minute
1 = Hour
2 = Day
3 = Week
4 = Month	Type of unit for measuring actual effort for task.	
AmountEstimatedEffort	Number	Amount of estimated time effort, in units set by TypeUnitEstimatedEffort.	
TypeUnitEstimatedEffort	0 = Minute
1 = Hour
2 = Day
3 = Week
4 = Month	Type of unit for measuring estimated effort for task.	
AmountStartWork	Number	Amount of time before end date to start work on item, in units set by TypeUnitStartWork.	
TypeUnitStartWork	0 = Minute
1 = Hour
2 = Day
3 = Week
4 = Month	Type of unit for amount of time before end date to start work.	
Billing	String	Billing information.	
CompletedDate	mm-dd-yyyy	Date task was completed.	
StartDate	mm-dd-yyyy	Date task starts.	
EndDate	mm-dd-yyyy	Date task ends.	
IsTaskAutoDone	T or F	If task should appear as automatically completed on end date.	
Mileage	String	Mileage associated with task.	
PercentCompleted	Number	Percentage of task completed.	
Priority	See the following explanation.	Priority of task.	

Priority Property
Schedule+ prioritizes tasks by using numbers (1 through 9) and/or letters (A through Z). For example, “A1,” “ 3,” and “B” are valid priorities. The migration file format converts this priority to a decimal. 
The following table illustrates how priorities are converted to decimal versions. The ASCII value of the letter or number is converted to a hexadecimal, the number 20 is prefixed or appended as a space and place holder, and this number is converted to a decimal.

Priority	Convert to hexadecimal	
Prefix or append 20	
Convert to decimal	
				
1	31	2031	8241	
2	32	2032	8242	
3	33	2033	8243	
4	34	2034	8244	
5	35	2035	8245	
6	36	2036	8246	
7	37	2037	8247	
8	38	2038	8248	
9	39	2039	8249	
A	41	4120	16672	
B	42	4220	16928	
C	43	4320	17184	
D	44	4420	17440	
E	45	4520	17696	
F	46	4620	17952	
G	47	4720	18208	
H	48	4820	18464	
I	49	4920	18720	
J	4A	4A20	18976	
K	4B	4B20	19232	
L	4C	4C20	19488	
M	4D	4D20	19744	
N	4E	4E20	20000	
O	4F	4F20	20256	
P	50	5020	20512	
Q	51	5120	20768	
R	52	5220	21024	
S	53	5320	21280	
T	54	5420	21536	
U	55	5520	21792	
V	56	5620	22048	
W	57	5720	22304	
X	58	5820	22560	
Y	59	5920	22816	
Z	5A	5A20	23072	

For a number priority of 3, for example, use the hexadecimal 33 and prefix 20. The value 2033 converts to decimal 8243. For a letter priority of C, for example, take the hexadecimal 43, and append 20. The value 4320 converts to 17184.
If your existing system prioritizes by requiring both letters and numbers (for example: A1, B3, or Z9), use this procedure. Convert both to hexadecimal, concatenate (link together) the values of the letter and number, and then convert that value to decimal. For a priority of A3, for example, use the hexadecimal of A (41) and concatenate it with the hexadecimal of 3 (33). The value 4133 converts to 16691.
Schedule+ Recurring Appointments, Events, and Tasks
The following examples illustrate the format for recurring appointments, events, and tasks:
RecurringEvents: 	
{
	Text: 	"Yearly tax audit. Start preparations early."
	Ring: 	T
	AlarmAmount: 	21
	AlarmTypeUnit: 	2
	StartDate: 	3-4-1996
	EndDate: 	3-4-1996
	RecurringType: 	7
	YearInterval: 	1
	DayOfMonthMask: 	8
	MonthOfYearMask: 	4
}
RecurringAppointments: 	
{
	Text: 	"SATR meeting.\
\
Big Sale."
	Ring: 	T
	AlarmAmount: 	15
	DayOfWeekStart: 	0
	StartRecurringTime: 	12:00
	YearInterval: 	1
	WeekInterval: 	1
	BusyType: 	0
	RecurringType: 	51
	StartRecurringDate: 	2-26-1996
	DayOfWeekMask: 	32
	EndRecurringDate: 	3-4-2000
	DayOfMonthMask: 	8
	EndRecurringTime: 	13:00
	MonthOfYearMask: 	4
	AlarmTypeUnit: 	0
}
RecurringTasks: 	
{
	Text: 	"Check online mailbox for new mail."
	Priority: 	8243
	TypeUnitActualEffort: 	2
	AmountEstimatedEffort: 	1
	TypeUnitEstimatedEffort: 	2
	Billing: 	"Billed at higher rate"
	BeforeEndOriginal: 	F
	AmountStartWork: 	0
	StartRecurringDate: 	3-2-1996
	RecurringType: 	64
	WeekInterval: 	1
	DayOfWeekMask: 	16
	DayOfWeekStart: 	0
	DayInterval: 	1
	EndRecurringDate: 	8-10-1996
	TypeUnitStartWork: 	2
	Ring: 	T
	AlarmAmount: 	0
	AlarmTypeUnit: 	2
	BeforeEnd: 	F
	Exceptions: 	
	{
		InstanceDate: 	3-3-1996
		StartDate: 3-3-1996
		EndDate:	 3-4-1996
		Deleted: 	F
		Text: "Check online mailbox for new mail. Check for new rates."
		Priority: 	8241
		TypeUnitActualEffort: 	2
		AmountEstimatedEffort: 	1
		TypeUnitEstimatedEffort: 	2
		BeforeEndOriginal: 	F
		AmountStartWork: 	0
		TypeUnitStartWork: 	2
		Ring: 	T
		AlarmAmount: 	5
		AlarmTypeUnit: 	2
		BeforeEnd: 	F
	}
}

The following table describes the properties shared by recurring appointments, events, and tasks.
Property 	Values	Description	
			
DayInterval	1 through  999	Number of days between instances. Used only if RecurringType is 64.	
DayOfMonthMask	1st day of month = bit 0
31st day of month = bit 30	Bit field indicating which days of the month are valid for recurrence pattern. Used only if RecurringType is 7 or 12.	
DayOfWeekMask	Sunday = bit 0
Saturday = bit 6	Bit field indicating which days of the week are valid for recurrence pattern. Used only if RecurringType is 48, 51, or 56.	
DayOfWeekStart	0 through 6
Sunday = 0	Start of week preference. Used only if RecurringType is 48. For recalculating biweekly meetings.	
EndRecurringDate	mm-dd-yyyy	End date for recurrence pattern.	
EndRecurringTime (Required)	hh:mm	End time for a recurring item.	
Exceptions	See “Exceptions Property” section later in this chapter.	Exceptions to a recurring item.	
FirstRecurringAlarmDate	Today’s date in mm-dd-yyyy format.	First recurring item with alarm. Recalculated during import into Schedule+.	
MonthInterval	1 through 99	Interval between months for recurrence pattern. Used only if RecurringType is 12 or 56.	
MonthOfYearMask	January = bit 0
December = bit 11	Bit field indicating which months of year are valid for recurrence pattern. Used only if RecurringType is 7 or 51.	
RecurringType (Required)	  7 = Yearly on specific day
12 = Monthly on specific day
48 = Weekly
51 = Yearly on a pattern
56 = Monthly on a pattern
64 = Daily	Type of recurrence pattern.	
StartRecurringDate (Required)	mm-dd-yyyy	Start date for recurrence pattern.	
StartRecurringTime (Required)	hh:mm	Start time for recurring item.	
WeekInterval	Positive integer	Interval between weeks for recurrence pattern. Used only if RecurringType is 48, 51, or 56.	
YearInterval	Positive integer	Interval between years for recurrence pattern. Used only if RecurringType is 7.	

The following table describes additional values required for the RecurringType property.
RecurringType	Required values	
		
  7 = Yearly on specific day	DayOfMonthMask, MonthOfYearMask, YearInterval	
12 = Monthly on specific day	DayOfMonthMask, MonthInterval	
48 = Weekly	DayOfWeekMask, DayOfWeekStart, WeekInterval	
51 = Yearly on a pattern	DayOfWeekMask, MonthOfYearMask, WeekInterval	
56 = Monthly on a pattern	DayOfWeekMask, MonthInterval, WeekInterval	
64 = Daily	DayInterval	

Exceptions Property
Exceptions are deleted or modified properties of a recurring appointment or task. To delete, only two properties are required: Deleted and InstanceDate. To modify, the appointment or task must be redefined as a single appointment or task, and you must redefine the StartDate and EndDate, even if only the Location property is modified.
Property	Values	Description	
			
Deleted	T or F	If instance was marked “deleted.” If FALSE, instance has been modified.	
InstanceDate	mm-dd-yyyy	Date that original instance would have occurred.	

Editing Migration Files
You can edit migration files to change or add data. You edit the primary files after they are extracted and before they are imported with the Migration Wizard. 

Important
Editing the secondary files is not recommended. Changes to secondary files require recalculating all offsets and then updating the primary file.

You may want to edit the primary files for the following reasons:
	To change the common names of mailboxes. You can only do this before the mailbox is created.
	To make the aliases different from the common names.
	To change the display name format.
	To parse the display name to generate the given name and surname fields, depending on the configuration of your source extractor.
	To add additional fields and data (telephone numbers, department names, and other items) to the directory. 
	To delete all messages sent before a certain date, if your source extractor doesn’t support the limiting of messages.

Important
Editing migration files can introduce invalid or incorrect data. Make a backup of all migration files before editing them.

You can avoid editing the primary file by configuring the source extractor appropriately. For example, you can configure the source extractor to create given names and surnames, or to accept a text file of the old mailbox names and their new Microsoft Exchange Server common names. Use the following procedures to modify common names.
	To modify the common names of mailboxes 
	1.	Configure the source extractor to create files with mailbox creation information only.
	2.	Modify the small primary file, and then use the source extractor to create migration files that don’t need editing.
	3.	Import the smaller mailbox creation files, and then import the mailbox data files.

You can also use the Directory Import and Directory Export commands instead of the Migration Wizard to import data. You can use these commands to change the display names, addresses, given names, surnames, and other mailbox properties.

Important   Some primary file fields may exceed 255 characters, but some spreadsheet programs can’t hold more than 255 characters in a cell. The extra can be truncated without notice, causing a loss of data.

Troubleshooting Errors
If errors occur during the import of migration files, the Migration Wizard logs errors to an application log and importing may stop. If importing continues, the error is written to a recovery file. A recovery file is created each time files are imported. The recovery files are written into the temp directory of the computer running the Migration Wizard. 
Therefore, if an error occurs, first check the application log and the recovery file. One error in the file format can cause multiple or cascading error messages. If the error can’t be found in the line with the error report, an error in a previous line might be causing the problem, or there may be an improper offset to the secondary file.
If it’s a primary file error, you can edit this file and fix the problem. If it’s a secondary file error, you get a pointer to the problem, which you can attempt to fix. If you must edit the secondary file, make a backup first. Be careful not to change the offsets of later sections. After all problems are fixed, you can create a new packing list file that lists the primary and edited (not original) secondary files.
File Processing 
If you understand how the Migration Wizard processes the files, you can troubleshoot problems. The Migration Wizard first reads the packing list file and then starts processing the first primary file. The following table describes how each primary file is processed.
Section	Processing	
		
Directory	Every line after the directory header line until the start of the next section is passed to the directory import dynamic link library one line at a time.	
PAB	Each line of PAB data is read. After all lines are read, a message is created.	
MailMessage	If the mailbox does not exist, it is created, if possible by custom recipient conversion. If a message is for public folder, it is created if necessary with appropriate permissions.
For each line, a message is created. The secondary file is checked for body and attachments. If body is empty and there is a document, the attachment to mailbox is copied as a free document. If body is empty and there is a schedule file, the body is supplied by the Migration Wizard and the attachment is added.	

Troubleshooting the Primary Files
If you can’t find anything wrong with the primary file lines with error reports, trace errors with the following procedure:
	To check for errors in a primary file
	1.	Make a backup copy of the original migration files.
	2.	Edit the primary file to remove all lines with error reports.
	3.	Import the edited files. 
Error reports can now be eliminated. However, if errors are still reported, the errors are in the previous lines. The errors in the previous lines did not stop the importing but did cause problems in the next lines.
	4.	Make a copy of the backup migration files.
	5.	Edit the primary file, removing the lines previous to the lines with error reports.
	6.	Import the edited files. 
The error reports can now be eliminated. 
	7.	If errors are still reported, repeat steps 4 through 7, removing lines previous to the lines removed in the last test.

Once you identify the problem lines, see how they differ from lines that were successfully imported, or how they differ from the proper migration file format.
Troubleshooting the Secondary Files
You can’t edit a secondary file if the edits will change the offsets. Adding or removing even a single character from the secondary file can cause errors when later importing objects. If you edited a secondary file and then get errors when you try to import it, replace the edited file with an unedited backup copy.
If you did not edit the file, first examine the application log and the secondary recovery files. If other objects of the same type migrated successfully, compare the objects in the recovery file with the objects in the migration files. Check whether the offsets from the primary file match the entries in the secondary file, and check for conversions that might have altered the end-of-line characters.