Deploying customizations for existing applications

Deploy customizations that you made to existing applications so that other users can use your customizations. This procedure explains how to deploy customizations from your local workstation.

To deploy a new application, see Deploying new applications.

Note: This topic is applicable to the SaaS version of Order Hub only.

Procedure

Retrieve the Customization folder, Customization client ID, Customization auth key for each of the tenants where you want to deploy the customizations.

You might need to contact an administrator to get the Customization auth key if the tenants are already configured for customization. For more information, see Enabling the customization menu for a tenant.
Open the features.json in the module's root directory.
For example, devtoolkit_docker/orderhub-code/buc-app-order/features.json. If the file does not exist, then create the file. The content that you need to add to the features.json depends on the type of customization that you want to deploy.
- If you are deploying a customization for an existing module without any new routes, add an empty array to the features.json file.
```
[]
```
- If you are deploying a new route, then retrieve the Feature JSON value from Order Hub.
  1. Log in to Order Hub.
  2. Switch to the customization tenant where you tested your customizations.
  3. Go to Settings > Customization.
  4. Select the custom item that launches your route.
  5. If you want to deploy customizations to the customization tenant where you tested your customizations, ensure that you select Hosted by IBM and you clear Local development environment. Otherwise, the tenant will continue to connect to your local server.
  6. In the Relative URL field, add the relative path to your route /<module-name>/<route-name>. Start with a forward slash (/). You do not need to include a trailing slash.
    For example, /buc-app-order/create-order.
  7. Save all changes.
  8. Copy the JSON from the Feature json field in the UI. Paste or merge the JSON as an array element in the features.json file that is in the module's root directory. The JSON from the UI resembles the following sample.
```
{
    "featureId": "custom-[Id]", // must be unique
    "state": "ACTIVE",
    "sequence": 0,
    "title": "[Title to display for the custom application]",
    "iconName": "website-20",
    "link": "/[module-name]/[path to new route]",
    "path": "/[module-name]/[path to new route]",
    "hidden": true,
    "allowedRoles": [   //the roles that can access this customization
      "Fulfillment Manager",
      "Tenant Administrator"
    ],
    "description": [
      {
        "locale": "en_US",
        "language": "en",
        "title": "Title to display for the custom feature"
      }
    ],
    "type": "IFRAME"
  }
```
    Depending on the contents in the features.json, you might need to surround the code with square brackets [] to add as an array element.
Update the package-customization.json file.
1. For every module that is customized, open the devtoolkit_docker/orderhub-code/<module-name>/package-customization.json file for editing.
2. In the routes object, add every route in the module that is customized. Keep the customizationContextRoot object empty.
  Each key in the routes object identifies the customized route package. The value is an object with a single key called type. Ensure that the type property is always set to "code".
  For example,
```
{
    "repositoryName": "buc-app-order",
    "customizationContextRoot": "",
    "routes": {
        "create-order": {
            "type": "code"
        }
    }
}
```

For each environment where you want to deploy customizations, add a build target in the <module-name>/package.json file, and then in the <module-name>/packages/<route-name>/package.json file for each route that was customized.

Open <module-name>/package.json file.
For example, buc-app-order/package.json.
Make a copy of the build-merged line for each target environment.
For example, assume that you want to deploy to four environments; dev1, qa3, preprod, and prod. Paste the line four times.

Replace build-merged with build-merged-<environment> in each copied line.

For example,

"build-merged": "lerna run build-merged --stream",
"build-merged-dev1": "lerna run build-merged-dev1 --stream",
"build-merged-qa3": "lerna run build-merged-qa3 --stream",
"build-merged-preprod": "lerna run build-merged-preprod --stream",
"build-merged-prod": "lerna run build-merged-prod --stream"

For each route that is customized, open the <module-name>/packages/<route-name>/package.json file.
For example, buc-app-order/packages/create-order/package.json.
Make a copy of the build-merged line for each target environment.

Replace build-merged with build-merged-<environment> in each copied line and add --deploy-url=<customization folder>/<module-name>/<route-name>/.

The value for <customization folder> is the value that you retrieved from step 1. Each target environment has a different customization folder value.

For example,

For the create-order route (in buc-app-order/packages/create-order/package.json):

"build-merged": "ng build create-order --configuration=merged-prod",
"build-merged-dev1": "ng build create-order --configuration=merged-prod --deploy-url=/buc-app-customization/T3R4fagafd45aadfaffasf/buc-app-order/create-order/",
"build-merged-qa3": "ng build create-order --configuration=merged-prod --deploy-url=/buc-app-customization/dbU2K1u4seqrRKwBZTyMp1lUJwqQkJ5A/buc-app-order/create-order/",
"build-merged-preprod": "ng build create-order --configuration=merged-prod --deploy-url=/buc-app-customization/zdD4uxaf8GRTbzMSg8zU2K/buc-app-order/create-order/",
"build-merged-prod": "ng build create-order --configuration=merged-prod --deploy-url=/buc-app-customization/balohTK3ang5GmXsRwOSeSidbQOKEw6N/buc-app-order/create-order/",

For the order-details route: (in buc-app-order/packages/order-details/package.json):

 "build-merged": "ng build order-details --configuration=merged-prod",
"build-merged-dev1": "ng build order-details --configuration=merged-prod --deploy-url=/buc-app-customization/T3R4fagafd45aadfaffasf/buc-app-order/order-details/",
"build-merged-qa3": "ng build order-details --configuration=merged-prod --deploy-url=/buc-app-customization/dbU2K1u4seqrRKwBZTyMp1lUJwqQkJ5A/buc-app-order/order-details/",
"build-merged-preprod": "ng build order-details --configuration=merged-prod --deploy-url=/buc-app-customization/zdD4uxaf8GRTbzMSg8zU2K/buc-app-order/order-details/",
"build-merged-prod": "ng build order-details --configuration=merged-prod --deploy-url=/buc-app-customization/balohTK3ang5GmXsRwOSeSidbQOKEw6N/buc-app-order/order-details/",

Build the customization package for each target environment by passing the corresponding build-target and customization-context-root parameters in the following yarn call.

yarn package-customization --build-target=build-merged-<environment> --customization-context-root=<customization_folder>

Note: You cannot use Git Bash if you are running this command in Windows.

For example,

To build for the dev1 environment:

yarn package-customization --build-target=build-merged-dev1 --customization-context-root=/buc-app-customization/T3R4fagafd45aadfaffasf

To build for the qa3 environment:

yarn package-customization --build-target=build-merged-qa3 --customization-context-root=/buc-app-customization/dbU2K1u4seqrRKwBZTyMp1lUJwqQkJ5A

Run the following command to publish the customizations to your target environment.
The target environment is determined by the client-id and client-secret. Each environment has a unique client id-secret pair.
```
yarn orderhub-cli publish-customization --client-id=<clientId> --client-secret=<clientSecret> --package-name=<module-name>
```
Required Parameters:
- --client-id - The customization client ID. For more information about how to get the ID and secret, see Enabling the customization menu for a tenant.
- --client-secret - The customization client secret.
- --package-name - The module folder under the build directory that contains the files to upload. This value corresponds to the module name, such as buc-app-order.
Optional Parameters:
- --orderhub-hostname - The hostname for the Order Hub API server. Defaults to app.omsbusinessusercontrols.ibm.com.
- --proxy-host - The proxy hostname and port in case the build machine does not have access to orderhub-hostname directly.
- --package-only - Indicates whether to build the customization asset zip only. Defaults to false
- --publish-only - Indicates whether to upload a prebuilt customization package. Defaults to false. If set to true, you must also specify the package to publish by using the --package-name parameter. For the --package-name, specify the path to <build-dir>/<package-name>.zip. For example,
```
--publish-only=true --package-name=./dist/buc-app-order.zip
```
- --build-dir - The directory that contains the compiled customization asset. Defaults to dist