Transaction server Run Engine commands

Use the following Run Engine commands to configure the Transaction server Docker container.

The following table contains the default Run Engine commands. To view the scripts, start with /SETUP/bin/entrypoint.sh. If you want to implement custom logic or override existing configurations, ensure that the necessary parameters can be resolved by the commands during startup.

Run Engine commands for the Transaction server.

Description Command
Converts the environment to an authoring environment. run convert-to-auth

Convert the ts-app live image to authoring image.

Set or change the merchant key. run update-encrypted-merchantkey MERCHANTKEY_ENCRYPT
MERCHANTKEY_ENCRYPT
The encrypted merchant key, encrypted with the key encryption key. The merchant key was created when you or an administrator loaded the HCL Commerce database schema.
For more information, see:
Important: You must specify your own merchant key and key encryption key values for the security of your HCL Commerce installation. Do not use the default values contained within the provided sample configuration files and documentation examples.
HCL Commerce Version 9.1.9.0 or laterSet or change the key encryption key. run update-key-encryption-key KEY_ENCRYPTION_KEY
KEY_ENCRYPTION_KEY
The plain text key that is used to encrypt the merchant key. The key encryption key is required to be 32 characters.
The SPI username and password is used for inter-component server API invocation only. The spiuser is configured in the Store server, Search server and Customization server, and used in the API invocation from those servers to the Transaction server. The images need to be configured with the spiuser password, otherwise the component servers cannot connect to the Transaction server.

Sets Java virtual machine (JVM) property: spi.username, spi.password

run set-spi-user userName ASCII_encrypted_password
userName
SPI username. The default user name is spiuser.
password
The ASCII encrypted password. You can encrypt the password by using utilities_root/wcs_encrypt.sh utility.
For development or authoring environment, set Search server name binding. run set-search-server search_host search_port
search_host
Search host name.
search_port
Search port.
For live environments, set the Search server name binding for the Search repeater. run set-search-server search_host search_port search_repeater_host search_repeater_port
search_host
Search host name.
search_port
Search port.
search_repeater_host
Search Repeater hostname, for live environments.
search_repeater_port
Search Repeater port, for live environments (for example, 3738).
Set the connection to the Ingest server. run set-ingest-server hostName port
hostName
The Ingest server host name.
port
The Ingest server port.
For authoring environments, add JAAS, JDBC provider, datasource connection information to connect to the live database. run add-datasource jndi dbName dbType dbHost dbPort dbUser dbPass xa sslConnect
jndi
The name of the JNDI.
The default value for the Transaction server is jdbc/WCDataSource.
dbName
The name of the database.
dbType
The database type.
For example, db2.
dbHost
The host name of the database server.
dbPort
The database server port.
dbUser
The database user name.
dbPass
The database password.
xa
A boolean value. Determines whether it is an XA data source. Set this value to false if you are using the default datasource.
sslConnect
A boolean value. Enable SSL connection.
Configure the connection to the Store server. run set-store-server hostName port
hostName
Store host name.
port
Store port.
Set Store server host name in the foundation wc-component.xmlconfiguration file. sed -i "s/value=\"store\"/value=\"${STORE_HOST}\"/g" /opt/WebSphere/AppServer/profiles/default/installedApps/localhost/ts.ear/xml/config/com.ibm.commerce.foundation/wc-component.xml
Note: This is not a Run Engine command, but it is a configuration that is required for the Management Center store preview function to work. If the host name of your Store server Docker container is not store, then you must change the value as needed using this command.
Set the connection to the React-based store Store server. run set-react-store-server hostName port
hostName
The React-based store Store server host name.
port
The React-based store Store server port.
Configure the connection to the Customization server. run set-xc-server hostName port
hostName
The Customization server host name.
port
The Customization server port number.
Configure the connection to the Store server web server for stores that have been migrated from WebSphere Commerce Version 7 or Version 8. run set-store-web-server storeWebHost storeWebPort
storeWebHost
Host name of the web server for the migrated store.
storeWebPort
Web server port.
Add a database connection datasource for Informix. run add-datasource-informix dbtype dbName dbHost dbPort dbUser dbPass xa sslConnect
dbType
The database type. For example, Informix.
dbName
The name of the database.
dbHost
The host name of the database server.
dbPort
The database server port number.
dbUser
The database user name.
dbPass
The database user password.
xa
A boolean value that specifies whether it is an XA data source. Set this value to false if you are using the default data source.
sslConnect
A boolean value that specifies if the connection should be secured via SSL.
Update the database user and password credentials that are used to connect to the database. run update-datasource-cred jndi dbUser dbPass
jndi
The name of the JNDI.
The default value for the Transaction server is jdbc/WCDataSource.
dbUser
The user name to connect to the DB2 database.
dbPass
The password for the dbUser.
Update the database server host name, port, database name, and the user and password credentials that are used to connect to the database. run update-datasource-db jndi database dbHost dbPort sslConnect
jndi
The name of the JNDI.
The default value for the Transaction server is jdbc/WCDataSource.
database
The name of the database.
dbHost
The host name of the database server.
dbPort
The database server port.
sslConnect
(Optional) Enable or disable the SSL protocol. If set to True, SSL is used. If False, SSL is disabled.
Add the JVM parameter string to existing JVM options (/Server:server1/JavaProcessDef:/JavaVirtualMachine:/). run add-generic-jvmarg jvmArg
jvmArg
The JVM argument.
For example, the following command sets -Xgcpolicy:gencon to a generic JVM argument.
run add-generic-jvmarg -Xgcpolicy:gencon 
Create new object cache instance. You can see the object cache list in Resources/Cache instances/Object cache instances of the WebSphere Application Server Administrative Console in the Transaction server. run add-objectcache jndiName cacheSize replicationType sizeMB
jndi
The JNDI name of the object cache.
cacheSize
(Integer) The maximum size, in number of entries, of the object cache.
replicationType
Important: This parameter is deprecated and is currently ignored. It is kept for backwards compatibility only and will be removed in future releases.
Replication type of the object cache. Valid values are:
  • PULL
  • PUSH
  • PUSH_PULL
  • NONE
sizeMB

Optional: (Integer) The size of the object cache in megabytes (MB).

Note: This command adds an object cache instance if one does not exist.
Updates virtualhosts.xml. run add-virtual-host VirtualHostName ListOfPorts
VirtualHostName
Name of the virtual host.
ListOfPorts
A comma-separated list of port aliases for the virtual host.
For example,
run add-virtual-host MyVirtualHost 24,40000,50600
Create a reserved work manager and set the maximum thread number to 10. run add-work-manager-reserved
Create a work manager and set the maximum number of threads. run add-work-manager name maxThread
name
The Work Manager name.
maxThread
The maximum number of threads for the work manager. Adds a Work Manager if it does not exist.
Enable application security. run enable-security appName
appName
Application name.

Configuration default values for activeUserRegistry, Authtype, AppSecurityEnablement, WIMuserRegistry, and mapping role to users.

Enable servlet and command caching for web container setting. run enable-servlet-caching

Enables servlet caching

For example, run enable-servlet-caching

Check whether the server1 is started by running the serverStatus command. run get-status
Reset the trace level to its default value (*=information). run reset-dynamic-trace-specification
Configure the database data source connection property. run set-connection-pool jndi connectionTimeout maxConnections minConnections reapTime unusedTimeout agedTimeout purgePolicy
jndi
The JNDI name of the datasource.
connectionTimeout
The time in seconds connection request waits before timeout exception.
maxConnections
The maximum number of physical connections in this pool.
minConnections
The minimum number of physical connections in this pool.
reapTime
The time interval in seconds to start the pool maintenance thread.
unusedTimeout
The time in seconds after which discard an unused connection.
agedTimeout
The time in seconds before a physical connection is discarded.
purgePolicy
The policy to purge connections when a connection error is detected.

For example, EntirePool or FailingConnectionOnly

Set the trace level. run set-dynamic-trace-specification spec
spec
The new logging trace specification.
Set the initialHeapSize and maximumHeapSize values. run set-heap-size initHeapSize maxHeapSize
initHeapSize
The minimum heap size.
maxHeapSize
The maximum heap size.
Create string name space binding. run set-jndi-entry jndi value
jndi
The JNDI name.
value
The JNDI value.
Set JPA specification compliance level. run set-jpa-spec-level level
level
Specification compliance level.
Updates an existing server property or adds a server property. run set-server-property propertyName propertyValue
propertyName
The property name.
propertyValue
The property value.

For example, run set-server-property threshold 1800

Set SSL protocol for SSL setting. run set-ssl-protocol sslProtocol
sslProtocol
SSL protocol value. Valid values are are
  • SSL_TLSv2
  • TLS
  • TLSv1
  • TLSv1.1
  • TLSv1.2
  • SSL_TLS
  • SSL
  • SSLv2
  • SSLv3
Sets the alias of the certificate to use for the server. run set-ssl-server-alias alias
alias
The certificate alias for the server.
Change WebSphere Application Server data source properties (statement cache size) for a specific data source. run set-statement-cache jndi cacheSize
jndi
JNDI name of the datasource.
cacheSize
Value for StatementCacheSize.
Set a custom JVM property. run set-system-property name value
name
JVM system property name.
value
JVM system property value.

For example, run set-system-property SKIP_IDENTIFIER_CHECK true

Sets a JVM custom property SKIP_IDENTIFIER_CHECK to true.

Set application thread pool properties. run set-thread-pool threadName minSize maxSize inactivityTimeout isGrowable
threadName
Thread name.
minSize
Minimum size.
maxSize
Maximum size.
inactivityTimeout
Thread inactivity timeout.
isGrowable
Determines whether the pool can grow. Valid values are true or false.

For example, run set-thread-pool webContainer 60 60 3000 false

Make trace.log and ffdc log generate to this directory. run set-trace-log-directory directory
directory
The location to write the logs.
Enable specific trace. run set-trace-specification spec
spec
The new logging trace specification.
Note: set-trace-specification does not work when JSON/HPEL logging mode is enabled. You must create your own custom run engine command to set trace specification with this mode.
Set a web container property.

Add custom properties for web container settings (for example, HideSessionValues, or httpOnlyCookies).

run set-webcontainer-property name value
name
Property name.
value
Property value.

For example, run set-webcontainer-property httpOnlyCookies WC_GENERIC_ACTIVITYDATA,WC_AUTHENTICATION_*

Change the WebSphere Application Server administrator user password. run update-admin-password adminUser adminPassword
adminUser
Name of the WebSphere Application Server admin.
adminPassword
New password for the WebSphere Application Server administrator.
Update all keystores that use the provided new password. run update-keystore-passwords currentPassword newPassword
currentPassword
The current password.
newPassword
The new password.

For example, run update-keystore-passwords aaa bbb

Create a transport chain on specified server name and node name. run add-transport-chain chainName endPointName host port
chainName
The transport chain name.
endPointName
The transport end point name.
host
The hostname for the port.
port
The port number.
Update the thread poll value of the TCP inbound channel for the specified end point. run update-tcpinboundchannel-threadpool endPointName threadPoolName
endPointName
The TCP end point name.
threadPoolName
The thread pool name.
Update the size of object cache instances. The size can be limited in number of lines, or in number of megabytes (MB). run update-objectcache-size jndi size sizeMB
jndi
The JNDI name of the object cache.

The JNDI value can be basecache (case insensitive) to update the basecache value.

size
The maximum size, in number of entries, of the object cache.
sizeMB
Optional: The maximum size, in megabytes (MB), of the object cache.
For example:
  • run update-objectcache-size dmap/PriceCache 30000

    If a cache instance with JNDI name dmap/PriceCache exists, limit the number of entries to 30000 with no limits on the size.

  • run update-objectcache-size dmap/PR_Cache 5000 400

    If a cache instance with JNDI name dmap/PR_Cache exists, limit the number of entries to 5000 and/or 400MB.

  • run update-objectcache-size basecache 3000 1000

    Update the basecache limits to 3000 entries and/or 1000MB.

Start or stop the Dynamic Cache Monitor application on deployment.
  • run start-cache-monitor
  • run stop-cache-monitor
Enable or disable the automatic startup of the Dynamic Cache Monitor application if the container is restarted.

Applications > Application Types > WebSphere enterprise applications > Dynamic Cache Monitor > Target specific application status

run enable-cache-monitor-auto-start value
value
A boolean value.
Accepted values are:
  • 1 or true, to enable the automatic startup of the Dynamic Cache Monitor application.
  • 0 or false, to disable the automatic startup of the Dynamic Cache Monitor application.
For example:
  • run enable-cache-monitor-auto-start true will enable the automatic startup of the Dynamic Cache Monitor application.
  • run enable-cache-monitor-auto-start false will disable the automatic startup of the Dynamic Cache Monitor application.
The set-cache-provider command includes two functions:
  • Generate a list of cache instances by their JNDI name and output it to a file.
    Note: The generated file is compatible with the run set-cache-provider cacheProvider filename command.
  • Set specified cache instances to a defined cache provider.

    For example, hcl-cache or dynacache.

  • run set-cache-provider print filename
print
Prints all JNDI names of cache instances.
filename
Specify a full path and file name for the generated file. If a full path is not specified the file is generated in the current directory.
  • run set-cache-provider cacheProvider all
  • HCL Commerce Version 9.1.2.0 or laterrun set-cache-provider cacheProvider jndiName
  • run set-cache-provider cacheProvider filename
cacheProvider
The cache provider name that you want to switch the specified cache instances to. The accepted values are hcl-cache or dynacache.
HCL Commerce Version 9.1.2.0 or laterjndiName
HCL Commerce Version 9.1.2.0 or laterSpecify the specific cache instance, specified by the jndiName, is to be switched to the specified provider.
all
Specify that all cache instances are to be switched to the specified provider.
filename
Use a filename that contains JNDI names to specify the cache instances that are to be switched to the specified provider.

You can use the set-cache-provider print command to generate a file in the accepted format.

For example:
  • set-cache-provider dynacache all will set all caches to use dynacache.
  • HCL Commerce Version 9.1.2.0 or laterset-cache-provider hcl-cache services/cache/WCFlexFlowDistributedMapCache will set the services/cache/WCFlexFlowDistributedMapCache cache to use hcl-cache.
  • set-cache-provider hcl-cache filename will set the caches specified by their JNDI names in the file filename to use hcl-cache.
HCL Commerce Version 9.1.11.0 or laterMerge cachespec.xml cache configuration files. run merge-cachespec-xml source_file target_file
source_file
The source cachespec.xml configuration file to be merged from.
target_file
The target cachespec.xml configuration file to be merged into.
Important: Ensure that you back up the target cachespec.xml configuration file before running this command. This file will be modified by this command.
Add or update custom datasource attributes

Resources > JDBC > Datasources > Custom properties

run update-datasource-attribute -j JDBCProvider -d Datasource -n AttrName -t AttrType -v AttrValue
JDBCProvider
Optional: The JDBC Provider name. If not provided, the default provider, WCDataSource_provider, is used.
Datasource
Optional: The datasource name. If not provided, the default datasource, WCDataSource, is used.
AttrName
The name of the datasource attribute to be added or updated.
AttrType
The type of the attribute. Accepted values are string or integer.
AttrValue
The value of the attribute.
For example, to update the isolation level of the datasource to Cursor Stability:
run update-datasource-attribute -n webSphereDefaultIsolationLevel -t integer -v 2
The attribute webSphereDefaultIsolationLevel will be added if it does not already exist, and is set to 2 (Cursor Stability). If the attribute is preexisting, it will be set to the new value of 2.
HCL Commerce Version 9.1.7.0 or laterAdd a custom integer attribute to an existing DB2 datasource. set-dataSource-integer-attribute jndi attributeName attributeValue
jndi
The JNDI name of the data source. The default value for the Transaction server is jdbc/wcdb.
attributeName
The name of the integer attribute.
attributeValue
The value of the attribute.
Update the settings of a work manager if the work manager exists. run update-work-manager-thread name minThreads maxThreads threadPriority
name
The WorkManager name.
minThreads
The minimum number of threads.
maxThreads
The Maximum number of threads.
threadPriority
The priority to assign to all threads in the thread pool.
Deploy an EAR to WebSphere Application Server. run install-ear transaction-server-ear-name
transaction-server-ear-name
Name of the EAR file on the Transaction server.
Install OIDC application to the application server run time. run install-oidc ear-name
ear-name
EAR name of OIDC application.

Change JVM property (EncryptionKeysInSystemProperty, CurrentEncryptedMerchantKey, CurrentEncryptedSessionKey).

run set-encryption-keys merchantKey sessionKey
merchantKey
Encrypted merchant key.
sessionKey
Encrypted session key.
  • run set-kafka-server KafkaServers TopicPrefix ZooKeeperServers
  • run set-kafka-server KafkaServers TopicPrefix ZooKeeperServers [ KafkaAuthenticationUserId KafkaAuthenticationPassword ]
KafkaServers
List of Kafka servers, separated by a comma.

Kafka IDs must follow the pattern hostname:port.

kafkaTopicPrefix
Kafka Topic Prefix.
listOfZooKeeper
List of ZooKeeper servers ( For example, zookeeperId1, zookeeperId2,.., zookeeperIdn) must be separated by commas.

ZooKeeper IDs must follow the pattern hostname:port.

KafkaAuthenticationUserId
(Optional) Kafka user
KafkaAuthenticationPassword
(Optional) Encrypted Kafka password
Note: The zookeeper servers are being used for script backward compatibility, hence this parameter should be ignored.

Change JVM property(wc.remote.kafka, wc.remote.kafka.topicPrefix, wc.remote.zookeeper, wc.store.remote.kafka, wc.store.remote.kafka.topicPrefix)

  • run set-kafka-server KafkaServers TopicPrefix ZooKeeperServers
  • HCL Commerce Version 9.1.10.0 or laterrun set-kafka-server KafkaServers TopicPrefix ZooKeeperServers [ KafkaAuthenticationUserId KafkaAuthenticationPassword ]
KafkaServers
List of Kafka servers, separated by a comma.

Kafka IDs must follow the pattern hostname:port.

kafkaTopicPrefix
Kafka Topic Prefix.
listOfZooKeeper
List of ZooKeeper servers ( For example, zookeeperId1, zookeeperId2,.., zookeeperIdn) must be separated by commas.

ZooKeeper IDs must follow the pattern hostname:port.

HCL Commerce Version 9.1.10.0 or laterKafkaAuthenticationUserId
HCL Commerce Version 9.1.10.0 or later(Optional) Kafka user
HCL Commerce Version 9.1.10.0 or laterKafkaAuthenticationPassword
HCL Commerce Version 9.1.10.0 or later(Optional) Encrypted Kafka password
HCL Commerce Version 9.1.10.0 or laterNote: The zookeeper servers are being used for script backward compatibility, hence this parameter should be ignored.
Change MQ connection pool information. run change-mqadapter-max-connection connectionNumber
connectionNumber
Maximum number of connections.
The default maximum connection number is 10.
Create JMS connection factory. run create-jms-connection-factory mqServerHost mqServerPort queueManager connectionNumber
mqServerHost
IBM MQ Server.
mqServerPort
IBM MQ Server port.
queueManager
IBM MQ queue manager.
connection Number
Maximum connection number.
The default maximum connection number is 10.

For example, run create-jms-connection-factory test.hcl.com 1414 FVT 15

IBM MQ server is test.hcl.com, port is 1414, queueManager is FVT.

Create JMS queues. create-jms-queues queueManager
queueManager
IBM MQ queue manager.

For example, run create-jms-queues FVT

Enable application activity sessions. run enable-activity-session timeout
timeout
The timeout value in seconds.
The default value is 300 seconds.
Update the datasource information in the wc-server.xml file. run update-wcserver-db dbType dbHost dbPort dbname dbauser dbapassword dbuser dbpassword nodeName
dbType
Database type. Set to db2.
dbHost
Database host name.
dbPort
Database port number.
dbname
Database name.
dbauser
Database admin user.
dbapassword
Database admin encrypted password.
dbuser
Database user.
dbpassword
Database encrypted password.
nodeName
(Optional) The node name of the remote database.
Set schedulerID. run add-generic-jvmarg -Dcom.ibm.commerce.scheduler.SchedulerHostName=${schedulerID}

Works with schedulerCloneID.

Set schedulerCloneID. run add-generic-jvmarg -Dcom.ibm.commerce.scheduler.SchedulerCloneId=${schedulerCloneID}

Works with schedulerID.

Set the total transaction lifetime timeout. run set-transaction-lifetime-timeout value
value
The maximum number of seconds that a transaction can take before timing out. By default, this value is set to 120.
HCL Commerce Version 9.1.6.0 or laterSet resource adaptor connection pool properties. run set-resource-adaptor-connection-pool-props uriName connectionTimeout maxConnections minConnections reapTime unusedTimeout agedTimeout purgePolicy
Where:
uriName
The name of the URI of the module. For example, Enablement-JCAEMailConnector.rar.
connectionTimeout
The number of seconds that the connection request waits before a timeout exception. The default value is 180.
maxConnections
The maximum number of connections in the pool. The default value is 10.
minConnections
The minimum number of connections in the pool. The default value is 1.
reapTime
The time interval, in seconds, to start the pool maintanance thread. The default value is 180.
unusedTimeout
The amount of time, in seconds, after which an unused connection is discarded. The default value is 1800.
agedTimeout
The amount of time, in seconds, before a connection is discarded. The default value is 0 (disabled).
purgePolicy
The policy that is used to purge connections when a connection error is detected. The default value is EntirePool.
Accepted values are:
  • EntirePool - the entire pool is reset.
  • FailingConnectionOnly - only the thread with an error is reset.
For WebSphere eXtreme Scale integration, create an extreme scale domain.
Tip: For more information about this integration, see Integrating HCL Commerce version 9 with WebSphere eXtreme Scale.
run create-XS-Domain hostname port
hostname
The host name of the WebSphere eXtreme Scale catalog server.
port
The listener port of the WebSphere eXtreme Scale catalog server.
For WebSphere eXtreme Scale integration, connect the baseCache instance to WebSphere eXtreme Scale cache provider.
Tip: For more information about this integration, see Integrating HCL Commerce version 9 with WebSphere eXtreme Scale.
run connect-basecache-wxs size gridName mapName
size
The new size of the default dynamic cache instance (baseCache).
gridName
(Optional) The name of the grid on the WebSphere eXtreme Scale server.
mapName
(Optional) The name of the map on the WebSphere eXtreme Scale server.
For WebSphere eXtreme Scale integration, connect the object cache instance to the WebSphere eXtreme Scale cache provider.
Tip: For more information about this integration, see Integrating HCL Commerce version 9 with WebSphere eXtreme Scale.
run connect-objectcache-wxs jndi size gridName mapName
jndi
The Java Naming and Directory Interface (JNDI) name of the object cache.
size
The new size of the object cache instance.
gridName
(Optional) The name of the grid on the WebSphere eXtreme Scale server.
mapName
(Optional) The name of the map on the WebSphere eXtreme Scale server.
HCL Commerce Version 9.1.10.0 or laterUpdate datasource server. update-wc-server-datasource dbType dbHost dbPort dbname dbauser dbapassword dbuser dbpassword
Where,
dbType
The database type.
For example db2, or oracle.
dbHost
The host name of the database server.
dbPort
The database server port.
dbname
The name of the database.
dbauser
Database admin user.
dbapassword
Database admin encrypted password.
dbuser
The database user name.
dbpassword
Database encrypted password.