OutlookTools

The OutlookTools UDF offers some often needed extended functionality to control and manipulate Microsoft Outlook. It is built on top of the OutlookEX UDF.

General

Technical Terms

You will encounter the following technical terms when working with the OutlookTools UDF. These terms are not unique to the UDF, so you will find just the general description in this section.

iCalendar

Internet Calendaring and Scheduling Core Object Specification (iCalendar). Filename extension: .ical, .ics, .ifb, .icalendar

CSV

A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values. Filename extensions: .csv

VCalendar

Predecessor of the iCalendar specification

vCard, VCF

vCard also known as VCF (Virtual Contact File), is a file format standard for electronic business cards.

Limitations/Requirements

• The functions do not support encoded text (e.g. =D6 for O Umlaut)
• The functions do not support multiline text (e.g. lines ending with =0D=0A)
• The functions do not support nested objects (e.g. nest a meeting.ics and person.vcf)
• Only supports local or UTC date/time. Time zones are not supported

Callback function

Most of the functions provide a callback function. It gets called before an Outlook item is processed.

You decide how the item is being handled by setting @extended. You HAVE to return one of the following values:

Flag	Action
$iOLT_FlagProcessRecord (1)	Process the current record, then continue with the next record
$iOLT_FlagCancelRecord (2)	Do not process the current record, then continue with the next record
$iOLT_FlagCancelAll (4)	Do not process the current record, cancel processing all remaining records and exit the _OLT_* function
$iOLT_FlagReturnData (8)	The data passed to the callback function has been modified. Pass the data back to the calling _OLT_* function

The function is called with a parameter describing the data being used to create the Outlook item. The full description of this data can be found in the corresponding function you find below.

This parameter is read only by default. If you want to modify this data and return it to the calling function you need to:

• set @extended to $iOLT_FlagReturnData
• set the return value to the modified variable or array

Example: Return the modified array to the calling function:

Func CallBack($aData)
	$aData[0] = "A"
	Return SetError(0, $iOLT_FlagReturnData, $aData)
EndFunc

Example: Do not return data to the calling function. Just process the record:

Func CallBack($aData)
	Return SetError(0, $iOLT_FlagProcessRecord)
EndFunc

Debugging

The OutlookTools functions accept the following debugging flags. You have to select $iOLT_DebugConsole or $iOLT_DebugFile. The result can then be combined with $iOLT_DebugProperties and/or $iOLT_DebugCreateOff:

Flag	Action
$iOLT_DebugOff (0)	No debugging (default)
$iOLT_DebugConsole (1)	Writes debugging messages to the console
$iOLT_DebugFile (2)	Writes debugging messages to a file specified by parameter $sDebugFile
$iOLT_DebugProperties (4)	Writes the properties used to create the Outlook item to the debugging destination
$iOLT_DebugCreateOff (8)	Do not create the Outlook item. Allows to test the function without modifying Outlook

Functions

_OLT_iCal_VEvent_Import

Import iCal events from an ICS file to an Outlook calendar.

The function processes the following properties (in whole or in part) according to RFC 5545 (properties not listed will be ignored):

COMPONENT:PROPERTY	SECTION IN RFC 5545	OUTLOOK PROPERTY	COMMENT
VEVENT:CATEGORIES	Section 3.8.1.2	Categories
VEVENT:CLASS	Section 3.8.1.3	Sensitivity	olNormal, olPrivate or olConfidentional. olPersonal does not get set
VEVENT:DESCRIPTION	Section 3.8.1.5	Body
VEVENT:LOCATION	Section 3.8.1.7	Location
VEVENT:PRIORITY	Section 3.8.1.9	Importance
VEVENT:SUMMARY	Section 3.8.1.12	Subject
VEVENT:DTEND	Section 3.8.2.2	End	specifies the non-inclusive end of the event
VEVENT:DTSTART	Section 3.8.2.4	Start	Example
VEVENT:DURATION	Section 3.8.2.5	End	used to calculate the end property
VEVENT:TRANSP	Section 3.8.2.7	BusyStatus
VALARM:TRIGGER	Section 3.8.6.3	ReminderMinutesBeforeStart	Only the minutes section of the duration is processed

Limitations/Requirements

Input for the function has been taken from the following standards:

• vCalendar 1.0: RFC 2445, 1998-11
• vCalendar 2.0: RFC 5545, 2009-09

This means that the function does not fully follow this standards. It just scans throught he input file and extracts as much information as possible. Means: What you get from the function is just an educated guess :-)

Example script

_OLT_iCal_VEvent_Import.au3

• creates a test.ics file in the current directory
• this test file holds two events starting today with a duration of 1 and 2 days
• debugging is done to the console
• it uses a callback function to suppress all events with SUBJECT=Party
• an array holding Start, End and Subject of the created items is displayed

Callback function parameter

A one dimensional zero-based array holding the Outlook properties to create the item.

Format: Outlook-property-name=Outlook-property-value

_OLT_vCard_Import

Import vCard contacts to an Outlook contacts folder.

The function processes the following properties (in whole or in part) according to RFC 6350 (properties not listed will be ignored):

COMPONENT:PROPERTY	SECTION IN RFC 6350	OUTLOOK PROPERTY	COMMENT
VCARD:FN	Section 6.2.1	fullname
VCARD:N	Section 6.2.2	lastname, firstname, middlename, title	Family Names, Given Names, Additional Names, Honorific Prefixes, and Honorific Suffixes
VCARD:ADR TYPE=HOME	Section 6.3.1	HomeAddressPostOfficeBox, HomeAddress, HomeAddressStreet, HomeAddressCity, HomeAddressState, HomeAddressPostalCode, HomeAddressCountry
VCARD:ADR TYPE=WORK	Section 6.3.1	BusinessAddressPostOfficeBox, BusinessAddress, BusinessAddressStreet, BusinessAddressCity, BusinessAddressState, BusinessAddressPostalCode, BusinessAddressCountry
VCARD:TEL TYPE=HOME	Section 6.4.1	PersonalHomePage
VCARD:TEL TYPE=WORK	Section 6.4.1	BusinessHomePage
VCARD:EMAIL	Section 6.4.2	Email1Address
VCARD:ORG	Section 6.6.4	CompanyName
VCARD:TITLE	Section 6.6.1	JobTitle
VCARD:CATEGORIES	Section 6.7.1	Categories
VCARD:URL TYPE=HOME	Section 6.7.8	PersonalHomePage
VCARD:URL TYPE=WORK	Section 6.7.8	BusinessHomePage

Limitations/Requirements

Input for the function has been taken from the following standards:

• vCard 2.1: vCard 2.1 specification, 1996-09-18 (https://web.archive.org/web/20120501162958/http://www.imc.org/pdi/vcard-21.doc)
• vCard 3.0: RFC 2426, 1998-09
• vCard 4.0: RFC 6350, 2011-08

This means that the function does not fully follow this standards. It just scans throught he input file and extracts as much information as possible. Means: What you get from the function is just an educated guess :-)

Example script

_OLT_vCard_Import.au3

• creates a test.vcf file in the current directory
• this test file holds a single contact
• debugging is done to the console
• it uses a callback function to not import contacts that already exist
• an array holding all created items is displayed

Callback function parameter

A one dimensional zero-based array holding the Outlook properties to create the item.

Format: Outlook-property-name=Outlook-property-value

_OLT_CSV_Import

Imports data from a CSV file and creates Outlook items in a specified folder.

Limitations/Requirements

• has only been tested for contact items
• this function does not read the input file (as other functions of the OutlookTools UDF do). You have to use _FileReadToArray (or a similar function) and pass the resulting array to _OLT_CSV_Import. With this approach you can process different types of CSV files (delimiters etc.) and files that do not comply to RFC 4180
• you have to pass a second array describing the structure of the data array. The structure is described by using the corresponding Outlook item properties
• this function allows to alter data used to create the Outlook item (all other functions don't for the time being). This is possible because the data is held in a global variable which is filled before _OLT_CSV_Import gets called

Example script

_OLT_CSV_Import.au3

• creates the data array ($aData) without reading a file (you should use _FileReadToArray to read the CSV file and fill the array)
• the structure array ($aStruct) describes the columns in $aData using the Outlook contact properties Firstname, LastName and UnRead
• debugging is done to the console
• it uses a callback function to set Outlook property UnRead to True for contacts with FirstName=Jane

Callback function parameter

The zero based index of the currently processed row in $aData.

As the data to process is being held in $aData in the main script the callback function can directly alter this data. So there is no need to return $aData to _OLT_CSVImport and hence _OLT_CSVImport will ignore returned data.

_OLT_Export

Export Outlook items (contacts, appointments ...) to files in different formats (VCF, ICS, CSV, Excel ...).

Limitations/Requirements

• currently just tested for contacts and appointments (VCF, ICS, CSV and Excel)

Example script

_OLT_Export_VCF.au3

• uses _OL_ItemFind to fill an array with all contacts to be exported
• column 0 of the array needs to be the EntryID of the item
• the VCF files are created in directory @ScriptDir & "\Export\"
• the files are named FirstName_LastName_Companies.VCF
• debugging is done to the console

_OLT_Export_ICS.au3

• uses _OL_ItemFind to fill an array with all appointments to be exported
• column 0 of the array needs to be the EntryID of the item
• the ICS files are created in directory @ScriptDir & "\Export\"
• the files are named Subject_StartDateTime.ICS
• debugging is done to the console

_OLT_Export_Excel.au3

• grab all users with firstname "Christian" from your contacts
• column 0 of the array needs to be the EntryID of the item
• the Excel workbook is created in directory @ScriptDir & "\Export\" as _OLT_Export_Excel.XLSX
• a header line is written to the workbook
• properties LastName and FirstName get written to the workbook
• debugging is done to the console

_OLT_Export_CSV.au3

• grab all users with firstname "Christian" from your contacts
• column 0 of the array needs to be the EntryID of the item
• the CSV file is created in directory @ScriptDir & "\Export\" as _OLT_Export_CSV.TXT
• a header line is written to the CSV file
• properties LastName and FirstName get written to the file
• debugging is done to the console

Callback function parameter

The zero based index of the currently processed row in $aItems.

As the data to process is being held in $aItems in the main script the callback function can directly alter this data. So there is no need to return $aItems to _OLT_Export and hence _OLT_Export will ignore returned data.