Validation Interfaces
We work with three kinds of validations: Syntax checks, validation rules and sub-processes. We separate these checks to create feedback that is as precise as possible.
Syntax checks
Syntax checks refer to a single segment or the structure or content within a segment. For example, a mandatory segment could be missing or the maximum length of a field could be exceeded.
Error messages
| Error message | Description |
|---|---|
| Unknown segment | This segment is not known in the structure of the Validation Interface. Usually, this happens if there is a typo in the segment name. |
| Segment found at wrong position | The segment itself exists in the Validation Interface, but not at this point. Please check the order of segments in the test message against the specification in the implementation manual. |
| Segment's max repetition exceeded | The segment is allowed at this place in the message but it exists more often than allowed. Please check in the implementation manual how often you may repeat the segment. |
| Segment missing | There should have been a segment at the place of the error message with the segment name that is mentioned in the error message. Please see the implementation manual for mandatory segments. |
| Mandatory element not found | An element within a segment does not exist or does not contain any content. |
| Element has overlapping data elements | At the end of the defined structure, there are further structural elements that should not exist there. For example, this can happen if a segment terminator is missing or if a nested data structure is not properly closed. |
| Element contains content but must not be filled with data | Some data exchange standards like EDIFACT offer more elements in a segment than the user of this standards needs. There may be even situation when he cannot process the incoming data properly if a certain element is filled. With this error code, the data receiver can specify that this element must not be filled. |
| Field content is not strictly alphabetic | This field must only contain letters, not numbers. |
| Field content is not strictly numeric | This field must only contain numbers, not letters. |
| Wrong field pattern | This field must contain one or more strictly defined patterns. For example, if only 'ABC123' and 'XYZ456' are allowed, 'DEF789' would be an error. |
| Field content too short | The minimum length was not reached. Please check the length in the implementation manual. |
| Field content too long | The maximum length was surpassed. Please check the length in the implementation manual. |
| Wrong decimal operator | There exist different decimal operators in different countries, but the data receiver expects a certain one. Please check the implementation manual for the allowed decimal separators. |
Validation rules
Validation rules check logical relationships between several segments within a message. The best way to work with them is to read the rule text carefully, check the affected segments and familiarize yourself with the rule mechanics.
Reading a rule
If a rule has been passed, it only contains a green check mark and the rule text. If, however, the rule has been failed, the rule element will expand and show you the arguments that consist of the rule. Furthermore, you will see what kind of error exist:
- No data: One or more arguments do not contain data. Either because the data is not included in the message or is not in the correct place.
- Logical error: The data in the arguments exists but does not fit the rule conditions. One example: If the value from argument 1 must be greater than the value from argument 2, there would be a logical error if the value from 2 is greater than the value in argument 1.
You can check where the segments belonging to an argument are located in the message with the highlight button. If you click on it, a red frame will appear around the segments. If the argument only includes one segment, the user automatically jumps to the appropriate position within the test message by pressing the highlight button.
You can also start the other way around: If you open a segment, you get a hint which rules are related to this segment. In the segment details, you will see which argument belongs to which element in the segment.
Groupings
A simple rule refers only to two or three single segments or all occurrences of a segment in the message. In more complex rules however, the information will usually be grouped. This means that the rule will be applied to all segments that belong to a certain group.
If there are multiple groups, the rule will be individually executed for all of them. If one group fails, the whole rule will fail as well but only the failed group will be shown in the error message.
A group can be defined by a segment or a combination of values in the message.
- Grouping under a segment: Imagine a despatch advice document where each consignment position is included in a segment 'position'. We could choose to group the rule by this segment and compare the net and the gross weight for each position. If the net weight is larger than the gross weight, the rule would fail. If this is only the case in the last position, only this position would be depicted.
- Grouping under one or more values: Sometimes, the message structure does not allow to group the data in the rule properly. This happens usually if the grouping criterion is set deep in the message structure. In this case, we can group the rule by values in the segments. One example: A delivery note number is depicted on a deep level in a despatch advice message. If we want to check something that is related to that number, we can group the rule by the delivery note number regardless of the message structure.
Rule examples explained
There is a core of operations that are conducted in the validation rules. Sometimes, these operations compose a rule alone, sometimes they are combined for more complex checks. With these examples, we want to show you the most common operations and how they are used in the rules.
Calculations
Here we add, subtract, multiply or divide two or more values and compare the result with another value. The values can either come from the test message or be fixed in the rule.
Example rule: "Calculate tax amounts". Taken from a Validation Interface for an invoice message.
Rule logic: We group the message content by the tax rates. I.e., TAX segments with qualifier 7 and their child segments. Within each of these groups, we multiply the tax rate (included in the TAX segment itself) with the taxable amount (included in the child segment MOA with qualifier 125). The result must equal the tax amount (included in another MOA child segment, this time with qualifier 124).
The rule is passed in these cases:
- If for all groups, the tax amount from the message is equal to the tax amount we calculated.
The rule is failed in these cases:
- If the tax amount from the message is NOT equal to the tax amount we calculated for all groups.
- If there is no tax rate, tax amount or taxable amount within at least one group.
Please note that if there is at least one incorrect group, the rule fails in total. However, we show you only failed groups not all, to keep a focus on the essentials. You see, while the core of the rule is the calculation and comparison of values, there are cases where it is passed or failed without any calculation.
Summaries
Is a variant of an addition rule: Here we do not add existing values but create a value by adding up all occurrences of a piece of information in a message.
Example rule: "Check for the representation of inner packages in outer packages". Taken from a Validation Interface for a despatch advice message.
Rule logic: We group the message content by the outer packages. I.e., those CPS segment groups with qualifier 3 and their child segments. Within each of these groups, there must be a QTY with qualifier 189 and one or more GIN segments with qualifier AW. From the QTY, we take the value from field 6060. From all GIN segments, we summarize the number of entries set in the first field in any C208 composite data element.
The rule is passed in these cases:
- If the sum of all values from the GIN segments is equal to the value from the QTY segment in all groups.
- If there is no CPS with qualifier 3 in the whole message (We may have no outer packages but only one-level packages like a lattice box with the material directly filled in).
The rule is failed in these cases:
- If the sum of all values from the GIN segments is NOT equal to the value from the QTY segment within at least one group.
- If there is no QTY or GIN segment within at least one group.
You see, while the core of the rule is summarization and comparison of values, there are cases where it is passed or failed without any calculation.
Comparisons
As the name already tells you, we compare the content from two or more arguments in comparison rules. As operators, we use greater than, less than, equal to, not equal to, greater than or equal to, less than or equal to.
Example rule: "Compare consignment gross weight versus net weight". Taken from a Validation Interface for a despatch advice message.
Rule logic: The rule contains the gross weight of a consignment in one argument and the net weight in another one. We just compare the two values. If at least one argument is missing or empty, the rule is passed as well. This is because the information itself is optional in this case and we only want to check the relationship between the two values if they are present.
Dependency checks
Sometimes, a segment must only be included in the message if a condition is fulfilled. This means usually, that a certain value is set in another segment or that a certain segment exists at all. We check if the dependent value is present if the condition is met.
Example rule: "Check handover address". Taken from a Validation Interface for a transport orders message.
Rule logic: If the value '10' is set in the segment TDT, there must be a segment NAD with the qualifier HA. Within this segment, the handover address must be contained. For any other value than 10, the check is passed as well, even if there is no NAD segment with qualifier HA.
Uniqueness checks
Information like position numbers or package IDs must be unique in a lot of message types. You can check this with uniqueness rules.
Example rule: "Check the CPS sequence numbers". Taken from a Validation Interface for a despatch advice message.
Rule logic: From all CPS segments (A segment to structure the display of packaging data), we take the sequence numbers. The rule is passed if all sequence numbers are unique. We also check if they ascend consecutively but this is not necessarily a condition in a uniqueness check.
Sub-processes
A lot of implementation manuals cover more than one business process. Or there are different characteristics of a business process that require different information and hence a different message content or composition. In such cases, Sub-processes help you to break down large Validation Interfaces into components that are easier to understand and to master.
Several Sub-processes for a Validation Interface typically share most syntax checks and some rules. In addition, some structural specifications deviate from the main process and there exist some rules exclusively for that process.
By only applying those checks that data sender really need to pass, you spare then the necessity to struggle with syntax checks and rules that will never apply to them. You can also use them to summarize different kinds of validation rules during the onboarding process.
Examples
- Separation by business process: If an interface covers sea, air and road transport, you can create sub-processes for each of them. This way, you can separate the rules for each transport mode.
- Separation by validation type: In a despatch advice, you could summarize all checks related to the display of packages in one Sub-process and all rules for the goods sent in another one. By doing so, you can increase the awareness of your partners for certain aspects of the message.
- Separation by partner: If you have different partners that use the same interface, you can create a Sub-process for each of them. This way, you can customize the validation rules for each partner. Such a setup can be helpful if your partners have a lot of leeway in how they implement your interfaces. Typically, this would be customers who transfer purchase orders or transport orders.
Making a Validation Interface publicly available
You can decide who should be allowed to work with a Validation Interface: Only users with an account in the scope of a project or everyone who has the link. If you choose to make a Validation Interface publicly available, you can share the link with your partners, and they can access the Validation Interface without any registration. This feature is called Open Validation.
Prerequisite
- Your account has the role of a Tenant Owner.
Steps
- Switch to the Administration view by clicking on "Administration" in the top bar.
- In the element "Interfaces", search for the Validation Interface you want to make publicly available.
- Click in the check box on the right side of the Validation Interface entry.
