Document Properties
Kbid
29X666
Last Modified
01-Aug-2023
Added to KB
20-Oct-2020
Public Access
Everyone
Status
Online
Doc Type
Guidelines
Product
  • IOM 3.0
  • IOM 3.1
  • IOM 3.2
  • IOM 3.3
  • IOM 3.4
  • IOM 3.5
  • IOM 3.6
  • IOM 3.7
  • IOM 4.0
  • IOM 4.1
  • IOM 4.2
  • IOM 4.3
  • IOM 4.4
  • IOM 4.5
  • IOM 4.6
  • IOM 4.7
  • IOM 5.0
Guide - IOM Shop Onboarding

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.

Glossary

Term

Description

B2B

Business to Business

B2C

Business to Consumer

COD

Cash on Delivery

DefDO

Persistence entities which contain a set of predefined values. They are referred as "Enumeration Tables" within the IOM Database Documentation.

DefRef

A foreign-key relation from one referencing database table column to another database relation, usually to a DefDO.

DO

Data Object - used as persistence entities to represent stored values in the database

DOSE

Dynamic Order Supplier Evaluation, a process of IOM that evaluates one or more suppliers for an order.
See OrderSupplierEvaluationRuleDefDO for validation rules and Guide - IOM Shop Onboarding#OrderOptimizeDefDO for possible optimizations.

IOM

The abbreviation for Intershop Order Management

ID

Identifier

OMS

The abbreviation for Order Management System, the technical name of IOM

OMT

The abbreviation for Order Management Tool, the graphical management tool of the IOM

PSP

Payment Service Provider

SQL

Structured Query Language

URL

Uniform Resource Locator

References

Prerequisites

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

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

Post Task

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

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.

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#ShopDO (optional) and Guide - IOM Shop Onboarding#ShopOrderValidationDO configurations are required first.

Basic Shop Configuration

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#Shop2OrderValidationRuleDefDO.

References

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

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

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 references to:

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",
	"shippingCountryTaxMapping" /* since 3.4 */
)
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,
	true	 --no preconfigured taxes, use tax-types as given by the order
);

OrderOptimizeDefDO

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

Shop-Related Configuration

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

Taxes

Taxes are defined through a type , e.g. "full tax", a rate, a location and a validity range.

Prior to 3.4

The tax has to be configured before an order will be accepted containing a tax.

Since 3.4

New tax-types can be created on the fly without pre-configuration.
See Public Release Note - Intershop Order Management 3.4#EnhancementsofTaxes and Reference - IOM REST API - Order 2.1.

Please also have a look at Concept - IOM Taxes.

For predefined values or details about persisted tax configuration please refer to Overview - IOM Database Documentation.

TaxTypeDefDO

The list of tax types, with their default name. Note that these types are not geo-located. This is basically just a list of names.

Prior to 3.4

TaxTypeDefDO is a fix list of types that could not be expanded.

Since 3.4

Predefined types can be added. This is required if new types should be mapped to different tax names per shop (please also see Shop2TaxTypeDefDO).

Example

-- add a new tax type
INSERT INTO "TaxTypeDefDO"
(
	id, description, "taxType"
)
SELECT nextval('"TaxTypeDefDO_id_seq"'), 'ecological tax', 'ENVIRONMENTAL';

Shop2TaxTypeDefDO

The table defines assignments and aliases to the taxType of TaxTypeDefDO (at max one alias per shop and type).

There is a fallback on the taxTypeDefDO internal names, hence this table's only usage is to provide alternate tax names. Only one name per shop and taxName is allowed.

These alias can then be used in incoming APIs, and are always used in outgoing API. Also see Overview - Intershop Order Management REST API and Reference - IOM SOAP Web Services.

Example

--assign major tax type to a shop
INSERT INTO "Shop2TaxTypeDefDO"
(
	id, "shopTaxTypeName", "taxTypeDefRef", "shopRef", "modificationDate"
)
SELECT nextval('oms."Shop2TaxTypeDefDO_id_seq"'), 'medioambiental', id, 17, now()
FROM "TaxTypeDefDO" WHERE "taxType" = 'ENVIRONMENTAL';

TaxDO

The table contains the effective rates per location for the tax types and their dates of validity. Common rates are already predefined for some countries, but their correctness should be verified and possibly missing ones should be added.

The table definition has been changed with IOM 3.4.

See Guide - IOM 3.4 Migration for Tax Enhancements.

Prior to 3.4

The tax location can only be a country, it is either the shop's country, or the country of the delivery address.

All attributes are required and an incoming order will be refused if the included taxes cannot be mapped to an existing, preconfigured entry of TaxDO.

See Overview - IOM Database Documentation.

Example

--add a tax definition for a country and type
--note: 'tax' = the tax-rate in percentage, e.g. 17.5 for 17.5%
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'
);

Since 3.4

Predefined entries with a validity range are still required when submitting an order that contain taxes without range. Please also see ShopDO.shippingCountryTaxMapping of Overview - IOM Database Documentation)

Deprecated since 3.4

countryDefRef is deprecated, use location instead which accepts any string.

When the location is a country it is recommended to use it's ISO-3-code.

It can be useful to set a validity range a before to handle rate changes and to help select concerned orders.

Example

--add a tax definition for a location and type
--note: 'tax' = the tax-rate in percentage, e.g. 17.5 for 17.5%
INSERT INTO "TaxDO"
(
	id, location, "tax", "taxTypeDefRef", "validFrom", "validUntil"
)
SELECT nextval('oms."TaxDO_id_seq"'), 'USA', 17.5, id, '2012-01-01 00:00:00', '2099-12-31 23:59:59'
FROM "TaxTypeDefDO" WHERE "taxType" = 'ENVIRONMENTAL';

Charges

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

Shop2ChargeTypeDefDO

This configuration is optional.

The table defines the types of charges that are used by a shop with a custom name. If no custom naming required, this table must not be used.

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

ChargeTypeDefDO

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

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.

Shop2CountryDefDO

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

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.

Payment and Debtors

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

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 provides merchants with 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.

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

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.

PaymentProviderDO

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

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

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

Debtor Management

A debtor management system hosts and controls payments from customers.

FinanceControllerDO

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

FinanceController2PaymentDefDO

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

FinanceController2TaxTypeDefDO

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

Shop2FinanceControllerDO

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

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

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.

Order Validation

When an order is announced (or created) in 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.

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#Order Validation.

Mandatory Rules

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

Recommended Validations

Synchronous 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#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
);

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 refer to Overview - IOM Database Documentation. Also see introduction: Guide - IOM Shop Onboarding#Order Validation.

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.

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

Order Approval

After an order is announced (or created) in 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.

Shop2Supplier2ApprovalTypeDefDO

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

ApprovalTypeDefDO

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

Order Creation Responses

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

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

Shop2ResponseStateCodeDefDO

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

ResponseStateCodeDefDO

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

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

Shop2OrderStatesDefDO

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 Order-state REST API or OrderState-webservice (deprecated). See Overview - Intershop Order Management REST API.

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

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.

Shop2OrderPosStatesDefDO

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 Order State REST API or OrderState-webservice (deprecated). See Overview - Intershop Order Management REST API.

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

OrderPosStatesDefDO

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

Supplier, Carrier, and Delivery

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

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.

Connected with 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 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. The selected suppliers receive a request that indicates whether the delivery can be fulfilled or not.

Shop2SupplierDO

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

Regarding this table, the following has to be considered:

  • As mentioned in the Guide - IOM Shop Onboarding#Prerequisite section, 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. 

The column allowParentStock to determine hierarchical stock usage has been added with IOM 4.6.0. 

see Concept - IOM Hierarchical Stocks Visibility

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", "allowParentStock"
 )
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, FALSE
);

--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", "allowParentStock"
)
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, FALSE
);

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

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 refer to Overview - IOM Database Documentation.

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.

Carrier

CarrierDO

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

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 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 Order SOAP API ignores unkown carriers w/o 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
);

Shop2CarrierDO

This configuration is optional.

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

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

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.

Shop2DeliveryFormDefDO

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

DeliveryFormDefDO

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

Shop2DeliveryOptionDefDO

This configuration is optional.

The table defines the delivery options that should be used for a shop. They will replace the default delivery options of 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
);

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.

Order Return-Related Configurations

In the scope of IOM, a return will be linked with the previous order. A return can be announced to IOM and the supplier before sending, but it can also be registered directly if the return was received by the supplier. Also see section Guide - IOM Shop Onboarding#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.

Return Types

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

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

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.

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.

Shop2ReturnReasonDefDO

This configuration is optional.

The table defines the return reasons that should be used for a shop. They will replace the return reasons of 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
);

ReturnReasonDefDO

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

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.

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 namings of the shop.

Shop2ReturnStatesDefDO

This configuration is optional.

The table defines the return states that should be used for a shop which replaces 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
);

ReturnStatesDefDO

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

Return Approval

A return approval can be the precondition before a return of an order back to the supplier can be processed. Therefore the RMA REST API can be used to approve or decline a return request. See Overview - Intershop Order Management REST API for more information about the RMA REST API.

Shop2ReturnReason2ApprovalStateCodeReasonDefDO

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

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.

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.

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.

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

Shop2ReductionUnitDefDO

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. They replace the reduction units of 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
);

ReductionUnitDefDO

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

Feature-Related Configurations

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.

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

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

Possible Processes

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.

Predefined Custom Properties Configurations

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, refer to Overview - IOM Custom Properties.

Product Import

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 describes files and configuration steps for the product import.

Business Events

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

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.

Possible Processes for Invoicing Events

The creation of an invoice or credit note can be attached to a business process (event). The following list shows all processes where the creation of an invoice can be useful.

Please refer to Overview - IOM Database Documentation for all processes (ProcessDO) and all invoicing types (TransmissonTypeDefDO) that are supported by the application by default.

Type

Process

Description

Invoice

CheckOrderQueue

Create invoice at order received

PrepareOrderResponseQueue  

Create invoice if order is approved

CheckDispatchQueue

Create invoice at dispatch received

CloseDispatchQueue

Create invoice if dispatch is successfully processed

Credit Note

CheckReturnQueue

Create invoice at return received

CloseReturnQueue

Create invoice if return is successfully processed

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

EventRegistryEntryDO

This table defines event listeners for a selected process and a selected shop. The type of event defines the handler for this event. In this case 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'),
	{{shopref}}, 3, 'Invoicing Events on CheckOrder'
);

InvoicingEventRegistryEntryDO

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

Please refer to 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
);

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(), {{shopref}}, 1
);

Note

The following SQL statement helps to 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

Document Creation Configuration

Creation of documents for a sending partner and a receiving partner. The receiving partner is NULL.

CommunicationPartnerDO

The table defines relations between two communication partners between which a transmission is to 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" = {{shopref}}), null
); 

DecisionBeanDefDO

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

DocumentTransformerConfigDO

Configure which mapper should be used for document format and document type.

-- Configure which mapper should be used for document format and document type.

-- DocumentTransformerConfigDO
FOREACH documentType IN ARRAY array[17, 18, 19] -- DocumentTypeDefDO: INVOICE_CREDIT_NOTE, INVOICE_NOTE, CREDIT_NOTE
LOOP
    IF NOT EXISTS (SELECT * FROM "DocumentTransformerConfigDO" 
                    WHERE "shopRef" = {{shopref}}
                    AND "documentFormatDefRef" = 1 -- DocumentFormatDefDO.PDF
                    AND "documentMapperDefRef" = 3 -- DocumentMapperDefDO.INVOICE_DOCUMENT_MAPPER_BEAN_V2
                    AND "documentTypeDefRef" = documentType)
    THEN
        INSERT INTO "DocumentTransformerConfigDO"(
			id, "documentFormatDefRef", "documentMapperDefRef", "documentTypeDefRef", "shopRef",
			"transformerFrameworkDefRef", save)
        SELECT
			nextval('"DocumentTransformerConfigDO_id_seq"'), 1, 2, documentType, {{shopref}},
			2, true;
    END IF;
END LOOP;

Payment Events

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

Possible Processes for Payment Events

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

Please refer to 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

Event Configuration

A payment action is an 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 the type PaymentEventManager (PAYMENT_EVENT_MANAGER), which listens 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

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 refer to Overview - IOM Database Documentation for all processes (ProcessDefDO) and all event 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'
);

PaymentEventRegistryEntryDO

This table defines the type of invoicing event (in this case create an invoice), payment method, type of invoice (in this case 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 help to visualize all configured payment events:

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


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.

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

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

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

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

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.

Possible Processes for E-mail Events

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

Event Configuration

The e-mail creation and sending is an 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 listens 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 e-mail address, the sender's name as well as the template names for subject, e-mail 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.

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

MailEventRegistryEntryDO

This table defines the type of mail event (in this case 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 refer to 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
);

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

ExecutionBeanValueDO

Please refer to 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
	)
);

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