Installing and Configuring Clara

Clara can be installed with Docker.

Checking system prerequisites

Before starting to install Clara, you must check the following system prerequisites:

1. Verify that Docker and Docker Compose are installed, configured, and ready to use. For the required version, see: System Requirements.  

If you don't have Docker and Docker Compose already installed, see: Installing Docker and Docker Compose.

2. Clara requires some values to be set for ulimit parameter, for Linux OS. See: How to verify and set ulimit parameter.

3. Verify the available virtual memory. See: How to verify and set the available virtual memory.

4. If you are installing Clara on RHEL or CentOS distros, SELinux must be set to Permissive or Disabled. See: How to set SELinux to permissive.

5. Obtain your Clara license entitlement (License Id) through the HCL Cloud License Server (a working internet connection is required). For details, see What is the HCL Software License & Download Portal. The license entitlement and expiration date depend on the type of license you have purchased (if product, bundle, or trial). The License Id must be specified during the installation procedure.

 

 

Installation procedure

To install and configure Clara, run the following procedure.

 

1. From HCL License Portal download the appropriate Clara installation package:

• HCL CLARA for HCL Workload Automation V2.0.0.0

 

Clara is available with 2 different types of installation packages:

 

• Installation package for offline installation: HCL_CLARA_2.0.0.0_OFFLINE.tar.gz containing:

• clara.tar.gz

• HCL_CLARA_IMAGES.tar.gz

• install.sh

• Installation package for online installation: HCL_CLARA_2.0.0.0_ONLINE.tar.gz containing:

• clara.tar.gz

• install.sh

 

The online installation requires a working internet connection to reach the Entitled Registry that contains Clara images. Contact your HCL sales representative for the login details required to access the Entitled Registry.

Execute the following command to log in into the Entitled Registry:

docker login -u <your_username> -p <your_entitled_key> hclcr.io

 

Clara images are as follows:

 

• hclcr.io/solutions/clara/clara-manager:2.0.0.0

• hclcr.io/solutions/clara/clara-rasa:2.0.0.0

• hclcr.io/solutions/clara/clara-search-engine:2.0.0.0

• hclcr.io/solutions/clara/clara-nginx:2.0.0.0

• hclcr.io/solutions/clara/clara-keycloak:2.0.0.0

• hclcr.io/solutions/clara/clara-asyncservice :2.0.0.0

• hclcr.io/solutions/clara/clara-rabbitmq :2.0.0.0

• hclcr.io/solutions/clara/clara-datastore :2.0.0.0

 

2. For the selected installation package (offline or online), extract the content of the tar.gz file(s) into <BUILD_DIR>, a directory of your choice, using one of the extraction tools available on your system or downloadable from the internet. The tool you use must be able to keep the file permissions on the extracted files.

3. You can properly modify the <BUILD_DIR>/clara/config/Clara-WA.env.TEMPLATE configuration file to set some common properties and customize Clara integration with Slack and Teams messaging tools. See below the sections about Customizing environment files and Integration with Slack and Teams.

Note:

After Clara installation, you can change or complete Clara customization by using Clara Dashboard. For details, see Clara Dashboard.

4. Open a bash shell and get ready to install Clara.  

5. From the <BUILD_DIR> directory, run the command:

 

./install.sh  [--load-images] --install  [--install-path <install_path>] --accept-license [--port <port_number>] [--img-repo <img_repo>] --license-id <license_id>

 

where:

 

--load-images is for offline installation only. Its is required to load Clara images into your environment.

--install-path <install_path> is optional if you wan to change the installation directory of your choice (default value is /opt/hcl).

--accept-license is required to accept the HCL Master License Agreement.

--port <port_number>  is optional if you want to change the HTTPS port to use with Clara (default port is 443).

--img-repo <img_repo> is for online installation only. It is optional if you want to specify an Entitled Registry prefix different from the default prefix (hclcr.io/solutions/clara/.

--license-id <license_id> is required to set Clara License Id.

 

By default, before starting the installation, Clara checks the installation prerequisites. If you want to skip this check, add the --noprereq parameter. For details, see the install.sh command usage.

 

6. The installation script checks the prerequisites, runs the installation process, and verifies its successful completion.

 

 

Post installation steps

When the installation is completed, you can access:

• Clara Web Interface at the link https://<IP:PORT>  

• Clara Dashboard at the link https://<IP:PORT>/dashboard

 where:

• IP is the IP address of Clara machine.

• PORT is the port of Clara machine. You can skip it if you use the default port (443).

 

Clara Dashboard can also be accessed from the drop-down menu of Clara chat window.

 

The installation script generates two Clara users:

• userid solutions, password Hclsolutions00, with user role

• userid admin, password Hclsolutions00, with administrator role

 

As you start chatting with Clara, you must:

• Define the Workload Automation environments that you want to manage with Clara and identify the current environment.

Go to Clara Dashboard > Environments. For details, see Environments.

• Define credentials for the product environments you want to manage with Clara. The Credential Manager component, accessible from Clara Dashboard, helps you map your product environment credentials with your Clara credentials (each Clara user can only manage his own product environment credentials). For additional details, see Managing User Credentials.

 

Use the Keycloak administration console to define new Clara users, new roles, or change default passwords. You can access Keycloak administration console https://<IP:PORT>/keycloak/auth/admin by using the following default credentials:

• userid=admin

• password=Hclsolutions00

You can also reach the Keycloak  administration console from Clara Dashboard, by clicking Manage roles in the Account icon drop-down menu on the dashboard header.

To change the Keycloak default password or the default SSL certificates, see Configuring Security.

 

If you want to enable multiple languages with Clara through HCL Translator, see Installing and configuring HCL Translator.

 

After Clara installation, use the Dashboard to complete the following Clara settings:

• User credentials

• Clara intents

• Dashboard language

• Clara integration in the Dynamic Workload Console

• Dashboard Time Zone

• Workload Automation environments that you want to manage with Clara

• Cache synchronization

• SMTP server for email notification

• Translation services

• HERO integration

For details, see Clara Dashboard.

 

To start/stop Clara containers and services, see clara.sh command options.

 

 

Integration with Slack and Teams

To integrate Clara with Slack and Teams  messaging tools, you must run the following steps:

 

1. Install Clara on a machine having a public internet connection.

2. Provide the required Slack and Teams parameters in the  <BUILD_DIR>/clara/config/Clara-WA.env.TEMPLATE configuration file.

3. Ensure that the email id that you set in Clara Dashboard > Credential Manager for your Clara user, matches the email id  you set on Slack and Teams.

4. Run some configuration steps for the messaging tools:

 

• Slack

1. Define Clara app on Slack by following the instructions contained in the Slack documentation. You can also watch a useful tutorial video.

2. In addition to the settings listed in the Slack documentation, set the following parameters:

 

Additional bot events:

app_home_opened

 

Additional scopes:

users.profile:read

users:read.email

 

Interactivity & Shortcuts -> Request URL:

https://<clara_url>/webhooks/slack_auth/webhook

 

Event Subscriptions -> Request URL:

https://<clara_url>/webhooks/slack_auth/webhook

 

3. On Slack, go to General Information -> Display Information and set the fields as indicated in the App settings table below.

 

• Teams

1. Register Clara's bot with Azure by following the instructions contained in the Azure documentation. You can also watch a useful tutorial video.

2. Define Clara app on Teams. A tutorial video for this step is also available.

3. On Teams, set the parameter Configuration -> Messaging endpoint: https:///<clara_url>/webhooks/botframework_auth/webhook.

4. On Teams, go to App Details -> Descriptions to set the name, and the short and long descriptions for the app, as indicated in the App settings table below.

5. Go to App Details -> Branding to set the app icon as indicated in the App settings table below.

 

 

App settings
App name	Clara
Short description	Your Workload Automation Virtual Assistance
Long description	Clara is an Intelligent Virtual Assistant that enhances HCL Workload Automation customer experience with Natural Language Processing (NLP) interactions, enabling customized self-service automation with immediate 24x7 response. HCL Clara is the product expert that users can consult to learn the product capabilities, execute routine tasks and get troubleshooting assistance.
App icon for Teams	Download Teams_icon.zip
App icon for Slack	Download Slack_icon.zip
Background color for Teams	#71D9F3
Background color for Slack	#01539B

 

 

You can follow your conversation with Clara even using both channels. For example, you can ask your question to Clara on Slack, and then continue the conversation on Teams.

 

Customizing environment files

Both for Workload Automation and Workload Automation for Z, before starting Clara installation, modify the  <BUILD_DIR>/clara/config/Clara-WA.env.TEMPLATE configuration file to set Clara common properties and optionally configure Clara integration with Slack and Teams messaging tools.

 

Common properties
NGINX_PORT	TCP/IP Port to use with Clara [Default: 443]
NGINX_CERTS	Path where nginx certificates for Clara are stored [Default: ./certs/nginx]
Properties for Clara integration with Messaging tools (Slack and Teams)
BOTFRAMEWORK_APP_ID	ID for Clara Teams account
BOTFRAMEWORK_APP_PASSWORD	Password for Clara Teams account
SLACK_TOKEN	The token generated by the Slack bot
SLACK_CHANNEL	The Slack bot channel ID
SLACK_SIGNING_SECRET	The Slack unique string for Clara.
Properties for source docker images
IMG_PREFIX	Clara docker image repo prefix when images are not available locally. [Default: hclcr.io/solutions/clara/]
TAG	Tag for Clara docker images based on Clara version, optional. [Default: 2.0.0.0]

 

After Clara installation, if a re-configuration is needed to integrate Clara with Slack or Teams messaging tools, you must modify the .env file created during the installation process and located in the folder <BUILD_DIR>/clara. Then, run the following command to activate the updates:

clara.sh --up --nc

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

  

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Leave feedback