Creating and Referencing External Content

Technical Document content can be an aggregation of multiple Technical Documents, which in turn can contain other Technical Documents and so on. The result is a hierarchy of document components. Individual Technical Document components can be reused in other Technical Documents and be edited concurrently with the documents that refer to them. A Relationship instance is created between the source document (document which includes the reference) and the target document (containing the external content).

When reusing document content, it’s important to keep in mind that the Technical Document Type of the document including the content must be valid. This means that the root nodes in the document to include must be able to exist at the location in the source document that they will be placed. For example, if a Table was going to include external content for its rows, each document that is included must only contains Row Document Elements as its top-most Document Elements. For each Technical Document, the system will store the name of the top-most (root) node in the document if there is only one. Otherwise, it will the term ‘multiple’. Documents with multiple root nodes are harder to reuse, especially if the root nodes are not the same type. This is because the sequence and type of root nodes must conform to every document that they are being reused in. For this reason, it is generally beneficial to only have a single root node for any Document that the author intends to reuse. If not a single root, then have all root nodes be of the same type.

At any location where either a child or peer Document is allowed, the context menus will include a sub-menu entitled ‘External Content’ (Adding Document Elements and Adding Document Elements). Selecting this menu item will display a search grid for Technical Documents. The searched content will be filtered by Documents that use the same Technical Document Type and that include root nodes of a type that can be added (or inserted as the case may be) where the author has chosen to add the content. The author adds whatever additional search criteria as is necessary and selects the Technical Document instance to add.

Figure 33. External content will display in the Navigation Pane as a separate node using the name of the Technical Document that is included. Using Creating and Referencing External Content as an example, the Technical Document ‘Standard Document Example 3’ was inserted. Note that the Document Element Standard-Doc must have a Title Document as the first child, an option Subtitle as the second child and any number of Section Document Elements that follow. Since the Technical Document that was inserted had a Section Document Element as its root, it was a candidate for insertion at the location it was inserted. In the Content Editor, the added external content looks identical to the content that exists within the document.

Any external content that is referenced can be brought into a document as permanent content. In this case a copy of the content of the referenced document is added to the source document, replacing the reference. To copy the contents of a referenced document to the location where it is referenced, right-click the External Content Document Element in the Navigation Pane and select Make Internal.

Figure 34.
The external content converted to internal is grouped using a Group Document Element. This can then be ungrouped. See Section 3.4.1.

A separate Technical Document instance can be created from selected Document Elements. This is useful when the author realizes that there is content within a current document that can be reused in other documents. To create a Technical Document using selected, contiguous Document Elements select the Document Element(s) using the left mouse button. To select multiple Document Elements, hold down the Control Key while selecting each Document Element. Right-click on one of the selected Document Elements and select Make External. The following dialog will be displayed:

Figure 35.
Provide the Name and Document Number for the Technical Document and select OK. After selecting OK, save the original document at which point the external Technical Document will be created and the external reference between the two documents created.

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. Referenced Technical Document Items are not kept unlocked after save or update operations.

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.

Figure 37.
Example Save, Done Editing, Discard Changes Command in Context Popup Menu

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. Users will know the Edit Mode that has been configured based on the existence of the Edit, Save, Done Editing, and Discard Changes menu options in the context 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.

Figure 38.
Example of Locked Referenced Content
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.

Referenced document content is distinguished visually by a solid bar displayed to the left of all content within the referenced document. In addition, when referenced document is editable, the content will be displayed in the same font color and opacity as all other content that exists within the opened Document. By contrast, when referenced document content is not editable, it will be displayed in a different opacity, which appears to the user as a slightly different color.

Figure 39.
Example Technical Document with Non-editable Referenced Document Content

Example of Unsaved Referenced Content

Using Implicit Mode editing, it is possible that referenced content can be changed/saved independent from the changes made to a Technical Document that references it. The Technical Document Editor will track the modification timestamp of all referenced content and compare that to the actual Item before an attempt is made to update the referenced Technical Document Item. When a discrepancy is found, the user will be prompted with the following dialog:

Figure 40.
Warning Dialog for Stale Document Content

Selecting Save will overwrite changes made to the referenced document. In Implicit Edit Mode, saving will cause the referenced Document Item to be locked, updated, and unlocked in one series of steps. Selecting Discard Local Changes will remove the changes made and revert to the latest. Selecting Cancel will cancel the Save with no update to the referenced document content.