Concept - IOM SOAP Web Services

1 Introduction

The Intershop Order Management (IOM) uses the Simple Object Access Protocol (SOAP). The present concept gives some basic information about the SOAP web service handling of the IOM and is primarily intended for all developers implementing a project or working in the core product of IOM.

1.1 Glossary

HTTPHypertext Transfer Protocol
HTTPSHypertext Transfer ProtocolSecure
IOMThe abbreviation for Intershop Order Management
SOAPSimple Object Access Protocol
SSLSecure Sockets Layer
WSDLWeb Service Description Language
PSPPayment Service Provider
Wording

Description

1.2 References

2 General Assumptions

The IOM is a transaction platform that can be used as meta-shop or meta-supplier to handle multiple shops/suppliers. From a shop's perspective the IOM works as a supplier that processes and transmits the data to the actual supplier. This way a shop system has to communicate with only one supplier, the IOM instead handles a large number of suppliers. From a supplier's perspective the IOM works as a shop which is connected to multiple shops, sales channels, marketplaces and so on.

The business process transaction is a transmission exchange between the business partners, in which each part can have the role as a sender and a receiver of a message. For technical clarification it has to be defined how to transmit data between the business partners. For this different business protocols have to be considered.

The IOM assumes that messages are pushed. That means that the sender is always the active part of the transmission.


2.1 Transmission Logging

Each transmission and also each attempt of a transmission, both sending and receiving, has to be logged by both communication partners. So the complete message content together with the response (or error response) has to be saved and called with suitable access paths (e.g., message IDs, time stamps, etc.).

Note

Only a message which can present the original message together with the response applies as a successful message.

2.2 Uniqueness of a Transmission and Attempt of a Transmission

During an attempt of a transmission different errors can appear. When a transmission failed the same message must be sent again. If a message-ID is part of the message, the ID has to be the same in a repeated transmission try. Only that way duplicates can be avoided reliably.

2.3 Fault Tolerance and Error Handling

Error Handling

2.3.1 Message ID

Messages which are at risk to be duplicated, must be identifiable with a message ID. Special attention should be for messages of orders, deliveries and returns. If a transmission attempt is responded with a receipt confirmation, no further message with the same ID is allowed to be sent. Otherwise the message receiver gets an duplication error. Plain requests without any kind of payload do not need a unique message ID. Also messages which refer to immutable objects does not require a unique message ID.

Note

A message ID is meaningfully build using the message type (or a code for each message type) and a numerical ID.
For an order
a message ID could be for example ORDER123456. A message ID of a delivery notification might look like this DISPATCH654543.

2.3.2 Acknowledgment of Receipt

For each object which is transmitted synchronously by a message, an acknowledgment of receipt has to be sent synchronously. An acknowledgment of receipt tells the sender that the message was received and confirmed that the message is available in a form which is expected by the receiving system. This does not mean that the message is semantically correct. This will be checked by some asynchronous processes. Problems at a asynchronous process will be handled separately.

When objects, which can be requested again anytime, are requested, no receipt confirmation is necessary. But if an object is not available after sending, the requesting system has to send a asynchronous acknowledgement.

Successfull Exchange of Messages

2.3.3 Renewed Message Transfer After Fault

The sender of a message has to continue his transmission until he gets a positive receive confirmation from the receiver. The following error types have to be considered in the transmission attempts:

  • Technical error: The receiving system cannot process the message because of internal reasons. The sender should send the unchanged message later again.
  • Validation error: The sender has received a wrong message regarding the content. It must correct the content mostly manually and send the message later again. Authentication errors also belongs in this section.
  • Duplication error: The receiver already received a message with the same message ID. The sender can stop further transmission tries for this message.
  • Further errors: All errors which are produced by the application environment such as timeouts, HTTP-error codes, etc. should be handled like technical errors.

2.3.3.1 Escalation for Repeated Failed Transmission Attempts

If despite several delivery attempts no positive acknowledgment from the receiver arrives, the sender has to identify the problem. A threshold value has to be defined for technical error, which determines whether an error case has to escalated. Escalation means that the error has to be checked manually. Technical errors should be checked by the receiver, meanwhile validation errors should be checked by the sender. For technical errors over the threshold value (or a multiple of the threshold value) the sender must also check the problem.

2.4 General Semantic and Plausibility Rules

The SOAP-based web services are tied to syntactic rules of the WSDL. Certain plausibility rules, which have to be semantically fulfilled, are applied for messages but not represented in the WSDL files themselves. Such plausibility rules can relate to consistency and completeness of the sent data and are specified in the description of the individual interface specification. Furthermore, message elements are limited in length. This is not syntactically given to avoid changes of the syntax due to database internal field changes. The limit of length has to be defined in the interface coordination.

2.5 Return Values

In case of a successful service call, the service sends a response message instead of a fault. In the response the client gets:

  • A string: This can be the ID of the object in the target system
  • Null: The return value null shows no error, but no object was created on the target system, so no ID can be given back
  • The requested object

2.6 Error Handling

The error handling follows the semantic check like described in section Concept - IOM SOAP Web Services#Fault Tolerance and Error Handling. Each error leads to the corresponding Java exception. This leads to according follow-up activities.

2.7 System Requirements

The system of the communication partner has to be able to understand a WSDL definition to validate incoming and outgoing messages and to decrypt the message channel. For Java systems, various binding frameworks to map WSDL definitions to Java classes exists. The developer can implement the application against the generated Java classes.

The decryption of the message channel takes place like described in chapter Concept - IOM SOAP Web Services#Security.

2.8 Versioning of IOM Web Services

Intershop continues to develop the web service interfaces for the IOM. An interface set to deprecated will be available at least for two minor releases. Different versions are located in different name spaces and URLs. IOM follows the recommendations of IONA (https://dl.dropboxusercontent.com/u/59555997/20070410-WSDL-Versioning-Best-Practise.pdf) for versioning.

2.9 Reserved Properties

Some use cases / business processes need additional information. TheXML Schema Definition provides additional fields to sending additional information via the existing interfaces if it is necessary for a business model. For this, many messages have the possibility to add properties at header, position level and in some cases at item level. These properties can also be grouped in a grouped code („PropertyGroup/@id“) and specified by key-value pairs („PropertyGroup/Property/@key“ und „PropertyGroup/Property/@value“).

Some combinations of property group and property key have a fixed meaning in the interface. These are called "Reserved Properties". These combinations are only allowed to use after previous agreement with the communication partner. These are in detail:

PropertyGroupKeyDescription
paymentmethodPayment method

paymentProviderOrderNo

Order number at PSP (Payment Service Provider)


RefNrReference number at PSP

merchantAccountMerchant account at PSP
recallreturnReasonReturn reason

returnReasonTextDescription of a return reason

returnReasonCommentComment for a return reason

shopReturnTypeName of a return type like it is used in the shop
referencesarticleRefArticle number as used by the IOM

shopArticleNoArticle number as used by the shop

supplierArticleNoArticle number as used by the supplier

positionNumberOrder position number
quantitiesquantityRemainingRemaining article count in a position
identificationretour_label_noReturn slip number

salesChannel

Sales channel 

Deprecated since 2.17


basketTokenToken of an article validation from the ValidateArticleService

orderTokenToken of an order with immaterial articles
couponcouponUnitUnit of a coupon

percentageValuePercentage value of a coupon
shippingClassshippingClassNameName of the shipping cost class

ShopSumGrossSum of the shipping costs of this class, gross

shopSumNetSum of the shipping costs of this class, net

shopSumTaxSales tax

taxTypeSales tax type
documentsinvoiceDownloadURLDownload URL of an invoice pdf document

creditnoteDownloadURLDownload URL of a credit note pdf document

BonusPoints

Deprecated since 2.17

partnerNameName of the bonus point partner like PAYBACK

cardNoBonus card number

bonusTypeType of bonus
  • basePoints
  • extraPoints

unitPointsPoints for a single product within the order position

unitIncentivePriceSales price related to the points

unitPriceSales price of a single product within the order position

quantityQuantity of points

marketingCodeCode of the marketing campaign
delivery_addressstreetNameStreet name without house number

houseNumberStreet number
billing_addressstreetNameStreet name without street number

houseNumberStreet number
reservationreservationIdID of a product stock reservation. See also the REST service "Stock Reservation"

pagination

Note

Only relevant at the
OrderStateService request

limitLimit (maximum) of result set - aka page size
offsetPage offset - usually a multiple of the limit (page size) - starts with 0

3 Security

3.1 Securing of the Communication Channel

To secure the compliance of data protection all data connections need to be SSL-encrypted. For this, business partners have to offer their web services in HTTPS. The key length of the symmetric encryption needs to be at least 128 bit. The communication partners need server- and client-side certificates. Self-validated certificates are sufficient and do not need to be signed by a public certificate authority. Before the first communication starts certificates need to be exchanged and if necessary validated.

Additionally, it is recommended to limit the communication by IP-address limitation and firewall systems.

3.2 Authentication

For every communication attempt, the sender has to authenticate itself towards the recipient. The sender transmits a combination of name, username and password, which is deposited for the sender at the receiver. A sender who cannot be authenticated by the recipient with this combination receives a validation error. The sender is responsible for correcting the message after a validation error. The sender also has to check whether the authentication data is correct.

3.3 Authorization

The authenticated sender is only authorized for the agreed actions. In case a sender sends an unauthorized message, it receives a validation error. The sender is responsible to check the message.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets