Domino RESTAPI Bug and WorkAround

This is not my usual line of thought as an Admin, but sometimes, AdminOps is better than DevOps because troubleshooting is not an exact science.

While customers over the last year or so have been asking about the HCL Domino REST API, my reply is usually something like, I can install it, but you are on your own afterward, or I point them to a Developer friend.

To be fair, HCL will help them/me with getting started or "where is/How do I" questions. But this is about the bug my client and I discovered and how to work around it.

While updating the v1202FP3 servers to v14FP1, all went okay, even with the change in Java classes, until we got to the REST API server.

If you had downloaded and added my tasks update for the Admin client, you would see that RESTAPI was running on the machine, as I saw. I let the customer know I would upgrade it from 1.04 to 1.014.

Usually, it's not a big deal; you run a long string of commands or broken down into 4 lines like the example shown in the documentation which I prefer as my typing is not perfect.

java -jar restapiInstall-14r.jar ^ -d="C:\Program Files\HCL\Domino\Data" ^ -i="C:\Program Files\HCL\Domino\notes.ini" ^ -p="C:\Program Files\HCL\Domino" ^ -r="C:\Program Files\HCL\Domino\restapi" ^ -u

 You then type an A to accept the update, which will upgrade the REST API code.

It replaces the existing files with new ones and any updated files.

Great. I rebooted the server, and it looks like everything is up. The task view in the Admin client shows REST API is up.

Test a few things, but Swaager is not connecting to anything.

My initial thought was that the developers had some code that had been deprecated or maybe not valid with something in v14. I wasn't far off. I tried a few things to get it to work, and then I decided to look at the schemas. I found them deactivated, which seemed wrong to me, so I enabled one to test.

And it worked again.

Great! I did the same trick with the others, and they also worked.

One last test, shut down Domino and reboot the box clean to ensure it was ok.

No luck. Back to square one, but now the schemas all showed activated, but still just errors like this one:

This not being my first effort, I figured let's deactivate everything and reactivate it and test it.

Sure enough, it worked.

So, in my mind, the problem was somewhere between the REST API code and some type of flag on the schemas/databases that just wasn't being accepted.

Opened a ticket with HCL to discuss the bug I found.

After the usual back and forth, get us this, debug that, a copy of the NAB, a db, schema db, etc.. HCl said they could not recreate my problem, yet here it was.

We had an online meeting so the dev team could get a good luck at my testing and poke around deeper.

They agreed something was fishy and went off to look into it further.

In the interim, given this was a key production server, we wanted to revert back to the old REST API version, which worked fine prior to the upgrade. But would it work on v14, among other questions we had?

HCL and I discussed it with the customer, and this is how you revert to an older version.

We had the old code downloaded, which is key as sometimes HCL has a way to make older versions "disappear" from the public. The steps included:

1. Shut down Domino
2. Copy the Domino\restapi folder contents out from Domino to a backup space.
3. Once the RESTAPI folder is empty, you can then walk through the installation steps as I showed them above, but the last line instead of -u should be -a.
4. This will reinstall all you need(presuming all URLs, folders, etc are NOT being edited/changed)
5. Start Domino
6. Test

This worked well, and the customer was back up and running on V14FP1, albeit with the older REST API code. 

After a few days, we got back some information from HCL, which I quote directly below:

Problem:
REST API 1.014 Running the APIs in local swagger returns Error "Failed to Load API Definition"

Possible cause
The issue is that the scope's Server name is not correct.
This setting was not working correctly in older versions of DRAPI and was fixed in v1.0.6. It was pretty much ignored in v1.0.4.

Possible solution/Workaround:
With DRAPI 1.0.14 you have to add the CN name/hierarchical name of the Domino server instead of host name for example: CN=customerTest/O=HCLLabs in the Edit scope>>Server field>>CN=customerTest/O=HCLLabs or CustomerTest/HCLLabs
Earlier server name field in scope>>Server field was: Host name of the server i.e keithbrooks.com

Change it to either CN name or the hierarchical name of the Domino server or can be left blank stating any server that has this scope in the KeepConfig.nsf assumes the database / schema exists.

Moving further the product dev team is going to update the error message in the product code as 'You need to query a different server' so it makes more sense to the testing on affected DRAPI versions.

There you have it. My guess initially was partially correct. 

The configuration was correct for the old version, but because the customer did not upgrade the RESTAPI code along the way, they missed the changes in code at 1.06, which would have probably prompted an HCL ticket at that time as well, but it would have been easier for all of us to see as the issue at that time. as the change would have been fresh in their mind.

The story's moral is, of course, ABU or "Always Be Upgrading" because of security, code, and functionality adjustments over time. While we don't want to break production, sometimes you must do so for your benefit.

The second moral is to have a Development or Staging environment for these critical applications. In this case, the lower environment did not match the upper one entirely, so the problem was not seen when we updated the lower environment.

Domino V14 - A New User Capability - Mail Merge

I have asked for this for many years, and we got it in V14! 

This is my guide and first reaction.

If you have Admin Assistants or need to do your marketing, you need to use Word or some 3rd party to do what should be a simple effort.

HCL has given us a nice Mail Merge inside the notes client.

It may take some testing for your first one, but hang in there, it is much easier than other methods I have used.

I will elaborate on these topics below:

• Where is the Mail Merge option
• What you need to set up the Mail Merge 
• Creating your Mail Merge
• Previewing and Running a Mail Merge

Where is the Mail Merge option?

Naturally, the first place to get information is the HCL Documentation.

https://help.hcltechsw.com/notes/14.0.0/client/mail_create_mailmerge.html

I'd like to say this is well-documented, so someone who is not a developer or in IT can follow along.

But it isn't, which is one of my few issues and why I am writing this blog post.

Presuming you updated your Notes client to V14 and updated your mail file template to V14, Mail Merge is a newly added option in your Mail inbox view, when you select New > Mail Merge.

(1st screenshot is from the HCL Docs and presumably a Mac client, the 2nd is from my Windows client, How do I get the Stationery option in Windows?)
   

What you need to set up the Mail Merge 

Like most Mail Merges, you need your data, usually in a spreadsheet. HCL asks for Excel. I did not test any other spreadsheets.

The documentation says, but doesn't show or provide an example:

1. Create an Excel spreadsheet.

   Each column represents an aspect of the email body that will be personalized; each row should specify every user receiving the email and their personalized information.

2. Save the Excel file.

Took me a few tries to figure this out.

Naturally, every row should be a name, easy enough.

What is the column story exactly?

At first, I tried putting in details, but that didn't work right.

You need to provide a Title to each column.

I thought I needed the Notes designer name for each field, which would be crazy for an end user, but I was wrong. 

The title can be anything you want; this is cool because oftentimes, you get hard requirements for naming.

But make it easy to follow, as you will see in the next steps.

Here is an example of my simple test Excel file, without the attachment column.

Then save your file.

Creating your Mail Merge

This is what you came here for, and it is set up like a Wizard to help you.

After selecting New>Mail Merge and you select the Excel file you created, you will see this dialog box:

(1st screenshot is the documentation and a mac client, 2nd is my windows client. Note the differences, Stationery, and Attachments are not consistent)

If you click on the drop-downs you can see all the column titles you created and in my screenshot below, it recognizes some names directly.

Attachments in Excel are messy, but I tested using a local file link.

Once your basic fields are defined, you move to the memo form.

NOTE: The attachment(s) do not appear anywhere in this form! But they are there, as we will see shortly.

I did not know what to expect, so I created a "Body" column with the text I wanted. Normally, this is where you would paste your Word document or email template, so the body field I created is not needed, but I added the field there to show an example of fields and text.

People who are used to creating a Mail Merge will understand that you format the mail/body text like usual and you can include graphics and other changes to fonts, etc..

NOTE: In my testing graphics that appeared in the preview did not come through to the recipient.

Usage cases for this include bulk email senders, bill notifications, or other similar types of standardized messages, but if you don't need heavy, intensive graphics, this will do quite well for your marketing team, too. YMMV.

When you need your fields from the Excel file, click on the Insert merge field, and it will add the block. You can then move it or work around it, as i did with BODY below.

Once your mail is ready, click the Preview and Send button.

Previewing and Running a Mail Merge

I grabbed a side-by-side screenshot to show you how the form looked compared to the preview.

You can see the attachment is now shown and takes up the top part of the mail, I would prefer it be on the bottom, and this causes a different issue when NOT including attachments, as we will see below.

There is a little arrow and number for you to check your previews, and if you need to edit it, select the Continue Editing button, or if it is ok to send, click on the Send Mail Merge button.

The screenshot below is how the email looks in my Verse client, and Gmail, when I receive it.

NOTE: I need to verify what went on, but the Mail merge seems to include an auto bcc to the sender. Be nice if this was documented or stopped, because why would I want 100s of emails flooding my inbox?

Note the long line across and how the message doesn't start on top but only under that long line? That area is the attachment area.

My hope is HCL fixes this in the future because it looks like the mail got cut off or is missing something.

For a fresh Out of The Box benefit for people, I like it and hope to use it in my marketing efforts.

Hope this helps you and your team that needs mail merge and thank an HCL person for listening to the customer voice.

V14 Notes, Domino, Traveler are out Now

But your Notes install may have an issue.

NOTE: This post will be updated/edited as I figure out more of what is going on. Domino install-info after the Notes client info below.

I tried installing HCL notes, only comes in 64-bit now, on 2 different machines.

The installation was on top of the existing ones.

You may want to use the NICE tool to clean up the prior install first, might save you some headache.

1st is my usual laptop, 6 months old, Windows 11 Pro which already had 1202fp2(64-bit), and while it looked ok after about 20 minutes of waiting to finish, it gave me this, with no more details. It possibly happened while uninstalling or disabling something.

And then backed out the installation.

Subsequently, what I did was extracted the installer to a new location.

Then ran the setup, RunAs admin.

And this time it worked. Thank you Marc Thomas for the hint that there may be some extraction issue and to try it this way.

So, 2 clients installed, a server with traveler installed and it took about an hour and a half including troubleshooting/retries.

The 2nd installation on my Windows Server 2019 which is a hosted VM gave me this message:

And after trying again to click ok said this:

Never had something like this happen before during an install. 

I extracted the 1202 notes client as requested to get the MSI file and then the installation continued on its way. Also takes about 20 minutes.

So the Server install completed, even after asking for the 1202 code.

Now to figure out what is wrong with my Windows 11 install.

Domino Install

If you do a custom install, like I do, you will see the options to install Nomad and Ontime and I think Verse, my screen capture did not capture, sorry.

You will also see something my beta code did not do which is confirm the Domino login name for the startup services.

You may want to be careful with that if you don't know how you are logging in because your server may not start afterward.

Time to update was between 5-10 minutes including restarting the server and updating the Directory.

Traveler is also available and installs like usual in a few minutes.

Nomad works just like it did before, so the update did not change that, but it would be nice if it told us which version it was, instead of developer code which is 1.0.9.5525-3341. How do I know if mine was even updated? Maybe 1.0.9 was what was installed, but i already was at that level.

Verse works as well. 3.2, which I had installed, need to look up what version is installed as V14.

Ontime kept my configuration, and the booking settings still work as well.

Pretty cool when you think about all the stuff HC has to verify on the Domino side given these things are now included in the installation.