Streamlining Custom Portlet Deployment with HCL Digital Experience (DX) DXClient and DXConnect

Published April 29, 2023

Jose Osornio

Principal Solutions Architect

As software developers, we constantly seek ways to optimize our workflows and speed up our tasks. When dealing with enterprise Portal solutions like HCL Digital Experience (DX), our standard process for deploying a custom portlet application involves building the asset, logging into the portal software using the correct credentials, and installing the portlet via the Administration interface. This process is outdated and prone to errors since it requires several manual steps and clicks on the screen. Imagine having to repeat this tedious process repeatedly as you continue to develop and deploy your application.

illustration of the devops process

However, with the recent release of HCL Digital Experience (DX) 9.5 CF19, developers now have access to a new toolset that can streamline this process and integrate their development process with a CI/CD pipeline. The DXClient, in conjunction with DXConnect, significantly improves the development experience in this aspect.

What is DXClient and DXConnect

DXClient is a tool that developers can execute from their workstations. It is capable of taking artifacts developed locally and deploying them to a DX server deployed on-premises platforms in standalone, clustered, or farm-topologies and supported Kubernetes platforms. This tool is available as a Docker image and as a Node.js-based CLI tool. Detailed instructions on how to install DXClient are available from the HCL DX product documentation page. page. The preferred way is to use the DXClient docker image since the Node.js-based tool has been deprecated since CF196. You will need to have Docker installed on your workstation if you use the Docker image.

DXConnect is a servlet-based application deployed on top of IBM WebSphere Application Server in the HCL DX 9.5 CF19 and later deployments, under the Configuration Wizard profile – cw_profile. DXConnect enables the DXClient tool to connect over an HTTP or HTTPS connection from a client development workstation or remote server to a source or target HCL DX 9.5 server to execute certain tasks requested via DXClient commands.

The installation is done through a ConfigEngine task and is documented in detail in the HCL DX product documentation page. It can be installed onto on-premises platforms in standalone, clustered, or farm-topologies and supported Kubernetes platforms. Note that DXConnect runs on the Configuration Wizard profile in WebSphere Application Server and may not always be running. Ensure that the Configuration Wizard profile is started before using DXConnect.

Example Deployment

After installing DXClient and DXConnect, you can significantly accelerate your development workflow. To illustrate, let’s go through an example of deploying a new Portlet, creating a page, and adding the portlet to the page. Prior to the availability of DXClient, performing these tasks required manual execution via the DX user interface, but now, with just a single command, these tasks can be accomplished seamlessly.

Prerequisites:

  1. Portlet application war file. This is the application that you have created and wish to deploy to your DX environment.
  2. XML Access File. This is a file that provides instructions to DX on creating a page and basic information about the portlet that you intend to deploy. DXClient includes sample XML files that you can utilize as a starting point for deploying your portlet. Additionally, you can obtain the assets used in this example from the GitHub repository.
  3. (Optional) Set the DXClient config.json properties file with the values from your DX environment. Common command arguments can be pre-configured inside the config.json file available under /store folder of DXClient. This will allow you to run DXClient commands with limited arguments (less typing).

Let’s Deploy

  1. To confirm that DXClient is correctly installed, use the “dxclient -V” command. If installed correctly, you should see the version number of DXClient. screen shot of dxclient command

  2. Next, we will now use DXClient to create a new page in our example DX site and deploy our portlet application to that page. The creation and placement of the portlet is done using the XML Access file which you can download here. screen shot of a HCL Portal page

  3. From the command line, execute the ‘deploy-portlet’ command giving the -warFile and -xml file arguments. All other required arguments have been set in our config.json file but can also be entered as arguments in this command if needed.

    In my workstation, the war file and xml access location is under: /home/jose/Documents/HCL/portlet-sample

    dxclient deploy-portlet -xmlFile /home/jose/Documents/HCL/portlet-sample/DeployPortlet.xml -warFile /home/jose/Documents/HCL/portlet-sample/AnnouncementPortlet.war

    Note: ensure the Configuration Wizard profile is running. In my environment, it is installed under: /opt/IBM/WebSphere/AppServer/profiles/cw_profile as server1

  4. On a successful deployment, you will see output similar to this: screen shot of a successful deployment

  5. Navigate back into the DX site and ensure that the new page has been created along with the Portlet deployed. screen shot of new portal page

  6. You can continue using this same command as you continue your Portlet application development to deploy your latest changes.

Deploying Portlets and pages is just the beginning. Depending on your DX CF level, you are able to use the following commands to speed up your development process.

DXClient Commands

It is also possible to use DXClient in your CI / CD pipeline to automate deployments. HCL DX 9.5 provides sample pipelines for use with the DXClient tooling to demonstrate how the deployment of portlets, Script Applications, Themes, DX Application, export and import of WCM libraries, etc., can be automated.

Sample Pipelines

In conclusion, the availability of the DXClient and DXConnect tools have significantly improved the development experience for software developers. The traditional manual process of deploying a custom portlet application has been replaced by a streamlined process that integrates with CI/CD pipelines. With DXClient, developers can deploy artifacts developed locally to a DX server deployed on-premises or on supported Kubernetes platforms. By automating the deployment of portlets, Script Applications, Themes, DX Application, export, and import of WCM libraries, etc., the DXClient tooling is an essential tool for any enterprise Portal solutions like HCL Digital Experience.

Resources:

https://help.hcltechsw.com/digital-experience/9.5/containerization/dxclient.html

https://help.hcltechsw.com/digital-experience/9.5/containerization/dxconnect.html

https://help.hcltechsw.com/digital-experience/9.5/config/cw_run.html

https://help.hcltechsw.com/digital-experience/9.5/containerization/sample_pipelines_for_use_with_dx_client_and_automation_servers.html

https://github.com/joseoso/hcl-deploy-portlet-example