XOG GEL Tag Library

ccppmop1591
Every GEL tag is associated with a tag library. The GEL Tag library on this page is a collection of general-purpose, frequently-used tags for XML manipulation. These tags also handle variables, expressions, logging, and JDBC datasources for 
Classic PPM
.
The following XOG GEL libraries are also available:
To use the GEL tag library, include the following namespace declaration in your script.
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary">
XOG GEL Tag Library:
gel:script - Defining GEL Scripts
gel:script is the root element for all GEL scripts.
This element is the core:jelly:
  • escapeText
    Values:
    • true. The tag body is escaped (interpreted as text).
    • false. The body is interpreted as XML.
    Default:
    true
    Type:
    Boolean
  • trim
    Values:
    • true. The white space inside this tag is trimmed.
    • false. The white space is not trimmed.
    Default:
    true
    Type:
    Boolean
gel:parse Parsing XML
gel:parse generates an XML document in memory from a file, InputStream (obtained with ftp:get tag), or from GEL script content.
Using other get tags, you can:
  • Save the output.
  • Generate an XML document from an InputStream.
  • Generate an XML document from GEL script content.
This tag has the following attributes:
  • file
    Optional. The file to read. Specify the input path and file name or the InputStream from the ftp:get tag. If this attribute is not set, the content of this tag is used.
    Type:
    File or InputStream
  • var
    Required. The name of the variable that contains the XML document to be generated.
    Type:
    String
Example 1
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:parse var="xmldoc" file="e:\temp\BB1.xml"/>
Example 2
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:parse var="xmldoc"> <groups> <group code="CTU">CTU Team</group> <group code="DS23">SWAT Team</group> </groups> </gel:parse> </gel:script>
gel:set Setting XML Document Values
After you use gel:parse or soap:invoke and have an XML node or document, you can use gel:set to retrieve certain element content or attributes and set the value to a variable. You can also use gel:set to change content (including text and attributes) or add an element with its full structure as a child into another element.
Example
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <!-- point A --> <gel:parse var="groups"> <groups> <group code="DS23">SWAT Team</group> </groups> </gel:parse> <!-- point B --> <gel:set select="$groups/groups/group" var="groupNode"/> <!-- point C --> <gel:set select="$groupNode/@code" var="code" asString="true"/> <!-- point D --> <gel:set value="${groupNode}" select="$groups/groups" insert="true"/> <!-- point E --> <gel:set value="CTU Team" select="$groupNode/text()"/> <!-- point F --> <gel:set value="CTU" select="$groupNode/@code"/> <!-- point G --> <gel:set select="$groups/groups" var="x" asString="true"/> <gel:out>${x}</gel:out> </gel:script>
The GEL context contains these values:
  • Point A. An XML document, referred by groups, with the specified content. The root element is <groups> and has one <group> sub-element.
  • Point B. The document groups are not changed. An XML node, groupNode, is the first <group> element in the document groups.
  • Point C. A variable code is created with the content of the code attribute from the node
    groupNode
    (that is, DS23).
  • Point D. A new XML node with the content specified in the groupNode node is added to the <groups> element of groups. The groups now refer to an XML document whose root element is <groups> that has two sub-elements with the same content. The groupNode still refers to the first [set the product group or family] element.
    Example:
    Groups is the whole XML document, and groupNode is the element:
    <groups> <group code="DS23">SWAT Team</group> <group code="DS23">SWAT Team</group> </groups>
  • Point E. The text content of groupNode is changed to
    CTU Team
    because groupNode is an element within groups. Document is also changed.
  • Point F. The code attribute of groupNode is changed to
    CTU
    .
  • Point G. The entire XML structure is captured as text to the variable x.
When you print the document referred by groups, you see:
<?xml version="1.0" encoding="UTF-8"?> <groups> <group code="CTU">CTU Team</group> <group code="DS23">SWAT Team</group> </groups>
Retrieve XML Document Values
Use the attributes
var
and
select
to retrieve values from an XML document.
If the select refers to a non-existing path, no value setting is performed. If 
var
refers to a variable that is not set in another place, it will be null.
To retrieve the text content of a node:
<set var="..." select="$doc/.../node_name/text()" asString="true"/>.
To retrieve a certain attribute:
<set var="..." select="$doc/.../node_name/@attribute_name" asString="true"/>
To retrieve a node, including its sub-nodes:
<set var="..." select="$doc/.../node_name"/>.
Modify XML Document Values
Use the attributes
var
and
select
together to set values in an XML document. The
select
attribute must refer an existing path. If
select
= "$doc/group" and there is not an element that is named group in the document or node that is referred by doc, an exception is thrown. If
select
="$doc/group/text()" and the <_group> element does not contain text content, an exception is thrown.
If the node does not have text content, to set the text content of a node:
<set value="..." select="$doc/.../node_name"/> -or- <set value="..." select="$doc/.../node_name/text()"/>
If you reverse the previous two examples, you get an exception. This happens because a node does not have any child text but you referred to it with text(), or the item you tried to set will be appended to the previous text content.
If you are not sure if the node for which you want to set text content has text content already, it is best to retrieve its text value first and then use core:if to verify if it exists before proceeding.
To set the attribute value of node:
<set value="..." select="$doc/.../node_name/@attribute_name"/>.
To set a node into another document:
<set value="${node_var}" select="$doc/.../node_name"/>
You can use attribute insert if you are adding a node to a path or to have this node replace whatever is referred to by the path. This information describes the gel:set:
  • var
    Either var or value is required. The variable to export for the item being iterated over. The variable can be a string, a number, and so forth.
    Type:
    String
  • value
    Either var or value is required. If the value is a node, it is inserted into the position that is specified by select. Otherwise, the string value is set as the text content or attribute that is specified by select.
    Type:
    Object
  • select
    Required.
    The XPath expression to use to retrieve a value.
    Type:
    org.jaxen.XPath
  • asString
    Optional. If set to "true", the value that is specified by select is converted to a string and is saved into the variable referred to by var. If set to "false", the node that is specified by select is set to the variable referred by var.
    Default:
    false.
    Ignored when var is not set.
    Type:
    Boolean
  • insert
    Optional. If set to "true", the node referred to by value is inserted as a child node to the node specified by select. If set to "false", the node that is referred to by value is used to replace the node that is specified by select.
    Default:
    false. Ignored when value is not set, or set but not with a node value.
    Type:
    Boolean
gel:expr Evaluating Expressions
Use this tag to evaluate an expression as text. Most often the expression resolves to an XML element as illustrated in these examples.
Example 1
<gel:script xmlns:core="jelly:core" xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:parse var="group"> <group code="CTU">CTU Team</group> </gel:parse> <core:comment> The code is <gel:expr select="$group//@code"/> </core:comment> </gel:script>
Example 2
The previous example is equivalent to the following gel:set example:
<gel:script xmlns:core="jelly:core" xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:parse var="group"> <group code="CTU">CTU Team</group> </gel:parse> <gel:set var="code" select="$group//@code" asString="true"/> <core:comment> The code is ${code} </core:comment> </gel:script>
The following information describes gel:expr
  • select
    Required. The XPath expression to retrieve the value.
    Type:
    XPath
gel:parameter - Defining Parameters
Use this tag to define parameters that can be used in a GEL script.
Example
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:parameter var="hostname" default="http://localhost/niku/xog"/> <gel:parameter var="username" default="admin"/> <gel:parameter var="password" default="niku2000" secure="true"/> <gel:out>Host = ${hostname}</gel:out> <gel:out>User = ${username}</gel:out> </gel:script>
Use gel:parameter Instead of core:set
When a GEL script is executed from the console, there is no difference between using gel:parameter and core:set. When gel:parameter is executed as a process, all parameters that were defined using the <gel:parameter> tag appear with input boxes on the action definition page. You can enter a value for a parameter to override the default value in the script.
You should use gel:parameter for values that may be changed by process administrators (such as URL, hostname, username, and so forth.). In addition, use this parameter for values which should be kept discrete, like passwords. You can only define one parameter name at a time. For example, if you use logic such as "if a certain condition, log in as userA, otherwise userB," instead of defining "username" in two places, use this parameter to log in, define two properties "usernameA" and "usernameB", and then use the <core:set> tag to pick one of those two properties to set into a variable in the "if" block.
A parameter can be used later just like other variables (that is, ${var}). This information describes gel:parameter:
  • var
    Required. The parameter name.
    Type:
    String
  • default
    Optional. The parameter default value. Provide this value if you want the script to be executable from the console, even if this parameter is not secure.
    Type:
    Object
  • secure
    Required. Set this attribute to "true" if the parameter content should not be shown in plain text to process administrators.
    Default:
    false
    Type:
    Boolean
gel:getDocument Requesting XML Documents
A process can be invoked in these ways:
  • Manually.
  • Invoked by a job scheduler.
  • Invoked by a request on the web service around the process engine.
When a process is invoked as a web service, the request is an XML document. You can use this tag to get that document, find what needs to be done, and then perform actions accordingly. If an XML document is set using the gel:setDocument tag in one step of a process, you can use this tag to retrieve the document a later step of the same process.
  • var
    Required. The name of an XML document variable which was set in the previous step of the same process. If this step is the first step, this variable is the body of the SOAP request that is sent to the process engine web service.
    Type:
    String
gel:setDocument Passing XML Documents
Use this tag to pass an XML document that was generated in one step of a process to the next step. You can write the processing logic in separate steps. For example, you can invoke one web service, save the response in a step, and then retrieve it and use it to invoke XOG in another step.
  • var
    Required. The name of an XML document variable to pass to the next step in the same process.
    Type:
    String
gel:persist Persisting Variables
When you set a variable in a GEL script, you can only use it when executing that script. Sometimes when the GEL script is executed in a process engine, you must share a value in other scopes such as:
  • Globally among all process GEL scripts.
  • Only with GEL scripts in a certain process within all process executions (such as a single variable that stores the time a
    Remedy Clarity Incident Sync
    process was most recently launched).
  • Only with GEL scripts in different steps of a process during one process execution.
  • Use <gel:persist> to achieve variable value sharing. Once a value is persisted, you can use it directly in proper scripts without defining any special tags. For example, after <gel:persist var="hostname" value="localhost" scope="INSTANCE"/> is processed, you can refer to ${hostname} directly in any GEL script of this process during this process execution.
You can access a persisted value with a PROCESS scope using scripts from that process (even if the process, its steps, and GEL scripts change). If a process is deleted and then recreated, it is considered to be a new process. All values that are persisted before with PROCESS scope are not available to the new process, even if the new process has the same process name, code, or steps as the deleted one.
  • var
    Required. The variable to be persisted.
    Type:
    String
  • value
    Optional. The value of the variable. Must be a string; formatted date strings are acceptable. When this attribute is not set, the tag content is used as the value to be persisted. If the value being persisted contains special characters, such as a new line, do not use this attribute, use the text content instead.
    Maximum Length:
    4000 characters. Longer strings are truncated.
    Type:
    String
  • scope
    Required. Specifies the scope of the variable.
    Values:
    • GLOBAL. Set once, use it anywhere.
    • PROCESS. Set once, use it anywhere in the same process.
    • INSTANCE. Set once, use it anywhere in the same process during the current execution.
    Type:
    String
Example
The following example persists the 
Classic PPM
 built-in variables
gel_objectInstanceId
and
gel_processInstanceId
throughout this process instance as
myObjectId
and
myProcessId.
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:persist var="myObjectId" value="${gel_objectInstanceId}" scope="INSTANCE"/> <gel:persist var="myProcessId value="${gel_processInstanceId}" scope="INSTANCE"/> </gel:script>
gel:notify Sending Notifications
Use this tag to send email. The email content is the text content of this tag, followed by process messages that are logged so far during the current process. Email server information is derived from the properties.xml file of the installation.
  • from
    Required. The email address of the sender.
    Type:
    String
  • fromName
    Optional. The name of the sender.
    Type:
    String
  • to
    Required. The email addresses of the recipient (delimited by commas, semicolons, or spaces).
    Type:
    String
  • subject
    The email subject.
    Type:
    String
  • level
    Optional. Here are the valid entries:
    • WARNING. The email is sent only if there are warning or error messages.
    • ERROR. The email is sent only if there are error messages. Only error messages are included in the message.
    If this attribute is not specified, an email is sent no matter how many log messages are retrieved. All process messages that are logged so far are included.
    Type:
    String
Example
This example sends a notification if an error had been logged with <gel:log>:
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:notify from="[email protected]" fromName="Clarity Admin" to="[email protected] " subject="There was a process error" level="ERROR"> A process error was received. </gel:notify> </gel:script>
gel:email Sending Email Messages
Use this tag to send an email. The email content is the text content of this tag. Email server information is derived from the properties.xml of the installation.
  • from
    Required. The email address of the sender.
    Type:
    String
  • fromName
    Optional. The name of the sender.
    Type:
    String
  • to
    Required. The email addresses of the recipient (delimited by commas, semicolons, or spaces).
    Type:
    String
  • subject
    Required. The email subject.
    Type:
    String
Example
This example sends a simple email:
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:email from="[email protected]" fromName="Clarity Admin" to="[email protected] " subject="Simple email"> Hello World. </gel:email> </gel:script>
gel:formatDate Formatting Time Strings
This tag provides a formatted time string which you can use as a part of a file name, appended to a comment line, or inserted into a database.
<gel:out>Hello World! Now it is <gel:formatDate format=" h 'o''clock' a, zzzz, d MMM yyyy"/>.</gel:out>
The previous example generates this output:
Hello World! Now it is 4 o'clock PM, Pacific Standard Time, 24 Mar 2005.
This tag has the following attributes:
  • format
    Optional. Specifies how time displays in java.text.SimpleDateFormat format. For more information about this format, search the Oracle website.
    Default:
    yyyy-MM-dd HH:mm:ss
    Type:
    String
  • stringVar
    Optional. This variable refers a formatted date string. If this attribute is not set, the formatted string is used in the content of this tag's parent element.
    Type:
    String
  • dateVar
    Optional. The variable, of type java.util.Date, referred to by this name is formatted as a string. If this attribute is not set, the current time is used.
    Type:
    String
Example 1
This example formats the current date and time into the format the XOG requires for investment start/finish dates.
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:out> <gel:formatDate format="yyyy-MM-dd'T'HH:mm:ss"/> </gel:out> </gel:script>
Example 2
This example formats the specified date and time into the format the XOG requires for investment start/finish dates. Notice the use of the Java class java.util.Date and the <core:new>, <core:invoke> and <core:arg> tags.
<gel:script xmlns:core="jelly:core" xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <core:new className="java.util.Date" var="date"/> <core:invoke on="${date}" method="parse"> <core:arg value="2009/03/27"/> </core:invoke> <gel:out> <gel:formatDate format="yyyy-MM-dd'T'HH:mm:ss" dateVar="date"/> </gel:out> </gel:script>
gel:parseDate Parsing Time Strings
This tag takes a formatted string and generates a date instance. This tag uses the following attributes:
  • format
    Optional. Indicates how the string is formatted in java.text.SimpleDateFormat format. For more information about this format, search the Oracle website.
    Default:
    yyyy-MM-dd HH:mm:ss
    Type:
    String
  • stringVar
    Optional. This variable refers to the string to be parsed. If the string does not have the format that is specified by the format attribute, a parsing exception is thrown.
    If this attribute is not set, the text content of this tag is used as the string.
    Type:
    String
  • dateVar
    Required. The parsed date is stored as a java.util.Date and referred to by this variable name.
    Type:
    String
Example
This example parses a date from a string, and then formats that date using <gel:formatDate>.
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:parseDate dateVar="date" format="yyyy-MM-dd">2009-03-27</gel:parseDate> <gel:out> My date was: <gel:formatDate format="yyyy-MM-dd'T'HH:mm:ss" dateVar="date"/> </gel:out> </gel:script>
gel:setDataSource Specifying Data Sources
Use this tag to identify the 
Classic PPM
 database.
<gel:setDataSource dbId="niku"/>
When you access the 
Classic PPM
 database, you only need to know its database ID. You do not need to provide other access information such as username.
This tag uses the following attribute:
  • dbId
    Required. The database ID.
    Type:
    String
gel:nsqlQuery Executing NSQL Queries
Use this tag to execute an existing NSQL query, or define a new ad-hoc query to retrieve data from the database, storing the results to the specified variable.
Examples
<gel:setDataSource dbId="niku" var="dataSource"/> <gel:nsqlQuery queryId="usercountbylicensetype" var="resultSet"> <gel:nsqlParameter name="license_wildcard" value="*"/> </gel:nsqlQuery> <core:forEach items="${resultSet}" var="row"> <gel:out>Row Contents: '${row}'.</gel:out> </core:forEach> <gel:nsqlQuery var="resultSet"> <![CDATA[ SELECT   @SELECT:U.USER_NAME:[email protected], @SELECT:U.ID:[email protected] FROM CMN_SEC_USERS U WHERE @[email protected] ]] > <gel:nsqlParameter name="user_name_wildcard" value="admin*"/> </gel:nsqlQuery> <core:forEach items="${resultSet}" var="row"> <gel:out>Row Contents: '${row}'.</gel:out> </core:forEach>
gel:log Logging Messages
Use this tag to insert status messages into the process engine log table.
<gel:script xmlns:gel="jelly:com.niku.union.gel.GELTagLibrary"> <gel:log level="warn" category="Employee Data" message="No record returned."/> </gel:script>
This tag logs messages as a process message in the BPM_ERRORS table when this script runs as a custom step in a process. If the process is running from the console, the message is inserted into the standard log file.
  • message
    Optional. The message to log. The message can be set as a value attribute or as the content of this tag.
    Type:
    String
  • category
    Optional. Use to distinguish logs; can be concatenated from business data type, file name, developer ID, and so forth.
    Type:
    String
  • level
    Optional. The warning level. The following values are supported:
    • DEBUG
    • ERROR
    • FATAL
    • INFO
    • WARN
    This attribute is not case-sensitive. For example, WARN, warn, and Warn are the same.
    A process message has only three levels: INFO, WARNING, and ERROR, while a logger message in the log file can have all levels. When a message is logged as a process message, DEBUG and INFO messages are logged as INFO messages, WARN messages are logged as WARNING messages, and ERROR and FATAL messages are logged as ERROR messages.
    Default:
    INFO
    Type:
    Level
  • var
    Optional. A variable name into which the log message should be stored. Use when you want to save log messages for other purposes such as sending emails.
    If the variable is:
    • Not set. A StringBuffer is created for storing the message; it can later be referred to using this variable name.
    • Already a StringBuffer. The StringBuffer is  appended to the log message.
    • A string. A StringBuffer is created for storing the string referred to by this variable followed by the log message. It can later be referred to using this variable name.
    Type:
    String
gel:out Printing to the Console
This tag prints the content of this tag to the system console. This tag does not have any attributes. Use this tag only when you are using the console to debug and the GEL script is not running as a process. For example:
<core:set var="x" value="file.rows[2][3]"/> <gel:out>${x}</gel:out>
If you have a variable that contains an XML Node, including an XML document and you want to print it, combine gel:out with gel:expr:
<gel:parse var="doc"> <groups>...</groups> </gel:parse> <gel:out><gel:expr select="$doc/groups"/></gel:out>