Groovy Libraries

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

1 Creating a Library
2 Writing Functions
- 2.1 Testing Functions
- 2.2 Annotating Functions
  - 2.2.1 SuggestionMethodMeta API
3 Rename/Delete a Library
4 Library Compilation

Creating a Library

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

You will be prompted to provide a unique identifier for the library, called the Library Key .

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

Upon saving the form 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

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

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 struckthrough when viewing in other scripts.
depAlternate	String	Optional alternative function name to use if this current function is deprecated.

import flexagon.fd.model2.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 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 it is recompiled.

Finally, when running a Groovy script, an instance of this library class is instantiated and made available to the script.