Customizing EAR resources (resources-ext)

In legacy toolkits, base XML configurations and properties were modified directly in the local workspace. In the HCL Commerce+ toolkit, the workspace uses a lightweight delta approach. Manage customizations and new Enterprise Archive (EAR) level files using the resources-ext directory, which overlays files onto the server during the build process.

About this task

Use this task to customize existing EAR resources or add new EAR-level files to your runtime environment.

Important:

Exception for wc-server.xml: Do not place a customized wc-server.xml file inside the resources-ext directory. Doing so overwrites dynamically generated database and server properties during the build. To customize this file, edit src/projects/ts-ear/template/xml/wc-server.xml.template directly and rebuild the ts-ear module using:

./mvnw install -pl src/projects/ts-ear -P toolkit,build

Procedure

Determine the target server location.
Find the original file in the deployed Open Liberty Server location, or determine the path for your new custom directory.
- Target example for existing files: .../opt/ol/wlp/usr/servers/transactionServer/apps/ts.ear/xml/config/com.ibm.commerce.catalog/dataextract
- Target example for a new custom directory: ts.ear/xml/config/com.ibm.commerce.catalog-ext/
Replicate the directory structure in your local project.

In your IDE, navigate to src/projects/ts-ear/resources-ext/ and replicate the exact folder path as it appears relative to ts.ear/ on the server.
Add or copy your customization files into the local workspace.
- To modify an out-of-the-box file: Copy the file from the server directory into your matched local directory under resources-ext. Edit the local copy instead of modifying the server file directly.
- To add a new file: Create the new file directly inside the mapped folder within resources-ext.
Copy resources to the running server.
From the root of the project, execute the Maven copy resources command:
```
./mvnw resources:resources@copy-resources-to-server
```
Note: If you are running the command on Windows (and not using WSL2), append the runtime install directory parameter to the command:
```
-Druntime.install.directory=C:/Users/<user-name>/opt/ol
```
The local resource files are copied to the mapped path on the server.
Verify your changes on the server.

Inspect the target folder on the running server to verify that the modified or new files were successfully overlaid.

What to do next

Do not place a customized wc-server.xml file inside the resources-ext directory. Placing it in resources-ext overwrites dynamically generated database and server properties during the build process.

To customize the wc-server.xml file:

Make your edits directly to the template file: src/projects/ts-ear/template/xml/wc-server.xml.template
Rebuild the ts-ear module to generate and apply your configuration changes:
```
./mvnw install -pl src/projects/ts-ear -P toolkit,build
```
Note: If project dependencies have not been built recently, append -am to the command to build required dependent modules.