test

Configuring Java CAPS Business Processes

Configuring Java CAPS Business Processes

The topics listed here provide links to task, conceptual and reference information for configuring Java CAPS Business Processes (BPs). If you have any questions or problems, see the Java CAPS web site at http://goldstar.stc.com/support.

Sun Business Process Manager (BPM) provides graphical editors to help you design and configure the models that depict your BPs using simple drag and drop procedures. These topics provide the background information and instructions you need to configure BPs.

Business Process and Element Properties Overview

You can define properties at two levels for a Business Process. The Business Process properties define the configuration of the entire Business Process. Modeling element properties define the configuration for specific elements in the Business Process. Certain properties for both the Business Process and the modeling elements are automatically defined as you create a Business Process.

Business Process Properties

Each Business Process has a set of properties that you allow you to configure the components and attributes of the Business Process model. These properties provide rapid creation and deletion of Business Process attributes. BPM uses this information to automatically create the appropriate Business Process attributes and the input and output structures for use in the Business Rule Designer. From the Business Process Properties window, you can edit the following types of properties:

Modeling Element Properties

Most modeling elements in a Business Process have a set of properties that you can modify from the element’s property sheet. You can specify a partner for an activity, define transactional support, bind correlation sets to an activity, define exceptions, create alerts and log messages, specify port types and partners, and more. The property sheets are accessed through the Show Property Sheet tool on the Business Process Designer toolbar, and the properties appear in the Business Process Designer to the right of the Business Process.

Configuring Business Properties

Many characteristics and components are automatically defined for you as you build a Business Process. Once you have all your modeling elements in place, view the properties of the Business Process to be sure it is configured correctly.

Perform any of the following functions to modify the configuration of a Business Process.

Configuring General Properties

The General page is the first page you see when you begin to edit Business Process properties. You can change the Business Process name, edit the target namespace, select the persistence state, and so on.

ProcedureTo configure general Business Process properties

  1. In the Project Explorer, right-click the Business Process and then click Properties.

    The Business Process Properties window appears with the General page displayed.

  2. Enter or select the values for the properties.

  3. Click OK to save your changes and exit the Business Process Properties dialog box, or select another tab to modify additional properties.

    Property 

    Description 

    Business Process Name

    The name of the Business Process. 

    Target Namespace

    The URL of the Business Process. 

    Persistence for Reporting

    An indicator of whether persistence for the Business Process is enabled. Note that a Business Process that contains only complex attributes and no simple attributes cannot be configured for reporting persistence.

    Lenient State

    An indicator of whether copy or write activities will be skipped when they throw an exception while the Business Process is running. This property specifically applies to Projects that are imported from Java CAPS 5.0.3 or earlier, or Business Processes from third-party vendors. These Projects do not contain the updated optional node assignments and throw an exception that stops the process instance. The possible values are: 

    • true - Adds the attribute 


       sbynruntime:processLenient="true"
 to the BPEL process tag. This in turn causes any copy or write activity that throws an exception to be skipped. A false is returned as an evaluation of the condition that threw the exception, overriding the settings you might have set for the switch block with the decision gate mapper.

    • false - No attribute is added. This is the default property. If you do not set this, any lenient flag on the individual copy or write activity has the same effect.

    Enable XA for Entire Business Process

    Enables transactional functionality for the entire Business Process rather than at the activity level. You can enable activity-level transactional functionality in the activity’s property sheet. 

    Theme

    The theme for the Business Process. The theme determines the look of the Business Process, including the icons used on the canvas. The default theme is BPMN; select Custom 1 for a different look.

    Max Concurrent Instances

    Specifies the maximum number of instances of each Business Process that can be processed by the BPM Engine at one time. If the engine receives additional requests, they are placed in a waiting state. As soon as any of the instances being processed is completed, one of the waiting requests is retrieved for processing.

    A higher value for this property results in higher memory requirements, though memory requirements are also based on the type of Business Process. Assuming that two Business Processes have the same value for this property, the Business Process that has more defined variables requires more memory. The suggested range is from 40 to 1000. 

Configuring Business Process Attributes

Business Process attributes, also known as containers, are data values used by a Business Process. They allow you to share data between activities in a Business Process and to move data to and from the components that implement those activities. For example, a Business Process attribute could store information such as customer names, addresses, order quantities, or item descriptions. Complex structures such as OTDs and Collaborations are represented automatically in the Project Explorer and are available for use in your Business Process.

Business Process attributes are used to pass values between the Business Process and external sources. Business Process attributes can also be assigned to specific activities. For example, the customer name is passed to an order process from the originating source. The customer name may be used by several of the activities in the Business Process and is included in the Business Process output.

BPM can pass all or part of a complex structure or it can even assemble a composite input to a component or web service from multiple Business Process attributes.

Creating a New Business Process Attribute

Attributes are automatically created for a Business Process as you add components to the process. You can create additional attributes to use in the Business Process.

ProcedureTo create a new Business Process attribute

  1. In the Project Explorer, right-click the Business Process and then click Properties.

  2. Click the Business Process Attributes tab.

  3. Click Create.

    The New Business Process Attribute dialog box appears.

  4. Enter information into the fields.

  5. Click Add.

  6. Click Close to return to the Business Process Properties dialog box.

    Field 

    Description 

    Name

    A name for the attribute. 

    Namespace

    The namespace of the attribute (select a value from the list of available namespaces). 

    Type

    The type of attribute you are adding (select a value from the list of available types). 

Editing a Business Process Attribute

Once you add a Business Process attribute, or one is added automatically, you can modify the attribute. If you only change the name of the attribute, you can specify that the rest of the Business Process be updated to reflect the change.

ProcedureTo edit a Business Process attribute

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Business Process Attributes tab.

  3. Select an existing attribute, and then click Edit.

  4. Modify the information in the fields.

  5. When you are done changing field values, click OK.

  6. If you changed the attribute name, the Confirm Refactoring dialog appears. Do one of the following:

  7. To update the name change across the Business Process, click Yes, Do Refactoring.

  8. To only change the name of the attribute, click No, Only Do Name Change.

    Note –

    To avoid this message in the future, select Don’t ask me again. The option you selected above will always be the default option.

  9. On the Properties window, click OK.

Deleting a Business Process Attribute

Once you add a Business Process attribute, or one is added for you, you can delete the attribute. Business Process attributes that are in use cannot be deleted. Attributes that are not in use can cause validation warnings, but typically will not stop the Business Process from running.

ProcedureTo delete a Business Process attribute

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Business Process Attributes tab.

  3. Click an existing attribute and then click Delete.

  4. Do one of the following:

    • Click OK to save your changes and exit the Business Process Properties dialog box.

    • Click Cancel if you deleted the attribute in error.

Configuring Partners

A partner is an abstracted identification for an external system that is linked with the Business Process in the Connectivity Map. Multiple activities can use the same external system, meaning multiple activities can have the same partner. By default, BPM assigns this identification to speed up and automate model development.

If you are invoking multiple components such as web services, JMS messages, or connectors such as eWays, you must create unique partner names for those components. Then, when you create the Connectivity Map, there will be a unique partner for each component rather than just one partner for multiple components. This enables you to successfully associate those components in your Deployment Profile and deploy your Project.

When creating a Business Process that will be used as a sub-process, you need to create a partner and associate it with the receive or receive and reply pair.

Creating a New Partner

Some partners are created for you automatically, but you can add new partners to use in your Business Processes as needed. Partners are associated with the activities in a Business Process. After you create a partner, associate it with an activity as described in Associating a Partner with an Activity.

ProcedureTo create a partner

  1. In the Project Explorer, right-click the Business Process and then click Properties.

  2. Click the Partners tab.

  3. Click New.

    The partner is added to the partner list.

  4. Double-click the partner name to rename the partner.

  5. Click OK.

Editing a Partner

Once you add a Business Process partner, or one is added for you, you can modify the partner name. When you change the name of a partner, you can specify that the rest of the Business Process be updated to reflect the change.

ProcedureTo edit a partner

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Partners tab.

  3. Double-click the name of the partner you want to modify, enter a new name, and then press Enter.

  4. Click OK.

    The Confirm Refactoring dialog appears.

  5. Do one of the following:

    • To update the name change across the Business Process, click Yes, Do Refactoring.

    • To only change the name of the partner, click No, Only Do Name Change.

      Note –

      To avoid this message in the future, select Don’t Ask Me Again. The option you selected above will always be the default option.

Deleting Partners

If you are not using a defined partner in the Business Process, you can delete the partner. Keeping partners that are not in use can result in validation warnings, which typically do not prevent the Business Process from running. You can only delete a partner that is not in use.

ProcedureTo delete a partner

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Partners tab.

  3. Click the partner name that you want to remove.

  4. Click Delete.

    The partner is removed from the partner list.

Associating a Partner with an Activity

Once you create a partner, you can associate it with an activity in the Business Process using the activity’s property sheet. You must create and select a partner for the receive and reply activities in a sub-process.

ProcedureTo associate a partner with an activity

  1. In the Business Process Designer, select an activity in the Business Process.

  2. In the Business Process Designer toolbar, click Show Property Sheet.

    The activity’s property sheet appears.

  3. Click the Partner field and select the partner from the drop-down list.

  4. Click Hide Property Sheet.

Defining Message Correlations

BPM provides the means for matching existing Business Process instances to messages that are arriving into a Business Process. Correlation keys are individual data values contained within both the incoming message and the BPM engine. When an arriving message contains a value that matches a configured correlation key, the unique Business Process instance associated with that value continues processing to the next step of the Business Process. You can perform the following tasks to define message correlation.

For an example of using message correlation, see Linking and Sequencing With Message Correlation.

Creating Correlation Keys

A correlation key is a value that you can define in a Business Process, like a purchase order number, that provides a way to associate and route information about specific Business Process instances. For asynchronous message exchange between components, you must implement correlation of the instance identification. An example of when you use asynchronous message exchanges is when you create a receive activity in the middle of a Business Process.

ProcedureTo create a correlation key

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Correlations tab.

  3. In the Correlation Keys section, click Create.

    The New Correlation Key dialog box appears.

  4. In the Name field, enter a name, or alias, for the correlation key.

  5. In the Select from Tree field, select a message type from the list to add to the alias. Select one or more correlation keys that comprise a unique identifier for a step in a Business Process.

  6. Click Add to save the new alias to the Selected Alias List.

    Note –

    The value for the Type field is automatically populated.

  7. Click OK.

Editing Correlation Keys

Once you create a correlation key, or one is created for you, you can modify the key by adding or removing message types.

ProcedureTo edit a correlation key

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Correlations tab.

  3. In the Correlation Keys section, click the key you want to modify and then click Edit.

  4. Do either of the following:

    • In the Select from Tree field, select a message type from the list to add to the alias, and then click Add.

    • In the Selected Alias List, select a message type you want to remove, and then click Remove.

  5. Click OK.

Deleting Correlation Keys

Once you create a correlation key, or one is created for you, you can delete the key if it is no longer used. Some correlation keys cannot be removed.

ProcedureTo delete a correlation key

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Correlations tab.

  3. In the Correlation Keys section, select the key you want to delete, and then click Delete.

  4. Click OK.

Adding Correlation Sets

Correlation sets are groups of properties (correlation keys) shared by all messages in the group. A correlation set matches messages and conversations with a Business Process instance. For example, you might want to assign a purchase order number and an invoice number to a transaction so all information about the purchase and payment are associated.

Note –

When naming correlation sets, use unique names. Duplicate correlation set names cause indexing problems in the monitoring and recovery database. Consider including the Business Process name in the correlation set name to ensure uniqueness.

ProcedureTo add a correlation set

  1. Click the Correlations tab.

  2. In the Correlation Set section, click Create.

    The New Correlation Set dialog box appears.

  3. In the Name field, enter a name for the new correlation set.

  4. In the Select from List box, select the correlation keys you want to add to the correlation set. Use the Ctrl key to select multiple keys.

  5. Click the right-arrow button to move your selections to the correlation set.

  6. Click OK.

Editing Correlation Sets

Once you create a correlation set, or one is created for you, you can modify the correlation set by adding or removing correlation keys.

ProcedureTo edit a correlation set

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Correlations tab.

  3. In the Correlation Sets section, click the correlation set you want to modify and then click Edit.

    The Edit Correlation Set dialog box appears.

  4. Do either of the following:

    • In the Select from List, select a key you want to add, and then click Add.

    • In the Selected Keys for correlation set list, select a key you want to remove, and then click Remove.

  5. Click OK.

Deleting Correlation Sets

Once you create a correlation set, or one is created for you, you can delete the set if it is no longer used. Some correlation sets cannot be removed.

ProcedureTo delete a correlation set

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Correlations tab.

  3. In the Correlation Sets section, select the set you want to delete, and then click Delete.

  4. Click OK.

Binding Correlation Sets to Receive Activities

When you use one or more correlation sets within a Business Process, you must bind the sets to a receive activity and initialize the sets before they are used. This ensures that the correlation set is created in memory before it is used.

If you choose to initialize a set within an activity, you must either choose to use both Business Process attributes or identify which Business Process attribute to use.

ProcedureTo bind a correlation set to an activity

  1. In the Business Process Designer, select an activity.

  2. On the Business Process Designer toolbar, click Show Property Sheet.

  3. Click in the Use Correlations field, and then click the ellipsis (...).

    The Use Correlations dialog box appears.

  4. Click Add.

    The Assign Correlation Set dialog box appears.

  5. In the Select From List panel, select the names of the correlation sets you want to bind to the activity, and then click Add.

  6. Click OK.

  7. On the Use Correlations dialog box, click OK.

Linking and Sequencing With Message Correlation

Linking and Sequencing

You can impose conditions on a set of messages, process a group of messages together, or make a decision contingent upon the receipt or non-receipt of all messages of a certain type. By using BPM’s linking and sequencing capabilities, you can sort messages into separate containers and execute Business Rules on containers of messages rather than on the individual messages. A container’s link identifier (a correlation ID) differentiates containers and links the messages identified with that container.

When BPM retrieves a message, it correlates the received message to a Business Process instance. If BPM finds a correlation match, it stores the message in the container for that Business Process. Otherwise, it instantiates a new Business Process instance.

For example, a Business Process handles HL7 messages that have been broken up with a continuation pointer. The Business Process contains logic that detects this condition and defers processing the HL7 message until it has been completely reassembled. The container qualifies as “full” when all HL7 messages for the same continuation pointer have been received.

Correlation Example

In this example, the Business Process expects to receive three course grades in order to qualify a student for further studies. The courses are Math, English, and Computer Science. Each message contains the course grade, the course type, and a correlation ID to indicate where the message belongs.

A new message arrives with a correlation ID of 101. First, BPM correlates the message to see if there is a match on the newly arrived message. Since this is the first message, there is no match and a new instance is created. The second message has a correlation ID of 101. BPM correlates the message and finds a match, so the message is forwarded to the same business instance as the first message. The third message has a Correlation ID of 102. Because there is no correlation match, the message is forwarded to a new business instance. This continues until a grade is received for each course type.

This process can continue depending on conditions you set based on count or time expiration. A sample Business Process is shown below for message correlation. The main Business Process uses a File eWay to read a DTD-based message, unmarshal the message, and then invoke a sub-process passing in the unmarshaled message.

The sub-process receives the unmarshaled message using an event-based decision and timer events in a while loop. The while loop continues until either a specified count has been reached or the time has expired. When messages are received, they are stored in containers until the requirements are met.

The timer event sets an expiration time. If time expires, the loop condition is set to false to terminate the loop. If a message is received, the message counter is incremented and, if the maximum number of messages have been received, the loop is terminated. When processing is complete, the date is written to a file.

Viewing WSDL Files

Web Services Description Language (WSDL) is an XML-based language used to describe business services. WSDL provides a way for individuals and other businesses to electronically access those services. WSDL files are used to invoke and operate web services. They can be used for web services on the Internet and to access and invoke remote applications and databases.

The WSDL page provides a listing of all loaded WSDL files, which represent predefined Business Process attributes for use in a Business Process. For troubleshooting purposes, the WSDL page provides a listing of all unresolved target namespaces and also provides viewing access to all loaded WSDL files.

ProcedureTo view a WSDL file

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the WSDL tab.

  3. Select a WSDL file from the list and then click View.

    The WSDL Viewer appears.

    Note –

    From the WSDL Viewer, you can copy and paste WSDL code to a text file. You cannot edit code in the WSDL Viewer.

Configuring Grid Properties

The Grid page provides a collection of formatting attributes for the Business Process Designer. The grid can help you align the components of a Business Process by providing a visual guide or automatic alignment. Grid properties can also be accessed by right-clicking inside the Business Process Designer canvas.

ProcedureTo edit Grid properties

  1. In the Project Explorer, right-click the Business Process, and then click Properties.

  2. Click the Grid tab.

  3. Enter or select the values for the properties.

  4. Click OK.

    Property 

    Description 

    Grid Width

    The distance from vertical line to vertical line in pixels. 

    Grid Height

    The distance from horizontal line to horizontal line in pixels. 

    Grid Color

    Displays a dialog box with three tabs for choosing the color of the grid lines: 

    • Swatches - An array of colors from which to choose.

    • HSB - A color selector based on hue, saturation, and brightness.

    • RGB - A color selector based on 256 brightness levels of red, green, and blue.

    Grid Thickness

    The thickness of the grid lines. You can select Thin, Medium, or Thick. 

    Grid Style

    The style of the grid lines. You can select Solid, Dashed, or Dotted. 

    Show Grid

    Shows or hides the grid lines. Select this check box to show the grid lines. 

    Snap to Grid

    Activates or deactivates “Snap to Grid”. When activated, this setting forces objects to gravitate toward the closest grid line. 

Configuring Modeling Element Properties

Many modeling element properties are automatically defined for you as you build a Business Process. Once you have all your modeling elements in place, view the property sheets for the elements to be sure they are configured correctly. The property sheets are accessed through the Show Property Sheet tool on the Business Process Designer toolbar, and the properties appear to the right of the Business Process.

Table 1 lists and describes all of the properties that appear on the properties sheet, but different types of elements have different combinations of properties. Some properties do not appear for certain elements, some properties are read-only for certain elements, and not all properties are required.

Table 1 Activity and Link Properties

Property 

Description 

Name

The name of the selected element. 

Properties

For decision elements only, opens the Decision Gate Properties dialog box, which allows you to view and modify the logic for the decision activity.

Timeout

For wait activities only, opens the Timeout dialog box, which allows you to set timeout periods based on deadline or duration.

Priority

For user activities only, the priority of the activity. 

Task Type

For user activities only, the type of task. If you change the name of the activity, this value is automatically updated to match.

If Expression Evaluation Fails

For while elements only, an action to perform when the while loop fails. You can specify to throw an exception, return Boolean true, or return Boolean false.

Scope

For compensation elements only, the name of the scope with which the compensation element is associated.

Partner

The name of the partner to associate with the activity.

Port Type

The name of the port type for the specified partner. This field is disabled for some activities.

Operation

The type of operation associated with the port type. This field is disabled for some activities. 

Exception Name

The name of the exception to throw for the element. You can select from a list of exception names (exceptions must be predefined for the Business Process). 

Input

The name of the attribute containing the input for the activity.

Output

The name of the attribute containing the output for the activity. 

Create Instance

For receive activities and event-based decisions only, an indicator of whether to create a new instance for the activity.

Use Correlations

An indicator of whether to use a correlation set for the activity. Use the dialog box for this property to bind a correlation set to the activity (for more information, see Defining Message Correlations).

Transaction Support

An indicator of whether and how the activity is defined for transactional (XA) support. Select one of the following options:

  • Participates - The activity is part of a Business Process that is configured for XA support, and is itself configured for XA support. Use this option for invoke activities only.

  • XA - The activity is configured for XA support in a Business Process that is not configured for XA support. Use this option for receive and invoke activities and message-based events.

    Leave this property blank if XA transactions are not supported. For more information, see Configuring Business Processes for XA Transactions.

Pass By Value

An indicator of whether the activity attributes are passed by value or passed by reference. 

Alert Properties

Accesses the Specify Alerts dialog box, which allows you to define specific alerts for the modeling element. For more information, see Adding Alerts to a Modeling Element.

Logger Properties

Opens the Specify Log Messages dialog box, which allows you to define specific logger messages for the modeling element. For more information, see Adding Logger Messages to a Modeling Element.

Adding Logging and Alerts to an Element

You can initiate custom logging and alert entries from a Business Process modeling element. These entries can then be viewed in the logging and alerts pages for the Business Process in Enterprise Manager.

Adding Alerts to a Modeling Element

Java CAPS allows you to initiate alert entries from a Business Process element. You can define the following types of alerts (from most to least severe): critical, major, minor, warning, and information. The alert nodes take a Boolean data type, but you can specify that the data types be automatically converted when you define the mapping.

ProcedureTo add an alert to a modeling element

  1. Open the Business Process containing the element to which you want to add an alert entry.

  2. In the Business Process Designer, select the element.

  3. In the Business Process Designer toolbar, click Property Sheet.

    The properties for the element appear to the right of the Business Process.

  4. Click in the Alert Properties field, and then click the ellipsis (...).

    The Specify Alerts dialog box appears.

  5. Define the alert using the available methods.

  6. When you are finished defining the alert, click OK.

Adding Logger Messages to a Modeling Element

Java CAPS allows you to initiate logging entries from a Business Process element. You specify one of the log4j log levels: FATAL, ERROR, WARN, INFO, or DEBUG. When you view the log entries in Enterprise Manager, these log levels are converted to the corresponding JDK log levels. Table 2 describes the log level mapping from most to least severe.

Table 2 log4j to Java Log Level Mapping

log4j Log Level

JDK Log Level

FATAL

SEVERE

ERROR

SEVERE

WARN

WARNING

INFO

INFO

DEBUG

FINE

The logger level nodes take a Boolean data type, but you can specify that the data types be automatically converted when you define the mapping.

ProcedureTo add a logger message to a modeling element

  1. Open the Business Process containing the element to which you want to add a logger entry.

  2. In the Business Process Designer, select the element.

  3. In the Business Process Designer toolbar, click Property Sheet.

    The properties for the element appear to the right of the Business Process.

  4. Click in the Logging Properties field, and then click the ellipsis (...).

    The Specify Log Messages dialog box appears.

  5. Define the log message using the available methods.

  6. When you are finished defining the log message, click OK.

Configuring Business Processes for XA Transactions

Distributed Transaction Processing (DTP), more commonly known as XA, is a proposed W3C standard for keeping multiple transaction system components secure during short-lived and long-lived distributed transactions. This helps to ensure the integrity of distributed transactions.

XA transactions fall into two broad categories: short-lived and long-lived. A short-lived XA transaction is simpler, quicker, and requires fewer system resources than a long-lived transaction, but it remains Atomic, Consistent, Isolated, and Durable (ACID) throughout the transaction. A long-lived XA transaction is generally more complex, more distributed, and longer-running. In BPM, short-lived XA generally applies to a whole Business Process (whole Business Process XA), and long-lived XA generally applies to an individual Business Process activity (activity-level XA).

This section provides details and procedures for enabling XA support for whole Business Process XA as well as activity-level XA using BPM. For details about getting started using XA, see http://www.w3.org.

Enabling XA Support for a Whole Business Process

Whole Business Process XA for a Business Process is configured from the General page of the Business Process Properties dialog box. The following procedure provides the steps for enabling whole Business Process XA.

ProcedureTo enable XA transactions for a whole Business Process

  1. In the Project Explorer, right-click a Business Process and then click Properties.

    The Business Process Properties window appears with the General page displayed.

  2. In the Enable XA for Entire Business Process drop-down list, click Yes.

  3. Click OK.

  4. In the Business Process Designer toolbar, click Show Property Sheet.

  5. In the Business Process Designer, click an invoke activity.

  6. In the Transaction Support property of the property sheet, select Participates.

  7. Repeat steps 5 and 6 for any other invoke activities in the Business Process.

    Note –

    If you do not need to use persistence for other Business Processes in your Project, you do not need to enable XA for the entire Business Process.

Enabling XA Support for an Individual Activity

BPM allows you to enable XA at the activity level for your Business Process. This is handled in the property sheet of any receive activity, invoke activity, or pick activity (OnMessage). The following procedure provides the steps for enabling activity-level XA.

Note –

In order to enable activity-level XA, you must deploy the Business Process using persistence.

ProcedureTo enable a XA transactions for an individual activity

  1. In the Business Process Designer toolbar, click Show Property Sheet.

  2. Select a receive activity, invoke activity, or pick activity (OnMessage).

  3. In the Transaction Support property on the property sheet, select XA.

  4. For each activity to be XA-enabled, repeat steps 2 and 3.

Persisting Reporting Data for Business Processes

When the BPM Engine is configured for persistence, general information about all Business Processes running on the engine is stored in the database. You can store and monitor additional information about a Business Process by configuring it for reporting persistence. You need to configure reporting persistence for each Business Process individually; the detailed information is only stored for those processes that are configured for it. This information can be accessed from the Enterprise Manager.

When you configure a Business Process for reporting persistence, a database script is generated that creates one database table for the Business Process. This table is populated with data from attributes of the WSD Object that are simple types (such as strings, integers, and so on). Data corresponding to complex attributes is not persisted, and a Business Process must include at least one simple attribute in order to be configured for persistence.

After you create your Business Processes, perform the following steps for each Business Process you want to enable for reporting persistence.

Scripts are also provided for you to uninstall the database components created for a Business Process.

Configuring a Business Process for Reporting Persistence

Reporting persistence for a Business Process is configured in the properties of the Business Process.

ProcedureTo configure a Business Process for reporting persistence

  1. In the Project Explorer of NetBeans, right-click the Business Process and then click Properties.

  2. On the General page of the Business Process Properties window, select Yes for the Persistence for Reporting option.

  3. Repeat the above step for each Business Process you want to configure for reporting persistence.

  4. Select Save All.

    A folder named Database Scripts appears under the Business Process.

Configuring Database Connection Information

In order to connect with the database to run the scripts, you need to specify the database connection information for the scripts.

ProcedureTo configure database connection information

  1. Right-click the Database Scripts folder under the Business Process, and then click Properties.

  2. Enter the properties.

  3. Click OK.

    Property

    Description 

    Database Type

    The database vendor and version you are using. 

    JDBC URL

    The URL to connect with the database. Enter one of the following: 

    • For Oracle: jdbc:SeeBeyond:oracle://<host>:<port>;SID=<SID>

    • For Sybase: jdbc:SeeBeyond:sybase://<host>:<port>

    • For SQL Server: jdbc:SeeBeyond:sqlserver://<host>:<port>;DatabaseName= <dbname>

    • For DB2: jdbc:SeeBeyond:db2://<host>:<port>;DatabaseName=<SID>;collectionId=JDBCPKG;packageName=JDBCPKG;embedded=true;createDefaultPackage=FALSE

      where <host> is the machine on which the database resides, <port> is the port number on which the database is listening, and <SID> and <dbname> are the name of the database.

    User

    The login ID of the user created by the monitoring and recovery database scripts. You can find the user name in the scripts in the Project Explorer under CAPS Components Library > Sun Business Process Manager > Run Database Scripts > Database Scripts.

    Password

    The password for the user created by the monitoring and recovery database scripts. 

Creating a Business Process Database Table

Once you configure the database connection information, you can run the database script. This procedure creates the table required for reporting on the Business Process. The name of the table created is unique to each Business Process, and begins with the first few characters of the Business Process name followed by a series of numbers and a version number.

Note –

Before you can perform this step, the monitoring and recovery database must be created and running. The BPM Engine must be configured for persistence in order for information to be stored in the Business Process table. Both of these procedures are described earlier in this chapter.

ProcedureTo create a Business Process database table

  1. In the Project Explorer, expand the Business Process.

  2. Expand the Database Scripts folder.

  3. From the Database Scripts folder, right-click the database install file appropriate to your database vendor, and then click Run.

Dropping a Business Process Database Table

BPM provides a simple way to uninstall the database tables created by the Business Process database installation script.

ProcedureTo drop a Business Process database table

  1. In the Project Explorer, expand the Business Process.

  2. Expand the Database Scripts folder.

  3. Right-click the appropriate uninstall script, and then click Run.

Configuring BPM for the OCI Driver

If you are using Oracle for the monitoring and recovery database, you can use Oracle’s Type 2 driver, the Oracle Call Interface (OCI) driver. This requires some additional steps. BPM typically uses a DataDirect® driver to establish a database connection and interact with the database server. This section provides the requirements and instructions for enabling and configuring BPM for the OCI driver.

The OCI driver works in conjunction with the monitoring and recovery database only. The Worklist Manager uses the DataDirect driver only.

System Requirements for the Oracle OCI driver

The Oracle OCI driver is also called the thick driver because of the extensive native code it uses to communicate with the database. OCI is written in C; all of its Java calls use JNI to direct the calls to the C layer. The C layer communicates with the database and returns the results to the Java layer.

The library to map the Java calls to C calls is installed with the Oracle client’s installation. To enable monitoring and recovery persistence with OCI, you must install the Oracle client software.

Before You Begin

Before configuring the OCI driver, make sure the following are in place.

Implementing the OCI Driver

Implementing the OCI driver involves the following tasks:

Copying the OCI Driver Library Files

In order for BPM to use the OCI driver, the library file must reside in the Logical Host’s library directory.

ProcedureTo copy the OCI driver library files

  1. Install the Oracle client on the system where Logical Host resides.

  2. Define the monitoring and recovery database in tnsnames.ora.

  3. Copy ojdbc14.jar (for JDK 1.4 or later) or classes12.jar (for JDK 1.2 and 1.3) from the /jdbc/lib subdirectory in the Oracle client installation to the /lib subdirectory in the Logical Host domain-specific directory. For example,

    copy from oracle_home\jdbc\lib

    to logical_host\is\domains\domain1\lib 


    
    		

    

    

    
Note – 

    The location of the files in the Oracle installation varies depending
on the version of Oracle being used and whether it is a client or server installation.
    


    


    4. 


  4. 

    Restart the Logical Host instance to load the driver classes.
    


    5. 




Setting up the Environment


To enable the OCI driver with the BPM Engine, set the following environment
variables. 


Note – 

oracle_home refers to the directory
where the Oracle client or database is installed. For example,  C:\oracle\ora92 or  /home/oracle/orahome. This folder contains
sub-folders such as bin, network, jdbc, jlib, and lib.  





For Windows operating systems:





For Linux and Unix operating systems (except
HPUX and AIX):




For HP-UX:



For AIX:



Configuring the BPM Engine to use the Oracle OCI
Driver


You must configure the BPM Engine to use the OCI driver instead of the
default thin driver. This is configured in the Environment Explorer in the
integration server properties sheet.



ProcedureTo configure the engine to use the Oracle OCI driver
    


  1. 

    In the Environment Explorer, right-click the integration or application
server, and then click Properties.
    


    2. 


  2. 

    Click BPM Engine Configuration.
    


    3. 


  3. 

    On the Properties dialog box, enter the service name in the Oracle
Net Service Name field.
    


    The value to enter is the TNS name configured
in the tnsnames.ora file (located at <oracle_home>/network/admin). The following example shows a typical TNS name configuration
where ORCL.STC.COM is the Oracle Net Service
Name.
    


    

    


    

    ORCL.STC.COM =
  (DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = MyHost)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVICE_NAME = orcl)
    )
    
    		

    

    

    4. 


  4. 

    Fill in the properties.
    


    5. 


  5. 

    Click OK.
    


    The following table describes
the fields you must configure in the BPM Engine Configuration properties.
    



    


    


    
Field
    

    		

    Description 
    

    		

    

    


    


    
Persistence
Mode
    

    		

    An indicator of whether persistence is enabled. Select one of the Persist to Database options to enable persistence
in BPM.
    

    		

    


    


    
Database
    

    		

    The database platform in use. Select the correct version of Oracle to
enable the OCI feature. 
    

    		

    


    


    
Database
Host
    

    		

    The name of the computer on which the Oracle database resides. 
    

    		

    


    


    
Database
Port
    

    		

    The port on which the Oracle database is listening. The default is 1521. 
    

    		

    


    


    
Oracle
Net Service Name
    

    		

    The TNS name of the database (from the tnsnames.ora). The BPM Engine uses the OCI driver if this property is populated.
Otherwise, the BPM Engine uses the default DataDirect driver.
    

    		

    


    


    
Database Instance/Schema
    

    		

    The name of the database. 
    

    		

    


    


    
Database
User
    

    		

    The user name to access the monitoring and recovery tables. 
    

    		

    


    


    
Password
    

    		

    The Password to access the monitoring and recovery tables. 
    

    		

    

    

    


     

    

     

    

    6. 




Implementing Transparent Application Failover


Oracle RAC is an Oracle database that has two or more instances accessing
a shared database using cluster technology. A cluster is a group of machines
(or nodes) that work together to perform the same task. To support this architecture,
two or more machines that host the database instances are linked by a high-speed
interconnect to form the cluster. The interconnect is a physical network used
as a means of communication between each node of the cluster.


After Oracle RAC is installed, the Transparent Application Failover
(TAF) feature can be configured to ensure the highest levels of availability.
TAF compliments all levels of the availability hierarchy. Applications and
users are automatically and transparently reconnected to another system, applications
and queries continue uninterrupted, and the login context is maintained. Oracle
Net Services is configured to allow the listener on each database instance
of RAC to failover in case of failure.


Note – 
Setting up the  Oracle RAC/OPS system to test the TAF feature
is beyond the scope of this document. Please contact your DBA to set up the
 Oracle RAC/OPS server with the configuration in the tnsnames.ora and listener.ora files. 




The OCI driver works in conjunction with the BPM Engine only. The Worklist
Manager uses the DataDirect driver only.



ProcedureTo implement transparent application failover


    


  1. 

    Set up the Oracle RAC server with the multiple hosts or instances
sharing the same data storage. 
    


    For information about configuring tnsnames.ora to enable the TAF feature when using the OCI driver,
see Before You Begin.
    


    2. 


  2. 

    If you have not already done so, install Oracle client locally
where the Logical Host is running. 
    


    Oracle client must be installed
for OCI to work. Since the OCI driver establishes connectivity to the database
based on a native C call, the same version of the Oracle client must be installed
as packaged with BPM. Version conflicts for OCI would result in problems configuring
the OCI driver with BPM.
    


    3. 


  3. 

    Configure the tnsnames.ora file for TAF.
    


    Below is an example of a tnsnames.ora file configured
for a transparent application failover (TAF).
    


    
Option 1: Connect time FAIL OVER and TAF
    


    

    


    

    MY_CLUSTER =
  (DESCRIPTION =
    (FAILOVER = ON)
    (LOAD_BALANCE = OFF)
    (ADDRESS_LIST =    
      (ADDRESS = (PROTOCOL = TCP)(HOST = Node1)(PORT = 1521))
      (ADDRESS = (PROTOCOL = TCP)(HOST = Node2)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVICE_NAME = my_cluster.my_company.com)
      (FAILOVER_MODE =
        (TYPE = SELECT)
        (METHOD = PRECONNECT)
        (BACKUP=Node2)
      )
    )
  )
    
    		

    

    

    
Option 2: TAF configuration
    


    

    


    

    MY_CLUSTER =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = Node1)(PORT = 1521))
    (CONNECT_DATA =
      (SERVICE_NAME = my_cluster.my_company.com)
      (FAILOVER_MODE =
        (TYPE = SELECT)
        (METHOD = PRECONNECT)
         (BACKUP = Node2)
       )
    )
  )
    
    		

    

    

    In the above configuration, MY_CLUSTER has the knowledge of the two
nodes that are configured to act as a cluster. The cluster should be configured
to share the same disk by RAC/OPS.
    


    In option 1, FAILOVER is set
to ON and LOADBALANCE is set to OFF. This is the configuration for a connect
time failover. In connect time failover, when the OCI driver tries to connect
to Node1 and determines that the node is down, it connects to the other host
in the Address list (Node2). Option 2 is shown only to illustrate configuring
just the TAF feature in the OCI client. For BPM, both the connect time failover
and the TAF configuration is required.
    


    Configuring the TAF option
involves adding Oracle Net parameters to the tnsnames.ora file
and the use of parameter values to ascertain the next step in the failover
process when one of the participating nodes encounters failure. The parameter
that drives the TAF option is the FAILOVER_MODE under the CONNECT_DATA section
of a connect descriptor. By using one or more of the following parameters,
the full functionality of TAF can be achieved.
    



    


    


    
Parameter

    

    		

    Description 
    

    		

    

    


    


    BACKUP 
    

    		

    Specifies a different net service name to be used to establish the backup
connection. A backup should be specified when using PRECONNECT to pre-establish
connections. Specifying a BACKUP is strongly recommended for BASIC methods;
otherwise, reconnection might first attempt the instance that has just failed,
adding additional delay until the client reconnects. 
    

    		

    


    


    TYPE 
    

    		

    Specifies the type of failover. Three types of Oracle Net failover functionality
are available to the Oracle Call Interface by default. 
    


      

    • 

      
SESSION– Fails over
the session. With this option only a connection is established and no work
in progress is transferred from the failed instance to the available instance.
      



      • 

    • 

      
SELECT– Enables a
user with open cursors to continue fetching on them after failure. Oracle
Net keeps track of any SELECT statements issued in the current transaction,
as well as how many rows have been fetched back to the client for each cursor
associated with a SELECT statement. If the connection to the instance is lost,
Oracle Net establishes a connection to a backup instance, re-executes the
SELECT statements, and positions the cursors so the client can continue fetching
rows as if nothing had happened. However, no DML operations are transferred.
      



      • 

    • 

      
NONE– No failover
functionality is implemented (this is the default).
      



      • 

    


    		

    


    


    METHOD 
    

    		

    Determines the speed of the failover from the primary to the secondary
or backup node. 
    


      

    • 

      
BASIC– Establishes
connections at failover time.
      



      • 

    • 

      
PRECONNECT– Pre-establishes
connections. If this parameter is used, connection to the backup instance
is made at the same time as the connection to the primary instance.
      



      • 

    


    		

    


    


    RETRIES 
    

    		

    Specifies the number of times to attempt to connect to the BACKUP node
after a failure before giving up. 
    

    		

    


    


    DELAY 
    

    		

    Specifies the amount of time in seconds to wait between attempts to
connect to the BACKUP node after a failure before giving up. 
    

    		

    

    

    


     

    

     

    

    4. 



Troubleshooting


To aid in troubleshooting, common error messages and resolutions are
described below.

Table 3  Troubleshooting Windows Systems









Error Message 




Checklist 












Exception in thread "main" java.lang.UnsatisfiedLinkError: no ocijdbc9.dll
in java.library.path 




    

  • 

    Is the oracle_home environment
variable set?
    



    • 

  • 

    Is oracle_home\bin added to the
system path?
    



    • 

  • 

    Is oracle_home\lib added to the
system path?
    



    • 












Exception No Such Method : make_c_state error 




    

  • 

    Is oracle_home\lib added to the
system path?
    



    • 

  • 

    Is the JDBC Oracle client driver version used to connect to
the database different from the application server version?
    



    • 












Exception in thread "main" java.lang.NoSuchFieldError: envCharSetId 




    

  • 

    Is oracle_home\lib added to the
system path?
    



    • 

  • 

    Is the JDBC Oracle client driver version used to connect to
the database different from the application server version?
    



    • 












 

Table 4  Troubleshooting Linux/Unix Systems









Error Message 




Checklist 












Exception in thread "main" java.lang.UnsatisfiedLinkError: no ocijdbc9
in java.library.path 




    

  • 

    Is the oracle_home environment
variable set?
    



    • 

  • 

    Is oracle_home/lib added to LD_LIBRARY_PATH?
    



    • 












Exception in thread "main" java.lang.NoSuchFieldError: envCharSetId 




    

  • 

    Is the oracle_home environment
variable set?
    



    • 

  • 

    Is the JDBC Oracle client driver version used to connect to
the database different from the application server version?
    



    • 












make_c_state error 




    

  • 

    Is oracle_home/bin added to the
system path?
    



    • 

  • 

    Is the JDBC Oracle client driver version used to connect to
the database different from the application server version?
    



    •