Custom Change Management Systems

FlexDeploy has out of box integration with ServiceNow, BMC Remedyforce, Freshworks Freshservice, and Jira ITSM, and provides a framework to enable custom integrations with other change management systems. Such third-party Change Management System integrations can be enabled using a Java or Groovy implementation.

To view the list of Change Management Systems defined within FlexDeploy, select the Change Management tab on the Integrations page and select the Providers button on the top right:

Here you will see the out of the box integrations.

To create a custom integration for another provider click the Create button. The following tasks will be performed to complete the integration:

Provide a unique name and description.
Determine whether you will implement the integration in Java or Groovy. Groovy has the advantage that the script is loaded dynamically and does not require a FlexDeploy server recycle when you make changes.
Define properties for the new change management system. Properties are configuration values used by FlexDeploy to connect to the new system and parameterize its usage.
Define Ticket Fields as necessary, which are used to create Ticket or Incidents automatically from FlexDeploy.
Develop either a Java class or Groovy script to perform the integration. Groovy is recommended in most cases, unless there is a Java SDK that will be used to assist in the development.

The examples below demonstrate a custom integration for Zendesk using both Java and Groovy.

Properties

The Properties tab defines the metadata for parameters necessary to both connect to the underlying system and provide configurable options for any instances which will consume this integration.

URL, credentials, and other connection related parameters should be exposed as properties so that the configuration can be updated without changes to the Java or Groovy classes/scripts.

For customers providing your own integrations you may choose to hard-code some of the logic into the scripts to follow enterprise standards for your organization. For Systems Integrators who are developing solutions which may be utilized by multiple customers it is important to make use of properties where appropriate to allow simple configuration based on end customer requirements.

The metadata for each property consists of the following attributes:

Attribute	Description

Attribute	Description
Active	Whether this property is in use for the integration. Allows hiding the property without removing it.
Code	A unique, required name which is used by the API and other scripts, and therefore must following keyword limitations of Java and Groovy (e.g. no spaces or special characters other than underscore).
Display Name	A name for the property which will be displayed for data entry rather than the technical Key Name.
Description	A meaningful description of what the property is used for.
Required	Whether or not a value for the property is required for CMS instances using this provider. Implementations should use default values in the Java/Groovy class or script for any optional properties.
Data Type	The data type for the property. Supported types - String, Boolean, Integer, or Double,
Sub-Type	An optional qualifier describing the type of data the property will contain. This is used to validate the data entry. Supported types - URL, JDBCURL, or Directory. Simply leave blank if none of these qualifiers are applicable.
Encrypted	Indicates whether the property is secure and should be encrypted when stored, and care should be taken not to print their values in the logs.

Values for these properties will be provided when instances of this CMS are created.

API Implementation

Custom integrations must implement the following API operations:

If your usage of the CMS will not include the automated creation of TICKET or INCIDENT objects the API can be simplified. Although createTicket and createIncident are required to be implemented, if you are not using these auto-creation features you can choose to simply throw an exception from one or both methods as appropriate.

Example

throw new UnsupportedOperationException("createIncident is not supported for Zendesk CMS integration");

Add custom task notes

With out-of-the-box CMS providers including BMCHelixRemedyforce, ServiceNow, JiraITSM, and Freshworks, you have the ability to add notes to a FlexDeploy External Approval upon approval or rejection. Custom Change Management Systems have the same functionality. Can do so by overriding the following getAdditionalTicketInfo in your Groovy API. It takes CMSObject and environment code as parameters and must return a Map<String, String>.

Simple Example

def getAdditionalTicketInfo(CMSObject pTicket, String pEnvironmentCode)
{
  // Create notes to add to External Approval
  def changeNumber = pTicket.getNumber()
  def map = {'notes': 'Approval note for ' changeNumber + ' added by FD admin'}
  return map
}

Groovy Implementation

Here are high level steps for 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 change management system, you can place those in the libext folder and use those classes from Groovy script. This allows you to keep the dynamic part of implementation in Groovy and use a Java library.

Create a groovy class. The example shown below has the methods implemented.

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();
String ticketNumber = ticket.getNumber();
String resourcePath = REDMINE_TICKET_REST_PATTERN.replaceAll("\\{REDMINE_ISSUE\\}", ticketNumber)

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

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

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.cms.api.ChangeManagementSystem. Example shown below has the methods implemented which uses properties map to retrieve the configuration values to connect to the change management system.
All properties defined are available in Map returned by getProperties method.
We are using Zendesk as a use case.

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 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.