This is an old article which is kept for the consistency of documentation pages.

This cookbook will show you how-to connect, transfer, update and sync your records between and SAP ByDesign.

Here is a common situation:

A company has numerous products with different variants to sell. They have their product list, description and details already inputted in SAP ByDesign business management software which is commonly called an enterprise resource planning (ERP) system.

This particular company has setup a shop system run on Sphere.IO which is an e-commerce platform-as-a-service (PaaS). They wish to sell their products and provide up-to-date information about the product availability, orders, payments and the deliveries.

Here is the solution plan:

For simplicity, we assume that this very promising company is just starting the business and has no previous customer records. To start it needs to:

  1. Export all the products and the variants from SAP ByDesign into shop. The system should be flexible to keep the information in sync so when any product related information is changed in ERP the shop system can react according.
  2. Keep the customer, order, payment and delivery information in sync in both systems. The shop system should be in sync with the available stock of products in the ERP so that a decision can be made to replenish the stock in time.

1. SAP ByDesign to

The data from the SAP ByDesign ERP system should be imported into the shop system and then kept in sync with the ERP system all the time. For simplicity we would assume that no customer data is available initially, so the only information the shop system will receive is the products.

The products themselves can have different fields in SAP ByDesign ERP which would be very specific to the type of business the company has. On the other hand some or more of the details in product description may not appear in the Shop system for various reasons. For example company keeps the names of suppliers in the same list but it is deemed irrelevant for the Shop system to display that.

... to be continued

2. Keeping both systems in sync

For this part of our cookbook we assume that all the product data between SAP ByDesign and the shop system running on is perfectly in sync. The Shop is open and the first customer wishes to buy a product.

Creating and Updating the Customer Data

Our strategy is to send the new customer data from into our SAP ByDesign ERP to create a new customer. This new customer needs to receive a permanent ID so that both systems would be able to identify him/her next time. Since ERP system is better suited to do our bookkeeping we better synchronise our new customer data based on the ID given by that system.

This ID from SAP ByDesign will be external for run Shop system, hence we can call it an external ID for simplicity. Next, our external ID needs to be reported back to run Shop system to identify this client for future transactions. The schematics below shows the process:

This is the logic behind now let us see how to do this using platform. To successfully connect and keep the customer data in synch between both systems we need to create two integration flows:

  • New Customer Data - this will collect data from Shop and report it to ERP system, then get the External ID from there and send this back to Shop.
  • Returning Customer Data - this will collect the returning customer data, assign already known External ID and send it to ERP system for the update.

To prevent multiple customer data creations - It is important to note that if the External ID is not used the system would not be able to identify the customer as returning and would generate multiple data for the same customer.

New Customer Data

Using integration flow designer we can create a flow which would look like this:

First we need to query the data from our shop system by simply using the - Query Customers trigger connector. This data needs to be mapped to the incoming fields of SAP ByDesign - Create Customer. When data gets mapped in SAP ByDesign it will receive an External ID which we will communicate back to shop for consistency and future use by using - Update Customer action connector. - Query Customers

Using Elastic.IO - Query Customers connector we can enquire all the new customer data from our shop system. The configuration of this connector might look like this:

After selecting the account we can proceed to apply a specific filter to get only those customers which have not External ID, meaning that they have not SAP By Design ID. Those would be all new customers. Here in the filter field we can write an expression like this: externalId is not defined. This filter would work not only for our first customer, but it would work also for every new customer which would get registered in our shop.

The new customer record which comes from consist of 41 fields which are capable of bringing the data from which only 12 of them are required. It is up-to us and our customer to populate them all. These records need to be mapped to the fields in SAP By Design ERP.

SAP ByDesign - Create Customer

To properly map and transfer our customer data from our shop into ERP we need to use SAP ByDesign - Create Customer connector. This connector can process and record information in more than 50 different fields but only 9 of them are required for proper operations at SAP By Design side.

Example Mapping

Both systems have plenty of fields that can be mapped and connected in order to transfer the information from into SAP By Design. Here we will present an example mapping with explanation on how and why this needs to be done. We cover all required fields, plus some commonly used optional fields which together provide better solution for this integration to run smoothly: SAP By Design ERP
Title AcademicTitle Code
Value ➡ {{results[*].title}}
This optional field can be used to map the Title value.
No input Account Debtor External ID (required)
Value ➡ unknown
The External ID is not defined at this stage so we can not link it yet. We assign a temporary unknown value to satisfy the requirements for SAP By Design system.
No input Account Determination Debtor Group Code (required)
Value ➡ 1234
In this case the situation is similar we get no value from our shop system due to the fact that our customer is new, however we can assign our new customer to become a member of the Debtor Group and have a special code for that to identify him afterwards in SAP. The 1234 is an arbitrary number for this explanation only. The idea behind of Debtor Group is when the new customer arrives she has not paid yet, hence she is in debt.
Address_company Address Care Of Name
Value ➡ {{results[*].addresses[*].company}} + Label
This optional field can be used to pass on the address of company where the customer works if it is given. If it is wished, some label also can be passed-on with the name. This information then can be used for some follow-up marketing for example.
Address_City Address City Name
Value ➡ {{results[*].addresses[*].city}}
Here we can pass-on the particular city name of the address which customer provides while registering in the shop.
Address_country Address Country Code (required)
Value ➡ {{results[*].addresses[*].country}}
The country code can have multiple values for one particular customer. For example different shipping and billing addresses. This is the reason we need to be able to get all the values under one customer name by using Array structure as it is shown in the setup.
Email Address Email
Value ➡ {{results[*].email}}
Customer e-mail address.
Address_street_number Address House Number
Value ➡ {{results[*].addresses[*].streetNumber}}
This field can be used to map customer address street or house number.
Address_mobile Address Mobile Phone
Value ➡ {{results[*].addresses[*].mobile}}
Customer mobile phone number
Address_phone Address Other Phone
Value ➡ {{results[*].addresses[*].phone}}
This optional field can be used to pass on the land-line number.
Address_pOBox Address PO Box Postal Code
Value ➡ {{results[*].addresses[*].pOBox}}
Customer Post Box Number
Address_street_name Address Street Name
Value ➡ {{results[*].addresses[*].streetName}}
Street name field for a customer.
Address_postal_code Address Street Postal Code (required)
Value ➡ {{results[*].addresses[*].postalCode}}
The same address multiplicity should be used here for postal codes in order to avoid multiple values being generated at SAP side.
Address_type Address Type Code
Value ➡ {{results[*].addresses[*]._type}}
This optional field can be used to map different types of address which customer provides. It could be residential or work.
No input Customer Group Code
Value ➡ Z7
This optional field can be used to assign a customer to one specific customer group in SAP ByDesign. For example, in this case, the customer will be in Z7 group. This is specific to individual requirements and can be different depending on particular need.
No input Company ID (required)
Value ➡ ID123456
The company ID information is related to internal bookkeeping and can be assigned to be one particular value for all new customers coming from our shop.
No input Currency Code (required)
Value ➡ EUR
Currency is obviously set for correct bookkeeping. If your shop is working with another currency system then this should have a different value.
No input Distribution Channel Code (required)
Value ➡ CODE
This code is more related to relating the internal SAP values to the new customer data. It is specific to a particular system used in SAP By Design ERP setup. For example, it can have 01 for direct sales.
Value ➡ {{results[*].id}}
Although this is an optional field in SAP ByDesign setup but we will be using this quite extensively to keep both systems in sync.
Last_Name Family Name (required)
Value ➡ {{results[*].lastName}}
This information comes from records.
No input Sales Organisation ID (required)
Value ➡ CODE
This code is also specific to the company which owns the ERP system and it is here to make sure to correctly assign the new customer data and further bookkeeping and invoicing.

More field available to map - There is more field available to map in this setup: for example, it is possible to pass-on the tax and VAT values for particular country of residence. These field are self-explanatory and only require diligent persistence to link both systems for better mapping results. - Update Customer

The final part of this integration flow would be to report back the ID from SAP By Design ERP system to run shop using - Update Customer connector:

SAP By Design ERP
External_ID Customer id (required)
Value ➡ {{externalID}}
In this required field, we map the External ID which comes from the SAP By Design ERP system with the Customer id generated inside the run Shop.
Internal_ID External id
Value ➡ {{customer.internalID}}
This is an optional field, however, for this integration to work properly, we would need to make the reverse mapping of Internal ID which comes from SAP By Design with the External id of run Shop.

Returning Customer Data

When our customer returns for more shopping but this time provides different delivery or billing address then we can update the customer data using our External ID. The flow shown below can be used to do this process:

We can use the same - Query Customers trigger connector to get the customer data from run Shop, but this time our customer already has a known ID (External ID) and this ID will identify and match the records in ERP system for which we will use SAP ByDesign - Update Customer action connector. - Query Customer

The filtering for this instance would be different since we want to report only existing customers and update their information for our bookkeeping in ERP. We will use externalId is defined:

SAP ByDesign - Update Customer

The mapping here is not particularly different from the one for SAP By Design - Create customer described above. In this case we can update the address as well by passing-on any new records which would be done similarly as before. The significant difference would be instead of External ID at ERP side we would have field called Internal ID: SAP By Design ERP
External_ID Internal ID - IMPORTANT
Value ➡ {{results[*].externalId}}
Although this is an optional field in SAP ByDesign setup but we will use this to reverse map our customer data which has already appropriate ID - External ID already given in the previous New Customer Creation stage by ERP system. This will be connected to the ERP system's Internal ID which is the only recognisable for our returning customer.

Orders and Sales

When our customer places the order in run Shop a new order is created and transmitted to SAP ByDesign ERP system where all the details should be stored since we are doing our all bookkeeping there. In ERP this new order receives a permanent ID which we need to report it back to our Shop system with the same idea behind - not to generate multiple records every time.

The danger of multiple records - Here the danger to generate multiple records is bigger since besides reporting to ERP when the new order is created the Shop system will report back several times and each with an updated information if there is no permanent ID associated with the order.

For example:

  • Price Update action - when your customer has a coupon or a special discount and it needs to be applied and returned back with an updated information,
  • Payment information update - when your customer already paid through Shop system and this needs to be reported for further action in Sales & Orders department.

New Order is Placed

When a customer places an order in our run shop system we want to process this order as fast as possible through our bookkeeping system in SAP ByDesign and give our customer the specific order number.

For this particular action we create a new flow which will use - Query Orders trigger connector to report the new order information to our ERP system. Our SAP ByDesign ERP system will create an order using SAP ByDesign - Create Order action connector and generate an Order Number (ID) which we report back to our Shop system using - Set Order Number action connector. Here is our created flow in Designer view shown below:

Syncing the price and payment info

After receiving the payment in shop system we wish to transfer that information to our bookkeeping. If we also have have a system of discounts and coupons then this will reflect on price and the price information needs to be synced with the ERP system as well. This process might involve several repetitions which will get out of hand if one unique Order ID is not used per order case.

In order to sync our order data from the Shop system with ERP system we can use - Query Orders trigger connector to send order data with already defined Order ID to the ERP system. In it's case at ERP side we can use SAP ByDesign - Set Order Payment Info action connector to record the payment data for our bookkeeping. In our Designer it would look like this:


One of the most important features of modern shopping experience is the ability to know or track the delivery of products for customers. Solutions for shipping and delivery are numerous and it is not the scope of this cookbook to describe them all. We present one method (for complete picture) of delivery reporting which is possible to do using components available at

After the order is ready it is shipped to our customer. We want to provide the customer with an up-to-date shipping and delivery status. While the initial shipping and delivery information should come from third party provider, but we can configure a receiving bucket and then give this information to our customer in the Shop system.

It is assumed that the shipping and delivery data is being delivered using some third party script which can post into a WebHook. From WebHook we can report this information back to the Shop using - Add a Delivery action connector which should then trigger - Change shipment state action connector to give our customer the final Shipped status. Using Designer we can do this by creating a flow which would look like this: