Working with the Java Pages Feature. PegaRULES ProcessCommander Versions 5.1 and 5.2

Transcription

1 Working with the Java Pages Feature PegaRULES ProcessCommander Versions 5.1 and 5.2

2 Copyright 2006 Pegasystems Inc., Cambridge, MA All rights reserved. This document and the software describe products and services of Pegasystems Inc. It may contain trade secrets and proprietary information. This information should not be disclosed to third parties unless otherwise provided for by a contract or business agreement with Pegasystems. This document and the software are protected by federal copyright law, international laws, and/or applicable treaties. This document is current as of the date of publication only. Changes in the document may be made from time to time at the discretion of Pegasystems. This document remains the property of Pegasystems and must be returned to it upon request. This document does not imply any commitment to offer or deliver the products or services provided. This document may include references to Pegasystems product features that have not been licensed by your company. If you have questions about whether a particular capability is included in your installation, please consult your Pegasystems service consultant. For Pegasystems trademarks and registered trademarks, all rights are reserved. Other brand or product names are trademarks of their respective holders. Although Pegasystems Inc. strives for accuracy in its publications, any publication may contain inaccuracies or typographical errors. This document could contain technical inaccuracies or typographical errors. Changes are periodically added to the information herein. Pegasystems Inc. may make improvements and/or changes in the information described herein at any time. This document is the property of: Pegasystems Inc. 101 Main Street Cambridge, MA (617) , fax: (617) PegaRULES Process Commander Document: Working with the Java Pages Feature Software Version: 5.1 and 5.2 Posting Date: December 2006

3 Contents Introduction...2 Overview...2 The Process...4 Other Java Objects...6 Summary of Steps...6 Creating the JavaBean s Data Model...7 Requirements for the Source Java Class...7 Before You Begin...8 Run the Accelerator...8 Results...10 Serialization and Design Changes...11 Using the Data Model with the Work Object...12 Copying Individual Values...12 Linking the Whole Object...12 Working with the JavaBean Instance...14 Mapping to and from Java Pages...14 Mapping Data with the Java Pages Activities...17 Testing and Troubleshooting...22 Additional Configuration Options...23 Data Types and Transforms...23 Custom Wrapper Classes...25

4 Working with the Java Pages Feature Many organizations have pre-existing Java data models, instances of which represent their business or work objects or parts of their business or work objects. Use Java pages and Process Commander Java properties to take advantage of pre-existing, external Java data structures when designing the data model for a flow application in Process Commander. Java pages and Process Commander Java properties enable a Process Commander application to interact with external Java objects that are instances of JavaBeans (usually delivered by services and connectors) as though they were pages and properties on the clipboard. Process Commander rules can interact with the external Java objects in the same way that they interact with Process Commander classes and properties. This document contains the following sections: Introduction Creating the JavaBean s Data Model Using the Data Model with the Work Object Working with the Java Testing and Troubleshooting Additional Configuration Options

5 Working with Java Objects Introduction The Process Commander Java pages feature enables you to use rules and the clipboard to interact with Java objects that are instances of JavaBeans in the same way that you use them to interact with Process Commander class and property rules. The Java pages feature provides both development and runtime components. Accelerators help during the development process by generating the rules that implement in Process Commander the data model of the Java object. The clipboard and standard activities that interact with the clipboard provide the runtime processing. For an example of a Process Commander data model based on an external Java data structure, see the class and property rules that create the AutoClaim sample application for the JSR 94 service sample in the PegaSample-IntSvcs ruleset posted on the Pega Developer Network (PDN). Overview The Java pages feature is implemented through the following items: The Embed-Java- class rule and the Java Property property modes: Java Property, Java Property List The Import JavaBeans Accelerator and the Create Connector Rules Accelerator, which automate the process of creating the Process Commander class and property rules that implement the data model of the Java class The clipboard PRObjectWrapper Java interface and generated Java wrapper classes that use the interface to attach Java objects to clipboard pages or get Java objects from clipboard pages Java Pages and Java Properties The Embed-Java- class rule is a helper class used to create the clipboard context where Java objects can be manipulated during Process Commander processing. Process Commander Java pages are instances of class rules that inherit from the Embed-Java- class and are stored on the clipboard as pages. These pages represent the Java class of an external Java object. Process Commander Java properties are of the mode Java Property or Java Property List. They represent the properties in the Java class that define the external Java object. You can create properties of this mode only for class rules that inherit from Embed-Java-.

6 Working with the Java Pages Feature Introduction 3 Use the Import JavaBeans Accelerator and Create Connector Rules Accelerator to generate the class rules and Java properties that represent the Java object s data model. The PRObjectWrapper Interface and the Java Wrapper Classes When you use the accelerators to generate the class and property rules that represent the data model of the external Java object, the accelerator also generates Java wrapper classes. The wrapper classes implement the PRObjectWrapper interface of the Clipboard Java API, allowing the clipboard to access the external Java object in a standard way. Each Process Commander class rule generated for the Java object has a matching generated Java wrapper class. The Import JavaBeans Accelerator The Import JavaBeans Accelerator is one of the rule and interface generation accelerators that automate integration tasks. It creates class and property rules that reflect the data model from an external system. You use the Import JavaBeans accelerator when a JavaBean instance will be sent from an external system to a Process Commander Javabased service rule. The accelerator creates class and Java property rules (properties of mode Java Property or Java Property List) that reflect the data model described in a Java class file. You manually create a top-level, or base, abstract class rule that inherits from the standard Embed-Java- class rule to serve as the container (or base) for the generated items. Then you start the accelerator and identify the source Java class. The accelerator inspects the Java class through introspection, and then generates the appropriate Process Commander class and property rules. It also creates Java wrapper classes that access the get and set methods from the source Java class through the PRObjectWrapper interface of the Clipboard API. The Create Connector Rules Accelerator The Create Connector Rules Accelerator (Connector Accelerator) is another interface generation accelerator that automates integration tasks. When your Process Commander application needs to call a method in an external Java class, you use the Connector Accelerator to generate a Java connector. If the method invoked by the connector has arguments that are themselves instances of JavaBeans, the Connector Accelerator will generate the appropriate class and property rules and Java wrapper classes in addition to the connector and activity rules. You identify or create an abstract class rule, typically one that inherits from Data-, to serve as the container or base for the generated items. Then you start the accelerator and identify the source Java class or EJB. The accelerator inspects the Java class through

7 Working with Java Objects introspection, and then generates the appropriate connector, activity, and Process Commander class and property rules. If the input arguments or response types are JavaBeans, the accelerator creates and inserts into the class rule structure an abstract class rule that inherits from Embed-Java- and uses it as the base class for class rules and Java properties that represent the JavaBean s data model. In this case, it also creates Java wrapper classes that access the get and set methods from the source Java class. The Process As mentioned in the Overview, a Java page is an instance of a class rule that inherits from the Embed-Java- class. You create rules and write activities that interact with Java pages just as you do for any other clipboard page. Process Commander automatically manages the additional processing when the page is a Java page. For example, to create a Java page, you use the Page-New activity method and specify the class rule as usual. To set property values on the page, you use the Property-Set activity method. Without any extra coding on your part, Process Commander uses the Java wrapper class generated for the class rule to access the methods in the Java source class to create the Java object and interact with it. Figure 1 illustrates the interaction between an activity, a generated Java wrapper class, the source Java class, and the clipboard Java page.

8 Working with the Java Pages Feature Introduction 5 Figure 1. Creating a Java Page In Figure 1, an activity rule creates a Java page named ClaimPage of class SampleJavaBase-Claim. (This class rule was generated in the PegaSample-IntSvcs RuleSet for the JSR 94 service sample.) The activity rule then uses the Property-Set method to set a value for the claimamount property. When invoking the Property-Set activity method, Process Commander uses the Java wrapper class generated for the SampleJavaBase-Claim class rule. The Java wrapper

9 Working with Java Objects class accesses the methods in the Claim Java class to create the instance of the Java object (the Java page) and to set values to or get values from the object. Other Java Objects If the Java object to be passed to and/or from your Process Commander application is not an instance of a JavaBean, you cannot use the Java pages feature to manage its data mapping. In such a case, you configure the service or connector to map the object to a property of type Java Object, Java Object List, or Java Object Group, as appropriate. Then you use Java steps in the service or connector activity to map the data from the object to and from the clipboard. Summary of Steps Following are the steps to complete when configuring a Process Commander application to use a pre-existing Java data model to represent part of a business or work object. 1. Put the Java class or.jar file in the Process Commander classpath so the accelerator can locate it. For help with this step, go to the Pega Developer Network ( and use the article PRKB About the Process Commander Version 5 Class Paths. 2. Run the Import JavaBeans Accelerator or Connector Accelerator, as appropriate, to generate the class and property rules and the Java wrapper classes. 3. Create properties for the work object to hold specific values from the incoming Java objects. 4. Code activities that interact with instances of the Java objects.

10 Working with the Java Pages Feature Creating the JavaBean s Data Model 7 Creating the JavaBean s Data Model Use the appropriate accelerator (Import JavaBeans for services, Connector Accelerator for connectors) to generate the classes, properties, and Java wrapper classes that implement in Process Commander the data model of the JavaBean. The accelerators generate classes, properties, and Java wrapper classes for the source Java class, any Java classes in its inheritance tree, and any encapsulated Java classes. (An encapsulated Java class is one that is referred to as a property by another Java class in the inheritance tree.) The accelerators use a recursive process that generates items for all Java classes referenced in any way by the source Java class. Requirements for the Source Java Class When generating the class and property rules, Process Commander uses the JavaBeans coding standard to determine the identities of properties in a Java class. That is, the getter and setter accessor methods for a property must begin with get and set. The JavaBeans coding standard defines an indexed property as one that has an array value. In Process Commander, that definition includes java.util.list and any of its implementing classes (java.util.arraylist, for example). However, because list properties are not typed, the source Java class must provide an indexed get method for the property so the data type can be determined. For example, imagine a Java class has a list property named somelist with the following get method for the entire list: public java.util.list getsomelist() For Process Commander to recognize the list as an indexed property, the Java class also needs a get method for an individual element in the list like the following: public Type getsomelist(int); Without an indexed get method, Process Commander cannot determine the data type of the objects held in the list and will not interpret the property as a list property in Process Commander. Note: If the source Java class implements the Serializable interface, Process Commander can persist instances of the Java class with other clipboard data. For example, it can save information from the Java object with work items.

11 Working with Java Objects Before You Begin Before you run the Import JavaBeans Accelerator or Connector Accelerator, you decide which abstract class rule to use as the base class for the generated rules and put the source Java class in a location where the accelerator can find it. Complete the following tasks: 1. Create or identify the base class rule for the generated rules: For the Import JavaBeans Accelerator, the base class rule be an abstract class that inherits from Embed-Java-. For the Connector Accelerator, you need two class rules: an abstract class rule that typically inherits from Data- to serve as the container for the class, property, and connector rules, and a concrete class rule that inherits from Work- to hold the connector activities. 2. Put the Java class on the Process Commander runtime and compile time classpaths. Go to the Pega Developer Network ( and locate the article PRKB About the Process Commander Version 5 Class Paths. Follow the instructions in the section titled Adding Third-Party jar Files and Java Class Files to the Class Paths. Run the Accelerator Which accelerator you use to generate the rules and wrapper classes that implement in Process Commander the data model of the Java object depends on the integration task you are trying to accomplish. Use the Connector Accelerator when the Process Commander application is to send or receive an instance of a JavaBean with a Java or EJB connector rule. Use the Import JavaBeans Accelerator when a fully constructed instance of a JavaBean is to be delivered by an external source through a service rule. Run the Connector Accelerator For information about using the Connector Accelerator, see Using the Connector Accelerator, which is available on the PDN. Follow the steps from the appropriate procedure. Additionally, the Application Developer Help system has context-sensitive topics for each form that the Connector Accelerator displays.

12 Working with the Java Pages Feature Creating the JavaBean s Data Model 9 Import JavaBeans Accelerator Complete the following steps: 1. In the main Process Commander window, click the Integration icon. 2. On the Integration page, under Wizards, select Import JavaBeans. 3. In the Enter Rule Info window, complete the fields as shown in Figure 2 and then click Next. Field Source Datatype Base Class Ruleset Version Value Select Java Class (for Java Properties) Select the Process Commander class rule that inherits from Embed-Java- that you created or identified. Select the appropriate RuleSet. It is easier, but not required, to use the same RuleSet for the generated rules as you did for the abstract base class. Select the appropriate version number for the RuleSet. Figure 2. Fields on the Enter Rule Info Window 4. In the Initial Parameters window, enter the fully qualified name of the Java class. For example, com.pega.pegarules.sample.autoclaim.claim was the correct package name and class for the AutoClaim Java class that is used in the JSR 94 service sample. Note that the name of the class is case-sensitive. The accelerator parses the Java class and then displays the names of the parameters that are defined in that Java class. 5. In the Fields window, select the properties for which you want the accelerator to create Process Commander Java properties, and then click Next. The accelerator generates the Process Commander class rules, Process Commander properties, and Java wrapper classes. 6. In the View Results window, examine the list of generated items and then write down the ID of the Interface Generator instance for future reference. Note that the Usage field of each generated rule also holds the ID of the Interface Generator instance.

13 Working with Java Objects Results When the Import JavaBeans Accelerator or Connector Accelerator is finished, it generated Process Commander classes, Java Property properties, and Java wrapper classes that implement the data model specified in the source Java class. (For information about the additional connector and connector activity rules generated by the Connector Accelerator, see the document Using the Connector Accelerator, which is posted on the PDN.) Class and Property Rules The Process Commander class rules and properties (of mode Java Property and Java Property List) are generated under the base class that you specify when you run the accelerator. The accelerator also creates model rules for the class rules. If you selected any properties that refer to other Java classes, the accelerator generates class rules and properties for those Java classes without prompting you to select additional fields. Wrapper Classes The Java wrapper classes are generated in a new package based on the name of the source class, according to the following syntax: <your package>.prpcwrapper.<your class name> For example, if the source class is named com.pega.big.blue.skybean, then the generated wrapper class is named: com.pega.big.blue.prpcwrapper.skybean If the source Java class implemented the Serializable interface, so does the matching Java wrapper class. The Java wrapper classes are located in the Process Commander PRGenJava subdirectory of the application server temporary directory. They are package-qualified so they are located in a directory structure that matches the package name. They are ready to go: your activities can use them without your having to restart the application server. If any compilation errors occurred while the accelerator generated the Java wrappers, the Accelerator writes them to a log file located in the root of the PRGenJava directory.

14 Working with the Java Pages Feature Creating the JavaBean s Data Model 11 Serialization and Design Changes As mentioned, if the source Java class implements the Serializable interface, Process Commander can persist instances of the Java class with other clipboard data. For example, it can save information from the Java object with work items. If your application is designed to save information from the Java object with work items, be sure to consider possible changes to the Java source class carefully; remember that standard Java Serialization rules apply. Before you make changes to a class and import it with the Import JavaBeans accelerator, consult the following resources to learn strategies for versioning objects:

15 Working with Java Objects Using the Data Model with the Work Object When using the data model of the JavaBean with the work object, there are two general options: Copy individual values from the Java Page on the clipboard to individual work object properties that you create specifically for this purpose. Link the entire JavaBean data model to the work object through an embedded page property. Copying Individual Values In most cases, you need to include only specific parts of the data from the Java object with the work objects in your Process Commander application. Create properties for the work object s class to hold only the data you are interested in. Then, use Property-Set steps in the service or connector activities to set values from the Java pages to those properties on the pyworkpage for the work objects. Linking the Whole Object Optionally, you can link the entire JavaBean data model to your work objects through embedded page properties. Complete the following steps: 1. Add a new property to the class rule of the work item. 2. On the Definition tab, complete the fields as shown in Figure 3: Field Property Mode Page Class Java Page Value Page or Page List Select the name of the generated class that represents the top level of the Java object s data model. (Optional) Select this option to enable the next option. Note that whether or not you select this option, the pages of the Page Class specified are Java pages because the class inherits from the Embed-Javaclass.

16 Working with the Java Pages Feature Using the Data Model with the Work Object 13 Field Serialize this object Value (Optional) Appears only when the Java Page option is selected. Select this option if the source Java class implements the Serializeable interface and you want to be able to save the data from this page property with the work item. Figure 3. Fields on the Definition Tab for a Property 3. On the History tab, enter a description in the Full Description and the Usage fields. 4. Save the property.

17 Working with Java Objects Working with the JavaBean Instance As mentioned, Process Commander applications usually work with external Java objects through services and connectors. Either a fully constructed Java object is delivered by an external source through a service, or the Process Commander application constructs a new Java object and sends it to an external application with a connector. The Process Commander service rule types that receive Java objects are EJB, Java, JMS, and JSR 94. The connector rule types that send Java objects are EJB, Java, JCA, and JMS. You can map an incoming instance of a JavaBean to the clipboard and outgoing instances of JavaBeans from the clipboard in either of the following ways: Map them to or from Java pages, that is, properties of mode Page or Page List whose page class inherits from Embed-Java- Map them to or from properties of mode Java Object, Java Object List, or Java Object Group and then use the Java Pages activities to move the objects to and from Java pages on the clipboard. This section describes both options and provides a detailed description of the Java Pages activities, which starts on page 17. Mapping to and from Java Pages The data mapping sections of all the Java-based service and connector rule types support the direct mapping of Java objects to and from Java pages. For example, the data in a JSR 94 request or response is a java.util.list. You can map the whole list as a single object directly to and from a Java page (a page list property whose page class inherits from Embed-Java-), individual elements in the list to individual Java pages, or individual elements in the list to individual Java properties on the Java page Services Example The JS4 94 service sample illustrates how to use the Java Pages activities but it could very easily map its claim objects directly to and from a Java page. To modify the sample, start with a Java page property; that is, a page list property whose page class is SampleJavaBase-Claim and that applies to the SampleJavaBase- class like the one shown in Figure 4.

18 Working with the Java Pages Feature Working with the JavaBean Instance 15 Figure 4. Java Page Property Because the SampleJavaBase- class rule inherits from the Embed-Java- class, an instance of the ClaimObjectJavaPageProperty page list property is a Java page. To map the incoming and outgoing claim objects to and from this property, simply select it in the Map To Key and Map From Key fields in the service rule. Figure 5 shows the mapping for an incoming object on the Request tab. Figure 5. Mapping Directly To a Java Page in a JSR 94 Service Rule Connector Example When you use the Connector Accelerator to generate EJB or Java connectors, it creates Java page properties when appropriate and the generated connector rules use them in data mapping as needed. For example, imagine a Java class structure that holds employee information. A Java class named Employee has a method named getpersonaldata that returns a variable named getpersonaldata_return. This variable refers to an object of a Java class called PersonalData. The PersonalData Java class has two variables that also refer to objects of another Java class: A variable named address that refers to an object of Java class HomeAddress. A variable named relatives that refers to a list of objects of Java class FamilyMember.

19 Working with Java Objects When the Connector Accelerator generates class and property rules for the Employee Java class, the property rules are the ones displayed in Figure 6. Figure 6. Class and Property Structure of getpersonaldata_return The Page Classes of the getpersonaldata_return, address, and relatives property rules inherit from the standard Embed-Java- class rule. The Connector Accelerator also generates a connector rule for the getpersonaldata method. When the PersonalData Java object is returned to the getpersonaldata connector, it is mapped directly to the getpersonaldata_return property, as shown in Figure 7. Figure 7. Mapping to a Java Page in a Java Connector Rule The data type of the return value in Figure 7 is the name of the Java class, com.pega.pegarules.sample.connect.java.personaldata. This Java object is mapped directly to a page on the clipboard where the connector activity generated for the getpersonaldata connector has direct access to it.

20 Working with the Java Pages Feature Working with the JavaBean Instance 17 Mapping Data with the Java Pages Activities When implementing integration projects, there are always special cases or exceptions to the typical case. For example, imagine an application that uses a single connector rule to communicate with an external system, but the object sent by the connector varies based on a choice configured in the flow. When a service or connector does not send (or receive) the same kind of JavaBean in each invocation, you cannot use the data map in the rule to map the object directly to or from a Java page. Therefore, Process Commander provides standard activities that attach JavaBeans to and detach JavaBeans from Java pages. The Java Pages activities apply to the Embed-Java- class, which means you can call them in activity steps whose step page class inherits from the Embed-Java class. The Embed-Java-.AttachJavaObject activity attaches the Java object to a Java page on the clipboard. This activity is typically used by service activities to attach to a clipboard page (Java page) a Java object passed in through a request to a service. The Embed-Java-GetAttachedJavaObject activity retrieves the Java object from a clipboard page (Java page). This activity is typically used by connector activities to provide the input for connector requests to external systems. After Java objects are attached to Java pages in the clipboard, your application rules can interact with and process the Java objects as though they were clipboard pages and properties. The JavaObject Activity Parameter and Java Object Properties Both the AttachJavaObject and the GetAttachedJavaObject activity have one activity parameter: JavaObject. The JavaObject parameter supplies the name of a Process Commander property of mode Java Object, Java Object List, or Java Object Group. (The property is relative to the step page from which you call the AttachJavaObject or GetAttachedJavaObject activity.) Properties of these modes hold a reference to an instance of a Java object. Use Java Object properties as placeholder properties for incoming and outgoing Java objects: The reference to an incoming Java object must be stored somewhere, temporarily, until the AttachJavaObject activity can wrap the object in the Process Commander clipboard context and attach it to a Java page on the clipboard. For an incoming Java object, code the application to store the Java object as a Java Object Property before it is processed.

21 Working with Java Objects When the GetAttachedJavaObject activity retrieves a Java object from a clipboard page, it must put the reference to that object somewhere for the connector rule that will send it to an external application. For an outgoing Java object, code the application to extract the Java object from the clipboard page, store the reference in a Java Object Property, and to use the property in the request sent to the external system Java Properties and Java Object Properties Although their names are similar, the Java Property properties and Java Object properties implement different functions. When an external Java object is referenced by a Java Object property rather than attached to a clipboard Java page, your application can access the object through Java steps in activity rules and function rules but cannot process them with rules of other rule types (declarative rules, for example). When you use Java pages and Java Property mode properties, however, you can write rules that work on the external Java objects. Example: Using the AttachJavaObject Activity with Services When you are not able to use the data map of a service or connector rule to map an incoming Java object directly to a Java page, you can map the incoming object to a placeholder Java Object property and then use the AttachJavaObject activity to attach it to a Java Page. You use the AttachJavaObject activity by calling it from another activity, typically a service or connector activity. The activity must set the context first by creating the Java page the object will be attached to. Additionally, the activity must provide the name of the Java Object property that currently represents the Java object in an activity parameter named JavaObject. The following example describes how you would use the AttachJavaObject activity for a service: 1. In the page class for the service rule, create a new property for the incoming Java object. Set the property mode to Java Object, Java Object List, or Java Object Group, as appropriate for the data type of the incoming Java object: Objects of type java.util.list, java.util.array, and java.util.arraylist can be mapped to properties of mode Java Object List. Objects of type java.util.map can be mapped to properties of mode Java Object Group.

22 Working with the Java Pages Feature Working with the JavaBean Instance In the service rule form, in the Page Name field, enter a name for the class specified in the Page Class field. By convention, this page is called ServicePage. 3. Still in the service rule form, on the tab that specifies the data mapping for the request, map the incoming Java object to the property of mode Java Object that you created in step In the form for the service activity, on the Pages and Classes tab, create page entries for the following class rules: The page class of the service rule. Be sure to give it the same name that you used in the Page Name field of the service rule form. By convention it is called ServicePage. The class for the work item. By convention the work page is named pyworkpage. The page class of the Java page that the incoming Java object will be attached to. If this class represents an embedded page property that links the entire Java object data model to the work object, use the convention pyworkpage.javapage where JavaPage is the name of the embedded page property. For example, pyworkpage.claim Figure 8 shows an example of the pages defined on the Pages and Classes tab of a service activity: Figure 8. Pages and Classes Example for a Service Activity 5. On the Steps tab, use the Page-New method to create the pyworkpage.javapage page in the first step. 6. In the second step, with the pyworkpage.javapage page as the step page, call the AttachJavaObject activity. It takes one parameter: JavaObject. The value of this parameter is ServicePage.JavaObjectProperty where JavaObjectProperty is the name of the property you created in step 1 of this procedure. Figure 9 shows an example.

23 Working with Java Objects Figure 9. Activity Step that Calls the AttachJavaObject Activity 7. Configure the remaining steps for the service activity, as appropriate. For example, save the work item and start its flow. Example: Using the GetAttachedJavaObject with Connectors When you are not able to use the data map of a service or connector rule to map an outgoing Java object directly from a Java page, use the GetAttachedJavaObject activity to extract the Java Object from the Java page. You use the GetAttachedJavaObject activity by calling it from another activity, typically a service or connector activity. Before an activity can call GetAttachedJavaObject, a named page of a class rule that inherits from Embed-Java- (a Java page) must exist on the clipboard. Additionally, the activity must provide the name of the Java Object property where the GetAttachedJavaObject activity puts the reference to the Java object after it retrieves it. The following example describes how you would use the GetAttachedJavaObject activity with a connector. 1. Open the connector activity generated by the Create Connector Rules Accelerator for the connector. 2. On the Pages and Classes tab, create page entries for each of the following class rules: The applies to class for the connector rule the activity calls. By convention the the Connector Accelerator names this page DataPage so it is best to continue to use DataPage as the page name for the connector. The applies to class for the connector activity, which is typically the applies to class for the work item. By convention the work page is called pyworkpage. The applies to class of the embedded page property that links the Java object data model to the work object. When naming the page, use the convention pyworkpage.javapage where JavaPage is the name of the embedded page property. For example, pyworkpage.claim. Figure 10 shows an example of the pages defined on the Pages and Classes tab of a connector activity:

24 Working with the Java Pages Feature Working with the JavaBean Instance 21 Figure 10. Pages and Classes Example for a Connector Activity 3. On the Steps tab, in the first step, set the step page to pyworkpage.javapage and use the Call method to call the GetAttachedJavaObject activity. It takes one parameter: JavaObject. The value of this parameter is DataPage.JavaObjectProperty where JavaObjectProperty is the name of the property you created in step 1 of this procedure. Figure 11 shows an example. Figure 11. Activity Step that Calls the GetAttachedJavaObject Activity 4. In the second step, with the step page set to the DataPage use the Connect-Java or Connect-EJB activity method, as appropriate, to call the connector rule. To continue this example, the connector rule would be configured to use the value from the AutoClaim property as the request.

25 Working with Java Objects Testing and Troubleshooting When testing the activities that interact with Process Commander Java pages, use the standard monitoring and debugging tools and practices as usual, as described in Testing Services and Connectors (available on the PDN). The Clipboard and Tracer tools, the Show-Page activity method, and so on work as expected. However, with a service such as JSR 94 that operates as an embedded Java process, you cannot use browser-based tools to examine the contents of a Java page. Instead, use a Java step in an activity to write diagnostic data to the Pega log where you can examine it. Insert a Java step that invokes the appropriate getxml Java method. For example: olog.infoforced(mysteppage.getxml()); Now when the activity runs, the contents of the named step page (Java page) appear in the console window where the application that invokes the service is running. For more information, see the Process Commander JavaDocs that describe the clipboard interface.

26 Working with the Java Pages Feature Additional Configuration Options 23 Additional Configuration Options Because there are exceptions to every rule, sometimes the results are not sufficient after the Import JavaBeans Accelerator generates the classes, properties, and Java wrapper classes for a Java object. For example, the accelerator may be unable to determine the data type for a property based on its definition in the source Java class. This section describes how to customize two things: how the accelerator implements properties that are themselves Java classes, and the Java wrapper classes. Data Types and Transforms When the Accelerators generate Process Commander classes and properties from a Java class, they implements properties that are themselves Java classes as embedded page properties in Process Commander. However, in some cases it is more appropriate to implement a Java class property as a single value property. For example, java.util.date should be interpreted as a single value property, not a page. To specify that a Java class should be interpreted as a single-value property rather than a page property, use the Process Commander Java Property Transform Registry to associate the Java class with a Java transform class. A Java transform class does two things: Specifies the Process Commander property type the Java class should be implemented as when the Accelerator creates classes and properties. Specifies how the Java wrapper classes get a single value from instances of the Java class and how they set single values to instances of the Java class The java.util.date Java class has such a registry entry, and all java.util.date properties are generated as single-value date properties. Example: Java Property Transform Registry for BigDecimal Imagine that you want to configure the Import JavaBeans Wizard to interpret BigDecimal objects (java.math.bigdecimal) as a single value property rather than a page. 1. First, you create the Java transform class. Figure 12 shows the Java source from a sample class named TransformBigDecimal: package com.bigbluesky.util.javaproperty; import java.math.bigdecimal; import com.pega.pegarules.pub.clipboard.clipboardproperty;

27 Working with Java Objects import com.pega.pegarules.pub.clipboard.javapropertytransform; public class TransformBigDecimal implements JavaPropertyTransform { public String instancetostring(clipboardproperty associatedproperty, Object sourceinstance) { // This will make sure we are given what we expect. // BigDecimal theinstance = (BigDecimal)sourceInstance; if (theinstance == null) { return ""; } } return theinstance.tostring(); public Object stringtoinstance(clipboardproperty associatedproperty, String sourcestring) { } } return new BigDecimal(sourceString); Figure 12. Example of a Java Transform Class 2. Put the Java transform class on the Process Commander runtime and compile time class paths. Go to the Pega Developer Network ( and locate the article PRKB About the Process Commander Version 5 Class Paths. Follow the instructions in the section titled Adding Third-Party jar Files and Java Class Files to the Class Paths. 3. From the Process Commander Class Explorer, select Data-Registry- JavaPropertyTransform and then click New. 4. In the New form, enter the name of the Java object type in the Registered Java Class field and click Create. In this case, you would enter: java.math.bigdecimal 5. On the Entry tab of the Java Property Transform form, select the appropriate data type in the Property Type field. In this case, you would most likely select Decimal. 6. In the Transform Class Name field, enter the fully-qualified name of the transform class. In this case: com.bigbluesky.util.javaproperty.transformbigdecimal (Figure 13).

28 Working with the Java Pages Feature Additional Configuration Options 25 Figure 13. Example Java Property Transform Registry for java.math.bigdecimal 7. On the History tab, enter a description in the Full Description and the Usage fields and then save the data object. Custom Wrapper Classes You can edit the generated Java wrapper classes or manually create your own if necessary. For example, if your Java classes are generated by a tool that does not implement the Java Beans coding standards by using the words get and set as the first part of the get and set methods, the Import Accelerator cannot recognize those methods as get and set methods. In such a case, you must edit the generated Java wrapper classes to call those methods. If you edit a generated wrapper class, move the wrapper to a different package. Specifically, remove the prpcwrapper level from the package name. Identify a new Java wrapper class whether it is one you created or a generated one that you edited to Process Commander as follows: 1. In the Process Commander browser interface, open the definition of the Process Commander class that you created the Java wrapper class for. 2. On the Advanced tab, in the Wrapper Name field, enter the fully qualified name of the Java wrapper class, and then click save. 3. Put the new Java wrapper class with the Java class it represents on the Process Commander runtime and compile time class paths. For help with this step, see the PDN article PRKB About the Process Commander Version 5 Class Paths. For information about the PRObjectWrapper interface of the Clipboard Java API, see the Process Commander JavaDocs.