Parts of an XI Message
Use
XI messages are generated by the messaging service of the Adapter Framework for the receiver direction and by the JCA resource adapter 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 different class properties.
Features
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 also 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. See: Generating Audit Log Entries
ConversationID and RefToMessageID
To support complex communication procedures as simple request/response mechanisms, the sender is provided with the optional ConversationID tag for each message. All messages with the same ConversationID belong to the same communication procedure or integration process.
If DeliverySemantic (see below under Quality of Service) is Exactly Once In Order, the ConversationID is identical to the queue ID of the Integration Server. This defines the serialization context, and all messages with the same ConversationID and with quality of service Exactly Once In Order must be delivered in the same sequence that they were received.
RefToMessageID is the MessageID 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.
CorrelationID
You may sometimes need to correlate messages with each other. To allow you to do this, the XI message header contains the ConversationID field. The following API methods are available to set the field.
● Message.getCorrelationId()
● Message.setCorrelationId()
Relationship Between APIs and Message Header Fields
XI Message Header Field |
Set/Read by API |
ConversionID |
Message.getCorrelationId() Message.setCorrelationId() |
QueueID |
Message.getConversationId() Message.setConversationId() |
RefToMessageID |
Message.getRefToMessageId() Message.setRefToMessageId() |
TimeSent and TimeReceived Time Stamps
The TimeSent property contains the time at which the message was sent from the Adapter Framework messaging service. The TimeReceived property contains the time at which the Adapter Framework received the message.
From/To Addressing Elements
The sender (from) or receiver (to) properties represent the sender or receiver of a message respectively. They consist of the elements party and service. Within a domain, the combination of party and service defines a message sender or message receiver uniquely. In the A2A case, the party information is usually left empty. The service, on the other hand, is always filled. Therefore, the creator of a message must always specify the service and the communication channel. The party is only filled in the corresponding (B2B) cases.
The party agency and scheme used in the NormalizationManagermust always be set to http://sap.com/xi/XIand XIParty and can therefore not be specified in the party class.
You are free to choose the service property of a sender/receiver. In the Integration Server, a service can be any of the following:
● A business system
● An integration 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.
Quality of Service
Quality of service describes mechanisms relating to the message transport. These include:
● Guaranteed delivery of messages within SAP Exchange Infrastructure
● Check for duplicate messages
● Delivery in the correct sequence (serialization)
The algorithms that guarantee the quality of service can be provided in different ways. They can be based on end-to-end acknowledgments or on quality-of-service models such as Best Effort or Exactly Once.
The XIMessage interface supports the latter approach. The quality of service is specified in 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 (defined by the ConversationID), which is used 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 want to send a message synchronously, you must choose the quality of service Best Effort.
● If you want to send 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().
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.
Provide the same options as those provided by SAP in the file/FTP adapter, for example. For more information, see the adapter metadata of the file/FTP adapter in the namespace http://sap.com/xi/XI/System of the software component SAP BASIS in the Integration Repository.
The AdapterTypeMetaData/DynamicAttributes element must be inserted in the adapter metadata. The individual attributes are then specified as references.
<DynamicAttributes>
<AttributeReference>
<ReferenceName>myAttribute</ReferenceName>
<AttributeReference>
<DynamicAttributes>
Describe myAttribute using an <Attribute> element, as is done 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 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). The attachments are forwarded to the receiver unchanged.
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
In TextPayload and XMLPayload the character set (encoding) of the data is important and must be set and read correctly.
● TextPayload.getEncoding() delivers the Java string encoding name of the character set of the text data in the object.
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/outbound case, 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/inbound case, the adapter must be able to be configured to convert non-UTF-8 text data to UTF-8. 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 therefore also has the getEncoding() and setContent() methods. However, 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/outbound case, an adapter must read the encoding attribute and, if necessary, convert the XML document to the character set of the external system or protocol.
○ In the sender/inbound case, it must be possible to configure the adapter to convert non-UTF-8 XML data to UTF-8. In any case, the adapter must make the character set of the XML data known in the encoding attribute.