OData Example: Read and Write Product Purchasing Data

SAP Business ByDesign (ByD) provides you with REST/OData access to more than 300 business objects. This blog post provides you with an roundtrip example (find – read – update) using ByD OData services.

Example Scenario

Assume we have a material with product ID “KHM4” and purchasing unit of measure “Each”. In this scenario we change the purchasing UoM to “Box” and create a quantity conversion between the units “Each” and “Box”.

Expose ByD Materials as OData Service

Open work center view Application and User Management – OData Services and create a Custom OData Service for business object Material.

Make sure you expose material properties that enable you to filter, read and update all relevant material data incl. nodes ProcurementProcessInformation and QuantityConversion. In my example I included the following elements to my Custom OData Service “khmaterial“:

• InternalID
• UUID
• Description (incl. content and languageCode)
• BaseMeasureUnitCode
• IdentifiedStockTypeCode
• ProcurementProcessInformation (embedded in collection Material)
  • ProcurementMeasureUnitCode
  • Status/LifeCycleStatusCode
• QuantityConversion (created as separate collection MaterialQuantityConversion with all elements)
  • CorrespondingQuantity/content
  • CorrespondingQuantity/unitCode
  • QCBATCHDEPENDENT
  • Quantity/content
  • Quantity/unitCode

Please note: In my example I changed some property names to align with UI element names for better usability.

Furthermore, embedding the the procurement process information in the material collection simplifies read and update operations, but you cannot create procurement process information. To be able to create create procurement process information as well, you would have to create this node as separate entity.

Activate your custom OData service and note down the Service URL from the OData Editor. In my example the service URL is

https://my123456.sapbydesign.com/sap/byd/odata/cust/v1/khemployee.

If needed you can retrieve the metadata using the metadata URL

https://my123456.sapbydesign.com/sap/byd/odata/cust/v1/khemployee/$metadata

Read and Update Material Procurement Data using the Custom OData Service

Step 1: Get material data

Using the http-method GET and entity set MaterialCollection you can filter and read ByD materials and include quantity conversions:

https://my123456.sapbydesign.com/sap/byd/odata/cust/v1/khmaterial/MaterialCollection?$filter=InternalID eq ‘KHM4’&$expand=MaterialQuantityConversion&$format=json

In my example I’m using the URL parameter

• $filter=InternalID eq ‘KHM4’ to filter the materials by the internal ID,
• $expand=MaterialQuantityConversion to include the product quantity conversions in the OData response, and
• $format=json to use JSON as body format of the response (default is xml),

and the http-header parameter

• x-csrf-token=fetch to get the CSRF-token to update the material in the next step.

As result ByD returns the following OData response body:

As you can see the material “KHM4” has the base unit of measure and procurement unit of measure “Each” and no quantity conversion so far.

Step 2: Create quantity conversion

Before we can change the procurement UoM to a unit that differs from the base UoM, we need to create the quantity conversion between the base UoM and the new procurement UoM. In our example the ratio should be 1 Box corresponds to 42 Each.

Using http-method POST and the parent object ID (material object ID) provided by GET-response in step 1 you can create a new quantity conversion:

Example URL:

https://my123456.sapbydesign.com/sap/byd/odata/cust/v1/khmaterial/MaterialQuantityConversionCollection

with the http-header parameters

• Content-Type = application/json
• x-csrf-token = <as provided by the response header in step 1>

and body

(XBX is the ISO code for “Box”)

Step 3: Update procurement unit of measure

Now we can set the purchasing UoM to “Box” (ISO code “XBX”).

We are again using http-method POST with x-http-method “MERGE” and the material object ID provided by the GET-response in step 1:

https://my123456.sapbydesign.com/sap/byd/odata/cust/v1/khmaterial/MaterialCollection(‘00163E0E25A61EE885F6DAC3F0934740’)

with http-header parameters:

• Content-Type = application/json
• x-http-method = MERGE
• x-csrf-token = <as provided by the response header in step 1>

and body:

Step 4: Get the updated material data

Similar to step 1 we again get entity set MaterialCollection, filter by the material ID and expand the response by material quantity conversions:

https://my123456.sapbydesign.com/sap/byd/odata/cust/v1/khmaterial/MaterialCollection?$filter=InternalID eq ‘KHM4’&$expand=MaterialQuantityConversion&$format=json

As result ByD returns the following OData response body:

As you can see the material “KHM4” now has the procurement unit of measure “Box” and a material quantity conversion node instance for the conversion between Each and Box.