Parts of an XI Message

XI messages are generated by the messaging service of the Adapter Framework for the receiver direction and by the JCA resource adapter or one of its modules for the sender direction. They are the Java representation of the SOAP XI messages that are transported between the Integration Server and the Adapter Framework.

The Message interface allows you to access all public parts of the XI message. The following describes the differences between the various class properties.

Message Identification with the Message ID

Every XI message must be uniquely identifiable in the system landscape. This is achieved by using an ISO-11578-compliant GUID (Globally Unique Identifier). Every XI message has a message ID, irrespective of its type (asynchronous/synchronous request, synchronous response). This is generated by the sender of the message. The standard makes it highly unlikely that the same message ID is generated twice.

The message object contains direction information (MessageDirection), which can be used by the modules. The direction information and the message ID together form the MessageKey. The MessageKey is used in the MessageException and for the audit log.

More information: Creating Audit Log Entries

RefToMessageID

RefToMessageID is the message ID of a previous message that is referenced by the current message. In the case of a synchronous response, RefToMessageID must be set to the message ID of the referenced message. Otherwise, RefToMessageID must be empty.

SequenceId and SerializationContext

In some integration scenarios the sequence of the messages is important. The message has the DeliverySemantic Exactly Once In Order.

Messages of a serialization context must be forwarded in the same sequence that they were received. The serialization context of the Adapter Framework comprises Direction + QueueId + ToParty + ToService. QueueId corresponds to the qRFC QueueId in the Integration Server. It can be set and read using set/getSequenceId().

You can use getSerializationContext() to read the serialization context.

CorrelationID

You may sometimes need to correlate messages with each other. To allow you to do this, the XI message header contains the ConversationIDfield. The following API methods are available to set the field.

• Message.getCorrelationId()
• Message.setCorrelationId()

Relationship Between APIs and Message Header Fields

TimeSent and TimeReceived Time Stamps

The TimeSent property contains the time at which the message is sent from the Adapter Framework messaging service. If the message has not yet been sent, the value from getTimeSent() is undefined.

The TimeReceived property contains the time at which the Adapter Framework receives the message.

From/To Addressing Elements

The sender (from) or receiver (to) properties represent the sender or receiver of a message respectively. They comprise the following elements: party and communication component. Within a domain, the combination of party and communication component defines a message sender or message receiver uniquely. In the A2A case, the party information is usually left empty. The communication component, on the other hand, is always filled. Therefore, the creator of a message must always specify the communication component and the communication channel. The party is only filled in B2B cases.

More information: Party , Communication Component , Communication Channel

You are free to choose the communication component of a sender/receiver. In the Integration Server, it can be any of the following:

• A business communication component
• A business process
• A name of your choice. This option is usually used in B2B scenarios between business partners.

The interface that is used between the sender and receiver is defined in the action class. . The term action is identical to the interface as defined in the Enterprise Services Repository.

Quality of Service

Quality of service describes mechanisms relating to the message transport. These include:

• Guaranteed delivery of messages within Process Integration
• Check for duplicate messages
• Delivery in the correct sequence (serialization)

The XIMessage interface supports the approach in which the quality of service is specified within the XI message. The following qualities of service are available:

• Best Effort: The message is sent to the receiver without guaranteed delivery, check for duplicate messages, or serialization mechanisms.
• Exactly Once: The message is sent to the receiver exactly once. There is no serialization. All components that are involved in the message processing (including modules and the JCA adapter) must guarantee delivery of the message exactly once by the correct transactional procedure.
• Exactly Once In Order: This mode is an extension of the Exactly Once mode. In addition to the above-specified characteristics, serialization takes place on the sender side. All components must guarantee that messages are delivered exactly once and in the same sequence that they were sent. Serialization is achieved using a queue that is identified in the serialization context.

Each message must contain a value for the quality of service in the DeliverySemantics property.

Two types of message processing are available:

• If you are sending a message synchronously, you must choose the quality of service Best Effort.
• If you are sending a message asynchronously, choose Exactly Once or Exactly Once In Order.

An application can only react to error situations in the synchronous case, since it receives a synchronous response. In asynchronous communication, the sender does not expect a response.

Message Class

XI messages can originate from various classes (ApplicationMessage, SystemError, and so on). To determine the message class, use the API method Message.getMessageClass().

Set Adapter-Specific Message Attributes

Adapters can support additional attributes contained in the XI message header fields. Using the attribute namespace and the technical name of the attribute, these attributes can be accessed in routing and mapping. Read-access to the attributes is possible in the Business Process Engine.

You use the following API methods to set and read these fields:

• Message.setMessageProperty()
• Message.getMessageProperty()

Make the setting of the attributes in the sender channel and the reading of them in the receiver channel configurable by defining the attributes supported by your adapter in the adapter metadata.

Furthermore, the AdapterTypeMetaData/DynamicAttributes element must be inserted in the adapter metadata. The individual attributes are specified as references.

<DynamicAttributes>

<AttributeReference>

<ReferenceName>myAttribute</ReferenceName>

<AttributeReference>

<DynamicAttributes>

Describe myAttribute using an <Attribute> element, as for static configuration attributes. Adapter-specific message attributes must be of the type String .

For more information about the selection and use of adapter-specific message attributes, see Adapter-Specific Message Attributes in the Message Header .

Message Payload

The message interfaces differentiate between the application payload, which is referred to as the document and is generally an XML business document, and the attachments of the application payload. A message can contain one document or no documents, and no, one, or several attachments.

The document is processed as it passes through the Integration Server (for example, by mapping). Attachments are forwarded to the receiver unchanged.

Use the PayloadSwapBean module to exchange an attachment with the payload. You can then edit the attachment.

More information: PayloadSwapBean

The Message interface provides several methods for creating and reading the payload. You can use the following classes to process a payload instance:

• Payload
• TextPayload
• XMLPayload

Payload

The Payload class provides methods for setting, determining, and deleting attributes. The XI protocol is based on SOAP with attachments. MIME attachments have attribute, such as content disposition or content type. You can manage attributes using the following statements:

• getAttributeNames()
• clearAttributes()
• getAttribute(String attributeName)
• setAttribute(String name, String value)
• removeAttribute(String attributeName)

TextPayload, XMLPayload

In TextPayload and XMLPayload the character set (encoding) of the data is important and must be set and read correctly. The encoding is set in the XML document. The setting here and in the XML document must match as XML payloads are handled as binary payloads.

• TextPayload.getEncoding() delivers the Java string encoding name of the character set of the text data in the object.
  Note

  The names are defined at iana.org/assignments/character-sets. The Java runtime environment does not support all the names; if there are several possible names, choose the preferred MIME name.

  • In the receiver direction, an adapter must first read the character set using TextPayload.getEncoding() and, if necessary, convert to the character set of the external system or protocol.
  • In the sender direction, you should provide a configuration option for converting non-UTF-8 text data to UTF. If the adapter does not use setText() and thus uses UTF-8, it must make the character set of the text data known using setContent().
• XMLPayload inherits from TextPayload and also has the getEncoding() and setContent() methods. These are not relevant for the encoding of the XML document. Instead, the encoding of the XML document is made known in the encoding attribute of the xml element of the XML document, as specified in XML 1.1, for example "<?xml version="1.0" encoding="UTF-8"?>".
  • In the receiver direction, the adapter must read the encoding attribute and, if necessary, convert the XML document to the character set of the external system or protocol. In this case, the encoding in the XML document also has to be adapted.
  • In the sender direction, you should provide a configuration option for converting non-UTF XML data to UTF. In any case, the adapter must make the character set of the XML data known in the encoding attribute.

    SAP recommends that you only send UTF XML documents to the Adapter Framework to avoid conversion problems (for example, with modules that do not use an XML parser but treat the payload as a string).