Deploy DX components using HCL DXClient and DXConnect

This section outlines features and functionality delivered as part of Continuous Integration and Continuous Delivery for HCL WebSphere Portal.

HCL WebSphere Portal 9.5 CF19 and higher includes a DXClient toolset, and DX Connect servlet that provides developers and administrators with an approach to deploy changes or improvements to the HCL WebSphere Portal platform, and partially automate the development and delivery process.

DXClient

DXClient is a tool which helps developers and administrators manage tasks such as uploading one or more portlets or Script Applications from source development environments to target HCL DX 9.5 deployments. This tool is capable of taking artifacts developed locally and deploying them to DX 9.5 servers deployed to supported on-premises platforms in standalone, cluster or farm-topologies.

Note: The DXClient tool is not supported for use with HCL DX 9.5 deployments in Red Hat OpenShift or supported Kubernetes platforms. Use of the DXClient tool with those platforms will be available in future HCL DX 9.5 update releases.

DXClient is a NodeJs based CLI tool and will require NodeJs to be installed as a prerequisite.DX Connect

DXConnect is a servlet based application deployed on top of IBM WebSphere Application Server in the HCL DX 9.5 CF19 and higher 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 machine or remote server to a source or target HCL DX 9.5 server to execute certain tasks requested via DXClient commands. See installation and configuration instructions below in this topic.

Architecture

Prerequisites

1. Node.js version 12.18.3 is the minimum supported version, and should be installed on the local workstation or automation server.
2. HCL DX 9.5 CF19 or higher is installed on target servers, on supported on premises platforms (Microsoft Windows, Linux or IBM AIX).

3. Install the DXConnect servlet using the instructions below. Once installed, ensure it is running under the Configuration Wizard (cw_profile) on target servers and is started. For more information on starting the Configuration Wizard reference this Help Center topic: Accessing the Configuration Wizard.
4. Configuration Wizard Administrator credentials are required to access the DXConnect application.

DXClient installation

Complete the following steps to install the DXClient tool to your local development workstation or automation server.

Install the DXClient tool

1. Ensure that Node.js version 12.18.3 or higher is installed to the local workstation. The DXClient tool is supported on Microsoft Windows, Linux, and Apple MacOS workstations and automation servers.

2. Download the DXClient.zip file (DXClient_VX_XXXXXXXX-XXXX.zip) to a local directory on the local workstation from the HCL WebSphere Portal 9.5 CF 19 or higher entitlements on the HCL Software License Portal. Reference the Docker topic for the latest list of HCL DX 9.5 files available for download.
3. Extract the DXClient.zip file locally.

4. From the extracted folder, run the following command.For Linux and Apple MacOS platforms:

   make install

   For Microsoft Windows platforms:

   make_install.bat

   The following commands will execute:

   

5. Run the following command below to link the application to the local npm module in your machine.For Linux and Apple MacOS platforms:

   make link

   For Microsoft Windows platforms:

   make_link.bat

   Note:

   • Avoid using this command when scripting deployments from an automation server (e.g. in pipelines) as there is a chance of picking up the wrong dependencies during tool version upgrades.

   • If the link command is not used (such as on automation servers), then use the following command below to run the application:For Linux and Apple MacOS platforms:

     ./bin/dxclient

     For Microsoft Windows platforms:

     node bin/dxclient

Verify the DXClient installation

Successful installation of the DXClient tool can be checked using the "dxclient -V" command which should show the version of the DX Client tool installed.

Once installed, commands can be executed using the DXClient tool to perform CI / CD actions on HCL DX 9.5 servers.

In HCL DX 9.5 CF19, the DXClient tool provides commands supporting two artifact types - portlets and script applications along with the documentation via help commands.

DXClient uninstall

To uninstall the DXClient tool, follow the commands below.For Linux and Apple MacOS platforms:

make clean

For Microsoft Windows platforms:

make uninstall.bat

To unlink the DXClient tool, follow the commands below.For Linux and Apple MacOS platforms:

make unlink

For Microsoft Windows platforms:

make_unlink.bat

DXClient commands Command syntax conventions is:

dxclient [command] [options]

Use the following command to execute the deploy portlet action:

dxclient deploy-portlet [options]

Use the following command to execute the undeploy portlet action:

dxclient undeploy-portlet [options]

Use the following command to execute the pull script application action:

dxclient deploy-scriptapplication pull [options]

Use the following command to execute the push script application action:

dxclient deploy-scriptapplication push [options]

DXClient Help commands

The following commands show the Help documents for DXClient command usage.Use the following commands to display the Help document for DXClient:

dxclient

dxclient -h, --help 

Use the following command to display the DXClient version number:

dxclient -V, --version

Use the following command to display the detailed help for a specific command:

dxclient help [command]

Available Artifact Types

The following are the artifact types currently supported by the DXClient tool. More will be added in later releases.

1. Portlets

Deploy Portlet

The deploy-portlet command is used to deploy one or more new or updated portlets from a source client or server environment to target HCL DX 9.5 CF 19 or higher server using a provided input XMLAccess file and deployable Portlet WAR file.

Note: The synchronization mode of all nodes in a clustered DX environment must be consistently set for a newly deployed portlet to be automatically started; otherwise redeployment or a manual start is required.

Required files

XMLAccess file

This xml file should contain the definition of the web application along with the details of the portlet(s) to be deployed. The web archive file path referred to in this file inside the URL element is ignored, but the URL element itself must exist as it is dynamically replaced when the command is executed. A sample XML file for deploying portlet(s) can be found in the samples directory of DXClient (samples/DeployPortlet.xml) or in DX server located in the following directory:  PortalServer_root/doc/xml-samples/DeployPortlet.xml.

Portlet Application web archive file

This web archive .war file should contain the necessary portlet artifacts for deployment, as per the JSR 286 portlet standard.

Command

dxclient deploy-portlet -xmlFile <path> -warFile <path>

Help command This command shows the help document on the deploy-portlet command usage:

dxclient deploy-portlet -h

Command options Use this attribute to specify the protocol with which to connect to the DX server (wp_profile):

-dxProtocol <value>

Use this attribute to specify the hostname of the target DX server:

-hostname <value>

Use this attribute to specify the port on which to connect to the DX server (wp_profile):

-dxPort <value>

Use this attribute to specify the path to DX configuration endpoint (e.g. /wps/config):

-xmlConfigPath <value>

Use this attribute to specify the username to authenticate with the DX server (wp_profile):

-dxUsername <value>

Use this attribute to specify the password for the user in the dxUsername attribute:

-dxPassword <value>

Use this attribute to specify the local path to the XMLAccess file:

-xmlFile <Absolute or relative path to XMLAccess input file>

Use this attribute to specify the local path to the WAR file to be deployed:

-warFile <Absolute or relative path to deployable war file>

Use this attribute to specify the Configuration Wizard Console port number:

-dxConnectPort <value>

Use this attribute to specify the Configuration Wizard Administrator username that is required for authenticating with the DXConnect application:

-dxConnectUsername <value>

Use this attribute to specify the Configuration Wizard Administrator password that is required for authenticating with the DXConnect application:

-dxConnectPassword <value>

Use this attribute to specify the path to the local directory where XMLAccess results should be written:

-outputFilePath <value>

All of the above command options can also be configured inside the config.json configuration file of the DXClient tool, available in the dist/src/configuration directory of the DXClient installation. Command options passed through the command line will override values set in the config.json file.

Log files from command execution can be found in the logs directory of the DXClient installation.

Undeploy Portlet

The undeploy-portlet command is used to remove a portlet application from a target HCL DX 9.5 CF 19 or higher server using a provided input XMLAccess file.

Required file

XMLAccess file

This XML file should contain the delete operation for the web application. A sample XML file for undeploying portlet(s) can be found in the samples directory of DXClient (samples/DeletePortlet.xml).

Command

dxclient undeploy-portlet -xmlFile <path>

Help command This command shows the help information for undeploy-portlet command usage:

dxclient undeploy-portlet -h

Command options Use this attribute to specify the protocol with which to connect to the DX server (wp_profile):

-dxProtocol <value>

Use this attribute to specify the hostname of the target DX server:

-hostname <value>

Use this attribute to specify the port on which to connect to the DX server (wp_profile):

-dxPort <value>

Use this attribute to specify the path to DX configuration endpoint (e.g. /wps/configwps/config):

-xmlConfigPath <value>

Use this attribute to specify the username to authenticate with the DX server (wp_profile):

-dxUsername <value>

Use this attribute to specify the password for the user in the dxUsername attribute:

-dxPassword <value>

Use this attribute to specify the local path to the XMLAccess file:

-xmlFile <Absolute or relative path to xmlaccess input file>

Use this attribute to specify the path to the local directory where XMLAccess results should be written:

-outputFilePath <value>

All of the above command options can also be configured inside the config.json configuration file of the DXClient tool, available in the dist/src/configuration directory of the DXClient installation. Command options passed through the command line will override values set in the config.json file.

Log files from command execution can be found in the logs directory of the DXClient installation. Example usage:

dxclient deploy-portlet -xmlFile <xml-file-with-path> -warFile <war-file-with-path> -outputFilePath <output-file-path>
dxclient undeploy-portlet -xmlFile <xml-file-with-path> 

2. Script Applications

The deploy-scriptapplication command is used with the DXClient tool to push or pull Script Applications between a local development workstation or automation server and DX 9.5 CF19 or higher servers. The command will push or pull the files that make up a script application to or from a Script Application instance stored in a Web Content Manager library on the server.

Required Files :

The script application push command in the DXClient tool requires a Script Application zip file or an extracted folder of the same (identified by the prebuiltZip or contentRoot attributes respectively). For more information on Script Applications, please reference the Script Application topics in the HCL DX Help Center.

Command This command invokes the deploy-scriptapplication command inside the DXClient tool to either push or pull a script application:

dxclient deploy-scriptapplication

Subcommands Use this command to create or update the content of a Script Application on the HCL DX server:

push [options]

Use this command to download the content of a Script Application from the HCL DX server:

pull [options]

Help command This command shows the help document on the  deploy-scriptapplication  command:

dxclient deploy-scriptapplication pull -h

dxclient deploy-scriptapplication push -h

Options for the pull subcommand Use this attribute to specify the protocol with which to connect to the DX server:

-dxProtocol <value>

Use this attribute to specify the hostname of the target DX server:

-hostname <value>

Use this attribute to specify the port on which to connect to the DX server:

-dxPort <value>

Use this attribute to specify the path to the  content handler  servlet on DX server (e.g. /wps/mycontenthandler):

-contenthandlerPath <value>

Use this attribute to specify the context of the virtual portal that contains the Script Application instance that we want to retrieve, if any:

-virtualPortalContext <value>

Use this attribute to specify the context of the portal project that manages the publication of changes to the Script Application instance, if any:

-projectContext <value>

Use this attribute to specify the username to authenticate with the DX server:

-dxUsername <value>

Use this attribute to specify the password for the user in the dxUsername attribute:

-dxPassword <value>

Use this attribute to specify the WCM content ID of the Script Application content item:

-wcmContentId <value>

Use this attribute to specify the absolute or relative path to a local directory in which to store the Script Application's content:

-contentRoot <value>

Options for the push subcommand Use this attribute to specify the protocol with which to connect to the DX server:

-dxProtocol <value>

Use this attribute to specify the hostname of the target DX server:

-hostname <value>

Use this attribute to specify the port on which to connect to the DX server:

-dxPort <value>

Use this attribute to specify the path to the  content handler  servlet on the DX server (e.g. /wps/mycontenthandler):

-contenthandlerPath <value>

Use this attribute to specify the context of the virtual portal that should receive the Script Application instance being pushed, if any:

-virtualPortalContext <value>

Use this attribute to specify the context of the portal project that manages the publication of changes to the Script Application instance, if any:

-projectContext <value>

Use this attribute to specify the username to authenticate with the DX server:

-dxUsername <value>

Use this attribute to specify the password for the user in the dxUsername attribute:

-dxPassword <value>

Use this attribute to specify the WCM ID of the Script Application content item:

-wcmContentId <value>

Use this attribute to specify the SiteArea containing the Script Application content item:

-wcmSiteArea <value>

Use this attribute to specify the name of the Script Application content item to be created or updated:

-wcmContentName <value>

Use this attribute to specify the full WCM path of the Script Application content item to be created or updated:

-wcmContentPath <value>

Use this attribute to set or update the title of the Script Application content item:

-wcmContentTitle <value>

Use this attribute to specify the path to the main HTML file within the Script Application:

-mainHtmlFile <value>

Use this attribute to specify the absolute or relative path to the Script Application's content as a ZIP file:

-prebuiltZip <value>

Use this attribute to specify the absolute or relative path to the Script Application's content in a directory:

contentRoot <value>

Note: At least one of (a) wcmContentId, (b) wcmContentPath or (c) both wcmContentName and wcmSiteArea must be specified. If multiple are provided, the priority order is (a), then (b), then (c).

Note: Use wcmContentId only if we are updating an existing Script Application instance - for new Script Applications specify either (a) wcmContentPath or (b) both wcmContentName and wcmSiteArea.

Note: mainHtmlFile is mandatory.

Note: If contentRoot is not provided, then the outputfile for pull will be generated inside /outputFiles/sp-pull-output.

All of the above command options can also be configured inside the config.json configuration file of the DXClient tool, available in the dist/src/configuration directory of the DXClient installation. Command options passed through the command line will override values set in the config.json file.

Example Usage:For Script Application Pull:

dxclient deploy-scriptapplication pull -contentRoot /temp -wcmContentId <wcmContentId>

If all required options are configured in  config.json  at path /dist/src/configuration of the DX Client tool, then execute:

dxclient deploy-scriptapplication pull

For Script Application Push, if the Script Application is extracted to a folder named temp at the root of the DXClient machine:

dxclient deploy-scriptapplication push -contentRoot /temp -wcmSiteArea "Script Application Library/Script Applications/" -wcmContentName DemoScriptApplication

If the Script Application is available as a .zip file in a folder named temp on the DXClient tool location, execute:

dxclient deploy-scriptapplication push -prebuiltZip /temp/DemoScriptApplication.zip -wcmSiteArea "Script Application Library/Script Applications/" -wcmContentName DemoScriptApplication

If all required options are configured in the  config.json  at the  /dist/src/configuration path  of the DXClient tool, then execute:

dxclient deploy-scriptapplication push

Troubleshooting Logs can be enabled and disabled as desired by DX developers and administrators through configuration options in the config.json file of the DX Client. The log files can be viewed inside the logs folder under the DXClient installation folder.

Note: The Logs enabling/disabling is limited to deploy-portlet command only.

Enable logger

The DXClient tool Logs can be enabled by setting the parameter enableLogger: true in the config.json file.

Disable logger

The DXClient tool Logs can be disabled by setting the parameter enableLogger: false in the config.json file.

DXConnect

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

Authentication

DXConnect requires the cw_profile Administrator security role to access the application servlet APIs.

DXConnect Installation

The DX Connect servlet is available with HCL DX 9.5 CF19 and higher releases. Install it:

./ConfigEngine.sh install-dxconnect-ear -DCwUserPwd=xxxxxx -Dcw_profile_dir=/opt/HCL/AppServer/profiles/cw_profile

• -DCwUserPwd is the password for the cw_profile Administrator.
• -Dcw_profile_dir is the profile path for cw_profile.

To verify it is installed on a given HCL DX Server 9.5 with CF19 or higher, navigate to the Configuration Wizard Admin console, and then under Enterprise Applications. The dxconnect application will appear on the console as shown in the example below. For more information on accessing and working with the Configuration Wizard, reference the Accessing the Configuration Wizard topics.

Note: The ConfigEngine task should be run under the cw_profile to have DXConnect installed in the correct location, and a restart of the cw_profile server may be required.

Endpoints references for DXClient Upload files to the target server:

POST https://<hostname>:<port>/hcl/dxconnect/processHandler?requestMethod=upload

Delete files from the target server:

POST https://<hostname>:<port>/hcl/dxconnect/processHandler?requestMethod=delete

Get response/output files generated from the target server:

GET https://<hostname>:<port>/hcl/dxconnect/processHandler?requestMethod=download&sourcepath=<path>

Here the port number should be of the cw_profile console.

Logging and Tracing for DXConnect

DXConnect logs are generated into the cw_profile server's SystemOut.log and trace.log files respectively.

• Sample Pipelines for use with DXClient A CI/CD pipeline can help automate processes in the development and test cycle, to deploying to code to the production environment. HCL DX 9.5 provides sample pipelines for use with the D Client tooling to automate deployment of portlet and Script Applications.