Give us feedback
domino-connector
Service icon

Domino Connector

version 1.0.3 (Compatible with OutSystems 11)
Published on 18 Apr by 
5.0
 (1 rating)
domino-connector

Domino Connector

Documentation
1.0.1

TL;DR on the Domino Connector

To run the Domino DB Browser app, you will need a Domino username and password and the URL of the Domino Server (which must have Domino Access Services running).

Once you configure these three pieces of info on the Domino DB Browser's configuration screen, the app's main page will attempt to connect to the Domino server's Domino Access Services API and pull the visible list of databases by that username.

Each Server Action call to the Domino Connector will require passing the URL, username, and password to use the API.

Background

HCL Domino is a document management and workflow platform based on the original Lotus Notes collaboration system that became popular in the early 1990s. When IBM purchased Lotus, the system - specifically the server technology - was named IBM Domino. Over a decade ago, HCL purchased the software from IBM. To learn more about the history of Lotus Notes/Domino, see this page. (For general info, visit the Wikipedia page.)

Most organizations using Notes/Domino (and hereafter just referred to as Domino) have moved mailboxes, calendaring, and most of their documents off the Domino platform onto more modern platforms. However, many organizations have built custom applications in Domino with complex logic and data that remain critical to the business.

This Domino component is provided by T4S Partners so that organizations with critical applications still on Domino can begin either:

  • Integrating their Domino applications into OutSystems solutions, as well as making this data more readily available to those solutions, or
  • Pulling the data from their remaining Domino applications to migrate to rapidly developed OutSystems applications that will replace the Domino applications

Either or both of these approaches can be taken depending on the needs of your business. Contact us about how to best decide between these application modernization options.

Key assumptions and constraints

Domino version 9.0.1 or higher required, with Domino Access Services enabled

This connector requires that Domino Access Services be enabled on the Domino Server being accessed. Domino Access Services provides a REST-style API, which the connector calls. See the HCL Domino documentation for information about enabling these Services.

Of course, Domino user credentials are needed - user name and password - and access to Domino Access Services and the target databases from which data will be pulled.

IT IS RECOMMENDED TO ONLY USE A HTTPS (TLS) ENDPOINT for Domino Access Services, as otherwise, the credentials will be "in the clear" and therefore not fully secured.

Need to have some understanding of Domino Data structures

Using this connector requires understanding how Domino data is logically structured with the Domino databases (NSF files). Domino databases are incredibly flexible in deciding how documents are grouped, hierarchically organized, and what data fields they contain. The connector only returns JSON objects that reflect each database's document definition structure(s). To use the connector, you will need to know how to extract the desired data from these JSON objects.

The Domino DB Browser is a tool that can pull the "raw" data from a Domino database; use this to determine how the data is structured in a specific database and build the appropriate Structures in Service Studio for deserializing the JSON.

High-Level Summary of Domino Database structure

The Domino connector currently allows you to retrieve data on three fundamental types of elements in a Domino Database:

  • Databases - Each database (represented by an NSF file internally)
  • Documents - contain the data and may reference other documents as parents or child documents.
  • Collections - Collections are defined sets of Documents. Documents may show up in multiple collections (sometimes referred to as views/folders)

Documents may be hierarchical; this structure is reflected in documents by using a "parent ID" and a position value in certain database designs. Documents can also have attachments (usually files).

The following image shows a collection of hierarchically structured documents based on the Discussion database template.

TreeView

All the above elements are referenced by a UID - a Unique IDentifier with a 32-character length hexadecimal value. These UIDs are required for many Server Actions of the Domino Connecter.

Using the Connector

The Domino Connector provides basic API access to an HCI Domino server using Domino Access Services. All calls to a Server Action provided by the Domino Connector requires:

  • The base URL of the Domino server (e.g., https://www.MyDominoServer.com )
  • The username and password of the user (or service account) with appropriate access to the database(s) from which data will be pulled

Most Server Actions also require the database name to be passed in.

  • The database "name" (usually the file name of the NSF file, such as "TeamADiscussion.NSF")

The relevant UID needs to be passed into the Server Action for accessing collections and documents.

Here is the current set of Server Actions provided by the Domino Connector:

ListOfServerActions

These correspond to similarly named API endpoints of the Domino Access Services. Each server action returns the JSON provided by the Domino Access Services endpoint. Further details on the Domino Access Services endpoints for Domino 9.0.1 can be found here.

General usage pattern of connector

The typical use of the connector will take these steps:

  1. Either look up the database name using GetDatabases or have the target database name
  2. For that database name, GetCollections to find the desired collection and get its UID
  3. Use GetCollectionEntries to see what's in the collection and get Document UIDs.
  4. Get multiple or single Documents (without attachments) using GetDocument
  5. Get attachments using GetResource with the attachments' "URL paths" from the document data

Using the Domino DB Browser

The Domino Connector also includes a sample application called the Domino DB Browser.

To use this application, make sure the following forge components are installed in your environment (in addition to the standard OutSystems components and extensions):

Configuring the application

Click on the Configure menu item to open the configuration screen and enter the three required data for connecting to the Domino server:

SetDominoAccessInfo

Browsing the Domino Server data

Once configured, the application will pull the list of databases on the Domino server (and visible to the configured username). This list will be visible in the tree.

ListOfDatabasesInTree

The JSON of the list of databases will also be shown in the "raw JSON" and the table widgets on the right side of the screen.

DataWidgets

You can then click on nodes in the tree. Once a node is clicked, the application will pull the data for that element in the database and (when appropriate) expand a subtree and show the data returned in the Raw data and grid widgets.

You can also use the following buttons (when active) on under the Raw Data widget:

  • Save Results - This will save the JSON contents of the Raw Data widget to a file
  • Save All Docs - When viewing the raw data of a collection's entries, this button will retrieve the JSON for that collection's top-level documents and download a zip file containing those JSON document files.
  • Save Attachments - When viewing a Document with attachments, this button will present a new screen with the list of attachments. You can then select the attachments to retrieve, combine them into a zip file, and download them as a single zip file. The following image shows an example of this screen:

AttachmentsScreen

Possible issues encountered

Access to Domino databases and their contents is controlled at every level (database, collection, document, resource). If the username used to access the server does not have appropriate access permission for a specific element, a 403 error will be returned. This is correct behavior.

Accessing some databases may result in the Domino server redirecting to the web login page, even when the username/password seems correct. This will also result in an error.

In both cases, you should be able to continue using the Domino DB Browser application to access elements that the configured user does have access to.

Specific API Notes

The Domino Connector focuses on the Document API endpoints of Domino Access Services; these endpoints are described in this section of the online HCL documentation.

Query Parameters of API calls

Some connector Server Actions accept additional parameters that get passed on into Query Parameters of the API call. Unless otherwise specified, if a Server Action does not take in additional parameters, default values for Query Parameters will be used in the API calls to the Domino Access Services.

Attachments retrieved separately from the document

The GetDocument Server Action of the Domino Connector does not retrieve and return the contents of the attachments. This was done to avoid situations where many attachments are retrieved in a single call (avoiding timeout). The retrieval of attachments is completed using the GetResource Server Action. Internally, the GetDocument results in an API call where the query value "multipart=false" is specified.

Page Size and Staring Index

The Server Action GetCollectionEntries uses default query parameters, which means that it will use the maximum page size configured on the Domino server. This means GetCollectionEntries will only have a number of documents lower than or equal to this maximum page size. Domino Servers have a default maximum page size of 100.

To access more than 100 documents in a collection, you need to call GetCollectionEntries multiple times, keeping track of which Starting_Index to start at. This will also return up to the maximum-page-size count of entries, starting at a particular index in the set of entries of the collection. You can also specify smaller page size, up to the maximum page size set on the server.

Therefore, to access a large document, multiple calls will need to be made to GetCollectionEntries with an appropriately increasing Starting_Index. The collection object itself will contain the count of entries.

To change the maximum page size configuration on a Domino Server, contact your Domino administrator. For additional information on the use of page size, see this webpage.

Setting up Domino Access Services

Information about setting up Domino Access Services can be found in this online manual.