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.
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:
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.
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.
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.
The Domino connector currently allows you to retrieve data on three fundamental types of elements in a Domino Database:
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.
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.
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:
Most Server Actions also require the database name to be passed in.
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:
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.
The typical use of the connector will take these steps:
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):
Click on the Configure menu item to open the configuration screen and enter the three required data for connecting to the Domino server:
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.
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.
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:
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.
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.
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.
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.
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.
Information about setting up Domino Access Services can be found in this online manual.