How to Access Domino V10 Using Node-RED
One of the most significant, game-changing features of the Domino V10 release is the ability for people to use the Node.js programming model.
As part of this evolution, Domino V10 includes:
- the “AppDev Pack,” which is the server-side component that allows a Domino V10 installation to support a new set of APIs and the new Domino Query Language (DQL)
- and the “domino-db NPM” component, which provides a Node.js package that allows Node.js developers to simply and easily create applications that make use of the features exposed by the “AppDev Pack”
This article focuses on how a power user can, transparently, use the “domino-db NPM” component by means of the new “Node-RED dominodb package” (see this link for more details). This new Node-RED package aims to provide a very simple and programmer-friendly abstraction for the APIs exposed by the “domino-db NPM” package in order to make it simple, even for not Node.js experts, to create integrations with Domino V10 with very little or no programming skills.
A New Set of APIs
The APIs exposed by the “domino-db NPM” component allow to perform CRUD operations on a given Domino database. Those APIs are described in the README.md and Reference.md files included in the “domino-db NPM” package. There are, roughly, three types of APIs:
- APIs that work on “sets” of documents. With these, you can:
- Get a set of documents specified either by a DQL query or by a list of unique IDs
- Replace a set of documents (or a set of items within the documents) specified either by a DQL query or by a list of unique IDs
- Delete a set of documents (or a set of items within the documents) specified either by a DQL query or by a list of unique IDs
- Create a set of documents
- APIs that work on a single document:
- You can read, replace, delete or create a document specified by its unique ID
- Service APIs:
- These APIs allow you to connect to a Domino Server, to select a Domino database to work with, to get information about the connection that has been established. An interesting service API allows the programmer to explain a DQL query before running it. It can become extremely useful when evaluating the optimal way to query a large Domino database.
This may quickly become an obstacle for power users or for Domino programmers who are more focused on the business logic and/or on the data that need to be manipulated. Here is an example of the code fragment that is required to create a single document using the new APIs:
Node-RED, which crisply defines itself as “flow-based programming for the Internet of Things,” is the tool that we have used to abstract the use of the standard APIs exposed by the “domino-db NPM package.”
Roughly, we encapsulated the access to the standard APIs as Node-RED nodes and we provided a simpler way to execute those APIs as part of a “flow.” Information about this new Node-RED package is available here.
Let’s explore this.
The Domino V10 Node-RED nodes
The “node-red-contrib-dominodb” Node-RED provides the following nodes:
Each node implements all the code (and error management) to properly connect to a Domino server and to a selected Domino database; you, as the creator of the Node-RED flow, simply need to select the right instance of the “dominodb node” on which the node will act upon.
Most of the nodes encapsulate the use of more than one APIs, thus allowing you to select which functional operation to execute instead than spending your time in understanding which API (and which parameters) to use.
The list of available nodes is shown under the Domino V10 category on the left palette of the Node-RED editor, as shown here:
This simple set of nodes can be used to quickly and safely access to, virtually, all the APIs exposed by the “domino-db NPM” component. The “domino-db NPM” component is a prerequisite for the Node-RED package and needs to be installed before the “node-red-contrib-dominodb” Node-RED package is downloaded (please refer to the installation section here for details).
A detailed article explaining the behavior of this new Node-RED package is available in the “docs directory” of the relevant Github repository.
The New Domino-db Node-RED Nodes in Action
Quickly integrate with IBM Connections
Let’s suppose that we have a Domino application which displays some quotes. Each “quote record” has several attributes (“account-number,” “customer,” “amount,” “total,” “part-number,” etc.).
One of these properties (that we inherited from whoever designed our Domino application) is “seller”: this property holds the “email address” of the seller who is responsible for that quote.
We are asked to make our Domino application friendlier by displaying the “real name” of the seller instead of her email address.
It turns out that all the sellers are in my organization and that my organization has deployed IBM Connections. The IBM Connections profiles module holds the information about each person in my organization: so, it would be logical to think that I would use IBM Connections to get the “real name” of the seller. But it would not be logical at all to manually add the “real name” to each record, right? 🙂
We have three possibilities to address this challenge:
- We could use the new Domino V10 LotusScript HTTP classes to build an agent which, for each record, would go and fetch the “real name” from IBM Connections given the “email address”
- We could use the new “domino-db NPM” component and build a Node.js application which would do the same but using the new APIs
- We could use the new “Node-RED dominodb” package to quickly do this
Obviously, here, in this article, we are going to choose the third option so that we can show the power and simplicity of the new “Node-RED dominodb” package.
We also assume you have installed the IBM Connections Node-RED package and configured it to access to your IBM Connections organization.
Get the Documents from Domino
Let’s open Node-RED and create a new flow. We will use the “Get Documents” node to retrieve the information from Domino:
Follow these steps:
- Let’s open the “Get Documents” node in order to configure it.
- The first thing we need to do is to create a connection to our Domino V10 server and to the Domino database holding our quotes application.
- We click on the pencil icon associated with database item.
Follow these steps:
- We enter the information that identify our Domino V10 server and the Domino applications database.
- We give a name to this configuration so that we can reuse it later.
- We, then, click on the “add” button to save the configuration.
When we come back to our initial “Get Documents” node we can complete the information as follows:
We have specified:
- That we want to retrieve document via a DQL query.
- The query is @all.
- That we want to retrieve the items status, customer, accountNum, description, seller.
- And that we want to name this node “My Quotes App.”
We click the “done” button and, then, we add an “inject” and a “debug” node to test what we have done (don’t forget to hit the “deploy” button to make your flow executable!).
Once you click on the “purple square” on the left of the “Inject node,” you will see the results appearing in the debug console on the right:
Now, we need to extract the seller information from each of the results and to pass it to the Get Profiles node from the “IBM Connections Node-RED package.”
Retrieve the information from IBM Connections
Let’s modify our flow as follows:
We added a “Function” node named “Extract Seller.”
- Extract the seller and @unid information from each of the results coming from the “My Quotes App” node
- Create an object (outMs) that will be passed to the IBM Connections “Get Profiles” node. Actually the outMsg.DDB_unid attribute is inserted in order for the “Get Profiles” node to transparently pass it further: we will need this information to update the Domino record later!
We also added an IBM Connections “Get Profile” node which is configured in this way:
This configuration, roughly, instructs the node:
- To get information for “somebody else.” This “somebody else” is what is specified in the target attribute of the out message we built in the previous “Extract Seller” node
- To retrieve the “userid” and “name” attribute from the IBM Connections server specified by the Server input in the configuration
So, at this point, we told the node:
- To retrieve the records from the Domino application
- To iterate through the results and, for each result, to retrieve the “name” and “userid” attributes from IBM Connections associated with the seller item in the relevant Domino document
Let’s hit the “deploy” button and execute again the flow (by clicking on the purple square on the left of the Inject node). The results will be shown here:
For each seller, you will see a response from IBM Connections. The response contains the “userid” and “name” attribute as we requested.
Update Each Domino Record
Now, we want to update each Domino record by adding a “name” attribute which contains the name of the seller as reported by IBM Connections. Let’s modify our flow in the following way:
We added a “function” node (named “Extract Name”) which is configured as follows:
The msg.DDB_itemValues adds the Name property (with a value coming from the “Get Person Name” node). This information is passed to the “add name attribute” node which is configured as follows:
This node gets the “item values” and the “DocUnid” values from the output of the previous node (msg.DDB_itemValues and msg.DDB_unid), and hides the complexity of using the “domino-db NPM” API directly.
Let’s hit the “deploy” button and execute again the flow (by clicking on the purple square on the left of the “Inject” node). The results will be shown here:
For each document in the Domino database, we added the “name” attribute. The msg.DDB_doc output attribute (highlighted in the above picture) confirms that a new “name” attribute was added to the Domino document.
Note: We could have done the whole operation in bulk, but this would have made this simple example a little bit more complex and outside of the scope for this.
Let’s go and modify the form in the Domino application to display the modified records:
This simple and short tutorial shows you how quick it is for someone, who is neither a deep expert in Node.js or LotusScript, to create an integrated solution which makes use of a Domino database together with information and processes coming from other systems.