Using Application Views in the Studio

This section presents the following topics:

• Before You Begin

• Task 1: Set Up a Task Node to Call an Application View Service

• Task 2: Set Up an Event Node to Wait for a Response from an Asynchronous Application View Service

• Task 3: Create a Workflow Started by an Application View Event

• Task 4: Set Up an Event Node to Wait for an Application View Event

• Handling Application View Local Transactions in Workflows

 

---

Before You Begin

After you create all the Application View services and events that are required for your enterprise, you can use the resulting Application Views to execute your business processes. The simplest way to do this is by using the WebLogic Integration Studio to design business process workflows that use your Application View services and events.

The WebLogic Integration Studio is a graphical user interface (GUI) for designing business process workflows. These workflows can include Application View services and events defined using WebLogic Integration. For details, see Using the WebLogic Integration Studio.

Before you can invoke an Application View service or receive an Application View event in the WebLogic Integration Studio, you must make sure the following prerequisites have been met:

• You have created an Application View and defined services and events for it.

• The Application View and its adapter are functional and saved. If you plan to call Application View services and events from a running workflow, the Application View must be deployed, as well.

• BPM and application integration functionality is available.

• The application integration plug-in has been loaded.

• You have received information about the required business logic for the workflows you are defining from the appropriate business analyst.

• A workflow template definition is open.

Workflow Setup Tasks

The following sections describe four tasks you may perform to set up your workflow to use Application View services and events:

• Task 1: Set Up a Task Node to Call an Application View Service

• Task 2: Set Up an Event Node to Wait for a Response from an Asynchronous Application View Service

• Task 3: Create a Workflow Started by an Application View Event

• Task 4: Set Up an Event Node to Wait for an Application View Event

You can perform any combination of these tasks to create your own workflows.

This document does not fully explain how to use the business process management (BPM) functions provided by WebLogic Integration; for complete information, see Learning to Use BPM with WebLogic Integration.

 

---

Task 1: Set Up a Task Node to Call an Application View Service

In your organization, there may be situations in which you want to call an Application View service from within a workflow. To make this type of call possible, add a task node to the workflow, then add an appropriate Application View Service action to the task node. Once the workflow is saved and activated, the Application View service is called whenever the task node is executed.

Steps for Setting up a Task Node to Call an Application View Service

To create a task node that calls an Application View service, complete the following procedure:

1. In the WebLogic Integration Studio, open a template definition. The Workflow Design window is displayed.

 

2. If there is no task node, create one.

3. Double-click the task node that calls the Application View service. The Task Properties dialog box is displayed.

   
    

4. In the Actions area, select the tab from which you want the service to be called. Your selection depends on your business processes.

5. Click Add. The Add Action dialog box is displayed.

   
    

6. Choose AI  Actions—>Call Application View Service and click OK. The Call Service dialog box is displayed.

   
    

7. In the navigation tree, find and select the service you want to call.

   The navigation tree organizes Application View services by folder (for example, Test2) and Application View (for example, Test). All Application View services are at the lowest level of the navigation tree.

   Note: To check for recently saved Application Views and events at any time, select the Refresh  Tree option.
   
   If the navigation tree is missing or appears too narrow, it may include an overly long XML or string variable name. Try shortening the names of your XML or string variables.

8. From the Request Document Variable list, select an existing XML variable that contains input data for the Application View service.

9. If no suitable XML variable exists, select <new> to open the Variable Properties dialog box, in which you can create a new XML variable.

   
    

10. In the Name field, enter a name for the variable.

11. In the Type menu, select XML. (XML is the only option on this menu.)

    For details about defining new variables, see Using the WebLogic Integration Studio.

12. Click OK to return to the Call Service dialog box.

13. To create a service request template for the specified service, or to modify an existing service request template, select one of the following:

    • Set—to create a template

    • Edit—to modify an existing template

    Whichever option you select, the Service Request Template dialog box is displayed.

    
     

    The Service Request Template dialog box displays the template to be used for all service requests of the type specified in step 11. This template is based on the input schema for the service.

    When this action is executed, the template data is assigned to the specified request document variable and used as the input document for the service. This template overrides any previous setting for the variable. (If you set up a template and then want to use the previous input variable instead of the new input variable, the easiest way to do this is to delete the Call Application View Service and recreate it.)

    For details about using the Service Request Template dialog box, see Using the WebLogic Integration Studio.

14. Click OK to return to the Call Service dialog box.

15. If you need to examine the XML schema of the input document, select View Request Definition. The View Definition dialog box is displayed.

    
     

16. Click Close when finished.

17. Call the Application View synchronously or asynchronously by selecting Synchronous or Asynchronous, respectively.

    Note: When a node calls a service synchronously, the workflow waits until the service returns a response document before continuing. If a node calls a service asynchronously, the workflow continues processing.

18. For synchronous services that require storage of the response, select a predefined XML variable from the Response Document Variable list. When the Studio receives a response from the Application View service, the response is stored in the response document variable. If you do not care about the response data, leave this field empty.

19. If no suitable XML variable exists, select <new> to open the Variable Properties dialog box, in which you can create a new XML variable. See step 9. in Steps for Setting up a Task Node to Call an Application View Service for details.

    For details about defining new variables, see Using the WebLogic Integration Studio.

20. If you need to examine the XML schema of the response document, select View Response Definition. The View Definition dialog box is displayed.

    
     

21. Click Close when finished.

22. For asynchronous services that require storage of the request ID, select a predefined string variable from the Request ID Variable list.

23. If no suitable string variable exists, select <new> to open the Variable Properties dialog box, in which you can create a new string variable.

    
     

24. In the Name field, enter a name for the variable.

25. In the Type menu, select String. (String is the only option on this menu.)

    For details about defining new variables, see Using the WebLogic Integration Studio.

    Note: When you set up a task node to call an asynchronous Application View service, the result is returned to the Studio. The workflow identifies this response using the request ID variable you selected. To set up an event node to receive the response, make sure to use the same request ID variable for the event node. For more information about creating such an event node, see Task 2: Set Up an Event Node to Wait for a Response from an Asynchronous Application View Service.

26. Click OK to save the action.

27. In the Task Properties dialog box, click OK to save the node.

 

---

Task 2: Set Up an Event Node to Wait for a Response from an Asynchronous Application View Service

This section explains how to receive an asynchronous Application View service response and handle any errors it may contain.

In a workflow, whenever an action calls an Application View service asynchronously, the Application View service returns a response. If you need the response, you must set up a corresponding asynchronous event node to wait for it. This section describes a highly simplified scenario in which an event node receives an Application View service response without checking for errors.

To set up an asynchronous event node to wait for a response from an asynchronous Application View service, create an event node and configure it to wait for an event of type AI  Async  Response.

Configuring Receipt of a Response

To set up an event node to receive an asynchronous service response, you can use either of the following methods:

• Select the Response Document tab (preferred method). Then select a request ID variable (a string) and a response document variable (of type XML). For details about using this method, see Procedure for Configuring Receipt of an Asynchronous Service Response (Preferred Method).

• Select the Asynchronous Variable tab (legacy method). Then select a request ID variable, an asynchronous service response variable (a string), and an asynchronous service response variable (of type AsyncServiceResponse). For details about using this method, see Procedure for Configuring Receipt of an Asynchronous Service Response (Legacy Method).

  Note: Use of the Response Document tab is preferred because it provides a universal means of receiving both asynchronous and synchronous responses. When you use this method, an XML document is received regardless of whether the response is asynchronous or synchronous, and you do not need to query the value of the asynchronous service response variable.

We recommend using a response document variable to receive asynchronous service responses whenever possible. To configure a service to wait for an event of type AI  Async  Response, use the Event Properties dialog box. This dialog box may or may not offer you the choice of using an asynchronous variable to receive the response. Whether this choice is available depends on the following conditions:

• If you edit an existing AI Async Response event node that was previously set up to use an Asynchronous Service Response variable to receive the response, then two tabs are displayed in the Event Properties dialog box: an Asynchronous Variable tab (legacy method) and a Response Document tab (preferred method). Thus you have a choice of two methods you can use to configure receipt of the service response.

• If you edit an existing AI  Async  Response event node that does not use an Asynchronous Service Response variable, or if you are creating a new AI  Async  Response event node, then the Event Properties dialog box displays a dialog box without tabs. In this case you must set up a response document to receive the service response (preferred method).

Handling Errors in an Asynchronous Application View Service Response

Although this task does not include the configuration of error handling for the Application View service response, you may want to handle errors in your own workflows. To handle asynchronous service response errors in workflows that use an AsyncServiceResponse variable, you can use the features provided by the application integration  plug-in.

The application integration plug-in includes the variable type AsyncServiceResponse and three functions:

• AIHasError()

• AIGetErrorMsg()

• AIGetResponseDocument()

For a complete description of these functions, see Functions Provided by the Application Integration  Plug-In.

Procedure for Configuring Receipt of an Asynchronous Service Response (Preferred Method)

To set up an asynchronous event node to wait for a response from an asynchronous Application View service, create an event node and configure it to wait for an event of type AI  Async  Response.

To set up an event node to use an XML variable to receive an asynchronous service response, complete the following procedure:

1. In the WebLogic Integration Studio, open a workflow template definition. The workflow design window is displayed.

 

2. If no event node exists, create one now. This event node will wait for an asynchronous response from a designated Application View service.

3. Double-click the event node. The Event Properties dialog box is displayed.

   
    

4. (Optional) In the Description field, enter a name.

5. In the Type list, select AI  Async  Response.

6. Select the Response Document (preferred) tab.

   Note: If your workflow does not use an AsyncServiceResponse variable, or if you are creating a new AI  Async  Response event node, then the Event Properties dialog box displays a dialog box without tabs, instead. Use this dialog box to set up a response document to receive the service response. (This method is the recommended.)

7. In the Request ID Variable list, select a string variable that is already defined. The WebLogic Integration process engine listens for an asynchronous response with an ID matching the ID stored in this variable.

8. If no suitable string variable exists, select <new> to open the Variable Properties dialog box, in which you can create a new string variable. See step 23. in Steps for Setting up a Task Node to Call an Application View Service for details.

   For details about defining new variables, see Using the WebLogic Integration Studio.

   Note: The purpose of this event node is to wait for a response to a Call Application View Service action that was called asynchronously earlier in the workflow. The Call Application View Service action sets the request ID variable. The action and this event node can work together only if both use the same request ID variable. For more information about setting up the Call Application View Service action, see Task 1: Set Up a Task Node to Call an Application View Service.

9. For asynchronous services that require storage of the response, select a predefined XML variable in the Response Document Variable list. Subsequently, whenever WebLogic Integration receives a response from the Application View service, the response is stored in the response document variable. If, on the other hand, you need the response data, skip this step.

10. If no suitable XML variable exists, select <new> to open the Variable Properties dialog box, in which you can create a new variable. See step 9. in Steps for Setting up a Task Node to Call an Application View Service for details.

    For details about defining new variables, see Using the WebLogic Integration Studio.

11. Click OK to save the event node.

Procedure for Configuring Receipt of an Asynchronous Service Response (Legacy Method)

The preferred method for receiving an asynchronous service response is to use a response document variable of type XML. However, if an existing workflow contains an asynchronous event node that was previously set up to use an AsyncServiceResponse variable (to wait for a response from an asynchronous Application View service), you can modify the event node.

To modify an event node that uses an AsyncServiceResponse variable to receive an asynchronous service response, complete the following procedure:

1. In the WebLogic Integration Studio, open a workflow template definition. The Workflow Design window is displayed.

 

2. Double-click the asynchronous event node. The Event Properties dialog box is displayed.

   
    

3. Select the Asynchronous Variable (legacy) tab.

4. From the Request ID Variable list, select a string variable that is already defined. WebLogic Integration listens for an asynchronous response with an ID matching the ID stored in this variable.

   Note: The purpose of this event node is to wait for a response to a Call Application View Service action that was invoked asynchronously earlier in the workflow. The Call Application View Service action sets the request ID variable. The action and this event node can work together only if both use the same request ID variable. For more information about setting up the Call Application View Service action, see Task 1: Set Up a Task Node to Call an Application View Service.

5. From the Asynchronous Service Response Variable list, select an AsyncServiceResponse variable in which to store the response data.

   Note: Because you are modifying an existing asynchronous event node, the asynchronous service response variable field is already populated. If you do not need the response, select the Response Document (preferred) tab. For details about using the preferred method, see Procedure for Configuring Receipt of an Asynchronous Service Response (Preferred Method).

6. Click OK to save the event node.

Functions Provided by the Application Integration  Plug-In

If your enterprise includes AI Async Response variables and you want to interrogate those variables while using the application integration plug-in, use the following functions:

• AIHasError()

• AIGetErrorMsg()

• AIGetResponseDocument()

Using these functions, you can set up decision nodes to handle success and failure conditions.

Note: These functions are available only if the application integration plug-in is installed, and they support only the asynchronous variable method for receiving asynchronous service responses. For details, see Procedure for Configuring Receipt of an Asynchronous Service Response (Legacy Method).

AIHasError()

Use AIHasError() to determine the status of an asynchronous service response. The following table provides details about this function.

Operands	AsyncServiceResponse variable
Preconditions	You have created a variable of type AsyncServiceResponse. You have called an asynchronous Application View service. The Application View service has returned a response, which is stored in your AsyncServiceResponse variable.
Returns	Boolean
Output explanation	False: The asynchronous Application View service call was successful. True: The asynchronous Application View service call failed.

AIGetErrorMsg()

Use AIGetErrorMsg() to retrieve the error message string returned by an asynchronous Application View service. The following table provides details about this function.

Operands	AsyncServiceResponse variable
Preconditions	You have created a variable of type AsyncServiceResponse. You have called an asynchronous Application View service. The Application View service has returned a response, which is stored by your AsyncServiceResponse variable.
Returns	String
Output explanation	Error string: Returns an error string explaining why the asynchronous Application View response failed. Empty string: There was no error.

AIGetResponseDocument()

Use AIGetResponseDocument() to retrieve the XML response document returned by an asynchronous Application View service. The following table provides details about this function.

Operands	AsyncServiceResponse variable
Preconditions	You have created a variable of type AsyncServiceResponse. You have called an asynchronous Application View service. The Application View service has returned a response, which is stored in your AsyncServiceResponse variable.
Returns	XML
Output explanation	XML document: Returns an XML document representing the asynchronous service response. Null: No response document is returned because an error occurred.

 

---

Task 3: Create a Workflow Started by an Application View Event

It is sometimes desirable to have a workflow that is started whenever a designated Application View event occurs. To create such a workflow, edit the workflow's start node so it responds to an event of type AI  Start, then select the appropriate Application View event. If necessary, you can set up conditions with which the event can be filtered. After you save and activate the workflow, the start node is executed each time the Application View event occurs.

Steps for Creating a Workflow Started by an Application View Event

To set up a workflow with a start node that is triggered by an Application View event, complete the following procedure:

1. In the WebLogic Integration Studio, open a template definition. The Workflow  Design window is displayed.

 

2. If no start node exists, create one now. This start node will respond to an Application View event that you specify.

3. Double-click the start node. The Start  Properties dialog box is displayed.

   
    

4. (Optional) In the Description field, enter a name.

5. Click Event.

6. From the Event list, select AI  Start.

7. In the navigation tree, select an Application View event.

   The navigation tree organizes Application View events by folder (such as the EastCoast and Sales folders shown in the preceding Start Properties dialog box) and Application View (for example, CustomerManagement). All Application View events are listed at the lowest level of the hierarchy.

   Note: To check for recently saved Application Views and events at any time, select Refresh  Tree.

   If the navigation tree is missing or appears too narrow, it may include an overly long XML or string variable name. Try shortening the names of your XML or string variables.

8. In the Key Value Expression field, define a key value for the event. You can enter a String as the key value, or you can create an expression that is evaluated at run time to produce the key value. (Select the A  +  B  option to display the Expression Builder dialog box, and then create an appropriate expression.) The specified key value must match an element in the incoming Event's XML before WebLogic Integration triggers the event.

   You must also define the expression that locates the key value in the XML for the incoming Event, so that WebLogic Integration can compare the incoming key value to the specified key value. If there is no key value expression, you are prompted to create one before you can save the event.

   The Event Descriptor for AI Events is the fully qualified Application View event name in the following form:

   namespace.Application View name.event

   Root is not part of the fully qualified event name. The Event Descriptor field is filled in automatically if the key value expression is created directly from the event dialog box. To accept each instance of the specified Application View event regardless of its contents, leave this field blank.

9. If necessary, filter the event in one of the following ways: enter a condition in the Condition field, or select the A  +  B  option to display the Expression Builder dialog box, and then create an appropriate expression.

   For information about setting up conditions and XPath expressions, see Using the WebLogic Integration Studio.

10. From the Event Document Variable list, select an XML variable. Data from the Application View event that is received by the start node is stored in this variable. If you do not need the event data, skip this step.

11. If no suitable XML variable exists, select <new> to open the Variable Properties dialog box, in which you can create a new variable. See step 9. in Steps for Setting up a Task Node to Call an Application View Service for details.

    For details about defining new variables, see Using the WebLogic Integration Studio.

12. If you need to examine the XML schema for the event document, click View Definition. The View Definition dialog box is displayed.

    
     

13. Click Close to return to the Start Properties dialog box.

14. In the Start Properties dialog box, click OK. The new or modified start node is saved.

 

---

Task 4: Set Up an Event Node to Wait for an Application View Event

In a workflow, it is sometimes desirable to have an event node that is triggered by an Application View event. To create such a node, edit an event node so it responds to an event of type AI  Event, then select the appropriate Application View event. If necessary, you can set up conditions with which to filter the designated Application View event. After you save and activate the workflow, the workflow progresses to this event node, waits for a specified Application View event, and continues processing.

Steps for Setting Up a Node to Wait for an Application View Event

To set up an event node to be triggered by an Application View event, complete the following procedure:

1. In the WebLogic Integration Studio, open a template definition. The Workflow  Design window is displayed.

 

2. If no event node exists, create one now. This event node will be triggered by a designated Application View event.

3. Double-click the event node. The Event  Properties dialog box is displayed.

   
    

4. (Optional) In the Description field, enter a name.

5. From the Type list, select AI  Event.

6. In the navigation tree, select an Application View event.

   The navigation tree organizes Application View events by folder (such as the EastCoast and Sales folders shown in the preceding Start Properties dialog box) and Application View (for example, CustomerManagement). All Application View events are listed at the lowest level of the hierarchy.

   Note: To check for recently saved Application Views and events at any time, select Refresh  Tree.

   If the navigation tree is missing or appears too narrow, it may include an overly long XML or string variable name. Try shortening the names of your XML or string variables.

7. In the Key Value Expression field, define a key value for the event. You can enter a variable or a String as the key value, or you can create an expression that is evaluated at run time to produce the key value. (Select the A  +  B  option to display the Expression Builder dialog box, and then create an appropriate expression.) The specified key value must match an element in the incoming Event's XML before WebLogic Integration triggers the event.

   You must also define the expression that locates the key value in the XML for the incoming Event, so that WebLogic Integration can compare the incoming key value to the specified key value. If there is no key value expression, you are prompted to create one before you can save the event.

   The Event Descriptor for AI Events is the fully qualified Application View event name in the following form:

   namespace.Application View name.event

   Root is not part of the fully qualified event name. The Event Descriptor field is filled in automatically if the key value expression is created directly from the event dialog box. To accept each instance of the specified Application View event regardless of its contents, leave this field blank.

8. If necessary, filter the event in one of the following ways: enter a condition in the Condition field, or select the A  +  B  option to display the Expression Builder dialog box, and then create an appropriate expression.

   For information about setting up conditions and XPath expressions, see Using the WebLogic Integration Studio.

9. In the Event Properties dialog box, select an XML variable from the Event Document Variable list. Data from the Application View event that is received by the start node is stored in this variable. If you do not need to save the event data, skip this step.

10. If no suitable XML variable exists, select <new> to open the Variable Properties dialog box, in which you can create a new variable. See step 9. in Steps for Setting up a Task Node to Call an Application View Service for details.

    For details about defining new variables, see Using the WebLogic Integration Studio.

11. If you need to examine the XML schema for the event document, click View Definition. The View Definition dialog box is displayed.

    
     

12. Click Close when finished.

13. In the Event Properties dialog box, click OK.

 

---

Handling Application View Local Transactions in Workflows

The LocalTransaction interface is exposed to adapter clients via the Common Client Interface (CCI) Connection class. Currently the Application View interface does not use the CCI LocalTransaction interface. To manage a local transaction, a user must first acquire a LocalTransaction from the Connection object.

Local Transaction Management Contracts

A local transaction management contract is created when an adapter implements the javax.resource.spi.LocalTransaction interface to provide support for local transactions that are performed on the system's underlying resource manager. This type of contract enables an application server to provide the infrastructure and run-time environment for transaction management. Application components rely on this transaction infrastructure to support their component-level transaction model.

For more information about transaction demarcation support, see:

http://java.sun.com/blueprints/guidelines/designing_enterprise_applications/transaction_management/platform/index.html

Connector Support for Local Transactions with No User Defined Transaction Demarcation

The following is a scenario for supporting Application View local transactions within the Application Integration Plug-in. This scenario is similar to TX_REQUIRES_NEW for EJB transactions because the connector supports only local transactions.

In this scenario, the Connector supports only local transactions and the BPM designer does not explicitly demarcate the start and end of a local transaction. WebLogic Integration allows the Connector to participate in the global transaction by providing an XA Wrapper around the LocalTransaction object. The XA Wrapper no-ops all methods on the XAResource interface that can not be delegated to the LocalTransaction instance. WebLogic Integration allows only one non XA resource in the transaction chain. As a result, a user can have only one Application View LocalTransaction within a workflow.

Connector Support for XA Transactions

In this scenario, Application View services are not called within a local transaction. Each service invocation is automatically enlisted in the Global XA transaction because the resource adapter supports XA.