Ensemble X12 Development Guide
Settings for X12 Business Processes
Provides reference information for settings of an X12 business process.
X12 business processes have the following settings:
Response Target Config Names
A comma-separated list of configured items within the production. If specified, this list identifies the destinations, in addition to the caller, to which responses will be forwarded. If empty, responses are only returned to the caller. This setting takes effect only if the Response From
field has a value.
setting of an X12 Document Router controls how the router validates the incoming message. If the incoming message fails the specified validation, Ensemble reports the failure in the event log, and the X12 routing process passes the message to its bad message handler only; see the Bad Message Handler
setting. If the message fails the specified validation but there is no bad message handler, an error is logged but the message is not sent to any target. If the message passes validation, the X12 routing process sends the message to the targets specified by the routing rules.
Ideally, you can use routing rules and data transformations to ensure each message is acceptable to the target system, and can, consequently, avoid using validation. This ensures that all messages are processed by the appropriate target. If you enable validation, Ensemble applies the validation tests before the routing rules. Any message that fails validation will not be sent to a target based on the routing rules; it will be sent only to the Bad Message Handler. However, there are some environments where X12 message validation is the preferred way to filter messages. For example, in the following situations, using X12 validation is a good choice:
You are developing or debugging an interface and want to determine the kind of message variants that your system needs to handle.
The target application cannot handle messages that have variances from the specification, and the routing rules and transformations cannot resolve those variances.
There is a regulatory or other business requirement that the messages conform to the specification.
X12 validation does add overhead to the routing process. This overhead can be significant and can reduce the maximum load of messages that your production can handle.
property allows you to specify flags that control the following:
Whether the message has a valid document type.
Whether the message structure is validated.
Whether trailing Z segments that are not specified in the schema are validated.
What specific field validations should be applied.
Whether the validation stops after reporting the first error or continues to validate the remaining segments and fields in the message.
If you specify an empty string as the Validation
property value, the message router skips validation and routes all messages. When you create a new X12 routing process in the Management Portal, the Validation
setting is initialized to an empty string.
For compatibility with previous releases, setting Validation
is treated the same as setting it to dm-z
and setting Validation
is treated the same as setting it to an empty string.
The message validation sequence is as follows:
Validate that the message object has a DocType
Validate the segment order.
Validate the fields within segments.
If at any time during this sequence the message fails validation and the -x flag is not specified, the X12 routing process does not validate the remaining segments of the message.
A message can pass validation and not conform exactly to the schema definition depending on the Validation
Validating the DocType Property
The business service sets the DocType
property value based on the Message Schema Category
defined for the service and the document name specified in the X12 message MSH:9 field. If the Validation
property value includes d
, the message router tests if the DocType
property has a value. If it does not have a value, the message is a bad message.
The business service does not assign a value to the DocType
property under any of the following circumstances:
The document name in the X12 message is not defined in the specified schema or, for custom schemas, in either the specified schema or the base schema.
This section describes how routing engines validate segments.
If the Validation
property has a value of dm
, or dm-z
, the routing process validation either validates the message or declares it bad, by the following tests:
If the segments in the message conforms to the message structure specified by the DocType value that the business service assigned to the message, the m
validation is satisfied. For example, if the message has a DocType value of 2.3.1 and the MSH:9 value in the message is ORU^R01
the message is verified against the ORU_R01 message structure under the 2.3.1 category. If the message data is missing some required segments, or if it has extra undefined segments, as compared to the 2.3.1 ORU_R01, then it is a bad message. X12 allows custom local variations to be added to standard messages as trailing Z segments. A trailing Z segment in a message is validated governed by the following rules:
If the schema specifies the trailing Z segment or specifies the Zxx wildcard segment, the trailing Z segment passes validation.
If the -z
flag is specified, the trailing Z segment in the message passes validation.
If the -z
flag is not specified and the trailing Z segment is not defined in the schema, the trailing Z segment fails validation.
If the schema requires a trailing Z segment and the message does not contain it, then the message fails validation.
If the DocType refers to a custom schema, the same rules apply as in test 1, except that the message is verified against the custom definition. Each custom schema has a base category defined (for example base="2.3.1"
). If a message arrives that is not explicitly defined in the custom schema, the base category is used.
If MSH:9 field can contain a nonstandard value, you must define a custom schema to avoid having messages with this nonstandard value fail validation. For example, if MSH 9 is equal to ORU^Z22
instead of ORU^R01
a custom schema is required to specify that the message name ORU^Z22 should be verified against the structure ORU_R01.
flag enables all field validation. If you specify f
, the message router performs the following field validation:
Tests that field and component order in the message conform to the schema.
Tests that required fields, components, and subcomponents are present.
Test that field sizes in the message conform to the schema.
Tests that field data values conform to the data type defined in the schema.
Tests that field data values conforms to the code tables, but allows any value if the code table includes the ...
value or if the code table is empty.
Specifying Validation Flags
Each flag can be preceded with the -
hyphen character to negate the meaning of the flag. For example, the x
flag specifies that the routing process should stop validation after encountering the first error, and the -x
flag specifies that the routing process should continue validation until the entire message is validated and all errors detected. Some validation flags are equivalent to specifying a series of flags. For example, the s
flag is equivalent to specifying the jpw
flags. You can remove one of the series by specifying a negating flag. For example s-p
is equivalent to jw
. To negate a flag, you must enter a hyphen immediately before the flag character. For example, if you want to negate both the z
flags, you must specify -z-x
The following table lists the X12 validation flags and describes how the routing process validates the message when each is specified.
||Enforces field array repetition limits.
||Interprets ... in a code table to allow any field value to pass validation.
||Performs all component and subcomponent validation. Is equivalent to gijopw.
||Requires that the DocType property be defined. Note that every other flag requires that DocType is defined in order to perform the specified validation.
||Performs every validation. Is equivalent to abdgijlmnoprtuwy.
||Performs all field validation within segments. Is equivalent to abgijlnoprtuwy.
||Enforces data structures within segments.
||Enforces component size restrictions.
||Ensures that required subcomponents are present. These are governed by the optionality setting in the schema.
||Enforces field size restrictions.
||Ensures that all required segments in the schema definition are included in the message and that the message does not contain any misplaced segments that are not allowed by the schema.
||Ensures that the segments contain the correct number of fields.
||Ensures that required components are present. These are governed by the optionality setting in the schema.
||Enforces component-level data structures.
||Enforces that required fields are present.
||Performs all subcomponent-level validation. Is equivalent to jpw.
||Enforces code tables. This flag can be modified by the b and u flags.
||Ignores code tables that do not list any permissible value. Permits any value for these empty code tables.
||Enforces subcomponent size restrictions.
||Stops validating after the first error is encountered. This is the default. -x specifies that the entire message is to be validated and all errors returned in the status.
||Enforces field data types, such as numeric.
||Requires that Z segments be explicitly specified in the schema or specified by the wildcard Zxx in the schema. -z allows trailing Z segments even if they are not specified in the schema.
||Skips validation and routes all messages.