25 Writing BPM Scripts

This chapter describes how to use BPM scripting to access and modify the data objects in a BPM Project

This chapter includes the following sections:

• Introduction to BPM Scripting

• Introduction to the BPM Code Editor

• Introduction to the Scripting Catalog

• Importing Custom Libraries

• Working with the Elements of a BPM Project

• Importing Business Objects from the Business Catalog

• Predefined Variables

• Implementing Script Tasks

• Type Description Mapping for XML Schema Types

25.1 Introduction to BPM Scripting

Oracle BPM supports Groovy 2.1 compiler and runtime (with static compilation enabled) as a scripting language.

Scripting is available in the following contexts:

• Script task

  See How to Implement a Script Task

• Business object methods

  See Working with Business Object Methods

Within a script block, you can create and use types from the Business Catalog, Java 6 SE API Library, and from any JAR files included in the BPM project.

25.2 Introduction to the BPM Code Editor

The BPM Code editor provides basic syntax highlighting, error and warnings highlighting, and code completion.

• Basic Syntax Highlighting

  It displays the code in different colors and fonts according to the category of terms. Syntax highlighting also helps developers find mistakes in their code.

• Error and Warnings Highlighting

  It highlights compiling errors and warnings while you are writing the code. It also provides a description of the problem.

• Code Completion

  It predicts a word or phrase that the user wants to type before they finish typing it.

The Code editor supports the following types of code completion:

• Inherited members (extends/implements)

• Instance members (fields/methods)

• Class members (fields/methods)

• Local variables

• Method parameters

• Primitive types

• Class Names (import will be automatically added if not exists)

The editor displays the options ordered by their relevance. If multiple options have the same relevance, the editor orders them alphabetically.

Figure 25-1 shows the Script editor with the implementation of a script task.

Figure 25-1 Script Editor

Description of "Figure 25-1 Script Editor"

25.3 Introduction to the Scripting Catalog

The Scripting Catalog contains all the libraries available for you to use in your scripts. These libraries contain components that you can access by instantiating them and invoking their method. These components are stored in modules.

The Scripting Catalog contains the following components:

• The default Groovy libraries

• The default Java libraries

• The business catalog components

• The imported custom libraries

Figure 25-2 Scripting Catalog Window

Description of "Figure 25-2 Scripting Catalog Window"

25.4 Importing Custom Libraries

You can use external Java libraries that contain functions that are useful for your project. This enables you to benefit from the vast amount of libraries that solve different problems and are available for Java developers to use.

You can import these Java libraries and invoke them from the Groovy scripts.

After you import a Java library, it becomes part of the Scripting Catalog for that BPM project and you can use the from the scripts you write.

25.4.1 How to Import a Custom Library

To use an external Java library you must first import it to the BPM project's Scripting Catalog.

To import a custom library:

1. Open the business object or the process where you want to import the library.
2. In the Scripting Catalog window, click Edit Libraries.

   The Libraries dialog box opens.

3. Click the Add button.

   The Open dialog box opens.

4. Select a the jar file containing the external library.
5. Click Open.

   The select library appears in the Libraries table.

6. Select the library.
7. Click OK.

   The selected library appears in the Scripting Catalog and is available for you to use its classes in your scripts. Note that some libraries may appear in already existing modules, like org or com.

25.5 Working with the Elements of a BPM Project

You can access the value of some of the elements of a BPM project and you can manipulate their values or use them to perform operations.

You can access the following elements of a BPM project from a script:

• project data objects

• process data objects

• business parameters

Project and process data objects are available as variables in the script.

25.5.1 How to Work with Business Objects

You can access the attributes and methods of the data objects defined as a business object, in the same way that you access the attributes and methods of a java object.

For example: You created a business data object that models a person. This business object contains a name attribute and a promote method.

You also defined a process data object of type Person.

You can access the name attribute using the following code:

person.name;

You can access the promote method using the following code:

person.promote;

To create an instance of a Business Object and store it in a local variable.:

1. Import the business object.

   For information on how to import a business object, see Importing Business Objects from the Business Catalog.

2. Create a variable with the type of the business object and assign it a new instance of the business object.

The following example imports the Person type, creates a local variable of type person, assigns a value to its attributes and then assigns the local instance to the Person process data object:

def localPerson = new Person();
localPerson.firstName = "John";
localPerson.lastName = "Cooper"
this.person = localPerson;

25.5.2 How to Work with Business Parameters

After you define a business parameter in the organization you can access it using its getter method.

For example, if you define a business parameter TAX_CODE, then you can access it using the following code:

this.getTAXCODE()

25.6 Importing Business Objects from the Business Catalog

You can use the business objects defined in the business catalog in your scripts. To do this you must first import the business objects.

To import a business object from the business catalog:

1. In the Script Editor, click Select Imports.

   The Select Imports dialog box appears.

2. Click the Add button.

   A new row appears in the imports table.

3. Start typing the path to the business object.

   For example: oracle.scripting.catalog.shipping.ShipOrder

   The auto-complete list displays a list of options.

4. Select the business object you want to import from the auto-complete list.
5. Click OK.

   The selected import is now available for you to use it in your code.

25.7 Predefined Variables

The variable predef is available in every script task method context. This variable enables you to access the available predefined variables.

The following table shows the supported predefined variables and how to access them using Groovy expressions. If the access type of the predefined variable is read/write, then you can use the Groovy expression to view the value of the predefined variable and to modify it. If the access type is read-only, then you can only view the value of the predefined variable.

Note:

BPMN only perform the necessity actions on the data and does not check the authenticity of the data. Predefined variable values must be validated, and right values must be set by client application.

Table 25-1 Groovy Expressions to Access Predefined Variables

Predefined Variable	Groovy Expression	Access Type
Organizational Unit	predef.organizationalUnit	Read/write
Title	predef.title	Read/write
Creation Date	predef.creationDate	Read-only
Modify Date	predef.modifyDate	Read-only
Instance Number	predef.instanceNumber	Read-only
Instance ID	predef.instanceId	Read-only
ECID	predef.ecid	Read-only
Process DN	predef.processDN	Read-only
Conversation ID	predef.conversationId	Read-only
Component Type	predef.component.type	Read-only
Component Name	predef.component.name	Read-only
State	predef.state	Read-only
Composite Name	predef.composite.name	Read-only
Composite DN	predef.composite.dn	Read-only
Composite Label	predef.composite.label	Read-only
Composite Revision	predef.composite.revision	Read-only
Composite Instance ID	predef.composite.instanceId	Read-only
Activity Name	predef.activity.name	Read-only
Priority	predef.priority	Read/write
Creator	predef.creator	Read/write
Owner	predef.owner	Read/write
Owner Type	predef.ownerType	Read/write
Action	predef.action	Read/write
Expiration	predef.expiration	Read/write
Reviewer	predef.reviewer	Read/write
ReviewerType	predef.reviewerType	Read/write
DueDate	predef.dueDate	Read/write

25.8 Implementing Script Tasks

A BPMN script task is an activity that runs a script.

This script is written in Groovy and can access and modify the value of the data objects defined in a BPM project.

25.8.1 How to Implement a Script Task

Script tasks require you to implement them using Groovy code.

To implement a script task:

1. Add the script task to your BPMN process.
2. Right-click the script task.
3. Select Go To Script.

   The Scripting tab appears. In this tab you can write the script that implements the script task. To go back to the process editor, select the Designer tab.

25.9 Type Description Mapping for XML Schema Types

This section describes the mapping between the XML schema data types and the type descriptions used in the scripts.

Table 25-2 Type Description Mapping for XML Schema Types

XML Schema Data Type	Type Description
xsd:string	java.lang.String
xsd:normalizedString	java.lang.String
xsd:token	java.lang.String
xsd:Name	java.lang.String
xsd:QName	java.lang.String
xsd:NCName	java.lang.String
xsd:anyURI	java.lang.String
xsd:language	java.lang.String
xsd:ID	java.lang.String
xsd:IDREF	java.lang.String
xsd:ENTITY	java.lang.String
xsd:NOTATION	java.lang.String
xsd:NMTOKEN	java.lang.String
xsd:uriReference	java.lang.String
xsd:anySimpleType	java.lang.String
xsd:IDREFS	java.lang.String
xsd:ENTITIES	java.lang.String
xsd:NMTOKENS	java.lang.String
xsd:timeInstant	java.lang.String
xsd:timeDuration	java.lang.String
xsd:anyType	java.lang.String
xsd:byte	java.lang.Byte
xsd:unsignedByte	java.lang.Byte
xsd:short	java.lang.Short
xsd:unsignedShort	java.lang.Short
xsd:int	java.lang.Integer
xsd:unsignedInt	java.lang.Integer
xsd:gDay	java.lang.Integer
xsd:gMonth	java.lang.Integer
xsd:gYear	java.lang.Integer
xsd:integer	java.math.BigInteger
xsd:positiveInteger	java.math.BigInteger
xsd:negativeInteger	java.math.BigInteger
xsd:nonPositiveInteger	java.math.BigInteger
xsd:nonNegativeIntege	java.math.BigInteger
xsd.long	java.lang.Long
xsd:unsignedLong	java.lang.Long
xsd:decimal	Decimal
xsd:float	java.lang.Float
xsd:double	java.lang.Double
xsd:boolean	java.lang.Boolean
xsd:dateTime	com.oracle.scripting.lib.xml.datatype.XmlCalendar
xsd:time	com.oracle.scripting.lib.xml.datatype.XmlCalendar
xsd:date	com.oracle.scripting.lib.xml.datatype.XmlCalendar
xsd:gYearMonth	com.oracle.scripting.lib.xml.datatype.XmlCalendar
xsd:gMonthDate	com.oracle.scripting.lib.xml.datatype.XmlCalendar
xsd:duration	com.oracle.scripting.lib.xml.datatype.XmlDuration
xsd:base64Binary	byte[]
xsd:hexBinary	byte[]