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.xmladds items to the top menu bar in Deploy
xl-rest-endpoints.xmladds custom REST endpoints
Both files are optional.
Adding menu items
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
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:
||Yes||Menu item ID, which must be unique within all menu items in Deploy. If there are duplicate IDs, Deploy will return a
||Yes||Text to show on the menu button.|
||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
||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:
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
extensions: ui: file: "xl-ui-plugin.xml" server: file: "xl-rest-endpoints.xml" timeout: 60 seconds rootPath: "/api" scriptsPathPrefix: "/extension"
||xl-rest-endpoints.xml||Update the file name to match with your file|
||60 seconds||Update the request timeout|
||/api||Update the rootPath matches with your file|
||/extension||Update the ScriptPathPrefix matches with your file|
Declaring server endpoints
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:
||Yes||Relative REST path which will be exposed to run the Jython script.|
||No||HTTP method type (
||Yes||Relative path to the Jython script in the classpath.|
xl-rest-endpoints.xml file adds a
GET endpoint at
<?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
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
The Deploy server returns a HTTP response of type
application/json, which contains a JSON object with the following fields:
||Serialized value that is set in
||Text that was sent to standard output during the execution.|
||Text was sent to standard error during the execution.|
||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
Sample UI extension
You can find a sample UI extension plugin in
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
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