2.3 Standard XML Schema

The Technical Documentation Application includes a default schema that defines a document structure called Standard. It is possible to customize this schema as well as develop additional custom schemas to meet business requirements.

The Standard schema implements the following structure:

1. Figure 1. Standard Document Type

To understand how XML schema is used, it is helpful to discuss a portion of the schema provided with the ‘Standard’ Document Type, which is included by default.

<xs:element name="Standard-Doc">                                                

    <xs:complexType>

        <xs:sequence>                                                

            <xs:element ref="Title"/>                                                

            <xs:element ref="Subtitle" minOccurs="0" maxOccurs="1"/>                                                

            <xs:element ref="TOC-Section" minOccurs="0" maxOccurs="1"/>                                                

            <xs:choice>                                                

                <xs:element ref="Section" minOccurs="0" maxOccurs="unbounded"/>                                                

                <xs:element ref="Chapter" minOccurs="0" maxOccurs="unbounded"/>                                                

            </xs:choice>                                                

        </xs:sequence>                                                

    </xs:complexType>

</xs:element>

The top-most schema element with name ‘Standard-Doc’ is essentially a container for the content defined within it. For Document Types, content within another schema element is either defined as a sequence or a choice. In the XML Schema definition, a sequence is an ordered list, and a choice is unordered.

Each schema element for a complex type is defined within either a sequence or choice and can have specific cardinality defined, which identifies the minimum and maximum number of XML Elements allowed. Minimum and Maximum counts are defined by the minOccurs and maxOccurs attributes respectively. Undefined min/maxOccurs attributes default to the value ‘1’. In this case, and XML Element with name ‘Standard-Doc’ can have, as children, the following XML Elements:

• A single, required ‘Title’ XML Element, followed by
• An optional ‘Subtitle’ XML Element, followed by
• An optional ‘TOC-Section’ XML Element (see Section ), followed by either
• 0 or more ‘Section’ XML Elements or
• 0 or more ‘Chapter’ XML Elements

Each of the XML Elements in this example is defined in another portion of the XML Schema. XML Schema ‘structures’ defined in this manner thus define the structure of the corresponding content in a Technical Document. The following example shows what content using this schema might look like. Note that the content for a ‘Chapter’ XML Element was not described above but is included in the Standard Document Type.

Figure 3: Sample Content from Standard Document Type

XML Elements defined within the XML Schema for a Document Type can be configured to extend XML Elements defined by the system. In this way these Document Elements are processed differently and provide additional functionality within the Technical Document Editor. This section describes each of the Document Element Types.

The simplest Document Element is identified as a ‘Container Element’ because it is used specifically to contain other Document Elements and thus has no other special processing by the Editor. ‘Standard-Doc’ is an example of this type. ‘Section’, ‘Chapter’, and ‘Graphic-Block’ are also examples of Container Elements defined in the ‘Standard’ Document Type. Note that many of the other Document Types defined in this section are also used to contain other content, but they have additional qualities and are thus processed differently by the Editor.

Item Document Elements are used to associate content within a Technical Document with a separate Item (Business Object). Typically, Item Document Elements also have a Content Generator (Section 4 Content Generation) defined so that the Item Document Element’s content can be automatically generated based on information extracted from the associated Item. This type of association is critical to a Digital Thread and helps maintain a link between technical documentation and the business objects it describes.

Once a Document Element is created, the system will prompt the author to select the referenced Item and a relationship will be created between that selected Item and the Technical Document Item in which the Item Document Element was placed. To illustrate this process, the following example of an Item Document Element is described:

<xs:element name="PartData">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:itemType">                                                

        <xs:choice maxOccurs="1">

          <xs:element ref="Table" minOccurs="0" maxOccurs="1"/>                                                

        </xs:choice>

        <xs:attribute name="typeId" type="xs:string" fixed="<Part ItemType Id>"/>                                                

      </xs:extension>

    </xs:complexContent>

  </xs:complexType>

</xs:element>

This example describes a ‘PartData’ Item Document Element. Item Document Elements extend the aras:itemType XML Element. This example defines a single child Document Element – Table. In addition, the XML Attribute typeId is used to fix the associated/referenced ItemType to a Part ItemType.

When placing an Item Document Element, the author has a choice to either choose an existing Item or create a new one.

Figure 4: Adding an Item Document Element

If the author chooses ‘Add Item’, the system will display a search dialog to choose a specific Item. If the typeId is used in the schema, only ItemTypes corresponding to the ItemType id specified will be displayed. Otherwise, the user can select the specific ItemType or search all.

If the author chooses ‘New Item’, the system will display the Form of the ItemType so that the Property values can be specified before the Item is created. If the typeId is not specified in the schema, the author will first need to select the specific ItemType to be created.

Authors can change the referenced Item for existing Item Document Elements with either a different, existing Item or based on a newly created Item. The functionality is like ‘Add’ and ‘New’ as defined above respectively.

Figure 5: Replacing a Referenced Item

Text Document Elements are used for textual data. Text Document Elements can either be formatted or non-formatted. Formatted Text Document Elements can have text content within them formatted with a limited set of options. Unformatted Text Document Element do not have formatting options.

Figure 6: Formatted Text Options

The following example shows two types of Text Document Elements.

<xs:element name="Subtitle">                                                

  <xs:complexType mixed="true"/>                                                

</xs:element>

 

<xs:element name="Text">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:text"/>                                                

    </xs:complexContent>

  </xs:complexType>

</xs:element>

In this example the ‘Subtitle’ Document Element is unformatted, and the ‘Text’ Document Element is formatted. Unformatted Text Document Elements are defined as a complex type with the mixed attribute set to ‘true’. Formatted Document Elements extend the aras:text XML Element.

Image Document Elements are used to place 2D images in a Technical Document. All Image Document Elements use the tp_Image ItemType to contain the 2D image file and are thus independently managed.

When a user places an Image Document Element, the system will display a Search Dialog for Items of type tp_Image (Graphic). Like Item Document Elements, an author can either select an existing Graphic Item or create a new Item. In the latter case, the system will present a Form for the author to enter necessary Properties before the new Graphic Item is created. Referenced Graphic Items will have a Relationship Item generated between the Graphic Item and the Technical Document Item in which the Image Document Element was placed.

The following example shows an Image Document Element schema definition:

<xs:element name="Graphic">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:imageType"/>                                                

    </xs:complexContent>

  </xs:complexType>

</xs:element>

In this example, the ‘Graphic’ Image Document Element is created. Image Document Elements must extend the aras:ImageType XML Element.

Mapped Property Document Elements are a type of Unformatted Text Document Element that are used to reference a Property of an Item referenced by an ancestor Item Document Element. These are also referred to as Item Property Document Elements. When authors place instances of a Mapped Property Document Element, the system will automatically apply the content of the associated Property of the referenced Item.

In the following example, a ‘ShippingInformation’ Item Document Element contains ‘LineItem’ Container Document Elements, which contain a single ‘Text’ (Formatted Text Document Element) and a ‘ShipProperty’ Mapped Document Element:

Figure 7: Mapped Property Example

The corresponding XML Schema would be specified as follows:

<xs:element name="ShippingInformation">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:itemType">                                                

        <xs:choice maxOccurs="1">

          <xs:element ref="LineItem" minOccurs="1" maxOccurs="unbounded"/>

        </xs:choice>

        <xs:attribute name="typeId" type="xs:string" fixed="<ItemType Id>"/>                                                

      </xs:extension>

    </xs:complexContent>

  </xs:complexType>

</xs:element>

 

<xs:element name="LineItem">                                                

  <xs:complexType>

    <xs:sequence>

      <xs:element ref="Text" minOccurs="1" maxOccurs="1"/>                                                

      <xs:element ref="ShipProperty" minOccurs="1" maxOccurs="1"/>                                                

    </xs:sequence>

  </xs:complexType>

</xs:element>

 

<xs:element name="ShipProperty">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:itemProperty">                                                

        <xs:attribute name="property" type="xs:string" fixed="name"/>                                                

        <xs:attribute name="mode" type="aras:itemPropertyModeEnum" fixed="read"/>                                                

      </xs:extension>

    </xs:complexContent>

  </xs:complexType>

</xs:element>

The example illustrates a possible scenario in which Shipping Information is maintained within a separate Item (Business Object). In this case, there may be several Properties related to the shipping information managed. Using Item Document Elements with Mapped Property Document Elements in this manner provide a convenient mechanism to automatically populate content in a technical document when these Document Elements are placed manually and update the content dynamically when the referenced Item is changed. See Section for a description of the Item Document Element.

The ‘ShippingInformation’ XML Element extends aras:itemType, is fixed to refer to an ItemType (presumably containing Shipping Information), and contains a single ‘LineItem’ Container Document Element. The ‘LineItem’ Container Document Element contains a single Text Document Element - ‘Text’ - and a single Mapped Property Document Element – ‘ShipProperty’ – which extends aras:itemProperty. The ‘ShipProperty’ Mapped Property Document Element is configured with two, optional Attributes: ‘property’ and ‘mode’.

If the ‘property’ Attribute is configured, it can specify the default Property name to map to (using the ‘default’ attribute) or fix the value using the ‘fixed’ attribute. If the ‘property’ Attribute is not configured, authors can manually specify the Property to map using the Attributes Dialog:

Figure 8: Attributes Dialog for Mapped Property Document Elements

If the ‘mode’ Attribute is configured, it can specify the default Property mode (using the ‘default’ attribute) or fix the value to either ‘read’ or ‘write’ using the ‘fixed’ attribute. If the ‘property’ Attribute is not configured, authors can manually specify the Property to map using the Attributes Dialog. Fixed values for these of these two Attributes will disable the ability to change them in the Attributes Dialog.

Mapped Property Document Elements are edited using a pop-up Form in the Technical Document Editor. To edit a value, select the Document Element in the Editor or Tree View and/or double-click to display the Property Editor Form. Document Elements with a grey, dotted border can be edited. Document Elements with a red, solid border are read-only. For example:

Figure 9: Mapped Property Editor Form

Values can only be changed using this Form. Selecting the ‘Check’ button will update the Mapped Property Document Element in the technical Document only. Authors will see a pencil icon ( ), signifying that the Property of the referenced Item has not been updated, next to the Document Element in the Tree View. The referenced Item will be updated when the technical document is saved, in which case the pencil icon will be hidden. Selecting the ‘X’ button will cancel the update without any changes to the technical document.

The following Property Value Types are supported:

• String
• Text
• Numeric (Integer, Decimal, etc.)
• Date
• Boolean
• Item (Display only - Editor not available)
• List (Display only - Editor not available)
• Image (Display only - Editor not available)

The Editor can display multiple Property Types, as shown above, but not all can be edited with the Technical Document Editor. Authors will be presented with an error if an attempt is made to edit an unsupported Type:

Figure 10: Mapped Property Editor Error Dialog

The Edit Field in the Property Edit Form is based on the Property Type. For Text and Numeric Fields, an attempt to set a value that does not match the type will result in an Error being displayed in a Dialog.

Figure 11: Mapped Property Edit Forms

Modifying a versionable Item vis-à-vis Mapped Property Document Elements will result in the referenced Item to be versioned automatically. Since Technical Documents reference Items via fixed Relationships, the Item Document Element will show as stale since it will refer to the previous generation of the Item.

Table Document Elements are used to group content in a tabular format. Document Elements that are configured as Tables have additional functionality provided in the Technical Document Editor to provide the ability to add columns, rows, merge cells, etc. Thus Tables, Rows, and Cell Document Element are a type of Container Document Element, but with extended capability.

Configuring a Document Element as a Table requires corresponding Document Elements for Rows and Cells. Table Document Elements can be nested within other Table Document Elements. The following is an example of a Table Configuration in XML Schema:

<xs:element name="Table">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:table"/>                                                

    </xs:complexContent>

  </xs:complexType>

</xs:element>

 

<xs:element name="Row" substitutionGroup="aras:tablerow">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:tr"/>                                                

    </xs:complexContent>

  </xs:complexType>

</xs:element>

 

<xs:element name="Entry" substitutionGroup="aras:tablecell">                                                

  <xs:complexType>

    <xs:complexContent>

      <xs:extension base="aras:td">                                                

        <xs:choice minOccurs="0" maxOccurs="unbounded">

          <xs:element ref="Text" minOccurs="0" maxOccurs="unbounded"/>

          <xs:element ref="List"/>

          <xs:element ref="Graphic"/>

          <xs:element ref="Table"/>                                                

        </xs:choice>

      </xs:extension>

    </xs:complexContent>

  </xs:complexType>

</xs:element>

Table Document Elements extend the aras:table XML Element. Table Document Elements must contain Row Document Elements as their only child element. Likewise, Row Document Elements must contain Cell Document Elements as their only child element. Cell Document Elements can contain other types of content, including other Tables as specified above. Row Document Elements extend the aras:tr XML Element. Cell Document Elements extend the aras:td XML Element.

List Document Elements are used to group content in a sequential list format. Document Elements that are configured as Lists have additional functionality provided in the Technical Document Editor to provide the ability to set the individual List Items as bulleted, numeric, or alpha. Thus Lists, and List Item Document Elements are a type of Container Document Element, but with extended capability.

Configuring a Document Element as a List requires corresponding Document Elements for List Items. There can be multiple List Document Elements defined and it is possible to nest Lists within Lists. The following is an example of a List Configuration in XML Schema:

<xs:element name="List">                                                

  <xs:complexType>                                                

    <xs:complexContent>                                                

      <xs:extension base="aras:list">                                                

        <xs:choice maxOccurs="unbounded">                                                

          <xs:element ref="List-Item" minOccurs="1" maxOccurs="unbounded"/>                                                

        </xs:choice>                                                

      </xs:extension>                                                

    </xs:complexContent>                                                

  </xs:complexType>                                                

</xs:element>

 

<xs:element name="List-Item">                                                

  <xs:complexType>                                                

    <xs:complexContent>                                                

      <xs:extension base="aras:listitemType">                                                

        <xs:choice maxOccurs="unbounded">                                                

          <xs:element ref="Text" />                                                

          <xs:element ref="Graphic"/>                                                

          <xs:element ref="List"/>                                                

        </xs:choice>                                                

      </xs:extension>                                                

    </xs:complexContent>                                                

  </xs:complexType>                                                

</xs:element>

List Document Elements extend the aras:list XML Element. List Document Elements must contain List Item Document Elements as their only child element. List Item Document Elements can contain other types of content, including other Lists as specified above. List Item Document Element extend the aras:listitemType XML Element.

The Document Type Form uses a Text Editor to display and edit the XML Schema definition. This Editor has been configured specifically for XML Schema to highlight XML keywords and show validation errors/warnings with indicators of such on the corresponding line in the User Interface. The XML Schema is validated as the user edits the content and when the user Saves the Document Type Item. If there are any warnings or errors, the user is prompted with a message. It is not possible to save a Document Type Item if there are schema errors. This is to prevent the inadvertent use of the schema if it is not valid.

Figure 12: XML Schema Validation Warning

Figure 13: XML Schema Validation Error Dialog

For each Document Element, the Technical Document Framework provides the ability to configure Content Generators (Section 4 Content Generation), Methods to prepopulate and validate Properties on referenced Items (Section 5 Item Reference Configuration), custom Tree Node Renders, and the default action for specific Classifications of Technical Document Enabled Items. These configuration options extend the default behavior of Document Element Types.

Figure 14: Document Element Configuration User Interface

Document Element configuration is specified using XML Schema Element Items. References to these Items are added in the Document Type Form. For each XML Schema Element Item, the associated Document Element is identified by Name. It is important that the spelling of the name match what is defined for the XML Element in the XML Schema. The Renderer identifies the JavaScript Method that is used as an alternative to the default logic for populating the Tree Node Icon and Text. The Content Generator identifies the C# Server-side Method that is called whenever an instance of the corresponding Document Element is placed in a Technical Document or when it is refreshed. The Dynamic Content checkbox determines how often a configured Content Generator is executed. When False, the Content Generator is only executed when the Document Element is first created or when it is manually refreshed in the Technical Document Editor. When True, the Content Generator is additionally executed whenever the Technical Document is opened or saved. Document Classification associates the Document Element with a Classification for the Technical Document Enabled Item. When the Technical Document Enabled Item is first created, with a specified Classification, the system will automatically add the Document Element as the root. In this case, only a single root element is allowed for this technical document.

Technical Documents can reference (and thus be composed of an aggregation of) the content of other Technical Documents so that documentation is managed by individual document modules. By default, all referenced document content cannot be edited within the context of a Technical Document that references it. Changing this content would thus require opening the associated Technical Document Item and editing the content from there. However, it is possible to enable referenced content editing in one of two modes: Implicit or Explicit.

Implicit Edit Mode allows authors to edit referenced content as if the referenced content was part of the opened document without any need to lock this content prior. In this mode, when the parent (or opened) document is saved, the referenced document content is locked, updated, unlocked in a continuous series of steps for any referenced document content that was changed.

Explicit Edit Mode will also allow authors to edit referenced content but will require that the associated Technical Document Item is first locked for Edit. This can be done directly in the Technical Document Editor or separately as is part of normal Lock/Unlock operations in Aras Innovator.

Explicit Edit Mode also requires that referenced Technical Document Items be unlocked when the author has completed their updates. This can be done within the Technical Document Editor or separately as part of the normal Item Lock/Unlock operations in Aras Innovator.

In Explicit Mode, referenced and locked Technical Document Items are saved when the parent document is saved. Authors can also save referenced document content directly using the context popup menu.

When a referenced document is claimed or locked by a separate User, the Technical Document Editor will display an icon for the node associated with the referenced document in the Structure Tree.

Hovering the mouse over the icon will display the name of the User who has the Technical Document claimed or locked. Any referenced document content that has been changed and not saved will also cause the display of an icon in the Structure Tree as an indication that the content has not been saved.