Export Utility for
IBM® Lotus Notes® / Domino®
LotusScript API Reference Guide
Sample Only
© AGECOM
https://www.agecom.com.au
Page 2 of 17
CONTENTS
Contents ........................................................................................................................................... 2
Introduction ..................................................................................................................................... 3
Export Configuration Settings ....................................................................................................... 3
Export Profiles ................................................................................................................................. 4
Running Exports On-Demand ........................................................................................................ 5
Export Options ................................................................................................................................ 7
ExportTitle ..................................................................................................................................... 7
OutputType ................................................................................................................................... 7
OutputFiles ................................................................................................................................... 7
StartDocument .............................................................................................................................. 8
MaxExportDocs ............................................................................................................................ 8
Appendix A – Processing Exports ................................................................................................. 9
Export Scheduler .......................................................................................................................... 9
On Demand Export ....................................................................................................................... 9
Background Export ..................................................................................................................... 10
Appendix B – Supported Character Sets .................................................................................... 12
Appendix C – Data Types for Export Items ................................................................................. 14
Appendix D – Sample Code .......................................................................................................... 15
Appendix E – Configuration Settings .......................................................................................... 16
RequireProfiles ........................................................................................................................... 16
MessageText .............................................................................................................................. 16
ShowFieldTypes ......................................................................................................................... 16
Appendix F – Acknowledgements ............................................................................................... 17
Page 3 of 17
INTRODUCTION
This sample reference guide provides an example of the information that is available in the full API
Reference Guide to assist you with writing your own code to hook into the Export Utility for IBM®
Lotus Notes® / Domino® application.
It provides detailed information on each of the fields in the main documents in the Export Utility:
• Export profile documents
• Export item documents
• Configuration documents
While the documentation is aimed primarily for development using LotusScript it can just as easily
assist with development in other languages such as Java or C/C++.
Using this guide you’ll be able to add exporting functionality to your own applications and perform
exporting on demand, or as required, with the assistance of the Export Utility.
Export profile documents are comprised of the following two components:
• Export profile document – contains all the settings for the export.
• Export items – one or documents specifying the fields, columns & computed formula to
export. Applicable only to Comma Delimited, Fixed Width, Microsoft Access, Microsoft
Excel, Tab Delimited and XML formats only.
A sample application is also available from AGECOM which contains agents and script libraries
you can customize and use in your own applications. The sample application:
• Demonstrates how to hook into the Export Utility to create new exports or edit existing
exports
• Shows how to run exports on demand
• Contains developer comments throughout the code explaining what is happening in
various sections or what customizations you may want to make
• Contains guidance on how to use and integrate the libraries into your own application.
The full API Reference Guide and Sample Application is available to licensed customers upon
request.
EXPORT CONFIGURATION SETTINGS
The Configuration Settings profile document contains numerous settings that affect the
functionality and operation of the Export Utility.
Appendix E contains detailed information for each field in this profile document. Sample code for
getting a handle to the Configuration Settings profile document has also been included.
Page 4 of 17
EXPORT PROFILES
Each export processed by the Export Utility requires a profile to be created. The profile document
is broken down into the following sections:
• Export Options – options, database, selection criteria, formatting, target file, attachment
handling and post export options.
• Schedule – specifying scheduling options for an export.
• Security – people / groups who can view the export profile.
• Custom Scripts – LotusScript code to execute before, during & after an export.
The following export formats also require one or more Export Item documents to be created and
linked to the export profile document:
• Comma Delimited (CSV)
• Fixed Width
• Microsoft Access
• Microsoft Excel
• Tab Delimited
• XML
Export Item documents are required to be created for each view column, document field,
document property or computed value that is to be exported. For other export formats export item
documents are not required. The fields and values for export item documents is also covered in
this guide.
Each field in the export profile document is outlined in this guide in order of the section they appear
in (or apply to) showing the field name, data type, possible values and other important information.
All fields are applicable to all export formats unless specifically stated otherwise.
Notes
1. The format of the fields and their possible values in Export Profile documents is shown
below. The actual value to assign to a field is shown in bold with additional information
shown after it. For example:
Y – Yes
N – No
In this instance the field should be assigned a value of ‘Y’ or ‘N’.
2. All fields are listed in each section in the order they appear on the Export Profile form.
3. Some field value descriptions may have ‘(default)’ after them. This indicates the particular
value is the default value for the field.
Page 5 of 17
RUNNING EXPORTS ON-DEMAND
Any export job can be run on-demand by calling the On-Demand Export agent. You can perform
an export for existing export profiles or create / update your own export profiles using custom
scripts from any application.
To run the On-Demand agent your code simply needs to get a handle to the Export Application
and call the ‘(OnDemandExport)’ agent passing it the Note ID of the export to be processed.
Example:
Set ExportOnDemandAgent = ExportDb.GetAgent(“(OnDemandExport)”)
Call ExportOnDemandAgent.Run(ExportProfileDoc.NoteID)
You should check the value returned by the call to the OnDemandAgent to ensure it completed
successfully. The return value is an integer where 0 indicates success.
Getting a handle to the export profile document
You can get a handle to the export profile document by looking it up by its Title in the
‘ExportsByTitle’ view.
Example:
Set ExportsByTitleView = ExportDb.GetView(“ExportsByTitle”)
Set ExportProfileDoc = ExportsByTitleView.GetDocumentByKey(“My Sample Export”, True)
Tip: Once you’ve got a handle to the export profile document you can update settings in it before
calling the OnDemandExport agent. The rest of this guide provides all the information you need to
update all settings in the export profile.
Page 6 of 17
Getting a handle to the collection of export item documents
The collection of export item documents associated with an export profile document can be
obtained by first getting a handle to the export profile document, retrieving the value of the
‘ProfileID’ field then performing a view lookup.
The following example demonstrates how to get a handle to the export profile document, retrieve
the collection of export item documents and iterate through each export item document.
Dim ExportDb As NotesDatabase
Dim ExportsByTitleView As NotesView
Dim ExportItemsView As NotesView
Dim ExportProfileDoc As NotesDocument
Dim ExportItemsCollection As NotesDocumentCollection
Dim ExportItemDoc As NotesDocument
Set ExportDb = New NotesDatabase([ServerName], [DbPathName])
Set ExportsByTitleView = ExportDb.GetView(“ExportsByTitle”)
Set ExportProfileDoc = ExportsByTitleView.GetDocumentByKey(“My Sample Export”, True)
Set ExportItemsView = ExportDb.GetView(“(Embedded-ExportMapping)”)
Set ExportItemsCollection = ExportItemsView.GetAllDocumentsByKey(ExportProfileDoc.ProfileID(0), True)
Set ExportItemDoc = ExportItemsCollection.GetFirstDocument
While Not ExportItemDoc Is Nothing
‘ Add your processing code here to update export item documents
Set ExportItemDoc = ExportItemsCollection.GetNextDocument(ExportItemDoc)
Wend
Page 7 of 17
EXPORT OPTIONS
The fields listed below relate to the 'Export Options' section of the export profile document. This
information specifies the title for the profile, output format of the export file, starting document and
the number of documents to export.
EXPORTTITLE
The title for the export profile document.
Data type: Text
Value: Specify the title for the export profile.
OUTPUTTYPE
The file format for the type of export being performed.
Data type: Text
Value: Set to one of the following values-
• ACCESS - Microsoft Access
• ATTACHMENTS – File Attachments Only
• CSV - Comma Delimited
• EXCEL - Microsoft Excel
• FIXED – Fixed Width
• HTML - HTML
• PDF – Adobe PDF
• TAB - Tab Delimited
• WORD - Microsoft Word
• XML – XML
Note: for exports to IBM Connections please refer to the ‘Export for Lotus Notes – LotusScript API
– IBM Connections’ guide.
OUTPUTFILES
Indicates if exported documents should be exported to a single file or exported to separate files (ie.
a file is created for each exported document). Applicable only to XML format.
Data type: Text
Value: Set to one of the following values-
• 0 – All documents are exported to a single file.
• 1 – Documents are exported to separate files.
Comments: For all export formats other than XML this field MUST be set to ‘1’.
Page 8 of 17
STARTDOCUMENT
The document to begin exporting from (ie. the number of documents to skip).
Data type: Numeric
Value: Set to one of the following values-
• 1 – Start exporting from the first document
• xx - Any numerical value to indicate the number of documents to skip before
beginning the exporting of documents.
MAXEXPORTDOCS
The maximum number of documents to be exported.
Data type: Numeric
Value: Set to one of the following values-
• 0 - All documents
• xx - Any numerical value to indicate the maximum number of documents to be
exported
This is a sample guide only. The remaining fields on the Export Profile form have been
removed.
Page 9 of 17
APPENDIX A – PROCESSING EXPORTS
After having written your customized code to create export profile and export item documents the
next step is to call the agents in the Export Utility application to process the export. You may call
one of the following agents depending on what your requirement is:
EXPORT SCHEDULER
This agent is normally scheduled to run periodically on your Domino servers to process scheduled
exports.
To have the Domino server process an export immediately you can set the schedule details in the
export profile document to ‘Once-Off’ and then call the ‘Export Scheduler’ agent. It will process the
Once-Off export immediately then set it back to a normal manual export.
ON DEMAND EXPORT
The On-Demand Export agent will process the specified export profile document immediately on
the Lotus Notes client. The NoteID of the export profile to be processed must be passed to the
agent.
Example:
Set ExportAgent = ExportDb.GetAgent(“(OnDemandExport)”)
If ExportAgent.Run(ExportProfileDoc.NoteID) = 0 Then
Print “On Demand Export agent completed successfully”
Else
Print “On Demand Export agent did not complete successfully.”
End If
You may also call this agent using the ‘RunOnServer’ method if you would like the Domino server
to perform the export.
Example:
Set ExportAgent = ExportDb.GetAgent(“(OnDemandExport)”)
If ExportAgent.RunOnServer(ExportProfileDoc.NoteID) = 0 Then
Print “On Demand Export agent completed successfully”
Else
Print “On Demand Export agent did not complete successfully.”
End If
Page 10 of 17
BACKGROUND EXPORT
Similar to the On-Demand Export agent the Notes Background Export agent will process the
specified export profile document but in the background on the Lotus Notes client.
To run this you MUST first write the Universal ID of the export profile document to be processed to
the Notes.ini file using the appropriate @Environment / SetEnvironmentVar function. The
configuration item to the write to the Notes.ini file is called ‘ExportDocUNID’.
After setting this you can call the NotesBackgroundExport agent to process the export. The agent
will read the ‘ExportDocUNID’ value so it can determine which export profile should be processed.
Example:
Call NotesSession.SetEnvironmentVar(“ExportDocUNID”, ExportProfileDoc.UniversalID)
Set ExportAgent = ExportDb.GetAgent(“NotesBackgroundExport”)
If ExportAgent.Run(ExportProfileDoc.NoteID) = 0 Then
Print “Notes Background Export agent completed successfully”
Else
Print “Notes Background Export agent did not complete successfully.”
End If
The RunOnServer method cannot be called with this agent.
Page 11 of 17
CHECKING FOR EXPORT ERRORS
After running an On-Demand export you can check if any errors occurred during the export
process. Error logs are linked to the export profile document and the following code demonstrates
how to lookup any errors that occurred when the export ran.
Dim ExportAgent As NotesAgent
Dim AgentResult As Integer
Dim CurrentDate As NotesDateTime
Dim NoteID As String
Set CurrentDate = New NotesDateTime(Now)
Set ExportAgent = ExportDb.GetAgent("(OnDemandExport)")
NoteID = ExportProfileDoc.NoteID
AgentResult = ExportAgent.Run(NoteID)
If AgentResult <> 0 Then
MessageBox "Export Failed - OnDemandExport Agent did not run successfully", 0+16, “On-Demand Agent Failed”
Else
Dim View As NotesView
Dim ViewNav As NotesViewNavigator
Dim ErrorLogEntry As NotesViewEntry
Dim ErrorLogDoc As NotesDocument
Dim ErrorLogDateTime As NotesDateTime
Set View = ExportDb.GetView("(ErrorLogsByExportProfileID)")
Call View.Refresh
Set ViewNav = View.CreateViewNavFromCategory(ExportProfileDoc.ProfileID(0))
If ViewNav.Count > 0 Then
' One or more errors have been found for this export. Iterate error logs in order of creation date
Set ErrorLogEntry = ViewNav.GetFirstDocument
While Not ErrorLogEntry Is Nothing
If ErrorLogEntry.IsValid Then
If ErrorLogEntry.IsDocument Then
Set ErrorLogDoc = ErrorLogEntry.Document
If Trim(Cstr(ErrorLogDoc.CreatedAt(0))) <> "" Then
Set ErrorLogDateTime = New NotesDateTime(ErrorLogDoc.CreatedAt(0))
Else
Set ErrorLogDateTime = New NotesDateTime(ErrorLogDoc.Created)
End If
If ErrorLogDateTime.LSLocalTime > CurrentDateTime.LSLocalTime Then
' Error log was created when the agent last ran
Messagebox "Error occurred during export: " & ErrorLogDoc.Error(0), 0+16, “Export Error”
Else
' Error log was created before the agent ran. No need to check any more errors
Goto Finish
End If
End If
End If
Set ErrorLogEntry = ViewNav.GetNextDocument(ErrorLogEntry)
Wend
End If
End If
Finish:
‘ Add additional code here…
Page 12 of 17
APPENDIX B – SUPPORTED CHARACTER SETS
The character set to use for target export files may be specified for various types of exports. The
recommended character sets to use are:
• DEFAULT
• UTF-8
• UTF-16
The following character sets are supported.
Character set Name Character set Code
Default platform character set DEFAULT
ASCII (US 7-bit ASCII, ISO-646) ASCII
ASCII (US-ASCII) US-ASCII
Cryllic (KOI8-R) KOI8-R
ISO Arabic languages (ISO-8859-6) ISO-8859-6
ISO Baltic rim languages (ISO-8859-4) ISO-8859-4
ISO Central European languages (ISO-8859-2) ISO-8859-2
ISO Cryllic languages (ISO-8859-5) ISO-8859-5
ISO Esperanto and Maltese (ISO-8859-3) ISO-8859-3
ISO Greek (ISO-8859-7) ISO-8859-7
ISO Hebrew (ISO-8859-8) ISO-8859-8
ISO Turkish (ISO-8859-9) ISO-8859-9
ISO Western European languages (ISO-8859-1) ISO-8859-1
ISO Western European languages (ISO-8859-15) ISO-8859-15
Japanese (EUC-JP) EUC-JP
Japanese (Shift_JIS) Shift_JIS
Japanese (ISO-2022-JP) ISO-2022-JP
Korean (EUC-KR) EUC-KR
Korean (ISO-2022-KR) ISO-2022-KR
Lotus Multi Byte Character Set (LMBCS) LMBCS
Simplified Chinese (GB18030) GB18030
Simplified Chinese (GB2312) GB2312
Taiwanese (EUC-TW) EUC-TW
Page 13 of 17
Traditional Chinese (Big5) Big5
UTF-16 (16 bit platform native byte order encoding of ISO-
10646)
UTF-16
UTF-16BE (16 bit big endian encoding of ISO-10646) UTF-16BE
UTF-16LE (16 bit little endian encoding of ISO-10646) UTF-16LE
UTF-8 (8 bit encoding of ISO-10646) UTF-8
Vietnamese (TCVN3) TCVN3
Windows Arabic languages (Windows-1256) Windows-1256
Windows Baltic rim languages (Windows-1257) Windows-1257
Windows Central European languages (Windows-1250) Windows-1250
Windows Cryllic languages (Windows-1251) Windows-1251
Windows Greek (Windows-1253) Windows-1253
Windows Hebrew (Windows-1255) Windows-1255
Windows Thai (Windows-874) Windows-874
Windows Turkish (Windows-1254) Windows-1254
Windows Vietnamese (Windows-1258) Windows-1258
Windows Western European languages (Windows-1252) Windows-1252
Page 14 of 17
APPENDIX C – DATA TYPES FOR EXPORT ITEMS
One or more export item documents must be created when exporting to the following formats:
• Comma Delimited
• Fixed Width
• Microsoft Access
• Microsoft Excel
• Tab Delimited
• XML
The data type to format values to in the target export file must be specified when creating export
item documents.
Listed below are the different data type values and descriptions. The DataType field in the export
item documents must be set one of the values shown below in bold. Note that the value is a String
value.
For all exports (except MS-Access):
1 – Rich Text
25 – MIME
768 – Numeric
1024 – DateTime
1074 – Names
1075 – Readers
1076 – Authors
1280 – Text (default)
For MS-Access exports only:
2001 – Boolean
2002 – Byte
2003 – Integer
2004 – Long
2005 – Currency
2006 – Single
2007 – Double
2008 – Date
2009 – Binary
20010 – Text
20011 – Long Binary
20012 – Memo (default)
20015 – GUID
20016 – Big Integer
20017 – Var Binary
20018 – Char
20019 – Numeric
20020 – Decimal
20021 – Float
20022 – Time
20023 – Timestamp
20030 – Date / Time
Page 15 of 17
APPENDIX D – SAMPLE CODE
The ‘Export Utility Sample Code’ application is available from AGECOM to licensed customers
upon request.
The sample code application has a script library containing all the functions and constant values
you’ll need to create and update export profile and export item documents in the Export Utility
application.
Sample agents for each type of export are also available in the sample application showing how to
create export profile and export item documents then call the export on-demand agent in the
export utility and display a summary of the results after the export completes.
This API Documentation should be used in conjunction with making customizations to the sample
code.
Page 16 of 17
APPENDIX E – CONFIGURATION SETTINGS
The Configuration Settings profile document contains items which control the operation of the
Export Utility. Each of the items are described below.
Getting a handle to the Configuration Settings profile document
The following sample code demonstrates getting a handle to the configuration settings profile:
Example:
Dim ExportDb As NotesDatabase
Dim ConfigSettingsDoc As NotesDocument
Set ExportDb = New NotesDatabase([ServerName], [DbPathName])
Set ConfigSettingsDoc = ExportDb.GetProfileDocument(“ExportProfile”)
Export Options
The fields listed below relate to the 'Export Options' section of the configuration settings profile
document.
REQUIREPROFILES
Indicates if databases which may be exported are limited to only those for which database profile
documents have been created for.
Data type: Text
Value: Set to one of the following values-
• Y – End users may only export data from databases for which database profiles have
been setup by the export administrator.
• N – End users may export data from any database on any server. (default)
MESSAGETEXT
The default text to add to emails when exported files are sent by email.
Data type: Text
Value: Enter the text for the default message.
The default message is: Please find attached file containing exported information.
SHOWFIELDTYPES
Indicates if the type of field is displayed next to field names when selecting fields to export.
Data type: Text
Value: Set to one of the following values-
• Y – Display field data types.
• N – Do not display field data types. (default)
This is a sample guide only. Remaining fields on the Configuration Settings form have been
removed.
Page 17 of 17
APPENDIX F – ACKNOWLEDGEMENTS
IBM, Lotus Notes, Domino, and LotusScript are registered trademarks of International Business
Machines Corporation.