Document Properties
Kbid28C769
Last Modified22-Jun-2020
Added to KB05-Oct-2018
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • IOM 2.9
  • IOM 2.15

Guide - IOM Supplier Onboarding

1 Introduction

This guide describes how to add a supplier to an existing IOM shop instance. It is addressed to IOM operators (e.g., an IOM administrator who has access to the whole system).

A questionnaire guides the target group to collect the necessary information in the run of the supplier configuration.

The guide does not cover any kind of supplier approval processes. So there is information of the following configuration tables in this document: 

  • Supplier2ApprovalStateCodeDefDO
  • Supplier2ApprovalStateCodeReasonDefDO
  • Shop2Supplier2ApprovalTypeDefDO

IOM Supplier Onboarding

1.1 Glossary

Term
Description
CODCash on delivery
DOData Object - used as persistence entities to represent stored values in the database
DOSEDynamic Order Supplier Evaluation
EOLEnd Of Life - the sale or support of goods and services is terminated
IOMThe abbreviation for Intershop Order Management
OMSThe abbreviation for Order Management System, the technical name of IOM
OMTThe abbreviation for Order Management Tool, the graphical management tool of the IOM
RMAReturn Merchandise Authorization / Return Material Authorization

1.2 References

1.3 Prerequisite

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

An essential parameter for the supplier configuration is the OMS internal ID of the OMS shop instance to which the new supplier should be connected. From now on this ID will be identified by <supplierid> and <shopid>.

1.4 Post Task

Note

After finishing the configuration a cache clear is required on all application servers. See Concept - IOM Synchronization of Java-based Caches, IOM REST API - Cache Statuses.

2 Questionnaire


QuestionRelates to

Does the supplier support order responses?

Does the supplier use the OMS ShopService to submit response messages?

Does the supplier use the OMS ShopService to submit dispatch messages (delivery notifications)?
Does the supplier use the OMS ReturnService to submit return messages?
Does the retailer/shop use the supplier for drop shipment?
  • Configure SupplierDO.supplierTypeDefRef
  • Configure Shop2SupplierDO.isDropShipment
Does the retailer/shop allow the splitting of an order into multiple shipments?
  • Configure Shop2SupplierDO.splitShipmentAllowed
Does the supplier support the payment method COD in relation to the retailer/shop?
  • Configure Shop2SupplierDO.supplierSupportsCOD

Does the shop system use the OMS feature to select a supplier with the order submission (shop system to OMS)?

If TRUE, Shop2SupplierDO.shopSupplierName has to be agreed with the shop system.

  • Configure Shop2SupplierDO.shopSupplierName

Which return reasons does the supplier use?

Does the supplier use own identifiers/names for return reasons in the communication with the OMS?

Does the shop/retailer support an RMA process?

If TRUE:

  • Should the OMS create RMA numbers for the supplier?
  • Is the RMA number a fix value for the supplier?

Which reduction reasons (name/identifier) does the retailer/shop use?

Which reduction reasons (name/identifier) does the supplier use?

What is the mapping of the reduction reasons between retailer/shop and supplier?

Should the inventory of a product be set to 0 if a product is no longer included in the import data files?

Note

This requires that the Shop2SupplierDO.checkMissingInLastDatapack at the product import configuration is set to TRUE.
  • Configure Shop2SupplierDO.resetStockOnImport
If the order includes coupons, should these be transmitted to the supplier?
  • Configure Shop2SupplierDO.sendOrderCoupon

3 Configuration

The following section describes how to add a new supplier to an existing shop instance.

3.1 Create a Supplier Instance

3.1.1 Basic Supplier Configuration

3.1.1.1 SupplierDO

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

For all available values please see Overview - IOM Database Documentation.

Example
-- create a supplier instance
INSERT INTO oms."SupplierDO"
(
	"id", "active", "contentSupplier", "countryCodeDefRef", "countryDefRef", 
	"cutOffTime", "deliveringSupplier", "legal", "modificationDate", 
	"name", "supplierName", "supportsReservation", "supportsResponse", 
	"singlePositionArticle", "internalSupplierName", "parentSupplierRef", 
	"cleanParentOnImport", "ignoreAdditionalPositions",
	"businessObjectProcessingDelay", "supplierTypeDefRef"
)
VALUES
(
	5000, TRUE, FALSE, 1, 29, 
	'14:30', TRUE, TRUE, now(), 
	'Flagship store - North', 'Store - North', FALSE, FALSE, 
	TRUE, 'warehouse_north', null, 
	TRUE, TRUE, 
	'15m', 2
);

3.1.1.2 SupplierContactDO

Optional

This configuration is optional.

Note

This table is deprecated.

3.1.1.3 Shop2SupplierDO

The table defines the suppliers that are used by a shop. It defines the relation between a shop and a supplier. See Guide - IOM Shop Onboarding - Supplier for detailed configuration.

3.2 Supplier-related Configuration

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

3.2.1 Taxes

Taxes are essential to a business model.

3.2.1.1 Supplier2TaxTypeDefDO

Optional

This configuration is optional.

Use the table to configure if the supplier insists on its own values for the taxes. If nothing is configured, the IOM internal values are used. It is used by Order Placement - IOM to supplier.

Note

In order to produce a complete match between the shop and the supplier, it is important to know which tax types the OMS shop instance uses.

SELECT "taxTypeDefRef" FROM oms."Shop2TaxTypeDefDO" WHERE "shopRef" = <shopId>

If there is nothing configured for the related shop instance, you have to find out which OMS internal tax types are used by the shop.

Example
-- assign a tax type
INSERT INTO oms."Supplier2TaxTypeDefDO"
(
	"id", "supplierTaxTypeName", "taxTypeDefRef", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2TaxTypeDefDO_id_seq"'), 'FULL-TAX', 5, 5000
);

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

3.2.2 Country and Currency

In general a supplier is located at a country which also determines the currency.

3.2.2.1 Supplier2CountryDefDO

Use the table to configure if the supplier insists on its own values for countries. It is used by Order Placement - OMS to supplier.

Note

In order to produce a complete match between the shop and the supplier, it is important to know which countries are used by the shop.

SELECT "countryDefRef" FROM oms."Shop2CountryDefDO" WHERE "shopRef" = <shopid>

If there is nothing configured for the related OMS shop instance, you have to find out which IOM internal countries are used by the shop.


Example
-- assign a country
INSERT INTO oms."Supplier2CountryDefDO"
(
	"id", "countryDefRef", "supplierCountryName", "supplierCurrencyName", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2CountryDefDO_id_seq"'), 9, 'BELGIUM', 'EURO', 5000
);

3.2.2.2 CountryDefDO

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

3.2.3 Sales Channels

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

3.2.3.1 Supplier2SalesChannelDefDO

Optional

This configuration is optional.

Use the table to configure if the shop uses different sales channels and the supplier requires this information for fulfillment. The configuration is used by Order Placement.

Example
-- assign a sales channel
INSERT INTO oms."Supplier2SalesChannelDefDO"
(
	"id", "salesChannelDefRef", "supplierSalesChannelName", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2SalesChannelDefDO_id_seq"'), 1, 'SALE', 5000
);

3.2.3.2 SalesChannelDefDO

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

3.3 Payment

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

3.3.1 Supplier2PaymentDefDO

Optional

This configuration is optional.

Use the table to configure if the supplier insists on its own values for payment methods. Otherwise the property PaymentDefDO.name is used. The configuration is used by Order Placement IOM to supplier (XML element "Sales" > attribute "method").

Example
-- assign a payment
INSERT INTO oms."Supplier2PaymentDefDO"
(
	"id", "paymentDefRef", "supplierPaymentName", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2PaymentDefDO_id_seq"'), 10, 'PP', 5000
);

3.3.1.1 PaymentDefDO

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

3.4 Carrier and Delivery

A carrier is a company that transports products or services.

The delivery therefore defines forms (i.e., standard) and options (i.e., night shipping) the transport has to fulfill.

3.4.1 Supplier2CarrierDO

Optional

This configuration is optional.

Use the table to configure if the supplier insists on its own values for the carrier. Otherwise the property CarrierDO.name is to be used. Please see Guide - IOM Shop Onboarding - Carrier for CarrierDO.

The configuration is used by SOAP ShopService method storeDispatch. See Dispatch transmission.

Example
-- assign a carrier
INSERT INTO oms."Supplier2CarrierDO"
(
	"id", "supplierCarrierName", "carrierRef", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2CarrierDO_id_seq"'), 'DHL', 11, 5000
);

3.4.2 Supplier2DeliveryFormDefDO

Optional

This configuration is optional.

This configuration contains the name of a delivery form, as used by the supplier, with reference to the IOM internal delivery form. There is no usage by the IOM itself, but it can be useful for customization.

Example
-- assign a delivery form
INSERT INTO oms."Supplier2DeliveryFormDefDO"
(
	"id", "deliveryFormDefRef", "supplierDeliveryFormName", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2DeliveryFormDefDO_id_seq"'), 20, 'FF', 5000
);

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

3.4.4 Supplier2DeliveryOptionDefDO

Optional

This configuration is optional.

This configuration contains the names of delivery options, as used by the supplier, with reference to the IOM internal delivery options. It is used by Order Placement - IOM to supplier (XML attribute name at element OrderPos > DeliveryOption)

Example
-- assign a delivery option
INSERT INTO oms."Supplier2DeliveryOptionDefDO"
(
	"id", "deliveryOptionDefRef", "supplierDeliveryOptionName", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2DeliveryOptionDefDO_id_seq"'), 8, 'OVERNIGHT', 5000
);

3.4.5 DeliveryOptionDefDO

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

3.4.6 Supplier2DeliveryTypeDefDO

Optional

This configuration is optional.

Note

This table is deprecated.

3.4.7 DeliveryTypeDefDO

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

3.5 Supplier Responses

After the IOM is sending a delivery request to a supplier, the supplier responses with a message. This message contains if the supplier agrees (or partially agrees or disagrees completely) to deliver the requested products including its conditions (i.e., prices).

3.5.1 Supplier2ResponseTypeDefDO

Optional

This configuration is optional.

Note

This table is deprecated.

3.5.2 Supplier2ResponseStateCodeDefDO

Optional

This configuration is optional.

The table is relevant if the supplier supports order responses and if the supplier insists on its own values for response state codes. Otherwise the property name from table ResponseStateCodeDefDO is to be used.

It is used by Response Transmission.

Example
-- assign a response state code
INSERT INTO oms."Supplier2ResponseStateCodeDefDO"
(
	"id", "responseStateCodeDefRef", "supplierResponseStateCodeName", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2ResponseStateCodeDefDO_id_seq"'), 1, 'OK', 5000
);

3.5.2.1 ResponseStateCodeDefDO

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

3.6 Returns

If a customer returns products that were delivered to the customer before, the products will arrive in a package at a supplier. The supplier will note this to the IOM using a return message.

The process of:

  • requesting requesting
  • approving requests
  • sending products
  • receiving products
  • and noting an arrival of returned products

requires several configurations of the supplier. Business processes are not mentioned here.

3.6.1 Supplier2ReturnTypeDefDO

The table contains the return types that should be supported by a supplier. It is used by the configuration table SupplierReturnAddressDO, the SOAP ReverseService method returnSlipRequestOMS and returnSlipRequest. Also see Reference - IOM SOAP Web Services.

Best practice: At least configure the return type Recall, Return and Inversion.

Using the column rmaNo will return this static rma-number in web services.

Using the columns rmaCode*, interval, startDate, minEndDate and ejbLookup, supplier-specific rma-numbers can be generated. A cookbook is in work and will be linked.For more information and all available return types see Overview - IOM Database Documentation.

Example
-- assign a return type
INSERT INTO oms."Supplier2ReturnTypeDefDO"
(
	"id", "returnTypeDefRef", "supplierReturnTypeName", "supplierRef", 
	"rmaNo", -- static rma number
	"preselected", "modificationDate",
	"rmaCodeCounter", "rmaCodeStart", "rmaCodeEnd", "interval", "startDate", "minEndDate", "ejbLookup" -- rma number generation
)
VALUES
(
	nextval('oms."Supplier2ReturnTypeDefDO_id_seq"'), 4, 'RET', 5000, 
	null,
	TRUE, now(),
	null, null, null, null, null, null, null
);

3.6.2 ReturnTypeDefDO

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

3.6.3 Supplier2ReturnReasonDefDO

Optional

This configuration is optional.

The table contains the return reasons supported by the supplier and can be used if the supplier does not use the default internal return reasons. Also see Return Transmission.

If not configured, all IOM internal return reasons are possible and displayed in a choice grouped by the return type at the OMT.

Note

You have to configure at least one return reason per configured return type.

Example
-- assign a return reason
INSERT INTO oms."Supplier2ReturnReasonDefDO"
(
	"id", "returnReasonDefRef", "supplierReturnReasonName", "supplierRef", "preselected"
)
VALUES
(
	nextval('oms."Supplier2ReturnReasonDefDO_id_seq"'), 307, 'WRONG_ITEM', 5000, FALSE
);

3.6.4 ReturnReasonDefDO

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

3.6.5 SupplierReturnAddressDO

The address specifies the location where a return shipment will be received.

It is used by the SOAP ReverseService method returnSlipRequest, return label creation and shop customer mails. See Reference - IOM SOAP Web Services, Overview - IOM Customer E-mails and also  Overview - IOM Database Documentation.

Note

For each configured return type (see Supplier2ReturnTypeDefDO) a return address has to be configured.


Example
-- assign a return address
INSERT INTO oms."SupplierReturnAddressDO"
(
	"id",
	"addressLine1", "addressLine2", "addressLine3", "addressLine4", "addressLine5",
	"supplier2ReturnTypeDefRef", "shop2SupplierRef"
)
VALUES
(
	nextval('oms."SupplierReturnAddressDO_id_seq"'),
	'Sports In Motion Warehouse', 'c/o Intershop Communications AG', 'Intershop Tower', '07740 Jena', 'Germany',
	10001, 15000
);

3.6.6 Supplier2ReductionUnitDefDO

Optional

This configuration is optional.

If the supplier insists on his own identifiers for reduction units, configure this table. Additionally, set the property sendOrderCoupon of related Shop2Supplier TRUE.

The configuration is used by the Order Placement - OMS to supplier (attribute value, key = "couponUnit" at XML element Property with id = "coupon" at position level) 

Example
-- assign a reduction unit
INSERT INTO oms."Supplier2ReductionUnitDefDO"
(
	"id", "reductionUnitDefRef", "supplierReductionUnitName", "supplierRef"
)
VALUES
(
	nextval('oms."Supplier2ReductionUnitDefDO_id_seq"'), 3, 'MO', 5000
);

3.6.7 ReductionUnitDefDO

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

3.6.8 Shop2Supplier2ReduceReasonDO

The table contains the reduce reasons for returns agreed between the shop and the supplier (return reduction matrix). At least one configuration is required per shop-supplier-relation (Shop2SupplierDO).

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

4 Product Import

The IOM needs to know about the products of the supplier which should be sold by a particular shop/retailer. The IOM needs a product import configuration and the relevant product data files from the supplier. The product import process, its files and configuration steps are described in a separate guide. See Guide - IOM Product Import.

5 Order Placement

The order transmission to the supplier takes place via an XML file on a default location. See Export Order for Order Placement of Reference - IOM ImpEx Interfaces describes the data format, file location and the configuration of the order placement.

Note

If you already have configured a partner referrer (oms." PartnerReferrerDO") for the supplier, you have to reuse this instance at the order placement configuration.

The partner referrer ID of the sending OMS shop instance is required for the configuration. Via the following SQL statement you can get this ID:

SELECT "id" FROM oms."PartnerReferrerDO" WHERE "shopRef" = <shopid>

6 Transmissions

6.1 Response Transmission

Optional

This is only relevant if the supplier supports order responses.

The SOAP ShopService method storeResponse establishes a synchronous communication channel of response messages from the supplier to the OMS. Alternatively, response messages can be created manually by using the OMT.

The supplier's Web service request must contain the credentials of a user account with the according permission Create receipt message to use the method storeResponse. This containing role must be assigned to the user account and the supplier you want to use for the SOAP message.

Note

You can use the same user account and role for response, dispatch, and return transmissions.

Some relevant notes to the storeResponse request:

  • Element User, property accountName (oms."UserDO") of the user account which is using this interface
  • Element Password, the password of the above mentioned user account
  • The XML element ShopSupplier must reference the related Shop2SupplierDO.supplierShopName

  • The XML element Supplier must reference the related SupplierDO.supplierName
  • The attribute name of the XML element Shop must reference the related Shop2SupplierDO.supplierShopName

For detailed information about this interface refer to Overview - IOM Interfaces and Reference - IOM Database Documentation.

6.2 Dispatch Transmission

The SOAP ShopService method storeDispatch establishes a synchronous communication channel for response messages from the supplier to the OMS. Alternatively, response messages can be created manually by using the OMT.

The supplier's Web service request must contain the credentials of a user account with the according permission Create delivery message to use the method storeDispatch. This containing role must be assigned to the user account and supplier you want to use for the SOAP message.

Note

You can use the same user account and role for response, dispatch, and return transmissions.

Some relevant notes to the storeDispatch request:

  • Element User, property accountName (oms."UserDO") of the user account which is using this interface
  • Element Password, the password of the above mentioned user account
  • The XML element ShopSupplier must reference the related Shop2SupplierDO.supplierShopName

  • The XML element Supplier must reference the related SupplierDO.supplierName
  • The attribute name of the XML element Shop must reference the related Shop2SupplierDO.supplierShopName

For detailed information about this interface please refer to Overview - IOM Interfaces and Reference - IOM Database Documentation.

6.3 Return Transmission

The SOAP ReturnService method storeReturn establishes a synchronous communication channel of response messages from the supplier to the OMS. Alternatively, response messages can be created manually by using the OMT.

The supplier's Web service request must contain the credentials of a user account with the according permission Create return message to use the method storeReturn. This containing role must be assigned to the user account and the supplier you want to use for the SOAP message.

Note

You can use the same user account for response, dispatch, and return transmissions.

Some relevant notes to the storeReturn request:

  • Element User, property accountName (oms."UserDO") of the user account which is using this interface
  • Element Password: the password of the above mentioned user account
    The XML element ShopSupplier must reference the related Shop2SupplierDO.supplierShopName
  • The XML element Supplier must reference the related SupplierDO.supplierName
  • The attribute name of the XML element Shop must reference the related Shop2SupplierDO.supplierShopName
  • The attribute name of the XML element Supplier should reference the related SupplierDO.supplierName

For detailed information about this interface please refer to Overview - IOM Interfaces and Reference - IOM Database Documentation.

7 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