integration content advisor: Discover B2B/A2A standard libraries

[gunther_stuhec]

Introduction

The integration content advisor (ICA) for SAP Cloud Platform Integration (Announcement: New integration content advisor for SAP Cloud Platform Integration) includes a number of useful features for effectively creating and maintaining integration content. An important aspect of the ICA is the extensive provisioning, from a single place, of all required information for building interface customizations or mappings.

The starting point for creating a customized B2B interface is a standard message type structure, usually provided by a standardization body. However, there are many different B2B standards, and often, message descriptions are either located in various sources, or the required information isn’t directly accessible. Another disadvantage is that content may be represented in various formats and medias, such as HTML, PDF, XSDs, and so on. This makes creating a customized B2B interface even harder, because the most important part of this task is the unambiguous understanding of the meaning of each element of a B2B standard message.

The ICA is a single place with a collection of all B2B/A2A standard content for the building of customized interfaces and mappings. This is called library of type systems. The blog explains what a type system is and how to access the various content that’s available for each type system.

What is a Type System?

A type system consists of two parts:

• The rules and methodology for defining the syntax, structure and naming of message interfaces and data types, as well as


• The library of message interface and data types that are based on these rules

A responsible agency must be responsible for both, the rules and the content management of the libraries. There are various agencies which B2B (Business-to-Business) or A2A (Application-to-Application) type systems based on a specific syntax representation, such as XML or JSON. Typically,  agencies that offer type systems are standardization bodies such as ISO, UN/CEFACT, ASC, and so on, or software vendors, like SAP SE.

The intention of ICA is to provide various type systems and their complete content in a single place, independent of syntax and methodology. The focus is on the common and comprehensive representation of the type system content, as well as on the semantics (business meaning), providing users with a clear understanding of all content.

Library of Type Systems

The library of type systems shows a collection of available B2B or A2A type systems in a central place. You can reach the collection of type systems by clicking "Library of Type Systems" on the landing page of the Integration Content Advisor (Figure 01).

Figure 01: ICA's landing page

 

ICA currently includes the following type systems (Figure 02):

• ASC X12 –  A highly adopted B2B standard in the USA, released and maintained by Accredited Standards Committee X12. Must be purchased from the SAP Store.


• ISO Codelists –   Internationally accepted codelists that are developed and maintained by the International Standardization Organization (ISO). These codelists are frequently used in the message types of B2B standards.  The ISO codelists are for free.


• UN/EDIFACT –  Frequently used international B2B standard called "United Nations/Electronic Data Interchange for Administration, Commerce and Transport" (UN/EDIFACT). Must be purchased from the SAP store.


• SAP IDoc –  SAP Intermediate Document is a SAP document format for business transaction data transfers used in SAP R3 and SAP S4HANA. Is freely available, from the ICA.


• UN/CEFACT –  Trade facilitation recommended codelists. Also freely available, from the ICA.

Figure 02: List of available type systems

SAP will make additional type systems available on demand or even on request. We have many B2B standards like cXML, OAGIS, UBL, ISO 15022, ISO 20022, xCBL, CIDX, PIDX, TRADACOMMS, VDA, ODETTE, and so on, in our pipeline. We’ll also soon offer subsets like EANCOM, EDIFICE, HIPAA, and so on.

The following sections explain the detailed content of type systems:

• Overview – General information about the type system.


• Version – The currently available versions of the type system content.


• Messages – Defined messages, their structures, and definitions.


• Complex Types – The reusable complex structures that are used to assemble a message.


• Simple Types – The reusable simple types that define the characteristics and properties of leaf elements.


• Codelists – The codelists with their code values.

Each type systems might not have content in all of these categories. For example, the type system "ISO - Codelists and Scheme" contains only codelists.

Overview of a Type System

If you select one of the type systems, such as UN/EDIFACT, you’ll see an overview for it (Figure 03).

The overview includes some general information, such as the responsible agency, and which partner provides the content to SAP. It also includes some additional information about the system’s intention and scope,  and the copyright statement.

Figure 03: Overview page of the type system: UN/EDIFACT

Versions

SAP’s intent is to publish all versions for the provided type systems in 2018. Our starting point for the first release is a few frequently used versions; for example, for UN/EDIFACT, D.96A, D.98A and D.01B. The currently available versions are shown on the VERSIONS tab (Figure 04).

Figure 04:  Available versions of  the type system UN/EDIFACT

Click a version to see list of messages, complex types, simple types, and codelists for that version. The following sections describe each tab from a version-independent point of view, which you see by selecting the appropriate tab: MESSAGES, COMPLEX TYPES, SIMPLE TYPES, and CODELISTS.

Messages

The main purpose of a responsible agency of a B2B standard is the development and maintenance of standardized messages for performing document transactions between two business partners in an electronic manner. These messages are also known as message types (for example, UN/EDIFACT) or transaction sets (for example, ASC X12).

Click the MESSAGES tab to see a complete list of messages (Figure 05). Expand a message entry to see a list of available versions for this message. You can create a new message implementation guideline (MIG) by clicking the create button on the right side of the version entry. How a MIG is created will be explained in the next blog, to be published shortly.

Figure 05: List of messages of UN/EDIFACT

Click the expand button To see message details, click a version entry, such as D.01B S3 (Syntax Version 3) for the message "ORDERS - Purchase Order Message."

Message - STRUCTURE Tab

After opening message details, you can see the structure of the message type by selecting the STRUCTURE tab. By default, the first level after the root node is expanded, and you can see, in case of the UN/EDIFACT ORDERS, the first-level segments and segment groups in this message, representing all content in this message as defined by the UN/EDIFACT (compare with: http://www.unece.org/trade/untdid/d10b/trmd/orders_c.htm). You also see the cardinality and position of each segment, segment group, or other kind of element group. A message is usually based on:

• Local defined groups like "Segment Groups" in UN/EDIFACT or ASC X12. These groups only belong to a message and are composites used to assemble a message so it individually considers the aspects of a business document (Figure 06). You'll find more information about general aspects of an assembly at:  Core Components Business Document Assembly


• Groups that are based on reusable complex types, which can be used across the message types or other complex types within the same type system. Complex Types has more details about the complex types.


• Leaf elements that are based on reusable simple types. These simple types give the restrictions of a leaf node as defined by the responsible agency. They are also reusable across the message types or complex types across the same type system. Simple Types explains them in more detail.

The following UML like example (Figure 06) shows the interaction of messages, local defined groups, complex types and simple types. It shows two different UN/EDIFACT messages: ORDERS (Purchase order message) and PRODAT (Product data message). Both of them have a same set of entities that are based on the same reusable complex types such as UNH (Message header), BGM (Beginning of message), and DTM (Date/time/period). Therefore, these complex types are reusable and have a further substructure of nodes that are based on reusable complex types or simple types. You'll find the list of reusable types within tab "COMPLEX TYPES" and "SIMPLE TYPES". The two messages also have two different local defined groups with the name SG1 (Segment Group 1). These are composites of the messages and provide a substructure that belong to the individual message, only. The SG1 of message ORDERS has two different child nodes: RFF (Reference), and DTM (Date/time/period), than the SG1 of message PRODAT, which has the child nodes TRU(Technical rules), and DTM (Date/time/period).

Figure 06: Interaction of messages, local defined groups, complex types and simple types

The assembly of a message in ICA is shown in Figure 07. It shows the first level of child nodes of the ORDERS message represented as a hierarchical structure. These child nodes are either based on complex types such as UNH (Message header), BGM (Beginning of message), and DTM (Date/time/period)or represent local defined groups such as SG1, SG2, etc.

Figure 07: Default view of message details displaying the message structure

The table of the hierarchical structure also provides further properties belonging to each node on overview level such as min .. max occurrence, and leaf node related properties such as primitive types, length, etc. This is explained in next section.

Expansion and Filtering

You can navigate through the structure and expand the segments and child nodes, as

shown in Figure 07 for "SG1 – Segment Group 1: RFF-DTM". There are two ways to navigate and get additional details. You can:

1. Expand and collapse the substructure (see Figure 08)


2. Filter by entering values at the header titles (see Figure 09)

Figure 08: Default view of message details displaying the message structure

The leaf data elements show additional information, such as the following elements that are called out in Figure 08:

• Primitive type – The defined primitive type, which is a normalized primitive type used in ICA. We’ll list all the possible primitive types and their properties in a subsequent blog, to be published soon.


• Syntax data type – The corresponding syntax data type as defined in the type system — UN/EDIFACT. The acronym “an” means  represents an alphanumeric data type.


• Length – The data elements’ defined min and max length of the value range.


• Codelist – Whether the data element refers to a codelist or not.

As mentioned above, you can filter the hierarchical substructure by entering values at the header title of the following columns:

• Node – Tag name and readable name are considered


• Cardinality – By using the convention n..m, where n is the min occurrence and m is the max occurrence


• Position – The position is based on the conventions of each type system


• Primitive Type – The ICA specific primitive type


• Syntax Data Type – The corresponding primitive type of the type system


• Length – By using the convention n..m, where n is the min length and m is the max length


• Codelist – By using the Boolean value "true" or "false"

Figure 09 shows results that include only the elements where the name or value matches the filter string "Reference". ICA also displays the ancestors of the filtered elements, visually showing how the filtered elements fit into the overall structure.

Figure 09: Filtered hierarchical structure

You can use a combination of values at the different columns. For example, if you enter "Reference" in the header "Node" and "1..14" in the header "Length", you ‘ll see only the elements with "Reference" in their names and a length of 1..14.

Element Details

Select an element (Figure 10) to show descriptions, behaviors, and properties of this element.

The NOTES tab at the top of the Details panel may include further comments, usage instructions, constraints, or usage examples.

Some leaf nodes may also have a link to codelists. If so, you can see details for them via the CODELIST tab.

Figure 10: Details of an on focus element

Select the CODELIST tab to see details for the linked codelist. Figure 11 shows details for codelist 1153; including general information, such as identifier, name, origin (type system), and definition. It also provides a complete list of code values, including names and possibly descriptions.

Figure 11: Details of linked codelist

The linked codelist doesn’t need to be from the same type system as the one that’s selected. Figure 12 displays the details of data element 3207 (Country name code), which is a link to the codelist ISO 3166-1 (Country name code), from type system "ISO - International Standardization Organization - Codelists and Schemes."

Figure 12: Node (Data element) refers to a ISO codelist

Message - OVERVIEW Tab

In addition to the structure, the ICA also provides general and detailed documentation for the message. The documentation is usually provided by the agency that is responsible for creating and maintaining the message. It is important that we provide all documentation and definitions, as this information gives you the meaning, scope, and usage instructions for each message.

Figure 13: General information and documentation for a message

Figure 13 shows the overview of UN/EDIFACT purchase orders message (ORDERS) version D.01B. It includes the definition that is also provided at: http://www.unece.org/trade/untdid/d01b/trmd/orders_c.htm. Messages from different type systems may have similar comprehensive definitions, depending on how much information each agency provides for each message. We provide only the content as provided by the responsible agencies; that is, we do not extend it, even if we’ve identified that doing so would be helpful.

Complex Types

A single message may be based on several reusable complex types. Each complex type has a structure of child elements that expresses the properties for an object such as "Partner," "Location," or "Address." These child elements can be based on further complex types, or they may be leaf elements that are based on simple types (see Simple Types). Reusability means that the same complex type can be used several times in the same message, or can be used across several message types or complex types within the same type system.

The COMPLEX TYPES tab lists all defined complex types of a type system (Figure 14). As with message representation, there two different ways to list the complex types:

1. Select the COMPLEX TYPE tab after selecting a type system. to see all possible complex types across all versions. The available versions are shown underneath each complex type.


2. Select the VERSIONS tab to see only the complex types that are defined for the selected version.

Figure 14: The overview list of complex types across all versions

ICA also presents the type-system-specific variations of complex types. For example, UN/EDIFACT uses the terms "Composite Data Element" and "Segment" (Figure 14). These complex types follow specific concepts as defined in ISO 9735 application-level syntax rules for syntax version 3 (see also http://www.unece.org/trade/untdid/texts/d422_d.htm or http://www.gefeg.com/jswg/v3/data/v3-guide.htm) for UN/EDIFACT. Other type systems might have different concepts for defining and shaping complex types. SAP's intention is to provide these complex types in the same way they are defined by the responsible agency.

Details of Complex Type

If you select one version of a complex type, you'll see its details. For example, Figure 15 shows the UN/EDIFACT complex type "RFF - Reference" with its all details.

Figure 15:  Structure of the complex type "RFF - Reference"

The representation of the content and structure as well as its behavior follows the same principles as described in Message - STRUCTURE tab and OVERVIEW tab.

Simple Types

A simple type is also a reusable type system, which defines the properties and value constraints of a leaf element that carries data in an instance. The properties can include, for example, the primitive type, the length, if a codelist is used, and further characteristics for expressing a simple value. A simple type can be used for leaf elements in complex types (see Complex Types) or in message types (see Messages).

The look and feel for representing simple types and their details is similar to messages and complex types.

Select the SIMPLE TYPE tab to see an overview page of the defined simple types for a selected type system. Figure 16 shows a list of simple types across all versions, or to see the simple types for a specific version, first select the VERSION tab.

Figure 16: Overview list of defined simple types

Figure 16 shows a list of UN/EDIFACT simple types that are filtered by having “11” in their tag name. This list also shows the most important properties such as the primitive type, length, and if there is a codelist reference.

Simple Type - Details

If you click a specific simple type, you'll see additional details, such as general information and documentation on the OVERVIEW tab.

Figure 17: Overview data of a selected simple type

The DETAILS tab shows the primitive type, length, and perhaps additional properties (Figure 18). Primitive types and their related properties will be explained in more detail in a future blog.

Figure 18: The details of a simple type

Codelists

The codelist is a fixed collection of coded representations (code values) for a business value, a name, a method, an integrity condition, a dimension, or a property description. Codelists are very common in business and trade and have been for a long time. The main idea of codelists is to simplify procedures by reducing the risks associated with international collaboration. A codelist is, for example,  a list of country codes, languages, or payment methods.

Each codelist must be maintained by a responsible agency. Only this agency can add, delete, or change code values or meanings, as change requests or other influences warrant. Only simple types refer to a codelist. A reference can be to a codelist in the same type system or to a codelist in another type system.

Select the CODELIST tab to see all codelists provided by the selected type system. Figure 19 shows the UN/EDIFACT codelists with names that include the characters “11”. Please consider, in case of UN/EDIFACT, an UN/EDIFACT codelist has the same identifier like the corresponding simple type such as 1153.

Figure 19: List of codelists

List of Code Values

If you select a version of a codelist, then select the CODE VALUES tab, you'll see the complete list of code values, including names and their definitions. The number designated in the tab title is the total number of code values in the selected codelist.

Figure 20: Code values of a codelist

Summary

This blog is an overview of type systems and their libraries. This content, especially the messages, is the basis for the creation of Message Implementation Guidelines (MIGs), in which a message interface can be customized according to business needs. In other words, these messages are the templates for the MIGs. How you can use these templates to create a MIG will be explained in the next blog.

The currently provided type systems, ASC X12, ISO Codelists and Schemes, SAP IDoc, UN/CEFACT Trade Facilitate Recommendation Codelists, and UN/EDIFACT are only the starting point. We’ll soon be providing additional type systems, with the same extent and quality of information. Stay tuned!

Further Reading

• 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