IvyScript

Introduction

The IvyScript language is used to write business rules, for manipulating process data, to define data mappings and to set properties and parameters on Rich Dialog components.

IvyScript Language

The Ivy scripting language IvyScript provides elements to write simple computational expressions but also more complex elements to program conditional-, loop- and exception handling blocks.

The IvyScript data types are defined for easy use. Especially, IvyScript bewares the programmer from null pointer exceptions because ivy data objects are automatically initialized to a default value. Read the section Null Handling for more details.

IvyScript can also directly manipulate Java objects in a easy way. Thus Java objects can be used without mapping and auto-casting simplifies the usage.

Language Elements

Conditions

Conditional expressions

Function style

IF (cond, ifExpr, elseExpr)

Java style

cond ? ifExpr : elseExpr

Conditional statements

if (cond) { ... } else { ... }

Loops

for

for (init; cond; increment) 
{ 
// do something here
 ... 
}

for (element: list)
 // do something here
... 
}

while

while (cond)
{
 // do something here
... 
}

Exception Handling

IvyScript supports the try/catch/finally construct to handle exceptions that happen while executing external Java code.

try 
{
// some code here
... 
} 
catch (Exception ex) 
{
// compensate code
... 
} 
finally 
{ 
// some code that is executed regardless of whether exceptions occurred 
... 
}

Null handling / Automatic object creation

IvyScript supports auto-initialization of the ivy basic types, i.e. you don't have to create/initialize fields or variables explicitly with new after declaration. Strings are initialised to an empty String, Numbers to zero, Lists to an empty List.

Ivy composite types (ivy Data Classes) are automatically created. Due to that automatic object creation, a null check expression like if(in.customer == null) is always false.

You can to use the .# operator to suppress the automatic object creation.

if( in.#customer == null)
{
  // object is null
}

if (in.#customer is initialized)
{
  // object is not null or has been set to a non-default value
}

Note

Any fields or variables of Java classes are also created automatically if they're referenced for the first time and if the type has a default constructor. Interface types and abstract class types are not auto-created because no instances can be created of such types in Java.

Note

Inside IvyScript it is generally recommended to use is initialized rather than comparing against null with the == operator. Because Java types may be null and IvyScript base types never, this operator will always ensure the correct checking depending on the type of the tested object.

Axon.ivy also supports auto-initialization of AXIS types:

org.apache.axis.types.Time to '00:00:00'

org.apache.axis2.databinding.types.Time to '00:00:00'

org.apache.axis.types.Duration to 'PT0S'

org.apache.axis2.databinding.types.Duration to 'PT0S'

A java.util.Date is auto-initialized to a default value of '0001-01-01 00:00:00'.

However, you do not have to compare the values of those types against hard coded default values in your code, simply use is initialized to find out if a value has been changed by the user or still bears the default value.

if (webserviceData.caseDuration is initialized)
{
  // do something
   ... 
}

IvyScript Editor

Overview

There exist two flavours of an IvyScript editor, a yellow editor for coding IvyScript and a blue editor for writing plain text that contains macros (this means, that you can mix IvyScript with normal text).

Figure 4.1. Standard IvyScript Editor

The yellow editors expect you to enter either a script with multiple statements (e.g. a script, that contains semicolons) which performs a certain task, or just an expression that evaluates to a certain value. Which is expected, should be clear by the context.

Figure 4.2. IvyScript Editor for macros

Features

Content Assist

Content Assist is invoked by pressing CTRL+SPACE at any point of editing a script. Content assist will open a popup, displaying proposals that are available in the current context, from which you may then select a suitable option. The selected proposal is inserted into the editor. You can get proposals for functions, types, packages, variables and methods and after the keyword "new" you also get a list of constructor proposals.

Example 1: When you would like to have displayed a list with all proposals that match with an already entered "c", you just enter "c" and press CTRL+SPACE. You will then get a list with proposals of functions, types and packages, each displayed with a help text if available.

Figure 4.3. Content assist in action

Example 2: The constructor proposal list just appears after the keyword new. So you could create a new date:Data d = new and press CTRL+SPACE after typing "new" and you get a list of possible constructors to create a new date.

Figure 4.4. Constructor proposals

Example 3: Similar to types, you can also get proposals for packages.

Figure 4.5. Package proposals

Tip

When the content assistant is opened and you press CTRL+SPACE again, the visibility level of the proposals is cycled. There are three different levels: Novice, Advanced and Expert. Depending on the visibility level, you get to see more or less proposals.

Parameter hopping

Another special feature is parameter hopping. When you insert a constructor or a method that has parameters, the first parameter is selected. When you now press the Tab key, then the next parameter gets selected. This way you may edit one parameter after another and simply jump to the next one when you're finished. After the last parameter was selected, the first is selected again. When you have finished, you can press Enter and the cursor jumps to the end of the inserted method or constructor.

Figure 4.6. Parameter hopping: After insertion of proposal first parameter is selected

Shortcuts

Shortcut	Action
CTRL+SPACE	Opens content assistant, when pressing again, the visibility of the content assistant is cycled.
F2	When pressing F2 in an editor, a bigger editor is opened in an own Dialog.
ESC	Inside an editor that was opened with F2, this closes the dialog and stores the entered text in the editor from where the F2 editor was opened.
CTRL+Z	Undo
CTRL+Y	Redo

Table 4.1. Available Shortcuts inside the IvyScript (and Macro) Editor

Smart Buttons

Figure 4.7. Smart Buttons

Next to the editors you usually find buttons (which ones, depends on the context), that hold certain actions. The exact actions that those buttons realize are described in the section Smart Buttons. There are e.g. actions to select an attribute from the current process data, to select content or to insert a link.

Figure 4.8. Macro Editor after insertion of a CMS object with help of the Content Smart Button

Browsers

Attribute and Method Browser

This browser is used to construct and insert IvyScript expressions for IvyScript text fields or areas in inscription masks. Those expressions are based on the process data in the context of the current step.

Figure 4.9. The Attribute and Method Browser

In the upper left area, you can choose between the different process attributes in the current context (such as in, out, param, result or panel). Depending on the selection, you can add a corresponding method to the expression in the upper right area and the help area displays information to the selected attribute/method. The constructed expression can be previewed in the insert text box at the bottom and be inserted into the inscription mask by clicking on the button insert.

Tip

By default only the most common attributes/methods are displayed. With the visibility_level button you can relax this filter in two steps. The same may be configured permanently in the Axon.ivy Designer IvyScript preferences.

Function Browser

This browser is used to construct and insert IvyScript expressions for IvyScript text fields or areas in inscription masks. Those expressions are based on the environment in the context of the current process or on general-purpose functions.

Figure 4.10. The Function Browser

In the upper left area, you can choose between the different attributes of the different environment variables in the current context. You can add a corresponding method to the expression in the upper right area and the help area displays information to the selected attribute/method.

A description of the accessible objects can be found in the section ivy environment variables

The constructed expression can be previewed in the insert text box at the bottom and be inserted into the inscription mask by clicking on the button insert.

Tip

Data Type Browser

The data type browser is used to choose a data type in the:

Data types are divided into two categories:

Figure 4.11. Ivy Base Types

This category contains the Axon.ivy base types. These types may be used within IvyScript without any restriction. Note that for convenience reasons database Record and Recordset, XML, Tree and List types are supported out of the box.

Selecting List<?> will bring up another data type browser where you specify the type of the list members.

Figure 4.12. All Other Types

Here you can find all other types that are available in your project. This includes all Data Classes that you have created, all classes that were generated from Web Services and all other Java classes that are on the build path.

Start typing the name of the desired type to get suggestions in the list. On the bottom, you may limit the suggestions to only custom Data Classes or Web Service classes.

Tip

In the filter, you can use * (any string) and ? (any character) as wild cards.

Tip

To switch between the tabs, use the shortcuts Alt+Left, Alt+Right or Ctrl+Shift+T.

To change the focus from the filter to the list, press the Tab or Arrow-Down key

Public API

For access within IvyScript a substantial portion of Axon.ivy functionality has been released as a Public API. You may use all classes and their objects in IvyScript fields.

IvyScript Reference

Operators

Operator Explanation Usage

Operator	Explanation	Usage
.	Field and method access of ivy objects	`in.customer.name` addresses the name attribute in the data structure `in.message.length()` calls the method length()
.#	Field access with suppressed auto initialisation	`in.#customer == null` null check of customer which is not initialised
as	Type cast operator	`in.anObject as Date` casts the object to a Date

Field and method access of ivy objects

in.customer.name addresses the name attribute in the data structure

in.message.length() calls the method length()

Field access with suppressed auto initialisation

in.#customer == null null check of customer which is not initialised

Type cast operator

in.anObject as Date casts the object to a Date

Table 4.2. IvyScript Field Access and Type Cast Operators

Operator	Explanation	Usage
>	greater than	`5 > 3` is true
<	less than	`5 < 3` is false
==	equals (Java equals)	`5 == 5` is true `"Hello" == "HELLO"` is false
!=	unequal	`7 != 2` is true
>=	greater than or equal	`7 >= 6` is true
<=	less than or equal	`2 <= 5` is true
&&	Boolean AND	`true && true` is true
\|\|	Boolean OR	`true \|\| false` is true
!	Boolean NOT	`! true` is false

Table 4.3. IvyScript Logic Operators

Operator	Explanation	Usage
+	Addition String Concatenation	`12.5+17.0` is 29.5 `"Hello "+"World"` is "Hello World"
-	Subtraction	`3020-12` is 3008
*	Multiplication	`2*4` is 8
/	Division	`7/2` is 3.5
%	Modulo Division	`7%2` is 1
**	Power	`2%5` is 32
++	Increment	`in.n++`
--	Decrement	`in.n--`
-	Negative Number value	`-9`

Table 4.4. IvyScript Arithmetic Operators

Ivy Script Data Types

Boolean

A boolean has the values true and false.

The IvyScript Boolean is based on the java.lang.Boolean but has a simplified class reference definition. Type conversion and format methods has been added while most other methods are hidden.

You can refer to the Java language documentation for a description of the methods of the data type Boolean.

Date

This class represents a date (without time of day).

Date constant objects are entered in the ISO 8601 format as 'yyyy-mm-dd' Where yyyy is for the year, mm for month and dd for day.

Accepted is also the format: 'dd.mm.yyyy'

new Date() returns the current date.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Date.

DateTime

An object of this class represents a Date with Time.

Constant DateTime objects are entered in the ISO 8601 format as 'yyyy-mm-dd hh:nn' or 'yyyy-mm-dd hh:nn:ss'. yyyy is for the year, mm for month, dd for day hh for hours, nn for minutes and ss for seconds.

Accepted is also the format: 'dd.mm.yyyy hh:nn or 'dd.mm.yyyy hh:nn:ss'

new DateTime() returns the current date and time.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type DateTime.

Time

An Object of this class represents a time of day.

Time constants are entered as 'hh:mm' or 'hh:mm:ss' Where hh is for hour, mm for minutes and ss for seconds

new Time() returns the current time.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Time

Duration

This data type is used for time periods.

You enter a duration in the ISO 8601 time period format such as: '12h20m' or '12h20m30s'

An example for the full format is: 'P3Y6M4DT12h30m10s'‘

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Duration

Number

IvyScript Numbers are Java Numbers. Number objects are integer or fixed-point numbers or floating point numbers.

Integer are entered as: 23 or -10

Fixed Point number are entered as: 0.1 or -123.57458

Floating point numbers are given with exponent: 1.2345E3 or 42.3234E-4

IvyScript Numbers java.lang.Number objects but has a simplified and extended class reference definition. Format methods has been added for convenience.

You can refer to the Java language documentation for a description of the methods of the data type Number

String

String objects represent character strings.

You enter a String literal in double quotes: "Hello John"

Strings can be concatenated with the + operator: "Hello "+"John"

The IvyScript Strings are java.lang.String objects but has a simplified and extended class reference definition. Conversion and format methods has been added for convenience.

You can refer to the Java language documentation for a description of the methods of the data type String

Record

Usually Records are obtained in the context of data base queries, where they represent a row in a table. Record objects are similar to a List where each element has an assigned field name.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Record

Recordset

A Recordset may be the result of a database query representing part of a table.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Recordset

XML

This class is used for the processing of XML documents. You can create XML Documents or apply XPath expression to filter and extract values.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Xml

Tree

This data type holds the data for a tree. A tree is a hierarchy of nodes and sub nodes. A node in the tree contains a value object and an info string and might have any number of attached children sub nodes.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Tree

Binary

A Binary object is a wrapper object for a byte array.

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type Binary

List

List objects can contain any number of other objects of any type. Each object in a list has an index which starts at zero.

Examples are: [1,2,3] a list with three numbers

[1,"Red",2,"Green",3,"Blue"] a list with different objects.

Beside this general list type, so called typed list exists. A typed list can only contain objects of certain type.

Those list types are written as follows: List<aClass>

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type List

File

A File object can be used to read/write temporary or persistent data. IvyScript Files are created in a confined area that belongs to the running application. Temporary files are created in a session-specific file area and are automatically deleted if a session ends. Temporary Files can be made persistent.

IvyScript Files are always addressed relatively, i.e. absolute addressing will lead to errors. You can create folders and files, i.e. a hierarchical structure, but you can not navigate outside the confined area (which is also the reason why absolute File paths are disallowed).

Read the Axon.ivy API Java Doc for the constructors and method summary of the data type File

Tip

You can always use java.io.File as an alternative to the IvyScript File object. However, in this case you must always use the Java File fully qualified, i.e. you can not import the class. Any IvyScript File can be transformed into a Java File (e.g. if needed to pass as parameter to a Java method).

The Environment Variable `ivy`

The ivy environment variable is provided to access the context of the current process, especially the workflow environment objects, the content management system and the Rich Dialog or HTML dialog contexts. The environment information is available as fields on the global ivy variable, e.g. to access the CMS of the current project you use:

String okMessage = ivy.cms.co("/text/messages/ok");

Note

Access from IvyScript:

The variable ivy is available everywhere, where IvyScript can be used, e.g. on Step elements or in output tables of other elements.

Access from Java:

You can also access ivy from a Java context, e.g. from helper classes or on a Rich Dialog panel implementation. To do so, simply import the ch.ivyteam.ivy.environment.Ivy class and use it's static API.

Please note that it is necessary that the Java code which makes use of the ivy context variable must run within an Ivy request. Otherwise context information will not be available, most likely resulting in an EnvironmentNotAvailableException.

Access from JSP:

The ivy variable is also accessible from JSP. You can import the class ch.ivyteam.ivy.page.engine.jsp.IvyJSP and declare the variable ivy in your JSP as follows:

<%@ page import="ch.ivyteam.ivy.page.engine.jsp.IvyJSP"%>
<jsp:useBean id="ivy" class="ch.ivyteam.ivy.page.engine.jsp.IvyJSP" scope="session"/>

The following environment objects are available on ivy (details of the objects are described in the Public API):

cal - an IDefaultBusinessCalendar object that gives access to business calendar informations and calculations.
request - an IProcessModelVersionRequest object, the representation of the request against the server to execute the current step
response - an IResponse object, the response of the Axon.ivy Engine on the request to execute the most current step
wf - an IWorkflowContext object giving access to all workflow objects (all tasks, all cases) of all users for the application under execution. Can be used to build a whole workflow administration UI application, find tasks, cases, do statistics, etc. There is a workflow context for each application and vice versa.
session - an IWorkflowSession object gives access to all workflow objects (task and cases) that belongs to the user of the current session. A workflow object belongs to a user if:
- A task is assigned to him or a role he owns.
- A task he is currently working on.
- A task he worked on in the past (needs permission).
- A task that a member of a role he owns has worked on in the past (needs permission).
- A case he has started (needs permission).
- A case that have been started by a member of a role he owns (needs permission),
- A case that has a task which he worked on (needs permission).
- A case that has a task which a member of a role he owns has worked on in the past (needs permission).
task - an ITask object, the representation of the user's current work unit in the process under execution.
case - an ICase instance that represents the current process under execution
cms - a IContentManagmentSystem object representing the CMS used in this project.
html - a IHtmlDialogContext object specifies the Axon.ivy HTML environment
rd - a IRichDialogContext instance allowing access to the context of the displayed Rich Dialog
log - a Logger object. You can define log outputs here that will be collected for each run. You can see these log entries in the Runtime Log view.
extensions - a IExtensions instance allowing access to Axon.ivy extensions
datacache - the reference to the IDataCacheContext instances for the application and session (see Data Cache for more information)
persistence - references to the existing persistence units in this application (see Persistence Configuration Editor and Persistence API for more information about the API of the Persistence)
var - references to the global variables that are defined for this application (see Data Global Variable for more information)
rules - references to the rule engine integration within Axon.ivy.

Note

The rd object is only available within a Rich Dialog logic step and the html object is only available within a business process.

IvyScript-Java Integration

Call Java methods and fields

You can easily write own Java classes and use it directly in IvyScript. You can call static methods and fields from Java classes (e.g. java.lang.Math). You have to address the class with the qualified name or use import statements. If a Java method has no return parameter (void) then the called object of the method is returned (e.g. a call to user.setName(...) returns object user).

import java.lang.Math;

Number r = Math.random();
Number pi = Math.PI;

out.n= r*pi;

Working with different Date, Time and DateTime implementations

When working with Databases and Web Services in Axon.ivy, then different implementations of Date, Time and combined Date-Time information are encountered (e.g. java.util.Date, java.sql.Date, Axis Time, etc). To complicate matters further, some of those implementations are - for historical reasons - mutable (e.g. java.util.Date) which is from todays' perspective an unwelcome behavior. This has been remedied by some other implementations.

To facilitate working with values of those different types, IvyScript will always convert them to the corresponding, immutable IvyScript base types whenever such values are encountered, according to the following table:

Java type	Ivy type
Axis1 `Time`	Ivy `Time`
Axis2 `Time`	Ivy `Time`
Axis1 `Duration`	Ivy `Duration`
Axis2 `Duration`	Ivy `Duration`
JDBC (SQL) `Timestamp`	Ivy `DateTime`
JDBC (SQL) `Date`	Ivy `Date`
JDBC (SQL) `Time`	Ivy `Time`
Java `Date`	Ivy `DateTime`

Table 4.5. Automatic conversion of foreign Date / Time values

The automatic conversion into IvyScript types takes place transparently. The developer should therefore only think in terms of the IvyScript Date / Time types. No explicit conversion has to be made, neither when reading nor when writing those types.

Warning

As a general rule, do not create any variables or objects of foreign (i.e. Java) Date / Time types inside IvyScript . Although a statement such as

java.util.Date myDate = new java.util.Date();

is valid and permitted in IvyScript, the actual type of the myDate object will aways be IvyScript DateTime, due to the auto-conversion. This can lead to confusion.

When trying to find out if date or time values are null or not initialized, developers should always use the is initialized operator rather than testing against null:

// recommended style
if (person.birthday is initialized) ...
if (in.lunchTime is initialized) ...
if (schedule.appointment is initialized) ...

// unsafe style, not recommended
if (person.birthday != null) ...
if (in.lunchTime != null) ...
if (schedule.appointment != null) ...

Auto casting rules

IvyScript supports auto casting between the most important Java types and IvyScript types. This means, that you no longer have to use the toXyz() methods on your IvyScript values. Instead you can directly assign IvyScript types to Java types and vice versa. This also holds for lists (IvyScript) and arrays (Java).

The following auto-casting rules are supported by IvyScript (bidirectional):

Java type		Ivy type
Axis1 `Time`	<->	Ivy `Time`
Axis2 `Time`	<->	Ivy `Time`
Axis1 `Duration`	<->	Ivy `Duration`
Axis2 `Duration`	<->	Ivy `Duration`
JDBC (SQL) `Timestamp`	<->	Ivy `DateTime`
JDBC (SQL) `Date`	<->	Ivy `Date`
JDBC (SQL) `Time`	<->	Ivy `Time`
Java `Date`	<->	Ivy `DateTime`
Java `Date`	<->	Ivy `Date`
Java `Date`	<->	Ivy `Time`
`byte[]`	<->	Ivy `Binary`
`aType[]`	<->	Ivy `List<aType>>`

Table 4.6. Auto casting rules

IvyScript

Introduction

IvyScript Language

Language Elements

Conditions

Loops

Exception Handling

Null handling / Automatic object creation

Note

Note

IvyScript Editor

Overview

Features

Content Assist

Tip

Parameter hopping

Shortcuts

Smart Buttons

Browsers

Attribute and Method Browser

Tip

Function Browser

Tip

Data Type Browser

Tip

Tip

Public API

IvyScript Reference

Operators

Ivy Script Data Types

Boolean

Date

DateTime

Time

Duration

Number

String

Record

Recordset

XML

Tree

Binary

List

File

Tip

The Environment Variable ivy

Note

Note

IvyScript-Java Integration

Call Java methods and fields

Working with different Date, Time and DateTime implementations

Warning

Auto casting rules

The Environment Variable `ivy`