Customizing the My Cloud Services console with top-level menu and submenu items

You can customize the My Cloud Services console with top-level menu and submenu items (as shown below). You can also include links to additional dashboards and reports or direct links on the My Cloud Services console.

These top-level menu items can open custom content on the body of the same page, or they can launch a separate browser window or tab. Finally, you can configure permissions so that the content that is displayed varies by tenant or by user role (for example, administrators versus end-users).

This topic contains the following information:

Before you begin

1. Verify that your configuration specifies the default location of the custom directory. 
   If com.bmc.cloud.ui.custom.resource.dir is missing and not properly configured, you will not see your changes. Depending on how you installed the My Cloud Services console (clmui), verify that the custom directory is set: 
   • If you installed the My Cloud Services console (clmui) on its own host, open the Config.properties file (by default, /opt/bmc/CloudPortalWebApplication/tomcat/webapps/clmui/WEB-INF/classes or C:\Program Files\BMC Software\CloudPortalWebApplication\tomcat\webapps\clmui\WEB-INF\classes).
     You should see the following property and value:
     com.bmc.cloud.ui.custom.resource.dir=installDirectory\\custom
     For example:
     com.bmc.cloud.ui.custom.resource.dir=/opt/bmc/CloudPortalWebApplication/Cloud_UI/custom (Linux)
     com.bmc.cloud.ui.custom.resource.dir=C:\\Program Files\\BMC Software\\CloudPortalWebApplication\\Cloud_UI\\custom (Windows)

   • If you did not install the My Cloud Services console (clmui) on its own host but on the Platform Manager host, open the cloudservices.json file (by default, C:\Program Files\BMC Software\BMCCloudLifeCycleManagement\Platform_Manager\configuration\cloudservices.json). In the CustomDir section, you should see the attributeValue property whose value is the custom directory: 

     {
         "cloudClass" : "com.bmc.cloud.model.beans.AccessAttribute",
         "datatype" : "String",
         "description" : "Directory that contains customization web content",
         "guid" : "780a47aa-d6a9-4894-9aa5-a5fa2ce26cb1",
         "hasValueObject" :
          [
            {
               "cloudClass" : "com.bmc.cloud.model.beans.AccessAttributeValue",
               "attributeValue" : "C:\\Program Files\\BMC Software
               \\BMCCloudLifeCycleManagement\\Cloud_UI\\custom",
               "guid" : "8b03984d-7750-4ba2-a8f7-8f7ef48fb43d",
               "name" : "CustomDir"
            }
          ],
          "isOptional" : true,
          "isPassword" : false,
          "modifiableWithoutRestart" : false,
          "name" : "CustomDir"
     }

     Note

     If the attributeValue property is missing or if it has no value or if the directory separator is a single backslash (\), update it to specify your custom directory with the correct double backslash separator (by default, C:\\Program Files\\BMC Software\\BMCCloudLifeCycleManagement\\Cloud_UI\\custom).

     Tip

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

2. Copy the contents of the installationDirectory/Cloud_UI/custom_sample directory to the installationDirectory/Cloud_UI/custom directory on the My Cloud Services Console host.
   

3. Create a file in the custom directory and name it customMenuConfig.json if it does not already exist. 

To add top-level menu items to the My Cloud Services console

You can easily add top-level menu items to the My Cloud Services console.

1. Log on to the My Cloud Services console. 

2. Open customMenuConfig.json in a text editor.

   Tip

   Be careful when you add new properties to the JSON. You can easily break the JSON by accidentally including or omitting commas, brackets, quotation marks, and so on.

3. Add square opening and closing brackets ( [ ... ] ) to define the JSON contents. 

4. In the brackets, add the menu items and links. 
   The following example adds the top-level menu item BMC Software to the console, as shown in the previous screenshot. Only the required items are included in the sample code. For detailed reference information, see Available options for use with top-level menu items.
   

   Note

   Do not include comments inside the JSON. Embedded comments (for example, \\this is help text ) can crash the browser.

   [
   	{   
           "label": "BMC Software",
           "name": "bmcsoftware",
           "url": "https://www.bmc.com",
   		"embed" : false
    	}
   ]

   1. Enclose menu items inside the opening and closing curly brackets ( {...} ).
      Separate each top-level menu item with a comma. 

   2. Add a required label.
      The label is displayed in the top-level menu. Separate all properties with a comma. 

   3. Add a required name.
      The name must be unique. It is displayed in the browser URL when the template is loaded in the console.
   4. Add a required URL for top-level menu items.
      The example URL opens an external URL, but it could also launch an HTML page. Make sure that the HTML page actually exists, or you will see an error. For more information, see To launch a new HTML page or embed HTML code.
5. Save customMenuConfig.json and reload the page.
   If you correctly entered the code, your changes are immediately displayed. 

6. Add another top-level menu item as needed, for example, Contacts. 
   Separate additional menu items with a comma, as shown in the code sample. If a user clicks Contacts, the browser opens the contacts.html file in a new tab or window, depending on your browser's configuration. 

   [
   	{   
           "label": "BMC Software",
           "name": "bmcsoftware",
           "url": "https://www.bmc.com",
   		"embed" : false
    	},
   	{
           "label": "Contacts",
           "name": "contacts",
           "url": "custom/contacts.html"
   	}
   ]

7. Save customMenuConfig.json and reload the page.
   

Back to top

To include submenu items under top-level menu items

You can include one layer of submenu items under top-level menu items. In the following screenshot, Browser Statistics has two submenu items – Browser Popularity and Browser OS. But you cannot include submenu items under a submenu item. For example, Browser OS cannot contain its own submenu items. 

 

1. Open customMenuConfig.json in a text editor. 
   The following code sample creates a top-level menu heading (Browser Statistics) with two sub-menu items that users can select. These submenu items open URLs in new tabs on your browser. 

2. Add the label and name properties to identify the top-level menu heading. 
   When you create submenu items, do not add a url property to the top-level menu. 

3. Add submenu as the type of the top-level menu item.

4. Add the items property and include opening and closing [...] brackets. 
   You must include all sub-menu items inside the opening and closing [...] brackets. 
   

   {
           "label": "Browser Statistics",
           "name": "browser statistics",
           "type": "submenu",
           "items": [
               {
                   "label": "Browser Popularity",
                   "name" : "BrowserPopularity",
                   "url"  : "http://www.w3schools.com/browsers/default.asp",
                   "type" : "menuitem",
                   "embed": false
               },
               {
                   "label": "Browser OS",
                   "name" : "BrowserUsageByOS",
                   "type" : "menuitem",
                   "url"  : "http://www.w3schools.com/browsers/browsers_os.asp",
                   "embed": false
               }
           ]
       }

    

5. Add the submenu items:
   1. Add the required label and a name. 
   2. Add menuitem as the type.
   3. Add a required URL. 
      These submenu items launch external URLs but they could reference HTML pages. For more information, see To launch a new HTML page or embed HTML code.
   4. Set the embed property to false so that the url opens the external website in a new window or tab, depending on your browser settings.
6. Save customMenuConfig.json.
7. Reload the page to see your changes.

Back to top

To add tenants to the top-level menu or submenu items

Optionally, you can attach tenants to display a different set of top-level menu or submenu items, based on how you configured tenants. If you do not add the tenants property, then the menu item appears for all tenants. For example, in the previous screenshot, AltoCloudAdmin was logged in and could view the Browser Statistics menu item.

If you specify a tenant or a set of tenants (using comma-separated tenant names as defined in the Tenant workspace of the Administration Console), then the menu item is shown only if a user belonging to that tenant logs in to the My Cloud Services console.

1. In customMenuConfig.json, add a tenant or set of tenants inside the opening and closing [...] brackets, separated by commas.
   Use the following syntax:

   "tenants" : ["CirroStratus Inc"]

   "tenants" : ["CirroStratus Inc", "AltoStratus LLC"]

   In the following code sample, only users belonging to the CirroStratus Inc tenant can see the top-level menu item. All other users are now excluded, for example, AltoCloudAdmin who belongs to the AltoStratus LLC.  

   {
           "label": "Browser Statistics",
           "name": "browser statistics",
           "type": "submenu",
   		"tenants" : ["CirroStratus Inc"],
           "items": [
               {
                   "label": "Browser Popularity",
                   "name" : "BrowserPopularity",
                   "url"  : "http://www.w3schools.com/browsers/default.asp",
                   "type" : "menuitem",
                   "embed": false
               },
               {
                   "label": "Browser OS",
                   "name" : "BrowserUsageByOS",
                   "type" : "menuitem",
                   "url"  : "http://www.w3schools.com/browsers/browsers_os.asp",
                   "embed": false
               }
           ]
       }

2. Save customMenuConfig.json and reload the page to see your changes.
   In the BMC test environment, the user AltoCloudAdmin was already logged on, He did not belong to the CirroStratus Inc tenant and consequently, the Browser Statistics menu item no longer appeared. When CirroCloudAdmin, a member of the CirroStratus Inc tenant, logged on, the menu item appeared. 

   

3. To refine the permissions, add the tenants property to any top-level menu or submenu item, as shown in the following example:

   Note

   When you add tenants to a submenu, the lower-level permissions of the submenu take precedence over the higher-level permissions of the top-level menu. However, adding tenants to the top-level menu implicitly sets the permissions for any submenus. If a tenant cannot see the top-level menu, that tenant cannot see the submenu, even if you explicitly assign the tenant to a submenu. 

   {
           "label": "Browser Statistics",
           "name": "browser statistics",
           "type": "submenu",
   		"tenants" : ["CirroStratus Inc", "AltoStratus LLC"],
           "items": [
               {
                   "label": "Browser Popularity",
                   "name" : "BrowserPopularity",
                   "url"  : "http://www.w3schools.com/browsers/default.asp",
                   "type" : "menuitem",
                   "embed": false,
   				"tenants" : ["AltoStratus LLC"]
               },
               {
                   "label": "Browser OS",
                   "name" : "BrowserUsageByOS",
                   "type" : "menuitem",
                   "url"  : "http://www.w3schools.com/browsers/browsers_os.asp",
                   "embed": false,
   				"tenants" : ["CirroStratus Inc"]
               }
           ]
       }

4. Save customMenuConfig.json and reload the page to see your changes.
   In this revised example, CirroStratus Inc and AltoStratus LLC are now the tenants of the top-level menu and they both can view the top-level menu. In addition, AltoStratus LLC is the tenant of the Browser Popularity submenu, and CiroStratus Inc is the tenant of the Browser OS submenu. When CirroCloudAdmin refreshes the browser, that user can view the top-level menu item but only one of the submenu items.

   

Back to top

To add roles to the top-level menu or submenu items

You can add roles to menu items. The roles property defines which functional roles can see the top-level menu or submenu items. The list of roles is comma-separated and can include 0 or more. The valid roles are:

• CLOUD ADMIN
• CLOUD ORGANIZATION ADMIN
• CLOUD END USER

If you do not specify a role or a set of roles, then all users (end users, tenant admins, and admins) can see the menu item. If you specify CLOUD ADMIN, then only cloud administrators can see the menu item, and so on. 

1. In customMenuConfig.json, add roles or a set of roles to the list inside inside the opening and closing [...] brackets, separated by commas without spaces between the roles. 
   Use the following syntax:

   "roles" : ["CLOUD ADMIN"]

   "roles" : ["CLOUD ADMIN", "CLOUD END USER"]

   In the following example, only the CLOUD ADMIN can see the Reports top-level menu item and the submenus.

   	{
           "label": "Reports",
           "name": "Reports",
           "type": "submenu",
           "roles": ["CLOUD ADMIN"],
           "items": [
               {
                   "label": "Report 1",
                   "name": "Report1Name",
                   "url": "custom/report1.html",
                   "type": "menuitem",
                   "embed": true
               },
               {
                   "label": "Report 2",
                   "name": "Report2Name",
                   "type": "menuitem",
                   "url": "custom/report2.html",
                   "embed": true
               },
               {
                   "label": "Report 3",
                   "name": "Report3Name",
                   "type": "menuitem",
                   "url": "custom/report3.html",
                   "embed": true
               }
           ]
       }

2. Save customMenuConfig.json and reload the page to see your changes. 
   If a CLOUD END USER or CLOUD ORGANIZATION ADMIN logs in, they cannot see the Reports top-level menu item.
    

3. To refine the permissions, add the roles property to any top-level menu or submenu item, as shown in the following example.

   Note

   The lower-level permissions of the submenu take precedence over the higher-level permissions of the top-level menu. However, adding roles to the top-level menu implicitly sets the permissions for any submenus. If a role cannot see the top-level menu, that role cannot see the submenu, even if you explicitly assign a role to a submenu. 

   	{
           "label": "Reports",
           "name": "Reports",
           "type": "submenu",
           "roles": ["CLOUD ADMIN", "CLOUD END USER"],
           "items": [
               {
                   "label": "Report 1",
                   "name": "Report1Name",
                   "url": "custom/report1.html",
                   "type": "menuitem",
                   "roles": ["CLOUD ADMIN"],
                   "embed": true
               },
               {
                   "label": "Report 2",
                   "name": "Report2Name",
                   "type": "menuitem",
                   "url": "custom/report2.html",
                   "roles": ["CLOUD ADMIN"],
                   "embed": true
               },
               {
                   "label": "Report 3",
                   "name": "Report3Name",
                   "type": "menuitem",
                   "url": "custom/report3.html",
                   "roles": ["CLOUD END USER"],
                   "embed": true
               }
           ]
       }

4. Save customMenuConfig.json and reload the page to see your changes.
   Based on the sample code, here are the expected results:
   • Any Cloud Administrator can see the Reports top-level menu and Report 1 and Report 2. 
   • Any Cloud End User can see the Reports top-level menu and Report 3.
     
   • A Cloud Organization Admin cannot see the Reports top-level menu or any reports.  

Back to top

To combine tenants and roles in the JSON

You can combine roles and tenants in the JSON. Make sure that you understand which roles and tenants that your users belong to—the results might not be what you expect. 

1. In customMenuConfig.json, include roles and tenants as needed to the menu items.
   The following example adds a set of tenants to the top-level menu and individual tenants to the submenus in the Reports section.

   	{
           "label": "Reports",
           "name": "Reports",
           "type": "submenu",
           "roles": ["CLOUD ADMIN", "CLOUD END USER"],
   		"tenants": ["AltoStratus LLC", "CirroStratus Inc"],
           "items": [
               {
                   "label": "Report 1",
                   "name": "Report1Name",
                   "url": "custom/report1.html",
                   "type": "menuitem",
                   "roles": ["CLOUD ADMIN"],
   				"tenants": ["AltoStratus LLC"],
                   "embed": true
               },
               {
                   "label": "Report 2",
                   "name": "Report2Name",
                   "type": "menuitem",
                   "url": "custom/report2.html",
                   "roles": ["CLOUD ADMIN"],
   				"tenants": ["CirroStratus Inc"],
                   "embed": true
               },
               {
                   "label": "Report 3",
                   "name": "Report3Name",
                   "type": "menuitem",
                   "url": "custom/report3.html",
                   "roles": ["CLOUD END USER"],
   				"tenants": ["CirroStratus Inc"],
                   "embed": true
               }
           ]
       }

2. Reload your browser.
   Based on the permissions you just set, AltoCloudUser1 can still see the top-level menu but now cannot see the submenu.
   
   The following table lists the expected results defined in the sample code: 

   Role/Tenant combination	Can see Reports top-level menu?	Can see Reports 1 submenu?	Can see Reports 2 submenu?	Can see Reports 3 submenu?
   Cloud Admin/CirroStratus Inc	Yes	No	Yes	No
   Cloud Admin/AltoStratus LLC	Yes	Yes	No	No
   Cloud Organization Admin/CirroStratus Inc	No	No	No	No
   Cloud Organization Admin/AltoStratus LLC	No	No	No	No
   Cloud End User/CirroStratus Inc	Yes	No	No	Yes
   Cloud End User/AltoStratus LLC	Yes	No	No	No

Back to top

To launch a new HTML page or embed HTML code

You can launch HTML code in a new page or embed HTML code in the My Cloud Services console. The customMenuConfig.json file uses the url property to reference the HTML page. 

1. Create an HTML file under the custom directory. 
   If the HTML content must interact with the My Cloud Services console using the JavaScript customization API – described at Using JavaScript to customize the My Cloud Services console– then the HTML page must be a partial page enclosed in <div></div> tags. In that case, include the JavaScript and CSS files that the HTML file uses in the custom/customResourcesToInclude.txt file. For more details, see the sample provided in the installationDirectory/Cloud_UI/custom_sample/samples/reportsmenu directory. 
   If the HTML content does not need to interact with the My Cloud Services console using JavaScript customization API, you can use a complete HTML page defined within <html></html> tags, as shown in the following example.

   <!DOCTYPE html>
   <html>
   <head>
   <script>
   function clickCounter() {
       if(typeof(Storage) !== "undefined") {
           if (sessionStorage.clickcount) {
               sessionStorage.clickcount = Number(sessionStorage.clickcount)+1;
           } else {
               sessionStorage.clickcount = 1;
           }
           document.getElementById("result").innerHTML = "You have clicked the button " + sessionStorage.clickcount + " time(s) in this session.";
       } else {
           document.getElementById("result").innerHTML = "Sorry, your browser does not support web storage...";
       }
   }
   </script>
   </head>
   <body>
   <p><button onclick="clickCounter()" type="button">Click me!</button></p>
   <div id="result"></div>
   <p>Click the button to see the counter increase.</p>
   <p>Close the browser tab (or window), and try again, and the counter is reset.</p>
   </body>
   </html>

2. In customMenuConfig.json, add the url property. 

3. Add the embed property.
   Depending on how you define the embed property (true or false), the behavior of the browser UI is significantly different. 

   • If "embed": true, the UI embeds the HTML code when you click the menu item (for example, Report 3). 

     {
         "label": "Report 3",
         "name" : "report3name",
         "type" : "menuitem",
         "url"  : "custom/report3.html",
         "embed": true
     }

     

   • If "embed": false, depending on how your browser is configured, the UI prompts you to open the HTML page when you click the menu item. In this example, the Firefox browser asks you how you want to open the file. You could open the HTML page in a new tab on the same browser, or you could open the HTML page in a different application, for example, Google Chrome. 

     {
         "label": "Report 3",
         "name" : "report3name",
         "type" : "menuitem",
         "url"  : "custom/report3.html",
         "embed": false
     }

     

4. Save customMenuConfig.json.
5. Reload the page to see your changes. 

Back to top

To localize top-level menu or submenu items

You can localize menu items as needed, based on your browser's language setting and resource files present under the custom\i18n directory. For more information, see Localizing the My Cloud Services console for version 4.6.

1. Edit the resource files of all the localized languages in your environment (English, French, Chinese, and so on) and add the new key/value pair.
   For example, add the following key/value pair to the French resource files (resources-locale_fr.js and resources-locale_fr-fr.js):

   {
   	"key" 	: "browserstatisticskey",
   	"value" : "Statistiques Navigateurs"
   }

2. In customMenuConfig.json, add the label_i18nkey property and the new key you just added to the resource file. 
   The following example adds a Browser Statistics menu item that references a localized menu item defined in your resource files. The following label_i18nkey key refers to the "Statistiques Navigateurs" value localized in resources-locale_fr-fr.js. 

   {
           "label": "Browser Statistics",
           "name": "browser statistics",
           "type": "submenu",
   		"tenants" : ["CirroStratus Inc"],
   		"label_i18nkey" : "browserstatisticskey"
   }

3. Save customMenuConfig.json.
4. Reload the page to see your changes. 
   

Back to top

Available options for use with top-level menu items

When you create top-level menu items and links, you can use the following options inside the customMenuConfig.json file:

 "label": "BMC Software", "name": "bmc", "url": "http://www.bmc.com", "embed": false }

Back to top

JSON template

A template version of the customMenuConfig.json file is attached for you to experiment with. 

1. Download the JSON (customMenuConfig.json) to the custom directory.
2. Create your own HTML pages to use with the My Cloud Services console.
3. Modify the customMenuConfig.json file as needed. 
4. Reload the browser page to see your changes. 

Back to top