GEL Basics

ccppmop1571
Learn here about GEL Basics; including the basic structure for a GEL script, GEL script tags, GEL conditionals and loops, GEL variables, GEL built-in parameters, GEL considerations, using SSL with GEL, and GEL tag restrictions.
GEL Script Structure
The following image shows the basic structure for a GEL script.
 
This image illustrates a basic GEL script with header, footer, and a comment
You can add a comment anywhere in a GEL script by using the structure <!-- comment -->.
GEL Script Tags
A GEL script is an executable XML file that is built from qualified elements that are bound to Java code named tags. Using namespace declarations, tags are organized into tag libraries which are made available in a script. In this Hello World example, two tag libraries are defined for the script: Core and GELTagLibrary as seen in tag pairs such as: <core:???></core:???> and <gel:???></gel:???>.
A script always resides within the GEL script tag.
Hello World Example
<gel:script xmlns:core="jelly:core" xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <core:forEach indexVar='i' begin='1' end='3'> <gel:out>Hello World ${i}!</gel:out> </core:forEach> </gel:script>
Variables are used extensively throughout GEL scripts. Many tags can set variables. An example of a tag that can set variables is core:set. You can use the common syntax ${variable_name} to reference variables. In the Hello World example, 'i' is a variable which is set by the forEach tag and is incremented with each loop. Core is a built-in Jelly library that contains general-purpose tags (such as forEach that is used in the previous example). GELTagLibrary is the primary GEL library; and it contains general-purpose tags that are not found in core and tags that are particular to 
Clarity PPM
.
GEL Conditionals and Loops
GEL contains the following tags for performing conditional processing:
  • <core:if>
    <core:if test="${hasDocs}"> ... </core:if>
  • <core:choose>
    <core:choose> <core:when test="${row[6].equals(&#34;&#34;)}"> ... </core:when> <core:otherwise> ... </core:otherwise> </core:choose>
  • <core:switch>
    <core:switch on="${caseType}"> <core:case fallThru="true" value="Incident"/> <core:case value="Problem"> ... </core:case> <core:case fallThru="true" value="Question"/> <core:default> ... </core:default> </core:switch>
  • <core:forEach>
    <core:forEach trim="true" items="${queryResult.rowsByIndex}" var="row"> ... </core:forEach>
GEL Variables
Variables in GEL scripts are declared at the time of use. There are no declaration blocks, like the ones you may find in other languages. GEL provides the following ways to store a variable value:
  • <gel:parameter>
    This tag allows values to be passed into a GEL script from a 
    Clarity PPM
     process. Inside the GEL script, you can refer to the parameter as you would with any other variable (that is, using the ${variablename} syntax). The optional attribute secure="true" causes 
    Clarity PPM
     to hide the actual value in the user interface with asterisks (*).
    <gel:parameter var="XOGUsername" default="admin"/> <gel:parameter var="XOGPassword" default="password" secure="true"/>
  • <core:set>
    This tag is used to set basic variables; that is, ones that do not need to be extracted from an XML document. Refer to the variable using the ${variablename} syntax.
    <core:set value="1" var="yes"/> <gel:out>${yes}</gel:out>
    You can do some basic math on the variable:
    <gel:out>${yes+2}</gel:out>
  • <gel:set>
    This tag is necessary to extract the value of the variable from an XML document. This tag differs from the <core:set> tag in that it takes a select attribute which in turn requires an XPath statement. If you are unfamiliar with XPath, think of it as a hierarchy mapping of the XML document. In this example, the select statement points the way to the Statistics node of a XOG output file.
    <gel:set asString="false" select="$XOGresult/SOAP-ENV:Envelope/SOAP-ENV:Body/NikuDataBus/XOGOutput/Statistics" var="stats"/>
  • <gel:persist>
    This tag allows you to set variables with a scope that extends beyond the current script.
  • <gel:parse>
    This tag is used to create an XML document in memory, and this is how you build XOG requests. The tag can be used to generate an XML document, or specific nodes that can later be attached into an existing XML document.
    <gel:parse var="loadContent"> <NikuDataBus xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:noNamespaceSchemaLocation="../xsd/nikuxog_resource.xsd"> <Header version="12.0.0.5028" action="write" objectType="resource" externalSource="ORACLE-FINANCIAL"/> <Resources> <Resource resourceId="abc" isActive="true"> <PersonalInformation lastName="doe" firstName="john" emailAddress="[email protected]"/> </Resource> </Resources> </NikuDataBus> </gel:parse>
GEL Built-in Parameters
Custom Action GEL scripts that are associated with processes have the following parameters available to them:
  • Object instance ID
    If no object is associated with the process, the ID is -1. Otherwise, the ${gel_objectInstanceId} parameter contains the object instance ID.
  • Process ID
    ${gel_processId} is the process identifier; all instances of this process share this identifier.
  • Process instance ID
    ${gel_processInstanceId} is the process instance identifier; all instances have a unique value.
All built-in parameters have a "gel_" prefix and are of data type - numeric.
GEL Considerations
Consider this information when working with GEL:
  • GEL is case-sensitive. This statement includes variable names.
  • All GEL scripts are contained in XML. Therefore, all XML rules apply to structure, tags, and special characters.
  • In the Jelly <sql:query> tag, you cannot use the
    less than
    (<) and
    greater than
    (>) operators. Use BETWEEN instead of these operators or escape the special characters using &lt; or &gt;.
Using SSL with GEL
When interacting with SOAP services in GEL, you may need to complete more steps when using the secure sockets layer (SSL) with web services. If the SSL certificate in use by the web service host has been issued by a well-known certificate authority (for example, Verisign or Thawte), no more steps are necessary, provided the appropriate certificate already exists in the
cacerts
keystore in the Java SDK that is running the GEL script.
However, you may need to complete more steps in these situations to ensure that the proper trust is established between the GEL script and web service host:
  • The SSL certificate is
    self-signed,
    which means you generated the certificate using your own certificate authority.
  • The expiration date on a certificate that is issued by a well-known certificate authority has been reached.
Set Up a Self-Signed SSL Certificate on a Web-Service Host
For this setup, identify the Java SDKs that will run the GEL scripts:
  • If GEL scripts are being run outside of the application using the XOG client, the first Java SDK that is listed in your PATH is the one that is running the scripts.
  • If GEL scripts are running inside a process in the application, typically the Java SDK that is running the BG service on the application server is the one that is running the scripts.
Complete these steps:
  1. Locate the Java SDK installation directory.
    For example, C:\jdk1.5.0_17.
  2. Export the SSL certificate or any updated certificate-authority certificate that you need to import to a file.
    For example, mycert.cer.
  3. Change directories to the Java SDK JRE security directory.
    cd c:\jdk1.5.0_17\jre\lib\security
    This directory is where the
    cacerts
    Java keystore resides. The keystore holds certificate-authority certificates that are used for establishing trust. The keystore password for this keystore is always
    changeit
    .
  4. Import your certificate into the
    cacerts
    keystore with the Java keytool command.
    keytool -keystore cacerts -storepass changeit -import -file c:\temp\mycert.cer -trustcacerts -alias mycert
    Assign the
    alias
    value to a value that is not currently in use in the keystore.
    You may be prompted if you want to trust this certificate. If so, answer Yes.
  5. If you are setting up the self-signed certificate for the BG service for GEL scripts that run in processes, restart the BG service.
    The keystore is loaded one time when the 
    Clarity PPM
     services are started.
GEL Tag Restrictions
To control the GEL tag restriction, use these commands:
  • admin general restrict-gel-tags
    . Sets the value of the gelTagRestriction property to 
    on
    .
  • admin general allow-gel-tags
    . Sets the value of the gelTagRestriction property to 
    off
    .
The property gelTagRestriction is referenced to determine whether gel tags are restricted. The property is on the system element. The element is optional. Use the values 
on
 or 
off 
to set GEL tag restrictions for the environment. Specifying any value other than 
off
 enables the GEL tag restriction. GEL tag restrictions are off by default.
Altering GEL tag restrictions requires that you restart the app and bg services.
Examples
Properties.xml file with no GEL tag restriction:
<system online="true" multiCurrency="false" licenseTypes="old" singleTenantMode="true"/>
or
<system online="true" multiCurrency="false" licenseTypes="old" singleTenantMode="true" gelTagRestriction="off"/>
Properties.xml file with GEL tags restricted:
<system online="true" multiCurrency="false" licenseTypes="old" singleTenantMode="false" gelTagRestriction="on"/>