ICXT Setup Preparations

Installation Options

ICXT can be installed in three different ways:

  • via AutoDeploy, which is our recommended approach
  • via provided Scripts, for restricted Windows/Linux installations (e.g. no Cygwin available, SSH limitations between cell server nodes)
  • by installing and configuring it manually

For all installation options, the install preparations mentioned below should be verified and executed (if an action is required).

Administrative users

ICXT needs administrative access to both, HCL Connections features (Communities, Activities, Blogs, Wikis, Forums) and the WebSphere cell.

  • Ensure that the user that is referenced as Connections admin (see: http.auth.admin.user) has got a valid Connections Profile and is assigned to the admin role throughout all Connections applications Connections admin role mapping

  • Ensure that the user that is referenced as WebSphere cell admin has got administrative rights in terms of the WebSphere cell. Typically, the Connections installation references a WAS administrator within the J2C authentication data list Connections admin role mapping

WebSEAL

If a WebSEAL is in place, following junction must be configured:

GET|POST|PUT|DELETE|HEAD /ic360/

WebSphere cell

Add an additional Cluster including a Server JVM that operates the ICXT application WAS DMGR new cluster WAS DMGR new cluster Step1 WAS DMGR new cluster Step2 WAS DMGR new cluster Step3 WAS DMGR new cluster Step4

Each ICXT JVM should have at least 2GB of maximum heap. You can verify this by navigating to Server Types > WebSphere application server. Then select your created server (do this step for all server, if you created multiple in your cluster),and navigate to Server Infrastructure > Java and Process Management > Process definition > Additional Properties > Java Virtual Machine. WAS JVM HeapSize

When accessing the application for the first time thru a browser you may encounter a webgroup not defined error. In that case check that the virtual host mapping was done for the newly created cluster’s ports (default and secure). As per default it’s not the case.

If the web servers (IHS) used by the ICXT cluster are in a DMZ, don’t forget to check that the secured and non secured ports used by the cluster are open in the firewall rules.

FileSystem

ICXT stores configurations (e.g. ACLs and exported Connections data) in the servers file system. In order to allow a clustered infrastructure, this directory must be located on a shared file system. Our recommendation is to choose a sibling next to the Connections shared data folder.

sudo su - wasuser
cd /mnt/my_shared_fs
mkdir icxt
mkdir icxt/config
mkdir icxt/backupstore

Note: the backupstore folder must be created, if the module backupstore should be installed, as well

Note: The shared file system path of your installation can be determined by using the parent folder of the customizations directory Connections Customization Path

Database

ICXT stores runtime information (e.g. state of export operations) in a database. This database is shared across several other Enterprise Social Solution assets, such as the HCL Connections Data Privacy Toolkit, ContentExporter, HCL Connections Invite.

Note: All database scripts assume that Connections is setup using the user LCUSER to access all databases. If there is another user in your environment, search and replace the LCUSER in all DDL scripts that you need to execute.

  • Copy the release archive to the server where the DeploymentManager is installed on.

    • Linux: use WINSCP or the scp command: scp /some/local/path/ic360.deployment-8.0.0-full.zip some-valid-user@your.dmgr.host:/opt/IBM/installs
  • Open a Remote Desktop Session and navigate to the release package

    • Windows Prepare the package
    • Linux: cd /opt/IBM/installs
  • Extract the archive and navigate into the extracted folder

    • Windows Extract the package
    • Linux:
      • unzip -d ic360.deployment-8.0.0-full ic360.deployment-8.0.0-full.zip
      • chmod +x ic360.deployment-8.0.0-full/icxt-prepare.sh

Database Setup DB2

  • Login on the database server
ssh user@dbserver
  • Change user to the DB2 instance user
[sudo] su - db2inst1
  • Verify if DB2CODEPAGE property is set to 1208
db2set
  • If not, set it
db2set DB2CODEPAGE=1208
  • Copy all files that ends with _DB2.ddl to the home directory of the local DB2 user (e.g. /home/db2inst1/icxt-prepare)
mkdir ~/icxt-prepare

# copy the scripts from the DMGR to the database server
scp some-valid-user@your.dmgr.host:/opt/IBM/installs/ic360.deployment-8.0.0-full/db-setup/*_DB2.ddl ~/icxt-prepare/

# or use this line, if the DB and the DMGR are on the same box
cp /opt/IBM/installs/ic360.deployment-8.0.0-full/db-setup/*_DB2.ddl ~/icxt-prepare/
  • Import the SQL file essapps-createDatabase_DB2.ddl
db2 -td@ -vf ~/icxt-prepare/essapps-createDatabase_DB2.ddl
  • Import the SQL file icxt-createTables_DB2.ddl
db2 -td@ -vf ~/icxt-prepare/icxt-createTables_DB2.ddl

Database Setup ORACLE

  • Login on the database server
ssh oracle@dbserver
  • Copy all files that ends with _Oracle.ddl to the home directory of the local Oracle user (e.g. /home/oracle/icxt-prepare)
mkdir ~/icxt-prepare

# copy the scripts from the DMGR to the database server
scp some-valid-user@your.dmgr.host:/opt/IBM/installs/ic360.deployment-8.0.0-full/db-setup/*_Oracle.ddl ~/icxt-prepare/

# or use this line, if the DB and the DMGR are on the same box
cp /opt/IBM/installs/ic360.deployment-8.0.0-full/db-setup/*_Oracle.ddl ~/icxt-prepare/
  • Import the DDL (as a user that has at least the SYSDBA role) by issuing following command:
sqlplus sysdba/password @essapps-createDatabase_Oracle.ddl

NOTE: The above command will create a user named ESSAPPS and will prompt for a password. If you prefer to specify the password right when calling the command, use the following syntax:

sqlplus sysdba/password @essapps-createDatabase_Oracle.ddl password
  • Import the SQL file icxt-createTables_Oracle.ddl and use the ESSAPPS user that was created in the previous step:
sqlplus essapps/password @icxt-createTables_Oracle.ddl

Database Setup MS SQL Server

coming soon

Database Setup MySQL

  • After installing MySQL on your server, you need to set a timezone
sudo mkdir /etc/mysql
sudo chmod 777 /etc/mysql
sudo echo "[mysqld]" > /etc/mysql/my.cnf
sudo echo "default_time_zone='+01:00'" >> /etc/mysql/my.cnf

NOTE: If you encounter timezone-specific issues during runtime, it’s possible that the aforementioned adjustments did not take effect. In this case, please try adding the timezone as a global server variable:

sudo /usr/local/mysql-8.0.12-macos10.13-x86_64/bin/mysql -u root -p
SET GLOBAL time_zone = '+1:00';
  • Start MySQL CLI by using the user root and create a user LCUSER
/usr/local/mysql-8.0.12-macos10.13-x86_64/bin/mysql -u root -p
create user 'LCUSER'@'localhost' identified by 'LCUSER';
grant all on *.* to 'LCUSER'@'localhost';
exit
  • Start MySQL CLI by using the user LCUSER
/usr/local/mysql-8.0.12-macos10.13-x86_64/bin/mysql -u LCUSER -p

  • Create the Database ESSAPPS
create database ESSAPPS;
  • Copy all files that ends with _MySQL.ddl to the home directory of the local MySQL user (e.g. ~/icxt-prepare)
mkdir ~/icxt-prepare

# copy the scripts from the DMGR to the database server
scp some-valid-user@your.dmgr.host:/opt/IBM/installs/ic360.deployment-8.0.0-full/db-setup/*_MySQL.ddl ~/icxt-prepare/

# or use this line, if the DB and the DMGR are on the same box
cp /opt/IBM/installs/ic360.deployment-8.0.0-full/db-setup/*_MySQL.ddl ~/icxt-prepare/
  • Connect to the ESSAPPS database and import the ICXT tables
use ESSAPPS
source ~/icxt-prepare/icxt-createTables_MySQL.ddl

Finalize the Database Setup

This setup must be finalized by creating a DataSource in the WebSphere Cell

  • Open a Remote Desktop or SSH Session on the Deployment Manager and navigate to the release package

    • Windows Prepare the package
    • Linux: cd /opt/IBM/installs
  • Create a copy of icxt-install_default.properties in the parent folder, or re-use a file from a previous installation

    • Windows Prepare the install properties
    • Linux: cp ic360.deployment-8.0.0-full/icxt-install_default.properties icxt-install.properties
  • Open the file and adjust all values that are listed in the table below

    • Windows Adjust the install properties
  • Linux: vi icxt-install.properties
Name Description Default
DMGR_PROFILE Specify the path to the DMGR profile C:\IBM\WebSphere\AppServer\profiles\Dmgr01
DMGR_SOAP_PORT Specify the SOAP port that is used to access the MBeans of the DMGR process 8879
ICXT_CLUSTER_NAME Specify the cluster name of the ICXT cluster. This value can be retrieved by looking into the config directory dir %DMGR_PROFILE%\config\cells\%CELL_NAME%\clusters ICXTCluster
WASADMIN_USER Specify the username of the wasadmin user (e.g.: wasadmin) NO VALUE SET PER DEFAULT
WASADMIN_PASSWORD Specify the password of the wasadmin user NO VALUE SET PER DEFAULT
ESSAPPS_DB_TYPE Specify the database type that is used. Allowed values are DB2, ORACLE, MSSQL DB2
ESSAPPS_DB_SERVER_OR_URL Specify the DB server name (DB2, MSSQL) or the Connection URL (ORACLE) localhost
ESSAPPS_DB_PORT Specify the DB server port (only necessary for DB2 and MSSQL) 50000
  • Open a Windows Command Shell and navigate to the install folder and invoke the install command

    • Windows ic360.deployment-8.0.0-full\icxt-prepare.bat icxt-install.properties
    • Linux: ic360.deployment-8.0.0-full/icxt-prepare.sh icxt-install.properties
  • Enter the WebSphere administrative console (e.g.: https://your.dmgr.host:9043/ibm/console) and navigate to System administration > Nodes, select all nodes and click Full Resynchronize Synchronize all nodes

  • Restart all ICXT servers

Module-specific Setup Preparations

PDF Export

PDF Export requires the wkhtmltox binary package in order to render PDF documents. This is a binary dependency that needs to be deployed on your HCL Connections server. The necessary installation steps are outlined below.

1). Download and install the wkhtmltopdf binary package.

The binary package is available to download here: https://wkhtmltopdf.org/downloads.html. Please use the latest stable version 0.12.6 for installation.

Ensure to download the package according to your server operating system. Common examples are listed below, all distributions can be found via above link.

OS Type
Windows 64-bit 32-bit
RHEL 7 / CentOS 7 x86_64 i686 aarch64 ppc64le
RHEL 8 / CentOS 8 x86_64 aarch64 ppc64le

Once downloaded, install the package according to your system’s requirements.

RHEL/CentOS:

rpm -Uvh wkhtmltox-0.12.6-<version>.rpm

Windows:

  • Download wkhtmltox-0.12.6-<version>.exe
  • Execute binary file to run installer
  • Install tool at appropriate location

2). Configure the PDF Export feature on WebSphere to leverage wkhtmltopdf binary

In order for the PDF Export feature to use the wkhtmltopdf library, it needs to be able to invoke the tool via the system’s command line. There are two ways to ensure this is the case.

2.1). Configure the system path to allow execution of the wkhtmltopdf command.

PDF Export tries to execute the command

wkhtmltopdf [args]

on the system’s command line (cmd on Windows, shell/bash on Linux). This can be enabled by adding the wkhtmltopdf to the system’s path variable. To test this, try to execute above command on the system’s command line. If the command is not recognized, this is not configured correctly. Otherwise PDF Export is now ready and can be used.

Note: The command needs to be executable by the same user that will start the WebSphere servers/JVMs.

2.2). Configure PDF Export to invoke wkhtmltopdf in the correct install location

If wkhtmltopdf is not available by invoking the command listed in 2.1, you can instead make the PDF Export aware of what execution command is necessary to invoke it instead. E.g. if you have installed the feature at location

/opt/HCL/Connections/wkhtmltox/bin/wkhtmltopdf

you can add this via WebSphere configuration. To do this, follow below steps:

  • Enter the WebSphere administrative console (e.g.: https://your.dmgr.host:9043/ibm/console) and navigate to Resources > Resource Environment > Resource Environment entries
  • Look for the ic360 resource environment entry and click on it
  • Navigate to Additional Properties > Custom properties
  • Click New… to create a new property
  • Enter the name wkhtmltopdf.command.exec and the path to the wkhtmltopdf binary (including its name) as the value, e.g. C:\Program Files\\wkhtmltopdf\bin\wkhtmltopdf.exe on Windows or /opt/HCL/Connections/wkhtmltox/bin/wkhtmltopdf on Linux.
  • Click Apply and OK.
  • Save the changes to the master configuration.
  • Restart ICXT server.

wkhtmltopdf configuration

Note: In case of a clustered environment, this library needs to be installed the same way on all nodes of the cluster.

[OPTIONAL] Server side fonts

Without installed fonts, the PDF rendering may result in unsatisfactory result. If there are no font sets installed, we recommend to install DejaVu fonts (https://dejavu-fonts.github.io/).

Note for CentOS or RHEL, the library wqy-microhei-fonts should additionally be installed to support Chinese and Japanese.

  • RHEL or CentOS:
sudo yum install dejavu-sans-fonts
sudo yum install wqy-microhei-fonts

To verify that the Dejavu fonts have been properly installed, run the command fc-list | grep "DejaVu Sans"

Sample output:

/usr/share/fonts/TTF/DejaVuSansCondensed.ttf: DejaVu Sans,DejaVu Sans Condensed:style=Condensed,Book
/usr/share/fonts/TTF/DejaVuSans-BoldOblique.ttf: DejaVu Sans:style=Bold Oblique
/usr/share/fonts/TTF/DejaVuSansMono.ttf: DejaVu Sans Mono:style=Book
/usr/share/fonts/TTF/DejaVuSansCondensed-Oblique.ttf: DejaVu Sans,DejaVu Sans Condensed:style=Condensed Oblique,Oblique
/usr/share/fonts/TTF/DejaVuSansMono-Oblique.ttf: DejaVu Sans Mono:style=Oblique
/usr/share/fonts/TTF/DejaVuSansCondensed-BoldOblique.ttf: DejaVu Sans,DejaVu Sans Condensed:style=Condensed Bold Oblique,Bold Oblique
/usr/share/fonts/TTF/DejaVuSans-ExtraLight.ttf: DejaVu Sans,DejaVu Sans Light:style=ExtraLight
/usr/share/fonts/TTF/DejaVuSans-Oblique.ttf: DejaVu Sans:style=Oblique
/usr/share/fonts/TTF/DejaVuSansMono-Bold.ttf: DejaVu Sans Mono:style=Bold
/usr/share/fonts/TTF/DejaVuSansCondensed-Bold.ttf: DejaVu Sans,DejaVu Sans Condensed:style=Condensed Bold,Bold
/usr/share/fonts/TTF/DejaVuSansMono-BoldOblique.ttf: DejaVu Sans Mono:style=Bold Oblique
/usr/share/fonts/TTF/DejaVuSans.ttf: DejaVu Sans:style=Book
/usr/share/fonts/TTF/DejaVuSans-Bold.ttf: DejaVu Sans:style=Bold