1 Introduction

This guide describes how to add a shop to an existing IOM instance with existing suppliers. It is addressed to IOM operators or consultants who have access to the whole application.

1.1 Glossary

1.2 References

• Overview - IOM Supplier Onboarding
• Reference - IOM SOAP Web Services
• Guide - IOM Product Import
• Overview - IOM Customer E-mails
• Overview - IOM Database Documentation
• Concept - IOM Synchronization of Java-based Caches
• Overview - IOM REST API
• Reference - IOM Database Documentation

1.3 Prerequisites

To follow this guide, good experience with SQL is required. Also an understanding of the retailing model between the shop and suppliers is helpful.

1.4 Post Task

2 Configurations

The following section describes how to add a new shop next to an existing shop instance with one or more existing suppliers. Each configuration step contains a short description, possibly a list of additional references and an SQL example.

2.1 Creating a Shop Instance

A shop can be added to the application by adding a new instance to the database. All shop-related configurations and information refer to this instance.

To create a new shop, existing Guide - IOM Shop Onboarding (2.9 - 2.17)#ShopAddressDO (optional) and Guide - IOM Shop Onboarding (2.9 - 2.17)#ShopOrderValidationDO configurations are required first.

2.1.1 Basic Shop Configuration

2.1.1.1 ShopAddressDO

The table contains addresses and additional information of one or more shops. This information is mainly used in customer e-mail templates.

--create a new shop address
INSERT INTO "ShopAddressDO"
(
	id, "addressLine1", "addressLine2", "addressLine3", "addressLine4", 
    "addressLine5", "shopUrl", "shopFaqLink", "shopMyAccountLink", 
    "shopRefundFaqLink", "shopCcarePhoneNo", "shopCcareMailAddress", 
    "shopFaceBookLink", "shopTwitterLink", "shopYoutubeLink", "shopInstagramLink", 
    "shopNewsletterSignupLink", "shopIban", "shopBankAccountHolder", 
    "shopOrderStateLink"
)
VALUES
(
	nextval('oms."ShopAddressDO_id_seq"'), 'Intershop', 'Intershop Tower', '07740 Jena', 'Germany', 
    null, 'http://www.intershop.com/', null, null, 
    null, null, null, 
    null, null, null, null, 
    null, null, null, 
    null
);

2.1.1.2 ShopOrderValidationDO

The table contains a set of properties (field names) that correspond to information within a received order message. It can be configured to determine whether a field should have a value or not. Also see Guide - IOM Shop Onboarding (2.9 - 2.17)#Shop2OrderValidationRuleDefDO.

--create 'B2C Invoicing Rule Set'
INSERT INTO oms."ShopOrderValidationDO"
(
    id,
	"articleId", Shop2OrderValidationRuleDefDO 
	"commercialRegister", "companyName", "companyType", "costNo", "department",
	"ean", "lineOfBusiness", "purchaseGross", "purchaseNet", "purchaseTax",
	"salesGross",
	"salesNet", "salesTax",
	"shopCustomerNo", "shopOrderNo",
	"shopSelectedSupplierId", "vatNo", "singlePositionArticle",
	"name",
	"orderAddressEmailRequired"
)
VALUES 
(
	200,
	true,
	false, false, false, false, false,
	false, false, false, false, false,
	true,
	false, false,
	true, true,
	false, false, false,
	'B2C Invoicing Rule Set',
	true
);

2.1.1.3 ShopDO

The main entity of the shop configuration is the database table ShopDO. All other shop-related configurations refer to this table.

The following example refers to the instances of ShopAddressDO and ShopOrderValidationDO that are created before (or still exist).

Additionally, there can be refences to:

• Guide - IOM Shop Onboarding (2.9 - 2.17)#CountryDefDO, the country the shop is attached to.
• Guide - IOM Shop Onboarding (2.9 - 2.17)#OrderOptimizeDefDO, the preferred rule is optimization by delivery time. The rule will be used in the DOSE-process.
• Guide - IOM Shop Onboarding (2.9 - 2.17)#ShopOrderValidationDO, the order validation rule that should be used for the shop for an announced/created order.

--create a new shop instance
INSERT INTO "ShopDO"
(
	"id", "active", "availabilityTolerance", "isB2B",
	"countryDefRef",
    "mapArticleId", "modificationDate", "name",
	"orderOptimizeDefRef", 
    "overwriteSelectedSupplierAllowed", "parentRef", 
    "returnDeadline", "shopName", "shopOrderSequenceName",
	"shopAddressRef", /* removed since 2.15. */
    "shopOrderValidationRef",
	"hasSupplierPrefix", 
    "internalShopName", "shopCustomerSequenceName", 
    "preferredSupplierOnly", "orderProcessingDelay", "shopOrderSequenceNumberFormatString", 
	"salesPriceCalculatorBeanDefRef", 
    "amountDaysForPaymentReminderMailOfPrepaidOrders", "amountDaysForAutoCancellationOfPrepaidOrders",
	"isReservationWithDOSE",
	"shopRMANumberSequenceName", "shopRMANumberSequenceFormatString"
)
VALUES
(
	5555, true, null, true,
	2, 		--countryDefRef; assumed 2 is the referenced country
    true, now(), 'inTRONICS',
	2,		--orderOptimizeDefRef; assumed 2 is the referenced entry
    false, null,
    14, 'inTRONICS', null, 
	5000, 	--shopAddressRef; assumed 5000 is the referenced address /* removed since 2.15. */
    200, 	--shopOrderValidationRef; assumed 200 is the referenced validation rule
	false, 
    'inTRONICS', null, 
    false, null, null, 
	null, 
    14, 30,
	false,   --DOSE-process is not used for the reservation. The supplier with the most available stock is used.
	null, null
);

2.1.1.4 OrderOptimizeDefDO

The table contains all order optimization types that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.2 Shop-Related Configuration

The following section describes further configurations of a shop, such as used tax type, charge types and the location of the shop including currency.

2.2.1 Taxes

Taxes are essential to a business model and must be configured at a shop.

2.2.1.1 Shop2TaxTypeDefDO

The table defines the tax types that are used in the order service for a shop. Also see Reference - IOM SOAP Web Services.

--assign major tax type to a shop
INSERT INTO "Shop2TaxTypeDefDO"
(
	id, "shopTaxTypeName", "taxTypeDefRef", "shopRef", "modificationDate"
)
VALUES
(
	nextval('oms."Shop2TaxTypeDefDO_id_seq"'), 'FULL-TAX', 5, 5555, now()
);

2.2.1.2 TaxTypeDefDO

The table contains all tax types that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.2.1.3 TaxDO

The table contains the effective rates per country for the diverse tax types and their dates of validity. Common rates are already defined there, but their correctness should be verified and possibly missing ones should be added.

Hence, the taxes applied in a shop depend from the country they are attached to ("ShopDO"."countryDefRef").

See Overview - IOM Database Documentation.

--assign major tax type to a shop
INSERT INTO "TaxDO"
(
	id, "countryDefRef", "tax", "taxTypeDefRef", "validFrom", "validUntil"
)
VALUES
(
	nextval('oms."TaxDO_id_seq"'), 7, 17.5, 6, '2012-01-01 00:00:00', '2099-12-31 23:59:59'
);

2.2.2 Charges

Charges are types of fees for various purposes, e.g., for optional payment cash on delivery (COD), for delivery or payment in general.

2.2.2.1 Shop2ChargeTypeDefDO

The table defines the types of charges that are used by a shop.

--assign charge type to a shop
INSERT INTO "Shop2ChargeTypeDefDO"
(
	id, "chargeTypeDefRef", "shopChargeTypeName", "shopRef"
)
VALUES
(
	nextval('oms."Shop2ChargeTypeDefDO_id_seq"'),
    1, --chargeTypeDefRef
    'delivery charge', 
    5555
);

2.2.2.2 ChargeTypeDefDO

The table contains all types of charges that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.2.3 Country and Currency

In general a shop is located in a country which also determines the currency. This information can also be used to determine country-related processes, documents, taxing, fees, language and many more.

2.2.3.1 Shop2CountryDefDO

The table defines country naming and currency naming as used by the shop instead of defaults.

--assign country as location to a shop
INSERT INTO oms."Shop2CountryDefDO"
(
	"id", "countryDefRef", "shopCountryName", "shopCurrencyName", "shopRef"
)
VALUES
(
	nextval('oms."Shop2CountryDefDO_id_seq"'), 9, 'BELGIUM', 'EURO', 5555
);

2.2.3.2 CountryDefDO

The table contains all countries, their assigned currencies and localization codes that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.2.4 Sales Channels

A sales channel in IOM offers the ability to mark shops as a special sales channel. This can be for example SPECIAL SALES or advertisements. The information can be given in the order import from the shop for example.

2.2.4.1 Shop2SalesChannelDefDO

The table defines a mapping of a sales channel of IOM to a shop-specific identifier, e.g., IOM channel 1 is marked for SPECIAL SALES.

--assign a sales channel to a shop
INSERT INTO oms."Shop2SalesChannelDefDO"
(
	"id", "salesChannelDefRef", "shopSalesChannelName", "shopRef"
)
VALUES
(
	nextval('oms."Shop2SalesChannelDefDO_id_seq"'), 1, 'SALE', 5555
);

2.2.4.2 SalesChannelDefDO

The table contains all sales channels that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.3 Payment and Debtors

The following section describes the configuration of the used payment methods, payment providers and possible debtor management system (finance controller).

2.3.1 Payment

Payment is the process of money transfer from one party to another, e.g., customer to merchant.

A payment service provider (PSP) is a company that offers merchants' online services for accepting electronic payments by a variety of payment methods including credit card, bank-based payments such as direct debit, bank transfer, and real-time bank transfer based on online banking.

2.3.1.1 Shop2PaymentDefDO

The table defines the payment methods and further properties that are used by a shop.

--assign a payment method to a shop
INSERT INTO "Shop2PaymentDefDO"
(
	id, active, "initOrderStateDefRef", "paymentDefRef", "shopPaymentName", 
    "shopRef", "safePayment", "payment2ProcessStageDefRef", "useAutomaticAuthorizationExtension", 
    "authizationDurationInDays", "timeForPaymentAllowed"
)
VALUES
(
	nextval('oms."Shop2PaymentDefDO_id_seq"'), true, 0, 5, 'invoice', 
    5555, true, 20, false, 
    null, null
);

2.3.1.2 PaymentDefDO

The table contains all payment methods that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.3.1.3 PaymentProviderDO

The table contains the characteristics of a PSP, i.e., a name and also says whether partly captures are allowed.

--create a payment provider
INSERT INTO "PaymentProviderDO"
(
	id, "modificationDate", name, "partlyCaptureAllowed", "partlyReverseAllowed"
)
VALUES
(
	nextval('oms."PaymentProviderDO_id_seq"'), now(), 'Klarna', false, false
);

2.3.1.4 Shop2PaymentProvider2PaymentDefDO

The table defines the payment service provider and a payment method that is used by a shop in this relation.

--assign a payment provider to a shop
INSERT INTO "Shop2PaymentProvider2PaymentDefDO"
(
	id, "shopRef", "paymentProviderRef", "paymentDefRef", "creationDate"
)
VALUES
(
	nextval('oms."Shop2PaymentProvider2PaymentDefDO_id_seq"'), 5555, 10000, 11, now()
);

2.3.2 Debtor Management

A debtor management system hosts and controls payments from customers.

2.3.2.1 FinanceControllerDO

The table contains a simple list of finance controllers (debtor management systems).

--create a finance controller
INSERT INTO "FinanceControllerDO"
(
	id, name
)
VALUES
(
	10000, 'Debtor Management System'
);

2.3.2.2 FinanceController2PaymentDefDO

The table defines the payment methods that are offered by a finance controller (debtor management systems).

--assign payment method to a finance controller
INSERT INTO "FinanceController2PaymentDefDO"
(
	id, "financeControllerRef", "financeControllerPaymentExportName", "financeControllerPaymentImportName", "paymentDefRef"
)
VALUES
(
	nextval('oms."FinanceController2PaymentDefDO_id_seq"'), 10000, 'PayPal', 'PayPal', 10
);

2.3.2.3 FinanceController2TaxTypeDefDO

The table defines the tax types that are used by a finance controller (debtor management system).

--assign tax type to a finance controller
INSERT INTO "FinanceController2TaxTypeDefDO"
(
	id, "financeControllerRef", "financeControllerTaxTypeExportName",
	"financeControllerTaxTypeImportName", "taxTypeDefRef"
)
VALUES
(	
	nextval('oms."FinanceController2PaymentDefDO_id_seq"'), 10000, 'FullTax',
	'FullTax', 5
);

2.3.2.4 Shop2FinanceControllerDO

The table defines the finance controllers (debtor management systems) that are used by a shop.

--assign a finance controller to a shop
INSERT INTO "Shop2FinanceControllerDO"
(
	id, "financeControllerRef", "shopRef", "financeControllerShopName", description
)
VALUES
(
	nextval('oms."Shop2FinanceControllerDO_id_seq"'), 10000, 5555, 'inSPIRED', 'inSPIRED'
);

2.4 Order-Related Configurations

The following section describes the configuration of order validations, order approvals and mappings of order status codes as used by a shop.

2.4.1 Order Validation

When an order is announced (or created) in the IOM, a set of rules can validate various parameters and circumstances, e.g., validation of prices, availability of names, validation of addresses or even the correction of missing information.
These rules are configurable. Additionally, a rule can be configured to be part of the order creation (synchronous) or to be processed later (asynchronous) after the order was created in the IOM.

In case a synchronous validation fails, the order announcement fails immediately. No order will be created.

In case an asynchronous validation fails, the order can be checked and fixed manually. The order can be processed then.

2.4.1.1 Shop2OrderValidationRuleDefDO

The table defines the validation rules for an announced (or created) order that are used by a shop. Also see introduction Guide - IOM Shop Onboarding (2.9 - 2.17)#Order Validation.

--assign a validation rule for an order to a shop
INSERT INTO "Shop2OrderValidationRuleDefDO"
(
	id, "orderValidationRuleDefRef", "runSynchron", "shopRef"
)
VALUES
(
	nextval('oms."Shop2OrderValidationRuleDefDO_id_seq"'), 1, true, 5555
);

2.4.1.2 OrderValidationRuleDefDO

The table contains all validation rules for an announced (or created) order that are supported by the application by default. For all available values please see Overview - IOM Database Documentation. Also see introduction: Guide - IOM Shop Onboarding (2.9 - 2.17)#Order Validation.

2.4.2 Order Approval

After an order is announced (or created) in the IOM, a set of rules can check various preconditions, e.g., upper limits of order totals, lower and/or upper limits of ordered items, fraud prevention, customer credit-worthiness and many more. These rules can be configured. An approval will be required when a rule determines a violation. As long as at least one approval is open, the order process is stopped. Rejecting of at least one approval will cancel the entire order.

2.4.2.1 Shop2Supplier2ApprovalTypeDefDO

The table defines the approval rules, their priority and further properties that are used by a shop. Optionally, a supplier and payment provider (PSP) can be assigned.

--assign an approval rule for orders to a shop (and optional: a shop and/ or a payment service provider for the rule)
INSERT INTO "Shop2Supplier2ApprovalTypeDefDO"
(
	id, active, "isAffectingDOSEonChange", "approvalRank", "approvalTypeDefRef",
    "isOrderTransmission", "supplierApprovalTypeName", "shopRef",
    "supplierRef", "paymentProviderRef", "decisionBeanDefRef", "sendOrderApproval",
    "supplierApprovalTypeDescription", "manualApproval")
VALUES
(
	nextval('oms."Shop2Supplier2ApprovalTypeDefDO_id_seq"'), true, false, 1, 3,
	false, 'General Approval', 5555,
    10000, null, null, false,
    'General Approval', true
);

2.4.2.2 ApprovalTypeDefDO

The table contains all approval types that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.4.3 Order Creation Responses

After having created an order successfully, the IOM returns a response to the shop. This response is marked with a code that describes the circumstances of order creation (or cancelation in case of errors). This code can be used from the shop as information or to handle further processes.

The IOM has a set of representative response codes. Codes can be for example Accepted, Accepted with change, Canceled and more. See Guide - IOM Shop Onboarding (2.9 - 2.17)#ResponseStateCodeDefDO for more details.
In case a shop uses its own naming, a mapping can be configured to enforce the IOM to use the response codes of the shop.

2.4.3.1 Shop2ResponseStateCodeDefDO

The table defines the order response codes that should be used for a shop which will replace the default response codes of the IOM.

--assign a response state to a shop
INSERT INTO oms."Shop2ResponseStateCodeDefDO"
(
	"id", "responseStateCodeDefRef", "shopResponseStateCodeName", "shopRef"
)
VALUES
(
	nextval('oms."Supplier2ResponseStateCodeDefDO_id_seq"'), 1, 'OK', 5555
);

2.4.3.2 ResponseStateCodeDefDO

The table contains all response state codes that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.4.4 Order States

An order state represents the processing status of an order related to the configured business processes. For example an order can be initial, in progress by a supplier or already dispatched.

The IOM has a set of representative states. In case a shop uses its own naming, a mapping can be configured to enforce the IOM to use the shop namings. Mappings are possible for order states (state of the entire order) as well as for order position states (state of a single order position of an order).

2.4.4.1 Shop2OrderStatesDefDO

The table defines the order status codes that should be used for a shop which will replace the default status codes of the IOM. It is used for example in the OrderState-webservice. See Reference - IOM SOAP Web Services.

--map an order status of the IOM to a name of the order status as used in the shop
INSERT INTO "Shop2OrderStatesDefDO"
(
	id, "orderStatesDefRef", "shopOrderStatesName", "shopRef"
)
VALUES
(
	nextval('oms."Shop2OrderStatesDefDO_id_seq"'), 0, 'initial', 5555
);

2.4.4.2 OrderStatesDefDO

The table contains all order status codes that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.4.4.3 Shop2OrderPosStatesDefDO

The table defines the order position status codes that should be used for a shop which will replace the default status codes of the IOM. It is used for example in the OrderState- webservice. See Reference - IOM SOAP Web Services.

--map and order position status of the IOM to a name of the order position status as used in the shop
INSERT INTO "Shop2OrderPosStatesDefDO"
(	
	id, "orderPosStatesDefRef", "shopOrderPosStatesName", "shopRef"
)
VALUES
(
	nextval('oms."Shop2OrderPosStatesDefDO_id_seq"'), 0, 'initial', 5555
);

2.4.4.4 OrderPosStatesDefDO

The table contains all order position status codes that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.5 Supplier, Carrier and Delivery

The following section describes the configuration of the related suppliers, carriers and delivery properties.

2.5.1 Supplier

In IOM a supplier is fulfilling the tasks of delivering products (orders) and handling order returns. A warehouse can be a supplier, too. Also see Guide - IOM Supplier Onboarding 2.0.

Connected with the IOM, a supplier can, among other things:

• Accept or reject offered requests to deliver orders - entirely or partially
• Announce the delivery packages (a dispatch)
• Announce the return of orders - entirely or partially
• Receive an announcement for an order return in the future

After an order was accepted by the IOM, a process (DOSE) selects appropriate suppliers for delivery using a configured set of DOSE rules. Rules are for example checks for product availability, delivery time, prices and more. Also see Guide - IOM Shop Onboarding (2.9 - 2.17)#OrderSupplierEvaluationRuleDefDO. The selected suppliers receive a request that indicates whether the delivery can be fulfilled or not.

2.5.1.1 Shop2SupplierDO

The table defines the suppliers that are used by a shop.

--assign a supplier to a shop
INSERT INTO oms."Shop2SupplierDO"
(
	"id", "active", "modificationDate", "reservationTimeInDays", "sendOffTimeInHours",
    "shopAccount", "shopPassword", "shopSupplierName", "splitShipmentAllowed",
    "supplierAccount", "supplierPassword", "supplierShopName", "shopRef",
    "supplierRef", "supplierShopKey", "sendOrderCoupon", "supplierSupportsCOD",
    "eolDetectionTimeInterval", "resetStockOnImport", "flatRateShipping",
    "isDropShipment", "immaterialArticleUrlValidityDuration", "returnCarrierRef",
    "leadCode", "useSupplierArticleNoAsShopArticleNo", "shopArticleNoPrefix",
	"stockReduceModel"
 )
VALUES
(
	15000, TRUE, now(), 0, 0,
    null, null, 'SIM supplier - North', FALSE,
    null, null, 'SIM', 5555,
    6666, null, FALSE, FALSE,
    null, FALSE, null,
    FALSE, null, null,
    null, FALSE, null,
	25
);

--map the shop to the IOM internal supplier
INSERT INTO oms."Shop2SupplierDO"
(
	"id", "active", "modificationDate", "reservationTimeInDays", "sendOffTimeInHours",
    "shopAccount", "shopPassword", "shopSupplierName", "splitShipmentAllowed",
    "supplierAccount", "supplierPassword", "supplierShopName", "shopRef",
    "supplierRef", "supplierShopKey", "sendOrderCoupon", "supplierSupportsCOD",
    "eolDetectionTimeInterval", "resetStockOnImport", "flatRateShipping",
    "isDropShipment", "immaterialArticleUrlValidityDuration", "returnCarrierRef",
    "leadCode", "useSupplierArticleNoAsShopArticleNo", "shopArticleNoPrefix",
	"stockReduceModel"
)
VALUES
(
	15001, TRUE, now(), 0, 0,
    null, null, 'OMS Internal Supplier', FALSE,
    null, null, 'SIM', 5555,
    1, null, FALSE, FALSE,
    null, FALSE, null,
    FALSE, null, null,
    null, FALSE, null,
	null
);

2.5.1.2 Shop2OrderSupplierEvaluationRuleDefDO

The table defines the rules for the DOSE-process that should be used by a shop. In case a validation fails, the order will be canceled automatically.

--assign an validation rule for a supplier to a shop
INSERT INTO "Shop2OrderSupplierEvaluationRuleDefDO"
(
	id, "errorForcesAutomaticCancelation", "orderSupplierEvaluationRuleDefRef", "shopRef"
)
VALUES
(
	nextval('oms."Shop2OrderSupplierEvaluationRuleDefDO_id_seq"'), true, 900, 5555
);

2.5.1.3 OrderSupplierEvaluationRuleDefDO

These rules are used within the DOSE (supplier selection). The table contains all validation rules that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.5.2 Carrier

2.5.2.1 CarrierDO

The table contains a list of carriers and additional properties, such as package tracking URL or the cargo center. 

--create a carrier
INSERT INTO "CarrierDO"
(
	id, "modificationDate", name, "trackingUrl",
	version, "cargoCompany", "cargoCenter", "identCodeGenerationBeanDefRef"
)
VALUES
(
	nextval('oms."CarrierDO_id_seq"'), now(),
	'DHL', 'http://nolp.dhl.de/nextt-online-public/report_popup.jsp',
	1, null, null, 2
);

2.5.2.2 Shop2CarrierDO

The table defines the carrier names that should be used for a shop which will replace the default namings of the IOM.

--assign a carrier to a shop
INSERT INTO oms."Shop2CarrierDO"
(
	"id", "shopCarrierName", "carrierRef", "shopRef"
)
VALUES
(
	nextval('oms."Shop2CarrierDO_id_seq"'), 'Deutsche Post DHL', 11, 5555
);

2.5.3 Delivery

Delivery is the process of transporting goods from a source location to a destination.

IOM optionally supports a property for the type of delivery, i.e., standard and more. The property can be used within customizations but is not used within the standard.

Additionally, IOM supports an option of delivery, i.e., cash on delivery or pick up in store.

2.5.3.1 Shop2DeliveryFormDefDO

The table defines the delivery form that should be used by a shop.

--assign a delivery form to a shop
INSERT INTO oms."Shop2DeliveryFormDefDO"
(
	"id", "deliveryFormDefRef", "shopDeliveryFormName", "shopRef"
)
VALUES
(
	nextval('oms."Supplier2DeliveryFormDefDO_id_seq"'), 20, 'Freight forwarding', 5555
);

2.5.3.2 DeliveryFormDefDO

The table contains all delivery forms that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.5.3.3 Shop2DeliveryOptionDefDO

The table defines the delivery options that should be used for a shop which will replace the default delivery options of the IOM.

--assign a delivery option to the shop
INSERT INTO oms."Shop2DeliveryOptionDefDO"
(
	"id", "deliveryOptionDefRef", "shopDeliveryOptionName", "shopRef"
)
VALUES
(	
	nextval('oms."Supplier2DeliveryOptionDefDO_id_seq"'), 8, 'Overnight', 5555
);

2.5.3.4 DeliveryOptionDefDO

The table contains all delivery options that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.6 Order Return-Related Configurations

A return is the act of giving or sending back ordered products.
In the scope of IOM, a return will be linked with the previous order. A return can be announced to the IOM and the supplier before sending, but it can also be registered directly if the return was received by the supplier. Also see Guide - IOM Shop Onboarding (2.9 - 2.17)#Supplier.

To support the return process, a set of properties are offered by the IOM. Therefore the following section describes the configuration of return-related configurations.

2.6.1 Return Types

A return type roughly indicates the reason of a return, i.e., a general return or a defect.

2.6.1.1 Shop2ReturnTypeDefDO

The table defines the return types that should be used by a shop.

--assign a return type to a shop
INSERT INTO oms."Shop2ReturnTypeDefDO"
(
	"id", "returnTypeDefRef", "shopReturnTypeName", "shopRef"
)
VALUES
(
	nextval('oms."Shop2ReturnTypeDefDO_id_seq"'), 4, 'RET', 5555
);

2.6.1.2 ReturnTypeDefDO

The table contains all return types that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.6.2 Return Reasons

A return reason specifies the type of return, e.g., return of goods because of missing product attributes for the return type return.

2.6.2.1 Shop2ReturnReasonDefDO

The table defines the return reasons that should be used for a shop which will replace the return reasons of the IOM.

--assign a return reason to a shop
INSERT INTO oms."Shop2ReturnReasonDefDO"
(
	"id", "returnReasonDefRef", "shopReturnReasonName", "shopRef", "shop2ReturnReasonDefSpecRef"
)
VALUES
(
	nextval('oms."Shop2ReturnReasonDefDO_id_seq"'), 307, 'WRONG_ITEM', 10000, null
);

2.6.2.2 ReturnReasonDefDO

The table contains all return reasons that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.6.3 Return States

A return state represents the status of processing of a return related to the configured business processes. For example a return can be initial, checked or already closed.

The IOM has a set of representative states. In case a shop will use its own naming, a mapping can be configured to enforce the IOM to use the namings of the shop.

2.6.3.1 Shop2ReturnStatesDefDO

The table defines the return states that should be used for a shop which will replace the return states of the IOM.

--assign a return state to a shop
INSERT INTO "Shop2ReturnStatesDefDO"
(
	id, "returnStatesDefRef", "shopReturnStatesName", "shopRef"
)
VALUES
(
	nextval('oms."Shop2ReturnStatesDefDO_id_seq"'), 0, 'initial', 5555
);

2.6.3.2 ReturnStatesDefDO

The table contains all return states that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.6.4 Return Approval

A return approval can be the precondition before a return of an order back to the supplier can be processed. Therefore the ReverseService-webservice can be used to approve or decline a return request. See Reference - IOM SOAP Web Services for more information about the ReverseService.

2.6.4.1 Shop2ReturnReason2ApprovalStateCodeReasonDefDO

The table defines the approval state code reasons that should be used for a shop and its return reason replacement.

--assign an approval state code reason to a relation of return reason and shop
INSERT INTO "Shop2ReturnReason2ApprovalStateCodeReasonDefDO"
(
	id, "approvalStateCodeReasonDefRef", "shop2ReturnReasonDefRef"
)
VALUES
(
	nextval('oms."Shop2ReturnReason2ApprovalStateCodeReasonDefDO_id_seq"'), 1, 10000
);

2.6.4.2 ApprovalStateCodeReasonDefDO

The table contains all approval state code reasons that are supported by the application by default. They are used for all approvals of IOM. For all available values please see Overview - IOM Database Documentation.

2.6.4.3 ApprovalStateCodeDefDO

The table contains all approval state codes that are supported by the application by default. They are used for all approvals of IOM. For all available values please see Overview - IOM Database Documentation.

2.6.5 Rebates and Reductions

A rebate is an amount paid by way of reduction, return, or refund on what has already been paid or contributed.

In IOM a reduction agreement can be configured for returns. The configuration basically includes the relation of a shop and a supplier plus further properties.

2.6.5.1 Shop2Supplier2ReduceReasonDO

The table defines a reduction agreement of a shop and a supplier in terms of an order return. It contains the reduction reasons as used by the shop supplier.

At least one default (isDefault=true) configuration is required for each relation in Guide - IOM Shop Onboarding (2.9 - 2.17)#Shop2SupplierDO.

--assign a reduction reason to shop-supplier relation
INSERT INTO oms."Shop2Supplier2ReduceReasonDO"
(
	"id", "shopReduceReason", "supplierReduceReason", "shop2SupplierRef", "isDefault"
)
VALUES
(
	nextval('oms."Shop2Supplier2ReduceReasonDO_id_seq"'), 'default', 'no reduction', 15000, TRUE
);

2.6.5.2 Shop2ReductionUnitDefDO

The table defines the reduction units that should be used for a shop which will replace the reduction units of the IOM.

--assign a reduction unit to a shop
INSERT INTO oms."Shop2ReductionUnitDefDO"
(
	"id", "reductionUnitDefRef", "shopReductionUnitName", "shopRef"
)
VALUES
(
	nextval('oms."Supplier2ReductionUnitDefDO_id_seq"'), 3, 'MO', 5555
);

2.6.5.3 ReductionUnitDefDO

The table contains all reduction units that are supported by the application by default. For all available values please see Overview - IOM Database Documentation.

2.7 Feature-Related Configurations

2.7.1 OMT - Send a Return Label on Demand by E-Mail

The OMT offers the functionality to trigger an e-mail of an existing return label document as attachment. To enable this feature, the following configuration is required.

2.7.1.1 CommunicationPartnerDO

First add a communication (partner). The receiving partner has to be NULL, because the receiver is defined by an e-mail address that will be selected or entered by the user. The example shows the configuration for the shop instance with id 5555.

-- creates a communication partner to enable the E-mail transmission on behalf of a OMS shop instance 
INSERT INTO oms."CommunicationPartnerDO"
(
	"id", "decisionBeanDefRef", "splitTransmission", "communicationRef", "receivingPartnerReferrerRef", 
	"sendingPartnerReferrerRef", "maxNoOfRetries", "retryDelay", "mergeTypeDefRef", "splitTransmissionPerSupplier"
)
VALUES 
(
	nextval('oms."CommunicationPartnerDO_id_seq"'), null, false, (SELECT "id" from oms."CommunicationDO" WHERE "key" = 'Send Customer Mail Return Label'), null, 
	(SELECT "id" FROM oms."PartnerReferrerDO" WHERE "shopRef" = 5555), 5, '1m', null, false
);

2.7.1.2 ExecutionBeanValueDO

Second configure the used mail templates. E-mail-transmission-specific parameters must be configured additionally in ExecutionBeanValueDO. 

Please refer to Execution Bean Keys (Reference - IOM Customer E-mails).

2.7.1.3 Possible Processes

2.8 Predefined Custom Properties Configurations

IOM has the ability to add additional information to various business objects. In order to configure a predefined custom property for e.g., return requests, please refer to Cookbook - IOM Configure Predefined Custom Properties.

For further details about the predefined custom properties, see Overview - IOM Custom Properties.

3 Product Import

The IOM requires information about products of suppliers that should be sold in one or more shops.

To import product data files from a supplier into IOM, a product import configuration is required. Guide - IOM Product Import 2.2 describes files and configuration steps for the product import.

4 Business Events

Business events extend the standard process of the IOM. They can be used to add additional functionality or to customize processes.

4.1 Invoice Creation

An invoice is a commercial document issued by a seller to the buyer, indicating the products, quantities, and agreed prices for products or services the seller has provided to the buyer. An invoice indicates that the buyer must pay the seller, according to the payment terms.

--create an event listener
--uses function admin.add_event_registry_entry(p_processesref bigint, p_shopref bigint, p_eventdefref bigint, p_description text) which is adding a new entry to EventRegistryEntryDO if not exists yet. 
SELECT admin.add_event_registry_entry
(
	(SELECT p.id FROM "ProcessesDO" p JOIN "ProcessDefDO" pd ON p."processDefRef" = pd.id AND pd."queueName" = 'CheckOrderQueue'),
	5555, 3, 'Invoicing Events on CheckOrder'
);

--configure type of invoice and used decision bean
--uses function admin.add_invoicing_event_registry_entry(p_eventregistryentryref bigint, p_invoicingeventdefref bigint, p_paymentdefref bigint, p_invoicingtypedefref bigint, p_decisionbeandefref bigint)
--which is adding a new entry to InvoicingEventRegistryEntryDO if not exists yet. The entry is set to active.
SELECT admin.add_invoicing_event_registry_entry
(
	(SELECT id FROM "EventRegistryEntryDO" WHERE description = 'Invoicing Events on CheckOrder'),
	1, null, 1, null
);

--create configuration for invoice number creation
INSERT INTO "InvoicingNoConfigDO"
(
	id, "name", "countGenerated", "creationDate", enabled, "generationDate",
	"startNumber", "endNumber", "numberRangeFormatterDefRef", "invoicingTypeDefRef", "maxNotAllocatedInvoiceNo", 
	"modificationDate", "startDate", "shopRef", version
)
VALUES
(
	nextval('"InvoicingNoConfigDO_id_seq"'), 'Billing number and credit note number', 0, now(),	true, null,
	'2017000000', '2017999999',	5, null, 1000,
	now(), now(), 5555, 1
);

select so."internalShopName", 
ere."shopRef", 
pd."queueName", 
ere.description  as "eventRegistryDesc", 
e.description as "eventDesc",
x.*,
iere.active,
iere."decisionBeanDefRef" ,
iidd.description as "invoicingEventDesc", 
it."name" as "invoicingType"
from "EventRegistryEntryDO" ere 
join "InvoicingEventRegistryEntryDO" iere ON(iere."eventRegistryEntryRef" =ere.id)
join oms."InvoicingEventDefDO" iidd on(iere."invoicingEventDefRef" =iidd.id) 
join "InvoicingTypeDefDO" it on(iere."invoicingTypeDefRef" =it.id)
join "EventDefDO" e on(ere."eventDefRef" =e.id )
join  "ProcessesDO" p on (ere."processesRef" =p.id) 
JOIN "ProcessDefDO" pd ON (p."processDefRef" = pd.id)
right JOIN "ShopDO" so ON (ere."shopRef" = so.id)
left join lateral (select invc."startNumber", invc."lastGeneratedNumber" from "InvoicingNoConfigDO" invc  where invc."shopRef"=ere."shopRef" and enabled order by id desc limit 1)x on true
order by 2,3

--create relation of communication partners 
--uses function admin.add_communication_partner(p_decisionbeandefref bigint, p_splittransmission boolean, p_communicationref bigint, p_sendingpartnerreferrerref bigint, p_receivingpartnerreferrerref bigint)
--which is adding a new entry to CommunicationPartnerDO if not exists yet. Default values are: maxNoOfRetries = 12, retryDelay = 30m, mergeTypeDefRef = NULL
SELECT admin.add_communication_partner
(
	25, false, 100049, (SELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = 5555), null
); 

4.2 Payment Events

Payment is the process of money transfer from one party to another, i.e., customer to merchant.

--create an event listener
--uses function admin.add_event_registry_entry(p_processesref bigint, p_shopref bigint, p_eventdefref bigint, p_description text) which is adding a new entry to EventRegistryEntryDO if not exists yet.
SELECT admin.add_event_registry_entry
(
	(SELECT p.id FROM "ProcessesDO" p JOIN "ProcessDefDO" pd ON p."processDefRef" = pd.id AND pd."queueName" = 'CloseInvoicingQueue'),
	5555, 2, 'Payment Events on CheckOrder'
);

--configure type of payment and used decision bean
--uses function admin.add_payment_event_registry_entry(p_eventregistryentryref bigint, p_paymenteventdefref bigint, p_paymentdefref bigint, p_paymentnotificationactiondefref bigint, p_decisionbeandefref bigint)
--which is adding a new entry to PaymentEventRegistryEntryDO if not exists yet. The entry is set to active.
SELECT admin.add_payment_event_registry_entry
(
	(SELECT id FROM "EventRegistryEntryDO" WHERE description = 'Payment Events on CloseInvoicingQueue' AND "shopRef"=1234),
	10, 3, 3, 70
);

select so."internalShopName" , ere."shopRef",
iere.active,
pd."queueName", ere.description  as "eventRegistryDesc", e.description as "eventDesc",
iere."decisionBeanDefRef" ,
pdo.description as "paymentDesc",
pna."name" as "PaymentNotificationAction"
from "EventRegistryEntryDO" ere 
join "PaymentEventRegistryEntryDO" iere ON(iere."eventRegistryEntryRef" =ere.id)
join oms."PaymentDefDO" pdo on(iere."paymentDefRef" =pdo.id) 
join oms."PaymentNotificationActionDefDO" pna on(iere."paymentNotificationActionDefRef" =pna.id)
join "EventDefDO" e on(ere."eventDefRef" =e.id )
join  "ProcessesDO" p on (ere."processesRef" =p.id) 
JOIN "ProcessDefDO" pd ON (p."processDefRef" = pd.id)
right JOIN "ShopDO" so ON (ere."shopRef" = so.id)
left join lateral (select invc."startNumber", invc."lastGeneratedNumber" from "InvoicingNoConfigDO" invc  where invc."shopRef"=ere."shopRef" and enabled order by id desc limit 1)x on true
order by 2,8,9

--create approval for a payment method related to a payment provider
--uses function admin.add_payment_action_approval(
--   p_paymentnotificationactiondefref bigint, 
--   p_shop2paymentprovider2paymentref bigint,
--   p_doprocess boolean, 
--   p_domanualapprove boolean) 
-- which is adding a new entry to PaymentActionApprovalDefDO if not exists yet.
SELECT admin.add_payment_action_approval ( 3, 5555, true, false );

--create communication object to send payment notifications
INSERT INTO "CommunicationDO"
(
	id, active, key, "documentFormatDefRef", "executionBeanDefRef", "transmissionTypeDefRef", "communicationVersionDefRef", "transmissionFormDefRef"
)
VALUES
(
	nextval('"CommunicationDO_id_seq"'), true, 'SEND_PAYMENT_NOTIFICATION', 2, 10000, 320, 1,10
);

--create relation of communication partners
--uses function admin.add_communication_partner(p_decisionbeandefref bigint, p_splittransmission boolean, p_communicationref bigint, p_sendingpartnerreferrerref bigint, p_receivingpartnerreferrerref bigint)
--which is adding a new entry to CommunicationPartnerDO if not exists yet. Default values are: maxNoOfRetries = 12, retryDelay = 30m, mergeTypeDefRef = NULL
SELECT admin.add_communication_partner
(
    null, false,
    (SELECT id FROM "CommunicationDO" WHERE "key" = 'SEND_PAYMENT_NOTIFICATION'),
    (SELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = 5555),
    (SELECT "id" FROM "PartnerReferrerDO" WHERE "paymentProviderRef" = 10000)
);

4.3 Customer E-Mails

In the context of e-commerce, e-mails enable business owners and systems to interact automatically with customers and deliver information on process statuses, which is legally relevant.

--create an event listener
--uses function admin.add_event_registry_entry(p_processesref bigint, p_shopref bigint, p_eventdefref bigint, p_description text) which is adding a new entry to EventRegistryEntryDO if not exists yet.
SELECT admin.add_event_registry_entry
(
	(SELECT p.id FROM "ProcessesDO" p JOIN "ProcessDefDO" pd ON p."processDefRef" = pd.id AND pd."queueName" = 'CheckOrderQueue'),
	5555, 1, 'Mail Events on CheckOrder'
);

--configure event handler and used decision bean
--uses admin.add_mail_event_registry_entry(p_eventregistryentryref bigint, p_maileventdefref bigint, p_decisionbeandefref bigint, p_transmissiontypedefref bigint)
--which is adding a new entry to MailEventRegistryEntryDO if not exists yet. The entry is set to active.
SELECT admin.add_mail_event_registry_entry
(
	(SELECT id FROM "EventRegistryEntryDO" WHERE description = 'Mail Events on CheckOrder'),
	1, 50, 500
);

--create relation of communication partners
--uses function admin.add_communication_partner(p_decisionbeandefref bigint, p_splittransmission boolean, p_communicationref bigint, p_sendingpartnerreferrerref bigint, p_receivingpartnerreferrerref bigint)
--which is adding a new entry to CommunicationPartnerDO if not exists yet. Default values are: maxNoOfRetries = 12, retryDelay = 30m, mergeTypeDefRef = NULL
SELECT admin.add_communication_partner
(
	null,
	false,
	(SELECT id FROM "CommunicationDO" WHERE "transmissionTypeDefRef" = 500),
	(SELECT "id" FROM "PartnerReferrerDO" WHERE "shopRef" = 5555),
	null
);

--assign am e-mail template to communication partner
--uses admin.add_execution_bean_value(p_executionbeankeydefref bigint, p_parametervalue text, p_communicationpartnerref bigint)
--which is adding a new value to ExecutionBeanValueDO if not exists yet.
SELECT admin.add_execution_bean_value
(
	1205, 'orderMessage.vm',
	(
		SELECT id FROM "CommunicationPartnerDO"
		WHERE
			"communicationRef" = (SELECT id FROM "CommunicationDO" WHERE "transmissionTypeDefRef" = 500) AND
			"sendingPartnerReferrerRef" = (SELECT id FROM "PartnerReferrerDO" WHERE "shopRef" = 5555) AND
			"receivingPartnerReferrerRef" isNull
	)
);

5 Postcondition Cache Clear

Please see Post Task at the beginning of the document.