Ben Langhinrichs

Photograph of Ben Langhinrichs

E-mail address - Ben Langhinrichs

Recent posts

Mon 11 Jan 2021

REST plus RPC: building the JavaScript for RPC calls

Wed 6 Jan 2021

REST plus RPC: the right data in the right format, and no more

Tue 5 Jan 2021

REST plus RPC: Do the demo backward

January, 2021
     01 02
03 04 05 06 07 08 09
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30

Search the weblog

Genii Weblog

Branching out: A few terms

Thu 16 Jan 2020, 02:42 PM

by Ben Langhinrichs
Inline JPEG image
Following up on my previous post, The tree you are busy hugging has new branches, I am starting a series of posts on how to explore those new branches. As a warning up front, I am not close to being an expert at this stuff, but maybe that is good. I hope you will follow this learning journey with me. The image above is shamelessly stolen from Bruce Elgort who posted it today. I will attempt to teach and, with any luck, we'll both learn someething. Btw, if you are one of those lofty gurus who knows more than I do (a low bar, I'm afraid), please don't hesitate to leave a comment here so I can correct and learn myself..
Node.js, so far as I can tell, is a way of taking JavaScript and making it more robust and speedy, as well as allowing some uses that were difficult before. It is implemented as a runtime environment outside of a browser, which means you can use Node packages standalone or in non-browser applications as well as in a browser. It is event-driven which goes along with HCL's direction (or perhaps HCL is going along with its direction?), and is built on a compiled C++ core so is very fast and very scalable. As IBM or HCL might call it, Enterprise Ready.
Like many things in the modern web world, there are multiple and somewhat incompatible versions of absolutely everything. Thus, if you go out to download NodeJS, which is freely and easily available, the version you find will be either 12.x.x or 13.x.x. But, of course, those aren't the versions you want. You will need the latest version of10.x, which you can find at the straightforwardly named As much as you can trust anything these days, you can trust downloads from Some versions of Node.js are marked with an LTS designation. LTS means Long Term Support, and it basically implies that an Enterprise wanting Enterprise Ready stuff can rely on that version in the long term. Thus, 10.x is dubbed LTS, and specifically "Dubnium" because everything on the web has to have a silly nickname so that you know developers are cool froods and not money-grubbing capitalists.
npm is the grand installer of things in the JavaScript and Node world. In JavaScript and Node, there are packages which you add in the same way you might add a LotusScript library, but they can be publicly or privately available. You may be familiar with packages from the plethora of JavaScript frameworks. (I hate the word framework. It brings to mind too many failed Lotusphere sponsors who over-promised and under-delivered, all while wearing excessive amount of black clothing and serious expressions.)
Fortunately, npm comes along with Node.js by default, so if you install Node.js, you will get npm for the same low, low price of free with no extra effort. 
The AppDev Pack is HCL's bundling of a few things you'll need to run Node JS stuff with HCL Domino 11.  You can download the AppDev Pack 1.0.3 from FlexNet where you get your Domino 11 downloads. Elements of the AppDev Pack include the following components. More documentation can be found here.
  1. Proton - The server addin which handles all the Notes/Domino logic. In true client/server fashion, the Node JS stuff from the client is packaged up and sent to Proton. Then, the DQL is resolved and reads/writes executed and the return value go back to the client. 
  2. domino-db - This is the package which your Node code will reference directly. It has six classes, though that is a bit deceptive. Almost everything in the package is for CRUD operations, though some of these are very powerful as they can do bulk actions on many documents.
    1. The DominoDB class is kind of like the NotesSession class in LotusScript in that it is instantiated once and then other stuff is accessed using it. It has one method and no properties. 
    2. The Server class is created using that useServer method from the DominoDB class.. It has three methods, but only one is a true method which gives the Database class. The other two are gets for properties.
    3. The Database class is created using the useDatabase method from the Server class. This is the closest you get to a true class like the NotesDatabase class in LotusScript. It has eighteen methods and a couple of other gets for properties. Most of the methods are for bulk operations based on DQL selections.
    4. The Document class is created using the useDocument method from the Database class. This is a parallel to the NotesDocument class in  LotusScript, and has seven methods for accessing, replacing, and deleting items and attachments.
    5. The BulkResponse class and DominoDBError class are both encapsulated ways to hand back information on the results of an action. The former lets you know the status of a bulk operation while the latter lets you know a bit about what went wrong when something did go wrong. 
  3. IAM - This is an authentication piece which allows for OAuth 2.0 scopes to be authenticated to user ids in the ID Vault (or locally on the server?). I don't know a heck of a lot about how it works, but it has three components:
    • domino-iam-service: A Node.js based lightweight server, which is deployed along with a Domino server to provide the whole IAM service.
    • oauth-dsapi-extension: A Domino extension to enable Domino to trust IAM and consume tokens that IAM grants to your application.
    • node-iam-client: A Node.js module to assist your Node.js application to talk with IAM. Java, .Net, and other applications can access IAM directly through IAM's RESTful APIs.
Domino Access Services, is a DSAPI way of reading/writing to Domino data using REST web services. It has been around a long time, but I think the intention is to have it get more powerful as part of HCL's modernization of web development in V11 and beyond. One of the long time gripes about DAS has been its security, and it appears that the IAM service allows for greater adherence to user-based security in DAS, meaning that it will get used a bunch more.
This may all be a lot for us tree huggers, but we can get it. For now, keep this post in mind as a resource. If you have questions or comments or thoughts, or even just want me to know I am not alone on my journey, please leave a comment.
Posts in this series: 

Copyright 2020 Genii Software Ltd.

What has been said:

1111.1. Ramazan Salpagarov
(01/16/2020 02:11 PM)

Hi, Ben

You are not alone :)

I wait some more functionality in DQL for start use it in my work.

So I hope you will wrote more and more great articles and will help through them me and all developers in the world :)

1111.2. Patrick Kwinten
(01/17/2020 02:22 AM)

thanx for explaining the terminology. I guess I will need a cheatsheet for DQL too soon

1111.3. Ben Langhinrichs
(01/17/2020 05:23 AM)

I'll focus on DQL in a later post, but not until I understand it at least a little better. All part of the journey.