Groovy Libraries - Flexagon Documentation

Groovy Libraries allow custom Groovy functions and helpers to be shared and reused across all Groovy scripts in FlexDeploy

Groovy Library access should be limited to a small group of trusted users, similar to Administrators, due to its powerful permissions.

Creating a Library

Libraries can be viewed and created by navigating to the Administration->Groovy Libraries page. Next click the Create Library (blue star)

button.

You will be prompted to provide a unique identifier for the library, called the Library Key (blue star)

The Library Key is also how your Groovy Library will be referenced from other scripts.

Upon saving the form (blue star)

you will be presented with a blank editor where one or more functions can be defined for your library.

Writing Functions

A function can be any common logic you would like to share across scripts. Lets take a very simple example and say we want to make a function that returns the FlexDeploy REST API URL.

// define any number of helper functions for this library

String getFlexDeployAPIUrl()
{
  def baseURL = FLEXDEPLOY.getFlexDeployBaseUrl()
  return "${baseURL}/flexdeploy/rest/v2"
}

Notice the use of the FLEXDEPLOY helper library as well. EMAIL, FLEXDEPLOY, REST, TOPOLOGY, and LOG helpers are all available for use in your custom library.

Testing Functions

Users must have the GROOVY_LIBRARY_UPDATE permission to test any Groovy library. Libraries can be tested at any point right from the editor by clicking the Try It button in the header.

Here you can write a sample script to test one or more functions in your library. Note that code suggestions for your library will not be shown in the try it window. With your test script ready simply hit the Run button or use the default shortcut of ctrl+shift+h to the test the function. In the screen shot we can see the result as http://localhost:8000/flexdeploy/rest/v2

Annotating Functions

By default when accessing library functions from other scripts they will have very basic information as seen below:

Its often beneficial to provide more information such as a description of the method and/or describing any parameters for your method. Both can be accomplished by using the SuggestionMethodMeta annotation.

Now we can see our function description when using it from other scripts:

SuggestionMethodMeta API

Field	Type	Description
description	String	Overall description of the function. Markdown can be used.
params	List of Strings	A list of strings describing the function parameters. See full example below.
deprecated	boolean (default false)	If true this will indicate the function as deprecated. The name will be <del>struckthrough</del> when viewing in other scripts.
depAlternate	String	Optional alternative function name to use if this current function is deprecated.

import flexagon.ff.common.core.suggestions.SuggestionMethodMeta;

@SuggestionMethodMeta(
  description = "Surely this function is overkill right?",
  params = ["first - The first param", "second - The second param"],
  deprecated = true,
  depAlternate = "multiply2"
)
Long multiply(Long first, Long second)
{
  return first * second;
}

Long multiply2(Long first, Long second)
{
  return first * second;
}

Rename/Delete a Library

To rename a library simply click the edit pencil :Pencil_Edit: icon next to the Library Key.

Changing the Library Key may break existing Groovy scripts using the old key of the Library. It is advised not to change the key once the library is in use.

To delete a library simply click the Delete button next to the edit button. Similar to renaming the library - deleting a library that is in use will break any Groovy script using the deleted library.

Library Compilation

The following section explains in detail how the script code you write is compiled and made available to each FlexDeploy Groovy script. This information can be helpful in more advanced Groovy Libraries. The authored script code for each library is wrapped in a class declaration like so

package com.flexagon.groovy.custom;
// imports in the script are moved here

public class LIB_MY_LIB {
  // your script code is inserted here  
}

This class is compiled once at server startup and then on each change of the library script. Finally, when running a Groovy script, an instance of this library class is instantiated and made available to the script as a variable matching the Library Key. You can think of it as FlexDeploy automatically adding the following lines at the beginning of all of your Groovy scripts:

def LIB_MY_LIB = new com.flexagon.groovy.custom.LIB_MY_LIB();

Importing Other Custom Libraries

Importing other custom libraries is only supported in version 9.0.0.2+

Custom libraries are not made available in other custom libraries by default, however they can be imported as needed. The below code snippet shows how the custom LIB_PIPELINE_UTILS imports and uses another custom library LIB_LOGGER.

// imports omitted for brevity

// create a new instance of our custom library
// the LOG variable should be passed in the constructor for any imported custom library instance
def logger = new com.flexagon.groovy.custom.LIB_LOGGER(LOG)

void myPipelineFunction()
{
  logger.logMessage("Logger library import")
  // code omitted for brevity
}

Static Methods

Methods can be called statically, without an instance created, if they have the static modifier. Note - this only applies when importing other custom libraries since other Groovy scripts have instances created behind the scenes. See Library Compilation above. For example: LIB_LOGGER

static void logMessage(String message)
{
  // log
}

void logMessage2(String message)
{
  // log
}

LIB_PIPELINE_UTILS

import com.flexagon.groovy.custom.LIB_LOGGER;

def loggerInstance = new LIB_LOGGER(LOG);

void myPipelineFunction()
{
  // This WILL work
  LIB_LOGGER.logMessage("Logger library static method")
  
  // This will NOT work
  LIB_LOGGER.logMessage2("Logger library instance method")
  
  // BOTH of these will work
  loggerInstance.logMessage("Logger library static method")
  loggerInstance.logMessage2("Logger library instance method")
}

Static method caveatA final note on static methods - Static methods cannot access instance variables. This means if you have a static method defined in your library and try to access FLEXDEPLOY, LOGor any other instance variables it will not work and produce an error like the following: You attempted to reference a variable in the binding or an instance variable from a static context.In this case you must either remove the static modifier or not use the variable in question.

Circular Imports

Circular imports of custom libraries are not allowed and if found an error will be thrown

[Circular imports detected. Please check if libraries are creating instances of each other outside of a function scope..]

when attempting to test or save the library.

The below example demonstrates a circular library import and why its a problem:

LIB_ONE

def libTwo = new com.flexagon.groovy.custom.LIB_TWO(LOG)

def myFunction() {
  // do some logic
}

LIB_TWO

def libOne = new com.flexagon.groovy.custom.LIB_ONE(LOG)

def myFunction() {
  // do some logic
}

Lets look at what happens when FlexDeploy compiles and creates instances of your custom libraries for other Groovy scripts to use.

FlexDeploy will iterate through all your Groovy Libraries and create an instance of each.
A new instance of LIB_ONE is created.
During initialization of LIB_ONE it will create a new instance of LIB_TWO as declared on line 1 of LIB_ONE
An instance of LIB_TWO is created during step 3. This in turn creates an instance of LIB_ONE as declared on line 1 of LIB_TWO.
1. We are now stuck in a loop between steps 3 and 4, infinitely creating new instances. This is what is known as a circular dependency and will result in an error being thrown.

If it is absolutely necessary to have a circular dependency between libraries, then the creation of library instances should be done within a function scope.

LIB_ONE

def libTwo = new com.flexagon.groovy.custom.LIB_TWO(LOG)

def myFunction() {
  // do some logic
}

LIB_TWO

import com.flexagon.groovy.custom.LIB_ONE;

def myFunction() {
  def libOne = new LIB_ONE(LOG)
  // do some logic
}

FlexDeploy 9.0 Documentation

​Groovy Libraries allow custom Groovy functions and helpers to be shared and reused across all Groovy scripts in FlexDeploy

​Creating a Library

​Writing Functions

​Testing Functions

​Annotating Functions

​SuggestionMethodMeta API

​Rename/Delete a Library

​Library Compilation

​Importing Other Custom Libraries

​Static Methods

​Circular Imports

Groovy Libraries allow custom Groovy functions and helpers to be shared and reused across all Groovy scripts in FlexDeploy

Creating a Library

Writing Functions

Testing Functions

Annotating Functions

SuggestionMethodMeta API

Rename/Delete a Library

Library Compilation

Importing Other Custom Libraries

Static Methods

Circular Imports