How to avoid typical errors in interface descriptions

As we develop EDIFACT test interfaces on the basis of existing manuals, we read instructions on the required structure of EDI messages several times a week. Over time, we have noticed that certain errors or inaccuracies appear frequently in interface documentations. If you avoid these pitfalls, you will make it easier for your partners to start exchanging data with your company.

One of the peculiarities of EDIFACT is that several segments are bundled into a group at various points within a message. Each segment group has its own status, which is independent of the status of the segments it contains. If the segment group as a whole is optional, the segments it contains do not necessarily have to be set in the message, even if they all have the status “mandatory”. You could also say “A segment group can be optional, but IF the group is to be displayed, the mandatory segments it contains must be set.”.

This also applies to segment groups that are contained in a higher-level segment group. If the subordinate segment group is optional, the segments it contains do not necessarily have to be set in the message, even if the superordinate segment group is mandatory. You should therefore check each time you revise a manual whether not only the status of the segments but also that of the segment groups is set correctly.

A very similar logic also exists within the segments: A segment can contain one or more composite data elements. These in turn bundle data elements, which then contain the actual information. As composite data elements also have a status independent of the status of the data elements they contain, you should make sure that this is correct.

Many manuals include different characteristics of a message. Which segments are to be set and which data elements are to be filled depends on what the message is supposed to represent. In the manual, this is expressed in the fact that a segment or data element is given the status “dependent”, often abbreviated with a “D”. The problem is that there is often no explanation of the circumstances under which the segment or data element must be set. As a result, the message implementer has to query this knowledge elsewhere or estimate what to do based on his experience. Neither is ideal, so each dependent element should be accompanied by a brief explanation of when it should be set. The explanation does not even have to be in the manual itself; a reference to another document or a website may suffice.

Each data element in EDIFACT has default values for the minimum and maximum length of its content and for its format. The format specifies whether numbers, letters or both may be placed. However, the editors of a manual may adapt these standards to their needs. You should make full use of this option, as it allows you to provide your partners with additional assistance when implementing their mappings. For example, if a data element is alphanumeric in the standard and can have a length of 1 to 35, but an eight-digit number is to be inserted here in your guideline, it makes sense to overwrite the standard values accordingly. This also helps us: during message validation, we also check the field lengths and format. If these are already shown correctly in the manual, we can implement the test interface more quickly.

Example messages are generally very helpful for implementers. With their help, it is easy to recognize how content interacts and how the message should basically look. However, they also have their pitfalls: for example, if the sample message is forgotten to be adapted accordingly when the manual is updated. This risk increases with the number of sample messages. Paradoxically, the good intention of providing as many examples as possible can lead to your partners being slowed down in their mapping development by outdated examples.

Another pitfall is uncommented examples for an interface that covers various business processes. It can be difficult to assign the example messages to the respective processes. In the worst case, this can lead to a partner developing a mapping incorrectly and having to revise it several times. It may therefore make more sense to provide fewer examples, but to carefully curate and comment on them.

Complaints about master data errors are ubiquitous in data exchange, regardless of the industry or specialist area. However, you can avoid at least some of the errors if you provide and manage the lists with the specified values centrally for your partners. The reason: if the same values, for example unloading points, are stored in different manuals, there is a high risk that not all documentation will be updated in the event of an expansion. If, on the other hand, you only store the reference to the lists in the manuals - for example in the form of a URL - you can be sure that your partners will find the appropriate values. Building on this, you could develop a system that automatically informs stakeholders about updates to the value lists.