Sample steps to upgrade and migrate data from Component Pack 6.5 to 7

Use these sample steps to help you upgrade Component Pack 6.5 to 7 in your own environment. The upgrade takes place on the same system as Component Pack 6.5 and temporarily preserves the 6.5 pods needed to migrate Elasticsearch 5 data to Elasticsearch 7.

Before you begin

For background information and where to get the latest download, see Installation and upgrades.

Before we start with the sample steps, let's make a few assumptions about the environment.

We are upgrading an environment which will be available behind However, this is just a public domain, and entry point to the Connections (and dynamicHost of Connections).

All the nodes are available using their FQDNs and are in a different domain:

  • Connections, with WebSphere and IBM HTTP Server is on
  • DB2 is on
  • Kubernetes cluster is just a single node, and it is on
  • NFS master is collocated with Its IP address is and all your folders are created in

About this task

This example uses the preceding assumptions to walk you through the following steps, in a logical order, to get your Component Pack deployment up and running:

Important: Start the upgrade using Helm v2. Once you've completed data migration and set up Orient Me for Component Pack 7, you will switch to Helm v3 and finish by upgrading a few components that require Helm 3 in Component Pack 7.

Set up NFS

We don't recommend or support any particular configuration of NFS - you can use whatever NFS implementation is available. For the sake of this example, however, let's assume that that our NFS is on, you have root access there, you installed NFS, you know how to manage it, and you just need the stuff needed for Component Pack.
  • Create /pv-connections folder on
  • Inside that folder, create this set of subfolders:
    • /pv-connections/customizations with permissions 0005
    • /pv-connections/esbackup-7 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esdata-7-0 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esdata-7-1 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esdata-7-2 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esmaster-7-0 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esmaster-7-1 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/esmaster-7-2 with permissions 0700 (Inside /pv-connections, create a subfolder for Component Pack upgrade )
    • /pv-connections/kudos-boards-minio with permissions 0700
    • /pv-connections/mongo-node-0 with permissions 0700
    • /pv-connections/mongo-node-1 with permissions 0700
    • /pv-connections/mongo-node-2 with permissions 0700

Ensure that all of the preceding folders are exported and mountable from your Kubernetes workers before you proceed.

Download and set up the package

On the server which has Helm v2 and kubectl configured for your non-root user, download and unpack the Component Pack archive to /opt/microservices_connections.

Push the images to the Docker Registry or Amazon ECR

Inside your Component Pack package, you basically get a set of Docker prebuild images and Helm charts. You need to push those images now to a Docker Registry, which in this example lives on on port 5000, has SSL enabled, and can be logged in to using the username admin and password password (whatever you set for them):

  • Go to component_pack_installation_folder/hybridcloud/support
  • Run this command: ./ -dr -u admin –p password

For an upgrade, the script adds only the new packages, and Helm charts know which version they need. Once this finishes, you should be good to go.

The same script is compatible with Amazon ECR.

Use –f instead of –set with Helm charts

An examples folder (provided on the HCL Support site) follows the naming convention that is used throughout this topic. Feel free to check the examples for what gets rewritten for each chart.

This change makes it much cleaner, and is also the way that the HCL-provided Ansible automation works. If you want to review or customize the examples, here's how:

  • Go to the Component Pack installation files for Helm chart configuration Knowledge Article on the HCL Software Support site, and download and unzip the folder
    Important: For the required Connections 7.0 update that the Component Pack is part of, replace this zip even if you already downloaded it when you installed or upgraded to 7.0, as some settings changed in
  • Copy the files to component_pack_installation_folder/hybridcloud/examples.
  • In the examples folder, open the subfolder that applies to your environment (either single or multiple domains).
  • Review the examples, or customize them by changing the values to the ones for your environment.
  • Continue with the steps that follow in this document.
Note: For upgrading Elasticsearch-related components involved in data migration, this document will borrow from the approach taken in the Kubernetes-services portion of the whitepaper Upgrading from Connections 6.5 to 7. As a result, the -set command will be used here to deploy the Helm charts of certain components involving to data. See Knowledge Article KB0090051 to download a PDF of the whitepaper.

The whitepaper is a valuable resource for anyone seeking a deeper understanding of how to upgrade Connections server and Component Pack using one machine to "mirror" the old version and upgrade/migrate to the new.

Set up persistent volumes and persistent volume claims on NFS

This command sets up both PVs and PVCs:
helm upgrade connections-volumes component_pack_installation_folder/hybridcloud/helmbuilds/connections-persistent-storage-nfs-*.tgz -i -f 
For how to troubleshoot PV and PVC setup, see the Troubleshooting Component Pack guide on the HCL software product documentation site.

Set up bootstrap charts

Bootstrap is one-time job. It creates secrets and certificates for various components, including Redis, MongoDB and ElasticSearch.

Be aware that simply rerunning/upgrading bootstrap also means recreating all those secrets and certificates, and requires in some cases redoing the steps which were dependent on it (like setting up certificates again for Metrics).

Starting with Component Pack 7, bootstrap will also create secrets and certificates for ElasticSearch 7, overwriting existing secrets so that Elasticsearch upgraders will later need to redo some configuration steps, like SSL interoperability.

To upgrade bootstrap, run:
helm del --purge bootstrap 
helm upgrade bootstrap component_pack_installation_folder/hybridcloud/helmbuilds/bootstrap*.tgz -i -f 

Set up connections-env charts

This chart by default installs connections-env configmap.

Note: If you will be deploying Microsoft Teams integration, you can choose to enable it during initial connections-env setup or modify connections-env later. The value integrations.msteams.enabled=true is used to indicate that an additional integrations-msteams-env configmap and ms-teams-secret secret should be created, which are necessary for Teams integration to work. If you choose to set integrations.msteams.enabled=true at this time, see Set up Microsoft Teams integration before going further for an example upgrade command and list of additional values that must be provided to successfully complete the connections-env upgrade.

The configmap for connections-env contains all the variables needed for the Customizer and Orient Me to function properly. Note that Customizer always points to the IBM HTTP Server directly, whereas Orient Me requests point to the front door proxy.

To upgrade connections-env, run:
helm upgrade connections-env 
component_pack_installation_folder/hybridcloud/helmbuilds/connections-env-*.tgz -i -f 

Set up infrastructure charts

This will install the infrastructure for OrientMe and other apps, the most prominent being MongoDB and appreg services.

If this step fails, and if all pods don't come up, there is no point proceeding until this is fixed. To troubleshoot the Component Pack installation check out the Troubleshooting Component Pack document.

To upgrade infrastructure, run:
helm upgrade infrastructure component_pack_installation_folder/hybridcloud/helmbuilds/infrastructure-*.tgz -i -f 

Set up Customizer

Customizer needs to be installed, customizations copied into its PV (living on your NFS:/pv-connections/customizations) and then enabled on Nginx:
  • Mount NFS:/pv-connections/customizations to the server where you have your Component Pack unpacked and from which you are managing installations
  • Copy all the files from component_pack_installations_folder/hybridcloud/support/customizations/* to NFS:/pv-connections/customizations
  • Copy component_pack_installations_folder/hybridcloud/support/ms-teams folder to NFS:/pv-connections/customizations
To upgrade Customizer, run:
helm upgrade mw-proxy 
component_pack_installation_folder/hybridcloud/helmbuilds/mw-proxy-*.tgz -i -f 
Setup your reverse proxy to forward some traffic to the customizer by sending it to KUBERNETES:30301. For Nginx, it would look like this:
location ~      ^/(files/customizer|files/app|communities/service/html|forums/html|search/web|homepage/web|social/home|mycontacts|wikis/home|blogs|news|activities/service/html|profiles/html|viewer)  { 



Customizer will not start serving any traffic until you start sending some, from whatever fronted reverse proxy you are using.

Learn more about configuring Customizer in Configuring the Customizer component.

Set up Elasticsearch 7 charts

With Connections 7, ElasticSearch 7 is the default backend for Orient Me. It is also the default backend for typeahead search and Metrics.

Solr and Zookeeper are not used anymore, so feel free to clean them up if you didn't already.

Important: Preserve your Elasticsearch 5 deployment on the same system as the Elasticsearch 7 setup until you have completed data migration and then enabled services like Orient Me, Metrics, and typeahead search to use Elasticsearch 7.
Install the new Elasticsearch 7 chart now by running:
helm upgrade elasticsearch7 
component_pack_installation_folder/hybridcloud/helmbuilds/elasticsearch7-*.tgz -i -f 
Note: ElasticSearch, because of the way it is set up starting with version 7, will not work if bootstrap didn't create its secrets and certificates beforehand.

Set up Tailored Experience features for communities

A replacement strategy is being used to install or upgrade the Tailored Experience features; therefore it's important to note that you must add --force to the end of the command.

To install or upgrade Tailored Experience, run:
helm upgrade tailored-exp 
component_pack_installation_folder/hybridcloud/helmbuilds/tailored-exp-*.tgz -i -f 
component_pack_installation_folder/hybridcloud/examples/multi_domain_environment/tailoredexperience.yml --force
Once this is all set, add the following rules to your httpd.conf on your IBM HTTP servers and restart the service:
# proxy rules for admin-portal
ProxyPass "/cnxadmin" ""  
ProxyPassReverse "/cnxadmin" ""
# proxy rules for community-template-service
ProxyPass "/comm-template" "" 
ProxyPassReverse "/comm-template" ""
# proxy rules for te-creation-wizard
ProxyPass "/te-creation-wizard/" "" 
ProxyPassReverse "/te-creation-wizard/" ""
For post-installation tasks required for to deploy community templates, see Assigning administrators to template management roles
Note: The Tailored Experience is not supported on the Microsoft SQL Server backend.

Set up Orient Me for Elasticsearch 5

With Connections 7, the default and only backend for Orient Me is ElasticSearch, and in the provided yaml files, the default Elasticsearch version is 7.

The prerequisites to set up and run Orient Me with Elasticsearch 5 are:
  • Helm should be version 2.
  • Infrastructure charts need to be already installed and all pods scheduled.
  • connections-env configmap needs to be already present.
  • ElasticSearch 5 and 7 need to be installed and running. For the point version of Elasticsearch 7, HCL tested data migration on Elasticsearch 7.10.1. If you use a different version, change any references to 7.10.1 in the commands in this document.
    Note: For the point version of Elasticsearch 7, HCL Software tested data migration on Elasticsearch 7.10.1. If you use a different version, change any references to 7.10.1 in the commands in this document.
To allow indexing and retrieval services to use Elasticsearch 5 while data migration is in process, you must upgrade Orient Me so that its indexing service does NOT initially point to Elasticsearch 7. You do this by running the following -set command, which sets the Elasticsearch indexing service for Orient Me to true, but sets its Elasticsearch 7 indexing service to false. (Once the migration is completed, you will point Orient Me at Elasticsearch 7.)
helm upgrade -i orientme orientme*.tgz --set 

Migrate data from Elasticsearch 5 to 7

  1. Log in to, the server where kubectl is configured in the sample environment.
  2. Prepare for data migration from Elasticsearch 5 to 7 by redeploying Elasticsearch 7 with an enhanced set of Elasticsearch 5 chart options, modifying the host, port, and migrate settings in the Elasticsearch chart as follows:
    helm upgrade elasticsearch7 component_pack_installation_folder/hybridcloud/helmbuilds/elasticsearch7-0.1.0-<timestamp>.tgz -i --reuse-values --set 
  3. Run these commands to start bash mode in the Elasticsearch 7 client pod:
    kubectl get pods -n connections | grep es-client-7
    Run the following command (using the pod name from the results of the previous command):
    kubectl exec -n connections -ti es-client-7-123 bash
  4. Go to the /opt/elasticsearch-7.10.1/probe/REINDEX directory, and run the following script to create the Metrics index for Elasticsearch 7 from the one in Elasticsearch 5:
  5. To migrate the Metrics data from Elasticsearch 5 to Elasticsearch 7, run this script:
  6. Run the following script to create the Typeahead Search index for Elasticsearch 7 from the one in Elasticsearch 5.
    Note: You can skip this step if the Typeahead Search index was already created in Elasticsearch 7 using the wsadmin python script SearchService.createES7QuickResultsIndex().
  7. To migrate the Typehead Search data from Elasticsearch 5 to Elasticsearch 7, run this script:
  8. Type exit to leave bash mode.

Verify migration

Downtime is needed for the final phase of upgrading to Elasticsearch 7: switching the services over to the Elasticsearch 7 deployment and configuring the apps for it.
  1. Shut down all Connections servers in the cluster.
  2. Log in to the server where kubectl is configured, and run the following commands.

    To start bash mode in the Elasticsearch 7 client pod, run:

    kubectl get pods -n connections | grep es-client-7

    Run the following command (using the pod name from the results of the previous command):

    kubectl exec -n connections -ti es-client-7-123 bash
  3. Go to the /opt/elasticsearch-7.10.1/probe/REINDEX directory.
  4. Run the data verification script for individual indices using
    ./ index_name

    For example: ./ quickresults You can get individual index names using the this command:

    cd /opt/elasticsearch-7.10.1/probe 
    ./ GET /_cat/indices?v
  5. In case there is data mismatch, rerun the data migration script by doing one of the following:
    • ./
    • ./ located at /opt/elasticsearch-7.10.1/probe/REINDEX
  6. Type exit to leave bash mode.
    Note: Do NOT restart the Connections cluster yet.

Switch the indexing service from Elasticsearch 5 to 7

To complete Orient Me set up, you also need to do the following:

  • After you set up Orient Me to point at Elasticsearch 7.6.1, you need to run profiles migration. In this step, we are migrating users from PeopleDB to MongoDB, which is used by Orient Me.
  • You need to set rewrite rules in httpd.conf on your IBM HTTP Server to enable sending requests to it from Connections.
Use the yaml file to upgrade Orient Me and have it point to Elasticsearch 7. Run these -f commands:
helm upgrade orientme 
component_pack_installation_folder/hybridcloud/helmbuilds/orientme-*.tgz -i -f 
To migrate profiles, run this:
kubectl exec -n connections -it $(kubectl get pods -n connections | grep people-migrate | awk '{print $1}') -- sh -c "npm run start migrate"

If you followed examples and the order of installation, this should work out of the box. If you want to do some customizations, or if you are later changing the database, you can SSSH into people-migrate pod and see the configuration that was precreated for you during the installation/upgrade of Component Pack in /usr/src/app/migrationConfig.

And finally, add the rewrites to your httpd.conf on the IBM HTTP Server, and then restart the service:
# OrientMe Config 
ProxyPreserveHost On 
ProxyPass "/social" "" 
ProxyPassReverse "/social" "" 
ProxyPass "/itm" "" 
ProxyPassReverse "/itm" "" 
ProxyPass "/community_suggestions/api/recommend/communities" "" 
ProxyPassReverse "/community_suggestions/api/recommend/communities" "" 
ProxyPass "/appreg" "" 
ProxyPassReverse "/appreg" "" 
ProxyPass "/appregistry" "" 
ProxyPassReverse "/appregistry" ""

Later, you can learn more about configuring Orient Me in Configuring the Orient Me component.

Uninstall Elasticsearch 5

Now you can remove Elasticsearch 5 artifacts by running:
helm delete -purge Elasticsearch
Then verify that Metrics and typeahead search are working, and that Orient Me opens for users.

Enable Metrics for Elasticsearch 7

Upgrade Helm from v2 to v3

Now, upgrade to Helm v3, as some of the components remaining to be upgraded to Component Pack 7 require Helm 3.

For guidance on upgrading to Helm 3, see the knowledge article KB0090051: Upgrading from Connections 6.5 to 7 Whitepaper, from which you can download a PDF of the paper.

Set up ingress

Connections 7 supports only the community Nginx Ingress controller.

With community ingress, besides its being more flexible with AWS and OpenShift, you get out-of-the-box Prometheus exporters, which come in handy if you decide to also set up monitoring.

To upgrade ingress to the community edition, run:
helm repo add ingress-nginx 

helm repo update 

helm upgrade cnx-ingress -i ingress-nginx/ingress-nginx --namespace connections --set 
After installing the ingress controller, it is best if you apply the ingress rules. You can do that by running:
helm upgrade cnx-ingress-rules 
component_pack_installation_folder/hybridcloud/helmbuilds/cnx-ingress-*.tgz -i -f 
Note: The versions tested by HCL are 0.35 to 0.41 (the latest one as of January 2021).

Set up Microsoft Teams integration

The Microsoft Teams integration microservices rely on a configmap (integrations-msteams-env) and secret (ms-teams-secret) that are part of the overall connections-env deployment. They are not installed by the connections-env chart by default; the expectation is that they are enabled as needed by customers who use Microsoft Teams and wish to enable the use cases that these micro-services support.

To upgrade the connections-env deployment to enable the correct settings for Microsoft Teams, three specific pieces of information are required which should have been created and noted while performing the steps in Configuring an Azure app to support the Microsoft Teams app.

The items of information needed for this setup are:
  • Teams tenant ID
  • Bot (app) ID
  • Bot (app) password (secret)
With this information, to upgrade the connections-env and create the configmap and secret, run:
helm upgrade connections-env component_pack_installation_folder/hybridcloud/helmbuilds/connections-env-*.tgz --reuse-values --set integrations.msteams.enabled=true,"your_tenant_id","your_bot_id",integrations.msteams.client.secret="your_bot_secret",integrations.msteams.auth.schema="3","not_used",integrations.msgraph.client.secret="not_used",integrations.msgraph.redirect.uri="not_used",integrations.msteams.share.ui.files.api="/files/basic/api",integrations.msteams.redirect.uri="not_used","not_used",integrations.msgraph.auth.endpoint="not_used",integrations.msgraph.meta.endpoint="not_used",integrations.msgraph.authorize.endpoint="not_used",integrations.msgraph.token.endpoint="not_used",integrations.msteams.share.service.endpoint="",imagePullSecretName="myregkey"

Once the configmap and secret are created, continue to install the microservices that rely on them for configuration.

Run the following command:
helm upgrade teams 
component_pack_installation_folder/hybridcloud/helmbuilds/teams-*.tgz -i -f 

Once the microservices are installed and running, add the following rules to your httpd.conf on your IBM HTTP Server and restart the server.

ProxyPass "/teams-tab" "http://master_node_host_name:32080/teams-tab" 
ProxyPassReverse "/teams-tab" "http://master_node_host_name:32080/teams-tab"    
# teams-tab-api 
ProxyPass "/teams-tab/api" "http://master_node_host_name:32080/teams-tab/api" 
ProxyPassReverse "/teams-tab/api" "http://master_node_host_name:32080/teams-tab/api"
# teams-share-service 
ProxyPass "/teams-share-service" "http://master_node_host_name:32080/teams-share-service" 
ProxyPassReverse "/teams-share-service" "http://master_node_host_name:32080/teams-share-service"
# teams-share-ui 
ProxyPass "/teams-share-ui" "http://master_node_host_name:32080/teams-share-ui" 
ProxyPassReverse "/teams-share-ui" "http://master_node_host_name:32080/teams-share-ui"
# Teams SameSite Fix
# Add SameSite property to all server-side set-cookie response headers
Header edit Set-Cookie ^(.*)$ "$1; SameSite=None;Secure"
# Fix for Embedded Experiences content loading in Teams Tab iframe
<Location /connections/opensocial/gadgets/ifr>
Header unset X-frame-Options
Header always set X-frame-Options "ALLOW-FROM"

The proxy pass statements map URI to the ingress controller service to route requests to the appropriate Microsoft Teams-related micro-services. Given tightening security of more recent versions of browser, especially Chrome (or Chromium-based browsers) and the use of embedded iFrames by Microsoft Teams, passing cookies correctly between the environments requires the SameSite=None and Secure property.

Lastly, and again for security reasons, you must change the x-frame-options header to support the way that Microsoft Teams uses an iFrame to embed application content in the tabbed pages. Since Connections also uses an iFrame to display embedded experiences content, this becomes an iFrame within an iFrame. The embedded experiences content cannot be displayed if SAMEORIGIN is used because the Teams UI and Embedded Experiences content do not share a common origin host. Using ALLOW-FROM permits the header to tell the browser that it is allowed to render content in the iFrame when processing the /connections/opensocial/gadgets/ifr request from an alternative host.

Set up Activities Plus

Prerequisites for installing Activities Plus are:
To install or upgrade it, run:
helm upgrade kudos-boards-cp 
component_pack_installation_folder/hybridcloud/helmbuilds/kudos-boards-cp-2.*.tgz -i -f 
Once this is all set, add the following rules to your httpd.conf on your IBM HTTP servers and restart the service:
# proxy rules for activities plus 
RewriteRule ^/activities/service/html/(.*)$ /boards/activities/service/html/$1 [R] 
ProxyPass "/boards" "" 
ProxyPassReverse "/boards" "" 
ProxyPass "/api-boards" "" 
ProxyPassReverse "/api-boards""

Starting with version 7, be sure that you have websockets enabled on your front proxy server.

If you are using Nginx, the configuration would look like this:
location /api-boards/ { 


                    proxy_http_version 1.1; 

                    proxy_set_header Upgrade $http_upgrade; 

                    proxy_set_header Connection "upgrade"; 


Find more about Activities Plus in the section Integrating with Activities Plus.

Set up Connections Add-in for Microsoft Outlook

Prerequisites for installing HCLConnections Add-in for Microsoft Outlook is:
To install or upgrade the Connections Outlook Add-in, run:
helm upgrade connections-outlook-desktop 
component_pack_installation_folder/hybridcloud/helmbuilds/connections-outlook-desktop-*.tgz -i -f 
Once this is all set, add the following rules to httpd.conf for your IBM HTTP servers and restart the service:
# proxy rules for outlook add-in
Redirect "/outlook-addin" "/outlook-addin/" 
ProxyPass "/outlook-addin/" "" 
ProxyPassReverse "/outlook-addin/" ""

Finally, update the add-in docker environment variables.

These are located in the outlook-addin.yaml file. These are passed into the Outlook add-in docker instance on startup:

  • What must be overriden:
    • CONNECTIONS_URL - URL of your Connections environment without a trailing slash (eg The same URL has to be used when generating secret in the first step.
    • CONNECTIONS_CLIENT_SECRET - Client secret generated by Connections when registering OAuth provider in the first step.
    • CONNECTIONS_CLIENT_ID - Client ID (aka. app ID) used when registering OAuth provider in Connections in the first step (default: hcl-cnx-office-addin)
  • What may be overriden:
    • CONTEXT_ROOT - The path to where the Outlook add-in is being served, relative to the CONNECTIONS_URL. Do NOT start or end with `/. (default: outlook-addin)
    • SUPPORT_URL - URL that a user can go to for support (help). (default:
    • CONNECTIONS_NAME – A custom name for the add-in..(default: 'HCL Connections')
  • Take care about ingresses listed there. You should point to both frontend domain and internal domains, if both are used. Otherwise, only point to the one that is used in your case.

Enable Microsoft Teams integration

See Setting up the Connections app for the Microsoft Teams client in the Integrating with Other Products section of this documentaion.

Enable Connections Add-in for Microsoft Outlook

See Making the Connections Add-in for Outlook available to users.