Denodo Domino Reader Custom Wrapper - User Manual
Introduction
This document contains information to use the Domino reader custom wrapper.
IBM Lotus Domino is a server product that provides enterprise-grade email, collaboration capabilities, and custom application platform. It can be used as an application server for Lotus Notes applications and/or as a Web server. It also has a built-in database system in the .nsf format.
The .NSF extension stands for Notes Storage Format (.nsf), which is a database format, also called application, commonly used by Lotus Notes clients and Domino servers.
Unlike other databases, such as Oracle and SQL Server, Notes doesn't have a relational database structure.
Lotus Domino databases can be accessed from Denodo via ODBC or via custom wrapper that uses the Lotus Domino Java API.
Using the Custom Wrapper
Introduction
This custom wrapper accepts host, port, user name, password and Domino database, reads all documents contained in the given database and downloads any existing attachments if specified by the user.
It allows specifying:
- If the content of the attachment is to be returned as a binary field in the output (e.g. in order to be indexed)
- What happens when two attachments have the same name (overwrite or rename)
- A comma-separated list of custom fields to be retrieved from Domino database.
If there is an error processing any of the email messages, the NotesId and error for that document is stored and the wrapper execution continues for the rest of the documents in the database.
When execution finishes, a list of ids for which processing has failed (if any) is returned.
In order to use the Lotus Domino Custom Wrapper, you must import its binary .jar into VDP. From the denodo-lotus-domino distribution, you have to select the denodo-lotus-domino-customwrapper-{version}-jar-with-dependencies.jar file and upload it to VDP using the File > Extensions > Jar management entry of the VDP Administration Tool top menu.
Besides its own .jar, the custom wrapper requires a library from the Lotus Domino installation in order to perform local data access, and a different library for remote access. For local access (which requires your Lotus and Denodo installations to be in the same machine) the notes.jar library is required. For remote access, the ncso.jar library is required. If you need to access several databases both locally and remotely, both of them will be required. These libraries can be usually located at the Lotus Domino installation folder, specifically at IBM\Domino\jvm\lib\ext.
Creating the Domino Custom Wrapper DataSource
The Lotus Domino libraries from IBM should now be obtained separately from your Lotus Domino installation. These are notes.jar for local access and ncso.jar for remote access. In order to make these libraries available to the VDP server, they should be copied into the $DENODOHOME/extensions/thirdparty/lib folder and the server should be restarted afterwards.
In order to create a new Lotus Domino data source, the “Custom” option must be selected in the data source menu (File > New... > Data Source > Custom).
Once this option is opened, click on Select Jars and select denodo-lotus-domino-customwrapper-{version}-jar-with-dependencies.jar. Finally, you only have to fill in the Name of the Data Source:
Figure 1: Custom data source form
- Name: data source name.
- Class name: when selecting the jar, Virtual DataPort Administration Tool fills in the content of this field with the value: com.denodo.connect.domino.DominoReaderCustomWrapper
When all the fields are correctly filled in, click save and the data source is created.
Creating a Base View
In order to create a base view the following input parameters are needed:
- DOMINO server : Domino server host name or IP, e.g. localhost or 192.168.1.3. This parameter should be left empty for local access.
- Port: Domino server port, e.g. 63148.This parameter should be left empty for local access.
- User: User name to connect to the Domino server.
- Password: User password.
- Pass-through session credentials: if selected, VDP will use the credentials of the current session to connect to the Domino server.
- DOMINO database: Domino database, e.g. mail.nsf
- Download Attachments?: boolean field that indicates if the attachments should be downloaded to a local folder.
- Download path: path for attachments, e.g. C:/attachments/. The directory must exist. Default directory is C:/
- Overwrite Attachments?: boolean field that indicates if attachments should be renamed or overwritten if duplicates exist.
- Return attachment as binary?: boolean field that indicates if wrapper should return contents of the attachment as binary.
- Custom fields: comma-separated list of custom fields to be retrieved from Domino database, e.g., field1,field2,field3. Can be left empty. All of them will be shown as a text field in VDP, including the lists of Domino.
Note: The directory to which attachments are going to be downloaded must exist. Otherwise the following exception might be raised:
ERROR 20130206095159314 com.denodo.connect.domino.DominoReaderCustomWrapper - Exception executing wrapper. NotesException: Could not detach file |
Figure 2: Custom Wrapper Form
Figure 3: Custom Wrapper base view
How to Query the Base View
If we execute SELECT * FROM domino_connector we are going to obtain all email messages with their attachments:
Figure 4: Select * from domino_connector
If we drill-down the attachments:
Figure 5: Attachments
Figure 6: Attachment type
The attachments are downloaded to the indicated folder.
Where clause
We can execute queries with different WHERE clauses. These WHERE clauses will be delegated depends on the fields in the clauses and the operators used.
The allowed operators are AND and OR. If these operators are included in the WHERE clause, they will be delegated to the custom wrapper. This means that the search will be done directly in the Lotus Domino Server.
Fields are dealt with in a way similar to operators. Depending on the fields in the WHERE clause, the search will be or not be delegated. The delegated fields are:
- SendTo
- CopyTo
- BlindCopyTo
- AltForm
- Classification
- From
- Principal
- Sign
If you try to use other fields in the WHERE clause, the query execution will not be delegated, i.e. the custom wrapper execution will return all the documents and Vitual DataPort will filter the documents in order to return only the expected results.
Query examples
Example of execution that finishes without errors
In vdp.log (asumming DEBUG level enabled for com.denodo.connect.domino) you should get:
DEBUG 20130409181942931 com.denodo.connect.domino.DominoReaderCustomWrapper - [DOMINO] Wrapper execution finished with no document processing errors |
In VDP Admin Tool you should get:
Figure 7: Example 1
Example of execution that finishes with errors for some documents
In VDP Admin Tool you should get:
Figure 8: Example 2
If you refer to vdp.log at the end of the wrapper execution you should get a summary:
941991 [48-01.06-cw_database.domino_connector] ERROR 20130411103351626 com.denodo.connect.domino.DominoReaderCustomWrapper - [DOMINO] Errors when processing '1' documents with Note IDs: '[1172]' #################### ERROR SUMMARY ##################### 941993 [48-01.06-cw_database.domino_connector] ERROR 20130411103351628 com.denodo.connect.domino.DominoReaderCustomWrapper - Processing document with Notes ID '1172' got the following error: com.denodo.connect.domino.commons.exception.UnsupportedClassException: Embedded object 'Paint.Picture' for document with Note ID '1172' has not been processed. Type 'EmbeddedObject.EMBED_OBJECT' is not currently supported, only EmbeddedObject.EMBED_ATTACHMENT is. at com.denodo.connect.domino.DominoReaderCustomWrapper.run(DominoReaderCustomWrapper.java:377) at com.denodo.vdb.misc.datasource.MyDataSource$1$1.doRun(Unknown Source) at com.denodo.vdb.engine.wrapper.raw.my.MyAccessImpl.doRun(Unknown Source) at com.denodo.vdb.engine.wrapper.RawAccess.run(Unknown Source) at com.denodo.vdb.engine.thread.d.if(Unknown Source) at com.denodo.vdb.engine.thread.c.run(Unknown Source) |