Viewing, Searching, and Managing Messages
All communication within a production is accomplished with messages, and the Management Portal provides many tools for viewing and working with messages. Also see Viewing Messages from Other Productions.
For background information on messages, see Concepts.
Browsing the Messages
You can view information about the messages that your production has sent or queued. The Interoperability > View > Messages page displays the messages. In addition to accessing this page from the menu, you can also access it by selecting Go to Message Viewer at the top of the Messages tab on the Production Configuration page.
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:
-
ID—The ID of the message. See Message Basics.
-
Time Created—The message creation time stamp. See Invocation Style and Message Time Stamps.
-
Session—The ID of the session associated with this message. See Sessions.
You can select the Session number in any row of the table to see a visual trace of the message object through the production.
-
Status—Indicates the status of the message. See Message Status.
-
Error—Provides a quick overview of the results returned by the message to the business host that sent it.
OK means normal behavior; Retry means the message experienced a failure but the business host that sent it is configured to retry the failed message. Error means an error was reported somewhere in the activity. Inactive means that the business host that sent the message has been idle for longer than its Inactivity Timeout setting, and may require diagnostic action.
-
Source—The business host that sent the message.
-
Target—The business host to which the message was sent.
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:
-
You can display the next page of messages. To do so, click Next.
-
You can display more messages. To do so, select a larger value for Page Size and click Search again.
The default is 100 messages.
-
You can display the previous page of messages. To do so, click Previous.
-
You can change how the messages are sorted. To do so, click a different value for Sort Order.
Also use Time Format to specify whether to show only the time or the complete time with the date. The default is Complete.
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 Interoperability > View > Messages page. The basic process is as follows:
-
Specify the filter criteria. In general, you can do this in two different ways:
-
Use the Basic Criteria and Extended Criteria areas to specify filter criteria.
-
Use the Saved Searches area to retrieve a previously saved set of filter criteria. To do so, select a value from the drop-down list and then click the check mark.
-
-
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.
-
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.
-
Optionally click Save or Save As to save the search criteria for later reuse. InterSystems IRIS 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.
Timed Out—When searching through an especially large message bank, it is possible that the search will time out before returning results. You can avoid this time out by increasing the Server Response Timeout parameter of the Web Gateway. For more information about increasing the Server Response Timeout parameter, see Configuring Default Parameters. The default value of the parameter is 60 seconds.
Filtering with Basic Criteria
To filter the messages shown in the Interoperability > View > Messages page, specify some or all of the following fields in the Basic Criteria area:
-
Status—Select a value from the drop-down list. See Message Status.
-
Type—Select a value from the drop-down list: Session Start, Request, Response, or All (the default).
-
Start Time—Enter the earliest desired message creation time stamp. See Invocation Style and Message Time Stamps.
-
Start Id—Enter the lowest desired message ID.
-
End Time—Enter the latest desired message creation time stamp.
-
End Id—Enter the highest desired message ID.
-
Source—The business host that sent the message. Choose from the list.
-
Target—The business host that is the target of the message. Choose from the list.
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:
-
To add a criterion, click Add Criterion. See the first subsection.
-
To add an OR, click Add OR. By default, the criteria are combined with AND. Use this option to combine adjacent criteria instead with OR. See How Criteria Are Combined.
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. InterSystems IRIS displays a wizard as follows:
Specify the following values:
-
Enable Criterion—Select to enable this search.
-
Criterion Type—Choose a value from the list. See the next subsection.
-
Class—Click a class name from the list. See the Class subsection.
-
Conditions—Allows you to specify fields and values for your logical statement. See the Conditions subsection.
-
Display Values—Allows you to specify additional values to display in the table. Your chosen values are displayed on the right side of the table.
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 production message body object. |
Header Field | Fields in a standard production 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 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. InterSystems IRIS 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. |
For background information about the VDoc fields in the Extended Criteria interface, see Using Virtual Documents in Productions. 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. InterSystems IRIS 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:
-
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.
-
For the second cell, select a comparison operator from the drop-down list. See the second table below.
-
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 some schemas, 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. |
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 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 the Pattern Match Operator reference page. |
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 the Pattern Matching reference page. |
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. |
When InterSystems IRIS 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, InterSystems IRIS provides details about how the message was created and sent. You can display the relevant information in multiple ways. For example:
-
Access the Interoperability > View > Messages page.
-
Select a message.
The right pane then displays the following tabs:
-
Header—Displays the fields in the message header.
-
Body—Displays the fields in the message body.
-
Contents—Displays the contents of the message body in an appropriate format.
-
Trace—Displays a small visual trace of the message and related messages through the production. To see the larger version, click View Full Trace; see the next section.
Note:On a backup mirror member, it may not be possible to view message body data.
-
The Visual Trace page displays the same information, arranged differently; it displays the message trace on the left and the Header, Body, and Contents tabs on the right.
Message Header Fields
The Header tab displays the standard fields in any production message header:
-
<ObjectId>—The ID of the message header (and also the message ID; see Message Basics).
-
TargetConfigName— The name of the business host that is intended to receive the message.
-
Type—The message type, Request or Response.
-
Invocation—Indicates how the message was sent. See Invocation Style and Message Time Stamps.
-
CorrespondingMessageId—For a request message, this field contains the message ID of the corresponding response (if any) or it is blank. For a response message, this field contains the message ID of the corresponding request.
-
SessionId—The ID of the session associated with this message. See Sessions.
-
SourceConfigName—The business host that sent the message.
-
SourceBusinessType—BusinessService, BusinessProcess, BusinessOperation, or Unknown.
-
TargetBusinessType—BusinessService, BusinessProcess, BusinessOperation, or Unknown.
-
BusinessProcessId—Every business process that gets executed has an instance and this is the object ID of that instance. If the message is a request, this field identifies the business process in whose context the message was created (sender). If the message is a response, this field identifies the business process to which it is being returned (receiver). This field is empty in various circumstances, for example if an error occurred.
-
TargetQueueName—The destination “address” for the message, this indicates where it is going:
-
If this is a name, it identifies a public queue, such as Ens.ActorOpens in a new tab.
-
If this is a number, it identifies the job ID associated with the private queue of a business host.
-
-
ReturnQueueName—The return “address” for the message, this indicates where it came from:
-
If this is a name, it identifies a public queue, such as Ens.ActorOpens in a new tab.
-
If this is a number, it identifies the job ID associated with the private queue of a business host.
The ReturnQueueId value is listed even if there is no response expected or needed for a particular request message type.
-
-
MessageBodyClassName—The class name for the message body.
-
MessageBodyId—The ID for the message body. This field matches the <ObjectId> field in the Message Body table.
-
Description—A text description of the message. The InterSystems IRIS Business Process Language (BPL) provides text in this field automatically, based on the type of BPL activity that generated the message.
-
SuperSession—The ID for messages sent via HTTP from one production to another. For details, see SendSuperSession.
-
Resent—Indicates whether this is a resent message.
-
Priority—The priority of the message relative to others in the queue, as assigned by the InterSystems IRIS messaging engine. See Message Priority.
-
TimeCreated—The message creation time stamp. See Invocation Style and Message Time Stamps.
-
TimeProcessed—The message usage time stamp. InterSystems IRIS sets this field when the message is taken off of the queue but then resets it to the current time while the message is being processed. Typically, for a completed message, it represents the time that the message processing was completed.
-
Status—Indicates the status of the message. See Message Status.
-
IsError?—The value 1 means that the message encountered an error. The value 0 means the message did not encounter any errors.
-
ErrorStatus—If IsError? is 1, then this is the text associated with the error. When IsError? is 0, ErrorStatus is the string “OK”.
-
Banked—Indicates whether or not this message is part of a message bank.
Message Body Fields
The Body tab displays the message body information. Fields include:
-
The message body class name above the list of fields.
-
If the message body is a standard production message body object, a table displays the following information:
-
<ObjectId>—The object identifier for the message body. This field matches the MessageBodyId field in the Header tab.
-
The name and value of each property in the Message Type class.
If the message body is any other type, there are no additional fields in the display.
-
Message Contents
The Contents tab displays formatted contents of the message body.
The standard production message body appears in colorized XML format, as shown in the following example:
A virtual document appears in segments, with one segment per line.
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 Using Virtual Documents in Productions.
Changing the Character Limit for XML Messages in the Contents Tab
When you select a message in the Messages page and then click the Contents tab, the Management Portal displays only the first 20000 characters of the message by default. This character limit prevents the Management Portal from becoming unresponsive while rendering very large messages such as batch files parsed with a record map. However, InterSystems IRIS enables you to modify the character limit by setting either of the following global nodes:
^EnsPortal.Settings("All","MessageContents","OutputSizeLimit")
^EnsPortal.Settings("All","MessageContents","OutputSizeLimit",<MessageBodyClassname>)
<MessageBodyClassname> is an optional node that specifies the class name of the message bodies to which the limit applies. If you set both nodes, the value in the <MessageBodyClassname> node is used.
You can set the nodes to a value of 0 or greater, where 0 indicates no limit and a positive value indicates the number of characters to display in the Contents tab. For example, to increase the character limit for the Contents tab to 30000 characters for the Demo.Loan.Msg.CreditRatingResponse sample message body class, you can issue the following command in the Terminal:
set ^EnsPortal.Settings("All","MessageContents","OutputSizeLimit","Demo.Loan.Msg.CreditRatingResponse") = 30000
The OutputSizeLimit nodes do not affect the behavior of the View Full Contents or View Raw Contents pages. If you click the View Full Contents or View Raw Contents links in the Contents tab for a message, InterSystems IRIS attempts to display the complete message. To set a character limit for either page, you can append &LIMITSIZE=limit to the page URL, where limit indicates the maximum number of characters to display. For example, to set the character limit for the View Raw Contents page to 30000, you might modify the URL, using the <baseURL> for your instance:
http://<baseURL>/csp/proddemo/EnsPortal.MessageContents.zen?HeaderClass=Ens.MessageHeader&HeaderID=3&RAW=1&LIMITSIZE=30000
Tracing the Path of Related Messages (Visual Trace)
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:
-
Access the Interoperability > View > Messages page.
-
Select a message.
-
Select the Trace tab, which displays a small version of the trace.
-
Select View Full Trace.
The left area of the Visual Trace page displays a visual representation of message activity, and the right area displays details for the selected message (if any; see Viewing the Message Details).
The trace displays 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 production messages. For example:
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 InterSystems IRIS 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:
-
The source item is marked with a circle; this is the item that sends the message.
-
The target item is marked with a rounded rectangle. The arrow points to this item, away from the source item.
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:
-
A number in square brackets outside the box on left is the message identifier.
-
A date and time within the box above the arrow indicates the message creation time stamp. See Invocation Style and Message Time Stamps.
-
The arrow is displayed in color. Normal request message arrows are blue; responses are green. If a message encountered an error, its arrow is red.
-
The text below the arrow is the message name.
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:
-
To filter for the matching request or reply for a specific message—select the message and then select Corresponding from the Apply Filter drop-down menu. This selection limits the messages displayed to the following:
-
All preceding messages with the target set to the source of the selected message.
-
If a request message is selected, the corresponding response message.
-
If a response message is selected, the corresponding request message.
-
If an ACK or IOLog message is selected, the corresponding request or reply.
-
-
To filter for all messages with a specific component as either the source or target of the message—select the column for the component and then select Host from the Apply Filter drop-down menu. This selection limits the messages to those having either a source or target of the selected component.
-
To filter for all messages having the same source and target as a specific message—select the message and then select Host from the Apply Filter drop-down menu. This selection limits the messages to those that have both the same source and same target as the selected message.
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.
If you select Legend, InterSystems IRIS displays a popup guide with additional information, as follows:
If a message is sent out from an outbound HTTP adapter to another interoperability-enabled namespace, the incoming message is assigned a new SessionID. If you want to associate the related messages across namespaces, you can use the SendSuperSession setting. If this setting is specified on an outbound HTTP adapter, the adapter sets the SuperSession property in the HTTP header. This header property is preserved through the incoming HTTP adapter and preserved throughout the production. For details, see SendSuperSession.
Resending Messages
If a message failed to be delivered, you can correct the problem that resulted in the failure, and then resend the message.
You can resend messages from the Management Portal or using a programmatic solution, as described in the following sections. A programmatic solution is more efficient for resending 100 or more messages at a time.
Resending Messages from the Management Portal
-
Access the Interoperability > View > Messages page.
-
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.
-
Select Resend Messages.
-
If you checked 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:
-
Select OK to continue with all the selected messages.
-
Select Cancel to continue with only the selected messages that were visible on the first page.
In either case, you can later cancel the action.
-
-
The system then displays details for the selected messages. The table includes the following information:
-
Session—The session to which each message belongs. Click this to view the visual trace of the primary message object through the production. See Sessions.
-
Header—The ID for the message header (also the message ID). Click this to view the visual trace of this specific message. See Message Basics.
-
Msg Body—The ID for the message body. Click this to view the message contents.
-
Created—The message creation time stamp. See Invocation Style and Message Time Stamps.
-
Source—The business host that sent the message.
-
Target—The business host that was intended to receive the message. This field also indicates if the production target is not running; note that you cannot resend a message if the intended target is not running. Click this to see the contents of the target’s message queue.
If you selected more than 1000 messages, only the first 1000 are shown, but the page indicates the total number that you selected.
-
-
Optionally select a new target business host. To do so, select a value for New target.
-
Optionally select Resubmit at head of queue.
If you do so, InterSystems IRIS 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.
Important:Before using this option, first disable the target component temporarily. This enables the production to build up the queue in the expected order, so that the target does not take messages from the queue before you have finished adding all the messages you want to resend.
-
Click one of the following:
-
Cancel—To cancel this action.
-
Resend—To resend the message or messages as specified.
-
Edit and Resend—To edit the message and resend it as specified. See the subsection for details.
-
When you resend multiple messages, InterSystems IRIS 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 Message Viewer page, you have the option to edit the body of the message before resending it.
-
Click Edit then Resend to display the Resend Editor page.
-
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.
-
Click Resend to send a new copy of the message header with your edited message body to the target.
-
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.
Resending Messages Programmatically
A programmatic solution is more efficient than the Message Viewer page for resending large numbers of messages. You can create a class using an SQL cursor and the ResendDuplicatedMessage()Opens in a new tab method of the Ens.MessageHeaderOpens in a new tab to resend 100 or more messages at a time, for example:
Class Sample.Resender Extends %RegisteredObject
{
ClassMethod Resend()
{
//Resend all messages sent from 'FromComponent' to 'ToComponent' between 2021-06-15 and 2021-06-20
&sql(DECLARE C1 CURSOR FOR
SELECT ID INTO :id FROM Ens.MessageHeader
WHERE SourceConfigName='FromComponent' AND TargetConfigName='ToComponent'
AND TimeCreated BETWEEN '2021-06-15' AND '2021-06-20')
&sql(OPEN C1)
&sql(FETCH C1)
set tSC = $$$OK
while (SQLCODE = 0) {
//id holds the id for one message. Resend it
set tSC = ##class(Ens.MessageHeader).ResendDuplicatedMessage(id)
quit:$$$ISERR(tSC)
&sql(FETCH C1)
}
&sql(CLOSE C1)
quit tSC
}
}
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:
-
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.
-
Access the Interoperability > View > Messages page.
Notice that this page now includes the Show Query button; this button is shown only if the previously mentioned global is set.
-
Select Show Query.
Managing Suspended Messages
A business operations can set the status of a failed message to suspended. In addition, a synchronous message is suspended when a productions stops before the message could be processed. You can also manually suspend a message.
InterSystems IRIS automatically places all Suspended messages on a special queue, shown in the Interoperability > View > 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:
-
Navigate to the Interoperability > View > Suspended Messages page.
-
If any messages in the currently running production are suspended, the system lists them in a table with the following information:
-
ID—The ID of the message. See Message Basics.
-
Time Created—The message creation time stamp. See Invocation Style and Message Time Stamps.
-
Session—The ID of the session associated with this message. See Sessions.
-
Error?—A quick overview of the results returned by the message to the business host that sent it.
OK means normal behavior; Retry means the message experienced a failure but the business host that sent it is configured to retry the failed message. Error means an error was reported somewhere in the activity. Inactive means that the business host that sent the message has been idle for longer than its Inactivity Timeout setting, and may require diagnostic action.
-
Source Configuration Name—The business host that sent the message.
-
-
Select the messages by selecting the check boxes in the left column.
-
Then use any of the following buttons:
-
Resubmit—Click this to resubmit the messages. As message similar to the following displays for each successfully resubmitted message:
Resubmit suspended message ID '7' completed.
Any message that you resubmit retains the same Session identifier and transmits the same Header object. The description in the message header contains text indicating this is a Resubmitted message.
-
Edit & Resubmit—Click this to edit a single message before resubmitting; this command is only valid if you select exactly one message. See the following subsection for details.
-
Discard—Click this to remove the message from list on this page. The message is still accessible from the Message Viewer, and its status is now Discarded.
-
Delete—Click this to remove all record of the message from the InterSystems IRIS database.
Caution: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 Interoperability > View > Suspended Messages page, you can edit the body of the message before resubmitting it.
-
Select Edit & Resubmit to display the Resend Editor page.
-
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, you can edit data in the message content and also edit object properties in the box below the content box.
-
Select Resubmit to resubmit the original message header with your edited message body contents to the target.
-
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.
Exporting Messages
You can download multiple messages to your local machine using the Export button of the Message Viewer, which you access from Interoperability > View > Messages . Clicking the Export button brings up a dialog box where you can specify the name of the export file, how you want to separate the messages within the file, and the character set used. The export file is downloaded to your local machine using your browser’s built-in download capabilities. You must have USE permissions for the %Ens_MessageExport resource to export messages.
Exporting Large Quantities of Messages
To prevent you from accidentally exporting a very large quantity of messages, the process for exporting large quantities is more complex. If you select all messages, but there are more messages returned by the search than fit on the results page, you must have access to the Workflow Inbox to complete the export process. For administrative instructions on giving users access to the Workflow Inbox, see Giving Users Access to Workflow Inbox .
To export large quantities of messages:
-
Go to Interoperability > View > Messages and search for the messages you want to export.
-
Click the check box in the header of the search results page to select all messages.
-
Click Export .
A dialog box appears that indicates that you have selected more messages than appear on the search results page.
-
Click OK .
-
Specify the name of the download file, how you want messages separated in the file, and the character set used.
-
Click OK twice.
-
Go the InterSystems IRIS home page.
-
Go to Analytics > User Portal . The current namespace must be enabled for Analytics to complete this step.
-
Click Workflow Inbox.
-
Select the message in the Workflow Inbox and click Confirm in the body of the message.
-
Wait until a new message titled “Exported File available for download” appears in the Workflow Inbox, then select the message.
-
Click Download in the body of the message.
-
When the file has been successfully downloaded by the browser, click Completed Download to remove the temporary file from the server.
You cannot download messages if they exceed 50% of the free disk space in the directory specified by %SYS("TempDir", namespace ) .
Giving Users Access to Workflow Inbox
You must have proper credentials to complete these steps. The user will not be able to access the Workflow Inbox unless the namespace is enabled for Analytics.
-
Go to Interoperability > Manage > Workflow > Workflow Users.
-
Select the user’s name from the Name drop-down list.
-
Select Active.
-
Click Save.
-
Go to Interoperability > Manage > Workflow > Workflow Roles.
-
In the Name field, enter: %ProductionMessageExport and click Save.
-
Select the new role from the list and click Add.
-
Select the user’s name from the User Name drop-down list and click OK.
If you want to change whether the user must confirm the download of multiple messages or who needs to confirm the export, add the EnsLib.Background.Process.ExportMessageSearchOpens in a new tab class to the production and edit the WorkFlow Settings.
Auditing Message Viewing
If the system is auditing the %SMPExplorer/ViewContents event, it writes data to the event log when the user is viewing a message in the Management Portal. If you wish to extend the kind of data written to the audit log, you can define a custom Data Transformation named EnsCustom.Util.DTL.Audit.MessageView. For more information about auditing events, see Auditing.