Introduction
In my brief overview of the library of type systems in the previous blog integration content advisor: Discover B2B/A2A standard libraries. I mentioned that all standardized B2B message structures are complex and must be customized depending on business needs. This customization must be precisely specified. The message types are the basis for building a message implementation guidelines (MIG). In other words, the standardized message structures form the template interfaces for a MIG. The MIG precisely describes the structure of a customized interface, the meaning of each defined element, and how each element of payload data is treated or processed according the conventions of the interface. Another aspect of a MIG is the consideration of integrity conditions and business rules. A MIG is intended to provide all the information needed to implement a customized message interface, so that the user or implementer doesn’t need to reference any other documents or sources. The more precisely a MIG is specified, the less effort required to create a mapping guideline (MAG), because ICA automatically considers all detailed definitions and parameters of the specified elements in the mapping elements of a mapping guideline. This approach significantly reduces the number of complex functions in the MAG. This will be explained in more detail in the next blog “Integration Content Advisor (ICA): Create a mapping guideline (MAG) using the MAG editor.”
Scope of the scenario
Before I start talking about the MIG, I’ll briefly describe typical B2B scenario in where a purchase order should be exchanged between two trading partners. The ICA is ideally suited for the integration content creation of this B2B scenario. How to create will be explained by the same B2B scenario throughout the following blogs:
- Creation of a Message Implementation Guideline (MIG) — this blog
- Creation of a Mapping Guideline (MAG) — will be published as a next blog.
- Generation of runtime artifacts, importing them into the prepared integration flow, and deploying—this blog will be next after "Creation of Mapping Guideline (MAG).
Assume that the company you’re working for as a B2B expert is a grocery store, located in Germany, that specializes in foods and beverages for the consumer products industry. The name of the company is "Lief GmbH" and it’s using SAP S/4 HANA Cloud for purchase processing. Lief GmbH wants to buy food and beverages from an American wholesaler called "ConTrade Inc" who have requested that the the ASC X12 standard. They want to start with the first business transaction step, which is the purchase order submission from Lief GmbH. From your point of view, this is in the outbound direction. They’ve provided you a message implementation guideline of the ASC X12 purchase order (850), version 004010 in form of a PDF file (see following link).
Submitted Message Implementation Guideline from ConTrade Inc.
Lief GmbH already has an enterprise license for SAP Cloud Platform Integration (CPI), and therefore access to ICA for creating the integration content for this B2B scenario. Let’s assume, you are responsible in Lief GmbH for onboarding, testing, and maintaining the B2B scenarios with the Lief's trading partners, and the Lief GmbH has a SAP S/4 HANA Cloud application.
SAP S/4 HANA Cloud supports SOA messages based on WSDL. Let’s assume that, in doing business with other trading partners, you’ve already defined a MIG with the customized message: "PurchaseOrderMessage_Out" by using ICA's MIG editor. But you’ll need to adjust the integration content for connecting ConTrade Inc. by taking the following steps:
- Create a target MIG based on an ASC X12 Version 004010 transaction set 850 (Purchase Order). Make sure the requirements are as defined in the submitted PDF file from ConTrade Inc. (see attachment)
- Create a mapping from Lief's customized structure SOA:PurchaseOrderMessage_Out (source MIG) to ConTade's ASC X12 Version 004010 850 represented as a target MIG.
- Create an integration flow with the required integration steps for processing the Lief's SAP IDoc ORDERS05 payload to ConTrade's ASC X12 interchange covering the 850 transaction set using the ICA's generated runtime artifacts for processing.
- Deploy the integration flow on Lief's CPI tenant, and test it.
Take a moment to imagine the effort this process takes using a classic middleware system.
This blog shows how you can easily create the ConTrade's ASX X12 850 purchase order using the ICA's MIG editor. You can then use the MIG as the target structure of the mapping (how to do this quickly, using the ICA’s MAG editor will be explained in the next blog).
Create a new message implementation guideline (MIG)
This section explains how to create the purchase order MIG according to the requirements from ConTrade, so that you can use it as the target for your mapping guideline.
Select a message template in type system ASC X12
The only way to create a new MIG is by using the library of type systems. Open it, as shown in Figure 01.
Remark: A future release is scheduled to include a Create button in the Message Implementation Guidelines component, which will allow you to select the message type using a wizard.
Figure 01: Open the library of type systems
You see a list of the available type systems. If you’ve already purchased ASC-X12 from the SAPStore you’ll see it listed here, with a provision type of Licensed (see (1) in Figure 02). You can open the library from here by selecting it (see (2) in Figure 02).
Remark: How to purchase libraries of B2B type systems from the SAPStore will be explained in a future blog.
Figure 02: Open the type system ASC X12, if you’ve already purchased it
There are two different ways to get to the required message ("Transaction Set"):
- Click the VERSIONS tab to see only the version-related content (see (1) in Figure 03).
- Click the MESSAGES tab to see all versions of all messages (see (2) in Figure 03).
Figure 03: Overview page for the ASC-X12 type system
Figure 04 shows the page I see after selecting the VERSION tab. Select the version 004010, as it’s the one required by ConTrade Inc.
Figure 04: Available versions of ASC X12
Figure 05 shows all messages that are available in version 004010. You can filter the list by entering a value such as 85 in the search field (see (1) in Figure 05). Click to the icon for creating a new MIG to the right of the message entry "850 - Purchase Order" (see (2) in Figure 05).
Figure 05: Select message 850 in version 004010
Remark: There is another entry point to create a MIG. Navigate to the overview of the MIGs and select “Add” You will be navigated through with a Guided activity by selecting the Type System, Version and Message as well the mandatory and optional fields described in the Figure 06 below
Dialog window: Create New Message Implementation Guideline
Once you’ve clicked on the icon for creating a new MIG,enter the following information in the dialog that appears (Figure 06):
- The name of the MIG (see (1) in Figure 06)
- The direction, which describes the direction from your point of view (see (2) in Figure 06):
- In - the direction from which your system receives and processes the incoming payloads.
- Out - the direction in which your system submits the payloads to the receiver, in this case to the trading partner
- Both - if the direction is not relevant.
- A summary that briefly describes the scope of the MIG (see (3) in Figure 06)
- Own business context (see (4) in figure 6)) - the context in which the MIG is used; in our scenario, for Lief GmbH. The business context is described in "Set business context," below.
Figure 06: Define the overview parameters of the new MIG
Version, Status, Message Type, Type System and Type System Version (see (5) in Figure 06) are automatically set, and can’t be changed here.
Set business context
The business context is the formal description of a specific business circumstance in where the business message should be used. This business context is identified by values of a set of business context categories, allowing different business circumstances to be uniquely distinguished.
Therefore, the business context is an important part of the MIG, labelling it so that the system can give you an appropriate proposal based on the defined business context. It will also be used to provide statistical information in future releases of ICA. You must set at least one business context value. ICA currently provides five different business context categories, each with a list of corresponding values, that you can use to set your own, and your business partners’, business context for your customized MIG. These business context categories are:
- Business Process - the most important aspect of a business situation is usually the activity being conducted. Business process context provides a way to unambiguously identify the business activity.
- Product Classification - describes the aspects of a business situation that are related to the goods or services affected involved in the business process.
- Industry Classification - the industry or subindustry in which the business process takes place.
- Geo Political - describes aspects that are related to region, nationality, or geographically based cultural factors. The starting point of the geo political context category is country.
- Business Process Role describes the aspects of a business situation that are specific to an actor or actors within the business process.
Remark: The business context categories and values will be extended in future releases, based on user/customer requirements.
Each business context category can have one or more business context values from a finite list of values. We recommend that you set business context categories and their business context categories with as much specificity as possible. The accuracy of the proposal depends on the selected number of business context categories and business context values. As more business context categories and values you selected as tighter will be the proposal.
First, set the business context for your side of the business transaction. Click the [+] button to the right of "Own Business Context" (see (1) in Figure 07), select the business context category , then enter the appropriate business context values, such as:
- Industry: Consumer Products
- Product Classification: Food and beverage industries
- Geo Political: Germany
- Business Role: Buyer
Business context values are autosuggested as you type (see (2) in Figure 07).
Figure 07: Set own business context
For your trading partner, set the following business context categories and business context values in the Partner Business Context area (Figure 08):
- Industry: Consumer Products
- Product Classification: Food and beverage industries
- Geo Political: United States
- Business Role: Seller
Figure 08: Set business partner's business context
When you click Create (see (1) in Figure 08), you'll get a new MIG which can be edited now. How to edit a MIG will be explained in the next chapter.
Edit MIG
The starting point for your new MIG is the overview page in view mode (see Figure 09).
Figure 09: Overview page for the new MIG
The definition (see (1) in Figure 09) is from the message template provided by the type system. If the MIG is in edit mode - click Edit to get there (see (2) in Figure 09)—you can change this definition, as well as other values.
A significant part of the customization entails selecting the required elements—for example, those that are defined in the PDF file from ConTrade Inc. Select the STRUCTURE tab (see (3) in Figure 10) to see the overall structure of the message template.
Figure 10: Default view of the structure after creating MIG
Figure 10 shows, on the right, the page with the message type structure overview of the PDF file. Select only the segments from this page that you need in your customized MIG.
Expand and collapse structure
A structure includes a number of element groups, which are also known as segment groups, segments, or loops. Expand these groups by clicking the expand icon (see (1) in Figure 11); this opens the direct child elements and does not display deeper hierarchies.
Figure 11: Expand one level
ICA also allows supports a full expansion of the complete structure. Select a group node, right-click and select Expand All (see (1) in Figure 12) to open the entire nested structure, starting from the selected root node.
Figure 12: Expand all
Close the nested structure by selecting Collapse All from the context menu (see (2) in Figure 12).
Select and deselect elements
You can now go through the entire structure and select the required elements by selecting the check box next to each (see (1) in Figure 13). If an element isn’t required, you can deselect the corresponding check box.
Figure 13: Select elements
Remark: Mandatory elements and their mandatory child elements are preselected.
Show only selected structure
To see only a selected structure, select the Node column header. This opens a submenu from which you can select Show Selected Nodes (see (1) in Figure 14), to see the structure you’ve selected showing by the checked check-boxes.
Figure 14: Show only selected elements
Each column header also has a filter feature that lets you limit the nodes you see to only those that match a string you enter. A filtered structure always shows all levels up to the root node.
Show and edit element details
Each element also includes detailed information, which you can change. To reach the details, select the line of the specific element, such as “100 - Currency Code” as shown in Figure 15. This opens the details panel, where you can view and change the parameters using the DETAILS tab (see (2) in Figure 15); change, add, or modify additional notes using the NOTES tab (4); and maintain a related codelist (if any) using the CODELIST tab (5).
Figure 15: Edit element details
Figure 15 (3) shows a section that’s labelled "Qualifiers". The qualifier approach can be useful for precisely expressing the semantics in the structure by building qualified variations. This approach is fully explained in Qualified variations. To build a qualified variation, you need a data element that another element, which can be a parent group element or another element at the same level. If a data element has a codelist, you can use the data element to qualify another element. The qualifier feature lets you set a qualifier marker that identifies the element that is qualified by this data element. This qualifier marker appears as a gray arrow. For example, you can set another qualifier marker from the data element "100 - Currency Code" to any ancestor element or to the data element "98 - Entity Identifier Code" which is at the same level.
You'll find many qualifier markers that are already set in the template structure. You can change or delete any of these predefined markers. We’ll explain more about the power and use of qualifiers in one of our next blogs, which describes the best practices the setting and usage of qualified variations more precisely.
Select and deselect code values
If a data element includes a reference to a codelist, it (the codelist) can be for the data element. Click the CODELIST tab, which you can see as long as there is a codelist that is referenced When you open the tab, you'll see a list of all code values as shown in Figure 16 (for codelist ISO 4217 - Currency Codes). By default, all code values are selected. You can deselect all code values by choosing Select All (1). The filter box (2) lets you filter the code values that match the string you enter (“Dollar” in the example).
Figure 16: Select required code values
Use the checkbox beside each code value to select or deselect it (3).
Remark: If the data element doesn’t have a reference to a codelist but you need for that node a specific codelist, you can create your own codelist. How to do this will be explained in separate blog that addresses qualifiers and codelists.
MIG proposal service
To customize an interface quickly, simply click Get Proposal (see (1) in Figure 17). You’ll see proposals for the most relevant elements in this structure for your set business context. Figure 17 shows the initial view of the proposal result in the "Proposal Indicator" column. Each element includes a bar chart that shows the confidence level for this element in the set business context (2).
Figure 17: Proposal of most revelant elements in set business context
Some of the elements that are used in this business context include an icon (3) for showing the qualified variations. Since most of the elements are used with qualified variations, the proposal indicator is currently quite low. The concept of qualified variations is described in chapter Get Proposal of Qualified Variations.
Remark: A future release is scheduled to also show the highest confidence ratio in the initial view, including the variances.
Qualified variations
Qualified variations is a powerful feature for defining the semantic different variations of same groups more precisely. It provides the required semantics to semantically generic element groups (in case of ASC X12: Segment Groups and Segments) and to peer/leaf elements by a reference to an element which has a codelist for the definition of the different variations of this element group or peer/leaf elements. Furthermore, it makes the mapping in the mapping guideline (MAG) much simpler. In other words, you'll get rid of the most complicated functions used in classic mapping tools because of the specific handling and mapping of elements / child elements provided by the qualifiers. This will all be explained in the upcoming blog-post “Integration Content Advisor (ICA): Create mapping using the MAG editor."
This section briefly describes how to use qualifier variations considering the ConTrade’s requirements as defined in their PDF based MIG, such as the definition of qualified N1 (Name and Address) segment groups described ##LINK##.
Figure 18: First qualified N1 segment group with qualifier value "BY - Buying Party"
Figure 19: Second qualified N1 segment group with qualifier value "SU - Supplier/Manufacturer"
For example, the first qualified segment group with qualifier value "BY - Buying Party" has further child segments. These semantic variations lead to many complex functions in a mapping.
Get proposal of qualified variations
The new innovative qualification approach that ICA uses increases the readability of the specifications and reduces the number of mappings. The proposal service also supports the setting of qualified variations by providing the most probable used qualifier values provided for the given business context. To explain the proposal service, I’m using the example from Qualified Variations.
As shown in Figure 20, the segment group N1 as defined in the ASC X12 standard provides the name, address, and any additional information for a party. This is quite generic, because it’s unclear whether the “party” is a buyer, a seller, a ship-to address, and so on.
Figure 20: Standard segment group: Loop N1
Semantic precision is provided via a child data element, which has a codelist that provides different qualifier values. This child data element, such as a segment group, is shown by the arrow--that is, the qualifier marker (see (1) in Figure 21).
Figure 21: Qualifier markers represented by arrows (1)
However, the codelist of data element 98 - Entity Identifier Code- has 1312 different code values. This means there can be as many as 1312 different variations of a party at the semantic level. Additionally, each qualified variation can also have a different substructure. Until now, only business domain experts with a deep knowledge of ASC X12 could provide the appropriate semantic precision. But now, with the ICA proposal service, you can get the most probable qualifier values that you need by clicking on the value help button besides the chart bar in the proposal indicator column (see (2) in Figure 21).
This button opens a dialog window where you can see the qualifier values that have the highest proposal value (see (1) in Figure 22). Simply select the qualifier values that are assigned the highest probability (2) and select Apply (4):
Figure 22: Dialog window shows the qualifier values with the highest confidence
As shown in Figure 23, ICA generates one qualified variation per selected qualifier value (1) and shows the meaning of each qualifier next to the name of each variation (2).
Figure 23: Definitions of qualified variations of segment groups.
Select substructures of qualified variations
If you expand the qualified variations, you'll see that in each variation, different child elements (in this case, segments) are proposed or not used (see Figure 24). For example, frequently used segments in the qualified variation: N1 - Loop N1 - Ship to (1) shows the segments that have a higher confidence as N1 - Name, N2 - Additional Name Information, N3 - Address Information, N4 - Geographic Location, and PER - Administrative Communications Contact. In contrast, the other qualified variation, N1 - Buying Party (Purchaser) (2) includes these frequently used segments: N1 - Name, N2 - Additional Name Information. The segments N3 - Address Information and N4 - Geographic Location have a lower confidence in this qualified variation. Segments that might have qualified variations, such as REF - Reference Identification, have specific proposals of qualifier values that belong only to the qualified variation of the segment group (N1 - Loop N1 - Buying Party (Purchaser). REF - Reference Identification has in this segment group the frequently used qualifiers SW - Seller Sale Number and 4N - Payment Terms Identifier.
Figure 24: Selected qualified variations with their proposed child elements
Final interface structure - further features
Once you’ve finalized your structure, you can save the new MIG (see (1) in Figure 25); it will then be included in your MIG overview list. You can now use it to create a mapping guideline (MAG), for the generation of a PDF document, (2) or for the generation of the runtime artifacts, which can be used as rules for syntax conversion; for example, from XML to ASC X12 syntax representation, precise payload validation according to all defined restrictions in the MIG, or preprocessing.
To submit the finalized MIG into the ICA's knowledge base, select Activate for productive use of the MIG in production systems. A proposal is calculated by contributions made by you as a user. Once you click Activate, the customized structure of the MIG is pushed into the central knowledge base in an anonymized manner. Changes are merged with other contributions, which means that the source of the published data isn’t traceable.
Remark: The Activate feature is scheduled to be automated in a future release.
Figure 25: View of the structure according the final business needs
Select Documentation, as shown in Figure 25 to create a PDF file similar to the following link:
Generated Message Implementation Guideline as PDF by Integration Content Advisor
Summary
This blog is an overview for quickly creating a MIG by using the proposal service. ICA provides features for creating more precise semantics and constraints, as well as for defining additional constraints. Building qualified variances has too many possibilities to cover in only one blog. For this reason, we have planned additional blogs that will provide best practices for finalizing MIGs according your individual business needs.
A created MIG can be now used to build a mapping guideline (MAG). How to create a MAG using the ICA’s MAG editor will be explained in the next blog. Let me just say that the MAG editor has also a lot of power for creating mapping guidelines much quicker.
Glossary
A2A – Application to Application
ASC X12 – Accredited Standards Committee X12, a frequently used B2B standard in USA
B2B – Business to Business
ICA – Integration Content Advisor
MAG – Mapping Guideline. It is the specification of a mapping between a source MIG and target MIG
MIG – Message Implementation Guideline. It is the specification of a customized message interface including all details.
SOA – Service Oriented Architecture
WSDL – WebService Definition Language
Further Reading
- integration content advisor: Discover B2B/A2A standard libraries
- Announcement: New integration content advisor for SAP Cloud Platform Integration
- SAP Help Portal – integration content advisor for SAP Cloud Platform Integration
- B2B Capabilities in Cloud Platform Integration
- B2B Capabilities in SAP Cloud Platform Integration – Part 1
- SAP S/4HANA Cloud EDI Integration Strategy
- SAP Managed Tags:
8 Comments
