Customizing the CloudBees CD/RO Platform UI

You can customize the CloudBees CD/RO platform UI to get a more intuitive, task-specific user interface.

Customizing parameters

Two types of objects contain formal parameters – procedures and state definitions. For these objects, you can customize the way their formal parameters are presented. You can reorder the parameters and set the labels, form element types, default values, tooltip Help text, and whether or not the parameter is required. When defined, this customization shows up whenever the parameters are displayed—running a procedure, creating a step to call a procedure, creating a transition definition to a specific target state, and so on.

How do you customize parameters?

Create a property named ec_parameterForm on the object containing formal parameters (the procedure or state definition). The value of this property is an XML-style specification of form elements that map to the parameters. This property must be in sync with the formal parameters, which means all formal parameters must have a corresponding XML element, with no "extra" XML elements.

Custom parameter form contents

The value of the property in XML: Under a top-level element called <editor>, you need an element called <formElement> for each parameter. Under a <formElement>, you can specify the following tags:

property*—the name of the formal parameter
type*— entry|textarea|select|radio|checkbox|project|savedSearch|credential
label*—displayed next to the element
value—the initial value of the element (does not apply to credentials, which must be specified at runtime)
required—if true, the user must enter a value for the element
documentation—text displayed in the tooltip when the form element is "moused" over
numRows—valid for `textarea ` elements; represents the height of the element
option—a single option for select|radio elements; at least one is required
name*—the text displayed in the option
value—the value of the option
checkedValue—valid for checkbox elements; the value of the element when it is checked
uncheckedValue—valid for checkbox elements; the value of the element when it is unchecked
initiallyChecked—valid for checkbox elements; whether or not the element is "checked" by default

Note: An asterisk in the list above indicates a required tag.

Example

The following example is a parameter form that rearranges parameters and sets the labels, descriptions, default values, and form elements for each parameter.

<editor>
    <formElement>
        <label>One:</label>
        <property>one</property>
        <documentation>The first parameter.</documentation>
        <type>entry</type>
        <value>Test value</value>
    </formElement>
    <formElement>
        <label>Two:</label>
        <property>two</property>
        <documentation>The second parameter.</documentation>
        <type>textarea</type>
        <required>1</required>
    </formElement>
    <formElement>
        <label>Three:</label>
        <property>three</property>
        <documentation>The third parameter.</documentation>
        <type>select</type>
        <option>
            <name>ABC</name>
            <value>abc</value>
        </option>
        <option>
            <name>XYZ</name>
            <value>xyz</value>
        </option>
        <value>xyz</value>
    </formElement>
    <formElement>
        <label>Four:</label>
        <property>four</property>
        <documentation>The fourth parameter.</documentation>
        <type>radio</type>
        <option>
            <name>First Option</name>
            <value>123</value>
        </option>
        <option>
            <name>Second Option</name>
            <value>456</value>
        </option>
        <value>123</value>
    </formElement>
    <formElement>
        <label>Five:</label>
        <property>five</property>
        <documentation>The fifth parameter.</documentation>
        <type>checkbox</type>
        <checkedValue>true</checkedValue>
        <uncheckedValue>false</uncheckedValue>
        <initiallyChecked>1</initiallyChecked>
        <value>true</value>
    </formElement>
    <formElement>
        <label>Six:</label>
        <property>six</property>
        <documentation>The sixth parameter.</documentation>
        <type>project</type>
        <value>myProject</value>
    </formElement>
    <formElement>
        <label>Seven:</label>
        <property>seven</property>
        <documentation>The seventh parameter.</documentation>
        <type>savedSearch</type>
        <value>/projects/myProject/ec_savedSearches/mySavedSearch</value>
    </formElement>
    <formElement>
        <label>Eight:</label>
        <property>eight</property>
        <documentation>The eighth parameter.</documentation>
        <type>credential</type>
    </formElement>
</editor>▼

Preserving spaces in parameter values containing only spaces

You can restore the behavior in CloudBees CD/RO versions 4.2. x in which spaces are not stripped from parameter values that contain only spaces. To do so, add the COMMANDER_XML_READER_STRIP_WHITESPACE_TEXT variable to the wrapper.conf file on the server and set it to false :

set.default.COMMANDER_XML_READER_STRIP_WHITESPACE_TEXT=false▼

When set to true (the default), these spaces are stripped. This variable does not strip spaces in parameter values that contain leading or trailing spaces in conjunction with other characters.

Customizing the tab layout

Overview

A "view" defines the layout of tabs in the CloudBees CD/RO web UI. One or more tab views may be defined at the server, group, and user level. The default view the user sees when they first log in can be set at the server, group, and user level. The default defined on the user takes precedence over its groups and the groups take precedence over the server. CloudBees provides a system default view that will always show up in the user’s list. Views can inherit from each other and add/modify/remove/reposition tabs and subtabs as needed.

If you define a custom view, you have to manually add tabs such as Continuous Integration so that they will appear in your custom view.

View definition syntax

A view is an XML property. The following is a list of elements that can be defined in a view:

tab—a top level tab
label—the text to display for the tab
url—the target URL of the tab
accesskey—the keyboard shortcut to access this tab (a single letter)
position—the position of this tab relative to the other tabs (first tab is 1, second tab is 2, and so on)
show—when inheriting from another base view, if 0, the tab is not visible, if 1 it is visible (default 1)
tab—a subtab displayed within this tab
label—the text to display for the subtab
url—the target URL of the subtab (relative to CloudBees CD/RO base)
position—the position of this subtab relative to the other subtabs (integer greater than 1)
show—when inheriting from another base view, if "0", the tab is not visible, if "1" it is visible (default 1)
base—the name of a view from which to inherit tab and subtab definitions

The following is a basic definition of a two-tab view where one of the tabs has three subtabs.

<?xml version="1.0" encoding="utf-8"?>
<view>
   <tab>
      <label>Home</label>
      <url>home.php</url>
      <accesskey>h</accesskey>
   </tab>
   <tab>
      <label>Administration</label>
      <url>workspaces.php</url>
      <accesskey>a</accesskey>
      <tab>
         <label>Workspaces</label>
         <url>workspaces.php</url>
      </tab>
      <tab>
         <label>Directory Providers</label>
         <url>directoryProviders.php</url>
      </tab>
      <tab>
         <label>Licenses</label>
         <url>licenses.php</url>
      </tab>
   </tab>
</view>▼

The following is a view that inherits from the above view and:

Changes the URL of the Home tab
Adds a new tab called Projects and places it at the beginning of the list
Changes the accesskey of the Administration tab
Moves the Workspaces subtab to the end of the list
Hides the Licenses subtab

<?xml version="1.0" encoding="utf-8"?>
<view>
   <base>
   firstView</base>
   <tab>
      <label>Home</label>
      <url>customizedHome.php</url>
   </tab>
   <tab>
      <label>Projects</label>
      <url>projects.php</url>
      <accesskey>p</accesskey>
      <position>1</position>
   </tab>
   <tab>
      <label>Administration</label>
      <accesskey>z</accesskey>
      <tab>
         <label>Workspaces</label>
         <position>3</position>
      </tab>
      <tab>
         <label>Licenses</label>
         <show>0</show>
      </tab>
   </tab>
</view>▼

Storing views

Tab views are stored in the server, group, and user property sheets. The view definitions are stored in a property sheet called ec_ui/availableViews. The name of the view is set to the property’s description if defined, otherwise it is set to the property’s name. The value of the view property is the XML definition document described above.

Default views

The property ec_ui/defaultView, if set, determines the default view for users inheriting from that object.

If this property is set on the server, it is the default for all users.
If this property is set on a group, all users belonging to that group will see that view, overriding the server’s default if it is set also.
Finally, a user can explicitly set their view by defining the property on their own property sheet. If the user belongs to multiple groups that define defaults, then CloudBees CD/RO chooses the first group alphabetically.

The user can set their view by clicking on their name in the navigation bar, then clicking on the Edit Settings link. The list of views shown here comprise all views defined in the ec_ui/availableViews property sheets for the server, groups to which the user belongs, and the user itself.

If views have the same name at different levels, then the user overrides the group which overrides the server. If a user selects a view and chooses to Save, then the ec_ui/defaultView property on their sheet is set accordingly.

Two special values are always available in this list: "EC Default" and "Inherit". The former is the default tab layout defined in the CloudBees CD/RO web UI. The latter means to use the first view in the list. By default, all users inherit their tab view.

For more information on user settings, see the Edit User Settings Help topic.

Developing and troubleshooting

If you create an invalid view definition on a group or server property sheet, you will break the UI for all users who inherit that view. The best practice for developing tab views is to use a "test user". Store the view definition in the ec_ui/availableViews property sheet for that user, and set the ec_ui/defaultView for that user to the name of the new view. When the view is working properly and ready for other users, you can migrate the new view to a group or to the server.

If you continue to have difficulty and tab definitions are not working correctly and can no longer get to the user settings page, revert to the CloudBees CD/RO default by running the following command:

ectool setProperty /users/$USERNAME/ec_ui/defaultView ec_default▼

When you log out and then log back in, you will have the default view again. Note that changes to views are not visible until the next time a user logs in.

Home page configuration

The Automation Platform Home page (https://<cloudbees-flow-server>/commander/) is your configurable Dashboard. This page allows you to manage shared configurations and you can customize this page for your work preferences also. Refer to The Home page Help topic for details on creating Job Configurations, Shortcuts, Jobs Quick View, and Reports.

Shared Home page configurations can be set globally or for specific groups of users only. The general model for creating shared configurations is:

Set up your personal configuration the way you want it to appear to others. To get to the configuration page, select the Administration tab > Plugins > and click the Configure link for EC-Homepage.
Click Save to make the configuration available to a specific group or globally to everyone on the server.

If you published the configuration to a specific group, no further action is needed. If you published the configuration globally, continue to the next step.

Copy and paste the Tab XML string into a specific user’s or group’s view.

This adds the public configuration to that user’s or group’s own home page and no further action is required for the user or group. If this step is not completed, additional action is required as described in Installing the Home page.

You can alter an existing shared configuration by loading from a previously saved location, make changes, then save the changes back to the original or an alternate location.

User settings

Use the Backup Settings action to save and restore your personal Home page configuration.

Select Create to back up and temporarily set aside your personal settings while you create or update shared settings.
Select Restore to retrieve your personal settings after updating shared settings.

Location

Select Global to share the new Home page with everyone on the server, or select Group to share with specific users only.

Installing the Home page

If a globally available Tab XML string (from the Configure EC-Homepage page) has not been pasted to the user’s or group’s view, it must be added to an existing view definition to replace the standard Home page with the one provided by this plugin. To do this, click Load. This replaces the current home page with the one that’s publicly available.

Reconfiguring the “Contact Support” Link

To redirect the CloudBees Support URL (available from the Help link on each CloudBees CD/RO web page) to your own support center, you can create a file to add to the CloudBees CD/RO installation directory at <CloudBees CD/RO Install Dir>/apache/htdocs/commander. Create a file named config_user.php with the following contents:

<?php $config["contactSupportUrl"] = "your URL"; ?>

Replace your URL in the example above with the URL for your customer support site. If no value is supplied, a blank window appears.

You must restart the CloudBees CD/RO web server for your change to take effect.