Extend the Release User Interface
You can extend Release by creating new endpoints backed by Jython scripts and new UI screens that use them. Each extension must be packaged in a jar archive and saved in the plugins folder of the Release server.
To avoid file name collisions, we recommend that you create a folder under web with a unique name for each UI extension plugin.
The following XML files tell Release where to find and how to interpret the content of an extension:
xl-rest-endpoints.xmlfor adding new REST endpointsxl-ui-plugin.xmlfor adding new top-menu items
These files are both optional.
Adding menu items to Release
The xl-ui-plugin.xml file contains information about the menu items to add to Release. You can order them using the weight attribute.
For example, xl-ui-plugin.xml could contain:
<plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.xebialabs.com/deployit/ui-plugin"
xsi:schemaLocation="http://www.xebialabs.com/deployit/ui-plugin xl-ui-plugin.xsd">
<menu-ref ref="xlrelease.menu.Main">
<menu id="xlrelease.menu.Custom" label="Custom" weight="45">
<menu-item label="Releases list" uri="include/ReleasesListPage/index.html" weight="10" path-suffix="custom/releases">
<property name="permissions" value="security#edit" />
</menu-item>
</menu>
</menu-ref>
<library name="xlrelease.releasesListPage"/>
</plugin>
Menus are enclosed in the <plugin> tag. The xl-ui-plugin.xsd schema verifies how menus are defined.
In this example, <menu-ref ref="xlrelease.menu.Main"> defines an extension for the Release main menu, which has the ID xlrelease.menu.Main.
<menu id="xlrelease.menu.Custom" label="Custom" weight="45"> adds a new menu with ID xlrelease.menu.Custom. This menu will have the label Custom and will be placed between the menus with IDs xlrelease.menu.Reports and xlrelease.menu.Settings, because weight 45 is between their respective weights.
Referring to predefined menu items
<menu-ref> is used to refer to the predefined Release menus. Predefined menus have structure similar to:
<menu id="xlrelease.menu.Main" label="" weight="-1">
<menu-item label="Tasks" path-suffix="tasks" weight="10" uri=""/>
<menu id="xlrelease.menu.Releases" label="Releases" weight="20">
<menu-item label="Overview" path-suffix="releases" weight="10" uri=""/>
<menu-item label="Pipeline" path-suffix="pipeline" weight="20" uri=""/>
<menu-item label="Templates" path-suffix="templates" weight="30" uri=""/>
</menu>
<menu id="xlrelease.menu.Reports" label="Reports" weight="40">
<menu-item label="Dashboard" path-suffix="dashboard" weight="10" uri="" />
<menu-item label="Release automation" path-suffix="release-automation" weight="20" uri="" />
<menu-item label="Release Value Stream" path-suffix="release-value-stream" weight="30" uri="" />
</menu>
<menu id="xlrelease.menu.Settings" label="Settings" weight="50">
<menu-item label="Profile" path-suffix="profile" weight="10" uri=""/>
<menu-item label="Global variables" path-suffix="global-variables" weight="20" uri=""/>
<!-- ... other menu items ... -->
<menu-item label="Configuration" path-suffix="configuration" weight="100" uri="">
<property name="permissions" value="admin"/>
</menu-item>
</menu>
</menu>
Nesting menu references
You can nest <menu-ref> items. This example shows how to add an item to a nested menu, in this case, xlrelease.menu.Reports:
<plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.xebialabs.com/deployit/ui-plugin"
xsi:schemaLocation="http://www.xebialabs.com/deployit/ui-plugin xl-ui-plugin.xsd">
<menu-ref ref="xlrelease.menu.Main">
<menu-ref ref="xlrelease.menu.Reports">
<menu-item label="Pending releases by team" ... />
</menu-ref>
</menu-ref>
...
Menu elements
Menu attributes
The attributes that are available for <menu> are:
| Attribute | Required | Description |
|---|---|---|
id | Yes | Menu item ID, which must be unique among all menu items in Release. If there are duplicate IDs, Release will return a RuntimeException. |
label | Yes | Text to show on the menu button. |
uri | Yes | Link that will be used to fetch the content of the extension. The link must point exactly to the file that the browser should load. Default pages such as index.html are not guaranteed to load automatically. |
weight | Yes | Menu item order. The higher the weight, the further to the right the menu item will be placed. |
<menu> can contain <menu>, <menu-item>, and <menu-separator> elements.
Menu-separator attributes
The attributes that are available for <menu-separator> are:
| Attribute | Required | Description |
|---|---|---|
weight | Yes | Menu separator order. |
Note: Menu separators are not rendered in the Release user interface.
Menu-ref attributes
The attributes that are available for <menu-ref> are:
| Attribute | Required | Description |
|---|---|---|
ref | Yes | ID of the menu item that will be extended. This must refer to an existing menu in the Release. |
<menu-ref> can contain <menu>, <menu-item>, or <menu-separator> elements, as well as other <menu-ref> elements.
Menu-item attributes
The attributes that are available for <menu-item> are:
| Attribute | Required | Description |
|---|---|---|
label | Yes | Text to show on the menu button. |
uri | Yes | Link that will be used to fetch the content of the extension. The link must point exactly to the file that the browser should load. Default pages such as index.html are not guaranteed to load automatically. |
weight | Yes | Menu item order. The higher the weight, the further in the menu item will be placed. |
path-suffix | Yes | Suffix that the menu item in the URL will use. |
<menu-item> elements can contain <property> elements.
Property attributes
Each menu item can contain multiple <property> elements that you can use to enhance functionality. The attributes that are available for <property> are:
| Attribute | Required | Description |
|---|---|---|
name | Yes | Name of the property exposed on a menu item. |
value | Yes | Value of the property. |
The only supported property is named permissions. It allows you to provide a comma-separated list of global or release permissions. If a user has any of the permissions in the list, then he or she can access the menu item. Global permissions are checked for the top-level menu, while release permissions are checked for the Release page submenu.
permissions can have the following values:
| Permission name | Scope | Permission description |
|---|---|---|
| admin | Global | All permissions |
| login | Global | Log in to Release |
| security#edit | Global | Access the Roles and Permissions screens and edit security on releases and templates |
| template#create | Global | Create a new template |
| release#create | Global | Create a release from any template; also see the Create Release permission on a single release |
| reports#view | Global | View reports |
| global_variables#edit | Global | Edit global variables (available in Release 4.8.0 and later) |
| environment#edit | Global | Create, edit or delete an environment. Permission is required to create stages and create environment labels |
| application#edit | Global | Create, edit, or delete an application |
| reservation#edit | Global | Access the scheduling pages, make a schedule, or reserve an environment |
| template#create_release | Template | Create a release from the template |
| template#view | Template | View the template |
| template#edit | Template | Edit the template |
| template#edit_security | Template | Edit the template security settings |
| release#view | Release | View the release |
| release#edit | Release | Edit the release |
| release#edit_security | Release | Edit the release security settings |
| release#start | Release | Start the release |
| release#abort | Release | Abort the release |
| release#edit_task | Release | Edit task in the release |
| release#reassign_task | Release | Reassign task in the release |
library attributes
The attributes that are available for <library> are:
| Attribute | Required | Description |
|---|---|---|
name | Yes | Name of the Angular module (extension library) that the extension should load. |