10 Using Apache Groovy for Custom Service Requests, Rules, and Manipulating Output

This chapter contains the following topics:

10.1 Understanding Groovy for Orchestration Components

In the Orchestrator Studio, programmers can use Apache Groovy, a scripting language for the Java platform, to extend the functionality of orchestrations. In the Orchestrator Studio, you can use Groovy to:

  • Create a custom service request that uses complex logic to perform transactions that cannot be configured in a standard service request.

  • Create a custom rule with complex conditions that cannot be configured in a standard rule.

  • Manipulate output from a REST connector response. For example, if an orchestration with a REST connector service request returns information in XML format, you can convert it to JSON for output mapping.

  • Manipulate the output from an orchestration response.

Using Groovy scripts has two advantages over using custom Java. First, the Orchestrator Studio provides an editing window for creating the Groovy script, so you do not have to use an external editor to create and test your custom program. The editing window contains a Groovy template that you can use to help get you started. Second, the Orchestrator includes the Groovy script natively as part of the orchestration, so you do not have to deploy a custom program like you do with custom Java. The Groovy script simply executes as part of the orchestration.

10.2 Groovy Template for a Custom Service Request

In the Orchestrator Studio, the Custom Service Request design page contains a Groovy template that you can use to create a custom service request.

Figure 10-1 Groovy Code Template for a Custom Service Request

Description of Figure 10-1 follows
Description of ''Figure 10-1 Groovy Code Template for a Custom Service Request''

The following list describes the highlighted sections in the preceding code:

  1. Add or remove import lines as necessary.

  2. Do not modify the function definition or script definition.

  3. Copy and paste the code in the commented lines and use them in your script. The code lines include:

    • Parameters for defining a string, numeric value, date format, and date value.

    • Parameters for including a warning or log statements in the AIS Server log, which can be used for debugging script issues.

    • Parameter for populating the returnMap for outputs.

The Groovy template also includes an orchAttr that enables you to include additional information in the Groovy script. See Additional Attributes and Methods Available in the Groovy Script Templates.

10.3 Groovy Template for a Custom Rule

In the Orchestrator Studio, the Custom Rule Request design page provides the following code template to help you create a custom rule using Groovy:

Figure 10-2 Groovy Code Template for a Custom Rule

Description of Figure 10-2 follows
Description of ''Figure 10-2 Groovy Code Template for a Custom Rule''

The following list describes the highlighted sections in the preceding code:

  1. You can add or remove import lines as necessary.

  2. Do not modify the function definition or script definition.

  3. Copy and paste the code in the commented lines and use them in your script.

    The code lines include parameters for defining a string, numeric value, date format, and date value. They also include parameters for including a warning or log statements in the AIS Server log, which can be used for debugging script issues.

The Groovy template also includes an orchAttr that enables you to include additional information in the Groovy script. See Additional Attributes and Methods Available in the Groovy Script Templates.

10.4 Groovy Template for Manipulating Output from a REST Connector Response

In the Orchestrator Studio, the Connector design page provides a Groovy code template that you can use to manipulate the output from a REST connector response.

The response can contain output in XML, which you can convert to JSON using Groovy. For example, your orchestration might include a step with a REST connector to a third-party system, and its response may return in XML. You could write a Groovy script to reformat that response in JSON.

Figure 10-3 Groovy Code Template for Manipulating REST Connector Output

Description of Figure 10-3 follows
Description of ''Figure 10-3 Groovy Code Template for Manipulating REST Connector Output''

The following list describes the highlighted sections in the preceding code:

  1. You can add or remove import lines as necessary.

  2. Do not modify the function definition or script definition.

    The main function uses "string in" and "string out," which cannot change.

    Call other functions in the script and define them below.

  3. Copy and paste the code in the commented lines and use them in your script.

    The code lines include parameters for defining a string, numeric value, date format, and date value, as well as writing log entries and populating the returnMap for outputs. The code lines also include parameters for including a warning or log statements in the AIS Server log, which can be used for debugging script issues.

The Groovy template also includes an orchAttr that enables you to include additional information in the Groovy script. See Additional Attributes and Methods Available in the Groovy Script Templates.

10.5 Groovy Template for Manipulating Output from an Orchestration Response

The Orchestration Outputs design page provides a Groovy template that you can use to:

  • Refine the outputs of an orchestration response as required by the parameters in the consuming device or program.

  • Add static text to the response such as details about a company or customer.

  • Delete information from the response so it cannot be read by the consuming program.

Figure 10-4 shows the Groovy template that you can use to manipulate orchestration output:

Figure 10-4 Groovy Code Template for Manipulating Orchestration Output

Description of Figure 10-4 follows
Description of ''Figure 10-4 Groovy Code Template for Manipulating Orchestration Output''

The following list describes the highlighted sections in the preceding code:

  1. You can add or remove import lines as necessary.

  2. Do not modify the function definition or script definition.

    The main function uses "string in" and "string out," which cannot change.

    Call other functions in the script and define them below.

  3. Copy and paste the code in the commented lines and use them in your script. The code lines include parameters for defining a string, numeric value, date format, and date value. They also include parameters for including a warning or log statements in the AIS Server log, which can be used for debugging script issues.

The Groovy template also includes an orchAttr that enables you to include additional information in the Groovy script. See Additional Attributes and Methods Available in the Groovy Script Templates.

10.6 Additional Attributes and Methods Available in the Groovy Script Templates

All Groovy scripts are passed an OrchestrationAttributes instance called orchAttr that contains additional information that can be used in the Groovy script. Table 10-1 provides a description of the attributes. Table 10-2 describes the methods available in the OrchestrationAttributes class.

Table 10-1 Attributes in the OrchestrationAttributes Class

Attribute Type Description

orchestrationName

String

The name of the currently running orchestration.

token

String

The token for the current session.

langpref

String

The language of the execution user.

locale

String

The locale of the execution user.

dateFormat

String

The date format of the execution user.

dateSeperator

String

The date separator of the execution user.

simpleDateFormat

Sting

The Java simple date format of the execution user.

decimalFormat

String

The decimal format of the execution user.

addressNumber

Integer

The address number of the execution user.

alphaName

String

The name of the execution user.

appsRelease

String

The current application release.

country

String

The country code of the execution user.

username

String

The user name of the execution user.

environment (Orchestrator Studio 6.1.0)

String

The current environment of the execution user.

tempDir (Orchestrator Studio 6.1.0)

String

The temp directory configured in the rest.ini.

Table 10-2 Methods in the OrchestrationAttributes Class

Method Response Type Description

writeWarn(String message)

String

Write a message as a warning to the log.

writeDebug(String message)

String

Write a message as a debug to the log.

writeWarn(String message, Exception e)

String

Write a message as a warning to the log with an exception.

writeDebug(String message, Exception e)

String

Write a message as a debug to the log with an exception.

getOrchestrationName()

String

Get the name of the currently running orchestration.

getToken()

String

Get the token for the current session.

getLangPref()

String

Get the language preference for the execution user.

getLocale()

String

Get the locale of the execution user.

getDateFormat

String

Get the date format of the execution user.

getDateSeperator()

String

Get the date separator.

getSimpleDateFormat()

String

Get the Java simple date format of the execution user.

getDecimalFormat()

String

Get the decimal format of the execution user.

getAddressNumber()

Integer

Get the address number of the execution user.

getAlphaName()

String

Get the name of the execution user.

getAppsRelease()

String

Get the current application release.

getCountry()

String

Get the country code for the execution user.

getUsername()

String

Get the username for the execution user.

getEnvironment()

(Orchestrator Studio 6.1.0)

String

Get the current execution environment.

getTempDir()

(Orchestrator Studio 6.1.0)

String

Get the temp directory configured in the rest.ini.

getTempFileName(String fileName)

(Orchestrator Studio 6.1.0)

String

Build a fully qualified file name in the temp directory configured in the rest.ini. The fileName parameter is the name of the file to be appended to the directory.

getUniqueTempFileName(String baseFileName)

(Orchestrator Studio 6.1.0)

String

Build a fully qualified unique file name in the temp directory configured in the rest.ini. The baseFileName parameter is the name of the file to be appended to the directory. If that file name already exists, a unique ID will be appended to baseFileName until a unique name is found.

getMachineKey()

(Orchestrator Studio 9.2.4)

String

Get the machine key (first 10 characters) of the AIS server. (Release 9.2.4.2)

The maximum length for this field is ten characters. If the string is longer than ten characters, it will be truncated.

getMachineName()

(Orchestrator Studio 9.2.4)

String

Get the machine name of the AIS server. (Release 9.2.4.2)

getLongUserId ()

(Orchestrator Studio 9.2.4)

String

Get the long User Id for the currently logged in user. (Release 9.2.4.2)

toString()

(Orchestrator Studio 6.1.0)

String

Outputs a JSON string representing all values in this class.