Guide for consultants and developers
Replicating items and business partners between SAP Business One company databases
Items and business partners are where every group starts, and where the Service Layer has the most habits. What to send, what to leave, how prices, addresses and contact persons behave, and the refusals you will meet, each from a run against a real SAP Business One 10.0 system.
Field names below are the Service Layer's own (Items, BusinessPartners). Everything described here was seen on SAP Business One 10.0 on SAP HANA; other versions and localisations may differ in details.
1. Items: three kinds of fields
Read an item through the Service Layer and you get about two hundred properties plus several lists. Sort them before you send anything.
| Treatment | Fields | Why |
|---|---|---|
| Never send | QuantityOnStock, QuantityOrderedFromVendors, QuantityOrderedByCustomers, MovingAveragePrice, AvgStdPrice, UpdateDate, UpdateTime, TreeType | SAP Business One owns them. Some are refused, others are silently ignored, and TreeType follows the bill of materials |
| Local unless decided otherwise | Series, DefaultWarehouse, the revenue and expense accounts, Picture, AttachmentEntry | They name things of one company. A target whose default series numbers items automatically cannot take the source's item number |
| On creation only | ManageSerialNumbers, ManageBatchNumbers, CostAccountingMethod, InventoryItem, ItemType, UoMGroupEntry, InventoryUoMEntry, GLMethod | SAP Business One refuses to change them once the item is in use |
Everything else is a candidate for replication: description, foreign name, group, manufacturer, units, dimensions, planning data, properties, user-defined fields.
2. What an item points at
These fields hold the key of another record, and that key is the source company's. Each has to be replaced by the target's own key:
ItemsGroupCode(item group),Manufacturer,ShipType,CustomsGroupCode: numbers SAP assigns, different in every company. The built-in rows such as "No Manufacturer" carry the same negative number everywhere and can pass as they are.UoMGroupEntryand the unit of measure entries for inventory, sales, purchasing and counting.Mainsupplierand the business partners inItemPreferredVendors.SalesVATGroupandPurchaseVATGroup: tax groups depend on each country's law. Map them; do not copy them.PriceListin every row ofItemPrices, and the warehouse in every row of the warehouse list.
3. Prices
ItemPrices has one row per price list, identified by PriceList, which is again a number of one company: price list 1 of the source may be price list 4 of the target. A few things to know:
- Every item has a row for every price list of its company. You do not add or remove rows; you set prices in them.
BasePriceListandFactordescribe how a list is calculated from another. They belong to the price list, not to the item, and are best not sent with the item.- A price of a calculated list travels as a value like any other. If the target should calculate that list itself, leave it out.
- Prices per unit of measure sit in a list inside each price row,
UoMPrices, identified by the unit. Each row repeats the price list number, which has to be translated as well. The Service Layer adds and updates these rows; it does not remove one that is no longer sent.
4. Bar codes and the order of things
An item has a default bar code in BarCode and a list of bar codes in ItemBarCodeCollection. Create an item with both in one request and the Service Layer may answer: "You cannot set bar code as default for this item; define bar code first". Create the item with its list first and set the default in a second request.
The same pattern returns elsewhere: a field that names something the record only gets with its creation has to be written afterwards. A price list is its own base list, for example, so it is created without BasePriceList, which is set right after, with the new number.
5. Business partners: what stays at home
| Treatment | Fields |
|---|---|
| Never send | Balances (CurrentAccountBalance, OpenOrdersBalance, OpenDeliveryNotesBalance), credit card data, Password, dunning level and date |
| Local unless decided otherwise | Series, the house bank fields, OwnerCode, the default bank, the interim and exchange difference accounts, PeymentMethodCode |
| On creation only | CardType, Currency |
| References to translate | GroupCode, PayTermsGrpCode, PriceListNum, SalesPersonCode, ShippingType, Territory, Industry, DebitorAccount, FatherCard, VatGroup |
The default payment method is refused without the partner's list of payment methods, and both carry house bank details: send both, or neither.
6. Addresses and contact persons
These two lists are where most duplicates come from.
Addresses (BPAddresses) are identified by name and type: "Head office" as a bill-to address and "Head office" as a ship-to address are two rows. Each has a RowNum that each company assigns itself. Adding an address is simple. Changing one is not: the Service Layer only recognises the row as an existing one when it also carries the business partner's code in BPCode. Without it the change is taken for a new address and refused as a duplicate. And SAP Business One does not tell "Ship To" from "Ship to": the second is refused as a duplicate of the first, so match address names without regard to case.
Contact persons (ContactEmployees) are identified by InternalCode, again a number of one company. If you match contacts by name, renaming one at head office creates a second contact in every target. Remember which InternalCode of the target each contact of the source became, and send changes to that row.
The fields ContactPerson, BilltoDefault and ShipToDefault name a row of these lists. A partner cannot name a default contact or address it does not have, so these fields only make sense when the lists travel too.
7. Refusals you will meet
| The Service Layer says | What it usually means | What to do |
|---|---|---|
| A property is unknown, and the whole record is refused | The record carries a user-defined field the target company does not have | Read the target's own field list first and leave such fields out, or create the field in the target |
| This entry already exists (-2035) when changing an address | The address row was sent without BPCode, or its name differs only in letter case from an existing one | Send RowNum and BPCode with a changed row |
| Could not commit transaction on every change to a table | A user-defined field was added and this Service Layer, or one of its nodes, started before it existed | Restart the Service Layer |
| The logged-on user does not have permission to use this object | The SAP user lacks the authorisation for that object. A standard user is held to its authorisations through the Service Layer, for reading too | Give the authorisation under General Authorizations |
| Duplicate value when changing one valid value of a user-defined field | The list of valid values is only taken whole | Send the complete list |
| Invalid record offset on a new territory | It asks for a place among its siblings that is taken | Do not send the place; SAP gives the next free one |
| No error, and the value is not there afterwards | SAP Business One silently did not take it, for example a packaging unit whose package type the target lacks | Read the record back after every write and compare |
8. A procedure that keeps you out of trouble
- Work between copies of your companies first.
- Replicate the set-up data the items and partners point at, or decide that it is created on the way.
- Pair what is local: tax groups, payment methods, dunning terms.
- For one item and one partner: look at what would be sent, field by field, before sending it.
- Create it, then run it again. The second run must send nothing. If it sends something, a comparison is wrong, usually nothing against zero or a value SAP did not take.
- Change the source and run again: only the changed fields should travel.
- Change the target, and decide what should happen to that change.
9. How CertiReplica handles all of this
Everything above is built into CertiReplica's catalogue and engine, and covered by automated tests, because each point was met on a real system. Items and business partners are two of its 32 objects; both are marked Proven.
- The three kinds of fields are the standard treatment of a new rule, shown next to the source company's real fields with a sample value. A rule changes the treatment of any field, or of a pattern such as
U_*. - References are translated by links, by name or by mapping, and missing ones are created first, fixed, or the record is held with a sentence that names them.
- Rows of lists are followed by a row map, so a renamed contact person is renamed. Lists are merged or mirrored, per list.
- Fields the target lacks are left out and named. Values SAP did not take are reported and not sent again.
- Steps 4 and 5 of the procedure are a button: Simulate shows what would be written, and after a run the same simulation must say "already the same".
It talks to each company through the Service Layer only and installs nothing in SAP Business One. Request a trial: it works in full for 30 days.