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:

ui-extension-demo-plugin
    src
        main
            python
                demo.py
            resources
                xl-rest-endpoints.xml
                xl-ui-plugin.xml
                web
                    demo-plugin
                        demo.html
                        main.css
                        main.js

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"
    xmlns="http://www.xebialabs.com/deployit/ui-plugin"
    xsi:schemaLocation="http://www.xebialabs.com/deployit/ui-plugin xl-ui-plugin.xsd">
    <menu id="test.demo" label="Demo" uri="demo.html" weight="12" />
</plugin>

Calling Deploy REST services

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

• Deploy REST API services
• REST endpoints created by the 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:

extensions:
  ui:
    file: "xl-ui-plugin.xml"
  server: 
    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"
           xmlns="http://www.xebialabs.com/deployit/endpoints"
           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 ... -->
</endpoints>

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:

• Request: JythonRequest
• Response: JythonResponse
• Deploy services, described in the Jython API documentation

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.

Troubleshooting

Menu item does not appear in UI

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 :

xl-rest-endpoints.xml
xl-ui-plugin.xml
web/

The incorrect output:

./xl-rest-endpoints.xml
./xl-ui-plugin
.xml
web/

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:

test/
test/__init__.py
test/importing-script.py
test/calc/test/calc/__init__.py
test/calc/Calc.py

This is the import:

from test.calc.calc import Calc