SAP Business ByDesign (ByD) uses unified data model components and UI components for address information in master data objects and business documents. This blog post describes how to read and write address information using OData services.
You find all examples mentioned in this blog post in the GitHub repository
SAP Business ByDesign - API Samples including the ByD custom OData services
khsalesorder and
khaddresssnapshot and the Postman collection
Master Data, folder
Address Snapshot.
Address Snapshot - Change Address Data in Business Documents
Let me start with some explanations about the handling of address information and the role of the business object "
AddressSnapshot" in ByD:
Business partner master data:
When you edit the address of a business partner, the system creates a new address snapshot. In general the address snapshot business object has no public write access and behaves as a read-only business object after it has been saved. In result the history of business partner address changes is stored as a stack of address snapshots, whereas only the latest address snapshot is displayed on the master data UI.
Business transactional documents:
When you create a business document, the system refers to the latest address snapshot from the respective business partner master data record.
Example: You create a sales order with the ship-to party “Silverstar Wholesale Corp”. In result the latest address snapshot of the business partner “Silverstar Wholesale Corp” is used as default and displayed as ship-to party address in the sales order.
By changing the address data in the business partner master data record, the address of the sales order ship-to party remains unchanged, because the sales order keeps a stable reference to the address snapshot instance that was assigned originally (even if it is no longer the latest address state from a master data point of view). By this approach we ensure stable address data in transactional documents and avoid implicit/accidental changes of transactional documents by master data changes.
Along business process chains the reference to the same address snapshot is handed over from business document to business document (for example from the sales order to the customer invoice). Hence, by default all business documents along a process chain refer to the same address snapshot instance, unless you edit the address information of some business document in the process chain.
If you change the address information of a business transaction document, then the system creates a new address snapshot instance which occurs as document specific address information.
On the ByD UI this address snapshot exchange is processed automatically by the system.
However, if you want to change the address in a business document via OData services, you need to realize the address snapshot exchange in a sequence of OData requests.
Flow of sample OData request
Example scenario: Create a sales order and change the address information of the ship-to party.
Step 1: Create sales order
POST /sap/byd/odata/cust/v1/khsalesorder/SalesOrderCollection
Request payload:
{
"ExternalReference": "{{A_SalesOrderExternalReference}}",
"Name": "Sales order for address change",
"DataOriginTypeCode": "1",
"SalesUnitParty":
{
"PartyID": "{{A_SalesUnitID}}"
},
"BuyerParty":
{
"PartyID": "{{A_CustomerID}}"
},
"PricingTerms":
{
"CurrencyCode": "EUR",
"GrossAmountIndicator": false
},
"Item":
[
{
"ID": "10",
"ProcessingTypeCode": "TAN",
"ItemProduct":
{
"ProductID": "{{A_MaterialID_stock}}"
},
"ItemScheduleLine":
[
{
"Quantity": "2",
"unitCode": "EA"
}
]
}
]
}
In result the ship-to address is defaulted with address information from the business partner master data record
Step 2: Get sales order with ship-to party address data
(business object node: SalesOrder.ProductRecipientParty.AddressSnapshot)
GET /sap/byd/odata/cust/v1/khsalesorder/SalesOrderCollection?$format=json&$expand=ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyName,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyFormattedAddress,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyPostalAddress&$filter=ID eq '4214'&$select=ObjectID,UUID,ID,Name,ExternalReference,ProductRecipientParty,ProductRecipientParty/ProductRecipientPartyDetails,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyName,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyFormattedAddress,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyPostalAddress&$inlinecount=allpages&sap-language=en
Response:
{
"d": {
"__count": "1",
"results": [
{
"ObjectID": "91C8E1EA590F1EED9EC7B422F39F9941",
"UUID": "91C8E1EA-590F-1EED-9EC7-B422F39F9941",
"ID": "4214",
"Name": "Sales order for address change",
"ExternalReference": "KH-2022-12-12T16:54",
"ProductRecipientParty": {
"ObjectID": "91C8E1EA590F1EED9EC7B422F39F9941 4",
"ParentObjectID": "91C8E1EA590F1EED9EC7B422F39F9941",
"PartyID": "CP100110",
"DeterminationMethodCode": "5",
"DeterminationMethodCodeText": "Copied Automatically from a Party with a Different Party Role Category",
"AddressReferenceTypeCode": "9",
"AddressReferenceTypeCodeText": "Address Snapshot",
"AddressReferenceUUID": "00000000-0001-1DDF-BA84-90748A78DCE3",
"ProductRecipientPartyDetails": {
"ObjectID": "0000000000011DDFBA8490748A78DCE3",
"AddressSnapshotUUID": "00000000-0001-1DDF-BA84-90748A78DCE3",
"SourceObjectNodeTypeCode": "143",
"SourceObjectNodeTypeCodeText": "Business Partner_Template",
"SourceObjectTypeCode": "441",
"SourceObjectTypeCodeText": "Business Partner",
"SourceNodeObjectUUID": "00000000-0001-1DDF-BA84-90748A78DCE3",
"FormattedName": "Silverstar Wholesale Corp",
"CorrespondenceLanguageCode": "",
"CorrespondenceLanguageCodeText": "",
"DefaultEMailURI": "",
"DefaultPhoneFormattedNumber": "",
"MobilePhoneFormattedNumber": "",
"DefaultWebURI": ""
}
}
}
]
}
}
Step 3: Get the address snapshot (business object:
AddressSnapshot) linked to the sales order ship-to party (product recipient party)
GET /sap/byd/odata/cust/v1/khaddresssnapshot/AddressSnapshotCollection?$filter=AddressSnapshotUUID eq guid'00000000-0001-1DDF-BA84-90748A78DCE3'&$expand=Name,PostalAddress,DisplayName,FormattedAddress&$format=json&sap-language=en
Response:
{
"d": {
"results": [
{
"ObjectID": "0000000000011DDFBA8490748A78DCE3",
"AddressSnapshotUUID": "00000000-0001-1DDF-BA84-90748A78DCE3",
"SourceObjectNodeTypeCode": "143",
"SourceObjectNodeTypeCodeText": "Business Partner_Template",
"SourceObjectTypeCode": "441",
"SourceObjectTypeCodeText": "Business Partner",
"SourceNodeObjectUUID": "00000000-0001-1DDF-BA84-90748A78DCE3",
"FormattedName": "Silverstar Wholesale Corp",
"CorrespondenceLanguageCode": "",
"CorrespondenceLanguageCodeText": "",
"DefaultEMailURI": "",
"DefaultEMailNormalisedURI": "",
"DefaultPhoneFormattedNumber": "",
"DefaultPhoneNormalisedNumber": "",
"DefaultMobilePhoneFormattedNumber": "",
"DefaultMobilePhoneNormalisedNumber": "",
"DefaultWebURI": "",
"Name": [],
"PostalAddress": [],
"DisplayName": [
{
"ObjectID": "0000000000011EE09788CC098F211B86",
"ParentObjectID": "0000000000011DDFBA8490748A78DCE3",
"FormattedName": "Silverstar Wholesale Corp",
"LanguageCode": "EN",
"LanguageCodeText": "English"
}
],
"FormattedAddress": [
{
"ObjectID": "0000000000011EE09788CC098F213B86",
"ParentObjectID": "0000000000011DDFBA8490748A78DCE3",
"FormattedPostalAddress": ""
}
]
}
]
}
}
Step 4: Create a new address snapshot for the sales order ship-to party
POST /sap/byd/odata/cust/v1/khaddresssnapshot/AddressSnapshotCollection
Request payload:
{
"SourceObjectNodeTypeCode": "{{AddressSnapshotSourceObjectNodeTypeCode}}",
"SourceObjectTypeCode": "{{AddressSnapshotSourceObjectTypeCode}}",
"SourceNodeObjectUUID": "{{AddressSnapshotSourceNodeObjectUUID}}",
"CorrespondenceLanguageCode": "EN",
"DefaultEMailURI": "catherine.kennedy-woods@us.almika-refsys.byd",
"DefaultPhoneFormattedNumber": "+1 216 399 3571-0",
"DefaultMobilePhoneFormattedNumber": "",
"DefaultWebURI": "www.sap.com",
"Name": [
{
"FirstLineName": "Silverstar Wholesale Corp",
"FourthLineName": "",
"SecondLineName": "",
"ThirdLineName": ""
}
],
"PostalAddress": [
{
"CountryCode": "US",
"RegionCode": "NY",
"CityName": "Buffalo",
"CompanyPostalCode": "",
"StreetName": "Nichols Pl",
"StreetPostalCode": "14203",
"HouseID": "23",
"CareOfName": "Catherine Kennedy-Woods",
"TaxJurisdictionCode": "NY"
}
]
}
Step 5: Update the reference to the address snapshot of the sales order ship-to party (business object node:
SalesOrder.ProductRecipientParty.AddressReference)
PATCH /sap/byd/odata/cust/v1/khsalesorder/ProductRecipientPartyCollection('91C8E1EA590F1EED9EC7B422F39F9941 4')
Request payload:
{
"ObjectID": "{{SalesOrderProductRecipientPartyObjectID}}",
"ParentObjectID": "{{SalesOrderObjectID}}",
"AddressReferenceUUID": "{{AddressReferenceUUID_New}}"
}
Step 6: Get the sales order incl. the new ship-to party details
GET /sap/byd/odata/cust/v1/khsalesorder/SalesOrderCollection?$format=json&$expand=ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyName,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyFormattedAddress,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyPostalAddress&$filter=ID eq '4215'&$select=ObjectID,UUID,ID,Name,ExternalReference,ProductRecipientParty,ProductRecipientParty/ProductRecipientPartyDetails,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyName,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyFormattedAddress,ProductRecipientParty/ProductRecipientPartyDetails/ProductRecipientPartyPostalAddress&$inlinecount=allpages&sap-language=en
Response:
{
"d": {
"__count": "1",
"results": [
{
"ObjectID": "91C8E1EA590F1EED9EC7DD7CAF569CAF",
"UUID": "91C8E1EA-590F-1EED-9EC7-DD7CAF569CAF",
"ID": "4215",
"Name": "Sales order for address change",
"ExternalReference": "KH-2022-12-12T17:03",
"ProductRecipientParty": {
"ObjectID": "91C8E1EA590F1EED9EC7DD7CAF569CAF 4",
"ParentObjectID": "91C8E1EA590F1EED9EC7DD7CAF569CAF",
"PartyID": "CP100110",
"DeterminationMethodCode": "1",
"DeterminationMethodCodeText": "Provided by an Unspecified External Source",
"AddressReferenceTypeCode": "9",
"AddressReferenceTypeCodeText": "Address Snapshot",
"AddressReferenceUUID": "91C8E1EA-590F-1EED-9EC7-E1774DAAFD4C",
"ProductRecipientPartyDetails": {
"ObjectID": "91C8E1EA590F1EED9EC7E1774DAAFD4C",
"AddressSnapshotUUID": "91C8E1EA-590F-1EED-9EC7-E1774DAAFD4C",
"SourceObjectNodeTypeCode": "143",
"SourceObjectNodeTypeCodeText": "Business Partner_Template",
"SourceObjectTypeCode": "441",
"SourceObjectTypeCodeText": "Business Partner",
"SourceNodeObjectUUID": "00000000-0001-1DDF-BA84-90748A78DCE3",
"FormattedName": "Silverstar Wholesale Corp",
"CorrespondenceLanguageCode": "EN",
"CorrespondenceLanguageCodeText": "English",
"DefaultEMailURI": "catherine.kennedy-woods@us.almika-refsys.byd",
"DefaultPhoneFormattedNumber": "+1 216 399 3571-0",
"MobilePhoneFormattedNumber": "",
"DefaultWebURI": "www.sap.com",
"ProductRecipientPartyName": [
{
"ObjectID": "91C8E1EA590F1EED9EC7E1774DAB9D4C",
"ParentObjectID": "91C8E1EA590F1EED9EC7E1774DAAFD4C",
"FirstLineName": "Silverstar Wholesale Corp",
"FourthLineName": "",
"SecondLineName": "",
"ThirdLineName": ""
}
}
],
"ProductRecipientPartyFormattedAddress": [
{
"ObjectID": "91C8E1EA590F1EED9EC7E1774DAC7D4C",
"ParentObjectID": "91C8E1EA590F1EED9EC7E1774DAAFD4C",
"FormattedPostalAddress": "23 Nichols Pl / Buffalo NY 14203 / US"
}
],
"ProductRecipientPartyPostalAddress": [
{
"ObjectID": "91C8E1EA590F1EED9EC7E1774DABBD4C",
"ParentObjectID": "91C8E1EA590F1EED9EC7E1774DAAFD4C",
"CountryCode": "US",
"CountryCodeText": "United States",
"RegionCode": "NY",
"RegionCodeText": "New York",
"CityName": "Buffalo",
"CompanyPostalCode": "",
"StreetName": "Nichols Pl",
"StreetPostalCode": "14203",
"HouseID": "23",
"CareOfName": "Catherine Kennedy-Woods",
"TaxJurisdictionCode": "NY",
"TaxJurisdictionCodeText": "New York",
"TimeZoneCode": "EST",
"TimeZoneCodeText": "(UTC-05:00) Eastern Time (New York, Quebec)"
}
]
}
}
}
]
}
}
Known issue:
Do not include the business object node FormattedAddressSuitableForLogonLanguage of address snapshots in OData services. This node does require a context parameter, which is not supported by the OData framework yet and hence this node raises error code
"500 - Internal server error in GET-requests".
