Using Java in an activity step

Activities execute as server-side Java, so it is technically simple to include custom Java statements within your activities. However, experience with designing, coding, and testing Java is required.

Whenever you Save an activity, the system validates Java code from information in the form and in other rule instances. This generated Java is read-only. To review the generated Java code, click the Show Java toolbar button ().

The window provides a preview of the Java that implements this rule instance. The Java code presented is similar to but not identical to the Java that executes at runtime, which includes Java code inlined from other rule instances and reflects rules in the requestor's RuleSet list.

The first time a requestor session selects this activity for execution, the rules assembly occurs again, generating and compiling Java that is specific to the RuleSet list and other context of that requestor. The next execution of the same execution by that requestor, or other requestors with identical access, does not require assembly or compilation.

To have Process Commander execute your custom Java within the generated Java for an activity, add inline Java into an activity step. (These are known as Java steps.)

Inline Java steps can introduce complex, difficult-to-debug processing into your application. Use this facility only when necessary. Following the SmartBuild guardrails, avoid Java steps when other approaches can achieve the same computational result. Activities containing a Java step are flagged with a warning message when you save the Activity form, and during the Preflight check.

1 Type Java in the Method field of the step.

2. Click the gear icon to expand the Method field. A text box appears in which you can enter normal Java code and Process Commander-specific Java.

3. Optionally, click the pencil icon () to start Windows Notepad or a workstation-based Java IDE — for example, Eclipse — that you have set up.

Your Java code can use two sources of Process Commander-specific Java:

• Functions defined through the Rule-Utility-Function rule type (See About Function rules)
• Java methods defined in the Process Commander Public Application Programmer Interface

In addition, your Java can call methods and functions in external libraries, if all these conditions are true:

• The JAR file for the library is in the proper directory of the application server
• The name is included in the class path
• The Java classes are loaded.

See the Pega Developer Network article PRKB-20931 About the Process Commander class paths. Consider Connect JAVA rules or Connect EJB rules as alternatives to Java steps.

Because the Java you write in an activity step is inline Java, you cannot import your Java libraries or add Java import statements. However, you can refer to Java classes using a fully qualified class name. For example:

Process Commander cannot accept:

Vector x = new Vector();

However, you can write:

java.util.Vector x = new java.util.Vector();

Use the String.equals() Java method, not the == or != operators, to compare the value of a property to a literal string or to the value of another property.

The icon identifies the iteration column of the Steps array. To cause this Java step to execute iteratively over the elements in a Value List or Page List property, click the iteration box and select the iteration type. The predefined currentProperty variable identifies the current element. See Pega Developer Network articles

• PRKB-8728 How to work with String List and String Group property elements
• PRKB-8730 How to work with Page List and Page Group property elements

For a complete list of available PublicAPI Java methods, consult the Public API JavaDocs. By convention, the tools variable identifies the PublicAPI class.

For example, the two Java methods getProperty() and getParameter() get and set property values on a page:

• getProperty(string prop_ref)

• setProperty(string dict_ref, string value)

• getParameterValue(string param_name)

• setParameterValue(string param_name, string value)

In many cases, your Java code needs to reference variables defined in the step's generated Java. For example, the generated Java often uses the variable myStepPage to refer to the current step page. (The step page must be present on the clipboard before the Java step starts.)

This example from of the standard activity named Work-.FinishAssignment uses Java methods in the ClipboardPage interface and uses local variables lockGone and lockCreationtime (declared on the Parameter tab of the Activity form).

In addition to the normal Java libraries, your Java step can call functions in the Rule-Utility-Function class. This class contains functions (Rule-Utility-Function rule type), organized into libraries (Rule-Utility-Library rule type).

Each function rule belongs to a RuleSet. To call a function rule from a Java step, refer to each library by its RuleSet and library name. For example, a standard library named String is defined in the Pega-RULES RuleSet. To reference this library in your Java, use this syntax:

pega_rules_string.

After the dot, enter the name of the String library function using exact case, and any required parameters:

pega_rules_string.equalsIgnoreCase ("ABC123DEF", pyWorkPage.Account);

Certain variables have assigned purposes and are reserved. See Activity rules — Reserved names for parameters and local variables.

When executing in the enterprise tier of a J2EE application server, applications cannot directly read from or write to the server file system. In such situations, you cannot use native java.io routines. Instead, use the Virtual File Interface (part of the Public API) provides similar methods. In Web tier installations, the Virtual File Interface methods merely call the corresponding native Java methods.

Technically, the text Java in the Method column does not reference a Process Commander method. But like methods, the Java instruction updates the pxMethodStatus property. See How to test method results using a transition.