OutlookTools: Difference between revisions

From AutoIt Wiki
Jump to navigation Jump to search
mNo edit summary
 
(49 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{WIP}}
[[Category:UDF]]
[[Category:Outlook]]
The OutlookTools UDF offers some often needed extended functionality to control and manipulate Microsoft Outlook.  
The OutlookTools UDF offers some often needed extended functionality to control and manipulate Microsoft Outlook.  
It is built on top of the OutlookEX UDF.
It is built on top of the OutlookEX UDF.


==General==
==General==
Most of the functions provide a '''callback function'''. It gets called before an Outlook item is created.
===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 : [https://en.wikipedia.org/wiki/ICalendar Internet Calendaring and Scheduling Core Object Specification (iCalendar)]. Filename extension: .ical, .ics, .ifb, .icalendar
; CSV : A [https://en.wikipedia.org/wiki/Comma-separated_values 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 : [https://en.wikipedia.org/wiki/VCard 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 the return value:
You decide how the item is being handled by setting @extended. You HAVE to return one of the following values:  
{| class="wikitable"
{| class="wikitable"
|-
|-
! Return value !! Action
! Flag !! Action
|-
|-
| 0 || Create the Outlook item, continue processing the next record
| $iOLT_FlagProcessRecord (1) || Process the current record, then continue with the next record
|-
|-
| 1 || Do not create the Outlook item, continue processing the next record
| $iOLT_FlagCancelRecord (2) || Do not process the current record, then continue with the next record
|-
|-
| 2 || Do not create the Outlook item, cancel processing all remaining records and exit the _OLT_* function.
| $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. This parameter is read only.
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.
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:
<syntaxhighlight lang="autoit">
Func CallBack($aData)
$aData[0] = "A"
Return SetError(0, $iOLT_FlagReturnData, $aData)
EndFunc
</syntaxhighlight>
 
Example: Do not return data to the calling function. Just process the record:
<syntaxhighlight lang="autoit">
Func CallBack($aData)
Return SetError(0, $iOLT_FlagProcessRecord)
EndFunc
</syntaxhighlight>
 
===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:
{| class="wikitable"
|-
! 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==
==Functions==


===_OLT_iCal_VEventImport===
===_OLT_iCal_VEvent_Import===
Import iCal events from an ICS file to an Outlook calendar.
Import iCal events from an ICS file to an Outlook calendar.


The function processes the following properties according to RFC 5545 (properties not listed will be ignored):
The function processes the following properties (in whole or in part) according to [https://tools.ietf.org/html/rfc5545 RFC 5545] (properties not listed will be ignored):


{| class="wikitable"
{| class="wikitable"
|-
|-
! COMPONENT:PROPERTY !! SECTION IN RFC 5545 !! OUTLOOK PROPERTY !! COMMENT
! COMPONENT:PROPERTY !! SECTION IN [https://tools.ietf.org/html/rfc5545 RFC 5545] !! OUTLOOK PROPERTY !! COMMENT
|-
|-
| VEVENT:CATEGORIES || Section 3.8.1.2 || Categories ||  
| VEVENT:CATEGORIES || Section 3.8.1.2 || Categories ||  
Line 54: Line 109:
| VALARM:TRIGGER || Section 3.8.6.3 || ReminderMinutesBeforeStart || Only the minutes section of the duration is processed
| 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: [https://tools.ietf.org/html/rfc2445 RFC 2445], 1998-11
* vCalendar 2.0: [https://tools.ietf.org/html/rfc5545 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====
====Callback function parameter====
xxx
A one dimensional zero-based array holding the Outlook properties to create the item.
 
Format: Outlook-property-name=Outlook-property-value


===_OLT_vCard_Import===
===_OLT_vCard_Import===
Import vCard contacts to an Outlook contacts folder.
Import vCard contacts to an Outlook contacts folder.
The function processes the following properties (in whole or in part) according to [https://tools.ietf.org/html/rfc6350 RFC 6350] (properties not listed will be ignored):


{| class="wikitable"
{| class="wikitable"
|-
|-
! COMPONENT:PROPERTY !! SECTION IN RFC 6350 !! OUTLOOK PROPERTY !! COMMENT
! COMPONENT:PROPERTY !! SECTION IN [https://tools.ietf.org/html/rfc6350 RFC 6350] !! OUTLOOK PROPERTY !! COMMENT
|-
|-
| VCARD:FN || Section 6.2.1 || fullname ||  
| VCARD:FN || Section 6.2.1 || fullname ||  
Line 89: Line 163:
| VCARD:URL TYPE=WORK || Section 6.7.8 || BusinessHomePage ||  
| 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: [https://tools.ietf.org/html/rfc2426 RFC 2426], 1998-09
* vCard 4.0: [https://tools.ietf.org/html/rfc6350 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====
====Callback function parameter====
xxx
A one dimensional zero-based array holding the Outlook properties to create the item.
 
Format: Outlook-property-name=Outlook-property-value


===_OLT_CSV_Import===
===_OLT_CSV_Import===
Imports data from a CSV file and creates Outlook items in a specified folder.
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====
====Callback function parameter====
xxx
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.

Latest revision as of 09:26, 27 July 2023

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:

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:

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.

Retrieved from "https://www.autoitscript.com/w/index.php?title=OutlookTools&oldid=14843"