A SysML Requirements Document with SparxSystems Enterprise Architect

SparxSystems Enterprise Architect comes with several templates for rendering graphics-based models into RTF and PDF.  If you find that the templates are too restrictive, you can create your own.

This SysML (1.2) Requirements Model contains three requirements in a package called "Specifications".  "Detect intruders" is broken down into two more specific requirements: "All weather conditions" and "24/7 operation".

In SysML, a requirement is an id / text pair where the id is usually a structured key indicating the source of the requirement (ex, "SYSX" for System X) and a hierarchy (1.1 belongs to 1).  "text" is the description of the requirement and is not limited in length.  id and text are represented as attributes in a compartment "tags".

A SysML Requirements Diagram

(This screenshot is from EA 9 and the requirement text is not able to be shown.  In EA 10, the <memo> representing the requirement's text will be replaced with the actual text in accordance with the SysML standard.)

"All weather conditions" and "24/7 operation" are represented as child objects of the "Detect intruders" requirement.  The hierarchy is enforced manually through id assignment and in the Project Browser by dragging one requirement over another.

Nested Requirements Elements

Generate Documentation

You can distribute this model by generating an RTF or PDF.  Right mouse click on a package, select Documentation, select Rich Text Format (RTF) Report to bring up the Generate Documentation dialog.  Alternatively, select a package and press F8.

Dialog for Document Generation and Template Management

(basic template)

Out-of-the-box, EA will select the "(basic template)" template.  This will result in an RTF file like the following.

RTF Document Generated with (basic template)

The document contains a table of contents, an embedded image of the model and a section for each of the three requirements.  However, this may be too verbose if we're interested in only the id and text of a requirement.  That is, three sentences has produced a 5 page document.

Templates

To create your own template, go to Settings > Document Template Designer.  A window like the following will appear.  Press "New" and give the template a name.

Document Template Designer

When the template is given a name, the check boxes on the left of the screen are enabled.  Check Package Element (this will also check Package), Element, and Child Elements (if not already selected).  This defines the looping structure of the document.  Each Package will be rendered (we're selecting only one), each element in the package will be rendered, and each child package will be rendered in turn.

Document Looping Structure

Remove the boilerplate text in the curly braces {}.  Right-click and insert the fields that you want shown such as "Name".  This will print out the package name and the handy short name I gave each requirement (not the standard id or text fields).

"Child elements" is important because of the nested requirements that I set up in the Project Browser.

Insert Field

EA represents the SysML attributes as tagged values and there are two ways to output them.  One way is to explicitly print out all the tagged values.  The other is to use the Insert Field > valueOf construct to intersperse the tagged values with other element attributes such as "Name".  The following screenshot shows the Insert Field menu -- displayed by right-clicking in the appropriate section -- which is used to put in the Name and valueOf references.

Document With Fields

I also formatted the sections and added some line breaks to make the report more readable.  The result is a much smaller document, but one that contains the essential SysML information.

Custom-built SysML Requirements Document Template

In a few short steps, you can produce a document template that supplements the standard templates of EA.  In some cases, less information is more valuable.  There's nothing more disconcerting than throwing a GUID in front of a customer.