Creating new applications

Edit online

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 backend
  • Sterling 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-v2latest.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 or --appConfigJson: Required. The app-config.json file that you created previously.
    • --moduleShortName or --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 is buc-app-settings, the module short name must be settings.
    • --prefix: The HTML selector to use for generated components. Default: buc
    • --sharedLibraryName: The name of the shared library. The default name is -shared. The package name is @/-shared.
    • --generateRootConfig: 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. Create or edit the overrides.json file in the root location of the module folder to include the routes that you are adding. For example,
    {
  "routes": {
    "custom-page1": {
      "useProd": false
    },
    "custom-page2": {
      "useProd": false
    }
  },
  "devServerConfig": {
    "hostName": "bucgenerichost"
  }
}
    • useProd: Determines whether you want the route to be served from production (true) or from your local development server (false).
      • If you are customizing the route, set to false so that the route is served from your local server.
      • If you are not customizing the route and the route was previously deployed to your tenant, set to prod so that the route is served from your Order Hub tenant.
    • hostName: Always set to bucgenerichost.
  9. Start the server.
    yarn start-app
    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.
    • If you encounter an error similar to the following message then you need to increase the heap size before starting the application.
      Error command failed with exist code 134.
lerna ERR! yarn run start .... exited 134
      Run the following command and then start the 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, run the following command after you terminate the server job to ensure that everything is stopped properly:
      yarn stop-app
  10. 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
  11. 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-v2latest.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.
    • --moduleName or --module-name: Required. The name of the module. For example, buc-app-settings.
    • --moduleShortName or --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 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.