Monitoring Ensemble
Viewing, Searching, and Managing Messages
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

All communication within a production is accomplished with messages, and the Management Portal provides many tools for viewing and working with messages. This chapter includes the following sections:

Also see the chapter Viewing Messages from Other Productions.”
For background information on messages, see the chapter Concepts.”
Browsing the Messages
You can view information about the messages that your Ensemble production has sent or queued. To access the [Ensemble] > [Message Viewer] page, do either of the following in the Management Portal:
The middle area lists the messages. To refresh this area, click the Search button. You can use the bottom left area to filter the list of messages; for information, see the following section. The right area displays details; see Viewing Message Details and Tracing the Path of Related Messages.”
Available Information
The top area of this page displays the following information for each message:
The Session column also uses color as follows:
Background Color Indication
Red The message encountered an error.
Green The message marks the start of a session.
Silver The message arrived after a timeout expired and is marked as discarded.
Orange The message is suspended.
White and pale tan, in alternating rows These messages are OK or are queued.
If you are using the Message Bank Viewer, there is an additional option to specify the Message Bank client to search. See Using the Enterprise Message Bank
Paging Through the Messages
Typically there are multiple pages of messages. To see all the messages, you have the following options:
Also use Time Format to specify whether to show only the time or the complete time with the date. The default is Time Only.
The read-only Page field indicates which page of the list is being displayed.
Filtering the Messages
To find a specific message more easily, you can filter the messages shown in the [Ensemble] > [Message Viewer] page. The basic process is as follows:
  1. Access this page as described in previously.
  2. Specify the filter criteria. In general, you can do this in two different ways:
  3. Click Search. The page is redisplayed with a list of messages that match your filter criteria. If the search has not yet completed, you can interrupt it by clicking Cancel.
    Or click Reset to restore the default criteria.
  4. If more matches are found than can be displayed, the Next button is active, and you can use that. Or, to display more data, select a larger value for Page Size and click Search again. Or adjust your filter criteria to narrow the search.
  5. Optionally click Save or Save As to save the search criteria for later reuse. Ensemble then displays a field in which you provide a name for the search criteria. Enter a value and click the check mark.
    This operation overwrites any previously saved criteria with the same name.
    To delete a saved search, click its name in the Saved Searches list and then click the red X.
Filtering with Basic Criteria
To filter the messages shown in the [Ensemble] > [Message Viewer] page, specify some or all of the following fields in the Basic Criteria area:
If you are using the Message Bank Viewer, there is an additional filter that restricts the search to a single Message Bank client. See Using the Enterprise Message Bank.
Filtering with Extended Criteria
The Extended Criteria area enables you to filter the displayed messages by extremely specific criteria. An advanced filter consists of one or more conditions, combined with the logical operators AND and OR. Each condition can use any information contained in the messages, comparison operators from a rich set, and your arbitrary expressions. Only messages that meet all the combined conditions are displayed.
To use this area, click the triangle next to Extended Criteria. Then do either of the following:
After you add these items, the Extended Criteria list displays your selections. For example:
When you are satisfied with your selections, click Search. The Message Viewer page displays the list of messages that match all your filter criteria.
Adding a Criterion
To add a criterion, click Add Criterion. Ensemble displays a wizard as follows:
Specify the following values:
Click OK to save this criterion and add it to the Extended Criteria list.
Criterion Type
For Criterion Type, select a value from the drop-down list, if applicable. The following table lists the choices and how they affect your subsequent choices in the Class and Conditions fields.
Type Class and Conditions refer to...
Body Property Properties of a standard Ensemble message body object.
Header Field Fields in a standard Ensemble message header object.
OR (used to logical OR two filter terms)
SearchTable Field Entries in a search table class that you have defined in this Ensemble namespace. A search table class is a specialized tool that you create to work with virtual documents.
VDoc Segment Field Fields in a virtual document message segment. Identify the standard and the segment of interest. Ensemble then prompts you to choose from a list of fields in that segment.
VDoc Property Path Fields in a virtual document message segment. Identify the standard and then enter a virtual property path that identifies a message segment and field that is valid for that standard.
Note:
For background information about the VDoc fields in the Extended Criteria interface, see Ensemble Virtual Documents. You do not need to use these fields unless your production routes some type of virtual document.
Class
For Class, select a value from the drop-down list, if applicable. Ensemble lists all the classes appropriate for the selected Criterion Type. For example:
Type Class Name
Body Property Choose from all the message classes in this namespace.
Header Field
OR
SearchTable Field Choose from all the search table classes in this namespace.
VDoc Segment Field Choose from all the virtual document classes in this namespace.
VDoc Property Path Choose from all the virtual document classes in this namespace.
Filter Conditions
For Conditions, specify fields and values for your logical statement, from left to right, as follows:
  1. For the first cell, select a value from the drop-down list, which includes all choices appropriate for this context. For further instructions, see the first table below.
  2. For the second cell, select a comparison operator from the drop-down list. See the second table below.
  3. In the third cell, type the literal string that you intend to match using the selected operator.
    Do not use double quotes around the string.
Choices in the Conditions panel vary according to your choice of Type. The following table describes the choices.
Type Conditions
Body Property Choose from all the properties in the Class Name message class.
Header Field
OR
SearchTable Field Choose from all the search table entries defined in the Class Name search table class.
VDoc Segment Field Select a value for Segment Type and then select a value for Field Name. (Or type values, if you know the applicable values.)
For HL7, you can type a numeric references if you prefer them to names, for example [5], [18.1], or 2.3.1:[3().1]. You may edit out the category reference and colon prefix, but keep the square brackets and their contents intact.
Square brackets differ from curly brackets in that square brackets enclose a segment:field combination that does not require you to identify its containing message structure. In the example above, Ensemble matches any message structure in the 2.3.1 schema category that contains a PID segment with a PatientAddress().city field .
VDoc Property Path Select a value for Doc Type and then select a value for Property Path. (Or type values, if you know the applicable values.)
Instead of selecting options to fill the left-hand Conditions field, you can type a virtual property path into the field, as long as you are careful to use the correct syntax. Curly bracket syntax requires a specific message structure, such as ADT_A06, to be identified.
The comparison operator between the two values in a Conditions statement can be any one of the following.
Operator The condition is true when the value at left is...
= Equal to the value on the right.
!= Not equal to the value on the right.
> Greater than the value to the right of the operator.
>= Greater than or equal to the value to the right.
< Less than the value to the right.
<=
Less than or equal to the value to the right.
If a condition >, >=, <, or <= involves strings, they are sorted alphabetically to determine the result. Symbols and numbers sort before alphabetic characters.
Contains
A string that contains the substring to the right.
The Contains operator is case-sensitive (except possibly within search table fields). If the value at left is Hollywood, California and the value at right is od, Ca, there is a match, but a value of Wood does not match.
The Contains operator might or might not be case-sensitive in search table fields, depending on the implementation of a particular search table class.
DoesNotContain A string that does not contain the substring at right.
DoesNotMatch A string that does not match the pattern in the string specified to the right, which uses syntax suitable for the ? pattern matching operator in ObjectScript. For details, see Pattern Matching in the chapter “Operators and Expressions” of Using Caché ObjectScript.
In Identical to one of the items in the comma-delimited string at right.
NotIn Identical to none of the items in the comma-delimited string at right.
StartsWith A string that starts with the substring at right.
DoesNotStartWith A string that does not start with the substring at right.
Like
A string that matches the pattern in the substring specified to the right, according to the rules for the LIKE predicate in SQL.
Matching for the Like and NotLike condition may be summarized as follows: The character “_” matches any single character, and the character “%” matches any sequence of zero or more characters. Thus, if the value at left contains the pattern %Com_ and the selected operator is Like, values of TransCom1 and UltraCom2 match, but values of UltraCom17 and Foxcom8 do not match.
Matches
A string that matches the pattern in the string specified to the right, which uses syntax suitable for the ? pattern matching operator in ObjectScript. For details, see Pattern Matching in the chapter “Operators and Expressions” of Using Caché ObjectScript.
NotLike A string that does not match the pattern in the substring specified to the right, according to the rules for the LIKE predicate in SQL.
InFile Found in the text file whose full pathname is specified to the right.
NotInFile Not found in the text file whose full pathname is specified to the right.
Important:
When Ensemble indexes virtual documents (thus adding to the search tables), it replaces any vertical bar (|) with a plus sign (+). Take this into consideration when you use the search table to search for content. For example, to search for a message that contains my|string, use my+string as the search criterion.
Rearranging and Modifying Criteria
If you have multiple items in the Extended Criteria section, you can click the up-arrow and down-arrow icons to adjust their order.
To edit an item, click the edit button for that item.
To delete an item, click X.
How Criteria Are Combined
If Extended Criteria displays contains multiple criteria, they are implicitly joined by AND. For example, suppose that you have three statements visible:
Logical Statement 1
Logical Statement 2
Logical Statement 3
In this case, your filter actually works like this:
Logical Statement 1
AND
Logical Statement 2
AND
Logical Statement 3
To modify this logic, use Add OR and reposition the OR as needed. Suppose you added an OR row and a fourth logical statement to the list shown above. The Extended Criteria panel now looks like this:
Logical Statement 1
Logical Statement 2
Logical Statement 3
OR
Logical Statement 4
And the resulting logic is now:
Logical Statement 1
AND
Logical Statement 2
AND
Logical Statement 3
OR
Logical Statement 4
The operator AND binds more tightly than OR, so the effect of the above sequence is actually:
(1 AND 2 AND 3) OR 4
Viewing Message Details
For each message, Ensemble provides details about how the message was created and sent. You can access the relevant page from multiple places. For example:
  1. Access the [Ensemble] > [Message Viewer] page as described in Browsing the Messages.”
  2. Click a message.
The system displays the following tabs in the right pane:
The following subsections describe the Header, Body, and Contents tabs.
The Trace tab displays a subset of the data and options that you see on the larger Visual Trace page. The Visual Trace page is described in the next section.
Message Header Fields
The Header tab displays the standard fields in any Ensemble message header:
Message Body Fields
The Body tab displays the message body information. Fields include:
Message Contents
The Contents tab displays formatted contents of the message body.
The standard Ensemble message body appears in colorized XML format, as shown in the following example:
A virtual document, such as an HL7 message, appears in segments, with one segment per line, as shown in the following figure:
For example, for HL7 messages, each line displays the following, from left to right:
To view all the contents of large virtual document, it may be necessary to drag the bottom scroll bar far to the right. To view the message in a wider display, click the View Full Contents link or the View Raw Contents link. View Full Contents displays the message formatted by fields and View Raw Contents displays the unprocessed message contents, which can easily be copied and pasted into a text editor. For background information, see Ensemble Virtual Documents. Or see the book for a specific kind of virtual document.
Tracing the Path of Related Messages
The Visual Trace page enables you to visually trace the path of a set of related messages between business hosts. You can access this tool from multiple places. For example:
  1. Access the [Ensemble] > [Message Viewer] page as described in Browsing the Messages.”
  2. Click a message.
  3. Click the Trace tab, which displays a small version of the trace.
The left area of the Visual Trace page displays a visual representation of message activity, with one column for each business host that handles the message. The business hosts are grouped into business services, business processes, and business operations.
If you enable the Archive IO setting for one or more business service and business operations, the Visual Trace also displays the input and output data in addition to the Ensemble messages. For example:
Note:
When you view calls with this tool, synchronous calls from long-running business processes are portrayed as if they were asynchronous. This does not change the fact that the calls are actually synchronous. It is a side effect of the internal tracking mechanism that Ensemble uses to free system resources while it is waiting for a synchronous call to return.
When a message has traveled from one item to the next, an arrow connects the two items within a rounded box:
In both cases, you can read the name of the business host at the top of the column.
Each of these rounded boxes corresponds to a message and displays information as follows:
Additional lines indicate when a given business host receives and later sends a message.
If there are many messages shown in the full trace, it can be useful to limit the messages displayed by using a filter. This is also useful if you are trying to find messages that are related to an ACK or Archive IO message. The Apply Filter drop-down allows you to restrict messages in the following ways:
When you apply a filter, the message trace displays the filter it is applying. For example:
Filter = SourceHost:MsgRouter250, TargetHost:TCPOp001
Once you have applied a filter, the Apply Filter label changes to Reapply Filter. If you change the selection of the value of the drop-down menu, you must select Reapply Filter to change filters.
If there are more messages than will display on a page, you can use the Items per page drop-down to control the number of items displayed. You can either use the Go to items drop-down or the Previous Page and Next Page links to scroll through the pages.
The right area displays details for the selected message in the trace. The Header, Body, and Contents tabs display the same information as the [Ensemble] > [Message Viewer] page; see Viewing the Message Details.”
If you click Legend, Ensemble displays a popup guide with additional information, as follows:
If a message is sent out from an outbound HTTP adapter to another Ensemble namespace, the incoming message is assigned a new SessionID. If you want to associate the related messages across namespaces, you can use the SendSuperSession and Generate Super Session ID settings. If these settings specify that SuperSession should be used, the inbound and outbound adapters set the SuperSession property in the HTTP header. This header property is preserved through the incoming HTTP adapter and preserved throughout the Ensemble production. For details, see SendSuperSession in Using HTTP Adapters with Ensemble. You can extend the use of SuperSession to other adapters with custom code.
Resending Messages
Sometimes it is useful to resend a message, particularly if the message delivery failed. (You would first correct any underlying problem, of course.) To resend messages, do the following:
  1. Access the [Ensemble] > [Message Viewer] page as described in Browsing the Messages.”
  2. Select the messages by selecting the check boxes in the left column. Or filter the display appropriately and then click the check box at the top of the left column.
    If you need to edit messages before resending them, then select a single message. You cannot use the Edit and Resend option (shown later) if you select multiple messages on this page.
  3. If you clicked the check box at the top of the left column and if there are multiple pages of selected messages, the system then displays the following message:
    More messages match your search criteria than appear here. If you want to resend all the messages that match your criteria, including those not shown on this page, click OK. To resend only your selected messages, click Cancel.
    Now do one of the following:
    In either case, you can later cancel the action.
  4. The system then displays details for the selected messages. The table includes the following information:
    If you selected more than 1000 messages, only the first 1000 are shown, but the page indicates the total number that you selected.
  5. Optionally select a new target business host. To do so, select a value for New target.
  6. Optionally select Resubmit at head of queue.
    If you do so, Ensemble places the resent message at the front of its target queue. This helps to preserve FIFO (first in, first out) processing when the order of messages is important.
  7. Click one of the following:
When you resend multiple messages, Ensemble resends them in order by age, starting with the oldest messages.
When you resend the messages, the page is redisplayed with an additional Resend Status column. Any status other than OK indicates that the resend operation failed. A resent message retains the same Session identifier and transmits the same message body, but acquires a new message header (with a new, unique ID) to mark its additional trip through the production. The visual trace includes both the original message transmission and any resend operations that involve the same message. The description in the message header contains text indicating this message has been resent; the description includes the original along with any subsequent header object identifiers.
Resend Editor
When you select one message to resend from the Ensemble Message Viewer page, you have the option to edit the body of the message before resending it.
  1. Click Edit then Resend to display the Ensemble Resend Editor page.
  2. Use the entry fields to update the message body data. The fields vary depending on the message. If the message has no properties, none are displayed.
    If you are editing a virtual document message, you can edit data in the message content and also edit object properties in the box below the content box.
  3. Click Resend to send a new copy of the message header with your edited message body to the target.
  4. After a successful resend, the page refreshes with text indicating the new Header and Msg Body identifiers. Click Trace to see the visual trace of the resent message.
Viewing the SQL Query Used by the Message Viewer
For debugging purposes, you might want to view the SQL query currently used by the Message Viewer. To do so:
  1. Open the Terminal, change to your working namespace, and enter the following command:
     Set ^Ens.Debug("UtilEnsMessages","sql")=1
    
    This command sets a code in a utility debugging global.
  2. Access the [Ensemble] > [Message Viewer] page as described in Browsing the Messages.”
    Notice that this page now includes the Show Query button; this button is shown only if the previously mentioned global is set.
  3. Click Show Query.
Managing Suspended Messages
As noted earlier, some business operations might set the status of a failed message to suspended. Alternatively, you can manually suspend a message.
Ensemble automatically places all Suspended messages on a special queue, shown in the [Ensemble] > [Suspended Messages] page of the Management Portal. You can use this page to determine why the message failed, fix the problem, and then resend the message. For example, if the problem is that an external destination went out of service, you can make a change to reestablish communication with that server. Then you can resubmit the suspended messages to the external server from this page. Or you can discard or delete the message.
To manage suspended messages, do the following:
  1. Click Ensemble.
  2. Click View.
  3. If any messages in the currently running production are suspended, the system lists them in a table with the following information:
  4. Select the messages by selecting the check boxes in the left column.
  5. Then use any of the following buttons:
    Warning:
    You cannot undo the Discard or Delete operations.
Any message that you edit and resubmit retains the same Session identifier and includes the same Header object, but it contains a new Msg Body object with a new identifier. The description in the original message header contains text indicating that this message has been resubmitted and includes the original Msg Body object identifier.
Resend Editor for Resubmitting Messages
When you select one message to resubmit from the [Ensemble] > [Suspended Messages] page, you can edit the body of the message before resubmitting it.
  1. Click Edit & Resubmit to display the Ensemble Resend Editor page.
  2. Use the entry fields to update the message body data. The fields vary depending on the method signature of the message. If the method has no properties, none are displayed.
    If you are editing a virtual document message (HL7, X12, or other), you can edit data in the message content and also edit object properties in the box below the content box.
  3. Click Resubmit to resubmit the original message header with your edited message body contents to the target.
  4. After a successful resubmit, the page refreshes with text indicating the Header and Msg Body identifiers. Click Trace to see the visual trace of the resubmitted message.