Document Properties
Kbid
2805L1
Last Modified
02-Mar-2022
Added to KB
02-Nov-2016
Public Access
Everyone
Status
Online
Doc Type
References
Product
  • IOM 3.0
  • IOM 3.1
  • IOM 3.2
  • IOM 3.3
  • IOM 3.4
  • IOM 3.5
  • IOM 3.6
  • IOM 3.7
  • IOM 4.0
  • IOM 4.1
  • IOM 4.2
  • IOM 4.3
  • IOM 4.4
  • IOM 4.5
  • IOM 4.6
  • IOM 4.7
  • IOM 5.0
Reference - IOM ImpEx Interfaces

Introduction

This document gives an overview of the so-called IMPEX interfaces of the Intershop Order Management.

Use an IMPORT interface to bring data into the IOM system (e.g., product data from a supplier) and vice versa use an EXPORT interface to create data files to be transmitted to a partner system like a 3rd-party warehouse management system.

Glossary

Term
Description
CreditorThe supplier, who has to send the products to the customer. A customer owes money to the supplier for the purchase(s) made.
DebtorA person (in B2C sense) or company (in B2B sense) who owes money (to shop or supplier) for the purchase made.

External Accounting System

Accounting service, which synchronizes debits and credits of the shop.

It is an intermediate item between the creditor (i.e., supplier) and the debtor (i.e., customer). The debtor pays to the creditor via an External Accounting System for the purchase(s).

IMPEXA portmanteau word. Short for Imp(ort) and Ex(port).
IOMThe abbreviation for Intershop Order Management
OMSThe abbreviation for Order Management System, the technical name of the IOM
RMA numberThe number for return material authorization, an identification number for an expected return

Creditor Management - Export Open Payments a.k.a. Unpaid Amounts of Dispatches

Note

Interface version 1.1 - based on PurchaseOrders-v1.1.xsd


The IOM provides an external standard interface in order to use a service of an external accounting system for the creditor management. This allows to export creditor relevant information about deliveries. A new dispatch triggers the export.

XML Reference

The file will be stored under <oms_base_path>/communication/messages/out/ with following syntax:

LevelParent ElementElementTypeminOccmaxOccSizeDescriptionAttributes
0-PurchaseOrdersxs:complexType11
Root elementno
1PurchaseOrdersMerchantIDalphanumeric1120Merchant IDno
1PurchaseOrdersTransIDalphanumeric1120Transaction numberno
1PurchaseOrdersPurchaseOrderxs:complexType1n
List of all open payments for different debtorsno
2PurchaseOrderRefNralphanumeric1120Reference for payment, e.g., invoice numberno
2PurchaseOrderPurchaseOrderNoalphanumeric1120Purchase order no from supplierno
2PurchaseOrderCurrencytext113DIN / ISO 4217 (EUR, USD, GBP, ...)no
2PurchaseOrderEventTokenalphanumeric112Event token, OC = Open Position Createno
2PurchaseOrderPayTypealphanumeric115CC = Creditcard
EDD = Direct debit
SO = Prepayment
PP = PayPal
GP = Giropay
SK = Check
BP = BillPay
COD = cash on delivery
CBA = Checkout by Amazon
RP = RatePay
no
2PurchaseOrderCreditorxs:complexType11
Creditor of purchase orderyes
2PurchaseOrderCustomerxs:complexType01
Customer of purchase orderyes
2PurchaseOrderCompanyCodealphanumeric0110Company code, e.g., 001 for Shop-A – differs per merchantno
2PurchaseOrderPayTermalphanumeric01255Terms of paymentno
2PurchaseOrderDeliveryNoteNoalphanumeric0170Delivery note numberno
2PurchaseOrderPurchasexs:complexType11
Purchase pricesno
3PurchaseNetxs:complexType1120Net amountyes

Note

Refer to oms."PlatformConfigDO" to find out more about <oms_base_path>. An example of <oms_base_path> is /home/baker under Linux operating system.

Attributes

Required attributes for XML-structure above are:

ElementAttributeTypeRequiredSizeDescription
Creditoridalphanumericyes20Unique ID of creditor, provided by supplier
Customeridalphanumericyes20Unique ID of customer
Netamountnumericyes20Net amount in minor units

Example

PurchaseOrders
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PurchaseOrders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <MerchantId>10461-10177-0a</MerchantId>
    <TransId>12345a</TransId>
    <PurchaseOrder>
        <RefNr>123456a</RefNr>
		<PurchaseOrderNo>1241451wre</PurchaseOrderNo>
        <Currency>EUR</Currency>
        <EventToken>OC</EventToken>
        <PayType>CC</PayType>
        <Creditor id="1234556a"/>
        <CompanyCode>001a</CompanyCode>
        <PayTerm></PayTerm>
        <Purchase>
            <Net amount="33900"/>
        </Purchase>
		<DeliveryNoteNo>123Abc</DeliveryNoteNo>
    </PurchaseOrder>
    <PurchaseOrder>
        <RefNr>123456a</RefNr>
        <Currency>EUR</Currency>
        <EventToken>OC</EventToken>
        <PayType>CC</PayType>
        <CompanyCode>001a</CompanyCode>
        <PayTerm></PayTerm>
        <Purchase>
            <Net amount="33900"/>
        </Purchase>
		<DeliveryNoteNo>234Bcd</DeliveryNoteNo>
    </PurchaseOrder>
</PurchaseOrders>

Example XML

XSDs

Configuration

General Configuration

see General Configuration

FinanceController2PaymentDefDO

For the required payment methods (e.g. cash on delivery, refer oms."PaymentDefDO"), the import and export names according to the finance controller have to be configured.

INSERT INTO "FinanceController2PaymentDefDO" (id, "financeControllerRef", "financeControllerPaymentExportName", "financeControllerPaymentImportName", "paymentDefRef")
VALUES(nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'RG', '00', 5),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'CC', '55', 3),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'GP', '51', 21),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'PP', '60', 10),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'COD', '80', 4),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'EDD', '65', 7),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'SO', '50', 9),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'ISH', '01', 24),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'COP', '02', 23),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'PRE', '03', 2);

Communication Partners

In case of a return, the external accounting system (sending partner) triggers the communication and pushes it to the supplier (receiving partner) using the sender bean FileSenderBean and XML as document type (refer the table oms.DocumentTypeDefDO). It is possible to use a custom implemented sender bean which is configured in the table oms.CommunicationDO.

For IOM < 4.1.0 - Transmission Type "SEND_OPEN_AMOUNT"

INSERT INTO "CommunicationPartnerDO"
("id", "decisionBeanDefRef", "splitTransmission", "communicationRef", "sendingPartnerReferrerRef", "receivingPartnerReferrerRef", "maxNoOfRetries", "retryDelay", "mergeTypeDefRef") 
values(
        nextval('"CommunicationPartnerDO_id_seq"'), -- id 
        null, -- decisionBeanDefRef
        FALSE, -- splitTransmission
        (select id from "CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_OPEN_AMOUNT'), -- communicationRef
        (select id from "PartnerReferrerDO" where "shopRef" = 10000), -- sendingPartnerReferrerRef
        (select id from "PartnerReferrerDO" where "financeControllerRef" = (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController')), -- receivingPartnerReferrerRef 
        5, -- maxNoOfRetries
        '1m', -- retryDelay
        null -- mergeTypeDefRef
    );

For IOM >= 4.1.0 - Transmission Type "SEND_PURCHASE_ORDER_DISPATCH"

INSERT INTO "CommunicationPartnerDO"
("id", "decisionBeanDefRef", "splitTransmission", "communicationRef", "sendingPartnerReferrerRef", "receivingPartnerReferrerRef", "maxNoOfRetries", "retryDelay", "mergeTypeDefRef") 
values(
        nextval('"CommunicationPartnerDO_id_seq"'), -- id 
        null, -- decisionBeanDefRef
        FALSE, -- splitTransmission
        (select id from "CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_PURCHASE_ORDER_DISPATCH'), -- communicationRef
        (select id from "PartnerReferrerDO" where "shopRef" = 10000), -- sendingPartnerReferrerRef
        (select id from "PartnerReferrerDO" where "financeControllerRef" = (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController')), -- receivingPartnerReferrerRef 
        5, -- maxNoOfRetries
        '1m', -- retryDelay
        null -- mergeTypeDefRef
    );

Creditor Management - Export Open Payments a.k.a. Unpaid Amounts of Returns

Note

Based on PurchaseOrder interface version 1.1


The IOM provides an external standard interface In order to use a service of an external accounting system for creditor management. This allows to export creditor relevant information for returns. New returns trigger the export process.

XML Reference

The same XSD/XML format is used for exporting open amounts for returns as well as for dispatches. The only difference is that the amount is prefixed with a minus, i.e., negative amount (e.g., -3200),as opposed to dispatches to indicate that it is for returns.

Upon export, the file will be stored in <impexBasePath>/communication/messages/out/ with following syntax:

LevelParent ElementElementTypeminOccmaxOccSizeDescriptionAttributes
0-PurchaseOrdersxs:complexType11
Root elementno
1PurchaseOrdersMerchantIDalphanumeric1120Merchant IDno
1TransIDPurchaseOrdersalphanumeric1120Transaction numberno
1PurchaseOrdersPurchaseOrderxs:complexType1n
List of all open payments a.k.a. unpaid amounts for different creditorsno
2PurchaseOrderRefNralphanumeric1120Reference for payment, e.g., invoice numberno
2PurchaseOrderPurchaseOrderNoalphanumeric1120Purchase order number of the supplierno
2PurchaseOrderCurrencytext113DIN / ISO 4217 (EUR, USD, GBP, ...)no
2PurchaseOrderEventTokenalphanumeric112Event token, OC = Create Open Paymentsno
2PurchaseOrderPayTypealphanumeric115CC = Creditcard
EDD = Direct debit
SO = Prepayment
PP = PayPal
GP = Giropay
SK = Check
BP = BillPay
COD = cash on delivery
CBA = Checkout by Amazon
RP = RatePay
no
2PurchaseOrderCreditorxs:complexType11
Creditor of purchase orderyes
2PurchaseOrderCustomerxs:complexType01
Customer of purchase orderyes
2PurchaseOrderCompanyCodealphanumeric0110Company code, e.g., 001 for Shop-A – differs per merchantno
2PurchaseOrderPayTermalphanumeric01255Terms of paymentno
2PurchaseOrderDeliveryNoteNoalphanumeric0170not usedno
2PurchaseOrderPurchasexs:complexType11
Purchase pricesno
3PurchaseNetxs:complexType1120

Net amount provided in negative contrary to dispatches, e.g., -120 EUR, for indicating the money transaction is the other way around.

yes

Note

Refer to oms."PlatformConfigDO" to find out more about <oms_base_path>. An example of <oms_base_path> is /home/baker under Linux operating system.

Attributes

Required attributes for XML-structure above are:

ElementAttributeTypeRequiredSizeDescription
Creditoridalphanumericyes20Unique ID of creditor, provided by supplier
Customeridalphanumericyes20Unique ID of customer
Netamountnumericyes20Net amount in minor units

Example

PurchaseOrders
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PurchaseOrders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <MerchantId>10461-10177-0a</MerchantId>
    <TransId>12345a</TransId>
    <PurchaseOrder>
        <RefNr>123456a</RefNr>
		<PurchaseOrderNo>1241451wre</PurchaseOrderNo>
        <Currency>EUR</Currency>
        <EventToken>OC</EventToken>
        <PayType>CC</PayType>
        <Creditor id="1234556a"/>
        <CompanyCode>001a</CompanyCode>
        <PayTerm></PayTerm>
        <Purchase>
            <Net amount="-33900"/>
        </Purchase>
    </PurchaseOrder>
    <PurchaseOrder>
        <RefNr>123456a</RefNr>
        <Currency>EUR</Currency>
        <EventToken>OC</EventToken>
        <PayType>CC</PayType>
        <CompanyCode>001a</CompanyCode>
        <PayTerm></PayTerm>
        <Purchase>
            <Net amount="-33900"/>
        </Purchase>
    </PurchaseOrder>
</PurchaseOrders>

Example File

XSDs

Configuration

General Configuration

see Guide - Generic Interfaces for External Accounting Systems.

FinanceController2PaymentDefDO

For the required payment methods (e.g. cash on delivery, refer oms."PaymentDefDO"), the import and export names according to the finance controller have to be configured.

INSERT INTO "FinanceController2PaymentDefDO" (id, "financeControllerRef", "financeControllerPaymentExportName", "financeControllerPaymentImportName", "paymentDefRef")
VALUES(nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'RG', '00', 5),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'CC', '55', 3),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'GP', '51', 21),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'PP', '60', 10),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'COD', '80', 4),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'EDD', '65', 7),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'SO', '50', 9),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'ISH', '01', 24),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'COP', '02', 23),
    (nextval('"FinanceController2PaymentDefDO_id_seq"'), (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController'), 'PRE', '03', 2);

Communication Partners

In case of a return,the external accounting system (sending partner) triggers the communication and pushes it to the supplier (receiving partner) by using the sender bean FileSenderBean and XML as document type (refer the table oms.DocumentTypeDefDO).

It is possible to use a custom implemented sender bean which is configured in the table oms.CommunicationDO.
For IOM < 4.1.0 - Transmission Type "SEND_OPEN_AMOUNT"
INSERT INTO "CommunicationPartnerDO"
("id", "decisionBeanDefRef", "splitTransmission", "communicationRef", "sendingPartnerReferrerRef", "receivingPartnerReferrerRef", "maxNoOfRetries", "retryDelay", "mergeTypeDefRef") 
values(
        nextval('"CommunicationPartnerDO_id_seq"'), -- id 
        null, -- decisionBeanDefRef
        FALSE, -- splitTransmission
        (select id from "CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_OPEN_AMOUNT'), -- communicationRef
        (select id from "PartnerReferrerDO" where "shopRef" = 10000), -- sendingPartnerReferrerRef
	    (select id from "PartnerReferrerDO" where "financeControllerRef" = (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController')), -- receivingPartnerReferrerRef 
        5, -- maxNoOfRetries
        '1m', -- retryDelay
        null -- mergeTypeDefRef
    );

For IOM >= 4.1.0 - Transmission Type "SEND_PURCHASE_ORDER_RETURN"

INSERT INTO "CommunicationPartnerDO"
("id", "decisionBeanDefRef", "splitTransmission", "communicationRef", "sendingPartnerReferrerRef", "receivingPartnerReferrerRef", "maxNoOfRetries", "retryDelay", "mergeTypeDefRef") 
values(
        nextval('"CommunicationPartnerDO_id_seq"'), -- id 
        null, -- decisionBeanDefRef
        FALSE, -- splitTransmission
        (select id from "CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_PURCHASE_ORDER_RETURN'), -- communicationRef
        (select id from "PartnerReferrerDO" where "shopRef" = 10000), -- sendingPartnerReferrerRef
	    (select id from "PartnerReferrerDO" where "financeControllerRef" = (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController')), -- receivingPartnerReferrerRef 
        5, -- maxNoOfRetries
        '1m', -- retryDelay
        null -- mergeTypeDefRef
    );

Debtor Management - Export Customer Information (Debtor Service)

This chapter describes the debtor export of the IOM. The export creates an XML file which is typically addressed to an external accounting system.

The syntax of the export file is SEND_DEBTOR_<ShopID>_<ShopName>_<Timestamp>_<DebitorTransmissionID>.xml.

  • <ShopID> is the ID of the OMS shop instance from the table oms."ShopDO"
  • <ShopName> is the property name of the OMS shop instance from the table oms."ShopDO"
  • <Timestamp> is in format YYYYMMDDHHMMSS
  • <DebitorTransmissionID> is the ID of the transmission object which triggered the export

Example:

SEND_DEBTOR_9012_PCompanyUK - Demo Shop_20151106092726.xml

Note

The export file is placed into the pre-configured directory BASEPATH/communication/messages/out

The BASEPATH is defined by the OMS property IS_OMS_DIR_VAR

Prerequisite

A debtor export only makes sense for OMS shop instances with configured “Invoicing Processes”. In other words, only through the “Invoicing Processes”, the debtors will be generated and updated.

XML Reference

The export file has the following syntax:

LevelParent ElementElementTypeminOccmaxOccSizeDescriptionAttributes
0-Debtorsxs:complexType11 Root elementno
1DebtorsMerchantIDxs:string1120Merchant ID of the retailer / shop at the export receiving systemno
1DebtorsTransIDxs:string1120Unique ID of the exportno
1DebtorsDebtorxs:complexType1n A debtor is an entity that owes a debt to another entityyes
2DebtorEventxs:string1110

Specifies the occasion of the export

  • CD = create debtor
  • UD = update debtor
  • DD = deactivate debtor
no
2DebtorCompanyxs:complexTypechoice Company
or  Person
 The debtor is a companyyes
2DebtorPersonxs:complexType The debtor is a private personyes
2DebtorAddressxs:complexType0n Billing address of the debtoryes
2DebtorEmailxs:string01128The email address of the debtorno
2DebtorTelephonexs:string0132The telephone number of the debtorno
2DebtorCurrencyxs:string013

Currency used by the debtor - DIN / ISO 4217 (EUR, USD, GBP, ...)

Note

always empty for debtor exports

<Currency></Currency>
no
2DebtorLanguagexs:language012

Language of the debtor ISO 639-1 (de, en, ...)

Note

always empty for debtor exports

<Language></Language>
no
2DebtorBankxs:complexType01 The bank account of the debtoryes
2DebtorProperty

xs:complexType

0n Additional properties of the debtoryes
3AddressCityxs:string1132City of the billing addressno
3AddressPostCodexs:string118ZIP code of the billing addressno
3AddressStatexs:string0164Federal state of the billing addressno
3AddressDistrictxs:string0164

District of the billing address

no
3AddressPOBoxxs:stringchoice POBox or
a sequenceof Street
and HouseNumber
 

Post office box of the billing address

no
3AddressStreetxs:string Street of the billing addressno
3AddressHouseNumberxs:string House number of the billing addressno
3AddressAdditionxs:string0464Address addition of the billing addressno
3AddressCountryxs:string012

Country of the billing address

Note

The OMS ignores the size restriction and the comment on this element for the debtor export. 
Normally, the XSD specifies the use of the ISO 3166-2 code at this place.

no

Attributes

The attributes for XML elements of the above XML structure are:

ElementAttributeTypeRequiredDescription
Debtoridxs:longyesID / primary key of the debtor
Debtortypexs:intyes

Type of the debtor:

  • 1 = B2B (company)
  • 2 = B2C (private person)
Companynamexs:stringyesName of the company
Companydepartmentxs:stringnoDepartment of the company
CompanylineOfBusinessxs:stringnoLine of business of the company
CompanycostNoxs:stringnoCost center of the company
CompanycommercialRegisterIdxs:stringnoCommercial register number of the company
CompanycommercialRegisterLocationxs:stringnoLocation of commercial register of the company
Companytypexs:stringnoBusiness form of t he company
CompanyvatNoxs:stringnoVAT No. of the company
Personsalutationxs:stringnoSalutation of the private person
Persontitlexs:stringno

Title of the private person

PersonfirstNamexs:stringnoFirst name of the private person
PersonmiddleNamexs:stringnoMiddle name of the private person
PersonlastNamexs:stringyesLast name of the private person
Addresstypexs:intyesAlways 2 = billing address, for debtor exports
Bankownerxs:stringnoName of the bank account owner
Bankibanxs:stringyesIBAN - International Bank Account Number
Bankbicxs:stringnoBIC - Bank Identifier Code
BankbankNamexs:stringnoName of the bank
Propertykeyxs:stringyesKey of an additional debtor property
Propertyvaluexs:stringyesValue of an additional debtor property

XSD's

Example

Debtors
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Debtors xmlns="http://types.theberlinbakery.com/v1_0" xmlns:ns2="http://types.theberlinbakery.com/v1_1">
    <MerchantID>MerchantId</MerchantID>
    <TransID>MJ002-20151106001-101217</TransID>
    <Debtor id="100654" type="2">
        <Event>CD</Event>
        <Person salutation="Mr." firstName="Matze" lastName="Katze"/>
        <Address type="2">
            <ns2:City>Berlin</ns2:City>
            <ns2:PostCode>10178</ns2:PostCode>
            <ns2:Street>Neue Promenade</ns2:Street>
            <ns2:HouseNumber>5</ns2:HouseNumber>
            <ns2:Addition>3. OG</ns2:Addition>
            <ns2:Addition>Terrasse</ns2:Addition>
            <ns2:Country>Germany</ns2:Country>
       </Address>
        <Currency></Currency>
        <Language></Language>
   </Debtor>
</Debtors>

Example File

Configuration

To enable the debtor export, the OMS needs a specific configuration at the database table oms."CommunicationPartnerDO".

PropertyDescriptionExample
idID / primary key100001

decisionBeanDefRef

<optional> not needed for debtor export - set to null
- reference to oms."DecisionBeanDefDO"
null

splitTransmission

not needed for debtor export - set to FALSEFALSE

communicationRef

id of oms."CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_DEBITOR'
- reference to oms."CommunicationDO"

2

receivingPartnerReferrerRef

specifies the receiver of the debtor export - typically the partner referrer of the finance controller / accounting system
- reference to oms."PartnerReferrerDO"

5001

sendingPartnerReferrerRef

specifies the sender of the export - typically the partner referrer of the retailer / shop
- reference to oms."PartnerReferrerDO"

10100

maxNoOfRetries

maximum number of retries in case of an erroneous transmission

  • 0 = no further retry
5

retryDelay

delay between the retries10m

mergeTypeDefRef

<optional> not needed for debtor export - set to null
- reference to oms."MergeTypeDefDO"

null
Configuration example:
INSERT INTO oms."CommunicationPartnerDO"(
            "id", 
			"decisionBeanDefRef", 
			"splitTransmission", 
			"communicationRef", 
            "receivingPartnerReferrerRef", 
			"sendingPartnerReferrerRef", 
			"maxNoOfRetries", 
            "retryDelay", 
			"mergeTypeDefRef")
    VALUES (
        nextval('oms."CommunicationPartnerDO_id_seq"'), 
		null, 
		FALSE, 
		(select "id" from oms."CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_DEBITOR'), 
        (select "id" from oms."PartnerReferrerDO" where "financeControllerRef" = (SELECT "id" FROM oms."FinanceControllerDO" WHERE "name" = 'Name of FinanceController')),
        (select "id" from oms."PartnerReferrerDO" where "shopRef" = shopId), -- enter the id of the OMS shop instance here
        5,
        '10m',
        null
    );

Debtor Management Import Open Positions

This chapter addresses consultants or support engineers for IOM with intermediate knowledge of SQL, XML/XSD, and Java.

In order to be able to use services of an external accounting system for debtor management, IOM provides an external standard interface to import relevant information about open amounts (also known as open payments or open positions). The import is triggered when a new file is placed in a pre-configured IOM file system directory.

XML Reference

The file should be placed in <configured_location> with following syntax:

Regarding file location, kindly refer the section 'FTP pull / scheduler / ExecutionBean configuration' and comment '-- FTP: remote ftp directory'.

ElementParent ElementTypeSizeMandatoryDescription
OpenPositions-   Root element
MerchantIdOpenPositionsalphanumeric20xMerchant ID (financeControllerShopName in Shop2FinanceControllerDO)
TransIdOpenPositionsalphanumeric20xTransaction number
OpenPositionOpenPostions 1unbounded 
RefNrOpenPositionalphanumeric20xReference for payment, e.g., invoicing number (InvoiceNo in InvoicingDO)
DebtorOpenPositionDebtorSimple x

refer ID from oms."DebitorDO"

AttributeTypeSizeDescription
idxs:long-Unique id of debtor
CreationDateOpenPositionnumeric6xCreation date in format YYYY-MM-DD (e.g., 2015-01-18)
VoucherNoOpenPositionalphanumeric30xVoucher Number
VoucherDateOpenPositionalphanumeric6xVoucher date in format YYYY-MM-DD (e.g., 2015-01-18)
EntryTextOpenPositionalphanumeric255-Entry text, booking text
EntryTextExtOpenPositionalphanumeric255-Entry text, booking text extension
CurrencyOpenPositiontext3xCurrency
PayTypeOpenPositionalphanumeric3x

Shortened name of the payment method (configurable)

PayTermOpenPositionalphanumeric255-Terms of payment
OPAmountOpenPositionnumeric20xAmount of open position
SumAmountOpenPositionnumeric20xSum of all payments
OpenAmountOpenPositionnumeric20xOpen Amount
DunningLevelOpenPositionalphanumeric20-Dunning indicator
LastDunningDateOpenPositionnumeric6-Date of last reminderin format YYYY-MM-DD (e.g., 2015-01-18)
ContraAccountOpenPositionalphanumeric20-In a double accounting system, at least two bookings must be made for each transaction. One booking on credit side of an account (e.g., first account), and the another booking on the debit side of an another account (e.g., second account). The account where debiting takes place is called as contra account.
EntryRangeOpenPositionalphanumeric10-Company code
Smallest organizational unit of external accounting for which a complete, self-contained set of accounts can be created. This includes the entry of all transactions that must be posted and the creation of all items for legal individual financial statements, such as the balance sheet and the profit and loss statement.
ModificationDateOpenPositionnumeric6-Date of last modification in format YYYY-MM-DD (e.g., 2015-01-18)

Attributes

Required attributes for XML-structure above are:

ElementAttributeTypeRequiredSizeDescription
Debtoridxs:longyes-NA-Unique ID of debtor

Example

OpenPositions
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OpenPositions xmlns="http://types.theberlinbakery.com/v1_0">
    <MerchantId>XYZ</MerchantId> <!-- refer financeControllerShopName from oms."Shop2FinanceControllerDO" -->
    <TransId>12345a</TransId>
	<OpenPosition>
		<RefNr>2014000001</RefNr> <!-- invoicingNo/ID from oms."InvoicingDO" -->
		<Debtor id="10000"/> <!-- id from oms."DebitorDO" -->
		<CreationDate>2015-01-18</CreationDate>
		<VoucherNo>12345dsf</VoucherNo>
		<VoucherDate>2015-01-18</VoucherDate>
		<EntryText>abc</EntryText>
		<!-- Avoid empty tags: <EntryTextExt></EntryTextExt> -->
		<Currency>EUR</Currency>
		<PayType>55</PayType> <!-- refer financeControllerPaymentImportName from oms."FinanceController2PaymentDefDO "-->
		<OPAmount>12345</OPAmount>
		<SumAmount>12346</SumAmount>
		<OpenAmount>1</OpenAmount>
		<EntryRange>01</EntryRange>
		<ModificationDate>2015-01-18</ModificationDate>
	</OpenPosition>
</OpenPositions>

XSDs

Configuration

General Configuration

Also see Guide - Generic Interfaces for External Accounting Systems.

FinanceController2PaymentDefDO (mandatory)

Defines how the payment methods are called for export and import. If the FinanceControllerDO uses "60" as name / id for PayPal payment in their OpenPositions.xml, it will be mapped to the PaymentDefDO with id = 10. This mapping is mandatory for all payment methods supported by the FinanceControllerDO, there is no fallback method.

 

FinanceController2PaymentDefDO payment method mapping
INSERT INTO oms."FinanceController2PaymentDefDO" (id, "financeControllerRef", "financeControllerPaymentExportName", "financeControllerPaymentImportName", "paymentDefRef") VALUES 
	(8, 10000, 'RG', '00', 5), 
    (1, 10000, 'CC', '55', 3), 
    (5, 10000, 'GP', '51', 21), 
    (4, 10000, 'PP', '60', 10), 
    (7, 10000, 'COD', '80', 4),
    (2, 10000, 'EDD', '65', 7), 
    (3, 10000, 'SO', '50', 9), 
    (9, 10000, 'ISH', '01', 24), 
    (10, 10000, 'COP', '02', 23), 
    (11, 10000, 'PRE', '03', 2);
-- also: instead of hardcoding financeControllerRef to 10000
-- (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController')

Shop2DunningLevelDO

The Shop2DunningLevelDO provides a mapping for (FinanceControllerDunningLevelName x Shop) → (DunningLevelDefDO). The configuration is optional, as long as the DunningLevel field is not used during import.

FinanceControllerDunningLevelName x Shop mapping
INSERT INTO oms."Shop2DunningLevelDO" (id, description, "dunningLevelDefRef", "financeControllerDunningLevel", "financeControllerRef", "shopRef")
    						   VALUES (10000, "No dunning level", 1, "INITIAL", 1, 10000);

Transformer / FTP Pull Configuration

Currently, the Open Positions import is only available as import via XML files. The files are read, transformed and persisted by a "Transformer" bean which has to be configured properly. The following basic configuration will pull and transform an OpenPositions.xml file from a specified FTP location every 10 minutes. Note that this has to be done after completing General Configuration.

PartnerReferrer and TransformerProcess(Group)
-- create transformer process group
INSERT INTO oms."TransformerProcessGroupDO" (id, name)
									VALUES  (nextval('"TransformerProcessGroupDO_id_seq"'), 'import_openpositions');
-- transformer to map and persist the op files into DOs
-- filenameRegex has to be defined, only these files are handled by the transformer
-- transformerBeanDefRef = 22 (SELECT id FROM oms."TransformerBeanDefDO" where name = 'ImportXmlOpenpositionsBean')
INSERT INTO oms."TransformerProcessDO" (id, index, "transformerBeanDefRef", "transformerProcessGroupRef", "filenameRegex", "moveObsoleteFiles")
							   VALUES  (nextval('"TransformerProcessDO_id_seq"'), 2, 22, currval('"TransformerProcessGroupDO_id_seq"'), 'OpenPositionsImport_[0-9]*\.xml', true);
-- the Transformer needs a special parameter where the shopId is configured (the internal id of the ShopDO, transformerProcessParameterKeyDefRef = 1)
INSERT INTO oms."TransformerProcessParameterDO" ( id, "parameterValue", "transformerProcessesParameterKeyDefRef", "transformerProcessesRef")
										VALUES  (nextval('"TransformerProcessParameterDO_id_seq"'), 10000, 1, currval('"TransformerProcessDO_id_seq"'));
 
-- filenameRegex for the transformer process 
INSERT INTO oms."TransformerProcessParameterDO" ( id, "parameterValue", "transformerProcessesParameterKeyDefRef", "transformerProcessesRef")
										VALUES (nextval('"TransformerProcessParameterDO_id_seq"'), 'OpenPositionsImport_[0-9]*\.xml', 4, 10000);
FTP Pull / Scheduler / ExecutionBean Configuration
--FTP config 
INSERT INTO oms."FileTransferConfigurationDO" (id, "basePath", "transmissionTypeDefRef", "typeDefRef", "creationDate", "modificationDate", "partnerReferrerRef", "description", "transformerProcessGroupRef")
									  VALUES  (nextval('"FileTransferConfigurationDO_id_seq"'), null, 1900, 10, current_timestamp, current_timestamp, (SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" =
											   currval('"FinanceControllerDO_id_seq"')), 'import_op', currval('"TransformerProcessGroupDO_id_seq"'));

-- pull every 10 min, Quartz cron format
INSERT INTO oms."ScheduleDO" (id, "creationDate", "modificationDate", active, "configId", cron, "expectedRuntime", "jobDefRef", "lastRun", "lockedSince", "key", "maxNoOfRetries", "retryDelay", "countRetry")
					 VALUES  (nextval('"ScheduleDO_id_seq"'), current_timestamp, current_timestamp, TRUE, currval('"FileTransferConfigurationDO_id_seq"'), '0 0/10 * 1/1 * ? *', 60000, 3, NULL, NULL,
							  'import_openpositions', 10, '5m', 0);

-- CommunicationPartnerDO
INSERT INTO oms."CommunicationPartnerDO" (id, "splitTransmission", "communicationRef", "receivingPartnerReferrerRef", "sendingPartnerReferrerRef", "maxNoOfRetries", "retryDelay")
								 VALUES  (nextval('"CommunicationPartnerDO_id_seq"'), FALSE, (SELECT id FROM "CommunicationDO" WHERE "key" = 'ANY###FTP_JOB###EXT_TRANSFER_FILE'),
										  (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000), (SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"')),
										  12, '30m');

-- FTP: Credentials
INSERT INTO oms."ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
							   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullFtpAccount'),
										'ftp-omtdata:ftp-omtdata@localhost', (SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" =
										'ANY###FTP_JOB###EXT_TRANSFER_FILE') and "receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" =
										(SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));	

-- FTP: optional private key config
/*
INSERT INTO "ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
						   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullPrivateKeyFile'),
									'/home/baker/keys/yourKeyFile.ppk', (SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" =
									'ANY###FTP_JOB###EXT_TRANSFER_FILE') and "receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" =
									(SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));
*/

-- FTP remote ftp directory 
-- FTP file should be placed under <impexBathPath>/accounting/customerxy/import_openpositions/
INSERT INTO oms."ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
							   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullDirectory'), 				
										'/accounting/customerxy/import_openpositions', (SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" =
										'ANY###FTP_JOB###EXT_TRANSFER_FILE') and "receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" =
										(SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));

-- FTP: regex filename (needs to be consistent with the TransformerProcessDO if there is no additional renaming process defined!)
-- Example file name: OpenPositionsImport_1234.xml
 INSERT INTO oms."ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
							   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullFilenameRegex'), 'OpenPositionsImport_[0-9]*\.xml',
										(SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" = 'ANY###FTP_JOB###EXT_TRANSFER_FILE') and
										"receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO"
										WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));
						

Debtor Management Import Payment Histories

This chapter addresses consultants or support engineers for IOM with intermediate knowledge of SQL, XML/XSD, and Java.

In order to be able to use services of an external accounting system for debtor management, IOM provides an external standard interface to import relevant information about open amount histories (also known as open payment histories or open position histories). The import is triggered when a new file is placed in a pre-configured IOM file system directory.

XML Reference

The file should be placed in <impexBasePath>/import with following syntax:

Note

<impexBasePath> is configurable

Please contact your support or refer the column "omtBasePath" from the table oms."PlatformConfigDO".

ElementParent ElementTypeSizeMandatoryDescription
PaymentHistories-   Root element
MerchantIdPaymentHistoriesalphanumeric20xMerchant ID (financeControllerShopName in Shop2FinanceControllerDO)
TransIdPaymentHistoriesalphanumeric20xTransaction number
PaymentHistoryPaymentHistories 1unbounded 
RefNrPaymentHistoryalphanumeric20xReference for payment, e.g., invoicing number (InvoiceNo in InvoicingDO)
DebtorPaymentHistoryDebtorSimple x
AttributeTypeSizeDescription
idxs:long-Unique id of debtor
EntryDatePaymentHistorynumeric6xEntry datein format DDMMYYYY
VoucherNoPaymentHistoryalphanumeric30xVoucher Number
VoucherDatePaymentHistoryalphanumeric6xVoucher date in format DDMMYYYY
ContraAccountPaymentHistoryalphanumeric20-

In a double accounting system, at least two bookings must be made for each transaction. One booking on credit side of an account (e.g., first account), and the another booking on the debit side of an another account (e.g., second account). The account where debiting takes place is called as contra account.

PositionTypePaymentHistoryalphanumeric255x

Two types of position: Z being payment amount, R being invoicing amount based on the column HI record.

Four outcomes:

  1. Positive amount and 'R' position type => invoicing amount
  2. Negative amount and 'R' position type => credit note / return
  3. Positive amount and 'Z' position type => amount for payment
  4. Negative amount and 'Z' position type => redemption / refund

The other possible combinations RU and ZU are rare and occur during re-booking between different open payments/open positions. These re-bookings are initiated manually by an accountant.

PositionDetailsPaymentHistoryalphanumeric255-Details of position, free text for field PostionType
PositionDetailsExtPaymentHistoryalphanumeric255-Details of position extension
AmountPaymentHistorynumeric20xAmount in minor units
EntryRangePaymentHistoryalphanumeric10-Company code
Smallest organizational unit of external accounting for which a complete, self-contained set of accounts can be created. This includes the entry of all transactions that must be posted and the creation of all items for legal individual financial statements, such as the balance sheet and the profit and loss statement.

Attributes

Required attributes for XML-structure above are:

ElementAttributeTypeRequiredSizeDescription
Debtoridxs:longyes-NA-Unique ID of debtor

Example

The XML file placed in the pre-configured directory might look as follows:

Example-XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<PaymentHistories xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <MerchantId>10461-10177-0a</MerchantId>
    <TransId>12345a</TransId>
	<PaymentHistory>
		<RefNr>123456a</RefNr>
		<Debtor id="1234556a"/>
		<EntryDate>23022015</EntryDate>
		<VoucherNo>12345dsf</VoucherNo>
		<VoucherDate>23022015</VoucherDate>
		<ContraAccount></ContraAccount>
		<PositionType></PositionType>
		<PositionDetails></PositionDetails>
		<PositionDetailsExt></PositionDetailsExt>
		<Amount>12345</Amount>
		<EntryRange>01</EntryRange>
	</PaymentHistory>
</PaymentHistories>

XSDs

Configuration

General Configuration

Also see Guide - Generic Interfaces for External Accounting Systems.

Transformer / FTP Pull Configuration

Currently, the Open Positions Histories import is only available as import via XML files. The files are read, transformed and persisted by a "Transformer" bean which has to be configured properly. The following basic configuration will pull and transform an OpenPositionHistories.xml file from a specified ftp location every 10 minutes. Note that this has to be done after completing General Configuration.

PartnerReferrer and TransformerProcess(Group)
-- create transformer process group
INSERT INTO oms."TransformerProcessGroupDO" (id, name)
									VALUES  (nextval('"TransformerProcessGroupDO_id_seq"'), 'import_paymenthistory');

-- transformer to map and persist the op files into DOs
-- filenameRegex has to be defined, only these files are handled by the transformer
-- transformerBeanDefRef = 23 (SELECT id FROM oms."TransformerBeanDefDO" where name = 'ImportXmlPaymenthistoriesBean')
INSERT INTO oms."TransformerProcessDO" (id, index, "transformerBeanDefRef", "transformerProcessGroupRef", "filenameRegex", "moveObsoleteFiles")
							   VALUES  (nextval('"TransformerProcessDO_id_seq"'), 2, 23, currval('"TransformerProcessGroupDO_id_seq"'), 'PaymentHistories_[0-9]*\.xml', true);

-- the Transformer needs a special parameter where the shopId is configured (the internal id of the ShopDO, transformerProcessParameterKeyDefRef = 1)
INSERT INTO oms."TransformerProcessParameterDO" ( id, "parameterValue", "transformerProcessesParameterKeyDefRef", "transformerProcessesRef")
										VALUES  (nextval('"TransformerProcessParameterDO_id_seq"'), 10000, 1, currval('"TransformerProcessDO_id_seq"'));
 
INSERT INTO oms."TransformerProcessParameterDO" ( id, "parameterValue", "transformerProcessesParameterKeyDefRef", "transformerProcessesRef") 
										VALUES (nextval('"TransformerProcessParameterDO_id_seq"'), 'PaymentHistories_[0-9]*\.xml', 4, 10000);
FTP Pull / Scheduler / ExecutionBean Configuration
--FTP config 
INSERT INTO oms."FileTransferConfigurationDO" (id, "basePath", "transmissionTypeDefRef", "typeDefRef", "creationDate", "modificationDate", "partnerReferrerRef", "description", "transformerProcessGroupRef")
									  VALUES  (nextval('"FileTransferConfigurationDO_id_seq"'), null, 1900, 10, current_timestamp, current_timestamp, (SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" =
											   currval('"FinanceControllerDO_id_seq"')), 'import_paymenthistories', currval('"TransformerProcessGroupDO_id_seq"'));

-- pull every 10 min, Quartz cron format
INSERT INTO oms."ScheduleDO" (id, "creationDate", "modificationDate", active, "configId", cron, "expectedRuntime", "jobDefRef", "lastRun", "lockedSince", "key", "maxNoOfRetries", "retryDelay", "countRetry")
					 VALUES  (nextval('"ScheduleDO_id_seq"'), current_timestamp, current_timestamp, TRUE, currval('"FileTransferConfigurationDO_id_seq"'), '0 0/10 * 1/1 * ? *', 60000, 3, NULL, NULL,
							  'import_paymenthistory', 10, '5m', 0);

-- CommunicationPartnerDO
INSERT INTO oms."CommunicationPartnerDO" (id, "splitTransmission", "communicationRef", "receivingPartnerReferrerRef", "sendingPartnerReferrerRef", "maxNoOfRetries", "retryDelay")
								 VALUES  (nextval('"CommunicationPartnerDO_id_seq"'), FALSE, (SELECT id FROM "CommunicationDO" WHERE "key" = 'ANY###FTP_JOB###EXT_TRANSFER_FILE'),
										  (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000), (SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"')),
										  12, '30m');

-- FTP: Credentials
INSERT INTO oms."ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
							   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullFtpAccount'),
										'ftp-omtdata:ftp-omtdata@localhost', (SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" =
										'ANY###FTP_JOB###EXT_TRANSFER_FILE') and "receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" =
										(SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));	

-- FTP: optional private key config
/*
INSERT INTO "ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
						   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullPrivateKeyFile'),
									'/home/baker/keys/yourKeyFile.ppk', (SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" =
									'ANY###FTP_JOB###EXT_TRANSFER_FILE') and "receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" =
									(SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));
*/

-- FTP: remote ftp directory
INSERT INTO oms."ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
							   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullDirectory'), 				
										'/accounting/customerxy/import_openpositions', (SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" =
										'ANY###FTP_JOB###EXT_TRANSFER_FILE') and "receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" =
										(SELECT id FROM "PartnerReferrerDO" WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));

-- FTP: regex filename (needs to be consistent with the TransformerProcessDO if there is no additional renaming process defined!)
INSERT INTO oms."ExecutionBeanValueDO" (id, "executionBeanKeyDefRef", "parameterValue", "communicationPartnerRef")
							   VALUES  (nextval('"ExecutionBeanValueDO_id_seq"'), (SELECT id FROM "ExecutionBeanKeyDefDO" WHERE "executionBeanDefRef" = 202 and "parameterKey" = 'pullFilenameRegex'), 'PaymentHistories_[0-9]*\.xml',
										(SELECT id FROM "CommunicationPartnerDO" WHERE "communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "key" = 'ANY###FTP_JOB###EXT_TRANSFER_FILE') and
										"receivingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 10000) and "sendingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO"
										WHERE "financeControllerRef" = currval('"FinanceControllerDO_id_seq"'))));
						

Export Customer - Version 1.1

Note

Interface version 1.1 - based on CustomerService-v1.1.xsd

This chapter describes the file format and the configuration of the IOM customer export.

If the customer data is changed via the OMT or by the IOM CustomerService, the IOM exports the customer data as XML file.

Note

The export is placed into the pre-configured directory BASEPATH/importarticle/export. The BASEPATH is defined by the OMS property IS_OMS_DIR_VAR.

XML Reference

The attributes of the individual XML elements are linked and can be found below this table. Click on the link to get to the respective attributes.

ElementParent ElementTypeminOccmaxOccSizeDescription
Customersroot
11
root element
CustomerCustomersxs:complexType1n
list of customers
ShopCustomerxs:complexType01
element for shop / retailer specific information
PersonCustomerCustomerPersonExtended01
personal data of customer
ContactCustomerCustomerContactDetails01
contact details of customer
AddressCustomerCustomerAddress0unbounded
address of customer
BankAccountCustomerCustomerBankAccount0unbounded
bank account of customer
ScoringCustomerCustomerScoring0unbounded10scoring of customer
PropertiesCustomerCustomerPropertyGroup0unbounded
group of generic properties of customer
PersonAddressCustomerPerson01
personal data of customer belonging to address
ContactAddressCustomerContactDetails01
contact details of customer belonging to address
LocationAddressCustomerAddressLocation01
location information belonging to address
IsValidatedAddressxs:boolean01
shows, whether and when the address was validated
StreetLocationxs:string01100street
HouseNoLocationxs:string0120street number
POBoxLocationxs:string0125post office box
PackstationLocationxs:complexType01
pack station
AddressAdditionLocationxs:string04
additional address information
DistrictLocationxs:string01100district
CityLocationxs:string01100city
PostCodeLocationxs:string01100post code
CountryLocationxs:string01100country - ISO 3166 ALPHA-3 code
BankNameBankAccountxs:string0130name of bank
AccountHolderBankAccountxs:string0130name of account holder
AccountNumberBankAccountxs:string0134bank account number
BankCodeBankAccountBankCodeExtended0120bank code
PropertyPropertiesCustomerProperty1unbounded
generic property of customer

Attributes

Attributes of Customer

AttributeTypeRequiredSizeDescription
isActivexs:boolean-
shows whether the customer is active or not
customerTypexs:stringx50

type of customer

possible values are:

  • b2b
  • b2c
isNewCustomerxs:boolean-
shows whether the customer is new or not
dunningLevelxs:string-50the dunning level of customer
hasNewsletterxs:boolean-
shows, whether the customer has subscribed a newsletter or not
hasDeliveryStopxs:boolean-
shows, whether delivery stop exists for customer or not
idxs:long-
internal ID of the customer at the OMS
versionxs:int-
version number of customer data

Attributes of Shop

AttributeTypeRequiredSizeDescription
shopCustomerNoxs:stringx20customer ID as used by the shop / retailer

Attributes of Person

AttributeTypeRequiredSizeDescription
companyNamexs:string-100company name, if the customer is a business user (B2B)
firstNamexs:string-50first name
lastNamexs:string-50last name
titlexs:string-10title
isFemalexs:boolean-
gender

dateOfBirth

Note

only if type is CustomerPersonExtended

xs:date-
date of birth

Attributes of Contact

AttributeTypeRequiredSizeDescription
phone1xs:string-25phone number 1
phone2xs:string-25phone number 2
mobilePhonexs:string-25mobile phone number
eMailxs:string-100email address
faxxs:string-25fax number

Attributes of Address

AttributeTypeRequiredSizeDescription
isDefaultxs:boolean-
customer default address or not
addressTypexs:stringx50

type of address (shipping address, invoice address, etc.)

possible values are:

  • SHIPPING
  • BILLING
  • IMMATERIAL
idxs:long-
ID of address at the OMS
shopAddressNoxs:string-50ID of address within the shop / retailer system
versionxs:int-
version number of address data
nightShippingxs:boolean-
indicates, if night shipping and delivery for this customer address is enable

Attributes of IsValidated

AttributeTypeRequiredSizeDescription
lastValidationxs:dateTime-
date of last address validation

Attributes of Packstation

AttributeTypeRequiredSizeDescription
userIdxs:stringx100customer number at the pack station
stationIdxs:stringx100number of pack station

Attributes of BankAccount

AttributeTypeRequiredSizeDescription
isDefaultxs:boolean-
default bank account or not
hasDirectDebitxs:boolean-
direct debit mandate exists
idxs:long-
ID of bank account at the OMS
shopBankAccountNoxs:string-50ID of bank account within the shop / retailer system
versionxs:int-
version number of bank account data

Attributes of BankCode

AttributeTypeRequiredSizeDescription
bankCodeTypexs:stringx50

type of bank code - sepa/standard

possible values are:

  • STANDARD
  • SEPA

 

Attributes of Scoring

AttributeTypeRequiredSizeDescription
sourcexs:stringx50origin of scoring
scoringDatexs:datex
date of auditing the scoring
idxs:long-
ID of scoring at the OMS
versionxs:int-
version number of scoring data

Attributes of Properties

AttributeTypeRequiredSizeDescription
typexs:stringx100

data type of value-field of belonging properties

possible values are:

  • STRING
  • BOOLEAN
  • TIMESTAMP

Attributes of Property

AttributeTypeRequiredSizeDescription
keyxs:stringx100property key
valuexs:stringx100property value
idxs:long-

ID of the property at the OMS

versionxs:int-
Version number of property data

Example

Customer data export example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Customers xmlns="http://types.theberlinbakery.com/customer/v1_1">
    <Customer isActive="true" customerType="b2c" isNewCustomer="false" dunningLevel="No dunning level" hasNewsletter="false" hasDeliveryStop="false" id="10071" version="0">
        <Shop shopCustomerNo="fce2b60b-7461-4efa-8c4f-3d7e35a7f3d3"/>
        <Person firstName="Herbert" lastName="Spock" isFemale="false"/>
        <Contact/>
        <Address isDefault="true" addressType="SHIPPING" id="10201" version="0" nightShipping="true">
            <Person firstName="Mario" lastName="Meier" isFemale="false"/>
            <Contact/>
            <Location>
                <Street>Heugraben</Street>
                <HouseNo>11</HouseNo>
                <City>Jena</City>
                <PostCode>07743</PostCode>
                <Country>DEU</Country>
            </Location>
            <IsValidated>false</IsValidated>
        </Address>
        <Address isDefault="true" addressType="BILLING" id="10200" version="0" nightShipping="false">
            <Person firstName="H." lastName="Spock" isFemale="false"/>
            <Contact/>
            <Location>
                <Street>Leutragraben</Street>
                <HouseNo>1</HouseNo>
                <City>Jena</City>
                <PostCode>07743</PostCode>
                <Country>DEU</Country>
            </Location>
            <IsValidated>false</IsValidated>
        </Address>
        <Properties type="BOOLEAN">
            <Property key="VIP" value="TRUE" id="10097" version="0"/>
        </Properties>
        <Properties type="STRING">
            <Property key="creator" value="WSTest" id="10098" version="0"/>
        </Properties>
    </Customer>
</Customers>

Example File

XSDs 

Configuration

The configuration for the schedule of the customer export has to be done in database table customer."CustomerExportConfigDO". An export configuration relates to one OMS shop instance, but you can define several export for one OMS shop instance.

It is possible to define an interval for a incremental export in minutes and/or an interval for a full export in days.

PropertyDescriptionExample
idID / primary key500
exportNameName of the export, used in filename <required>IOM-CUSTOMER
exportStartDate

Date when the export starts the first time

Note

NULL at this column is equivalent with a disabled export configuration

2016-11-13 12:00:00
exportVersion

Counter of export (position before decimal point is counter for Full- and position after decimal point counter for the Delta-Exports)

The exportVersion is used in filename

Note

set exportVersion to null on configuration, the IOM creates the version 1.00000 with the first Full-Export

5.00002
intervalFullInDaysInterval for full customer export in days <required and must be greater then  0>  1 (once a day at 12:00:00 depends on exportStartDate)
intervalIncrementInMinutesInterval for incremental customer export in minutes <required and must be greater then  0>60 (every 60 minutes)
lastExportTimestamp of last export - is written by the export process2016-11-19 10:12:00.029
shopRefReference to the OMS shop instance - references oms."ShopDO" <required> 100
versionDB internal version of configuration1
startTimeControlAppTimestamp when the job has started the export - just for internal process controllingnull
startTimeMDBTimestamp when MDBean was catching the JMS message - just for internal process controllingnull
exportNewCustomerOnIncrementIf true the new customers will be exported in incremental exports otherwise not <default = TRUE>TRUE

Example

INSERT INTO customer."CustomerExportConfigDO"(
            "id", "exportName", "exportStartDate", "exportVersion", "intervalFullInDays", 
            "intervalIncrementInMinutes", "lastExport", "shopRef", "version", 
            "startTimeControlApp", "startTimeMDB", "exportNewCustomerOnIncrement")
    VALUES (500, 'IOM-CUSTOMER', now(), null, 1, 
            60, null, 100, 1, 
            null, null, TRUE);

Export File Name  

File name pattern: <exportName>_<shopRef>_<exportVersion>_<exportStartTime>_<exportType>.xml

The export configuration (customer."CustomerExportConfigDO") has direct impact to the name of export file.

Example: IOM-CUSTOMER_100_2.00007_20161110153700_INCREMENT.xml

IOM-CUSTOMER = exportName from export configuration
100 = shopRef from export configuration 
2.00007 = export version - Delta-Export number 7 after the second Full-Export

20161110153700
= export process start time in format yyyyMMddHHmmss
INCREMENT = type of export - in case of an Full-Export is <exportType> = FULL

Export Open Positions

This chapter describes the open position export format of IOM 1.1.0.0 defined in the XML schema description <jboss>/bakery.schemas/communication-v1.0/src/main/resources/META-INF/wsdl/SalesOrders-v1.0.xsd.

XML Reference

Note

In the following tables, the contents of the fields Class:Attribute represent object path expressions.

The element is the root of open position XML data. SalesOrder definitions and lists must be enclosed in this element.

LevelParent ElementElementTypeminOccmaxOccSizeDescriptionAttributes
0-SalesOrders    Root Elementno
1SalesOrdersMerchantIDalphanumeric1120Merchant IDno
1SalesOrdersTransIDalphanumeric1120Transaction IDno
1SalesOrdersSalesOrder 1n List of all open positions for different debtorsno
2SalesOrderRefNralphanumeric1120Reference for payment, e.g. shop order numberno
2SalesOrderCurrencytext113DIN / ISO 4217 (EUR, USD, GBP, ...)no
2SalesOrderEventTokenalphanumeric112Event token, OC = Open Position Createno
2SalesOrderPayTypealphanumeric115Configured as financeControllerPaymentExportName in FinanceController2PaymentDefDO with an internal reference to PaymentDefDOno
2SalesOrderDebtorcomplexType with attributes11 Debtor of the orderyes
2SalesOrderCustomercomplexType with attributes01 Customer of the orderyes
2SalesOrderCompanyCodealphanumeric0110Company code, e.g., 001 for Shop-A – differs per merchantno
2SalesOrderPayTermalphanumeric01255Terms of paymentno
2SalesOrderInvoiceDatenumeric116OP_Valutadate in format DDMMYYno
2SalesOrderSalecomplexType11 Sales pricesno
3SaleTaxescomplexType11 Taxes of the orderno
4TaxesTaxcomplexType with attributes11 Single taxyes
2SalesOrderGrosscomplexType with attributes1120Gross price of the orderyes
2SalesOrderNetcomplexType with attributes1120Net price of the orderyes

Attributes

ElementAttributeTypeRequiredSizeDescription
Debtoridnumericyes20Unique ID of debtor
Debtortypeintyes11=B2B, 2=B2C
Customeridaplhanumericyes20Unique ID of customer
Grossamountnumericyes20Gross amount in minor units
Netamountnumericyes20Net amount in minor units
Taxcodealphanumericyes10Tax Code (e.g., 001 for 19%)
Configured as financeControllerTaxTypeExportName in FinanceController2TaxTypeDefDO with an internal reference to TaxTypeDefDO
TaxnetAmountnumericyes20Net amount for this tax code in minor units
TaxtaxAmountnumericyes20Tax amount for this tax code in minor units

Examples

SalesOrders example
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SalesOrders xmlns="http://types.theberlinbakery.com/v1_0" xmlns:ns2="http://types.theberlinbakery.com/v1_1" xmlns:ns3="http://types.theberlinbakery.com/customer/v1_0">
    <MerchantID>MerchantId</MerchantID>
    <TransID>2014007838</TransID>
    <SalesOrder>
        <RefNr>0083</RefNr>
        <Currency>GBP</Currency>
        <EventToken>OC</EventToken>
        <PayType>PP</PayType>
        <Debtor id="100646" type="2"/>
        <Customer id="MJ4"/>
        <CompanyCode>123abc</CompanyCode>
        <InvoiceDate>2015-10-27</InvoiceDate>
        <Sale>
            <Gross amount="87925">0</Gross>
            <Net amount="75387">0</Net>
            <Taxes>
                <Tax code="101" netAmount="62687" taxAmount="12538"/>
                <Tax code="000" netAmount="12700" taxAmount="0"/>
                <Tax code="002" netAmount="0" taxAmount="0"/>
            </Taxes>
        </Sale>
    </SalesOrder>
</SalesOrders>

Example File

XSDs

Configuration

General Configuration

see Guide - Generic Interfaces for External Accounting Systems

INSERT INTO "CommunicationPartnerDO"("id", "decisionBeanDefRef", "splitTransmission", "communicationRef", "sendingPartnerReferrerRef", "receivingPartnerReferrerRef", "maxNoOfRetries", "retryDelay", "mergeTypeDefRef") values
    (
        nextval('"CommunicationPartnerDO_id_seq"'),
        null,
        FALSE,
        (select id from "CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_OPEN_AMOUNT'),
        (select id from "PartnerReferrerDO" where "shopRef" = 100), -- enter the required shop ID (e.g. 10000) here
        (select id from "PartnerReferrerDO" where "financeControllerRef" = (SELECT "id" FROM "FinanceControllerDO" WHERE "name" = 'Name of FinanceController')),
        5,
        '10m',
        null
    );

FinanceController2PaymentDefDO

Illustrates how the payment methods are called for export and import.

FinanceController2PaymentDefDO
INSERT INTO "FinanceController2PaymentDefDO" (id, "financeControllerRef", "financeControllerPaymentExportName", "financeControllerPaymentImportName", "paymentDefRef") 
VALUES(8, 1, 'RG', '00', 5), 
	(1, 1, 'CC', '55', 3), 
	(5, 1, 'GP', '51', 21), 
	(4, 1, 'PP', '60', 10), 
	(7, 1, 'COD', '80', 4),
	(2, 1, 'EDD', '65', 7), 
	(3, 1, 'SO', '50', 9), 
	(9, 1, 'ISH', '01', 24), 
	(10, 1, 'COP', '02', 23), 
	(11, 1, 'PRE', '03', 2);

FinanceController2TaxTypeDefDO

Illustrates how the tax types are called for export and import.

FinanceController2TaxTypeDefDO
INSERT INTO "FinanceController2TaxTypeDefDO" (id, "financeControllerRef", "financeControllerTaxTypeExportName", "financeControllerTaxTypeImportName", "taxTypeDefRef") 
VALUES(1, 1, '101', '001', 5),
 	(2, 1, '002', '002', 3),
 	(3, 1, '000', '000', 1);

Export Order for Order Placement

This section describes the order export format of IOM 1.1.0.0 defined in the XML schema description <jboss>/bakery.schemas/communication-v1.0/src/main/resources/META-INF/wsdl/OrderService-v1.0.xsd.

After processing the order in IOM, it is exported as an XML-file with the structure described here.

The file is located in: $OMS_VAR/communication/messages/out/

The file name has the following syntax: sendOrder_shopId_supplierId_timestamp_uniqueId.xml

E.g., sendOrder_1000_2000_20160608150955_10084.xml

XML Reference

XML elements listed in the table with specific attributes are rendered as links. Click the link to navigate to the attributes' description.

ElementParent Element(s)TypeminOccmaxOccDescription
Orderroot 11Root element
CustomerOrderxs:complexType1n

The Customer

ContactCustomer; DeliveryAddress; Addressxs:complexType01Customer contact data
PersonCustomer; Receiverxs:complexType11A customer can be a private person or a company
CompanyCustomer; Receiverxs:complexType11A customer can be a private person or a company
ContactPersonCustomer; Receiverxs:complexType01Contact person for a company
ShopOrderxs:complexType11The Shop
ImmaterialOrderxs:complexType11The package is non-physical/ digital. No delivery address required.
CarrierOrderxs:string01Carrier, if the package is physical/ non-digital
EmailImmaterialxs:string11receiver mail address
TelephoneImmaterialxs:string01receiver telephone number
OtherImmaterialxs:string01other receiver information
DeliveryAddressOrderxs:complexType11Delivery address, if the package is physical/ non-digital
ReceiverDeliveryAddress; Addressxs:complexType11Receiver, can be a private person or a company
LocationDeliveryAddress; Addressxs:complexType11Location of the address
CityLocationxs:string11City
PostCodeLocationxs:string11Postal code
DistrictLocationxs:string01District
StreetLocationxs:string11Address can be a street, post box, or a pack station
POBoxLocationxs:string11Address can be a street, post box, or a pack station
PackstationLocationxs:string11Address can be a street, post box, or a pack station
AdditionLocationxs:string02Addition to address
CountryLocationxs:string11Country
AddressOrderxs:complexType01Generic addresses: Optional; in consultation further addresses can be specified
SalesOrder; Positionxs:complexType11Submit sales prices. In case of cash on delivery set ./Total/Gross/@amount which is the price the carrier should receive
SumSalesxs:complexType01Sum of prices of order positions
NetSum; Charge; Total; Unitxs:string01Net price
GrossSum; Charge; Total; Unitxs:string01Gross price
TaxSum; Charge; Total; Unitxs:string0nSum of VAT (value added tax) by type of VAT
ChargeSalesxs:complexType0nFees including delivery
TotalSalesxs:complexType01Total order amount
NoSalesOrderxs:string11Set if no payment information should be sent
OptimizationOrderxs:string01Preferred optimization. If the order can be handled in different ways a preference between best-price or processing-time can be set
SplitShipmentAllowedOrderxs:string01Set true to deliver immediately available articles even if other articles of the order currently are not available
PositionOrderxs:complexType1nFor each article (line-item) there is only one order position.
ArticlePositionxs:complexType11Article reference
SelectedSupplierPositionxs:string01Supplier selected to deliver the article
OrderedPositionxs:complexType11Ordered (quantity/delivery days)
DeliveryOptionPositionxs:complexType0nExtra delivery conditions for supplier
PurchasePositionxs:complexType01Purchase prices
UnitSalesxs:complexType11Price per unit
PropertiesOrder; Positionxs:complexType0nAdditional information
PropertyPropertiesxs:complexType1nA list of key-value pairs

Attributes

Attributes of Customer

AttributeTypeRequiredDescription
orderIdxs:stringxOrder ID as used by the shop

Attributes of Contact

AttributeTypeRequiredDescription
emailxs:stringxMail address
telephonexs:string-Phone number
mobilexs-string-Mobile phone number
faxxs-string-Fax number

Attributes of Person

AttributeTypeRequiredDescription
salutationxs:string-Salutation
titlexs:string-Title
firstnamexs-string-First name
lastnamexs-stringxLast name

Attributes of Company

AttributeTypeRequiredDescription
namexs:stringxName of company
departmentxs:string-Department
lineOfBusinessxs-string-Area of business, e.g., automotive
costNoxs-string-Cost center
commercialRegisterIdxs-string-Commercial register number
commercialRegisterLocationxs-string-Location if commercial register
typexs-string-Corporate form
vatNoxs-string-TAX number (VAT)

Attributes of Shop

AttributeTypeRequiredDescription
orderCreationDatexs:dateTimexDate of order creation
customerIdxs:string-Customer ID as used by the shop
companyIdxs-string-Company ID as used by the shop
orderIdxs-string-Order ID as used by the shop
invoiceIdxs-string-Invoice ID

Attributes of ContactPerson

AttributeTypeRequiredDescription
salutationxs:string-Salutation
titlexs:string-Title
firstnamexs-string-First name
lastnamexs-stringxLast name

Attributes of Address

AttributeTypeRequiredDescription
typexs:string-Type of address, e.g., "BILLING"

Attributes of Sales

AttributeTypeRequiredDescription
methodxs:string-Payment method
currencyxs:string-Currency

Attributes of Net

AttributeTypeRequiredDescription
amountxs:string-Amount

Attributes of Gross

AttributeTypeRequiredDescription
amountxs:string-Amount

Attributes of Tax

AttributeTypeRequiredDescription
typexs:string-Type of tax, e.g., "NO_TAX", "LOW_TAX", "NORMAL_TAX", ... See documentation reference SOAP API, section codes, section 'Types of Tax'
amountxs:string-Amount of tax

Attributes of Charge

AttributeTypeRequiredDescription
typexs:string-Type of fee, e.g., DELIVERYCHARGE, PAYMENTCHARGE

Attributes of Position

AttributeTypeRequiredDescription
numberxs:stringxOrder position number

Attributes of Article

AttributeTypeRequiredDescription
namexs:stringxArticle name
articleIdxs:stringxID of article
eanxs-string-EAN
isbnxs-string-ISBN

Attributes of Ordered

AttributeTypeRequiredDescription
quantityxs:integerxQuantity
deliveryDaysxs:integerxExpected availability of article in days

Attributes of DeliveryOption

AttributeTypeRequiredDescription
namexs:stringxCode of delivery option

Attributes of Properties

AttributeTypeRequiredDescription
idxs:stringxID of the property group

Attributes of Property

AttributeTypeRequiredDescription
keyxs:stringxName of the property
valuexs:stringxValue of the property

Example

storeOrder

Example: Order data export format
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<storeOrder xmlns="http://types.theberlinbakery.com/v1_0" xmlns:ns2="http://types.theberlinbakery.com/customer/v1_0" xmlns:ns3="http://types.theberlinbakery.com/as/v1_0" xmlns:ns4="http://types.theberlinbakery.com/immaterialorderstate/v1_0" xmlns:ns5="http://types.theberlinbakery.com/validatearticle/v1_0" xmlns:ns6="http://types.theberlinbakery.com/v1_1">
    <MessageId>7410612-64399579-0</MessageId>
    <User></User>
    <Password></Password>
    <Shop>Company.com</Shop>
    <Order>
        <Customer orderId="000000300">
            <Company name="Company"/>
            <ContactPerson salutation="Mr." firstName="Bob" lastName="Buyer"/>
            <Contact email="b.buyer@company.com" telephone="+493087723812"/>
        </Customer>
        <Shop orderCreationDate="2015-09-17T14:22:59.462+02:00" customerId="1234567" orderId="000000300"/>
        <DeliveryAddress>
            <Receiver>
                <CompanyName>Company</CompanyName>
                <ContactPerson salutation="Mr." firstName="Bov" lastName="Buyer"/>
            </Receiver>
            <Contact email="b.buyer@company.com" telephone="+493087723812"/>
            <Location>
                <City>Berlin</City>
                <PostCode>10234</PostCode>
                <Street>Street 1</Street>
                <Country>DE</Country>
            </Location>
        </DeliveryAddress>
        <Address type="BILLING">
            <Receiver>
                <CompanyName>Company</CompanyName>
                <ContactPerson salutation="Mr." firstName="Bob" lastName="Buyer"/>
            </Receiver>
            <Contact email="b.buyer@company.com" telephone=""/>
            <Location>
                <City>Berlin</City>
                <PostCode>10234</PostCode>
                <Street>Street 1</Street>
                <Country>DE</Country>
            </Location>
        </Address>
        <Sales method="PAYPAL" currency="EUR">
            <Sum>
                <Net amount="48.00000"/>
                <Gross amount="57.12000"/>
                <Tax type="FullTax" amount="9.12000"/>
            </Sum>
            <Charge type="DELIVERYCHARGE">
                <Net amount="5.00000"/>
                <Gross amount="5.00000"/>
                <Tax type="NoTax" amount="0.00000"/>
            </Charge>
            <Total>
                <Net amount="48.00000"/>
                <Gross amount="56.17000"/>
                <Tax type="FullTax" amount="8.17000"/>
            </Total>
        </Sales>
        <SplitShipmentAllowed>true</SplitShipmentAllowed>
        <Position number="1">
            <Article name="Copy of Copy of Stuurventiel 18-18-18-AET" articleId="SD111001" ean="123456789"/>
            <Ordered quantity="1500" deliveryDays="0"/>
            <Standard></Standard>
            <Sales>
                <Sum>
                    <Net amount="48.00000"/>
                    <Gross amount="57.12000"/>
                    <Tax type="FullTax" amount="9.12000"/>
                </Sum>
                <Unit>
                    <Net amount="0.03200"/>
                    <Gross amount="0.03808"/>
                </Unit>
            </Sales>
            <Purchase>
                <Sum>
                    <Net amount="30.00000"/>
                </Sum>
                <Unit>
                    <Net amount="0.02000"/>
                </Unit>
            </Purchase>
            <Properties id="references">
                <Property key="key" value="value"/>
            </Properties>
        </Position>
        <Properties id="references">
            <Property key="key" value="value"/>
        </Properties>
    </Order>
</storeOrder>

Example File

XSD's

Configuration

To get the processed orders exported as XML file, a communication partner configuration is needed. The configuration is carried out at the database table oms."CommunicationPartnerDO".
This configurations requires a so-called partner referrer configured at the table oms."PartnerReferrerDO".

PartnerReferrerDO

The oms."PartnerReferrerDO" table is configuration table to set up all partners of the OMS environment.
Partners in this context are shops, suppliers, payment providers, finance controllers, carriers, and bonus partners. 

Note

The configuration is mostly already created with the setup of the partner (e.g., supplier, shop ...).

Each partner can have only one configuration in this table. This is ensured by a unique constraint at the database.

A valid configuration must and may only use one of the partner referencing columns.

PropertyDescriptionExample
id

Primary key of the partner referrer

5000
versionVersion flag1
shopRefReference to a shop (oms."ShopDO")null
supplierRefReference to a supplier (oms."SupplierDO")5000
paymentProviderRefReference to a payment provider (oms."PaymentProviderDO")null
financeControllerRefReference to a finance controller (oms."FinanceControllerDO")null
carrierRefReference to a carrier (oms."CarrierDO")null
bonusPartnerRefReference to a bonus partner (oms."BonusPartnerDO")null
Example: Partner referrer for supplier with id 5000
INSERT INTO oms."PartnerReferrerDO"(
            "id", "version", "shopRef", "supplierRef", "paymentProviderRef", 
            "financeControllerRef", "carrierRef", "bonusPartnerRef")
    VALUES (5000, 1, null, 5000, null, 
            null, null, null);

CommunicationPartnerDO

Configuration table to set up all relationships for a communication between different partners. In case of order placement it is a communication between shop and supplier.

PropertyDescriptionExample
idPrimary key of the communication partner1010
decisionBeanDefRefOptional: Reference to a decision bean for customized controlling of communication partnersNULL
splitTransmissionSplit into single transmissions for every order positionfalse
communicationRefReference to oms."CommunicationDO", in this case CommunicationDO with key XML###MESSAGE_FILE_SENDER_BEAN###SEND_ORDER

100005

select id from oms."CommunicationDO" where "key" = 'XML###MESSAGE_FILE_SENDER_BEAN###SEND_ORDER'
receivingPartnerReferrerRefid of the receiving oms."PartnerReferrerDO", in case of order placement the partner referrer id of the supplier or NULL for all suppliers of the OMS shop instance.5000
sendingPartnerReferrerRefid of the sending oms."PartnerReferrerDO", in case of order placement the partner referrer id of the shop10010
maxNoOfRetries

Maximum number of retries in case of errornous transmissions.
0   meant no further try .

10
retryDelayDelay of the retry5m
mergeTypeDefRef

Optional: order merge type

  • MergeTypeDefDO.MERGE_MASTER (10): only orders of merge type MERGE_MASTER will be transmitted
  • MergeTypeDefDO.MERGE_CHILD(20): only orders of merge type MERGE_CHILD will be transmitted 
NULL
Example
INSERT INTO oms."CommunicationPartnerDO"(
            "id", "decisionBeanDefRef", "splitTransmission", "communicationRef", 
            "receivingPartnerReferrerRef", "sendingPartnerReferrerRef", "maxNoOfRetries", 
            "retryDelay", "mergeTypeDefRef")
    VALUES (1010, null, false, 100005, 
            5000, 10010, 10, 
            '5m', null);

Export Return Requests/ Return Announcement

Please refer to Reference - IOM ImpEx Export RMA for more details about the structure and configuration for the new export of return announcement.

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.