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.
|HTTP||Hypertext Transfer Protocol|
|HTTPS||Hypertext Transfer ProtocolSecure|
|IOM||The abbreviation for Intershop Order Management|
|SOAP||Simple Object Access Protocol|
|SSL||Secure Sockets Layer|
|WSDL||Web Service Description Language|
|PSP||Payment Service Provider|
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.
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.).
Only a message which can present the original message together with the response applies as a successful message.
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.
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.
ORDER123456. A message ID of a delivery notification might look like this
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.
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:
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.
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.
In case of a successful service call, the service sends a response message instead of a fault. In the response the client gets:
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.
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.
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.
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:
Order number at PSP (Payment Service Provider)
|RefNr||Reference number at PSP|
|merchantAccount||Merchant account at PSP|
|returnReasonText||Description of a return reason|
|returnReasonComment||Comment for a return reason|
|shopReturnType||Name of a return type like it is used in the shop|
|references||articleRef||Article number as used by the IOM|
|shopArticleNo||Article number as used by the shop|
|supplierArticleNo||Article number as used by the supplier|
|positionNumber||Order position number|
|quantities||quantityRemaining||Remaining article count in a position|
|identification||retour_label_no||Return slip number|
Deprecated since 2.17
|basketToken||Token of an article validation from the ValidateArticleService|
|orderToken||Token of an order with immaterial articles|
|coupon||couponUnit||Unit of a coupon|
|percentageValue||Percentage value of a coupon|
|shippingClass||shippingClassName||Name of the shipping cost class|
|ShopSumGross||Sum of the shipping costs of this class, gross|
|shopSumNet||Sum of the shipping costs of this class, net|
|taxType||Sales tax type|
|documents||invoiceDownloadURL||Download URL of an invoice pdf document|
|creditnoteDownloadURL||Download URL of a credit note pdf document|
Deprecated since 2.17
|partnerName||Name of the bonus point partner like PAYBACK|
|cardNo||Bonus card number|
|bonusType||Type of bonus|
|unitPoints||Points for a single product within the order position|
|unitIncentivePrice||Sales price related to the points|
|unitPrice||Sales price of a single product within the order position|
|quantity||Quantity of points|
|marketingCode||Code of the marketing campaign|
|delivery_address||streetName||Street name without house number|
|billing_address||streetName||Street name without street number|
|reservation||reservationId||ID of a product stock reservation. See also the REST service "Stock Reservation"|
Only relevant at the
|limit||Limit (maximum) of result set - aka page size|
|offset||Page offset - usually a multiple of the limit (page size) - starts with 0|
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.
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.
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.
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.