228.0.0 • Published 4 months ago

@hcl-software/dxclient v228.0.0

Weekly downloads
-
License
Licensed Material...
Repository
-
Last release
4 months ago

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.

Table of Contents

Deployment Options

  1. This documentation, recommended for local developers and admins, is for the Native JavaScript Code Installation Option of DXClient.

  2. One other option is the DXClient container package which is preferred for CI/CD automation scenarios. 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 with HCL DX 9.5 CF196 and later releases. More information could be found in the dxclient-scripts.

Important Note related to DXClient version & distribution: DXClient is now available free to download/install through NpmJS and harbor repositories. Following the decision to openly distribute DXClient, we have changed the current versioning format of DXClient from 1.xx.x to CFNumber.x.x. For example, the old release version of DXClient was "1.29.0" but the upcoming releases is reformatted to "221.0.0". The number 221 is synonymous with the CF Number version of DX deployments.

This document is for the native JS (non-container) version of DXClient

Native JavaScript Code Installation Options

  1. From NpmJS Registry:

    1. To install globally (Recommended): npm install -g @hcl-software/dxclient
    2. To install locally: npm install @hcl-software/dxclient
    3. To uninstall: npm uninstall @hcl-software/dxclient
  2. From HCL Software Portal:

    • Download the DXClient.zip file from your HCL Digital Experience 9.5 CF196 or higher entitlements.
    • Run make install to install all dependencies (for Windows, run make_install.bat).
    • (Optional but recommended) Link your application to the local npm module: make link (for Windows, run make_link.bat), this will make your dxclient available globally.
    • Run dxclient -V to verify the installation.

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 (Option 1.1). Use "./node_modules/.bin/dxclient -V" when installed locally (Option 1.2).

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 may use "dxclient version-compat" to check version compatibility between DX Core and DXClient.

DXClient configuration

Common command arguments that are listed in config.json can be pre-configured via this file. The common arguments could also be provided through command line. If so, it will override the values in config.json and execute. This json file will be generated in the store folder that is created where you executed the dxclient command.

A sample configuration file that could be used on-premises platforms in standalone, cluster platforms is also available under here for reference.

Configuring TLS Certificate Validation for Secure Connections

As part of our ongoing efforts to improve security and maintain best practices in our development and production environments, we have made a key change in the way we handle TLS (Transport Layer Security) connections while using DXClient from CF226. You can still trust custom certificates (e.g., self-signed or third-party CAs), without disabling validation entirely.

Step 1: Obtain the Certificate Ensure you have the .pem certificate file that you wish to add to the trust store. It must contain the whole content of both key and certificate files.

Step 2: Add the certificate You have two ways to add/set the Certificate file. a. Using NODE_EXTRA_CA_CERTS By enabling NODE_EXTRA_CA_CERTS, we now provide a secure way to add custom trusted certificates. To use the NODE_EXTRA_CA_CERTS environment variable, you need to specify the path to a PEM file that contains the key & certificate details. Here's how you can configure it in your local or production environment:

"Linux and Apple macOS"

export NODE_EXTRA_CA_CERTS=/Users/myUser/my-cert.pem

"Microsoft Windows"

set NODE_EXTRA_CA_CERTS=C:\Users\myUser\my-cert.pem

b. Add certificate to the trust store on your OS.

Note In local or development environments, you may want to disable this security feature to allow connections to services with self-signed or invalid certificates. By setting NODE_TLS_REJECT_UNAUTHORIZED to 0, you can bypass certificate validation. This can be useful for testing, but it should never be used in production environments because it can expose your application to potential security risks.

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]

Use the following command to show version compatibility details between DX Core and DXClient:

dxclient version-compat [command] [options]

All available commands

CommandDescription
dxclientHelp document for the commands usage
dxclient version-compatCommand to show version compatibility details
dxclient accept-licenseCommand to explicitly accept the license without prompt
dxclient deploy-portlet optionsCommand to execute the deploy portlet action
dxclient undeploy-portlet optionsCommand to execute the undeploy portlet action
dxclient xmlaccess optionsCommand to execute the xmlaccess action
dxclient deploy-scriptapplication optionsCommand to execute the deploy script application action
dxclient undeploy-scriptapplication optionsCommand to execute the undeploy script application action
dxclient restore-scriptapplication optionsCommand to execute the restore script application action
dxclient deploy-theme optionsCommand to execute the deploy theme action
dxclient undeploy-theme optionsCommand to execute the undeploy theme action
dxclient deploy-application optionsCommand to execute the deploy application action
dxclient undeploy-application optionsCommand to execute the undeploy application action
dxclient manage-syndicator optionsCommand to execute the syndicator action
dxclient manage-subscriber optionsCommand to execute the subscriber action
dxclient restart-dx-core optionsCommand to execute the DX Core restart action
dxclient mls-export optionsCommand to export content of a WCM Library for translation
dxclient mls-import optionsCommand to import the translated contents into the DX
dxclient manage-syndicator get-syndication-report optionsCommand to execute the syndication failed report
dxclient delete-dam-schema optionsCommand to execute the delete dam schema action
dxclient list-dam-schemas optionsCommand to execute the list of all dam schema action
dxclient pzn-export optionsCommand to export the pzn rules from the target server
dxclient pzn-import optionsCommand to import the pzn rules into the target server
dxclient resource-env-provider optionsCommand to create, update or delete a custom property from an existing Resource Environment Provider
dxclient manage-virtual-portal optionsCommand to manage virtual portal tasks in the DX server
dxclient manage-dam-staging register-dam-subscriber optionsCommand to execute the register subscriber action
dxclient manage-dam-staging trigger-staging optionsCommand to execute the trigger staging action
dxclient manage-dam-staging deregister-dam-subscriber optionsCommand to execute the deregister subscriber action
dxclient manage-dam-staging get-all-subscribers optionsCommand to execute the get subscribers details action
dxclient manage-dam-staging update-secrets optionsCommand to execute the update secrets action
dxclient manage-dam-staging find-staging-mismatch optionsCommand to execute the find mismatch action
dxclient manage-dam-staging get-staging-mismatch-report optionsCommand to generate staging mismatch report
dxclient manage-dam-staging start-staging-resync optionsCommand to execute the staging resync action
dxclient manage-dam-staging delete-staging-mismatch optionsCommand to execute the delete staging mismatch action
dxclient create-credential-vault optionsCommand to create credential vault in the DX server
dxclient wcm-library-export optionsCommand to export the wcm libraries from the target server
dxclient wcm-library-import optionsCommand to import the wcm libraries from the target server
dxclient dx-core-configuration-reports optionsCommand to generate any dx core configuration reports
dxclient manage-dam-assets export-assets optionsCommand to export the dam assets
dxclient manage-dam-assets validate-assets optionsCommand to validate the dam assets
dxclient manage-dam-assets import-assets optionsCommand to import the dam assets
dxclient restart-core-pods optionsCommand to execute the Restart Core Pods action (for Kubernetes deployments)
dxclient livesync push-theme optionsCommand for watching a theme folder path live and syncs it in DX Server
dxclient livesync pull-theme optionsCommand for downloading theme files from DX Server to a target local theme folder
dxclient livesync pull-wcm-design-library optionsCommand for downloading WCM Design Library files from DX Server to a target local folder
dxclient livesync push-wcm-design-library optionsCommand watching a WCM Design Library folder path live and syncs it in DX Server

Command options

AttributeDescription
-hostname valueUse this attribute to specify the hostname of the target server
-dxConnectProtocol valueUse this attribute to specify the protocol with which to connect to the CW server
-dxConnectUsername valueUse this attribute to specify the username that is required for authenticating to the cw_profile
-dxConnectPassword valueUse this attribute to specify the password that is required for authenticating to the cw_profile
-dxConnectPort valueUse this attribute to specify the port number of the cw_profile (for Kubernetes Environment dxConnectPort is 443)

Logger enablement

Enable Logger

Logger can be enabled by setting parameter "enableLogger": true in the config.json file. If logger enabled then logger file will be generate in logs folder of the dxclient.

If logger enabled then logger file will be available in the below location: store/logs/

Disable Logger

Logger can be disabled by setting parameter "enableLogger":false in the config.json file

DXClient Release Timelines & Updates

  • deploy/undeploy portlets
  • deploy script applications
  • xmlaccess
  • restore script application
  1. If connecting to an HCL DX 9.5 CF192 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • undeploy script applications
  • deploy themes (EAR & WebDAV based)
  1. If connecting to an HCL DX 9.5 CF193 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • restart application
  • deploy application
  • manage syndicator
  • manage subscriber
  1. If connecting to an HCL DX 9.5 CF195 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • undeploy theme
  1. If connecting to an HCL DX 9.5 CF196 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • shared library
  1. If connecting to an HCL DX 9.5 CF197 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • Get Syndication failed report
  • Delete DAM schema
  1. If connecting to an HCL DX 9.5 CF198 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • Resource Environment Provider Updates - Create,update and delete
  • Create/import/export/list of virtual portal
  • Import and Export PZN
  • List DAM schemas
  1. If connecting to an HCL DX 9.5 CF199 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • Resource Environment Provider Updates - Export and Import
  • Create Credential Vault Slot
  • Create Syndication Relation
  • DAM Staging - Register, Deregister and Trigger
  1. If connecting to an HCL DX 9.5 CF200 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • WCM Libraries - Export and Import
  • DX Core Configuration Reports - summary-report
  1. If connecting to an HCL DX 9.5 CF201 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • An optional parameter requestId added to Deploy theme, Deploy application, Restart DX Core server, and Manage virtual portals.
  • Retrieve feature added to the Resource environment provider.
  • Accessing ConfigWizard in container environment Note that a few parameters are deprecated and replaced with new parameters in the DX Core configuration reports. For information, see DX Core server configuration report.
  1. If connecting to an HCL DX 9.5 CF202 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • Deprecated parameter dxConnectHostname. It is recommended that you start using the replacement parameter -hostname starting from CF202 wherever necessary.
  • DAM Assets Export & import
  1. If connecting to an HCL DX 9.5 CF207 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • Support to set different Container Runtimes.
  1. If connecting to an HCL DX 9.5 CF208 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • Get all subscribers details for DAM staging
  1. If connecting to an HCL DX 9.5 CF209 deployment, the DXClient tool provides commands supporting the following additional artifact types along with the documentation
  • Restart Core Pods in a Kubernetes Deployment
  1. If connecting to an HCL DX 9.5 CF210 deployment, following changes are to be expected.
  • Removed paramaters deprecated during CF201 & CF202 deployment.
  • added ability to export/import wcm libraries in Virtual Portal.
  1. If connecting to an HCL DX 9.5 CF211 deployment, following changes are to be expected.
  • Deploy and Undeploy Applications
  1. If connecting to an HCL DX 9.5 CF213 deployment, following changes are to be expected.
  • Livesync of WebDAV based Themes
  1. If connecting to an HCL DX 9.5 CF214 deployment, following changes are to be expected.
  • Livesync Improvements
    • List themes during Pull theme in case themeName is not provided.
    • Livesync is now supported in scaled DX environment setups
  1. If connecting to an HCL DX 9.5 CF216 deployment, following changes are to be expected.
  • Show Version compatibility details between DXCore and DXClient
  1. If connecting to an HCL DX 9.5 CF219 deployment, following changes are to be expected.
  • Enabled multiple environment configuration in node version
  1. If connecting to an HCL DX 9.5 CF221 deployment, following changes are to be expected.
  • DXClient Version Type(Node/Container) information available using help/version-compat commands
  • A one time license agreement click-through is enabled. To skip the prompt, use "accept-license" command.
  • DXClient will be openly distributed in NPMJS & Harbor repository.
  1. If connecting to an HCL DX 9.5 CF224 deployment, following changes are to be expected.
  • LiveSync Pull and Push commands for WCM Design Library are now available for HTML and Folder Components.
  1. If connecting to an HCL DX 9.5 CF225 deployment, following changes are to be expected.
  • LiveSync now supports Presentation Templates.
  1. If connecting to an HCL DX 9.5 CF226 deployment, following changes are to be expected.
  • DXClient no longer ignores certificates that cannot be properly validated when using Transport Layer Security (TLS) connections
  • New documented limitations for LiveSync
  • Updated scripts to pass certificates to container.
  1. If connecting to an HCL DX 9.5 CF227 deployment, following changes are to be expected.
  • LiveSync now supports Style-Sheet Components.
  1. If connecting to an HCL DX 9.5 CF228 deployment, following changes are to be expected.
  • XML Access max request file size can now be changed in the config.json at xmlAccessMaxFileSizeMB. Default set as 256MB, changing this might result to unexpected results.

DXClient Documentation

Full documentation of DXClient can be found here.