Understanding Document Specifications

A document specification is theterminology used to signify a XML document that has been formally described. A document specification describes the records and fields in other documents.

BizTalk Server only processes document specifications. The document specification describes relationships between different data items. This is done by organizing the items in a hierarchy. The document specification is actually a hierarchy of nodes with a root node at the top. The nodes beneath the root node can be records or fields. The lowest level of the hierarchy contains fields. These are the fields that are directly associated with the data contained in the actual document.

When it comes to creating document specifications, you have the following options:

  • You can create your own document specifications.Managing Document Specifications for BizTalk Server

  • You can use standard specifications.

The industry standards commonly used are:

  • X12

  • EDIFACT

The above standards support Electronic Data Interchange (EDI). Electronic Data Interchange is the electronic transfer of information between two organizations. The EDI standards define how to exchange data electronically. For organizations to do an EDI, they have to agree on specific standard transactions. For EDI to work, each organization must identify itself and be able to interpret the information being exchanged. Simply put, the organizations have to agree on a document specification.

In most cases, the standard specifications contain more records and fields that what you actually need. You can modify the standard specification to cater for your needs:

  • By deleting the records and fields which you do not need.

  • By changing the properties of the records and fields that you do need.

You can use the BizTalk Editor to modify a standard specification. When performing this type of modification to a standard specification, it is said that you are using a subset of the industry-standard specification. The BizTalk Editor is also used to create your own specifications.

As just mentioned, you can use the BizTalk Editor tool to create a specification or import a specification. The following specifications are available after you install BizTalk Server:

  • UN/EDIFACT standards: The United Nations rules for Electronic Data Interchange For Administration, Commerce, and Transport (UN/EDIFACT) is one of the older standards. UN/EDIFACT describes rules for structuring data and describes data at various levels. The EDIFACT standard is difficult to use and has six versions which might not be compatible with each other.

  • X12 standards: The X12 standard is made up of transaction sets, with each transaction set pertaining to a business document. A transaction set contains data segments, and a data segment contains a data element. The data element is the tiniest data entity you can define. The data segments group connected data elements together. A data segment starts with a segment identifier and ends with a segment terminator. The X12 standard allows you to associate syntax rules with records. When a subset of the X12 standard is used, it is referred to as an implementation convention (IC). The implementation convention represents the agreement between trading partners on how the X12 standard will be utilized.

  • XML schemas: BizTalk.org is the body which promotes the BizTalk Framework. BizTalk.org assists businesses in sharing the document specifications used for Enterprise Application Integration (EAI), and also business to business document exchange. A business can register its schemas with BizTalk.org. Businesses can also use schemas currently being used by other businesses

Using BizTalk Editor to Create Document Specifications

To create document specifications and manage document specifications, you will have to use the BizTalk Editor tool.

When you open BizTalk Editor, you will see that the BizTalk Editor window is sorted or organized into three panes:

    • The left pane is the specification tree of the document specification.

    • The right pane is used to define the properties of records and fields.

    • The bottom pane shows the results of creating the document specifications.

The specification field on the right pane of the BizTalk Editor window contains a number of tabs that you can use to define the information of the document:

    • Declaration tab: Used to set properties for the root node, and records and fields.

    • Reference tab: Used to define the standard and the version utilized by the document specification.

    • Parse tab: Used to define the properties which assist the parser to determine the document structure.

When creating document specifications, remember the following important factors:

    • A document is structured in a hierarchical manner.

    • All documents must have one root node.

    • You have to configure properties for each node and configure properties for each field within the document.

    • The Declaration tab contains the standard properties. The node type determines the set of properties.

The properties on the Declaration tab that you can configure for the root node and records nodes are listed here

    • Name; identifies the root node or record node. You have to define a unique name for each child of a node.

    • Description;describes the record or field

    • Type; for records it is Element. For fields it can be either Element or Attribute.

    • Model; can have a value of either Open or Closed. The Model property describes how the document instance adheres to the specification structure.

    • Open; the data in the document does not match the specification structure precisely.

    • Closed; the data within the document matches the specification structure.

    • Content; can have a value of:

    • Element Only; the node can only contain elements.

    • Text Only; the node can contain text only.

    • Empty; the record contains no elements.

    • Order; indicates the order of sub-elements as One, Sequence, or Many.

    • Cycle Count; indicates how many cycles exist beneath the base record for cyclical elements.

The different Fields properties that you can define for fields within the specification tree are listed here:

    • Name; indicates the name for the field.

    • Description;describes field.

    • Type; indicates the type of the item. For fields it can be either Element or Attribute. For records it is Element.

    • Model; can have a value of either Open or Closed. The Model property describes how the document instance adheres to the specification structure.

    • Open; the data within the document does not match the specification structure precisely.

    • Closed; the data within the document matches the specification structure.

    • Content; Text Only is the value for the Content property. The Content property is available when the Type property is set to Element. The node can contain text only – no sub-elements.

    • Data Type; the data types that you can define for fields are listed here:

    • Character; string one character in length.

    • String; text of whatever length.

    • Number; an integer, decimal fraction, or number with an exponent.

    • Float; number that has no length limit. Can contain a leading sign, exponent or a fraction component.

    • Fixed Point (14.4); number made up of up to 14 digits prior to the decimal point and up to 4 digits following the decimal point.

    • Boolean; expression that evaluates to TRUE (1) or FALSE (0).

    • Date; date represented as a subset ISO 8601 format.

    • Date Time; date in a subset of ISO 8601 format that can have the date and time component.

    • Date Time.TZ; date in a subset ISO 8601 format that can have the date and time component and the time zone.

    • Time; time in a subset of ISO 8601 format.

    • Time.tz; time in a subset of ISO 8601 format that can have time zone information.

    • Byte (i1); 1 byte-long whole number containing a sign.

    • Word (i2); 2 byte whole number containing a sign.

    • Integer (i4); 4 byte whole number. Could be preceded by a sign.

    • Double Integer (i8); 8 byte whole number. Could be preceded by a sign.

    • Unsigned Byte (ui1); 1 byte-long unsigned whole number.

    • Unsigned Word (ui2); unsigned whole number 2 bytes in length.

    • Unsigned Integer (ui4); unsigned whole number 4 bytes in length.

    • Double Unsigned Integer (ui8); unsigned whole number 8 bytes in length.

    • Real (r4); number between 1.17549435E-38F and 3.40282347E+38.

    • Double real (r8); number between 1.17549435E-308F and 3.40282347E+308F.

    • Universal Unique Identifier (uuid); number consisting of hexadecimal octets with optional hyphens used only for presentation.

    • Uniform Resource Identifier (uri); prefix that refers to a namespace.

    • Binary (base64); binary encoding that defines a conversion of a format.

    • Binary (hex); hexadecimal number.

    • ID; defines the field as being an identifier.

    • IDREF; defines the field as being referenced to a field that holds the ID value.

    • IDREFS; defines the field as holding a list of IDs which are separated by spaces.

    • Enumeration; an ordered sequence of items

    • Custom; can be specified as the data type.

    • Data Type Values; the Data Type Values property becomes available when you select the data type as Enumeration, and is used to define the values of the Enumeration data type.

    • Minimum Length; the Minimum Length property becomes available when you select the data type as String, Number, Binary (base64), or Binary (hex), and is used to define the minimum number of characters.

    • Maximum Length; the Maximum Length property becomes available when you select the data type as String, Number, Binary (base64), or Binary (hex), and is used to define the maximum number of characters.

    • Default Value; when the document instance does not contain a value for the field, the Default Value property defines that the value will be supplied.

    • Reference Tab Properties: To describe how the items in the specification tree are used.

The root properties that describe the standard and the version that the document specification uses are listed here:

    • Specification Name; the name of the specification. Can be the same name as the name of the root node.

    • Standard; defines the standard that the specification adheres to:

    • XML

    • X12

    • EDIFACT

    • Custom

    • Standards Version; indicates the version of the standard where the standard currently has multiple versions.

    • Document Type; defines the document type. The Document Type value is determined by the Standard property and Standards Version property.

    • Version; indicates the version number of the document standard whereon the ocument specification is based.

    • Default Record Delimiter; when the Standard property has the Custom value, then you can define the character that will be the end character of a record marker.

    • Default Field Delimiter; when the Standard property has the Custom value, then you can define the character that will be the end character of a field marker.

    • Default Subfield Delimiter; when the Standard property has the Custom value, then you can define the character that will be the end character of a subfield marker.

    • Default Escape Character; when the Standard property has the Custom value, then you can define the character that will be an escape character.

    • Code Page; when the Standard property has the Custom value, the Code Page property defines the character set used in the document.

    • Receipt; specifies whether the document is a receipt for a document that has been sent before. The default value for the property is No.

    • Envelope; specifies whether the document is an interchange specification.

    • Target Namespace; used with BizTalk Framework instances where the namespace is specified.

The root and record properties used to define the minimum and maximum number of occurrences is listed here:

      • Minimum Occurrences; used to specify the minimum number of times that the record can occur. The default is 1. The other value that can be set is 0.

      • Maximum Occurrences; used to specify the maximum number of times that the record can occur. The default is 1. The other values that can be set are 0 and * (looping records).

The properties that you can configure on the Parse tab guide the parser to determine the structure of the document.

The root and record node properties that you can configure are:

    • Structure; the value for EDI-compatible standards is Delimited. This means that the document is specified according to the delimited file structure. The Structure property can be Delimited or Positional for Custom standards. When the value is Positional, it means that the record is based on a positional file structure. The Structure property for the root node must be Delimited when the document contains records.

    • Source Tag Identifier; used to match the record with the data.

    • Field Order; defines where a delimiter exists in relation to components. Values that can be specified are:

    • Prefix; should be set when the delimiter exists before each component.

    • Postfix; should be set when the delimiter exists after each component.

    • Infix; should be set when the delimiter exists between components.

    • Delimiter Type; defines whether the delimiter delimits records, or fields, or subfields.

    • Delimiter Value; can be specified when the Custom standard is used.

    • Escape Type; not available for X12 documents. When set to Default Escape Character, it indicates a Release Character. For the Custom standard, you can set the Escape Type as Character.

    • Escape Character; only configurable when the Escape Type property is set to Character. You can define any character as the Escape Character.

    • Append New Line; used to define the behavior of the serializer:

    • A value of Yes means that the serializer must append a new line character when it reaches the record delimiter.

    • A value of No means that the serializer must not append a new line character.

    • Skip Carriage Return; defines whether the parser should skip the carriage return (CR) value after a delimiter.

    • Skip Line Fed; defines whether or not the parser should skip the line feed (LF) value after a delimiter.

    • Ignore Record Count; defines whether or not the serializer or parser should count the record.

The properties that you can configure for a field are listed here:

    • Custom Data Type; indicates the custom data type recognized by the document standard.

    • Custom Date/Time Format; used for X12 documents when the date or time option is defined as a custom data type, to specify the date and time format.

    • Justification; defines the manner in which data is aligned (Left or Right).

    • Pad Character; defines the character used for padding the field.

    • Wrap Character; defines the character used for wrapping the field.

    • Minimum Length With Pad Character; specifies the minimum length of a field in the document instance. All pad characters are included.

How to open a document specification

  1. Open BizTalk Editor.

  2. Click the File menu and then select New.

  3. The New Document Specification dialog box opens.

  4. Double-click X12 to access the X12 standard specifications.

  5. Double-click 4010 to list all available document specifications.

How to open a blank document specification

  1. Open BizTalk Editor.

  2. Click the File menu and then select New.

  3. The New Document Specification dialog box opens.

  4. Click Blank Specification.

  5. Click OK.

How to configure properties for the root node

  1. Open BizTalk Editor.

  2. Click the Blank Specification node.

  3. In the Details pane, click the Declaration tab.

  4. All default values for the root node are displayed.

  5. Click the Name property. In the Value field of the Name property, specify the name for the root node.

  6. Click the Description property. In the Value field of the Name property, provide a description for the root node.

How to add records and fields

  1. Open BizTalk Editor.

  2. Right-click the root node and then select New Record from the shortcut menu.

  3. The new record appears beneath the root node. Rename the new record.

  4. Right-click the new record that you have just created and then select New Field from the shortcut menu.

  5. The new field is added. Rename the new field.

  6. Access the Declaration tab for the new field and then click the Value field for the Data Type property. Specify the data type from the available list.

How to make a record Required or Optional

  1. Open BizTalk Editor.

  2. Select the record that you want to configure.

  3. Switch to the Reference tab.

  4. In the Value field of the Minimum Occurrences property:

    • Select 1 to make the record required.

    • Select 0 to make the record optional.

How to make a field Required or Optional

  1. Open BizTalk Editor.

  2. Select the field that you want to configure.

  3. Switch to the Reference tab.

  4. In the Value field of the Required property:

    • Select Yes to make the field required.

    • Select No to make the field optional.

How to make a record a looping record

  1. Open BizTalk Editor.

  2. Select the record that you want to configure.

  3. Switch to the Reference tab.

  4. In the Value field of the Minimum Occurrences property, select *.

How to specify a cyclical reference

  1. Open BizTalk Editor.
    Create a base record.

  2. Select the base record.

  3. Click the Edit menu and then select New Record.

  4. The name of the new record and the base record should be the same.

  5. Press Enter.

  6. On the Declaration tab, double-click the Value field of the Cycle Count property.

  7. Specify the appropriate value for Cycle Count.

How to create a specification based on an existing document

  1. Open BizTalk Editor.

  2. Click the Tools menu and then click Import.

  3. The Select Import Module dialog box opens.

  4. Select Well-formed XML Instance and click OK.

  5. The Import dialog box opens.

  6. Locate the appropriate file and then select Open.

  7. BizTalk Editor next creates a specification based on the file that you have selected.

How to validate document specifications

  1. Open BizTalk Editor.

  2. Open the specification that you want to validate.

  3. Click the Tools menu and then select Validate Specification.

  4. All errors and warnings are displayed on the Warnings tab.

How to create a valid document instance

  1. Open BizTalk Editor.

  2. Click the File menu and then select Open.

  3. Locate and open the specification that you want to work with.

  4. Click the Tools menu and then select Create XML Instance.

  5. The Create Document Instance As dialog box opens.

  6. In the File Name textbox, enter the name for the document instance, and then click Save.

How validate a document instance

  1. Open BizTalk Editor.

  2. Click the Tools menu and then select Validate Instance.

  3. The Validate Document Instance dialog box opens.

  4. Locate and select your document instance and then select Open to validate the instance to the specification.