WordExport templates

  1. Introduction
  2. Note Format
  3. A Basic Template. Custom Document Properties
  4. Import the dradis Framework Schema
  5. Identify Sections
  6. Insert the Document Fields
  7. Upload to the Server

Warning: Please note that this tutorial applies to the latest version of the WordExport plugin which at the time of this writing is only in the subversion repository. For instructions on how to download the latest stable version of the framework from the repository see the Information for developers section.

Introduction

The WordExport plugin lets you export the contents of your repository into a Word XML formatted document.

In order for a note to appear in the exported report it will have to be assigned to the 'WordExport ready' category although the name of the category can be adjusted through the WordExport::REPORTING_CATEGORY_NAME constant.

In addition to this, the note's Text needs to be formatted in a particular way as discussed in the next section of this tutorial.

Finally, you would need a template (although a default one is provided). A template is a specially formated Word XML document that will be filled with the contents from the notes in your repository.

back to top

Note Format

The Framework lets you define your own fields, you can define as many fields as you want in your note's Text as long as you follow the right format.

For this tutorial we are going to use: Title, Risk, Description and Recommendation:

A screenshot showing the format that a note's text should follow in order for the framework to detect the dfields it consists of

back to top

A Basic Template. Custom Document Properties

In order for the WordExport plugin to properly fill in your template, you will need to create a set of Custom Document Propeties in your Word template.

Lets start with a new empty document. Go to the Advance Properties window. File -> Prepare -> Properties -> Document Properties -> Advanced Properties:

A screenshot showing the custom properties once they have been added to the Word document

As you can see in the screenshot above, the set of Custom Properties must match the fields we defined in the Text of our note.

The next thing you need to do is create the document layout that you want. Hopefully any combination will do the trick. For example we will have a Details section and Summary of Findings table:

A screenshot showing a basic document layout

back to top

Import the dradis Framework Schema

Before we can continue we need to import the dradis Framework XML Schema (dradisframework.xsd) to our current document.

The easiest way to do that is through the Developer tab in Word (File -> Word Options -> Popular -> tick the 'Show Developer tab in the Ribbon' check box).

A screenshot showing Word's Ribbon menu, the Developer tab selected and the Schema option highlighted

Go to the Schema option, then Add Schema, choose the downloaded copy of dradisframework.xsd (Note that this file is also provided with dradis in /server/vendor/plugins/word_export/dradisframework.xsd). And fill in the rest of the details:

A screenshot showing the new schema's properties: URL, alias and file location

That would create a new schema in the list and you just need to click on it to associate it with your current document.

Please note that you will only need to do this step once. When you are creating your second template, the schema would already be there and you would only need to associate it with the document.

back to top

Identify Sections

If everything goes according to plan, that should have activated the XML Structure panel on the right-hand side of the window as shown in the screenshot (click to enlarge).

A screenshot showing the XML panel that displays both the structure and elements of the current schema associated with the document

In the upper section of the panel you will see the XML structure of your document (more later). In the lower section you will see all the elements defined in the dradisframework.xsd schema which are:

What we need to do now is go through our document layout and apply these tags to the relevant sections.

To do this, just select the text you want to apply the tag to and then click on the chosen element in the XML panel.

Keep in mind that the plugin will only repeat the sections enclosed between dradis-template tags, so you can have introduction paragraphs, or other sub-sections inside the section that will not be repeated.

In our simple example, the result should be similar to the one shown in the screenshot:

A screenshot showing the template layout with the XML tags applied to the different sections

back to top

Insert the Document Fields

The last thing we need to do with our template is indicate where the plugin needs to place the contents of the different fields of your notes.

As already discussed we are going to use Document Custom Properties to do it, so we need to insert the relevant fields in the right locations of our template.

To insert a field, select the text you want to replace (for instance we are going to use the Title field instead of the current Issue Title) and go to Insert -> Quick Parts -> Field...

In the Field names list, choose DocProperty and in the Property list choose Title. Be careful because there will be two Title properties: the first one is Word's default property, the second one is the one we defined.

A screenshot showing Word's insert field dialog. The DocProperty field name is choosen and the second Title entry is also selected

Repeat the process with every field in you note, replace the dummy text we used to create the look and feel of the template with you Custom Property fields.

Once you have inserted the field, Word will swap your text with the default text you chose when you created the Custom Property. It will also highlight the field with a grey background when you click on it.The final result should look like the screenshot below.

A screenshot showing the template layout with Fields inserted where the contents of each note should go

back to top

Upload to the Server

The final stage in this proces. Save the document as a Word 2003 XML document. Use the filename template.xml.

Go to your dradis installation folder, backup the current template (./server/vendor/plugins/word_export/template.xml) and replace it with your new one.

You don't need to restart the server in order for the plugin to pick up the new template!

To get you started you can download the sample template we have created during this tutorial. There is also a new entry in the WordExport menu: View template that lets you inspect the current template used by the plugin.

back to top

using dradis:

developing dradis:

support from:

want your link here? +

If you're part of the community, have used the tool, like the project or want to tell everybody you support the project and it's goals, do not hesitate in contacting us so we can add your link.