Clarity Consultants

Gel Introduction Training Session

In this session we’ll find out what GEL is, see how to set up the environment for command line GEL scripting, and create simple stand-alone GEL scripts from a subset of the available tag libraries.

You can download this programme as a PDF here.

What is GEL?

From the standard Clarity/GEL documentation:
“GEL (Generic Execution Language) is tool you can use to turn XML into executable code. It is based on Jelly, a Commons project."

It has been extended and embedded into CA Clarity PPM to enable custom logic to solve business problems. GEL is the basis for the enterprise application integration framework within CA Clarity PPM.

GEL also provides a collection of standard integrations that provide connectors to enterprise applications such as Remedy Help Desk.

With GEL you can invoke and process a variety of data sources:

Web Services
GEL can read or write to any SOAP-based web service. This includes the XOG web services.

File System
GEL can read or write to any delimited file including those on local disks, network disks or disk arrays.

GEL can upload or download to FTP servers.

GEL uses JDBC to access RDBMS to read or write data.”

GEL scripts can be executed from within Clarity by installing them as processes (this is covered in session 4), or from the command line.

Further Reading: has details of all the standard libraries that can be included within a GEL script. It was last updated around January 2007.

Chapter 7 of section 2 of contains some details of the core, XML and SQL libraries.

The CA Clarity PPM XOG Developer Guide has chapters on GEL but the latest edition (for R13) omits most of the library details. Only the GEL, Core and SOAP libraries are listed. This seems to be a deliberate act of omission, but hopefully doesn’t presage deprecation of the missing ones.


The above non-CA references are fine as far as they go, but be aware that some libraries are unique to Clarity (eg GEL, BPM) and that some seemingly standard tags have been modified by CA to integrate them better with Clarity.

The indication for this is usually the presence of 'niku' in the path when including a library but its absence is no guarantee that the library is 100% standard.


GEL is a powerful and very flexible tool, but with flexibility comes discipline, and CA’s customisation policy is there for a reason.

Processes can extend Clarity’s business logic but should not replace it. Any process that updates the database using direct SQL calls will almost certainly be viewed as an unsupported customisation. The sole exception is where SQL is used to manipulate custom attributes or enforce business logic on them.

Stand-Alone Setup

Ensure you have the Java SDK installed and then download and unzip the XOG client to a convenient location on your hard drive. Avoid paths that have spaces in them (for example, do not install to ‘My Documents’ or similar).

When this is done open up a command prompt and navigate to the ‘bin’ directory and enter the ‘gel’ command. If all is working the usage information should be presented:

C:\>cd xog
C:\XOG>cd bin
Usage: gel [scriptFile] [-script scriptFile -o outputFile -Dsysprop=syspropval -validate]

GEL Scripting

Script Components

GEL Scripts consist of a set of tags that follow standard XML syntax.The tags are written as <library:tag-name> and </library:tag-name>, and what appears between them forms the tag body.

The opening and closing tags of any Clarity GEL script are always <gel:script> and </gel:script>. Between these two tags, other tags will define its logic.

A very simple example that outputs a message to the console would be the following:


<gel:out>This is an information message"~lt;/gel:out>

The xmlns lines indicate which tag libraries will be used in the script. It’s a bit like including header files (eg stdio.h) in a C program. The first line must contain the jelly:core library declaration. The next line indicates that we will be using tags from the GEL tag library in the script.

Tags may be nested (as shown above) and this allows quite complex scripts to be built.

Practice Example 3.1
Key in and execute the above script to confirm GEL is installed and working correctly.

Tag Libraries

The available tag libraries are listed, with examples, in the appendix. Some more esoteric ones are also available but their use is too specialised to be of general interest. If all else fails and something can’t be achieved using the available tags it is possible to create your own. Before doing that though, consider using the <core:new> tag. This allows any Java class and associated methods to be used in a GEL script.

Most libraries reside in the $NIKU_HOME/lib folder. They are included using an alias as shown in the above examples. Some other libraries are included using a URL. For example the SOAP Envelope tags are included using the following reference:


and the XOG tags are included using the following reference:


Apart from this difference the tags are invoked identically to any others.

One of the libraries unique to Clarity (GEL) includes tags from other libraries that have been rewritten to work better in a Clarity context. Unless there is an overriding reason, the GEL tags should be used rather than their synonyms from the other libraries.

So, use <gel:email> rather than <email:email> as it looks at Clarity’s setup to find the configured mail server. Similarly use <gel:setDataSource> rather than <sql:setDataSource> as it knows what data sources are configured.


It is recommended that a clear, consistent and unambiguous usage is adopted when including and using tags. For example the Core tags should be referenced as <core:xxx> even though the tag in question might be unique and could be used standalone simply as <xxx>.

The rest of this document will follow this convention.


The complete signature of each tag is shown using the attribute name and its type. For example trim=”boolean” indicates that the trim attribute takes values of true or false, var=”int” indicates that the var attribute takes a variable called “int”

Some attributes are common to several tags. Rather than list them every time they occur, these are listed here:

  • trim=”boolean” indicates that whitespace inside this tag should be trimmed or not. The default is true
  • escapeText=”boolean” indicates whether angle brackets (< and >) in the body of the tag should be converted to > and <. The default is true
  • var=”String” specifies the name of the variable to hold the tag’s result


Variables are instantiated at the point of use rather than being declared first and then assigned to later. Thus, the following assignment creates the variable myInteger and assigns it a value of 1.

<core:set var=”myInteger” value=”1”/>

To find the value store in myInteger we need to dereference the contents using the ${myInteger} construct. The following will record the value in the log:

<gel:log message=”myInteger value = ${myInteger}” level=”INFO”/>

Some tags do not require the contents of a variable but a reference to it, which is done using the $myInteger construct. Tags that consume XML strings (eg <gel:include>, <gel:set> ) are the main ones that use this method of passing variables into themselves.

So, when passing an XML string contained in variable xmlString into a SOAP call we use:

<gel:include select=”$xmlString”/>

Rather than:

<:gel:include select="${xmlString}"/>

The latter would most likely result in a null pointer exception

Tag Syntax

As is standard with XML, it is sometimes convenient to specify tags as open and sometimes as closed. The following are equivalent:

<gel:log level="INFO" message="This is an information message"/>


<gel:log level="INFO">This is an information message</gel:log>

Website © Clarity Consultants 2014