| Oracle® Enterprise Service Bus Developer's Guide 10g (10.1.3.3.0) Part Number E10295-01 |
|
|
View PDF |
| Oracle® Enterprise Service Bus Developer's Guide 10g (10.1.3.3.0) Part Number E10295-01 |
|
|
View PDF |
This chapter describes how to use Oracle ESB Control, a Web-based interface for managing, administering, and monitoring an Oracle Enterprise Service Bus.
This chapter contains the following topics:
The Oracle ESB Control is typically used at run time to monitor and fine tune the enterprise service bus. The Oracle ESB Control enables you to:
Create, modify, and delete ESB systems and service groups
View and modify routing rules for routing services, including filter expressions, transformations, execution type (synchronous or asynchronous), and so on.
View and modify adapter and SOAP services
View the connections among the various Oracle Enterprise Service Bus services in a schematic diagram
View run-time statistics
View system, group, and service definition details, including URLs required to call ESB services from applications that are external to the enterprise service bus
Track message instances across the service bus in a schematic diagram
View error conditions within a schematic, including the messages that did not reach their destination, and resubmit messages for retryable errors.
View and define domain-value maps
Note that many of these features are also available in Oracle JDeveloper. Table Table 3-1 summarizes the features available in each of these tools:
Table 3-1 Comparison of Features Available in the Oracle ESB Control and Oracle JDeveloper
| Feature | Available in Oracle JDeveloper? | Available in Oracle ESB Control? |
|---|---|---|
|
Create, modify, and delete ESB systems |
Yes |
Yes |
|
Create, modify, and delete ESB routing service definitions |
Yes |
Yes |
|
Create, modify, and delete routing rules (transformations, filter expression and so on) |
Yes |
Yes |
|
Create a transformation file |
Yes |
No |
|
Create, modify, and delete ESB adapter services |
Yes |
No |
|
Create, modify, and delete SOAP invocation services |
Yes |
No |
|
View service connections schematically |
Yes |
Yes |
|
View run-time statistics |
No |
Yes |
|
Specify notification channels |
No |
Yes |
|
View message instances schematically |
No |
Yes |
|
Resubmit messages that have failed due to an error |
No |
Yes |
|
Define and view trackable fields |
No |
Yes |
|
Define domain-value maps |
No |
Yes |
Figure 3-1 shows the Oracle ESB Control with the schematic that is generated when you complete the tutorial documented in the Oracle Enterprise Service Bus Quick Start Guide. On the left side of the Oracle ESB Control is a navigation tree that enables you to select a system, group, or service; on the right side of the Oracle ESB Control are tabbed pages that display, and enable you to change, properties for an object selected in the navigation tree.
Figure 3-1 Oracle ESB Control - Services View Diagram Tab
For information about starting ESB components and opening the Oracle ESB Control, see "Opening the Oracle ESB Control"
The Oracle ESB Control provides three views, which you select by clicking the links that run across the top of the page. The currently selected view is indicated by a blue bubble that encloses the link. In Figure 3-1, for example, the currently selected view is Services.
Each of the views is described in the following subsections:
Note:
All the tasks described in this section assume that the ESB Server is started and the database that is serving as the ESB repository is up and running. For information about starting the ESB Server, see "Starting, Stopping, and Accessing Oracle Enterprise Service Bus Components".The Services view of the Oracle ESB Control, enables you to view service definitions, update routing rules, define trackable fields, and view a schematic diagram of the services.
As shown in Figure 3-1, the Services view is divided into two main regions: a services panel on the right and tabbed pages on the left. The services panel provides a navigation tree of ESB systems and the service groups and services within each, and buttons to create, delete, and move objects within the navigation tree.
The services panel appears on the left side of the Oracle ESB Control. It provides buttons for creating and deleting ESB systems, groups, and services and a navigation tree to present these items (and their current status) after they have been created.
The tabbed panel presents details about services selected in the navigation tree. Depending on the service selected, the following tabs are available:
On the Diagram tab, view the relationship of the selected service to other objects within the ESB system. Oracle Enterprise Service Bus creates this diagram automatically, based on the definitions you specify for each service.
The selected service is represented in blue within the diagram, whereas the other services are represented in gray. In the diagram, the following conventions are used:
Adapter services are represented by rectangles with a long horizontal plane.
Routing services are represented by rectangles with long vertical planes.
Communication between services is represented by the lines between the services.
A routing service filter expression is indicated by a funnel.
A transformation is indicated by two rectangles with an X overlay.
The navigator tab indicates which area of the diagram is currently being displayed in relation to the entire diagram. This is useful for large diagrams that extend beyond the area that can be presented in the diagram region. When you move the scroll bar in the diagram region, notice that the blue window in the navigator scrolls also, to highlight the portion of the diagram that is currently visible.
The detail tab provides the name of the selected service and the status of the selected service in the Diagram tab. Overlay metrics enable you to select which metrics, if any, you want to be superimposed on the diagram.
See "Creating, Viewing, and Updating Organizational Units for Services".
On the Definition tab, view the definition of the selected service, enable it, or disable it. For outbound adapter services and routing services, these details including the concrete WSDL URL, which you can use to invoke the service using SOAP over HTTP from another application.
On the Routing Rules tab, view, update, delete, and set the priority of routing rules for the selected routing service. The routing rules tab is presented only when you select a routing service from the navigation tree. It shows the rules that govern how a message is routed by the routing service.
See "Understanding and Managing Routing Rules" for more information about routing rules.
On the Properties tab, view, update, and delete endpoint properties for the selected adapter or SOAP service. The Properties tab is presented only when you select an adapter or SOAP service from the navigation tree.
Click the + on right side of the screen to add endpoint properties. Select the endpoint from the list under the Name column and enter a value in the Value column. Setting endpoints is similar to the actions in the endpoint properties panel in Oracle JDeveloper. For more information about using endpoint properties, see "Using Endpoint Properties".
On the Trackable Fields tab, define trackable fields for the selected service. See "Defining and Managing Tracking Fields".
The Instances view enables you to view details about message processing across an ESB system.
It enables you to filter messages based on any of the following properties:
The service that processed them
The status of the messages (Any, Error, Faulted, Processing, or Completed)
Tracking name and tracking value
Message IDs
Time frame during which the message was processed
When you select a service for a message from the Instances panel, the message instance's path through the enterprise service bus is presented in the Tracking tab diagram (and the selected service is enclosed by dotted lines in the diagram). Within the diagram, endpoints that successfully processed the message are represented in green, services where an error occurred are represented in red, and services that processed the message successfully, but were rolled back due to an error are represented in yellow. Endpoints that were not invoked in the processing of the message are represented in gray.
Figure 3-2 shows that the CRM adapter service (CRMOut) was successfully invoked and that the database adapter service (CustDBOut) was not invoked because a filter expression excluded the message from delivery to the database adapter service.
Figure 3-2 Oracle ESB Control - Instances View Tracking Tab
If you select a service where an error occurred for the message, an Error tab is presented, as shown in Figure 3-3. The Errors tab contains an error table that lists the time, service:operation, and message associated with each error. Click the Error Details icon in the Message column to view the error message and the stack trace.
Figure 3-3 Oracle ESB Control - Instances View Errors Tab
For more information message tracking, see Chapter 10, "Tracking Message Instances Across the Enterprise Service Bus". For more information about error handling, see Chapter 11, "Error Handling".
The Maps view enables you to create, update, and delete domain-value maps, as well as view, export, and import existing domain-value maps.
Applications that you want to integrate using Oracle Enterprise Service Bus likely use different values to represent the same information. For example, one application may represent the state of Massachusetts as MA whereas another application might represent it as Massachusetts or Mass. A domain-value map enables you to associate values from one application to values from another. Each domain-value map typically holds a specific category of value mappings among multiple applications. For example, one domain-value map might hold mappings for country codes and another might hold mappings for units of measurement.
Figure 3-4 shows a sample domain-value map in the Maps view of Oracle ESB Control. The names of the saved maps are listed in the left panel of the page and right panel shows the details about the mappings in a specific map. In this sample map, mappings are set up for the long, abbreviated, and short name of states in the columns of the map.
Figure 3-4 Oracle ESB Control - Maps View with Sample Domain-Value Map
For more information domain-value maps, see Chapter 7, "Domain-Value Maps".
Oracle Enterprise Service Bus provides system and service group structures for organizing services. ESB systems are required; service groups are optional.
Every service you create must be defined as a child of either a service group or a system. A service is uniquely identified by its full path within the system/service group/service or system/service structure. A service is represented by a gear icon in the services navigation tree.
An Oracle Enterprise Service Bus system is an organizational unit, typically used to contain the services associated with of a single application, proxy for an application, or a technical system, such as an Oracle Applications instance. Examples of systems are:
An Oracle Applications instance
A set of transformations, Oracle BPEL Process Manager services, and adapter services for an SAP instance
A set of transformations, BPEL Services, and database services for a custom database application
A standalone Oracle Business Activity Monitoring instance, complex event processing (CEP) services, and other related services
An Oracle B2B engine (that serves as a proxy for trading partners) and related transformation services and other services
A set of services, adapter services, and Oracle BPEL Process Manager services representing a bridge to a third party integration infrastructure (such as webMethods, Inc, and IBM infrastructures)
When you create a service, you must create it within the context of an Oracle Enterprise Service Bus system. A service cannot belong to multiple ESB systems.
You can specify that an administrator be alerted if an error or fault occurs for a service contained within an ESB system.
A system is represented in the Oracle ESB Control by a stacked disks icon.
For more information see "Creating an ESB System" or "Viewing or Modifying an Existing ESB System Definition".
Similar to systems, service groups are units for organizing services. Unlike systems, however, you are not required to create a service group before you can create a service. A service group must be created within the context of an ESB system. A service can belong to, at most, one service group.
A service group is represented in the navigation tree by a folder icon on which a gear icon is superimposed.
For more information, see "Creating Service Groups" or "Viewing or Modifying an Existing Service Group"
Icons used to represent objects in the Oracle ESB Control are shown in Figure 3-5.
Figure 3-5 Icons Used in the Oracle ESB Control
You can use the Oracle ESB Control to create new ESB systems, or view and modify existing ESB systems. The following sections provide step-by-step instructions:
To create a system, follow these steps:
In the Service panel, click Create.
A dialog box opens.
In the What do you want to create? field, select System.
The dialog box refreshes to present only the fields required to create a system.
In the Specify Name field, enter a unique name for the system.
Click OK.
The named system is added to the Services panel (with an downward pointing arrow that indicates that the system is disabled), and the Definition tab is presented.
On the Definition tab, optionally specify the following:
The Java Message Service (JMS) topic where you want messages that could not be delivered due to an errors be stored.
The JMS topic for storage of messages that are delivered asynchronously.
The notification channels that you want the ESB Server to use in the event that an error occurs. See "Setting Up Notification Channels" for details.
On the Definition tab, click Create.
An Update Service window opens to indicate that the system has been created. The arrow next to the named service in the Services panel now points upward to indicate that the service is enabled.
In the Update Service window, click OK.
To view or modify the definition for a previously created ESB system, follow these steps:
Click Services if the Services view is not currently displayed.
In the Services panel, click the name of the ESB system of interest.
The Definition tab displays similar to Figure 3-6.
Review the properties presented on the Definition tab and described in Table 3-2.
Make any desired updates. All properties can be updated except the Asynchronous Topic and the Error Topic.
If you are satisfied with your changes, click Apply; otherwise, click Reset to return the properties to the settings that were presented when you opened the page.
Table 3-2 ESB System Definition Tab
| Page Element | Description |
|---|---|
|
Name |
The name used in the Oracle ESB Control to identify the system. |
|
Cluster Name |
The name of the Oracle Application Server cluster associated with the system. |
|
Virtual Host |
The name of the host where the Oracle Application Server is running. |
|
Port |
The port number on the host where the Oracle Application Server is running. |
|
Topic Location |
The JNDI location of the JMS topic to which messages are published when messages are routed asynchronously. |
|
Connection Factory Location |
The connection factory location to which messages are published when messages are routed asynchronously. |
|
Number of Listeners |
The number of listeners for the JMS topic to which messages are published when messages are routed asynchronously. |
|
Notification Details |
The notification details specify the communication channel or channels that will be used to alert an administrator that an error has occurred within the Oracle Enterprise Service Bus system. You can specify notifications with the following channels:
|
Similar to systems, service groups are units for organizing services. Unlike systems, however, you are not required to create a service group before you can create a service. A service can belong to, at most, one service group.
To create a service group:
Click Services if the Services view is not currently displayed.
In the Service panel, click Create.
A dialog box opens.
In the What do you want to create? field, select Service Group.
The dialog box refreshes to present only the fields required to create a system.
In the Specify Name field, enter a name for the service group that is unique within the system or parent service group in which you are creating it.
To the right of the Choose the parent System or Service Group field, click the icon.
The Choose Parent System or Service Group dialog box opens.
In the Choose Parent System or Service Group dialog box follow these steps:
Select the name of the parent system or service group.
Click Select.
Click OK.
The dialog box closes and the service group name is added to the navigation tree. The status column indicates that the service group is disabled.
On the Definition tab, in the Description field, optionally enter a description for the service group.
On the Definition tab, click Create.
A window opens to indicate that the changes have been successfully applied.
Click OK.
The status column in the Services panel indicates that the status of the newly created group is up.
After you have created a service group, you can change its name or description, if desired. However you cannot change its parent.
To view or modify a service group, follow these steps:
Click Services if the Services view is not currently displayed.
In the Services panel, click the name of the service group of interest.
Review the properties presented on the Definition tab and described in Table 3-3.
Make any desired updates. All properties can be updated except the Identifier.
If you are satisfied with your changes, click Apply; otherwise, click Reset to return the properties to the settings that were presented when you opened the page in Step 2.
Table 3-3 ESB Service Group Definition Tab
| Page Element | Description |
|---|---|
|
Identifier |
The name by which the ESB Server identifies the service group. When you create a service group, ESB Server creates an identifier using the format systemnameSystem.servicegroupname, where systemname is the name of the system in which the service group was created and servicegroupname is the name that was originally specified for the service group when it was created. If you change the name of the service group, the name used in the Services panel is updated to reflect your change, but the identifier remains the same. The ESB Server uses the identifier, not the name, to refer to the service group in error messages. |
|
Name |
The name used in the Oracle ESB Control to identify the service group. |
|
Parent Name |
The ESB system that contains the service group. |
|
Description |
A user-specified description of the service group. |
To delete a system or service group, select the system or service group and click Delete. You need to confirm the action to delete the object from the Oracle ESB Control.
Note that deleting a system or service group from the Oracle ESB Control does not remove the object from Oracle JDeveloper. If you register the ESB project again with the ESB Server in Oracle JDeveloper, it will appear in Oracle ESB Control after a refresh.
Although you cannot create services using the Oracle ESB Control, you can view the service definitions, modify some properties, and create or modifying routing rules for existing services, as described in the following sections:
For information about creating services, see Chapter 4, "Creating Inbound and Outbound Services" and Chapter 5, "Creating Routing Services and Routing Rules".
To enable or disable a service, follow these steps:
Click Services if the Services view is not currently displayed.
In the Services panel, navigate to the service of interest, and then select it.
Click the Definition tab.
Click Enable or Disable, as desired.
Note:
By default, all services are enabled. When you explicitly disable a service, an error is thrown back to the invoker.In case of a routing service, the routing rule errors out when the target service is disabled. This is applicable to synchronous as well as asynchronous routing rules.
To view the definition of an ESB service, follow these steps:
Click Services if the Services view is not currently displayed.
In the Services panel, navigate to the service of interest, and then select it.
Click the Definition tab.
The Definition page summarizes the contents of the WSDL file for the selected service. It consists of the following three regions for all services, except inbound adapter services. Inbound adapter services present the overall section only, and only a subset of the fields for that region.
General
This region of information, which is not labeled, appears at the top of the page. The elements that are presented in this region of the page are described in Table 3-4. For inbound adapter services, only the following elements are presented: Name, Type, Description, and Inbound Adapter WSDL URL.
Table 3-4 Service Definition – General Region
| Page Element | Description |
|---|---|
|
Name |
The name that was entered to identify the routing service when it was created. |
|
Type |
The type of this ESB service. The value of this field is always Routing Service for a routing service. |
|
Description |
An optional user-specified description of the routing service. |
|
Invocable from an external service |
Indicates whether the service can be invoked from an external service. |
|
Concrete WSDL URL |
The concrete WSDL URL for the service. Use this URL to call the service from any external Web Services client (such as .Net). Click the URL to view the WSDL in your default browser. |
|
Port Type |
A name that refers to the set of operations performed by this service. This name corresponds to the name attribute of the portType element in the WSDL that defines this routing service. |
|
Namespace |
The XML namespace specified in the WSDL that defines this routing service. |
|
WSDL URL |
The abstract WSDL URL that ESB Server used to configure the service. Click the URL to view the WSDL in your default browser. |
|
SOAP Endpoint URI |
The URl of the SOAP endpoint. Click the URL to open the Test Web Service page. Note: For information on using the Test Web Service page, see "Testing the ESB Services" and Oracle SOA Suite Developer's Guide. |
Operations
This region of the page lists the operations that the service WSDL describes and their type. Table 3-5 describes this region of the page.
Operation Details
This region of the page provides details on an operation selected in the Operations region. Table 3-6 describes this region of the page. Which tabs are presented in this region depend on the operation definition, as follows:
One-way operations
If the selected operation is defined as a one-way operation (only input elements are defined for the operation in the WSDL), then only the Request tab is active.
Request/response operation
If the selected operation is defined as a request/response operation (both input and output elements are defined for the operation in the WSDL), then both the Request and Response tabs are active.
Faults
If a fault is defined for the operation (fault elements are defined for the operation in the WSDL), then the fault tab is active. Note that a fault is simply a special response that can be directed to the requester.
Table 3-6 Service Definition - Operation Details Region
| Page Element | Description |
|---|---|
|
Validate Payload at Runtime |
Enables you to specify whether or not you want the message payload validated against the schema (XSD) definition at runtime. Select to enable, deselect to disable. If you select this option and a message payload received by the service is invalid, the message handled as described in "Managing Error Conditions". |
|
Element |
The message payload element name. This corresponds to the <part> element's |
|
Schema Location |
Specifies the location of the schema, if any, used by the service. |
While a routing service determines the operations that will be performed on the messages received by the routing service, whether or not it can be invoked by an external service, and whether or not the message payload will be validated by the routing service at run time, routing rules determine the following:
The set of target services to which message instances will be sent from the routing service
The operation that will be applied to a message instance upon reaching the target service
Whether a transformation will be applied to the structure of a message instance before being sent to a given target service
Whether some message instances will not be sent to a target service, on the basis of a filter applied to the message payload
This section discusses the following topics:
For information about creating routing services, see Chapter 5, "Creating Routing Services and Routing Rules".
Although routing rules are typically specified as part of the development phase using Oracle JDeveloper, the Oracle ESB Control also provides tools for creating and modifying routing rules at run time. Although the method for accessing the controls are different for each tool, the actual controls are the same.
To access the controls for creating a routing rule using the Oracle ESB Control, follow these steps:
In the Services panel, click the routing service for which you want to create or modify routing rules.
Click the Routing Rules tab.
The controls on Routing Rules tab in the Oracle ESB Control are similar to the Routing Rules tab in Oracle JDeveloper. For information about using these controls, see "Specifying Routing Rules".
To view the current routing rules for a routing service, follow these steps:
In the Services panel, click the routing service for which you want to view the routing rules.
Click the Routing Rules tab.
Table 3-7 describes the page elements on this tab.
Table 3-7 Routing Rules Tab in Oracle ESB Control
| Page Element | Description |
|---|---|
|
Priority arrows |
The green arrows at the top of the routing rules table enable to you to set the priority of the routing rules relative to other synchronously executed routing rules. |
|
Filter Expression |
Specifies an expression by which you want messages to be filtered for the selected rule. You might specify a filter expression, for example, if you only want messages written to a database for a customer record if that customer address is in the United States. This field is optional. Click the icon to the right of this field to open the Expression Builder. See "Using An Expression for Filtering Messages Based on Payload" for more information. |
|
Transformation Map File |
Specifies the XSLT file that defines the transformation you want to apply to the data format of message before it is delivered to the service to which it is being routed. You might specify an XSLT file to transform message data from a canonical format to the format expected by the database receiving that data. This field is optional. Click the icon to the right of this field to open the Map Browser dialog box, which enables you to search for and browse among defined and registered Data Map (.xslt) files or to create a new one. See "Creating an XSL Map File for Data Structure Transformation" for more information. |
|
Target Operation |
Specifies the service and operation to which messages will be sent. Click the icon to the right of this field to open the Service Operation Browser dialog box, which enables you to search for and browse among registered service operations. |
|
Accept Messages From |
Specifies the ESB systems from which messages will be accepted by the target service, as follows:
|
|
Rule Execution |
Specifies whether execution of the routing rule will be synchronous or asynchronous. See "Specifying Synchronous or Asynchronous Execution" for more information. |
In the Services panel, click the routing service from which you want to delete a routing rule.
Click the Routing Rules tab.
Click the plus sign (+) to the left of the routing rule to select it.
Click the minus (-) button on the far right of the routing rule page to delete the selected routing rule.
Click Apply.
The Oracle ESB Control enables you to track the path particular message instances take across the Oracle Enterprise Service Bus and the current routing status of that message.
The mechanism by which you track messages is using trackable fields. A trackable field is a name-value pair, where the name is any meaningful string that you specify (such as CustomerName or POId) and the value is an XPath expression defined for the input and output message of an entire service or an operation performed by the service.
Using the Trackable Fields tab in the Services view of the Oracle ESB Control, you can define one or more trackable fields for each message associated with a service and operation to keep track of the messages that the service operation processes at run time. You can then search the message instances that the service or operation has processed using the Instances view of the Oracle ESB Control.
The following sections provide step-by-step instructions on the tasks associated with trackable fields:
The Trackable Fields tab contains the following fields:
Name
A unique name that you provide for the trackable field.
Operation
The operation associated with the service that you select for the trackable field.
Message
The message type of the service that you select for the trackable field.
Expression
The expression that you want to track for the service. This field includes a variable of the message instance that is tracked.
Enabled
The status of the trackable field you can set to enable or disable.
To define or update trackable fields, follow these steps:
At the top of the Oracle ESB Control, click the Services button if the Services view is not currently displaying.
In the Services panel, select the service for which you want to set trackable fields.
Click the Trackable Fields tab.
Click the plus (+) button to add a row to the table and enable editing for that row; double-click an existing row to update that row.
Figure 3-7 Services View – Trackable Fields Tab
Enter values in the row, as follows:
In the Name field, enter a name for the trackable field that is unique across the ESB system in which the service exists.
In the Operation field, select from the list the operation on which you want to define the trackable field.
In the Message field, select from the list the type of message you want to track for this service. Possible values are: Request, Response, Fault.
In the Expression field, enter the XPath expression that identifies the field that you want to track.
Click the wand icon to the right of the Expression field to open the Expression Builder, which assists you in building the XPath expression. For information about the Expression Builder, see "Filter Expression Overview".
In the Enabled field, click the check box to enabled the specified trackable field. Deselect the check box to disable it.
If you disable the trackable field, the trackable field information is not logged and is not available in the Instances view of the Oracle ESB Control.
Click OK when finished.
Click Apply to save the changes you have made; click Reset to return to the values that were presented before you began editing fields.
For information about the Expression Builder, see "Filter Expression Overview".
At the top of the Oracle ESB Control, click the Services button if the Services view is not currently displaying.
In the Services panel, select the service for which you want to set trackable fields.
Click the Trackable Fields tab.
Click the plus (+) button to add a row to the table and enable editing for that row; double-click an existing row to update that row.
Click the plus \ icon to launch the Expression Builder.
Select and expand the Variables tree and select a variable.
Note:
If you are not able to expand the Variables tree, then you can manually enter the expression in the Expression field.Click Insert into Expression.
Figure 3-8 Trackable Fields - Expression Builder
Click OK.
Click Apply to save the changes you have made; click Reset to return to the values that were presented before you began editing fields.
To enable or disable trackable fields, follow these steps:
At the top of the Oracle ESB Control, click the Services button if the Services view is not currently displaying.
Click the Trackable Fields tab.
Double-click the row that contains the trackable field that you want to enable or disable.
In the Enabled column, select the check box to enable the trackable field, deselect the check box to disable the trackable field.
Click Apply.
At the top of the Oracle ESB Control, click the Services button if the Services view is not currently displaying.
Click the Trackable Fields tab.
Click the row that contains the trackable field to select it.
A selected row is highlighted in blue.
Click the minus (-) button.
Click Apply.
