LotusScript API Reference Guide - AGECOM · While the documentation is aimed primarily for...

Export Utility for

IBM® Lotus Notes® / Domino®

LotusScript API Reference Guide

Sample Only

© AGECOM

https://www.agecom.com.au

https://www.agecom.com.au/

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

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.

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.

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.

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

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


• 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’.

of 17

STARTDOCUMENT

The document to begin exporting from (ie. the number of documents to skip).

Data type: Numeric


• 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


• 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.

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

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.

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…

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

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

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

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.

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


• 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


• 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.

of 17

APPENDIX F – ACKNOWLEDGEMENTS

IBM, Lotus Notes, Domino, and LotusScript are registered trademarks of International Business

Machines Corporation.

LotusScript API Reference Guide - AGECOM · While the documentation is aimed primarily for...

Documents

Transcript of LotusScript API Reference Guide - AGECOM · While the documentation is aimed primarily for...