Community
Enterprise Resource Planning Blog Posts by Members
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 
Read only

SAP S/4HANA Functionality for EDI Processing: Inbound Order Creation by API vs. IDOC (Part 2)

M_Kalyabin
Participant
‎2024 Dec 25 7:07 PM
2,382

This is the second part of a detailed comparison of the order creation process using APIs and IDocs. The first part focused on partner mappings. In this part, I will examine the mapping of external material numbers to internal ones. My objective is to compare the features supported by the API with those available for IDocs, identify new opportunities, and highlight deviations that require attention. The purpose of this analysis is to evaluate whether the selected API can effectively replace IDoc-based processing. For this, I will focus on the logic that aligns closely with classical IDocs. While the API may offer extended functionality, such cases are beyond the scope of this article.

As mentioned in one of my previous posts, the appropriate API for inbound order creation is ORDERREQUEST_IN: Sales Order/Customer Return - Create, Update, Cancel (B2B). This API is compared with the IDoc ORDERS processing, which uses process code ORDE and function module IDOC_INPUT_ORDERS.

TLDR: Main Comparison Results (Material Determination)

The B2B API supports most of the IDoc logic in the described areas while introducing several useful new features:

  • Material determination employs similar logic for vendor material and customer material info records.
  • New feature: Material and UoM determination by EAN/GTIN, based on material master data.
  • Legacy logic for EAN/GTIN based on VB12 is not supported, and additional cross-checks have been introduced in the determination logic.
  • Text Item might be created if CMIR is not recognized

Material Determination Logic

This topic can be divided into two parts: business logic and technical implementation. In my previous article about IDoc processing for Material Determination for Inbound Orders, I shared my thoughts on business logic, including X12 and EDIFACT examples, approaches relevant for "contracts" and "catalogues", and key challenges from a business perspective. Naturally, these challenges and ideas also apply to API processing. For more details, please refer to that article.

This article focuses on the technical aspect—specifically, how material determination logic works for APIs in comparison to IDocs.

For illustration, I will use the same test cases as those used for IDocs. Generally, customers use the following options as input data:

  • Customer Material Number (CMIR): Each customer has their own ERP system and unique material numbers, as well as any associated coding.
  • Vendor Material Number: A customer may use this number on the order, though it could sometimes be outdated, incorrect, or related to reference material.
  • EAN/UPC/GTIN: A barcode and number used internationally for product identification.

Material number mappingMaterial number mapping

The ORDERREQUEST_IN API request structure provides transparent fields for these options, as well as for unit of measure (UoM) information:

 

 

<OrderItem>
   <PurchaseOrderItemID>10</PurchaseOrderItemID>
   <OrderItemText>Customer Order item text</OrderItemText>
   <RequestedQuantity unitCode="PCE">10.0</RequestedQuantity>
   <Product>
      <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
      <SupplierProductID>1521</SupplierProductID>
      <BuyerProductID>ACME-1521</BuyerProductID>
   </Product>
</OrderItem>

 

 

Processing logic is described in the program code. The MAP_PRODUCT method in the CL_EDI_SD_ORDR_MAPPING class outlines the logic as follows:

 

 

* Material determination logic:
* Priority 1: Supplier Product ID (material_no)
* Priority 2: EAN code            (international_article_no)
* Priority 3: Buyer Product ID    (customer_material_no)
*
* If EAN does not match material -> error in GOAL
* If EAN does not match customer material -> ignore customer material
* If material does not match customer material -> ignore customer material

 

 

T-code SE80, MAP_PRODUCT method:

Material Mapping Logic in the ABAP method MAP_PRODUCTMaterial Mapping Logic in the ABAP method MAP_PRODUCT

From this description, it is clear that this logic differs from IDoc material determination in at least two ways: the sequence of priorities and the additional EAN/GTIN control.

Another noteworthy feature is the use of EAN/GTIN data directly from the material master record during the determination process. This capability, long desired by users, is now available out of the box!

Comparison of API and IDoc Logic for Material Determination

Recap of IDoc Logic

When the SAP standard function module IDOC_INPUT_ORDERS is used to process inbound orders, the material determination sequence is as follows:

  1. Vendor Material Number (Qualf = 002):

    • If the value is not recognized, the IDoc fails, regardless of other qualifiers.

  2. CMIR (Qualf = 001):

    • If the value is incorrect, the system attempts to use the EAN. If the EAN is not provided, the IDoc fails.

  3. EAN (Qualf = 003):

    • If the value is incorrect, the IDoc fails.

API Logic Sequence

For API processing, the material determination sequence is:

  1. Vendor Material Number (<SupplierProductID>):

    • If the value matches an SAP material number or material substitution record, determination is successful.
    • If the value is not recognized, the message fails, regardless of other fields.
    • If <GlobalTradeItemNumber> is provided, an EAN check is performed. If the material or UoM does not match the EAN, the message fails.

  2. EAN/GTIN (<GlobalTradeItemNumber>):

    • If a unique material is found based on the EAN, determination is successful.
    • If the EAN is not found, the message fails.
    • If multiple materials are found by EAN and <BuyerProductID> (CMIR) is provided, CMIR determination is performed. Otherwise, the message fails.

  3. CMIR (<BuyerProductID>):

    • If the customer-material record is found, determination is successful.
    • If <GlobalTradeItemNumber> is provided, an EAN check is performed. If the material or UoM does not match the EAN, the message fails.
    • Regardless of whether <BuyerProductID> is used for determination, it is recorded as the customer material number in the relevant sales order item field.

Key Differences Between IDoc and API Logic

  1. Sequence Differences:

    • IDoc Sequence: Vendor Material → CMIR → EAN.
    • API Sequence: Vendor Material → EAN → CMIR.

  2. Interdependency:

    • IDoc logic is linear, with values not influencing one another.
    • API logic introduces EAN checks. A material determined by Vendor Material or CMIR must match the EAN/GTIN if provided.

  3. Data Source for EAN/GTIN Determination:

    • IDoc uses material substitution (t-code VB12).
    • API uses material master data (t-code MM02, table MEAN).

Similarities Between IDoc and API Logic

  1. Vendor Material:

    • Both use the SAP material number or material substitution (t-code VB12).

  2. CMIR Determination:

    • Both rely on the same CMIR mapping (t-code VD52, table KNMT).

Conclusion

If only CMIR and Vendor Material are used for determination, the API and IDoc logic function identically. However, if EAN is included in the material determination process, the master data and determination logic must be carefully reviewed and adjusted.

Unit of Measure Determination Logic

Unit of Measure (UoM) determination is a critical feature for certain industries. I previously elaborated on this topic in the context of EDI and IDocs in the article UoM Determination for Inbound Orders.

The API follows a similar approach but includes some important adjustments:

  1. Mapping of UoM:

    • If the UoM is provided in the message, it is mapped from the external "ISO" code to the internal SAP code (t-code CUNI, table T006), just as it is for IDocs.

  2. EAN-Based UoM Validation:

    • If both the UoM and an EAN are provided in the message, an additional control ensures that the item's UoM matches the UoM associated with the EAN.

  3. Default UoM Logic:

    • If the UoM is not provided:
      • For Vendor Material or CMIR determination, the default value from the material master is used.
      • For EAN determination, the UoM connected to the EAN is used.

From my perspective, UoM determination based on EAN is a valuable enhancement introduced with the API. However, its effectiveness relies heavily on the quality of both the customer's and supplier's master data.

Material Determination Test Examples

Let’s review test cases to illustrate both successful processing scenarios and potential errors.

Vendor Material, EAN and CMIR

Example: Item with Vendor Material, EAN, and CMIR

In the message snippet below, all three external identifiers are provided:

 

 

 <OrderItem>
   <PurchaseOrderItemID>10</PurchaseOrderItemID>
   <OrderItemText>Customer Order item text</OrderItemText>
   <RequestedQuantity unitCode="PCE">10.0</RequestedQuantity>
   <Product>
    <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
    <SupplierProductID>1521</SupplierProductID>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
   </Product>

 

 

In this case, Vendor Material 1521 must be recognized either as an SAP material or through the material substitution technique, and the EAN 8427324815219 must correspond to the determined material. While the CMIR ACME-1521-0000 is not used for material determination, it is recorded as the customer material number in the relevant sales order item.

Below is the complete request structure for this test case:

 

 

<n0:OrderRequest xmlns:n0="http://sap.com/xi/EDI">
 <MessageHeader>
  <ID>Message_Header_ID</ID>
  <CreationDateTime>2020-04-10T02:53:20Z</CreationDateTime>
  <SenderParty>
   <InternalID>246</InternalID>
  </SenderParty>
 </MessageHeader>
 <Order>
  <PurchaseOrderID>B2B_API_test_23122024-1</PurchaseOrderID>
  <PurchaseOrderCreationDate>2024-12-23</PurchaseOrderCreationDate>
  <Party PartyType="SoldTo">
   <BuyerPartyID>ACME-0211</BuyerPartyID>
   <GlobalLocationNumber>7089900000016</GlobalLocationNumber>
  </Party>
  <Party PartyType="ShipTo">
   <BuyerPartyID>ACME-0212</BuyerPartyID>
   <GlobalLocationNumber>7089900000023</GlobalLocationNumber>
  </Party>
  <Party PartyType="Supplier">
   <BuyerPartyID>WHOLESALER_ASA</BuyerPartyID>
   <GlobalLocationNumber>7088800010002</GlobalLocationNumber>
  </Party>
  <Text Type="SalesNote">
   <TextElementLanguage>EN</TextElementLanguage>
   <TextElementText>Header note 1 by API</TextElementText>
  </Text>
  <OrderItem>
   <PurchaseOrderItemID>10</PurchaseOrderItemID>
   <OrderItemText>Customer Order item text</OrderItemText>
   <RequestedQuantity unitCode="PCE">10.0</RequestedQuantity>
   <Product>
    <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
    <SupplierProductID>1521</SupplierProductID>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
   </Product>
   <ExpectedNetPrice>
    <Amount currencyCode="NOK">11</Amount>
    <BaseQuantity unitCode="PCE">1</BaseQuantity>
   </ExpectedNetPrice>
   <ExpectedNetAmount currencyCode="NOK">110</ExpectedNetAmount>
   <Text Type="MaterialText">
    <TextElementLanguage>EN</TextElementLanguage>
    <TextElementText>Material text by API</TextElementText>
   </Text>
  </OrderItem>
 </Order>
</n0:OrderRequest>

 

 

The Sales Order created by this request :

Sales order 1576Sales order 1576

Material Master Validation: The EAN in the message (8427324815219) matches the EAN in the material's master record (t-code MM03) for the specified unit of measure (PC).

Material master: EAN detailsMaterial master: EAN details

Vendor Material, EAN and CMIR – error handling

Example: Incorrect Vendor Material

In this scenario, the Supplier Product Number (X1521) provided cannot be recognized by the system:

 

 

<Product>
    <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
    <SupplierProductID>X1521</SupplierProductID>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
</Product>

 

 

Error message: EAN/UPC 8427324815219 is incompatible with material X1521 and unit PC

The actual reason for the error is that the Supplier Product Number (X1521) was not recognized as a valid SAP material or substitution. However, since an EAN (8427324815219) was provided in the message, the system performed an additional validation to check the EAN's compatibility with the material and unit of measure (PC). The error description reflects the result of this EAN check, even though the primary issue lies with the unrecognized material.
Below is the complete error response:

 

 

<n0:StandardMessageFault xmlns:n0="http://sap.com/xi/SAPGlobal/Global" xmlns:prx="urn:sap.com:proxy:SW1:/1SAI/TAS86C5ECFCD060648BFE9A:757">
<standard>
<faultText> Execution failed; see further messages for details</faultText>
<faultDetail>
<severity>error</severity>
<text>EAN/UPC 8427324815219 is incompatible with material X1521 and unit PC</text>
<id>084(SLS_LORD)</id>
</faultDetail>
<faultDetail>
<severity>information</severity>
<text>Check route for Ship-to party 0000000212 in document header</text>
<id>008(VPD)</id>
</faultDetail>
<faultDetail>
<severity>information</severity>
<text>Taxes have been re-determined</text>
<id>217(V1)</id>
</faultDetail>
</standard>
</n0:StandardMessageFault>

 

 

Example: Incorrect EAN

In this scenario, the EAN provided (8427324815202) cannot be recognized by the system:

 

 

<Product>
    <GlobalTradeItemNumber>8427324815202</GlobalTradeItemNumber>
    <SupplierProductID>1521</SupplierProductID>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
</Product>

 

 

Error Message: No material exists for EAN/UPC 8427324815202

Since an EAN (8427324815202) was included in the message, the system attempted to validate it against the material master. The error occurred because this EAN could not be found or matched to a valid SAP material.

This example highlights a potential risk when using EAN as additional data. Even though the Vendor Material (1521) is correct and could be processed successfully, the inclusion of an invalid or unrecognized EAN causes the entire message to fail.

Example: EAN doesn't match UoM

In this scenario, the EAN provided (8427324815219) does not match the unit of measure (UoM) specified in the message:

 

 

 <RequestedQuantity unitCode="PAK">10.0</RequestedQuantity>
 <Product>
    <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
    <SupplierProductID>1521</SupplierProductID>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
 </Product>

 

 

Error Message: EAN/UPC 8427324815219 is incompatible with material 1521 and unit PAC

Since an EAN (8427324815219) was provided, the system recognized it as relevant for Material 1521 and the UoM PC (Piece). However, the UoM specified in the message item was PAK, which was mapped to PAC during processing using the CUNI-related technique. This mismatch triggered the error.

Vendor Material– error handling

Example: Incorrect Vendor Material

In this scenario, the Supplier Product Number (X1521) provided cannot be recognized by the system and the EAN wasn't provided.

 

 

<Product>
    <SupplierProductID>X1521</SupplierProductID>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
</Product>

 

 

Error Message: Material X1521 is not defined for sales org.1000, distr.chan.10, language EN

Example: Incorrect Unit of Measure

In this scenario, the Unit of Measure (XXX) provided cannot be recognized by the system and the EAN wasn't provided.

 

 

<RequestedQuantity unitCode="XXX">10.0</RequestedQuantity>
<Product>
    <SupplierProductID>1521</SupplierProductID>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
</Product>

 

 

Error Message: Sales unit XXX is not defined for item 000010

Item with EAN

Example: Item with EAN

When using an EAN, both the material and unit of measure (UoM) can be determined. In this test case, the EAN 8427324815226 is recognized by the system as uniquely relevant to Material 1521 and the UoM PAC.

Below is the complete request structure for this test case:

 

 

<n0:OrderRequest xmlns:n0="http://sap.com/xi/EDI">
 <MessageHeader>
  <ID>Message_Header_ID</ID>
  <CreationDateTime>2020-04-10T02:53:20Z</CreationDateTime>
  <SenderParty>
   <InternalID>246</InternalID>
  </SenderParty>
 </MessageHeader>
 <Order>
  <PurchaseOrderID>B2B_API_test_23122024-3</PurchaseOrderID>
  <PurchaseOrderCreationDate>2024-12-23</PurchaseOrderCreationDate>
  <Party PartyType="SoldTo">
   <BuyerPartyID>ACME-0211</BuyerPartyID>
   <GlobalLocationNumber>7089900000016</GlobalLocationNumber>
  </Party>
  <Party PartyType="ShipTo">
   <BuyerPartyID>ACME-0212</BuyerPartyID>
   <GlobalLocationNumber>7089900000023</GlobalLocationNumber>
  </Party>
  <Party PartyType="Supplier">
   <BuyerPartyID>WHOLESALER_ASA</BuyerPartyID>
   <GlobalLocationNumber>7088800010002</GlobalLocationNumber>
  </Party>
  <OrderItem>
   <PurchaseOrderItemID>10</PurchaseOrderItemID>
   <OrderItemText>Customer Order item text</OrderItemText>
   <RequestedQuantity>10.0</RequestedQuantity>
   <Product>
    <GlobalTradeItemNumber>8427324815226</GlobalTradeItemNumber>
   </Product>
  </OrderItem>
 </Order>
</n0:OrderRequest>

 

 

Material Master data: The EAN in the message (8427324815226) is relevant for material 1521 and UoM PAC.

Material master: EAN detailsMaterial master: EAN details

The Sales Order created from this request successfully uses the UoM PAC, determined automatically based on the provided EAN.

Sales order 1577Sales order 1577

Item with EAN – error handling

Example: Incorrect EAN

In this case EAN was clearly spoiled and couldn't be recognized:

 

 

<Product>
    <GlobalTradeItemNumber>X8427324815226</GlobalTradeItemNumber>
</Product>

 

 

Error Message: No material exists for EAN/UPC X8427324815226

Example: EAN is not unique

In this case, the EAN provided for material determination (8427324815219) is assigned to multiple materials in the system.

 

 

<Product>
    <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
</Product>

 

 

MEAN table: EAN 8427324815219 is associated with two SAP materials: 1521 and 2591.

MEAN for 8427324815219MEAN for 8427324815219

Error Message:More than one material exists for EAN/UPC 8427324815219

Notice: if a correct CMIR record was provided also, a material could be determined, as shown below.

Item with EAN and CMIR

Example: EAN Is Unique, CMIR Ignored

If material determination succeeds using an EAN, the CMIR is ignored. In this test case, the EAN 8427324815202 is recognized by the system as uniquely relevant to Material 2591 with the UoM PAC.

Request example:

 

 

<RequestedQuantity unitCode="PAK">10.0</RequestedQuantity>
<Product>
    <GlobalTradeItemNumber>8427324815202</GlobalTradeItemNumber>
    <BuyerProductID>ACME-1521</BuyerProductID>
</Product>

 

 

The EAN 8427324815202 is associated in the master data with Material 2591 and the UoM PAC.

84273248152028427324815202

While the CMIR value ACME-1521 is valid for SAP Material 1521 (t-code VD52), it was not used during material determination because the EAN was sufficient to uniquely identify the material.

CMIR for ACMECMIR for ACME

Sales order 1578 was created with material 2591. Despite being ignored for material determination, the CMIR ACME-1521 was recorded as the Customer Material Number in the sales order item.

Sales Order 1578Sales Order 1578

Example: EAN Is Not Unique, CMIR considered

As previously shown, the EAN 8427324815219 is assigned to multiple materials in the system. However, if the message also contains a relevant CMIR, the material can be uniquely recognized.

 

 

 <RequestedQuantity>10.0</RequestedQuantity>
 <Product>
    <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
    <BuyerProductID>ACME-1521</BuyerProductID>
 </Product>

 

 

MEAN table: the EAN 8427324815219 is associated with two SAP materials: 1521 and 2591.

MEAN for 8427324815219MEAN for 8427324815219

The CMIR value ACME-1521 is valid for SAP Material 1521 (t-code VD52). CMIR for ACMECMIR for ACME

By combining the EAN and the CMIR value, the system was able to identify Material 1521 as the correct material.

Sales Order 1579Sales Order 1579

Example: EAN Is Not Unique, CMIR doesn't match EAN

CMIR records helps if it matches a material determined by EAN. Otherwise determination fails as if CMIR wasn't provided. In the example below CMIR in the message is relevant to SAP material 1531, while EAN 8427324815219 is relevant for 1521 and 2591.

 

 

 <RequestedQuantity>10.0</RequestedQuantity>
 <Product>
    <GlobalTradeItemNumber>8427324815219</GlobalTradeItemNumber>
    <BuyerProductID>ACME-1531</BuyerProductID>
 </Product>

 

 

As result error appears. Error Message:More than one material exists for EAN/UPC 8427324815219

Item with CMIR

Example: CMIR is recognised

A correct CMIR is enough for material determination.

 

 

 <RequestedQuantity unitCode="PCE">10.0</RequestedQuantity>
 <Product>
    <BuyerProductID>ACME-1521</BuyerProductID>
 </Product>

 

 

The CMIR value ACME-1521 is valid for SAP Material 1521 (t-code VD52). CMIR for ACMECMIR for ACME

Sales order 1580 created:

Sales Order 1580Sales Order 1580

Example: CMIR Is Not Recognized, TATX Item Is Created

In this case, CMIR ACME-1521-0000 is not recognized in the system.

 

 

 <RequestedQuantity unitCode="PCE">10.0</RequestedQuantity>
 <Product>
    <BuyerProductID>ACME-1521-0000</BuyerProductID>
 </Product>

 

 

Since the CMIR value ACME-1521-0000 cannot be determined, the system does not assign an SAP material number. Instead of generating an error, the system creates a text item (item category TATX). Such item doesn't contain SAP material number and quantity. Sales order with TATX itemSales order with TATX item

This approach avoids a processing error and delegates the issue to customer service for manual resolution.

Note: This case is another difference between IDoc and API logic:

  • API Logic: When CMIR mapping is missing, the system creates a text item (TATX) as a fallback, enabling continued processing.
  • IDoc Logic: If CMIR mapping is missing, processing fails entirely, resulting in a hard error and blocking the order.

Acknowledgements and System Overview

Thanks to my colleagues at Capgemini and others who explored this topic with me across numerous projects. Also, thanks to Capgemini for providing me with a sandbox system, which I used for investigations, creating test examples, and preparing screenshots. The sandbox was SAP S/4HANA 2022 (S/4HANA On-Premise Release 2022 SP 01, February 2023 FPS).

Labels