Preparing to deploy customizations for existing applications

Before you can deploy customizations that you made to existing applications (like devtoolkit_docker/orderhub-code/buc-app-order), you need to indicate which customizations to deploy. For example, you can be working on two new routes but you might want to deploy only one.

For deploying a new application, see Preparing to deploy new applications.

Procedure

  1. 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.

  2. 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.
  3. 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"
        }
    }
}
  4. 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.
    1. Open <module-name>/package.json file.
      For example, buc-app-order/package.json.
    2. 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.
    3. 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"
    4. 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.
    5. Make a copy of the build-merged line for each target environment.
    6. 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/",
  5. If you use a CI/CD pipeline to deploy customizations, check in all customization changes to your repository.

What to do next

Deploy customizations.