HCL Connections Docs – 2.0.1 Update Issue

Lately I had an issue upgrading from HCL Docs 2.0 CR3 iFix009 to 2.0.1. While upgrading “Docs Editor” application, using upgrade/install scripts, I was blessed with the following error code:

2021-03-05 17:23:16,464 INFO –>IM:RegisterDocsInNews
2021-03-05 17:23:16,465 INFO Register Docs application in Connections News Started
2021-03-05 17:23:40,280 INFO Register Docs application in Connections News completed
2021-03-05 17:23:47,996 INFO –>IM:ReviseLotusConnectionsConfig
2021-03-05 17:23:47,997 INFO Register Docs application in LCC.xml
2021-03-05 17:24:03,913 INFO Exception: ‘ascii’ codec can’t encode character u’\xa0′ in position 32627: ordinal not in range(128)
2021-03-05 17:24:03,913 ERROR Error while executing command, now rollback previous changes…
2021-03-05 17:24:03,913 INFO –>IM:Rollback RegisterDocsInNews
2021-03-05 17:24:03,914 INFO Rollback successfully.
2021-03-05 17:24:03,914 INFO Remove temp dir…
2021-03-05 17:24:03,915 INFO Exception: Upgrade failed. Check log file for more detail.
2021-03-05 17:24:03,915 INFO –>IM:FAILED

Although it took me a lot of time to solve this issue, it is quite simple.  I don’t know how, but I had some “Non-breaking space” characters in the LotusConnections-config.xml file for which, as it turns out, Python 2.7 does not show a lot of love.

To solve this problem I have done the following:

  1. Login to the WAS Deployment Manager and check out the LotusConnections-config.xml.
  2. Create a backup of the file.
  3. Delete all “Non-breaking space characters.
    • I managed to do this only in vim editor, by using the following setting “set list listchars=nbsp:!”.
    • Delete all newly shown “Non-breaking space” characters.
    • For more information, take a look at the Stack Exchange post.
  4. Check the file back in.
  5. Synchronize all WAS nodes in the cell.
  6. Restart the installation.

After that, the installation should complete. I hope this helps. 🙂

Note that the Error code shown above lists the exact position in the “LotusConnections-config.xml” file where the problematic character was found in the first place, but this can be misleading as you could have more than one “Non-breaking space” character in the file, so make sure to delete all of those characters.

HCL Connections 7 – PDF Export Issues

After upgrading to HCL Connections 7, the new PDF Export feature didn’t work. By clicking on the new “PDF” button inside the Wiki Page and trying to export it as a PDF, I would get an error in the GUI. In my two environments where I have encountered this, I had to do the following steps.

  1. Install “wkhtmltopdf” software and additional fonts.

This step is very well documented in the official documentation. Albeit a bit hidden.

2. Modify the IC360 configuration parameters.

In order to do this, login to the WAS Administration Console or ISC, and navigate to “Resources –>Resource Environment –> Resource environment entries –> ic360 –> Custom Properties”. Make sure that the following configuration parameters are correct:

“http.hostname” should correspond with the FQDN you are using to access HCL Connections, for example “social.domain.com”.

“http.auth.admin.user” set to WAS Administrator username.

“http.auth.admin.password” needs to have the value of WAS Administrator password. When changing the password, just delete the whole value, including “{xor}” in the field, after saving, the password will automatically be encrypted with XOR.

For additional information about IC360 configuration parameters, refer to the official documentation.

3. Sync and restart IC360 Applications.

After doing the steps mentioned above, you should be able to export the HCL Connections content to PDF files.

HCL Connections – Do Not Forget To Install A New APNs Certificate For 2021

By default, the APNs certificates are valid for one year. The current APNs certificate for HCL Connections is going to expire on the 21st of March. You can update the APNs certificate by installing an Interim Fix provided by the HCL Connections development team, which can be obtained from the HCL Software License & Delivery Portal. There is an Interim Fix for basically all relevant versions of HCL Connections, 7, 6.5 CR1 and 6.0 CR6 and 6.0 CR3. For all details, take a look at the official article.

As soon as the APNs certificate expires, the users of the HCL Connections mobile app on iOS will not be able to get push notifications, which means that they will not get alerts or notifications from HCL Connections while the mobile application is running in the background.

Installing Interim Fixes for HCL Connections is fairly straightforward, for a step-by-step guide, refer to the official documentation. This particular Interim Fix will take about one to five minutes to install, depending on the environment.

HCL Connections Invite – Issues when using TDS/SDS as User Repository

Take care when deploying the HCL Connections Invite application using the TDS (Tivoli Directory Server)/SDS (IBM Security Directory Server) as user repository. The following information from the official documentation is wrong:

The following value includes the LDAP property used to map the user in LDAP to their Profiles GUID. In an Active Directory environment, for example, the default property is objectGUID. Other known defaults are entryuuid (IBM Security Director Integrator, formerly TDI),…

<profiles-connector>
             <entry>
                  <attributes>
                       <attribute>
                            <value>${ldap:objectGUID}</value>

First, the value of the Attribute in the “selfregistration-config.xml” is missing, this would be: “<key>com.ibm.snx_profiles.base.guid</key>”.

By reading the documentation, you would set the <value> parameter to ${ldap:entryuuid}, if you do that, you would get the following error:

00000660 SelfRegistrat W   Failed to get all the required attributes! required: ‘{​${​ldap:entryuuid}​=entryuuid, ${​ldap:sn}​=sn, ${​ldap:cn}​=cn}​’, received attributes: ‘{​sn=sn: Mail, cn=cn: <e-mail>}​’

The correct value for the parameter, when using TDS/SDS, would be “${ldap:ibm-entryuuid}”, so you should endup with the following:

<attribute>
                    <key>com.ibm.snx_profiles.base.guid</key>
                    <value>${ldap:ibm-entryuuid}</value>
                    <type>text</type>
                </attribute>

Although there are some comments in the “selfregistration-config.xml” showing the right information, a few colleagues/friends including me found them to be a bit “misleading”. This will surely be corrected in the future.

HCL Connections & Kerberos Authentication Protocol Issue

After implementing Kerberos Authentication protocol for HCL Connections, as described in the official documentation (HCL Connections and IBM WebSphere documentation) and restarting the whole environment, the “synchronization status” of the Nodes in the IBM WebSphere ISC Console appeared to be “unknown”. All the HCL Connections Applications were running, there were no errors in GUI and the SSO was working without any issues. From the logs of the node agents we could see that the synchronization with the deployment manager was taking place and completing successfully, only in the “SystemOut.log” of the WepSphere deployment manager I found the following error message:

000015c Krb5WSSecurit E SECJ9314E: An unexpected exception occurred when trying to run initSecContext() method : GSSException: org.ietf.jgss.GSSException, major code: 11, minor code: 41


major string: General failure, unspecified at GSSAPI level
minor string: Kerberos error formatting credential for delegation: 41
at com.ibm.security.jgss.i18n.I18NException.throwGSSException(Unknown Source)
at com.ibm.security.jgss.mech.krb5.g.a(Unknown Source)
at com.ibm.security.jgss.mech.krb5.g.a(Unknown Source)
at com.ibm.security.jgss.mech.krb5.g.initSecContext(Unknown Source)
at com.ibm.security.jgss.GSSContextImpl.initSecContext(Unknown Source)
at com.ibm.security.jgss.GSSContextImpl.initSecContext(Unknown Source)
at com.ibm.ISecurityLocalObjectTokenBaseImpl.Krb5WSSecurityContextImpl$1.run(Krb5WSSecurityContextImpl.java:508)
at java.security.AccessController.doPrivileged(AccessController.java:770)
at javax.security.auth.Subject.doAs(Subject.java:570)
at com.ibm.ISecurityLocalObjectTokenBaseImpl.Krb5WSSecurityContextImpl.initSecContext(Krb5WSSecurityContextImpl.java:273)
at com.ibm.ISecurityLocalObjectTokenBaseImpl.Krb5WSSecurityContextImpl.initSecContext(Krb5WSSecurityContextImpl.java:157)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.processInternal(SOAPConnectorClient.java:1285)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.getSecurityHeader(SOAPConnectorClient.java:1095)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplateOnce(SOAPConnectorClient.java:783)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplate(SOAPConnectorClient.java:697)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invokeTemplate(SOAPConnectorClient.java:687)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.queryNames(SOAPConnectorClient.java:599)
at com.ibm.ws.management.connector.soap.SOAPConnectorClient.invoke(SOAPConnectorClient.java:524)
at com.sun.proxy.$Proxy40.queryNames(Unknown Source)
at com.ibm.ws.management.AdminClientImpl.queryNames(AdminClientImpl.java:108)
at com.ibm.ws.management.AdminServiceImpl.queryNames(AdminServiceImpl.java:679)
at com.ibm.ws.management.connector.AdminServiceDelegator.queryNames(AdminServiceDelegator.java:113)
at sun.reflect.GeneratedMethodAccessor88.invoke(Unknown Source)
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:55)
at java.lang.reflect.Method.invoke(Method.java:508)
at com.ibm.ws.management.connector.soap.SOAPConnector.invoke(SOAPConnector.java:503)
at com.ibm.ws.management.connector.soap.SOAPConnector.service(SOAPConnector.java:335)
at com.ibm.ws.management.connector.soap.SOAPConnection.handleRequest(SOAPConnection.java:65)
at com.ibm.ws.http.HttpConnection.readAndHandleRequest(HttpConnection.java:733)
at com.ibm.ws.http.HttpConnection.run(HttpConnection.java:522)
at com.ibm.ws.util.ThreadPool$Worker.run(ThreadPool.java:1892)

After a quick Google search I found that this boils down to a problem with a hostname defined or spelled in upper case letters. As described in the following article:

https://www.ibm.com/support/pages/apar/PM66457

This article also mentions a custom variable which could be set to remedy this issue.

But before trying the custom variable out, I wanted to make sure that this was really the issue. I checked the DNS Server and all SPN records, I could not find any issues there. The output of the “hostname” and “hostnamectl” commands (the whole environment is running on RHEL), were all returning the hostname written in (all) lowercase characters. Only when looking into the “hosts” file of the deployment manager I could find the issue, there was a “127.0.1.1” entry stylized in “CamelCase”. I replaced the upper case letters in the “hosts” file with lower case letters and as soon as I have done that, all the nodes in the ISC console had the status “synchronized” and the error mentioned above did not appear anymore. The custom variable was not needed.

I hope this saves you some time! 🙂

HCL Notes Connections Plug-In – Login via SPNEGO not possible

If you are trying to use SPNEGO as the means for authenticating HCL Notes Connections Plug-In and you run into an issue, check if “Use the alias host name for the application server” option is used on Websphere Application Server and if that is the case try turning it off.

For some reason the HCL Notes Connections Plug-In cannot use SPNEGO authentication mechanism when this option is used on WAS. You can find this setting under “Global Security – Web and SIP security – SPNEGO web authentication”.

Depending on your DNS configuration and SPN entries created, this option may be needed for HCL Connections or other applications, so make sure you test everything appropriately after changing the SPNEGO settings.

HCL Connections – URL Preview Tip

If you have implemented or planing to implement the “URL Preview” feature for HCL Connections, make sure you import the Root Certificate for “Let’s Encrypt” certificate authority inside the java trust store.

By default, the root certificate of “Let’s Encrypt” certificate authority is not in the java trust store which the HCL Connections documentation suggests to use for URL Preview. Which means that if you do not import it manually, the URL preview won’t work for websites which are using “Let’s Encrypt” certificates.

HCL Connections Invite – Trace/Debug Parameters

If you are having issues with HCL Connections Invite, than the following Websphere debug or trace code might help:

com.ibm.lconn.registration.*=finest

HCL Connections Invite is assigned, per Default, to the WebSphere Homepage Cluster/Server. So this is where you have to set the parameter mentioned above.

This is how you can set the debug parameter during runtime. No restart needed.

HCL Connections – Configure access for the Tiny Editors Services through a HTTP proxy – Configuration/Documentation error

Take care when configuring access for the Tiny Editor through an HTTP proxy. The Documentation says to modify the “application.conf” in following manner:

ephox {
    proxy {
        http.proxyHost = someproxy.internal.corp
        http.proxyPort = 8080
        https.proxyHost = someproxy.internal.corp
        https.proxyPort = 8443
        http.nonProxyHosts = localhost|*.internal.corp
    }
}

If you follow the official documentation and do not set the values of “http.nonProxyHosts” in the double quotation marks the Tiny Editor WAS Application will start, but some features of Tiny Editor will not work (like Spellchecking). The correct will configuration looks like the following:

An example of proxy settings:

ephox {
    proxy {
        http.proxyHost = someproxy.internal.corp
        http.proxyPort = 8080
        https.proxyHost = someproxy.internal.corp
        https.proxyPort = 8443
        http.nonProxyHosts = "localhost|*.internal.corp"
    }
}

Hope this helps.

We Have Lost The “wasadmin” Account Password!

If you have lost the “wasadmin” account password or any other local WebSphere account, there is a rather simple way to recover it.

Just connect to the server where WebSphere Deployment Manager is running, via RDP or SSH, depending on the OS of the server, and open the “security.xml” file located under “<WebSphere_Installation_Directory>/AppServer/profiles/<Deployment_Manager_Profile>/config/cells/<Cell_Name>” for example “/opt/IBM/WebSphere/AppServer/profiles/ic-dmgr01/config/cells/ic-cell01”.

After that just search for the account name, for which you would like get the password, in the same line you should find the attribute “password”:

Then just copy the value of the “password” attribute, now we need to decode the xor encoded password. For that I am usually using the following Website: https://strelitzia.net/wasXORdecoder/wasXORdecoder.html

Just paste the encoded text and click the “decode” button, after that you should have the password.