Mapped Document Elements (MDE) are a core feature added to the existing Technical Document Framework (TDF) application, released in Aras Innovator Version 12 Service Pack 5 for all users. This enhancement allows for the association of Document Elements in a TDF-enabled document to a Property of a referenced Item. A Document Element to Item Property association means that the properties of the Item in the Tech Doc will update as the Item’s property is updated. Additionally, the Element can be flagged with ‘write’ permissions to allow for editing and saving the Property value directly from the Tech Doc.
MDE is a useful feature for ensuring a Tech Doc’s references to an Item stay updated as the Item’s properties are changed. One application of this feature is documenting the most recently calculated cost of Parts in an assembly. This blog post will cover enabling MDEs for Part Items and mapping a Part Item’s name property to a Technical Document.
Enabling Mapped Document Elements in TDF
By default, the new Mapped Document Elements are not included in the Standard schema, to prevent any unexpected behavior with existing ItemInfo Elements in Tech Docs. We’ll need to create a new schema to utilize the enhancement.
- Go to Technical Documentation > Document Types in the TOC
- Right click and select Create New Document Type
- Fill in the name field with ‘MDE Enabled’
- In the content section, copy and paste this code:
gist.github.com/…/24420dfa39e6af880ce0a17f456c56f1 - In the Stylesheet tab, click Add New Document Style
- Enter the name ‘MDE Enabled Stylesheet’
- Right click and select Stylesheet > Open
- In the style section, copy and paste this code:
gist.github.com/…/3d5e5e5eaecbd8c302874fea7fb1ea2a
- Click on the Validate button, the schema should be valid
- Click Done to save
Adding an MDE to the Document
Now that the schema is made, we can start to build our Tech Doc. First, we’ll want to create a Tech Doc that uses our new Schema:
- Go to Technical Documentation > Technical Documents in the TOC
- Right click and select Create New Technical Document
- Fill out the form’s required information:
- Document Number – ‘MDE-0001’
- Name – ‘MDE-Test’
- Schema – MDE Enabled
- Save (but don’t close) the new Tech Doc
- Click on the Tech Doc Editor tab that was added to the left side column
From the Editor tab, we can start adding elements to our Tech Doc. Adding a Mapped Document Element is like adding any other Element to a Tech Doc, with some additional steps for selecting the specific Part. Just follow the steps below:
- Right click on the root element and select Insert > Item Info > Add Item. In the dialog, search for and select the desired Item, then click OK
- Right click the ItemInfo entry in the tree and select Insert > PartStatement > Add Item. In the dialog, search for and select the desired Item, then click OK
- Right click the PartStatement entry and select Insert > Any Property
- Right click on the AnyProperty entry and select Edit Attributes to open a dialog
- In the property field, enter ‘name’
- Select ‘write’ for the mode
- Click apply
- Save (but don't close) the Tech Doc
While the Tech Doc is claimed and in edit mode, you can double-click on the Property in the editor pane to open a pop-out field editor. When selected, an MDE with write permissions will have a gray dashed border, while a read-only MDE will have a solid red border. Changes made in that field can be added or discarded by clicking on the check or x boxes, respectively. Once a change is made, the element in the tree and its parent element will be marked as changed with a pencil icon; clicking on that icon will open a dialog prompt to revert the changes. To save any changes made to an Item, just click Save or Done. On a save, any changes to Properties will be validated by the system.
Additionally, if changes have been made outside of the Tech Doc, the property in the editor will be highlighted with a red dashed border. The right click menu on the PartStatement tree element will now contain a Version menu, which gives you option to update the data to reflect the latest version, ignore the current version, or ignore this and all new versions and changes.
We’re excited to share this enhancement to the Tech Doc Framework; this core feature will enable other new features in future Requirements Engineering and Technical Documentation application releases. To take advantage of the range of options available in Technical Documents, check out our previous blogs that cover other ways to customize your Tech Docs, such as custom content generators, adding links to Documents, and creating templates. We also have a GitHub repo with a number of custom Technical Document examples to use as ideas for your own Tech Docs.