9 Working with Reports
This chapter describes the reporting features of Oracle SOA Suite for healthcare integration. The configurable reports display the real-time status of message processing through the healthcare integration application based on the criteria you specify.
This chapter includes the following topics:
9.1 Introduction to Reports
The Reports page of the Oracle SOA Suite for healthcare integration user interface lets you view the status of the messages being processing through healthcare integration components in real-time. You can view all messages, or you can narrow down the messages displayed by a variety of criteria, including endpoints, date ranges, document information, and payload fields.
Several reports are predefined on the healthcare integration user interface. These are based on recent time ranges, such as the past 24 hours, the past week, and so on, and display all messages processed within those time periods. You can create additional reports based on more specific criteria to narrow down the types of messages displayed.
Each report is divided into four sections:
-
A report configuration bar
-
The message list
-
A graphical depiction of the message flow
-
Message details for the selected message.
If you select multiple messages from the report, a summary of information for the selected messages appears in place of the flow diagram.
Figure 9-1 shows an example of a report as displayed on the Reports tab.
Figure 9-1 Reports Page Showing a Predefined Report
Description of "Figure 9-1 Reports Page Showing a Predefined Report"
In the message list, each message is marked with an icon that provides processing information about the message. An envelope icon indicates normal processing; a green arrow over the envelope indicates the message was resubmitted; and a red square with an "X" over the envelope indicates an error.
9.1.1 About the Business Message Report Filter Editor
You use the Business Message Report Filter Editor to create new reports and to edit existing reports. The report editor allows you to define a wide variety of criteria for the messages that are displayed on the report, including a time range, an endpoint, the message status, and document definition information. You can also use advanced options, which include correlation fields, SOA composite fields, message IDs and so on.
Figure 9-2 Business Message Report Filter Editor
Description of "Figure 9-2 Business Message Report Filter Editor"
For most filters, you need to select an operator that specifies how to evaluate the value you specify for the filter. You can also specify whether or not the search is case-sensitive. Most filters support the following operators to act against the value you specify: Any, Equals, Like, Not Equal, or Not like. For the Like and Not Like operators, you can use SQL wildcard characters in the value. SQL wildcard characters include:
-
% (percent): Represents zero or more unknown characters
-
_ (underscore): Represents a single character
-
[charlist]: A list of characters; the unknown value is any character in the list
-
[^charlist] or [!charlist]: A list of characters; the unknown value is not a character in the list
For most string-based criteria, you can specify whether or not the search should be case sensitive by selecting or deselecting Ignore case next to the field. Use the links next to Filter Conditions to move between sections in the filter conditions list.
9.1.1.1 About Correlation and Payload Key Fields
When you create your document definitions, you can specify up to three fields in the message as payload key fields. These fields are defined by a unique name and an XPath expression that locates the field in the message. For example, you might name a field LastName and specify the XPath expression for the last name field in the PID segment of an HL7 A03 message. You can similarly define correlation fields for a document definition.
If you have defined either correlation fields or payload key fields for a document definition, then you can use these fields as filters for business message reports. In the filter editor, these filters are defined by name and value pairs. You use the unique name you gave the field when you created the document definition, and then specify what the value should be for that field in the messages you want to include on the report.
9.1.2 About Resubmitting Messages
When messaging errors are internal to Oracle SOA Suite for healthcare integration, you can correct the problem and resend the message. For example, if a message is sent to an endpoint that is not configured correctly, correct the error and use the resubmit feature for application messages or wire messages.
Resubmitting an application message for an outbound message clones the message, assigns the new message a state of RESUBMITTED, and attempts to deliver the clone. If the resubmitted application message is part of the batch message, the state of the associated wire message is set to RESUBMITTED as well. Resubmitting this type of message is helpful when the document configuration is not as required and the message must be restructured with updated settings.
Resubmitting an application message for an inbound message sets the state of the message to RESUBMITTED and attempts to deliver the message again to the back-end application. Resubmitting this type of message is useful when the back-end application is down and the delivery must be retried.
Resubmitting a wire message for an outbound message sets the state of the message to RESUBMITTED and attempts to redeliver only the previously processed message. There is no repackaging or other message transformation. This is helpful when the problem was with the delivery endpoint (for example, the receiver's server is down and unable to receive the message).
Resubmitting a wire message for an inbound message clones the wire message, assigns the new message a state of RESUBMITTED, and attempts to deliver the message. The message states of the business and application messages are also set to RESUBMITTED. The functional acknowledgment is not returned to the remote endpoint even though the endpoint expects it. This is useful when the document settings are not correct and the message must be translated and validated again.
9.1.3 Important Note About Clustered Environments
In a cluster environment, if system time stamps are not synchronized for all nodes in the cluster, you might see message time stamps that look incorrect, but are not. For example, given an unsynchronized, multi-node cluster, if an outbound message is received on one node, but the reply is sent from another node, it is possible for a report to show message receipt at 4 a.m., but an acknowledgment sent at 3:55 a.m.
9.2 Creating and Configuring Reports
Oracle SOA Suite for healthcare integration provides several predefined reports for you to get started with. These reports are filtered only by a time range. You can create additional reports that further filter messages by criteria such as endpoint, message ID, document properties, and key payload fields. You can also use the predefined reports as a basis, and either modify them or save them as new reports.
9.2.1 Creating Reports
Although several time-based reports are predefined, you can create additional reports to meet your specific requirements.
-
On the Oracle SOA Suite for healthcare integration user interface, click the Reports tab.
The main Reports page appears.
Note:
If you have already defined a default report, that report will automatically appear. You can perform the following steps from the default report page.
-
Click the plus icon in the upper right, and select New Report.
-
On the Create Business Message Report dialog, enter a name for the report and click Create.
The report appears with the Business Message Report Filter Editor displayed.
Figure 9-4 Business Message Report Filter Editor
Description of "Figure 9-4 Business Message Report Filter Editor"
-
On the Business Message Report Filter Editor, enter any of the filter criteria described in the following table.
Use the links next to Filter Conditions to quickly move between the different sections in the filter conditions list.
Note:
Multiple conditional operators are supported for most string criteria. For more information about using Any, Equals, Like, Not Equal, or Not Like, see Section 9.1.1, "About the Business Message Report Filter Editor."
Table 9-1 Business Message Report Filters
Filter Description The name of the report.
A brief description of the report.
An indicator of whether the search criteria are joined by an AND or OR operator. Select Match all of the following conditions to use AND; select Match any of the following condition to use OR.
The business message ID of the message to display. Select the operator and the enter all or part of a message ID.
The following three options specify a date range.
-
Any
Does not narrow the report by any date range, and displays messages from all dates and times.
-
Last
Narrows the report down to a range of most recent dates or times. For example, you can select the past 12 hours, past five days, or past two weeks. Slide the pointer on the sliding scale to select a time range.
-
Range
Narrows the report down to the range of dates you specify. In the From or To field, or in both fields, provide a date and time in the format shown (MM/DD/YYYY HH:MM:SS AM/PM) or click the Select Date and Time icon to select a date and specify the time.
To search for all messages after a specific date, only enter a date for the From field. To search for all messages earlier than a specific date, only enter a date in the To field. To search for all messages within a range of dates, enter dates in both the From and To fields. To exclude a specific time range, enter the first date in the range to exclude in the To field and enter the last date in the range to exclude in the From field. The search returns all messages received.
For both the from and to dates, select Inclusive to include the specified dates in the search, or deselect Exclusive to exclude those dates from the search.
The direction of the messages to display. Select from Any, Equals, or Not Equals, and then click in the field on the right to select a direction (inbound or outbound) from the list
The endpoint of the messages to display. Select the operator and then enter the name of a defined endpoint.
The state of the messages to display. Select from Any, Equals, or Not Equals, and then click in the field on the right to select one or more message states from the list.
Document
The following three fields specify document properties. For any of these fields, select Ignore case if you do not want the search to be case sensitive.
The document protocol of the messages to display. Select the operator and then enter the document protocol. For HL7 messages, enter HL7.
The document protocol version of the messages to display. Select the operator and then enter the version. For example, for HL7 2.6 messages, enter 2.6.
The document protocol type of the messages to display. Select the operator and then enter the version. For example, for HL7 ADT_A04 messages, enter ADT_A04.
Name and value pairs that narrow the search down by the contents of a field in a message. For each field name you enter, enter a corresponding value for the field. For any of the names or values, select the operator.
These fields can only be used if they are defined on the XPath page for the document definition. For Name fields, enter the name specified on the XPath page, which represents a field in the message. For Value fields, enter the expected value of the corresponding field.
For more information about key fields, see Section 9.1.1.1, "About Correlation and Payload Key Fields."
Document
The document definition used by the messages to display. Select the operator and then enter the name of a defined document definition.
A unique identifier for the interchange. This number is used to track messages, to find duplicate or missing transmissions, or to find messages that are out of sequence.
A unique identifier for the group. This number is used for auditing, to find duplicate or missing groups, or to find groups that are out of sequence.This number is referenced by the functional acknowledgment.
A unique identifier for the transaction set. The functional acknowledgment references this number for transaction set acknowledgment.
Composite
The name of the transport protocol used by the Oracle SOA composite application.
The version of the transport protocol used by the Oracle SOA composite application
The execution context ID. The ECID enables end-to-end message tracking.
The Oracle SOA composite instance ID.
The name of the Oracle SOA composite application in Oracle JDeveloper.
The name of the healthcare integration service binding component in the Oracle SOA composite application.
The name of the healthcare integration reference binding component in the Oracle SOA composite application.
The name of the WebLogic domain on which the Oracle SOA composite application is deployed.
The version of the Oracle SOA composite application in Oracle JDeveloper.
Correlation
The name of the correlation field for initiating the correlation This and the remaining correlation fields can only be used if they are defined on the Correlation page for the document definition. For usage information, see Payload Key Fields in Table 9-1.
The value of the above field.
The name of the second field for the correlation.
The value of the above field.
Error
The error code for error message to display on the report.
The text of an error message to display on the report.
Message
The unique identifier for the application message to display in the report.
The unique protocol message identifier for messages displayed in the report.
The size of the original message prior to being translated. Select from Any, Equals, Not Equal, Less than, Less than or equals, Greater than, or Greater than or equals, and provide a numerical value.
The size of the message after it is translated. Select from Any, Equals, Not Equal, Less than, Less than or equals, Greater than, or Greater than or equals, and provide a numerical value.
-
-
To revert any unsaved changes you made to the report filters, click Revert.
-
When you are done specifying report filters, do any of the following:
-
To test your filter criteria, click Search, and then click the Collapse Pane icon at the bottom left of the Business Message Report Filter Editor.
-
To save the changes you made to the filter criteria for the report, click Save.
-
To save a new report based on your changes, enter the new report name in the Name field, click the down arrow next to Save and then select Save as New.
-
9.2.2 Specifying a Default Report
You can select one report that automatically appears when you click the Reports tab. This is the default report.
-
On the Oracle SOA Suite for healthcare integration user interface, click the Reports tab.
-
Click the down arrow next to the Selected Report field, and select the report that you want to make default.
-
Click Apply.
The selected report appears. The next time you select the Reports tab, this report will automatically appear.
9.2.3 Configuring Reports
Once you create a report, you can use the Business Message Filter Editor to modify the filter criteria for the report. You can also create a new report using an existing report as a template.
-
With the report you want to configure displayed on the Reports tab, click Show Filters.
The Business Message Report Filter Editor appears.
Figure 9-5 Business Message Report Filter Editor
Description of "Figure 9-5 Business Message Report Filter Editor"
-
Modify any of the filters described in Table 9-1.
-
To revert any unsaved changes you made to the report filters, click Revert.
-
When you are done specifying report filters, do any of the following:
-
To test your filter criteria, click Search, and then click the Collapse Pane icon at the bottom left of the editor to view the report.
-
To save the changes you made to the filter criteria for the report, click Save.
-
To save the configuration as a new report based on your changes, enter the new report name in the Name field, click the down arrow next to Save and then select Save as New.
-
9.2.4 Refreshing a Report and Setting the Auto-Refresh Rate
You can manually refresh the displayed report at any time, but you can also specify that the report be automatically updated at set intervals. Note that the auto-refresh rate is only activated and configured for the current session. If you close and then re-open a report, the auto-refresh option is disabled.
To refresh a reports and set the auto-refresh rate
-
If the report you want to monitor is not already displayed, click the plus icon in the upper right of the main Reports page and select the report to configure.
-
To refresh the report, click the Refresh icon in the upper right.
-
To enable the auto-refresh option, do the following:
-
Click the down arrow to the right of the Refresh icon in the report toolbar.
-
Specify the time interval in seconds to wait between automatically refreshing the report, and then select Auto-Refresh.
-
To disable automatic refreshing, deselect the Auto-Refresh check box.
-
9.2.5 Deleting Reports
You can delete any of the reports you create. You can also delete any of the predefined reports, but use caution when doing this because this action is irreversible.
-
From the main Reports page, click the plus icon in the upper right and select Delete Reports.
The Delete Business Message Reports dialog appears.
Figure 9-6 Delete Business Message Reports Dialog
Description of "Figure 9-6 Delete Business Message Reports Dialog"
-
By default, only the reports you created appear in the list. To include predefined reports, select Include Standard Group.
-
In the reports list, select the check box next to the reports you want to delete.
-
Click Delete Selected Reports or click Cancel to close the dialog box without deleting any reports.
9.3 Viewing Reports and Report Information
When you first open a report, a list of messages matching the report criteria appears on the Reports tab. This list shows summary information for each message including the following:
-
Message ID
-
Created Date and Time
-
Direction
-
Endpoint
-
State
-
Document Type
You can select any of the messages in the list to view more detailed information and you can view a summary of multiple messages, as described in the following topics:
-
Section 9.3.4, "Viewing the Flow Trace in Oracle Enterprise Manager"
-
Section 9.3.5, "Viewing Overview Information for Multiple Messages"
If you do not have permissions to view the document type of a message, certain details are hidden from view. The option to download information is disabled unless you have the required permissions.
9.3.1 Viewing a Business Message Instance
Business messages include instance information for a document protocol, including the endpoint name, the message direction, the message ID, the state, the transport protocol and document protocol, and message details.
To view a business message instance
-
Display a report on the Reports page.
-
In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list.
Figure 9-7 Healthcare Integration Message Flow
Description of "Figure 9-7 Healthcare Integration Message Flow"
-
To view the message details in a larger area, click Business Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.
The message details appear.
-
Expand or collapse sections of the business message by clicking the arrow icon next to the section you want to expand or collapse.
-
To download information, click Download As XML or Download as Text in the section you want to download.
Note:
This option is not available in all sections.
-
If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.
9.3.2 Viewing a Wire Message
Wire messages are the native format of data sent into or out from an endpoint. Wire message details include message IDs, communication and protocol information (such as the transport binding and header details), payload message content, packed message content, and security information.
-
Display a report on the Reports page.
-
In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list.
Figure 9-9 Healthcare Integration Message Flow
Description of "Figure 9-9 Healthcare Integration Message Flow"
-
To view the message details in a larger area, click Wire Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.
The message details appear.
-
Expand or collapse sections of the wire message by clicking the arrow icon next to the section you want to expand or collapse.
-
To download information, click Download As XML or Download as Text in the section you want to download.
Note:
This option is not available in all sections.
-
If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.
9.3.3 Viewing an Application Message
Application messages provide information related to the SOA composite if a back-end composite application sent or received the message, including the composite name, version, instance ID, and so on.
To view an application message
-
Display a report on the Reports page.
-
In the messages list, select the message for which you want to view instance data.
The message flow diagram appears below the message list.
Figure 9-11 Healthcare Integration Message Flow
Description of "Figure 9-11 Healthcare Integration Message Flow"
-
To view the message details in a larger area, click Application Message in the message flow diagram and then click the Collapse Pane icon beneath the message list. You can also click Pin Current Message Details Into a New Tab to open a new page containing the detailed information.
The message details appear.
-
Expand or collapse sections of the application message by clicking the arrow icon next to the section you want to expand or collapse.
-
To download information, click Download As XML or Download as Text in the section you want to download.
Note:
This option is not available in all sections.
-
If you collapsed the message list pane, click Restore Pane above the message flow diagram to return to the message list.
9.3.4 Viewing the Flow Trace in Oracle Enterprise Manager
Healthcare integration reports provide links for each message to the flow trace of the composite in Oracle Enterprise Manager. Clicking the link automatically opens Oracle Enterprise Manager to the correct Flow Trace page.
To view the flow trace in Oracle Enterprise Manager
-
Display a report on the Reports page.
-
In the messages list, select the message for which you want to view the flow trace.
The message flow diagram appears below the message list.
Figure 9-13 Healthcare Integration Message Flow
Description of "Figure 9-13 Healthcare Integration Message Flow"
-
Click Composite in the message flow diagram.
The Login page of Oracle Enterprise Manager opens in a separate browser tab or window.
-
Enter your login information for Oracle Enterprise Manager and then click Login.
The flow trace appears for the selected message.
Figure 9-14 Message Flow Trace in Oracle Enterprise Manager
Description of "Figure 9-14 Message Flow Trace in Oracle Enterprise Manager"
9.3.5 Viewing Overview Information for Multiple Messages
You can view a summary of information for multiple selected messages in the messages list of a report. This gives you a quick view of all selected messages, including the number of messages processed, the number of endpoints and document types used, the number of errors, the number of processed messages, and so on.
To see an overview of multiple messages
-
Display a report on the Reports page.
-
In the messages list, select the messages for which you want to view summary data.
An overview of the selected messages appears beneath the list.
Figure 9-15 Multiple Messages Selected for a Report
Description of "Figure 9-15 Multiple Messages Selected for a Report"
-
From here you can purge or resubmit the selected messages.
For more information, see "To resubmit multiple messages" or "To purge messages from the repository".
9.4 Working with Error Messages
If processing for a message results in an error, the message appears in the message list with a red box over the icon. You can select error message to view additional information about the error.
9.4.1 Viewing an Error Message
This report provides information related to errors in message processing, including the error message, code, severity, level, and description.
-
Review the messages list to find messages with errors, as indicated by an error icon or a state of MSG_ERROR.
Figure 9-16 Error Message in Messages List
Description of "Figure 9-16 Error Message in Messages List"
-
When you find an error message to view, select the message.
The message flow diagram changes to display where the error occurred.
Figure 9-17 Message Flow Diagram With an Error
Description of "Figure 9-17 Message Flow Diagram With an Error"
-
Click the error icon in the message flow diagram.
The error message details appear beneath the diagram.
9.4.2 Resubmitting Messages
You can resubmit wire and application messages from the Reports tab. When a message transaction contains an error, use the reporting features to determine the nature of the error and correct it. Once the issue is fixed, resubmit the message. You can resubmit messages one at a time or in a group.
-
In the messages list for the displayed report, select the message you want to resubmit.
-
Do one of the following:
-
Select Resubmit, and then select Associated Application Message or Associated Wire Message.
-
In the message flow diagram, right-click either Wire Message or Application Message, and then select Resubmit Wire Message or Resubmit Application Message.
-
-
On the confirmation dialog that appears, click OK.
The error icon on the message in the messages list changes to a green arrow to indicate the message was resubmitted.
-
In the messages list for the displayed report, select the messages you want to resubmit.
A summary of information about the selected messages appears beneath the messages list.
Figure 9-19 Multiple Messages Selected on the Reports Page
Description of "Figure 9-19 Multiple Messages Selected on the Reports Page"
-
In the yellow bar above the Selection Overview, click Resubmit, and then select Associated Application Message or Associated Wire Message.
-
On the confirmation dialog that appears, click OK.
9.5 Purging Messages from the Repository
You can purge messages that you no longer want to store in the healthcare integration repository. If a message you purge is part of a batch process, all messages in the batch are also deleted.
You can purge messages one at a time or as a group.
To purge messages from the repository
-
In the messages list of the displayed report, select the message or messages you want to remove.
-
Click Purge.
-
On the confirmation dialog that appears, click Yes.