The Issue Tracking Systems page, which can be accessed through the Administration - Integrations - Issue Tracking Systems menu, allows management of integrations into third-party issue tracking systems. FlexDeploy currently provides out of box integration with Atlassian Jira. You can define custom implementation using either Java class or Groovy script. FlexDeploy reads ticket(s) from SCM commit message comments during build execution. As an example, if you use SVN, when committing a change back to the repository, simply put the issue name in the commit comment(case sensitive).  If using Git as your SCM, make sure that the Git executable is installed on FlexDeploy server and is accessible on the PATH. The Git executable version must be 1.7.9 or higher. 

Here is the out of box issue tracking systems. To configure, select Jira and click the Edit button. Issue Tracking System screen allows you to view the details on our of box Jira. FlexDeploy comes up with Java Implementation to integrate with Jira, you are not allowed to change implementation class and change or add new  properties. You can create additional Issue Tracking System as necessary using the Create button.

Image Removed

Image Removed

You can update description and ticket patter for the Jira integration here. Other fields are not editable.

...

Field Name

...

Required

...

Description

...

Id

...

Yes

...

System generated identifier (read-only).

...

Name

...

Yes

...

Name of the issue tracking system.

...

Description

...

No

...

Description of the issue tracking system.

...

Ticket Number Pattern

...

Yes

...

Pattern of the issues within the issue tracking system, used to associate FlexDeploy builds with particular issue(s). If not specified here, the pattern will need to be defined on each project which associates to your issue tracking system. For Jira, the pattern of tickets is the Jira project Key, followed by a dash (e.g. "MYPROJ-"). All tickets created for this project are prefixed by this key, making it the pattern.

...

You can provide global customizations for the Jira integration here, or override the settings at the project, or environment/project level. The customizations available are as follows.

Default Configuration

FlexDeploy can configure default rules which will apply at the project level.

Image Removed

You can provide global customizations for the Jira integration here, or override the settings at the project, or environment/project level. The customizations available are as follows.

...

Field Name

...

Required

...

Description

...

Update Tickets on Build

...

No

...

Check this box if you want to globally update any tickets associated to FlexDeploy builds. Can be overridden at the environment, project, or environment/project level.

...

Build Update Comment Pattern

...

No

...

Applicable only if Update Tickets on Build is checked. The value of this property is a groovy script which evaluates to the comment you wish to update associated tickets with when a build completes successfully. Groovy variables available to the script are provided in the (x=) dropdown to the right. Can be overridden at the environment, project, or environment/project level.

...

Update Ticket Status on Build

...

No

...

Applicable only if Update Tickets on Build is checked. Check this box if you want to globally update the status of any tickets associated to FlexDeploy builds. Can be overridden at the environment, project, or environment/project level.

...

To (Build)

...

No

...

Applicable only if Update Ticket Status on Build is checked. Any associated ticket will be updated to this status whenever the build completes successfully. Can be overridden at the environment, project, or environment/project level.

...

Update Tickets on Deploy

...

Check this box if you want to globally update any tickets associated to FlexDeploy deployments. Can be overridden at the environment, project, or environment/project level.

...

Deploy Update Comment Pattern

...

Applicable only if Update Tickets on Deploy is checked. The value of this property is a groovy script which evaluates to the comment you wish to update associated tickets with when a deployment completes successfully. Groovy variables available to the script are provided in the (x=) dropdown to the right. Can be overridden at the environment, project, or environment/project level.

...

Update Ticket Status on Deploy

...

FlexDeploy issue tracking systems integration (out of box or custom) can be configured globally for use by various Projects. Configurations can be overridden at Project level as well as necessary.

Image Added

Click on particular issue tracking system to configure it.

Image Added

You can update name, description and ticket pattern.

Default Configuration

You can provide the default configuration for the issue tracking system on the Default Configuration tab. You can still override these settings at the project or environment/project level.

Image Added

The configurations available are as follows.

Environment Configuration

FlexDeploy can configure global environment rules which will apply to all projects in the application unless overridden at the project level.

Image Removed

The selected ticket status for the Auto-approve Tasks on Status field, is for any External Approval Task that gets created for the Development environment. The task is automatically approved when the associated ticket, in the Issue Tracking System, reaches or exceeds the desired status. For more information on the setup of the External Approvals and configuring Issue Tracking System at the Project level, refer to the Project Issue Tracking System Configuration section of the Projects page.

Properties

Issue Tracking System properties provide the definition of configuration parameters that are required to integrate with that system. Values for these properties will be provided when Issue Tracking System Instances associated with the system (e.g. Jira) are configured in the FlexDeploy topology. See Topology for more information.

...

Status

Issue Tracking System statuses identify the statuses within your Jira system, and allows FlexDeploy to update your issues to those values at build or deployment time. You will add the statuses from the Jira workflow(s) associated to your Jira project(s). Click the Image RemovedandImage Removedbuttons to add or remove statuses from the list. 

...

Click the Save button to apply any updates. 

Build Request

Tickets can also be manually associated to an Issue Tracking System on the Build Request Form for each project.

Image Removed

Custom Issue Tracking System Integration

Let's see how to create a custom Issue Tracking System and integrate with Flex Deploy. Please follow the below steps for creating a new Issue Tracking System

• Provide a unique name and description
• Define properties for the new issue tracking system. Properties are configuration values used by FlexDeploy to connect to the new system.
  • If you define properties, you can indicate display and validation details. You can also indicate if property is required and/or encrypted.
  • Enter a unique Name before adding any properties
• Provide either Java Implementation or Groovy API

Let's define an example issue tracking system, so we can easily how to setup in FlexDeploy. You can provide implementation as Java class or just Groovy script. Groovy script would allow for dynamic update but use of Java code will require restart of server.

Here we are creating custom issue tracking system with the properties, you can add more as necessary.

Image Removed

API Implementation

Implementation must implement the following API operations to integrate with FlexDeploy.

...

Method Name

...

Description

...

populateTicket

...

This method should call the issue Tracking System using the ticket number(pTicket.getNumber())  and set the Description and Type

...

getTicketURL

...

This method should constrct the URL to access the ticket. (Ex http://<hostname>:<port>/redmine/issues/<issuenumber>.json)

...

addCommentToTicket

...

Adding pComment to the ticket. The ticket number(pTicket.getNumber()) from Ticket object should be used to get the Ticket and add the comment.

...

changeTicketStatusTo

...

Change the status of the ticket to pStatus. The ticket number(pTicket.getNumber()) from Ticket object should be used to get the Ticket and change the status.

...

getTicketStatus

...

checkConnection

...

This should invoke any status or heath check URL of the issue tracking system to ensure the system is up and running

...

parseTicketNumberFromChangeLogs

...

pProjectName - name of the project for which the Issue tracking system is condifured

pMessageToParse - list of string from the SCM commit logs

pTicketPatterList  - pattern configured in the project or for the issues tracking system.

Add a custom rule by project to parse the message log string using single or multiple patterns. You can also use a different pattern list. Should return a unique list of ticket numbers

Java Implementation

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

• Create java class that extends flexagon.fd.model.integration.its.api.IssueTrackingSystem. See example below.
  • Below example has testConnection method implemented. The method uses the properties map to retrieve the configuration values to connect to the issue tracking system.

package mycompany.extension.redmine.impl;

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.filter.HTTPBasicAuthFilter;

import java.io.Serializable;

import java.util.HashMap;
import java.util.Map;

import javax.ws.rs.core.Response;

import flexagon.fd.model.integration.its.api.IssueTrackingSystem;
import flexagon.fd.model.integration.its.api.Ticket;
import flexagon.fd.model.integration.util.ApiException;

public class RedmineServiceIntegration
  extends IssueTrackingSystem
{
  public RedmineServiceIntegration()
  {
    super();
  }

  @Override
  public void checkConnection()
    throws ApiException
  {
    String methodName = "checkConnection";
    System.out.println(methodName + " getting version for project to check connection");
    ClientResponse clientResponse = getWebResource("/projects/1/versions.json").get(ClientResponse.class);
    System.out.println(methodName + String.format(" Successfully invoked test connection URL %s", clientResponse));
    int statusCode = clientResponse.getStatusInfo().getStatusCode();
    if (statusCode == 401)
    {
      throw new ApiException("Invalid credentials.", "");
    }
    if (!(clientResponse.getStatusInfo().getFamily() == Response.Status.Family.SUCCESSFUL))
    {
      throw new ApiException(clientResponse.getEntity(String.class), clientResponse.getStatusInfo().getReasonPhrase());
    }
    System.out.println(methodName + " Test connection response code looks valid, check content of response");
    System.out.println(methodName + " Validated that JSON data was received from test connction URL invocation.");
  }

  private StringBuilder getRedmineURLBuilder()
  {
    StringBuilder urlBuilder = new StringBuilder((String) getProperties().get("REDMINE_URL"));
    return urlBuilder;
  }

  private String getRedmineURL()
  {
    return getRedmineURLBuilder().toString();
  }

  private String getUserName()
  {
    return (String) getProperties().get("REDMINE_USER_NMAE");
  }

  private String getPassword()
  {
    return (String) getProperties().get("REDMINE_PASSWORD");
  }

  @Override
  public void populateTicket(Ticket pTicket)
    throws ApiException
  {
    // TODO Implement this method
  }

  @Override
  public String getTicketURL(Ticket pTicket)
    throws ApiException
  {
    // TODO Implement this method
    return null;
  }

  @Override
  public void addCommentToTicket(Ticket pTicket, String pString)
    throws ApiException
  {
    // TODO Implement this method
  }

  @Override
  public void changeTicketStatusTo(Ticket pTicket, String pString)
    throws ApiException
  {
    // TODO Implement this method
  }

  @Override
  public String getTicketStatus(Ticket pTicket)
    throws ApiException
  {
    // TODO Implement this method
    return null;
  }

  private Client getRestClient()
  {
    Client restClient = Client.create();
    restClient.addFilter(new HTTPBasicAuthFilter(getUserName(), getPassword()));
    restClient.setReadTimeout(20000);
    restClient.setConnectTimeout(10000);
    return restClient;
  }

  public WebResource getWebResource(String resource)
    throws ApiException
  {
    String methodName = "getWebResource";

    if (resource != null && !resource.isEmpty() && !resource.startsWith("/"))
    {
      resource += "/" + resource;
    }
    WebResource webResource = null;
    try
    {
      webResource = getRestClient().resource(getRedmineURL()).path(resource);
    }
    catch (Exception e)
    {
      throw new ApiException(e.getMessage(), e.getMessage());
    }

    return webResource;
  }
}

• In order to compile your java class, you will need FlexDeployAPI.jar on classpath.
• 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.", "");
• Once you are ready with unit testing, you can prepare Jar file for your credential store java class and other utility classes. This jar file can be placed on server classpath now.
  • For Tomcat, put this jar file in apache-tomcat-flexdeploy/lib folder.
  • For WebLogic, put this jar file in Domain lib folder.
  • If you are using any third party libraries from your Java implementation, then those jar files will also need to be added to same lib folder. Keep in mind that this can cause issues with server functioning, so be prepared to remove your additional library files.

Groovy Implementation

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

• Create a groovy class. See example below.
  • Below example has testConnection and other methods implemented.

import flexagon.fd.model.integration.its.api.Ticket;
import flexagon.fd.model.integration.util.ApiException; 
class RedmineIssueTrackingSystem
{
  def checkConnection()
  {
	String methodName = "checkConnection()";
    try
    { 
      fdrestutils.testConnection(REDMINE_URL, "/projects/1/versions.json", REDMINE_USER_NMAE, REDMINE_PASSWORD)
    }
    catch (Exception e)
    {
      log.logInfo(methodName, " Failed in Test connection" + e.getMessage() + " " + e)
      throw new ApiException("Connection failed. " + e.getMessage());
    }
  }
  
  String getTicketStatus(Ticket ticket)
  {
    String methodName = "getTicketStatus()";
    String message = " ticket# ${ticket.toString()}"
    log.logInfo(methodName, message);
    String resourcePath = REDMINE_TICKET_URL_PATTERN.replaceAll("\\{REDMINE_ISSUE\\}", ticket.getNumber())
    javax.json.JsonObject jsonObj = fdrestutils.getRequest(REDMINE_URL, resourcePath, REDMINE_USER_NMAE, REDMINE_PASSWORD);
    if(jsonObj != null)
    {
      javax.json.JsonObject issue = jsonObj.getJsonObject("issue")
      if(issue!=null)
      {
        javax.json.JsonObject status = issue.getJsonObject("status")
        if(status !=null)
        {
          return status.getString("name")
        }       
      }
    }
	return null;
  }

   
  String getTicketURL(Ticket ticket)
  {
    String methodName = "getTicketURL()";
    String message = "ticket# ${ticket.toString()}"
    log.logInfo(methodName, message);
    String resourcePath = REDMINE_TICKET_URL_PATTERN.replaceAll("\\{REDMINE_ISSUE\\}", ticket.getNumber())
	message = "Redmine ticket URL is # ${REDMINE_URL}, resourcePath=${resourcePath}"
    log.logInfo(methodName, message)
	return REDMINE_URL + resourcePath;
  }
  
  def populateTicket(Ticket ticket)
  {
    String methodName = "populateTicket()";
	String message = "Populate ticket# ${ticket.toString()}"
    log.logInfo(methodName, message)
    String resourcePath = REDMINE_TICKET_URL_PATTERN.replaceAll("\\{REDMINE_ISSUE\\}", ticket.getNumber())
    javax.json.JsonObject jsonObj = fdrestutils.getRequest(REDMINE_URL, resourcePath, REDMINE_USER_NMAE, REDMINE_PASSWORD);
    if(jsonObj != null)
    {
      javax.json.JsonObject issue = jsonObj.getJsonObject("issue")
      if(issue!=null)
      {
        ticket.setDescription(issue.getString("description"))
        javax.json.JsonObject tracker = issue.getJsonObject("tracker")
        if(tracker !=null)
        {
          ticket.setType(tracker.getString("name"))
        }       
      }
    }
  }
  
  def addCommentToTicket(Ticket ticket, String pComment)
  {
	String methodName = "addCommentToTicket()";   
    try
    { 
	  String message = " Adding comment to ${ticket.toString()} , comment=${pComment}"
      log.logInfo(methodName, message)
      def builder = new groovy.json.JsonBuilder()
      def root = builder.issue {
              notes "${pComment}"
       }
      String payload = builder.toString();
      String resourcePath = REDMINE_TICKET_REST_PATTERN.replaceAll("\\{REDMINE_ISSUE\\}", ticket.getNumber())
      fdrestutils.putRequest(REDMINE_URL, REDMINE_USER_NMAE, REDMINE_PASSWORD, resourcePath, payload);
    }
    catch (Exception e)
    {
      log.logInfo( methodName, " Failed while  adding comment to the issue - " + e.getMessage() + " " + e)
      throw new ApiException("Connection failed. " + e.getMessage());
    }
  }
  
  def changeTicketStatusTo(Ticket ticket, String pStatus)
  {
    String methodName = "changeTicketStatusTo()";
	String message = " Adding comment to ${ticket.toString()} , status=${pStatus}"
    log.logInfo(methodName, message)
	def builder = new groovy.json.JsonBuilder()
	def root = builder.issue {
		notes "Status updated to ${pStatus}"
		status_id "${pStatus}"
	}
	String payload = builder.toString();
	String resourcePath = REDMINE_TICKET_REST_PATTERN.replaceAll("\\{REDMINE_ISSUE\\}", ticket.getNumber())
	fdrestutils.putRequest(REDMINE_URL, REDMINE_USER_NMAE, REDMINE_PASSWORD, resourcePath, payload);
  }
  
   
   def parseTicketNumberFromChangeLogs(String pProjectName, List<String> pChangeLogMessages, List<String> pTicketPatternList)
  {
	String methodName = "parseTicketNumberFromChangeLogs()";
	Set<String> ticketNumberList = HashSet<String>();
	String message = " Input ProjectName= ${pProjectName}, ChangeLogMessages=${pChangeLogMessages} , TicketPatternList=${pTicketPatternList}"
    log.logInfo(methodName, message)	
    if("Gradle".equals(pProjectName)) {
      String[] patterns = ["ZZZ-"];
      pTicketPatternList = Arrays.asList(patterns);
      message = "override pattern for Gradle TicketPatternList=${pTicketPatternList}"
      log.logInfo(methodName, message)
    }
    Collection<String> parsedTicketNumbers = flexagon.fd.model.integration.its.util.ChangeLogParser.getParser().parse(pChangeLogMessages, pTicketPatternList);
	message = "parsedTicketNumbers=${parsedTicketNumbers}"
    log.logInfo(methodName, message)
		
    if(parsedTicketNumbers != null && !parsedTicketNumbers.isEmpty() && pTicketPatternList != null && !pTicketPatternList.isEmpty())
    {
      parsedTicketNumbers.each{ parsedTicket ->
        pTicketPatternList.each{ pattern ->
			if(parsedTicket.startsWith(pattern))
			{
				String ticketNumber = parsedTicket.substring(pattern.length(),parsedTicket.length())
				ticketNumberList.add(ticketNumber)
			}
		}
      }
    }
	return ticketNumberList;
  }

}

• 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.", "");

...

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.

Using Groovy has the below advantages

• All the properties defined are available as groovy binding variables. For example, properties can be accessed directly like REDMINE_URL, REDMINE_USER_NMAE or REDMINE_PASSWORD etc
• log is a FlexDeploy logger variable which should be used to log any information from the groovy class.
• fdrestutils is a utility object available to use FlexDeploy API to invoke any REST API
  
  • testConnection(String pHostName, String pUrl, String pUserName, String pPassword)
  • getRequest(String pHostName, String pResourcePath, String pUserName, String pPassword) - Returns javax.json.JsonObject
  • postRequest(String pHostName, String pUserName, String pPassword, String pResourcePath, String pResourceName, String pPayload) - Returns boolean
  • putRequest(String pHostName, String pUserName, String pPassword, String pResourcePath, String pPayload) - Returns boolean

def builder = new groovy.json.JsonBuilder()

def root = builder.issue {

notes "${pComment}"

}

String payload = builder.toString();

String ticketNumber = ticket.getNumber();

String resourcePath = REDMINE_TICKET_REST_PATTERN.replaceAll("\\{REDMINE_ISSUE\\}", ticketNumber)

...

Issue Tracking System Variables

The list of Groovy variables available to use. Can be used at the project level on the Issue Tracking Systems tab or global level under Administration → Integrations → Issue Tracking Systems.

Environment Configuration

FlexDeploy can be configured with global environment rules which will apply to all projects unless overridden at the project level. Environment Configurations done for specific environment will be applicable for that specific environment (i.e. overrides for Default Configuration)

Image Added

The selected ticket status for the Auto-approve Tasks on Status field, is for any External Approval Task that gets created for the Development environment. The task is automatically approved when the associated ticket, in the Issue Tracking System, reaches or exceeds the desired status. For more information on the setup of the External Approvals and configuring Issue Tracking System at the Project level, refer to the Project Issue Tracking System Configuration section of the Projects page.

Properties

Issue Tracking System Properties provide the definition of configuration parameters that are required to integrate with specific instance of issue tracking system. Values for these properties will be provided when Issue Tracking System Instance is configured. Properties are read-only for out of box integrations.

Image Added

Status

Issue Tracking System Statuses table defines status details for specific issue tracking system, and allows FlexDeploy to update your issues to those values at build or deployment time.

Each status is represented by Id and Name. Click the Save button to apply any updates. 

Finding Jira Statuses

In case of Jira, you will add the statuses from the Jira workflow(s) associated to your Jira project(s). Click the Image AddedandImage Addedbuttons to add or remove statuses from the list. Similarly for other issue tracking systems, provide similar status details here.

Image Added

To identify the statuses to add, from within your Jira system, view the workflow(s) associated to your Jira project(s). Switching to the Text view of the workflow editor/viewer you can identify the workflow statuses and transition ids.

Image Added

Image Added
It is critical that the ids entered match the transition ids within your Jira workflows, otherwise, FlexDeploy will be unable to provide the desired updates.

Finding Redmine Statuses

In Redmine, issue statuses are global and can be found in the administration settings. Generally, statuses start with 1 and are sequential in the same order as listed in Redmine settings. However, sort order could have been changed, so it's recommended to use Redmine's Issue Statuses REST API to verify status ids. It is critical that the ids entered match the status ids in Redmine, otherwise, FlexDeploy will be unable to make the desired updates.

Image Added

Finding Azure Boards Statuses

In Azure Boards, issue statuses can be retrieved from the column names in the individual Board itself. It is critical that the status names entered in FlexDeploy match the column names in the Azure Board, otherwise, FlexDeploy will be unable to make the desired updates.

Image Added