Introduction
The MIG is used for the precise specification of how a message interface should be customized and refined so it refers only to the aspects of the final business needs at the semantic level. Customizing an interface is described in Integration content advisor: Create a customized interface using MIG editor. If you examine a customized interface in detail, you’ll see that codelists and their code values play a significant role not only in the MIG, but also in the mapping guideline (MAG) in which you use the MIG, at either the source or the target side. A codelist is a stable collection of code values that’s maintained by a responsible agency. Codelists can be used in several ways:
- A fixed list of commonly used acronyms and abbreviations that provides a common understanding of the names, meanings, or objects that are represented by code values; for example, the country codelist.
- Shorter representation and controlled list of methods, conditions, or rules, that provides the system further instruction for processing or validating data; for example, the status list, which tells if something is new or in progress.
- List of qualifying values that provide a more precise meaning to semantically generic elements in an interface; for example, the qualifiers for the generic group “Party” might be “seller” or “buyer.”
Codelists require consideration when you use them MIGs, for the following reasons:
- Code values must be mapped from the source side to the target side in a mapping guideline (MAG).
- Code values are used as qualifiers that make MIG semantics more precise. This approach will be explained in a future blog.
- Code values are used when generating, processing, or validating payloads.
This blog explains how to use, create, and maintain codelists via the ICA's MIG editor.
Remark: All the following examples are based on the type system "ASC X12". The MIG example is similar to the one used in other blogs and is based on the message type 850 (Purchase Order) in ASC X12 . The fictitious trading partner who is using this message is "ConTrade Inc.," located in the United States. Types of codelists
The ICA currently distinguishes between three different types of codelists:
- Reusable - some type systems are codelists only, which are provided and maintained by international standardization organizations or software providers. You can use these codelists in MIGs that are based on any type system. For example, the ISO 3166 - Country name codelist can be used in MIGs that are based on SAP IDoc, SAP SOA, or even UN/EDIFACT.
- Type-system related - these codelists belong only to a single type system such as SAP IDoc or UN/EDIFACT. You can use these codelists only in MIGs that are based on the same type system. .
- Local - locally defined MIG-related codelists that can be used only in a MIG in which the local codelists are defined independently of the type system.
Remark: It is planned to provide a global codelists feature that allows to reuse own defined codelists across all MIGs in your own workspace.The following figure shows the codelists that are provided by the ISO (International Standardization Organization). You can use these codelists in MIGs that are based on any type system.
Figure 1: Reusable codelists across type systems
Codelists in a new message implementation guideline (MIG)
If you create a new MIG like the one shown below for the North American trading partner ConTrade,(based on ASC X12 purchase order 850), you’ll see the inherited structure from the template if you open the context menu at the root node and click "Expand All" (see (1) in Figure 2). You can also see all elements that already have a reference to a codelist, indicated by the checkmarks in the Codelist column (2).
Figure 2: Elements with references to codelists
Filter to leaf elements with codelists
You can also filter the structure to see only the leaf elements with codelists. Click the Codelist column header (see (1) in Figure 3) and enter your filter text, for example, “true.” (2). Click "Return" to see the filtered structure that shows only those leaf elements with references to codelists (3) and their ancestors.
Figure 3: Filtered structure with elements having references to codelists
Type of codelists from template
A new MIG that uses a structure that’s inherited from a template has two types of codelists:
- Reusable codelists such as the ISO based country code, language code, and currency code as well as the UN/ECE-based measure unit code
- Type-system-related codelist, which is provided by the type system itself
You can see the difference if you choose an element that refers to a codelist such as "100 - Currency Code" by clicking with the mouse in the line (see (1) in Figure 4). This shows the details panel for the chosen element (2). Open the "Codelist: …" tab (3) to see that the codelist is from type system "ISO" (4), which is reusable. The latest version of the ISO currency codelist is automatically considered (5). The tab also shows the definition and additional details about the codelist (6), including all its code values. (7). Each code value entry includes its acronym or abbreviation, the human readable name, and possibly additional definition information.
Figure 4: A reusable codelist (ISO 4217: Currency Codes)
In comparison, a type-system related codelist uses the same type system name as the type system of the chosen message type. In our case, this is "ASC X12." You'll see this if you choose the element "640 - Transaction Type Code" (see (1) in Figure 5) and open the “Codelist:…” tab (2). This codelist is from the type system (3).This codelist is always at the current version (4), which means that codelist has the same version as the version of the selected message type, which is in our case "004010."
Figure 5: A type-system related codelist (640: Transaction Type Code)
Select elements with referenced codelists
If you select an element with a referenced codelist, such as the "100 - Currency Code" (see (1) in Figure 6), you’ll see that you can now select or deselect all code values (2)(3).
Figure 6: Selected element with referenced codelist
Sort code values
You can sort code values alphabetically or numerically by clicking the sort button (see (1) in Figure 8). This sorts the entire list in ascending or descending order. The number in brackets (2) always shows the number of listed/filtered code values.
Figure 7: Sorted code values in descending order
Filter and select single code values
If you’re looking for a single code value, you may want to filter the list. Enter a code value, name, or definition, such as "Euro" (see (2) in Figure 7) in the search box. Note that the returned entries include the string you entered. From here, you can select the required code value (2).
Figure 8: Filtered codelist
Sort selected code values
The system sorts selected and unselected code values separately, if you’ve already selected several code values. For example, if the currency codes Chinese Renminbi (CNY), Euro (EUR), and US Dollar (USD) are selected and you click the sort button (see (1) in Figure 9), the selected code values are at the top of the sorted results (2) and the unselected ones appear following the selected ones (3).
Figure 9: Sorted selected and unselected code values in ascending order
Create and maintain local codelist
A local codelist is necessary if the reusable or type-system related codelists don’t support user-specific requirements, or if the user already has a specific codelist that must be considered in the MIG. A local codelist can be referenced by any leaf element in the MIG in which it’s defined.
Create a new codelist
Click the “Local Codelist” tab (see (1) in Figure10) in your already selected MIG, which is in edit mode. Click "Add" (2) to open a new entry in the "Local Codelists" section where you can enter the codelist’ s identifier (3), its human readable name in English (4), and a short description (5).
Figure 10: Add a new codelist
Remark: You can change any of these values (including the codelist identifier) or delete the entire codelist if you are in edit mode and if have been defined.Click the new codelist entry (see (1) Figure 11) to add code values.
Figure 11: Enable panel for adding code values
This opens a new details panel for the codelist. Click "Code Values" (see (1) Figure 12). Click “Add” (2), enter the code value (3), the human readable name (4), and optionally the definition (5). Repeat this step to add all the required code values.
Figure 12: Added code values to codelist
Don’t forget that you can search for or filter on code values, sort in ascending or descending order, or change or delete any code values or entries.
Assign codelists to leaf elements
You can assign reusable codelists or local codelists to leaf elements that:
- Don't have a reference to a codelist, or
- Already have a reference to a type-system related codelist or a reusable codelist.
Assign local codelist
Before assigning a local codelist to a leaf element, create at least one local codelist (See "Create and maintain local codelist"). You can assign your local codelist, if you are in MIG edit mode.
Select the leaf element to which you want to assign a local codelist (see (1) in Figure 13). In the details panel (2),click the "Codelist" tab (3). If no codelist is assigned to the selected leaf element, you see "None" in "Selected Codelist" (4). For example, the selected leaf element "325 - Tax Identification Number" doesn’t refer to any codelist. Click the add (+) button (5) to assign a new codelist.
Figure 13: Add a new reference to a codelist
The next window shows that "Local Codelists" is already set (see (1) in Figure 14) and that the local codelists are already listed. Select the required codelist such as "NatlTaxIdCodes" (2).
Figure 14: Select local codelist
You see the details for this codelist on the "Codelist: …" tab (see (1) in Figure 15). The assigned codelist appears in the tab name (2) as well as in the “Selected Codelist” field (3). You can select the required code values for this leaf element (4).
Figure 15: Customize assigned codelist
In the structure view, you'll now see that this leaf element also has a reference to a codelist (see (1) in Figure 16).
Figure 16: Assigned codelist in structure view
Assign reusable codelist
You can also assign reusable codelists to leaf elements. Select the leaf element to which you want to assign a reusable codelist. Figure 17 shows the leaf element "355 - Unit or Basis for Measurement Code" with an already assigned codelist (1). You can assign additionaly codelists here, which can be individually selected afterwards.
To add a codelist, click the add (+) button (2).
Figure 17: Leaf element with already assigned codelist
In the next window, select "From Type System" (see (1) in Figure 18) and select the type system, which provides your required codelist (2). You see the available codelists of this selected type system (3) from which you can select your required codelist (4).
Figure 18: Select a reusable codelist
Once you’ve selected a codelist, you see all its details in the "Codelist:…" tab (see Figure 19). You can customize this codelist as discussed in "Select elements with referenced codelists."
Figure 19: Select a reusable codelist
Switch between assigned codelists
If a leaf element has more than one assigned codelist, you can easily switch between them. The selected codelist is the actual codelist, which can be customized. In this example, the codelist "Rec_20 - Measurement unit code" is the second referenced codelist assigned to leaf element "355 - Unit or Basis for Measurement Code" (see (1) in Figure 20). You can switch to “None” or to codelist "355 - Unit or Basis for Measurement Code."
Figure 20: List of assigned codelists
If you select "355 - Unit or Basis for Measurement Code", you see its details (Figure21), which can be individually customized.
Figure 21: Another selected codelist
Unlink codelist
You can delete an assignment to a codelist, simply by clicking the delete () button (see (1) in Figure 22).
Figure 22: Delete an assignment to a codelist
If the assignment you delete is the only one, you'll see the default entry, which is “None” (see Figure 23).
Figure 23: View after deletion of assignment
Remark: You can change to another assigned codelist, if this element had at least two assigned codelists before you deleted one.If the value in the selected codelist is “None,” you see the codelist marker in the structure (see (1) in Figure 24).
Figure 24: None codelist is used
Summary
Codelists are an elementary and important part of MIGs, because in many cases the final meaning of leaf elements are just provided together with code values. For example an element “Unit or Basis of Measurement Code” provides with its codelist the measure unit codes and the meaning of these codes such as “Kilogram”, “Meter”, or “Piece”. However, not all code values are required for expressing final business requirements in a MIG. Therefore, the ICA provides a number of features for assigning and customizing codelists. It is recommended to assign and customize all the required codelists in your MIGs. This especially makes the understanding of the message implementation guidelines and the further use in mapping guidelines much easier. Because the focus of mapping guidelines is primarily on the aspects and semantics of customized the message implementation guidelines. This also includes customized codelists.
The next blog post will describe the power of qualifier references, especially those references that use codelists They provide a precision to elements that don't have an exact meaning, such as "Buyer" for "Party" or “Delivery" for "Date and Time." Qualifier references are only one example of the importance of implicit coverage of meanings via codelists. This makes understanding and implementing integration content much simpler. Stay tuned.
Glossary
- A2A– application to application
- ASC X12– Accredited Standards Committee X12, a frequently used B2B standard in the USA
- B2B– business to business
- codelist – a fixed list of code values maintained by a responsible agency
- code value - an acronym, abbreviation, shortcut, symbol, or number that represents a name, meaning, or instructions
- ICA– integration content advisor
- MAG– mapping guideline. The specification of a mapping between a source MIG and a target MIG.
- mapping entity– a single mapping between the directly involved elements at the source and target sides.
- MIG– message implementation guideline. The specification of a customized message interface, including all details.
Further Reading
General
- Announcement: New integration content advisor for SAP Cloud Platform Integration
- SAP Help Portal – integration content advisor for SAP Cloud Platform Integration
Type system related
MIG related
MAG related
Runtime artifacts related
B2B related
- SAP Managed Tags:
