Importing and tracing from a Source Document using Sparx EA 12

*** Currently there is a Bug in Sparx EA 12.0.1215 that prevents you from using the features in 3.1 and 3.2 ***

http://www.sparxsystems.com/cgi-bin/yabb/YaBB.cgi?num=1438024703/0#0

As a Business Analyst I often reference existing documentation as a source of statements that describe people, processes, requirements, rules etc, included in my analysis.   Early on I discovered that Sparx EA allows me to import and store RTF documents, and then directly generate elements in the repository by selecting statements from these documents.   Unfortunately the interface for this feature is NOT very user friendly, requiring you to navigate several nested menus each time you want to create a new element.   To address this issue (and later to simplify some other tasks), I decided to use an application called AutoHotKey to reduces these steps down to a single Keyboard Shortcut.

For this post, I’m going to use the Canadian Regulation: Heavy-duty Vehicle and Engine Greenhouse Gas Emission Regulations (HDVEGGER) (SOR/2013-24) as the source document.

To import this regulation you will need to:

  1. Create a new Package and Document Element to contain a Source Document.
  2. Convert and import the HTML document as a linked document
  3. Create an Element for each statement in the Source Document that you want to trace from
  4. Bugs and workarounds for using this feature.

1.0: Create a new Package and Document Element to contain a Source Document

I find there are two types of documents I typically work with:

  • Source documents that contain statements that may impact more than one project (e.g. legislation, regulations, standards, etc.)
  • Source documents that only impact the current project (e.g. minutes from meetings, emails, change requests etc.)

1.1: For source documents that impact more than one project

  • Heavy-duty Vehicle and Engine Greenhouse Gas Emission Regulations (HDVEGGER) (SOR/2013-24)
    • Extracted Statements
    • Derived Terms and Domain Model
    • Derived Requirements

This package structure allows me to keep the results of my analysis with the source document so I can more easily identify what requirements and terms came from this specific source document v.s. the requirements and terms documented in a project that may be an amalgamation or compromise between information derived from multiple source documents.

1.2: For source documents that only impact the current project

  • Minutes from 2014-05-05: Meeting to …
    • Packages dependent on document type(s).

This package structure allows me to keep a set of documents together that may have come out of a single meeting, e.g. mind maps, videos etc.

For some short documents like emails I may not even directly extract the statements, instead I’ll trace from the source document to the impacted requirement, rule, activity, etc.  and include the statement in the notes of that item (more on this in my future post on writing requirements).

1.3: Creating the Document Element

Personally I use the tool-set: Documentation -> Document Artifact for my element type, but you can create a linked document for any element or package in Sparx EA, so it’s up to you what you choose.

Once I’ve created the new “document” element there are three ways to create a linked document:

  • Menu: Select an element -> right click -> Linked Document
  • Keyboard shortcut: Select an element and press Ctrl+Alt+D
  • Icon: Select an element and if you have the “notes” window open, you can select the linked document icon

sparx_ea_notes_dialog_box_arrow_to_linked_document

2.0 Convert and import the HTML document as a linked document

When published to the web, many documents are broken in to multiple pages to make them easier to read and navigate in your browser.  Unfortunately this can make importing these documents a bit of a pain.   Luckly many sites now have links to full text versions, or print versions that contain all the sections of the document.

For the HDVEGGER there is a full text version that we can work with.  If you already have your source document saved as an RTF file, you can skip to the next section.

2.1: Option 1 (Best): Convert from HTML to RTF using a word processor, example uses MS Word

I’ve found the built-in document editor in Sparx EA is still a bit limited for creating new documents, so I’ve found it is better to do a bit of preparation work on the source document in a more fully featured word processor before importing in to Sparx EA.

  1. Navigate to the full text version
  2. Use your browser’s “File -> Save As” feature to save a copy of the page to your computer
  3. Open MS Word, or some other word processor that supports both html and RTF.
  4. Load the .htm(l) file in to the Word Processor

At this point you should see the unmodified document in your Word Processor (download .rtf):

Screen shot of the Regulation pre-cleanup

I personally like to do three things at this point:

  1. Remove all the navigation menu links from the beginning and end of the document.
  2. Remove all the hyperlinks to other documents
    • in MS Word for windows you can do this quickly by selecting all (ctrl+a)
    • with the text selected press ctrl+shift+F9
  3. Remove any extra text, in this case “Footnote” and “Return to footnote” were removed using search and replace.

At this point you should see the prepped document in your Word Processor (download .rtf):

import_HDVEGGER_to_sparx_html_prepped

You can now return to the linked document you created in step 1.3 and import the RTF file in to Sparx EA

  1. Menu: Select the blank document -> right click -> File -> Import -> Select the prepped RTF file you created
  2. Keyboard Shortcut: none
  3. Icon: none

sparx_ea_import_dialog_box_rtf

2.2: Option 2 (Mixed results) import directly from HTML in to Sparx EA

The later versions of Sparx EA introduced the ability to import not just RTF documents but also HTML files.  This can work for simple HTML source documents, but I’ve found it isn’t the best for larger ones with more complex formatting or other issue you may want to clean up.

  1. Navigate to the full text version
  2. Use your browser’s “File -> Save As” feature to save a copy of the page to your computer
  3. You can now return to the linked document you created in step 1.3 and import the HTM file in to Sparx EA
  4. Menu: Select the blank document -> right click -> File -> Import -> Select the prepped HTM file you created in step

sparx_ea_import_dialog_box_html

3.0: Create an Element for each statement in the Source Document that you want to trace from

Now that you have the Source Document in Sparx EA as a Linked Document, you can start extracting statements from the document to use as the source of your requirements, rules etc.

For most regulatory documents I’ve found that a good place to start is any section that discusses the Reports, Notices etc. that have to be created by the Regulatee and sent to the Regulator, for HDVEGGER this section starts on Section 48 (page 63 for my imported document)

*Note: To improve traceability I typically update the paragraphs to have the fully numbered path before I use them for a statement.  (I’m hoping to make a script that will automate this)

For Example:

  • Original: (2) The end of model year report must indicate…
  • Updated: 48(2) The end of model year report must indicate…
  • Original: (A) conform to the applicable N2O and CH4 emission standards…
  • Updated: 48(2)(a)(ii)(A) conform to the applicable N2O and CH4 emission standards…

3.1: Option 1 the slow way (not recommended)

  1. Select the text that you want to create a Statement from
  2. Menu: right click on the select text -> create -> new -> other
  3. In the “New Element Dialog”, Select Toolset -> requirements
  4. Select Type: Requirement
  5. In Stereotype: type “statement”
  6. Press Create

3.2: Option 2 the fast way (needs AutoHotKey)

First make sure AutoHotKey is installed, running, and my custom script is active.

  1. Select the text that you want to create a Statement from
  2. Press Ctrl+ + on you number pad
  3. The “New Element Dialog” should now be displayed, with everything filled in.
  4. Press Create.

For both options you should now see the selected text as a hyperlink.  Click on this link will highlight the related element in the project browser.

sparx_ea_import_link_and_new_element

Bugs and workarounds for using this feature.

If you don’t see a hyperlink, you are probably experiencing what I call the “long text” bug.  If the selected text is greater than 255 characters the element will be created, but the hyperlink will not be created.   To fix this you have to:

  1. Re-select the text
  2. Menu: right click on the select text -> create -> Link to Existing Element
  3. In the Selected Classifier dialog, either browser for the Element or use the Search Tab to locate the element.
  4. Select the Element and press OK
  5. The text should now be properly linked.

Or if AutoHotKey is installed and running with my custom script.

  1. Re-select the text
  2. Press Ctrl+ 0 on you number pad
  3. The Selected Classifier dialog should appear with the Search Tab selected and the Element (or elements) with the name matching selected text will be listed.
  4. Select the matching Element and press OK
  5. The text should now be properly linked.

If your links are going to the same element, I’ve found that occasionally if there isn’t a gap between links they get combined.  To avoid this I leave a character (. or , or space) between sections of linked text.

One thought on “Importing and tracing from a Source Document using Sparx EA 12

Leave a Reply

Your email address will not be published. Required fields are marked *