Adding custom panels or sections to the Catalog service details page

How you configure options for a service offering can determine how they are appear in the Catalog service details page of the My Cloud Services console. A panel can appear in the generic section (at the top-level of the service offering) or within a server group’s panel. The various placements are discussed in Determining-how-requestable-offerings-appear-in-My-Cloud-Services-console.

By configuring a json file, you can further customize the Catalog service details page so that the page contains a separate panel (under the generic section at the top or at the bottom of the other panels) or a section within a server group’s panel. The customized panel or section can contain custom fields or other content. For example, you might want a panel that focuses on a business justification. The panel might include fields like Proposed Use and Backup Plan. (This information would not make sense in a server group’s panel.)

This topic includes:

• • Configuration files required for customizing
  • The overall process
  • Using sample files
  • To add a custom panel or section
  • To pass data back to BMC Atrium Orchestrator or the HTTP server

Configuration files required for customizing

The customization process involves several files that you can find in the custom directory. You can find the location of the custom directory in one of the following files:

• config.properties (if the My Cloud Services console UI is installed as a standalone) – The location of the custom directory is set in the com.bmc.cloud.ui.custom.resource.dir property. By default, the config.properties file is in the /opt/bmc/CloudPortalWebApplication/tomcat/webapps/clmui/WEB-INF/classes or C:\Program Files\BMC Software\CloudPortalWebApplication\tomcat\webapps\clmui\WEB-INF\classes directory. 
• cloudservices.json (if the My Cloud Services console UI is installed as part of Platform Manager) – The location of the custom directory is set in the CustomDir access attribute. By default, the cloudservices.json file is in the C:\Program Files\BMC Software\BMCCloudLifeCycleManagement\Platform_Manager\configuration directory.

In the custom directory, you will find these json files:

• customPanelsConfig.json – Defines the panel, including the panel name and the location where the panel appears (on the Catalog details page or the Checkout page). The entry point function is also specified.
• customMenuConfig.json – Defines the entry point function for the top-level menus and submenus you want to add to the My Cloud Services console.

The overall process

The process for adding custom panels or sections is as follows:

Step 1:

• The cloud administrator creates a custom panel in HTML format.
• The cloud administrator implements callback hooks in JavaScript for initializing, validating, and fetching the custom field values.
• The cloud administrator updates the customPanelsConfig.json file to indicate where the HTML panel should appear.
• The cloud administrator updates the metadata.json file to indicate the custom field and its type. (The metadata.json file is located in BMC_CLM_Install_folder\Platform_Manager\configuration\customField. For an example of how fields are customized in that file, see Customizing-the-Cart-Checkout-page.)

Step 2: 

• If the data is sourced from a BMC Remedy AR System form or from BMC Atrium Orchestrator, the cloud administrator creates a data source configuration.
• The cloud administrator updates the HTML and JavaScript to use the data source configuration. See Adding-dynamic-lists-to-fields and Using-JavaScript-to-customize-the-My-Cloud-Services-console.

Step 3:

• (Optional) If support for the legacy My Cloud Service console is required, the cloud administrator customizes a BMC Service Request Management form.

Step 4:

• In My Cloud Services console, the end user opens the Service Catalog and selects the service offering with the custom panel.
• My Cloud Services console renders the HTML and the field in it. It also executes JavaScript to fetch the fields and associates them to the ServiceRequest object.
  In the legacy My Cloud Services console, the customized BMC Service Request Management form is used.

• The end user submits the cart, and provisioning starts.

Using sample files

You can find sample panels (for the Catalog service details page or the Cart Checkout page) in the CLMInstallationFolder\Cloud_UI\custom_sample folder. The custom panels are included in the customPanelsConfig_SAMPLE.json file. The html files and JavaScript files used in the samples are under the CLMInstallationFolder\Cloud_UI\custom_sample\samples folder.

The sample files show how to add the callback methods in JavaScript for initializing and handling events. For more information, see Using-JavaScript-to-customize-the-My-Cloud-Services-console.

To use the samples:

1. Copy the required files from the custom_sample folder to your CLMInstallationFolder\Cloud_UI\custom folder.

   Success

   Tip

   Do not confuse the custom directory here with the custom directory in installationDirectory\tomcat\webapps\clmui.

2. Rename the customPanelsConfig_SAMPLE.json file to customPanelsConfig.json, or copy the contents to the existing customPanelsConfig.json file.
3. Add the appropriate metadata to the CLMInstallationFolder\Platform_Manager\configuration\customField\metadata.json file.
   For an example of this procedure, see Customizing-the-Cart-Checkout-page.

To add a custom panel or section

1. Create a customPanelsConfig.json file in the custom folder. (Use the example in step 2 to create the file.)
   You can find the location of the custom folder in one of the following files:
   • config.properties (if the My Cloud Services console UI is installed as a standalone)
   • cloudservices.json (if the My Cloud Services console UI is installed as part of the Platform Manager)

2. Use the following example customPanelsConfig.json file, and edit your file to create the custom panel or section:

   [
       {
           "panel_name": "myCartCheckoutPanel",
           "title": "",
           "title_i18nkey": "",
           "url": "custom/cartcheckout.html",
           "location": "cart.checkout"
       },
       {
           "panel_name": "myAdditionalDisksPanel",         // REQUIRED. A unique name for this panel.
           "title": "Additional Disks",                    // OPTIONAL. If given, then it will be displayed as the title for the panel.
           "title_i18nkey": "cust_panel_addtldisks",       // OPTIONAL. This is the i18nkey for the title. If given, then the localized string will be looked up.
           "header": "Disk1, Disk2",                       // OPTIONAL. This is the string displayed as the header of the panel.
           "header_i18nkey": "addtldisk_header",           // OPTIONAL. This is the i18nkey for the header string.
           "panel_icon": "panelIcon", // OPTIONAL. If given, then this will add a new custom class to panel icon. Default icon is __icon-list
           "url": "custom/additionaldisks.html",           // REQUIRED. The html file to display in the custom panel embedded.
           "location": "catalog.offering.servergroup",     // REQUIRED. Where to embed this panel. See also location_data below.
           "location_data": {                                // OPTIONAL. Additional data that is needed to place the panel correctly. Content varies based on the location property
               "offerings": ["offering1", "offering2"],  // OPTIONAL. List of offerings (comma-separated offering names) for which to add the panel.
               "servergroup_tags": "<tags>",             // OPTIONAL. Server group tags that identifies which server groups to include.
               "panel_index": 1,                         // OPTIONAL. 0-based index of where to place.
               "servergroup_names" : ["servergroup1", "servergroup2"]  // OPTIONAL. List of server group names to include.
           },
           "entry_point_function": "mycompany.clmui.request.addtlDisksPanelEntryPointFn",  // REQUIRED unless the panel is just read-only information. Console will call this method and pass the API context.
           "roles": ["CLOUD ADMIN", "CLOUD ORGANIZATION ADMIN", "CLOUD END USER"], // OPTIONAL. Roles for which the panel should appear.
           "tenants": ["calbro", "widgetsinc"]                                      // OPTIONAL. List of tenants for which this panel should appear. If left out, then all tenants will see.
       }
   ]

   In the preceding example, the first section customizes the Cart Checkout page. (For an alternate way to customize the Cart Checkout page, see Customizing-the-Cart-Checkout-page.) The second section is for the custom panel. Following are more details about each key in the file:

   Key	Description
   panel_name	(Required) Name for the panel. (The name should be unique among the default and custom panels.)
   title	(Optional) Title for the panel. In the following example, "ADDITIONAL DISKS" is the title.
   title_i18nkey	Localization key for the title. If this key is specified, the localized string is looked up in the CLMInstallationFolder\Cloud_UI\custom\i18n\resources-locale_*.js file. (* represents the browser locale.) If the title_i18nkey key is not specified, then the title is displayed as it is specified in the configuration file.
   header	Header string displayed in the header of the panel. In the example above, "Disk 1, Disk 2" is the header.
   header_i18nkey	Localization key for the header string. If this key is included, the localized string is looked up in the CLMInstallationFolder\Cloud_UI\custom\i18n\resources-locale_*.js file. (* represents the browser locale.) If the header_i18nkey is not specified, the header is displayed as it is specified in the configuration file.
   panel_icon	Custom class for the panel icon. The default icon is __icon-list. If you want to use a different icon, add the new class to the CLMInstallationFolder\Cloud_UI\custom\skinning\css\styles.css file, and add the same class name to the configuration file.
   url	(Required) HTML file to display in the custom panel.
   location	(Required) Specifies where to place the panel. If it is inside a server group’s panel, and if you want to put it only for certain server groups, that server group will be identified by tag or name. Valid values: catalog.offering– For the Catalog service details page (top-level) catalog.offering.servergroup– For the Catalog service details page; applies to all server groups, or specific ones as defined by additional information in location_data
   location_data	(Optional) Additional information needed to place the panel. If the location is catalog.offering or catalog.offering.servergroup, you can specify additional location data in these properties: offerings – Identifies the offerings for which the panel will be added. Offerings are identified by their names, and you can specify 0 or more names. If the list is empty, or if the offerings property is not present, the panel is added to all the offerings. servergroup_tags – Identifies which server groups the panel applies to. The identifier is tag, which is configured in blueprints in the Service Designer of BMC Cloud Lifecycle Management. If the servergroup_tags key is not specified, the panel applies to all the server groups. If the panel applies to all server groups, or if the tag matches more than one server group, the panel is placed above all the server groups (like generic options panels). If a panel applies to multiple server groups, it is also placed above all server groups, and the panel title lists the server group names that the panel applies to. If the tag matches only one server group, the panel is placed inside the server group. (Applicable only to panels placed inside a server group) panel_index– A 0-based index that instructs where to place the panel inside a server group panel in relation to other subpanels such as Hardware and Software. If the index is 0, the panel will be the first one inside the server group and so on. If the panel_index property is not specified, the custom panel will be placed as the last panel inside the server group.
   entry_point_function	Method that the My Cloud Services console will call and then pass the API context.
   roles	Roles who will see the panel. It is a comma-separated list of 0 or more roles. Valid roles: CLOUD ADMIN CLOUD ORGANIZATION ADMIN CLOUD END USER For example, if CLOUD ORGANIZATION ADMIN is specified, only tenant admins will see it. If roles is not specified, all users (end users, tenant administrators, and administrators) will see the panel.
   tenants	Tenants who will see the panel. It is a comma-separated list of tenant IDs. (The tenants are defined in the Tenants workspace.) If tenants is not specified, the panel will appear for all users (after accounting for the roles specified). For example, if roles is defined as CLOUD END USER and tenants is defined as calbro_id, all end users of Calbro will see the panel.

To pass data back to BMC Atrium Orchestrator or the HTTP server

Complete the following step to ensure that data from fields on a custom panels is passed to BMC Atrium Orchestrator or the HTTP server. The data is passed in the form of CustomField objects that are embedded within the CSM request.

1. On the provider operation, set the pre-callout or post-callout to indicate which details must be passed to BMC Atrium Orchestrator workflow or a HTTP server call.

Use the following syntax for embedded CustomField objects in CSM requests. See also a complete CSM request (CSMRequest.txt) and a SampleAOCallout.roarfile (attached to this topic).