Understanding important folders and files

Learn about the source code folder structure to find the components that you need to customize, where to save your customizations, and the purpose of some files. These folders and files are important if you are customizing existing applications.

Order Hub code directory

The Order Hub source code is available in the following location:

The default location is devtoolkit_docker/orderhub-code.

After you have identified the location of the Order Hub source code in your environment, this location is denoted by <order_hub_code_directory>.

Understanding the different modules

The <order_hub_code_directory>/<module-name> folders include code for different menu items and the pages within the menu.

buc-app-configurations: Includes code for the Configurations menu. The Configuration menu is available if you are subscribed to Sterling Intelligent Promising.
buc-app-exception: Includes code for the Exceptions menu.
buc-app-fulfillment: Includes code for the Fulfillment menu.
buc-app-inventory: Includes code for the Inventory menu.
buc-app-node: Includes code for the Nodes and capacity menu.
buc-app-order: Includes code for the Orders and Shipments menus.
buc-app-settings: Includes code for some items in the Settings menu (Display settings, User roles, Distribution groups, Customizations).
buc-app-workspace: Includes code for Home, Workspaces, Alerts, and Alert rules menus.

Understanding the 'packages' folder

The <order_hub_code_directory>/<module-name>/packages directory holds all the code that renders the pages and actions for a particular module.

The packages directory contains the following important child folders:

<route-name>

The routes that are included in the module. For example, <order_hub_code_directory>/buc-app-order/packages/create-order route correlates to the Create order page in the user interface.

<route-name>/node_modules

Includes external dependencies for the route. Do not modify this folder.

<route-name>/src

Includes original code from IBM. Do not modify this folder. This folder is overwritten with new installations or updates from IBM.

<route-name>/src-custom

Add your custom code in this folder. Copy the folder structure and files that you need to modify from the src folder into this src-custom folder.

<route-name>/src-merged

Includes compiled code that is running within the application. Do not modify this folder. The compile process merges the src and src-custom folders into src-merged.

<route-name>/<module_short_name>-shared/assets

Includes assets that are shared across all routes in the module, such as:

Translation files (for example, en.json for English strings and fr.json for French strings)
Styling files (for example, main.scss)
Images
JSON files for customization by configuration (for example, buc-field-details.json, buc-table-config.json)

If you want to add custom strings or update existing components by using the customization by configuration technique, you need to copy this shared/assets folder into the src-custom folder. For more information, see Understanding and populating the 'src-custom' folder.

Understanding the 'src' folder

The <order_hub_code_directory>/<module-name>/packages/<route-name>/src directory holds all the original code from IBM. Do not modify this folder. This folder is overwritten with new installations or updates. Instead, copy the folder structure and the files that you need to modify. Then, paste into the src-custom folder. The src directory contains the following important child folders and files that you might need to copy.

app

Includes page components (.html, .ts), modules, and service definitions.

environments

Includes environment configurations that determine which assets to use in a specific environment. Do not modify this folder. Instead, copy this folder into src-custom and then modify as needed.

app/features/*.module.ts

The page application routing module definition for all the routes in this application. By default, IBM defines one route to allow for granular customization without taking ownership of all other routes within the parent module. However, you can introduce custom routes as needed in your src-custom/app/features/ext-NNNmodule.ts file.

Within your custom module.ts files, add injection points to define custom services within the providers object. Order Hub provides two Injection Tokens, 'CUSTOM_ACTIONS' and 'CUSTOM_FEATURE_ACTIONS' to override existing actions or to provide custom actions.

The value for the injection token is an array where each element is an object containing two properties:

name - The name of the action.
action - The service that handles or implements the action.

You need to define the Injection point in the ext-NNN.module.ts file to ensure that the service that is injected in to the action has all bundles loaded by the feature module.

Understanding and populating the 'src-custom' folder

The <order_hub_code_directory>/<module-name>/packages/<route-name>/src-custom folder is initially empty. You need to populate the folder with custom code. To customize existing code, copy the necessary folders and files into src-custom, and then edit as needed. In most cases, you need to copy the following files and folders to the src-custom folder:

Features in Order Hub are organized within the src/app/features directory. Copy the features folder that you want to customize and paste into the src-custom folder. Edit as needed. For example, if you want to customize the search feature from the inventory-search-results route, then you need to copy the corresponding search folder from src to src-custom. Ensure that you follow the same folder hierarchy as in src.
Predefined assets that are shared between routes are organized in the <module_short_name>-shared/assets directory. Copy the <module_short_name>-shared/assets/<module-name> folder into the src-custom/assets folder so that your customizations can access the predefined assets (such as label text). For example, if you are customizing the buc-app-inventory module, copy the inventory-shared/assets/buc-app-inventory folder into src-custom/assets.
If you need to edit or add assets, create a src-custom/assets/custom folder. You can edit or add the necessary custom translation files, scss files, and JSON configuration files as needed.
When you deploy customizations, your customization code works in parallel with Order Hub code. But, you also want to ensure that future updates by IBM do not conflict and override your customizations. Therefore, copy the src/environments folder into the src-custom folder. In each src-custom/environments/*.ts file, add the following code to indicate to Order Hub that you customized this route. When you set to true, you do not automatically get updates for this route, which ensures that your customizations are not overwritten. To get new updates, you need to re-sync your customization changes to the latest code release.
```
environment.customization = true;
```
Note: If you are solely using the customization by configuration technique where you are only updating the JSON configuration files (buc-table-config.json, buc-field-details.json, search_fields.json, then you do not need to change the environment files.

Understanding the 'src-merged' folder

The <order_hub_code_directory>/<module-name>/packages/<route-name>/src-merged folder is generated by merging the code from the src and src-custom folders during code compilation. A compilation occurs every time that you save code changes on your machine. Do not modify code in the src-merged folder. Instead, update the src-custom folder as needed.

Understanding and modifying the angular.json file

An angular.json file exists at the root of each module. Each route in the file includes a merged > assets array that defines which assets to use when running the application. If you have custom assets in src-custom/assets/custom, then for each route that you are customizing, update the route to use your custom merged assets instead of the shared assets:

Within the angular.json file, find the projects > [route-name] > architect > build > configurations > merged > assets array.

Replace the default contents with the following code to point to the merged assets. Replace <route-name> and <module-name> as needed.

            "assets": [
              {
                "glob": "**",
                "input": "packages/<route-name>/src-merged/assets",
                "output": "assets"
              },
              {
                "glob": "*.json",
                "input": "packages/<route-name>/src-merged/assets/<module-name>",
                "output": "assets/<route-name>"
              },
              {
                "glob": "**",
                "input": "node_modules/@buc/svc-angular/assets",
                "output": "assets"
              },
              {
                "glob": "**",
                "input": "node_modules/@buc/common-components/assets",
                "output": "assets"
              }
            ],

Also replace the contents in the projects > [route-name] > architect > build > configurations > merged-prod > assets array.