Troubleshooting / FAQ
Connecting to HCL Connections using HTTPS with Self-Signed Certificates
If your HCL Connections server uses a self-signed certificate, configure the agent to trust it using one of the two options explained below.
In both cases, first download the certificate from your HCL Connections server:
URL=your-hcl-connections-server.com:443
openssl s_client -connect $URL -showcerts < /dev/null 2>/dev/null | openssl x509 -outform PEM > server-cert.pemOption 1: Use a Custom Keystore
Create a keystore containing the server certificate and configure it in the agent:
keytool -import -alias hcl-connections-cert -file server-cert.pem \
-keystore connections-truststore.p12 -storetype PKCS12 \
-storepass changeit -nopromptIn the connector, enabled useCustomSslKeystore and upload the created
connections-truststore.p12, also configure these settings:
-
raytion.connector.agent.connections.server.sslAuth.keyStoreType=PKCS12 -
raytion.connector.agent.connections.server.sslAuth.keyStorePassword=changeit -
raytion.connector.agent.connections.server.sslAuth.keyPassword=<password>(optional, see below)
Note that - only certificates in the custom keystore will be trusted. - the keyPassword is only required if the keystore contains a private key for client authentication and that key uses a different password than the keystore itself. For truststore-only use cases (no client authentication), this parameter is not needed.
Option 2: Use your JVM’s Default Truststore
Add the certificate to the JVM’s default truststore.
# Set this based on your JVM path
CA_CERTS=/path/to/jre/lib/security/cacerts
sudo keytool -import -alias raytion-hcl-connections-truststore -file server-cert.pem \
-keystore "$CA_CERTS" -storepass changeit -nopromptKeep raytion.connector.agent.connections.server.useCustomSslKeystore=false (default).
To verify the certificate was imported to the correct truststore:
keytool -list -keystore "$CA_CERTS" -storepass changeit | grep raytion-hcl-connections-truststoreTo remove the certificate from the JVM truststore:
sudo keytool -delete -alias raytion-hcl-connections-truststore \
-keystore "$CA_CERTS" -storepass changeitImportant Notes
-
Certificate Requirements: The server certificate must include Subject Alternative Names (SANs) matching the hostname. Certificates without SANs will fail hostname verification.
-
Legacy Certificates: If you cannot fix the certificate and must connect to a server with a legacy certificate lacking SANs, you can set
raytion.connector.agent.connections.server.disableHostnameVerification=true. WARNING: This is insecure and should NEVER be used in production environments.
Repeated Error Regarding Item Deletion
The connector might run into a situation where it repeatedly logs error messages like the following:
s.a.t.c.ContentTraversalCallbackListener : Item Backend invalidated the callback for deleting the item c197e826-0615-382a-b449-e744e8b2d0ab [job: 930db724-f4da-3efc-8e92-15d9beae4c5b].com.raytion.connector.backend.sharepoint.content.asynchronous.MicrosoftSharePointSearchException: Item [ItemReference(reference=c197e826-0615-382a-b449-e744e8b2d0ab)] is requested to be submitted for Deletion. It will not be submitted because is not present in SharePoint.
This occurs if the connector has submitted the deletion of an item to SharePoint, but missed the notification from the Raytion BCS Solution in SharePoint that the submission was received. In this case, the connector will try to delete the same item again and again in subsequent content traversals. Each attempt will yield the above-mentioned message.
As a workaround, delete the item in question from the connector database. To do this, proceed as follows:
-
Shutdown the connector.
-
Open the connector database.
-
Execute the SQL query
DELETE FROM item_store.partition_item_membership where item_id = '<item-id>';
(Replace<item-id>with the item’s UUID which you find in the error message, in the example above:
c197e826-0615-382a-b449-e744e8b2d0ab.)