Skip to main content

Core Concepts

This topic discusses the concepts that are relevant when you monitor an interoperability production.

Productions

A production is a specialized package of software and documentation that integrates multiple, potentially disparate software systems. A production includes elements that communicate with these external systems, as well as elements that perform processing that is internal to the production.

InterSystems IRIS® data platform permits only one production to be running in a given namespace at any given time.

A running production continues to run even when you close the Management Portal.

Production States

It is important to be familiar with the acceptable states of a production, as well as the problem states. These states are displayed in the Management Portal:

State Meaning
Running When a production has been started and is operating normally, it has a status of Running. This is an acceptable state.
Stopped A production acquires a status of Stopped when, at the end of the shutdown sequence, all of its queues are free of synchronous messages. This is an acceptable state.
Suspended

A production acquires the Suspended status if, at the end of the shutdown sequence, some queues still contain synchronous messages, waiting for a response. Depending on how the production has been designed, this may or may not indicate a problem. If you suspect a problem, see Correcting Production Problem States.

Troubled A production acquires a status of Troubled if InterSystems IRIS is stopped but the production did not shut down properly. See Correcting Production Problem States.

Business Hosts

A production includes a number of business hosts that communicate with each other (and with external systems). A business host is responsible for some category of work.

There are three distinct types of business host. In order to monitor a production, it is not necessary to know the details of why a given business host was implemented as a certain type. However, it is useful to be aware of the types:

  • A business service receives input from outside the production, sometimes by means of an inbound adapter.

  • A business process is responsible for communication and logic that is entirely within the production.

  • A business operation usually sends output from the production, sometimes by means of an outbound adapter.

    Business operations can also be used for communication and logic within a given production.

Messages

Within a production, all communication is carried out by means of request and response messages between the business hosts. In order to understand a production at a high level, just remember that messages carry all traffic, and that the work of a production is to process messages.

Without exception, the production message warehouse stores all messages, and this information is available in the Management Portal. This section provides an overview of messages and the information that is available about them:

Message Basics

Every message is either a request or a response. There may be requests that do not have a corresponding response defined, but every response is (conceptually) paired with a request. Any request may be synchronous (waits for a response) or asynchronous (does not wait), depending on the details of the business host; you cannot configure this.

Each message has a unique numeric identifier or ID. This is displayed in many places in the Management Portal, with the caption ID or <ObjectId>, depending on the location on the page.

A message has a header, whose structure is the same for all messages. The header contains data fields that help route the message through the system. A message also contains a body, which provides different fields depending on the message type.

Diagram of a message showing a message header with an identifier and a message body with a separate identifier

Each message uses a specific message body class, chosen by the production developers. The message body class determines whether the message is a request or a response and determines the fields that the message contains. These decisions are not configurable once the production is complete.

For Electronic Document Interchange (EDI) formats, InterSystems IRIS provides specialized message body classes that represent the message as a virtual document. In this case, the message body does not contain fields to represent data in the message. InterSystems IRIS provides alternative mechanisms for accessing that data. For an introduction, see Using Virtual Documents in Productions.

The Management Portal displays contents of the message as a whole, treating the message header and the message body as a single unit. The ID of the message header is the ID of the message as a whole. In some cases (for example, if you resend a message), a new header is added (with a new unique ID); as a result, the ID of the resent message is not the same as that of the original message.

Sessions

Every message is associated with a specific session. A session marks the beginning and end of all the activities prompted by a primary request message from outside InterSystems IRIS. Sessions are useful to you because they give you an easy way to see sets of related messages; the Management Portal provides an option for visually tracing the messages, and you can filter this display by session.

Each session has a unique numeric SessionID. All messages associated with a session use the same SessionID. InterSystems IRIS assigns these SessionIDs as follows:

  1. The primary request message starts the session. The SessionID is the same as the ID of the primary request message.

  2. Each additional message that is instantiated during this session has the same SessionID as the primary request, but has a unique message ID.

The following shows an example. Note that (unlike the example) the message IDs within a session are unlikely to be sequential in a production that has many business hosts. When creating a new message, InterSystems IRIS always uses the next available integer as the message ID.

Diagram of a session numbered 1025, which contains three messages numbered 1025, 1026, and 1027

Message Status

Each message has a life cycle during which its status changes. These statuses are visible on most pages that display messages. The possible status of any message is one of the following:

Created

The message is in transit between its sender and the appropriate queue. This is the first stage in the normal life cycle of a message.

Queued

The message is on a queue. This is the second stage in the normal life cycle of a message.

Delivered

The intended recipient has received the message. This is the third stage in the normal life cycle of a message.

Completed

The intended recipient has received the message and has finished processing the message. This is the fourth stage in the normal life cycle of a message.

Deferred

This status applies only to response messages.

A business operation can defer a message response for later delivery. The response can be picked up and sent back to the original requester by any business host in the production. Between the time when the business operation defers the response, and when the response is finally sent, the response message has a status of Deferred.

The sender of the original message is unaware of the fact that the message was deferred. If the original call was synchronous, the call does not return to the sender until the response is sent.

When the response message is finally sent, it has a status of Completed.

Discarded

A response message becomes Discarded if it reached its destination after the timeout period for the corresponding request expired.

You can also manually mark a message as Discarded, which you might do for a suspended message that cannot be delivered for some reason.

Note that a message that is marked as Discarded still remains in the permanent store; messages are deleted only when you explicitly delete them.

Suspended

The message was suspended by the business operation after failing to reach its external destination or was manually suspended by an administrator. Note that some business operations are designed to set the status of any failed messages to Suspended.

In either case, you can view this message within the Management Portal to determine why it failed and you can resend it if appropriate. For example, if the problem is on the external side of the communication, the external system can be repaired, and then the message can be resent. You could also discard it or even delete it.

Aborted

The message was aborted by an administrator.

Error

The message encountered an error.

Note that request and response messages have separate statuses. Request-response pairs are not tracked together for various reasons: a request might be repeated several times before it is successfully delivered; some requests have an optional response that can be ignored if it does not arrive; some responses can be deferred for later delivery; some requests are designed to have no response.

Message Invocation Style and Time Stamps

Each message has an invocation style, which describes how the message was sent. The business host that sends a message specifies its invocation style:

  • Queue means the message is created in one job, then placed on a queue, at which time the original job is released. Later, when the message is processed, a different job will be allocated for the task.

  • Inproc means the message will be formulated, sent, and delivered in the same job in which it was created. The job will not be available again in the sender’s pool until the message is delivered to the target.

InterSystems IRIS records the following two time stamps for each message. Note that the invocation style affects the meaning of these time stamps:

  • The message creation time stamp. For Queue messages, this is when InterSystems IRIS placed this message on the queue. For Inproc messages, this is when InterSystems IRIS called the Send method.

  • The message processed time stamp. InterSystems IRIS sets TimeProcessed when the message is taken off 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.

Message Priority

The Management Portal displays the priority of the messages in several places. The priority of a message determines how that message is handled relative to other messages in the same message queue. For information about message queues, see Monitoring a Production.

The InterSystems IRIS messaging engine determines the priority of a message, which is one of the following:

  • HighSync (1) — Used for ACK messages and alarms for interrupted tasks.

  • Sync (2) — Used for synchronous messages.

  • SimSync (4) — Used for an asynchronous call made for a BPL synchronous <call>. This ensures that the request and response are processed before any queued asynchronous message.

  • Async (6) — Used for other asynchronous messages.

Jobs and Message Queues

The business hosts process messages by means of jobs. A job is a CPU process that hosts the work done by a production. This terminology is intended to avoid confusion between CPU processes (jobs) and business processes (processes).

In general, a job is either running (processing a message) or it is not running. From a low-level, system viewpoint, a production consists almost entirely of jobs waiting to wake up to perform work.

A pool consists of one or more jobs. Each business host can have its own, private pool of allocated jobs — a pool with a specific size that cannot be exceeded.

When a business host receives a message, the business host assigns the work to a job from its pool. The job then performs the work. If no job is available, the business host waits for a job to become available. After the job completes the work, the job either returns to the pool or starts work on another message.

More formally, each message is assigned to a specific message queue, which handles messages in the order that it receives them. Each queue is associated with a single pool, and vice versa.

Unlike other types of business host, a business process can use a public pool (called the actor pool), which receives messages from a public queue (called the actor queue or Ens.ActorOpens in a new tab). The actor pool and actor queue are shared by all business processes that do not use private pools and queues.

For further information, see Pool Size and Actor Pool Size.

FeedbackOpens in a new tab