Customizing Order Hub

You can customize and configure Order Hub to suit your business needs. For example, customize an existing page to show more data from the OMS API, or add your own pages to show custom data directly within Order Hub.

Note: Ensure that the administrator or developer that is customizing Order Hub has the Tenant Administrator role. You need the Tenant Administrator role to set up, configure, and test customizations in Order Hub. For more information about roles, see Adding users.

Understanding your customization options

You can customize and configure Order Hub in two ways. There are benefits to each method, so your choice will depend on your customization requirements and how you want to handle and process updates.

Create new applications and pages
Modify existing Order Hub applications and pages

Create new applications and pages: With this method, you add functionality by designing and coding a new, separate, custom application or page. When you create a brand new application or page, your code is isolated from IBM code and does not affect any of the modules or pages that are provided by IBM. Therefore, when monthly feature updates come out from IBM, the updates will not affect your customizations.

Modify existing Order Hub applications and pages: With this method, you add functionality by customizing existing applications and pages that are provided by IBM. There are different approaches to this method. Depending on the approach that you take, you may either write new code or, for simple customizations, you may simply make some configuration changes. In either case, you have flexibility in how updates are processed and rolled out and what they affect. Which approach you use will depend on your customization requirements and how you want to maintain and update your code. For more information, see Customizing existing applications.

Customization by creating new applications

When customizing Order Hub by adding brand new applications and pages, you will be in control and 'own' your code. To get started with this type of customization, follow the Order Hub development environment setup instructions with the option of generating a new code module repository. For more information, see Creating new applications.

Customization by modifying existing applications

When customizing Order Hub by modifying applications and pages, there are different levels of flexibility and control over the code and different ways of handling updates depending on the approach that you take. There are two approaches that you can take:

Customization by configuration
Customization by code

The customization by configuration approach

With the customization by configuration approach, you customize existing pages without writing code. There are certain pages/patterns in Order Hub that allow for simple customizations by completing configuration changes defined through JSON files. The patterns that support this capability are the search forms, tables, and field attributes that have the settings icon (). See the customization by configuration approach in action by reviewing the following tutorials:

For more information about customization by configuration, see Customizable elements by configuration.

The customization by code approach

With the customization by code approach, you customize existing pages by writing code in one of two ways:

Differential customization
Customization by overrides

Differential customizations: With differential customization, you keep your customization code separate from IBM code. When IBM releases updates to a page that you have customized, your updates are preserved. No code merge is require; simply recompile with the monthly DTK code. With differential customization, you can:

Add custom pages.
When you add new pages to the navigation, it acts as an iFrame inside of the common shell. For more information, see Creating new applications.
Add content to existing pages by using extension points.
Every component that makes up a page contains 2 extension points (top and bottom) for inserting custom code into any existing page. Fixes and new capability introduced by IBM are easily picked up due to clean code separation. For more information, see Adding content to existing pages by using extension points.
Add custom tabs and page actions.
Add custom tabs and page actions in the ordering of your choice. For more information, see Adding custom tabs to existing pages and Adding custom actions to existing pages.

See the differential customization approach in action by reviewing the Tutorial: Customizing the Schedule order action tutorial.

Customization by overrides: With customization by overrides, you can perform any customization on an existing page in Order Hub with complete flexibility. However, after modifying the code, you take ownership of that route or page and all the corresponding companion code assets that come with that page. Therefore, when IBM releases new updates, you will not automatically get updates for that page. To get new updates, you will need to resynchronize your customization changes to the latest code release. See the customization by overrides approach in action by reviewing the following tutorials:

Tip: Check if the desired customization is an existing pattern in Order Hub, then find the component in the Order Hub source code and replicate as needed.

Customization approaches quick comparison

When deciding which approach to take for your customizations, consider the following coding and update/code merging requirements.

Table 1. Customization approach quick comparison
Approach	Coding required?	For IBM fix updates: code merge required?
Customization by configuration	No	No
Customization by code	Yes	Yes and no, depending on which approach you take For Differential customization: No - you recompile with the monthly DTK code. For Customization by overrides: Yes - you need to manually resynchronize your customization changes to the latest code release.

Development environment best practices

Regardless of which customization option that you select, consider these development environment best practices.

Dedicate two environments to your customization efforts. When you customize your software, you should plan to dedicate one environment for developing customizations and another environment for deploying customizations. Configurations from the custom menu will take precedence over deployment. By dedicating two environments, you ensure that if you make changes to the customization UI, but deploy a different version, the UI version will take precedence over the deployed changes. If you have a business need to use only one environment and make changes to the UI, you can work around this issue by deleting the menu to synchronize with the deployed version.
Always use the latest DTK download from the Self Service tool to extract the Order Hub source code for your customization efforts. Since the Order Hub UI is in a multi-tenant environment that is automatically updated on a monthly basis by IBM with fixes and features, the matching Order Hub UI source code will always be available as part of the latest DTK. If you download the DTK from the environment link instead, you might get an older version of the Order Hub source code which could be missing the latest fixes and features.

References

Order Hub is built using the Angular framework. For more information, see https://angular.io. We support Angular versions v13 and v15. If you have customizations on Angular v13, they will continue to work with no changes. If you have customizations on Angular v11, you will need to migrate them over to Angular v15.
Order Hub only supports Carbon components version 10. For more information, see Carbon Components Angular.
Get started with quickly prototyping UI fragments for your Order Hub pages by using the IBM Carbon UI Builder. For more information, see https://builder.carbondesignsystem.com.
View Order Hub's custom components by accessing the Storybook. For more information, see Step 8 after installing the toolkit.