I installed HCL Connections Docs 2.0.1 on top of an already installed HCL Connections 6.5CR1 with Docs Viewer. Usually a simple task, the installation was smooth, after the mandatory restart the Edit button in the files’ application appeared and all looked good, but when the users clicked on edit a white page was loaded.
I checked the application itself starting with a version check on https://mydomain.tld/docs/version and the version was displayed.
The funny part was that the test environment installed with the same script ran flawlessly with the same settings. I had an issue with the hostname of the environment when we started with Invite. Invite didn’t understand the single sign on domain, because the hostname has only two parts domain.tld. Invite got a fix and works now, but the first thought was maybe the two part hostname was again involved, and the test environment uses test.domain.tld which worked in Invite too.
The SystemOut.log showed following message when a user tried to open a file in the editor.
Some lines below there was an SSO error message with the domain.tld. So I still thought about the hostname.
So I installed a new test environment to double-check that the issue is not hostname related. The test server deployment worked fine with a two part hostname …
Back to the production server I started comparing everything with test, the JSON files are stored in git, so I could compare line by line. I checked the whole IBMDocs-config-directory, no success. Docs still loads the white page.
The environment is running about 6 years now and was updated from 4.0 to 4.5 to 5.0 to 5.5 and finally 6.5. The 6.5CR1 ran nearly a year until I installed Docs on top (Viewer was installed since the beginning and updated to 2.0.1 during the 6.5CR1 deployment).
So I searched the whole Docs stuff, double-checked conversion which was moved to Linux during the 6.5 migration, checked access rights and so on. Enabled tracing but there was nothing in the trace.log which would explain the error message:
NoSuchAlgorithmException sounded just weird. So I went through all documents about TLSv1.2 in the HCL documentation
and knowledge base
:
Some restarts later I just wanted to give up (which means opening a case with HCL), so I downloaded the git repository with all configs and started to put everything together. This time I had a look into LotusConnections-config.xml which looked somehow strange formatted.
<sloc:serviceReference
acf_config_file="acp-configkey__stoeps.xml"
bootstrapHost="admin_replace"
bootstrapPort="admin_replace"
clusterName="Util"
enabled="true"
serviceName="rte"
ssl_enabled="true"
>
<sloc:href>
<sloc:hrefPathPrefix>/connections/rte</sloc:hrefPathPrefix>
<sloc:static
href="http://cnx7-was.stoeps.home"
ssl_href="https://cnx7-was.stoeps.home"
/>
<sloc:interService href="https://cnx7-was.stoeps.home" />
</sloc:href>
</sloc:serviceReference>
There were way more line breaks than I would have expected.
Normally the xml looks like this:
<sloc:serviceReference acf_config_file="acp-configkey__stoeps.xml" bootstrapHost="admin_replace" bootstrapPort="admin_replace" clusterName="Util" enabled="true" serviceName="rte" ssl_enabled="true">
<sloc:href>
<sloc:hrefPathPrefix>/connections/rte</sloc:hrefPathPrefix>
<sloc:static href="http://cnx7-was.stoeps.home" ssl_href="https://cnx7-was.stoeps.home" />
<sloc:interService href="https://cnx7-was.stoeps.home" />
</sloc:href>
</sloc:serviceReference>
And the end of the file (genericProperty section):
<genericProperty name="com.ibm.connections.SSLProtocol">
TLSv1.2
</genericProperty>
<genericProperty name="icec.light">
true
</genericProperty>
Weird, but still the xmllint tool showed the file is valid XML (check in and out validated the XML too), and all Connections and Docs Viewer are working without any issue, but the formatting remembered me about the TLSv1.2 message in SystemOut.log.
So I gave it a try and reformatted the XML, so all whitespace was removed.
<genericProperty name="com.ibm.connections.SSLProtocol">TLSv1.2</genericProperty>
<genericProperty name="icec.light">true</genericProperty>
I synchronized the nodes and restarted all application servers to be sure that the new configuration was loaded. The Docs-Server now showed this message on startup:
Wow! No line break or algorithm exception.
I opened Files > Edit document and Docs loads the document and all looks good now. So for me, it looks like that Docs does not ignore Whitespace in the XML configuration and all other applications do.
Summary
I checked the git history when the XML was reformatted, and it was already there in 5.5, maybe earlier. I edit everything in VIM and I haven’t enabled linting or automatic code format there, but sometimes I have to use VS Code and I found that some XML add-ons format XML on save and there are settings which move attributes to new lines. So I suspect that this happened years ago, someone edited with Code (or something similar) and on save the code was reformatted, as no error appeared, the change was committed.
Lessons I learned
Always check LotusConnections-config.xml when an application shows an error. They all read base configuration from there. This is BTW the reason that you have to restart all Connections’ application after changing LotusConnections-config.xml.
Second, when you use a two part hostname in production, then use a two part hostname for your test environment too!
