Skip to content

DXClient

DXClient is a command line tool featuring a single, unified interface to all HCL DX automation and CI/CD-related tasks. It helps developers manage several DX tasks such as uploading one or more portlets, Script Applications, and themes. Administrators can manage WCM libraries, PZN rules, shared libraries, etc.

DXClient can take artifacts developed locally and deploy them to HCL DX servers independently of whether these are deployed on-premises platforms in standalone, cluster, or farm-topologies, or in a container environment.

DXClient is meant to be the one-stop, platform-independent solution that lets you integrate HCL DX with any automation infrastructure of your choice.

DXClient comes with two deployment options:

  1. The default deployment option is the DXClient container package. DXClient is packaged as a container that can be run using OCI-based runtimes such as Docker or Podman. It is available as a container image from HCL DX 9.5 CF196 and later releases. See the DXClient installation for more details.

  2. For backward compatibility, we also still offer DXClient JavaScript source codes. Customers who want to rely on this deployment option need to install their own Node.js and npm runtime environment in the correct version and must install necessary dependencies as needed.

Architecture

The following image illustrates the DXClient Architecture diagram:

HCL DXclient Architecture diagram

Installing DXClient using the container package

The container package provides a fully packaged OCI-compliant container that contains everything to successfully run DXClient. You may use any container runtime that implements OCI Runtime Specification (for example, Docker or Podman).

In addition, the package includes scripts for all operating systems that make it simpler to work with the container image. These scripts handle the storage for the container and sync input files with the container itself.

Note

When you upgrade to use the container image DXClient, you must first uninstall the Node.js DXClient.

  1. Navigate to the <working-directory> folder where you wish to use the DXClient from.

  2. Download the DXClient.zip file (DXClient_VX_XXXXXXXX-XXXX.zip) to a local directory on the local workstation from your HCL Digital Experience 9.5 CF196 or higher entitlements on the HCL Software License Portal.

    Note

    If you are upgrading from the node to container image version of DXClient, you must first uninstall or unlink the current version using the following command before installing the newer version.

    make unlink

    make_unlink.bat

  3. Extract the DXClient.zip file.

    Note

    The default OCI runtime for DXClient is docker. If you wish to use any other OCI runtime, run the following command before proceeding further.

    export CONTAINER_RUNTIME=<YOUR_CONTAINER_RUNTIME>

# For example: export CONTAINER_RUNTIME=podman

    set CONTAINER_RUNTIME=<YOUR_CONTAINER_RUNTIME>

:: For example: set CONTAINER_RUNTIME=podman

  4. Load dxclient.tar.gz image.

    docker load < dxclient.tar.gz

    docker load -i dxclient.tar.gz

  5. Optional: Add DXClient to your PATH. Open terminal and add path to the DXClient bin directory to your PATH variable to be able to call DXClient from any directory. If you plan to run multiple versions of DXClient on the same system in parallel, you may want to skip this step.

    export PATH=<working-directory>/bin:$PATH

    Open command prompt, add dxclient.bat script in the bin directory to the PATH variable, to call DXClient from any directory.

    set PATH=<working-directory>\bin;%PATH%

    Note

    You will lose these changes by closing the terminal/command prompt. If you set in system path permanently, kindly take the necessary steps to remove it.

  6. Set appropriate read and execute permissions as per user/group/owner.

    chmod xxx <working-directory>/bin

# where xxx is a 3-digit number where each digit can be anything from 0 to 7.
# Ref: https://wiki.archlinux.org/title/File_permissions_and_attributes#Numeric_method
    1. Right click <working-directory>/bin directory > "Properties" > "Security" Tab.
    2. Set the appropriate permission for the folder.

  7. Run dxclient -V to verify that the required version of DXClient command line is installed.

  8. A folder named store will be created in your working directory. This is the shared volume location of your container. If you require to create a new volume directory for a different configuration, set the VOLUME_DIR to the desired directory name and run your task. For example:

    export VOLUME_DIR=storeForScriptApplication

# or if you want spaces in its value, enclosed it in double quotes ("")
export VOLUME_DIR="store for script application"

    set VOLUME_DIR=storeForScriptApplication

:: or if you want spaces in its value
set VOLUME_DIR=store for script application

    Warning

    Do not enclose the value of VOLUME_DIR in double quotes ("") in Windows. This will produce unwanted errors when executing dxclient commands.

    The VOLUME_DIR will require read and write access permissions. Set appropriate permissions for the VOLUME_DIR as per user/group/owner.

    chmod xxx <working-directory>/<VOLUME_DIR>

# where xxx is a 3-digit number where each digit can be anything from 0 to 7.
# Ref: https://wiki.archlinux.org/title/File_permissions_and_attributes#Numeric_method
    1. Right click <working-directory>/<VOLUME_DIR> directory > "Properties" > "Security" Tab.
    2. Set the appropriate permission for the folder.

  9. You can find the configuration, logger, output, and sample files under location <working-directory>/<VOLUME_DIR>.

    Common command arguments can be pre-configured inside the config.json file available under the <working-directory>/<VOLUME_DIR> folder. A sample configuration file that can be used on on-premises platforms in standalone, cluster (default-config.json) or kubernetes (default-config-kube.json) platforms is also available under /samples/sample-configurations for reference. If you want to override any of the parameters in the config.json, add them in your command line.

  10. Refer to the sample pipeline provided to find out how to integrate the container image in the automation server.

  11. By default, the logs will be available in UTC format. If needed, synchronize your local timezone from host to container using an environment variable as shown in the example below.

    Example Usage:

    export Timezone=Asia/Kolkata

    SET Timezone=Asia/Kolkata

Installing DXClient using the source code package

Note

You are encouraged to use the DXClient container image package from CF196 onwards for easier installation.

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

    Note

    If you are upgrading from CF19, CF191, or later releases, you should first unlink the current version using the following command before installing the newer version.

    make unlink

    make_unlink.bat

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

  3. Download the DXClient.zip file (DXClient_VX_XXXXXXXX-XXXX.zip) to a local directory on the local workstation from your DX 9.5 CF19 or later entitlements on the HCL Software License Portal.

  4. Extract the DXClient.zip file.

  5. From the extracted folder, run the following command.

    make install

    make_install.bat

  6. Optional: Run the following command to link your application to the local npm module in your machine. Refer to the following Notes section before you proceed.

    make link

    make_link.bat

    Note

    • Avoid using this command when scripting deployments from an automation server (for example, 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 to run the application:
    ./bin/dxclient

    node bin/dxclient

Uninstalling DXClient using the source code package

  • To uninstall the DXClient tool, perform the following commands:

    make clean

    make_uninstall.bat

  • Optional: To unlink the DXClient tool, perform the following commands:

    make unlink

    make_unlink.bat

Verifying your DXClient installation

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

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

Important

The DXClient version is mostly forward and backward compatible with the DX CF versions. However, in some cases, it might not work as expected if the CF versions are different. Make sure that the CF versions of both DXClient and DX Core are the same in your installation. You can use "dxclient version-compat" to check version compatibility between DX Core and DXClient.

Note

Refer to the list of features that were released in the following HCL DX 9.5 Container releases:

Additional Information

  1. The attribute -dxConnectHostname has been deprecated (since CF202) and removed (since CF210) and must be replaced with -hostname wherever necessary.
  2. The attribute -targetServerHostname, -targetServerPort,-targetServerUsername,-targetServerPassword & -targetServerProfileName has been deprecated (since CF202) and removed (since CF210) and must be replaced with -targetHostname, -targetDxConnectPort,-targetDxConnectUsername,-targetDxConnectPassword & -targetDxProfileName respectively wherever necessary.
  3. If deploying or importing huge CICD artifacts using DXClient to the Kubernetes environment, you might receive failure or request pending messages while you run the ceratin tasks. This might happen because of the connection getting closed by the load balancer due to timeout before the response is ready. In such situations, before re-triggering the request, we advise you to check your target server to verify if the artifact has been deployed/imported or the server is up, as the request was already triggered from the client-side. In cases of request pending you are expected to receive a requestId which you can use to check the status of response later. Find troubleshooting tips here.
  4. The maximum input file size allowed in DXClient is 256 MB currently. This limitation will be addressed in one of the future releases.
  5. As of CF213, the property DXCONNECT_MAX_MEMORY_SIZE_MB in DXC_ConfigSettings Resource Environment Provider has been removed. Refer DXC_ConfigSettings for more details.

Configuring DXClient

Common command arguments can be pre-configured inside the config.json file available under dist/src/configuration folder. A sample configuration file that can be used on on-premises platforms in standalone, cluster (default-config.json), or kubernetes (default-config-kube.json) platforms is also available under /samples/sample-configurations for reference. If you want to override any of the parameters in the config.json, add them in your command line.

{
    "name":"config.json",
    "desc":"The attributes in this file are used for configuration purpose and those must not be deleted.",
    "dxProtocol": "",
    "dxConnectProtocol": "https",
    "hostname": "",
    "dxPort": "",
    "dxSoapPort": "10033",
    "dxConnectPort": "10202",
    "dxContextRoot":"/wps",
    "contenthandlerPath": "/wps/mycontenthandler",
    "projectContext": "",
    "virtualPortalContext": "",
    "xmlConfigPath": "/wps/config",
    "damAPIPort": "",
    "ringAPIPort": "",
    "damAPIVersion": "v1",
    "ringAPIVersion": "v1",
    "dxConnectHostname": "",
    "dxConnectUsername": "",
    "dxConnectPassword": "",
    "dxUsername": "",
    "dxPassword": "",
    "dxProfileName": "",
    "dxProfilePath": "",
    "dxWASUsername": "",
    "dxWASPassword": "",
    "enableLogger": true,
    "enableBackup": "false",
    "lastModifiedAfter": "",
    "restoreAsPublished": false,
    "targetHostname": "",
    "targetDxConnectPort": "",
    "targetDxConnectUsername":"",
    "targetDxConnectPassword":"",
    "targetDxProfileName": "",
    "targetServerHostname": "",
    "targetServerPort": "",
    "targetServerUsername":"",
    "targetServerPassword":"",
    "targetServerProfileName": "",
    "vaultUsername": "",
    "vaultPassword": "",
    "wcmContentName": "",
    "wcmContentId": "",
    "wcmContentPath": "",
    "wcmSiteArea": "",
    "wcmLibraryId": "",
    "wcmLibraryName": "",
    "wcmProjectName": ""
}

DXClient commands

Command syntax conventions:

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 xmlaccess action:

dxclient xmlaccess [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]

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

dxclient undeploy-scriptapplication [options]

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

dxclient restore-scriptapplication [options]

Use the following command to execute the deploy application action:

dxclient deploy-application [options]

Use the following command to execute the DX Core restart action:

dxclient restart-dx-core

Use the following command to restart DX Core pods in a Kubernetes deployment:

dxclient restart-core-pods [options]

Use the following command to execute manage-subscriber action:

dxclient manage-subscriber -h

Use the following command to execute manage-syndicator action:

dxclient manage-syndicator -h

Use the following command to execute the deploy theme action:

dxclient deploy-theme [options]

Use the following command to execute the undeploy theme action:

dxclient undeploy-theme [options]

Use the following command to execute the manage-syndicator get-syndication-report action:

dxclient  manage-syndicator get-syndication-report [options]

Use the following command to execute the shared-library action:

dxclient  shared-library [options]

Use the following command to execute the delete DAM schema action:

dxclient delete-dam-schema [options]

Use the following command to list all DAM schemas present:

dxclient list-dam-schemas  [options]

Use the following command to export the personalization rules from the target server:

dxclient pzn-export  [options]

Use the following command to import the personalization rules into the target server:

dxclient pzn-import  [options]

Use the following command to manage virtual portal tasks in the DX server:

dxclient manage-virtual-portal [options]

Use the following command to register subscriber:

dxclient manage-dam-staging register-dam-subscriber [options]

Use the following command to deregister subscriber:

dxclient manage-dam-staging deregister-dam-subscriber  [options]

Use the following command to trigger manual sync:

dxclient manage-dam-staging trigger-staging  [options]

Use the following command to create credential vault slot in the DX server:

dxclient create-credential-vault  [options]

Use the following command to create the syndication relation between syndicator and subscriber in DX server:

dxclient create-syndication-relation  [options]

Use the following command to create, update, delete, export or import a custom property from an existing Resource Environment Provider:

dxclient resource-env-provider [options]

Use this command to export WCM libraries:

dxclient wcm-library-export

Use this command to import WCM libraries:

dxclient wcm-library-import

Use the dx-core-configuration-reports command to get a summary of the configurations of a single DX server or both source and target DX servers, which users can use to compare.

dxclient dx-core-configuration-reports [OPTIONS]

Use this command to sync WebDAV themes in server and then watch for succeeding changes which will immediately reflect in the WebDAV Server:

dxclient livesync push-theme [options]

Use this command to download the theme files in WebDAV Server in preparation for livesync push-theme:

dxclient livesync pull-theme [options]

Use this command to show version compatibility details between DX Core and DXClient version-compat:

dxclient version-compat [options]

DXClient command line help

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]

HCLSoftware U learning materials

For an introduction and a demo on how to use DXClient, go to Staging. To try it out yourself, refer to DXClient Lab.

Related information