Custom Issue Tracking Systems

FlexDeploy has out-of-box integrations with Jira, Redmine, Azure Boards, GitLab, and GitHub. You can easily integrate with other issue tracking systems as well. Such third-party Issue Tracking System integrations can be enabled using Java or Groovy implementation. Several ITS templates are shipped with FlexDeploy, but you can create more to connect to other systems that aren’t supported with a vanilla install.

Go to Issue Tracking Systems page using Configuration → Integrations → Issue Tracking menu.

Let's look at more details on how to create a custom Issue Tracking System Provider with FlexDeploy. Click Create to implement an integration with custom issue tracking system.

Go to the ITS Providers screen.

Click create, or click on an existing row if you are making changes to an existing ITS Provider.

Provide a unique name and optionally description
Define properties for the new issue tracking system. Properties are configuration values used by FlexDeploy to connect to the new system. The values of the properties that you define here are set on Issue Tracking Instances, folders, and projects.
- If you define properties, you can indicate display and validation details. You can also indicate if a property is required and/or encrypted.
- Enter a unique Name before adding any properties
Provide either Java Implementation or Groovy API. If both are supplied, the Java Implementation is used. Java implementation means that you are giving the classpath for a java class which you are placing the jar for in the apiext folder. This is a change from 7.0 and earlier, where they went in libext. Groovy is defined on the Groovy API tab. A Groovy script would allow for dynamic update, whereas use of Java code will require restart of server.
Click Save.

Here we are editing a custom issue tracking system with properties. You can add existing properties using the drop down on the create button.

API Implementation

Your Implementation must extend IssueTrackingSystem (FlexDeploy Function SDK javadoc) in order to be used by FlexDeploy. If you are not going to allow calling a method, you can leave the body blank, or throw an error in the body, but the method must be defined. If you choose to make a Java implementation, your IDE will verify that you have implemented all the required methods. If you choose the Groovy implementation, then the FlexDeploy UI will validate that your class contains the necessary methods. Groovy implementations can be used even with 3rd party jars that you place in apiext, and allow for easier iterations.

Groovy Implementation

Here are the high level steps for a Groovy implementation. You can use any IDE to prepare this implementation.

As groovy is able to access FlexDeploy variables and Java classes, you can take advantage of Java libraries from Groovy script. For example, if there is Java library used to access the issue tracking system, you can places those in lib folder and use those classes from Groovy script. This allows you to keep dynamic part of implementation in Groovy and use Java library.

Create a groovy class. The example shown below has methods implemented.
You need to implement all methods defined in IssueTrackingSystem (FlexDeploy Function SDK javadoc)
All properties defined are available as groovy binding variables. For example, properties can be accessed directly like REDMINE_URL, REDMINE_USER_NAME, REDMINE_PASSWORD, etc,
Implement all the methods described in the table in the API Implementation section
For any failure connecting to the system or if any issues with the data, then you can throw exception. For example, throw new ApiException("Invalid credentials.", "");

Groovy Utilities

There are a number of functions available for use in your custom groovy implementation scripts. View suggestions while editing in the script editing windows by typing Ctrl + Space.

Class	Description

Class	Description
LOG	Functions for printing log messages to fd logs
REST	Functions for making REST API calls

def builder = new groovy.json.JsonBuilder()
def root = builder.issue
{
    notes "${pComment}"
}
String payload = builder.toString();

def client = REST.getClient().url(REDMINE_URL + REDMINE_REST_PATTERN);
client.basicauth(REDMINE_USER_NAME, REDMINE_PASSWORD);
client.put(payload);

LOG.info("Rest API create call successful");

Java Implementation

Here are the high level steps for a Java implementation. You can use any IDE to prepare this implementation.

Create java class that extends flexagon.fd.model.integration.its.api.IssueTrackingSystem. Example shown below has testConnection method implemented which uses properties map to retrieve the configuration values to connect to the issue tracking system.
All properties defined are available in Map returned by getProperties method.

In order to compile your java class, you will need FlexDeployAPI.jar on classpath.
Implement all the methods defined by IssueTrackingSystem (FlexDeploy Function SDK javadoc) .
For any failure connecting to the system or if any issues with the data, then you can throw exception. For example throw new ApiException("Invalid credentials.", "");
Once you are ready with unit testing, you can prepare Jar file for your java class and other utility classes. This jar file can be placed on server classpath now.
- Put this jar file in $FLEXDEPLOY_HOME/apiext folder. This folder should be next to the apache-tomcat-flexdeploy folder. This is a change from versions prior to 8.0.
- If you are using any third party libraries from your Java implementation, then those jar files will also need to be added to same apiext folder. Keep in mind that this can cause issues with server functioning, so be prepared to remove your additional library files.
To pickup changes to your API, the FlexDeploy server must be restarted.