Create Custom Configuration Types

You can add custom configuration types in XML. Custom configuration types appear in the configuration screens, and custom tasks can reference configuration instances. You can use custom configuration type tasks to reference third-party component settings. For example, Release includes with JIRA Server and Jenkins Server, which are custom configuration types.

To use a custom configuration type from a custom task, you need:

• The definition of the custom configuration type
• The reference to the configuration type in the custom task definition
• To create a configuration instance
• To reference the configuration instance from a custom task

Configuration type definition

You define the custom configuration type in XML in synthetic.xml. For example, this is the definition of the "JIRA Server" and "Jenkins Server" types:

<type type="jira.Server" extends="configuration.HttpConnection"/>
<type type="jenkins.Server" extends="configuration.HttpConnection"/>

Each configuration type must extend the xlrelease.Configuration or configuration.HttpConnection root configuration type. The xlrelease.Configuration type can be used for simple configuration types, while the configuration.HttpConnection should be used if you need to define an HTTP endpoint.

In the example, the "JIRA Server" and "Jenkins Server" types extend configuration.HttpConnection, which defines these properties:

Property	Description
url	Address where the server can be reached
username	Log-in user ID on the server
password	Log-in user password on the server
proxyHost	HTTP proxy host
proxyPort	HTTP proxy port

The virtual="true" attribute means that this type will not appear in the UI and that you can not create an instance of this type.

Reference configuration type from custom task definition

To reference a custom configuration type from a custom task, you must add a specific property to the custom task definition in synthetic.xml. For example, this is the "Create JIRA issue" definition:

<type type="jira.CreateIssue" extends="xlrelease.PythonScript">
    <property name="jiraServer" category="input" label="Server" referenced-type="jira.Server" kind="ci"/>

    ...
</type>

The required attributes to refer to a custom configuration type are:

• kind="ci": Specifies that this property is a reference
• referenced-type="your.Type": Specifies which configuration type can be referenced in this property

Connections page

Use the Connections page to configure objects that a custom task can reference (such as JIRA tasks or Jenkins tasks). This page is accessible to users with the Admin global permissions.

You can also set up a custom configuration type on a specific folder. For more information, see Folder level configuration.

The page shows the configuration types that are currently available and allows you to create instances of the types.

To add a configuration instance, click for the type that you need. You can then set properties:

Enter a name in the Title box. In the Release application, the configuration instance is referred to by this name.

Display Warning for Entity Deletion

With Digital.ai Release 22.3, a warning dialog box is displayed to indicate reference templates and releases when deleting shared connections.

Testing connectivity

You can test the connectivity of the Connections options. All types that extend xlrelease.Configuration or configuration.HttpConnection in synthetic.xml are eligible for testing.

To enable the testing feature, place a Python script in the plugin folder with the name of the type. For example, in the case of a JIRA server:

<type type="jira.Server" extends="configuration.HttpConnection"/>

The script should be located in the jira folder and called Server.py. You can override the location and file name by adding the property scriptLocation in the type declaration:

<type type="jira.Server" extends="configuration.HttpConnection">
  <property name="scriptLocation" default="jira/TestConnection.py" hidden="true" />
</type>

The following properties are available in the script context:

Property	Description
HttpRequest	For more information, see the Jython API
HttpResponse	For more information, see the Jython API
configuration	Container with all properties from the type; for example, if the type extends configuration.HttpConnection, you can access the user name, password, and so on

The content of the script can be similar to:

import sys

# get the configuration properties from the UI
params = { 'url': configuration.url, 'username' : configuration.username, 'password': configuration.password,  'proxyHost': configuration.proxyHost, 'proxyPort': configuration.proxyPort }

# do an http request to the server
response = HttpRequest(params).get('/', contentType = 'application/json')

# check response status code, if is different than 200 exit with error code
if response.status != 200:
  sys.exit(1)

If your type extends from configuration.HttpConnection, you can use a standard simple HTTP connection test script available at path configuration/HttpConnectionCheck.py:

<type type="nexus.Server" extends="configuration.HttpConnection">
    <property name="scriptLocation" hidden="true" default="configuration/HttpConnectionCheck.py"/>
    <property name="checkConfigurationPath" hidden="true" default="/service/local/authentication/login"/>
    <property name="checkConfigurationContentType" hidden="true" default="application/json"/>
</type>

This script takes the URL configured in the UI, appends the value of the checkConfigurationPath property, and sends a HEAD request with the user name and password provided, also taking proxy settings into account. If the response status code is between 200 and 399, the configuration is considered to be correct.

Reference a configuration instance from a custom task

For information about referencing a configuration instance from a custom task, see Create a Jenkins task.