Document Properties
Kbid28B459
Last Modified25-Sep-2020
Added to KB18-Sep-2017
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • IOM 2.9
  • IOM 2.15
  • IOM 2.16

Guide - IOM Shop Onboarding (2.9 - 2.17)

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.

IOM Shop Onboarding

1.1 Glossary

TermDescription
B2BBusiness to Business
B2CBusiness to Consumer
CODCash on Delivery
DefDOPersistence entities which contain a set of predefined values. They are referred as "Enumeration Tables" within the IOM Database Documentation.
DefRefA foreign-key relation from one referencing database table column to another database relation, usually to a DefDO.
DOData Object - used as persistence entities to represent stored values in the database
DOSEDynamic Order Supplier Evaluation, a process of IOM that evaluates one or more suppliers for an order.
See Guide - IOM Shop Onboarding (2.9 - 2.17)#OrderSupplierEvaluationRuleDefDO for validation rules and Guide - IOM Shop Onboarding (2.9 - 2.17)#OrderOptimizeDefDO for possible optimizations.
IOMThe abbreviation for Intershop Order Management
IDIdentifier
OMSThe abbreviation for Order Management System, the technical name of IOM
OMTThe abbreviation for Order Management Tool, the graphical management tool of the IOM
PSPPayment Service Provider
SQLStructured Query Language
URLUniform Resource Locator

1.2 References

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.

Note

A supplier must already exist in IOM for this guide. Also see Overview - IOM Supplier Onboarding.

1.4 Post Task

Note

After having finished the configuration, a cache clear is required on all application servers. See Concept - IOM Synchronization of Java-based Caches and Overview - IOM REST API.

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

From IOM version 2.9 this table is deprecated. It has been removed in 2.15.


Optional

This configuration is optional.

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

Example
--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.

Note

References

A rule must be referenced in Guide - IOM Shop Onboarding (2.9 - 2.17)#Shop2OrderValidationRuleDefDO to be executed.

Note

Mandatory Rules

All rules that are not referenced and mandatory will be executed asynchronously.

Example
--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:


Note

This table ShopAddressDO has been removed in IOM version 2.15 and is no longer available. Do not use the table any longer.

Note

The column ceo is deprecated since 2.15. and has been removed with IOM 3.0. Do not use the column any longer.

Example
--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.

Example
--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.

Example
--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.

Example
--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

Optional

This configuration is optional.

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

Example
--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

Note

Sales Channels is deprecated since version 2.17 and removed since version 3.0.

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

Note

Shop2SalesChannelDefDO is deprecated since version 2.17 and removed since version 3.0.

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.

Optional

This configuration is optional.


Example
--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

Note

SalesChannelDefDO is deprecated since version 2.17 and removed since version 3.0.

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.

Example
--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.

Optional

This configuration is optional.
Example
--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.

Example
--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

Optional

This configuration is optional.

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

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

2.3.2.2 FinanceController2PaymentDefDO

Optional

This configuration is optional.

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

Example
--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

Optional

This configuration is optional.

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

Example
--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.

Optional

This configuration is optional.
Example
--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.

Note

Mandatory Rules

All rules that are not referenced and mandatory will be executed asynchronously.

Recommended Validations

Syncronous validations that are recommended:

Asynchronous validations that are recommended:

  • Check if article-ids are known within the application
  • Set addition to the order if required
  • Validation of delivery address
  • Validation of billing address

Reference to Guide - IOM Shop Onboarding (2.9 - 2.17)#OrderValidationRuleDefDO.id = 1 to enable the checks for existing values that are referenced in ShopDO.shopOrderValidationRef.

If enabled, use the highest priority for this shop validation rule and the same value for synchronicity.

Example
--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.

Note

Mandatory Validations Rules

A set of mandatory validations rules must be configured. Please see mandatory rules of the table OrderValidationRuleDefDO in Reference - IOM Database Documentation.

Note

The rule with id = 1 maintains the reference to the rule that is configured in ShopDO.shopOrderValidationRef (a rule of Guide - IOM Shop Onboarding (2.9 - 2.17)#ShopOrderValidationDO ). Use it to enable the rule set.

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

Optional

This configuration is optional.

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.

Example
--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

Optional

This configuration is optional.

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

Example
--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

Optional

This configuration is optional.

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.

Example
--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

Optional

This configuration is optional.

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.

Example
--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.

Note

Regarding this table, the following has to be considered:

  • As mentioned in Guide - IOM Shop Onboarding (2.9 - 2.17)#Prerequisite, a supplier must exist for the following tasks.
  • A mapping of all shops to the internal supplier (id = 1) is required for IOM internal processes.
  • A unique constraint ensures that the relationship of a specific shop (property shopRef) to a specific supplier (property supplierRef) only occurs once.
    Another
    unique constraint ensures that for a specific shop (property shopRef), the shop supplier name (property shopSupplierName) only occurs once. 
    Still another unique constraint ensures that for a specific supplier (property supplierRef) the supplier shop name (property supplierShopName) only occurs once.
     


Example
--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.

Example
--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.

Note

Since IOM 2.14

The supplier evaluation rule to support cash on delivery is optional (OrderSupplierEvaluationRuleDefDO id=7). Also see Guide - IOM 2.14 Migration of Business Configuration.

2.5.2 Carrier

A carrier is a company (e.g., DHL, Hermes) that transports products or services for example from:

  • The fulfillment center to the consumer to deliver the ordered products
  • The consumer back to the fulfillment center in case of returns
  • The client to the storage of the fulfillment center
  • The fulfillment center back to the client in case of return surplus of stock.

Normally the carrier and the fulfillment center are under contract.


2.5.2.1 CarrierDO

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

Note

A carrier with the id=1 has a special meaning:
If defined, it will be considered as "unknown carrier".

When a shop order comes in with an unknown shipping method, this can be mapped to the "unknown carrier".
To activate that mapping, the carrier with id=1 must be registered in the table "Shop2CarrierDO".

Without the mapping, the SOAP API ignores unkown carriers without any message.

Since introduction of the order REST API orders with unknown carriers will be refused, unless this mapping is set.

Example
--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

Optional

This configuration is optional.

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

Note

Consider the "unknown carrier mapping" described in "CarrierDO"
Example
--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

Optional

This configuration is optional.

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

Example
--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

Optional

This configuration is optional.

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

Example
--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.

Best practice: At least configure the return type RecallReturn and Inversion.

Example
--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

Optional

This configuration is optional.

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

Example
--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

Optional

This configuration is optional.

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

Example
--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

Optional

This configuration is optional.

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

Example
--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.

Example
--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

Optional

This configuration is optional.

It can be used if the property sendOrderCoupon of Shop2Supplier is true.

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

Example
--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.

Example
-- 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

Note

Not an event

As this kind of e-mail is triggered by user interaction in the OMT, it must not be registered as an event. Also see IOM Customer E-mails - Possible Processes.

2.8 Predefined Custom Properties Configurations

Optional

This configuration is optional.

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.

4.1.1 Possible Processes for Invoicing Events

The following list is showing all processes where the creation of an invoice can be useful.

Please see Overview - IOM Database Documentation for all processes (ProcessesDO) and all invoicing types (InvoicingTypeDefDO) that are supported by the application by default.

ProcessDescriptionInvoicing Type
CheckOrderQueueCreate invoice at order receivedInvoice
PrepareOrderResponseQueue  Create invoice if order is approved
CheckDispatchQueueCreate invoice at dispatch received
CloseDispatchQueueCreate invoice if dispatch is successfully processed
CheckReturnQueueCreate invoice at return receivedCredit Note
CloseReturnQueueCreate invoice if return is successfully processed

4.1.2 Event Configuration

The invoice creation is an event that must be configured. By default, after the initial setup of IOM, there is no configuration that uses invoicing events. The following list shows the major steps of how to configure invoicing events and properties to enable a customized invoicing event.

  1. In the Event Registry Configuration define a listener that will act each time the business process event occurs.
    The event listener has to be of type InvoicingEventManager (INVOICING_EVENT_MANAGER), which will listen especially for invoicing events only.
  2. The Invoicing Event Registry Configuration defines which type of invoice should be created and which decision bean should be executed, i.e., no invoice for customers with invoice aggregation.
  3. The InvoiceNo Configuration defines the number range to use for invoice and credit note number generation.

4.1.2.1 EventRegistryEntryDO

This table defines event listeners for a selected process and a selected shop. The type of event defines the handler for this event. Here INVOICING_EVENT_MANAGER.

Please see Overview - IOM Database Documentation for all processes (ProcessDefDO) and all events handlers (EventDefDO) that are supported by the application by default.

Example
--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'
);

4.1.2.2 InvoicingEventRegistryEntryDO

This table defines the type of invoicing event (here create an invoice), payment method, type of invoice (here invoice) and a decision bean.

Please see Overview - IOM Database Documentation for all invoice events (InvoicingEventDefDO), all invoice types (InvoicingTypeDefDO), all decision beans (DecisionBeanDefDO) and all payment methods (PaymentDefDO) that are supported by the application by default.

Example
--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
);

4.1.2.3 InvoicingNoConfigDO

This table defines the range of numbers that are used for documents like invoices or credit notes.
The field "maxNotAllocatedInvoiceNo" defines the count of invoice numbers to be generated in advance to guarantee a gapless use. Make sure that enough invoice numbers are pre-generated for high load scenarios.

Please see Overview - IOM Database Documentation for all number generators (NumberRangeFormatterDefDO) and all invoicing types (InvoicingTypeDefDO) that are supported by the application by default.

Example
--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
);

Info

The following sql statement helps visualize all configured invoicing events:

sql
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

4.1.3 Document Creation Configuration

Creation of documents for a sending partner and a receiving partner. The receiving partner is NULL in this case, because it is an unknown customer.

4.1.3.1 CommunicationPartnerDO

The table defines relations between two communication partners between which a transmission should be executed.

Example
--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.1.3.2 DecisionBeanDefDO

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

4.2 Payment Events

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

4.2.1 Possible Processes for Payment Events

The following list shows all processes where the creation of a payment event can be useful.

Please see Overview - IOM Database Documentation for all processes (ProcessesDO) and all payment methods (PaymentDefDO) that are supported by the application by default.

ProcessDescriptionPayment Action
CloseInvoicingQueueCapture/refund if invoice/credit note is successfully createdCapture or Refund
CheckOrderQueueCapture at order receivedCapture
PrepareOrderResponseQueue Capture if order is approved
CheckDispatchCapture at dispatch received
CloseDispatchCapture if dispatch is successfully processed
CheckReturnQueueCreate refund at return receivedRefund
CloseReturnQueueCreate refund if return is successfully processed

4.2.2 Event Configuration

A payment action is a event that must be configured. By default, after the initial setup of IOM, there is no configuration that uses payment events. The following list shows the major steps of how to configure payment events and properties to enable a customized payment event. 

  1. In the Event Registry Configuration define a listener that will act each time the business process event occurs.
    The event listener has to be of type PaymentEventManager (PAYMENT_EVENT_MANAGER), which will listen especially for payment events only.
  2. The Payment Event Registry Configuration defines which type of action (authorization, capture, refund) should be executed for a specific payment method and which decision bean should be executed.
  3. Payment Approval Configuration
  4. Communication and Partner Configuration

4.2.2.1 EventRegistryEntryDO

This table defines event listeners for a selected process and a selected shop. The type of event defines the handler for this event. Here PAYMENT_EVENT_MANAGER.

Please see Overview - IOM Database Documentation for all processes (ProcessDefDO) and all events handlers (EventDefDO) that are supported by the application by default.

Example
--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'
);

4.2.2.2 PaymentEventRegistryEntryDO

This table defines the type of invoicing event (here create an invoice), payment method, type of invoice (here invoice) and a decision bean.

Please see Overview - IOM Database Documentation for all payment (InvoicingEventDefDO), all invoice types (InvoicingTypeDefDO), all decision beans (DecisionBeanDefDO) and all payment methods (PaymentDefDO) that are supported by the application by default.

Example
--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
);

Info

The following sql statement helps visualize all configured payment events:

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

4.2.3 Payment Approval

The payment approval configuration defines if a payment method in combination with a specific payment provider requires a manual approval and/ or a transmission of the payment notification.

4.2.3.1 PaymentActionApprovalDefDO

The table defines a list of payment action approvals that should be used by a shop.
Therefore a relation of shop, payment provider and payment method (see Shop2PaymentProvider2PaymentDefDO) is linked to payment actions an approval should be processed, e.g., for authorization.

Example
--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 );

4.2.4 Payment Notifications

The payment notification configuration defines a set of information that should be used to create/ send payment notifications to external applications (message consumers).

4.2.4.1 CommunicationDO

The table defines possible relations of communication properties which are send in various formats to extenal applications.

Example
--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
);

4.2.4.2 CommunicationPartnerDO

The table defines relations between two communication partners between which a transmission should be executed.

Example
--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.

4.3.1 Possible Processes for E-mail Events

See Processes for E-mail Events for business processes where the sending of a customer e-mail can be useful.

The following example shows the configuration of a customer e-mail after an order was received initially (CheckOrderQueue).

4.3.2 Event Configuration

The e-mail creation and sending is a event that must be configured. By default, after the initial setup of IOM, there is no configuration that uses e-mail events. The following list shows the major steps of how to configure customer e-mail events and properties to enable a customized e-mail event. 

  1. In the Event Registry Configuration define a listener that will act each time the business process event occurs.
    The event listener has to be of type MailEventManager (MAIL_EVENT_MANAGER), which will listen especially for mail events only.
  2. The MailEvent Registry Configuration defines which type of e-mail should be send depending on the transmission type and which decision bean should be executed.
  3. The Communication Partner Configuration defines the execution bean and the transmission type to use on the basis of CommunictaionDO indirectly.
  4. The Execution Bean Value Configuration defines a set of parameters that are used within the e-mail creation. This includes the sender's email address, the sender's name as well as the template names for subject, email content and more. The registered Mail Template Locations will be referenced here for the selected type of e-mail, i.e., orderSubject.vm and orderMessage.vm for the processed order. This configurations has to be linked to a Communication Partner exclusively, a shop in this case.

4.3.2.1 EventRegistryEntryDO

This table defines event listeners for a selected process and a selected shop. The type of event defines the handler for this event. Here MAIL_EVENT_MANAGER.

Please see Overview - IOM Database Documentation for all processes (ProcessDefDO) and all events handlers (EventDefDO) that are supported by the application by default.

Example
--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'
);

4.3.2.2 MailEventRegistryEntryDO

This table defines the type of mail event (here create an invoice), type of transmission (here sendCustomerMailOrder) and a decision bean(here sendEmailDeciderBean).

For decision bean only SEND_EMAIL_DECIDER_BEAN (id = 50) is available by default. For mail event handlers only SEND_SHOP_CUSTOMER_MAIL_PC (id = 1) is available by default. All transmission types with prefix SEND_CUSTOMER_MAIL_ of TransmissionTypeDefDO can be used. Please see Overview - IOM Database Documentation for all transmission types (TransmissionTypeDefDO) that are supported by the application by default.

Example
--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
);

4.3.2.3 CommunicationPartnerDO

The table defines relations between two communication partners between which a transmission should be executed.

Example
--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
);

4.3.2.4 ExecutionBeanValueDO

Please see Reference - IOM Customer E-mails for all keys that are available for customer e-mails.

Example
--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.


Disclaimer

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

Customer Support
Knowledge Base
Product Resources
Support Tickets