Creating new applications

Use one of the IBM-provided Angular schematics to generate a brand new application and then access the application within Order Hub from a new menu item.

Order Hub menu with a new menu item that says "Custom page" which can point to your new application
When you create an application with the schematics, the resulting application is automatically configured to include the libraries that are used by Order Hub to communicate with various services, such as:
  • The Sterling Order Management System system backend
  • Sterling Intelligent Promising Inventory Visibility tenants
  • Other micro service tenants
  • Carbon UI libraries to design pages to have the same look and feel as existing pages in Order Hub.
You can use the scripts to generate one of the following Angular repositories:
  1. An Angular monorepo, similar to how all the Order Hub code is orchestrated.
  2. A basic Angular repository.

Creating an Order Hub monorepo

This schematic creates a new monorepo by using Lerna and Single-Spa.
  1. Ensure that you have extracted the Order Hub code. For more information, see Getting started with customizing Order Hub.
  2. Open a terminal and go to the Order Hub code directory.
    • The default location is devtoolkit_docker/orderhub-code.
  3. Run the following command to set strict-ssl to false.
    npm config set "strict-ssl" false
  4. Run the following command to reinstall the latest version of @buc/schematics to access the IBM-provided schematics.
    npm uninstall -g @buc/schematics
npm install -g ./lib/buc/schematics/schematics-v3latest.tgz
  5. Create a folder for your application. The name of the folder will be the module name. In the folder, create an app-config.json file that describes the routes in the module. The value for "name" must be the module name. For example,
    {
  "name": "custom-monorepo",
  "devServerConfig": {
      "port": 9300,
      "contextRoot": "/custom-monorepo"
  },
  "prodServerConfig": {
      "hostName": "static.omsbusinessusercontrols.ibm.com"
  },
  "routes": {
      "custom-page1": {
          "devServerConfig": {
              "port": 9301,
              "contextRoot": "/custom-page1"
          }
      },
      "custom-page2": {
          "devServerConfig": {
              "port": 9302,
              "contextRoot": "/custom-page2"
          }
      }
  }
}
  6. In the terminal, go to the folder that you created.
  7. Run the following command.
    ng new --collection=@buc/schematics \
--app-config-json=<app-config.json-file-name> \
--module-short-name=<short-name-for-the-module> \
--prefix=<selector-prefix>
    The following options are supported by the schematic.
    • --skip-git: Do not initialize a git repository. Default false.
    • --commit: Initial git repository commit information. Default true.
    • --app-config-json: This option is required. Use the app-config.json file that you created in step 5.
    • --module-short-name: The short name for the module. If the module name has dashes, then the short name must be the text after the last dash. For example, if the module name is buc-app-settings, the module short name must be settings.
    • --prefix: The HTML selector to use for generated components. Default: buc
    • --shared-library-name: The name of the shared library. The default name is <module-short-name>-shared. The package name is @<prefix>/<module-short-name>-shared.
    • --generate-root-config: Indicates whether to generate a root-config router project. Default true.
    • --skip-install: Indicates whether to install packages. Default false.
    For example:
    ng new --collection=@buc/schematics  --app-config-json=app-config.json
      --module-short-name=monorepo  --prefix=monorepo
    After the command completes, a success message appears: "Packages installed successfully."
    Note: If you encounter an error similar to the follow message, then you can safely ignore the error. These errors do not affect the icons that are used by Order Hub.
    Error: Failed to compile entry-point @carbon/icons-angular/
  8. Start the server.
    yarn start-app
    Note: You see the following message.
    "** Angular Live Development Server is listening on bucgenerichost:<port>, 
open your browser on https://localhost:<port>/<module>/<route> **"
    You can ignore this message.
    Note: If you encounter an error similar to the following message, increase the heap size before you start the new application.
    Error command failed with exist code 134.
lerna ERR! yarn run start .... exited 134
    Run the following command and then start the new application.
    • Windows CMD prompt: 
      SET NODE_OPTIONS=--max_old_space_size=8048
    • Bash/Git Bash: 
      export NODE_OPTIONS=--max_old_space_size=8048
    • Powershell: 
      $Env:NODE_OPTIONS=--max_old_space_size=8048
    If you need to stop the server, stop the server job and run the yarn stop-app command to verify that everything is stopped properly.
  9. After you develop your application, configure Order Hub to connect to your server and load your new page within the user interface. For more information, see Testing new applications or routes in Order Hub
  10. If you want to test your customizations with a different OMS server than the server configured in your Order Hub tenant, update the <module-name>/packages/<route-name>/src/environments/environment.ts file by adding the following information:
    
import { BucSvcAngularStaticAppInfoFacadeUtil } from '@buc/svc-angular';

// set url to the OMS app server
// example url:  https://mydomain.mycompany.com:9443/smcfs
BucSvcAngularStaticAppInfoFacadeUtil.setLocalDevModeCustomizationTeamOMSUrl('https://<host>:<port>/smcfs');
    Where host and port are the values of the OMS server's hostname and port number that you want to test.

Creating an Order Hub basic Angular repo

  1. Ensure that you have extracted the Order Hub code. For more information, see Getting started with customizing Order Hub.
  2. Open a terminal and go to the Order Hub code directory.
    • The default location is devtoolkit_docker/orderhub-code.
  3. Run the following command to set strict-ssl to false.
    npm config set "strict-ssl" false
  4. Run the following command to reinstall the latest version of @buc/schematics to access the IBM-provided schematics.
    npm uninstall -g @buc/schematics
npm install -g ./lib/buc/schematics/schematics-v3latest.tgz
  5. Create a folder for your application. The name of the folder will be the module name. In the folder, run the following command. The value for --module-name must be the module name.
    ng new --collection=@buc/schematics \
--module-name=<name-of-the-module> \
--module-short-name=<the-short-name-for-the-module> \
--prefix=<selector-prefix>
    The following options are supported by the schematic.
    • --skip-git: Do not initialize a git repository. Default false.
    • --commit: Initial git repository commit information. Default true.
    • --module-name: Required. The name of the module. For example, buc-app-settings.
    • --module-short-name: The short name for the module. If the module name has dashes, then the short name must be the text after the last dash. For example, if the module name is buc-app-settings, the module short name must be settings.
    • --prefix: The HTML selector to use for generated components. Default: buc
    For example:
    ng new --collection=@buc/schematics  --module-name=custom-angularrepo
      --module-short-name=angularrepo  --prefix=angularrepo
    Note: If you encounter an error similar to the follow message, then you can safely ignore the error. These errors do not affect the icons that are used by Order Hub.
    Error: Failed to compile entry-point @carbon/icons-angular/
  6. Start the server.
    yarn start --host=bucgenerichost
    Note:
    • You will see a message:
      "** Angular Live Development Server is listening on bucgenerichost:<port>, 
open your browser on https://bucgenerichost:<port>/<module>/<route> **"
      You can ignore this message. You must connect your Order Hub tenant to your local workstation to view your customizations. For more information, see Testing existing module customizations in Order Hub.
  7. Update the src/app/app.component.html file and add some text to display in your application. For example, to add Hello, World!, use the following code:
    
<div class="app-root-custom-angularrepo">
	<div class="app-region-body">
		<div class="app-body-content" *ngIf="isBucTenantChangeSuccess || isBucJwtRefreshSuccess">
			<router-outlet></router-outlet>
		</div>
		<div *ngIf="isInitialState" class="app-loading">
			<div ibmCol>
				<buc-loading [isActive]="isInitialState"></buc-loading>
			</div>
		</div>

Hello World!

	</div>
</div>
  8. After you develop your application, configure Order Hub to connect to your server and load your new page within the user interface. For more information, see Testing new applications or routes in Order Hub
  9. If you want to test your customizations with a different OMS server than the server configured in your Order Hub tenant, update the <module-name>/src/environments/environment.ts file by adding the following information:
    
import { BucSvcAngularStaticAppInfoFacadeUtil } from '@buc/svc-angular';

// set url to the OMS app server
// example url:  https://mydomain.mycompany.com:9443/smcfs
BucSvcAngularStaticAppInfoFacadeUtil.setLocalDevModeCustomizationTeamOMSUrl('https://<host>:<port>/smcfs');
    Where host and port are the values of the OMS server's hostname and port number that you want to test.