Getting started with customizing Order Hub

Before you can customize Order Hub, you must get the Order Hub source code and decide whether to create new applications or customize existing applications to suit your business needs. After customizing Order Hub, test your customizations to ensure that they are working as intended in your environment.

Procedure

Get the Order Hub source code:

For containers: Install Docker.
Docker is used to install the necessary components and dependencies to set up the Order Hub container only. You do not develop Order Hub customizations within the container. You develop on your local workstation.
Install a Node.js version that is compatible to Angular 15. For more information, see the Angular pageVersion compatibility. If multiple node versions are required, consider using nvm (for Mac or Linux) or nvm-windows (for Windows).
Install Yarn.
Install Angular CLI globally by running the following command in a terminal.
```
npm install -g @angular/cli@15
```
For containers: Download and set up a developer toolkit environment on your local workstation for optimal performance. It is recommended that you do not set up the toolkit inside another Docker container or in a virtual machine. The following steps quickly summarize how to set up the toolkit for customizing Order Hub. For a complete guide on how to set up a developer toolkit, see Setting up a developer toolkit environment.
1. Download the developer toolkit to your local workstation where you want to develop customizations for Order Hub.
  
  Tip: For Microsoft Windows, save the devtoolkit_docker.tar file to the drive's root directory. For example C:/devtoolkit_docker.tar. After installation, files are extracted to your local workstation and long file paths mights cause issues.
2. Open a terminal on your local workstation.
3. Browse to the location where you downloaded the tar file and run the following command.
```
tar -xf devtoolkit_docker.tar && chmod +x devtoolkit_docker/compose/*.sh
```
  As a result, a devtoolkit_docker folder is created on your local workstation.
4. Go to the devtoolkit_docker/compose directory.
5. Create a copy of the devtoolkit_docker/compose/om-compose.properties.sample file, and name it om-compose.properties.
  For example,
```
cp om-compose.properties.sample om-compose.properties
```
6. Set the appropriate value for the AP_HOST property.
  For more information, see Overriding the default Docker Compose properties.
7. Start Docker.
  If you installed Docker Desktop, start Docker Desktop. If you installed Docker Engine, start Docker through the command line.
```
sudo service docker start
```
8. Run the following command to set up the developer toolkit.
  - If you only want to set up Order Hub in the developer toolkit, run the following command.
```
./om-compose.sh setup-orderhub
```
  - If you want to set up the full developer toolkit to also include other Sterling Order Management-related containers (like Sterling Business Center), run the following command.
    - To set up a new toolkit:
      ./om-compose.sh setup
    - To upgrade an existing toolkit:
      ./om-compose.sh setup-upg
9. Run the following command to extract the source code to your local workstation. Use the source code to customize Order Hub.
```
./om-compose.sh extract-orderhub-code <version>
```
  <version>: Valid values are oms or omoc.
  - oms: For the On Premises version of Order Hub
  - omoc: For the SaaS version of Order Hub
  The source code is available on your local workstation at devtoolkit_docker/orderhub-code.
  Note: If you used Windows Subsystem for Linux version 2 (WSL 2) to install the toolkit, the files are available on your local workstation as well. For example, if you ran the commands in WSL at /mnt/c/devtoolkit_docker then the files are also available at C:/devtoolkit_docker. Complete all customizations on your local workstation (C:/devtoolkit_docker).
For traditional: Get the source code.
The source code is in <runtime>/repository/orderhub/code/orderhub/on-prem-source.tar.

Make a directory where you want to work on your development, then extract the code to that directory.
For example:
1. Make the directory:
```
mkdir -p orderhub-code/lib
```
2. Extract the on-prem-source.tar file:
```
tar -xf <runtime>/repository/orderhub/code/orderhub/on-prem-source.tar --directory=orderhub-code
```
3. Extract the lib.tar file:
```
tar -xf <runtime>/repository/orderhub/code/orderhub/lib.tar --directory=orderhub-code/lib
```

Customize Order Hub to suit your business needs:

Decide whether you want to create an application that you can access through a new menu item inside Order Hub, or customize existing applications that are provided by IBM.
For more information, see:
- Creating new applications
- Customizing existing applications
Optional: You can refer to the storybook to help you build UI components.
Access the storybook at the following URL.
- For containers:
```
https://localhost:8443
```
  Note: If you changed the OH_EXT_HTTPS_PORT in the om-compose.properties file, then update the port from 8443 to the port that you specified.
  The orderhub extension Docker container must be running to access the storybook. If the container is not running, go to devtoolkit_docker/compose and run the following command.
```
./om-compose.sh start orderhubext
```
- For traditional:
```
https://localhost:port/storybook
```
  Where port is the port number that is configured in the web server configuration.

Try it out:

Test your customizations to ensure that they are working as intended in your environment.
- If you created a new application or new route, use the Settings > Customization menu to add the application to the customization tenant for testing. For more information, see Testing new applications or routes in.
- If you customized an existing application, you can test the changes by configuring Order Hub to connect to your toolkit environment. For more information, see Testing existing module customizations in Order Hub.