Extend the Deploy user interface

You can extend Deploy by adding user interface (UI) screens that call REST services from the Deploy REST API or from custom endpoints, backed by Jython scripts that you write.

Structuring a UI extension

You install a UI extension by packaging it in a JAR file and saving it in the XL_RELEASE_SERVER_HOME/plugins folder. The common file structure of a UI extension is:


The recommended procedure is to create a folder under web with an unique name for each UI extension plugin, to avoid file name collisions.

The following XML files inform Deploy where to find and how to interpret the content of an extension:

  • xl-ui-plugin.xml adds items to the top menu bar in Deploy
  • xl-rest-endpoints.xml adds custom REST endpoints

Both files are optional.

Adding menu items

The xl-ui-plugin.xml file contains information about the menu items that you want to add to the top menu bar. You can order individual menu items using the weight attribute.

Menus are defined by the menu tag and enclosed in the plugin tag. The xl-ui-plugin.xsd schema verifies how menus are defined.

The attributes that are available for the menu tag are:

Attribute Required Description
id Yes Menu item ID, which must be unique within all menu items in Deploy. If there are duplicate IDs, Deploy 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 to the file that the browser will load. Default pages such as index.html are not guaranteed to load automatically.
weight Yes Menu item order. Indicates the position on the menu bar. A higher value for the weight places the item further to the right. Menu items created by extensions always appear after the native Deploy menu items.

Example menu item definition

This is an example of an xl-ui-plugin.xml file that adds a menu item called Demo:

<plugin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.xebialabs.com/deployit/ui-plugin xl-ui-plugin.xsd">
    <menu id="test.demo" label="Demo" uri="demo.html" weight="12" />

Calling Deploy REST services

You can call the following services from an HTML page created by a UI extension:

Important: The Deploy GUI uses the Session-based Authentication and all the UI extension requests are automatically authenticated.

Tip: If you have configured Deploy to run on a non-default context path, ensure you take this into account when building a path to the REST services.

Extend the server extension

To update the default server extension capability, configure the following token in the deploy-server.yaml file:

    file: "xl-ui-plugin.xml"
    file: "xl-rest-endpoints.xml"
    timeout: 60 seconds
    rootPath: "/api"
    scriptsPathPrefix: "/extension"
Attribute default value Description
file xl-rest-endpoints.xml Update the file name to match with your file
timeout 60 seconds Update the request timeout
rootPath /api Update the rootPath matches with your file
scriptsPathPrefix /extension Update the ScriptPathPrefix matches with your file

Declaring server endpoints

The xl-rest-endpoints.xml file declares the endpoints that your extension adds to Deploy.

Every endpoint should be represented by an endpoint element that can contain following attributes:

Attribute Required Description
path Yes Relative REST path which will be exposed to run the Jython script.
method No HTTP method type (GET, POST, DELETE, PUT). The default value is GET.
script Yes Relative path to the Jython script in the classpath.

Example: This xl-rest-endpoints.xml file adds a GET endpoint at /test/demo:

<?xml version="1.0" encoding="UTF-8"?>
<endpoints xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.xebialabs.com/deployit/endpoints endpoints.xsd">
    <endpoint path="/test/demo" method="GET" script="demo.py" />
    <!-- ... more endpoints can be declared in the same way ... -->

After processing this file, Deploy creates a new REST endpoint that is accessible via http://{xl-deploy-hostname}:{port}/{[context-path]}/api/extension/test/demo.

Note: If the default server extension token is updated/changed in deploy-server.yaml, make sure the same configured values are used in the URL.

Writing Jython scripts

You can implement the logic of REST endpoints in Jython scripts. Every script will perform queries or actions in Deploy and produce a response.

Objects available in the context

In a Jython script, you have access to the following objects:

HTTP response

The Deploy server returns a HTTP response of type application/json, which contains a JSON object with the following fields:

Field Description
entity Serialized value that is set in response.entity during script execution. Deploy handles serialization of standard JSON data types: Number, String, Boolean, Array, Dictionary, and udm.ConfigurationItem.
stdout Text that was sent to standard output during the execution.
stderr Text was sent to standard error during the execution.
Exception Textual representation of any exception that was thrown during script execution.

HTTP status code

You can explicitly set an HTTP status code via response.statusCode. If a status code is not set explicitly and the script executes with no issues, the client will receive code 200. For unhandled exceptions, the client will receive code 500.

Sample UI extension

You can find a sample UI extension plugin in XL_DEPLOY_SERVER_HOME/samples.


If you do not see your UI extension in Deploy, verify that the file paths in the extension JAR do not start with ./. You can check this with the jar tf yourfile.jar command.

The correct output :


The incorrect output:


Importing Jython modules

For Jython extensions, if you import a module in a Jython script, the import must be relative to the root of the JAR and every package must have the __init__.py file.

For this file structure:


This is the import:

from test.calc.calc import Calc