In my last post I discussed the concept of executing your specification using different forms of simulation. In this post I’d like to take a step back and examine some of the fundamentals of specification writing in GENESYS. A lot of people use GENESY to start their MBSE journey, but how many really follow through and generate specifications and other documentation directly from the model? Generate diagrams, provide multi-dimensional traceability between entities in the models, yes this is common, but going full out and building the specification from the model itself? This seems to be a lot less common. Let’s fix that!
Specification Overview
Let’s start with an overview of a typical spec format and flow. The GENESYS System/Segment Specification report follows the Mil-Std-961 format very closely. This format is fairly common even outside of the Mil/Aero world and is a generally popular specification format. This basic format is very common and can be tailored for any specific needs your organization may have.
The standard GENESYS provided spec format starts off with some pretty basic “up front matter”. These sections define the usual system descriptions, associated/referenced documents, and any other necessary descriptive material that’s proper in an introduction to a specification.
The next major portion of a specification is the System Capability requirements. This is the real meat & potatoes of the specification. Typically, there may or may not be a section for State and Mode requirements, but there is always a section for System Capability requirements. Typical spec formats may or may not include sections covering interface requirements. Personally, I believe these should be covered in a separate IRS/ICD document, but that is a matter of preference, and some out there will argue for its inclusion in the standard specification template. After the interface requirements come the constraint requirements – the “ilities”, and specific categorized requirements.
Next up, you’ll usually find the “qualification provisions” or, in other words, the verification aspects of the requirements. This is the information that answers the questions on how your requirements in the previous section are going to be verified. What is the objective of your verification statement? What is the method of your verification? What is the environment in which the requirement is going to be verified? What does a successful verification look like?
The last essential section of a specification is the requirements traceability matrix. This shows the traceability between your requirements in this specification and requirements at a higher level of your specification tree.
Last, but definitely not least, and usually overlooked are the appendices. Typically, the appendices are where you can have the most fun, and put in all the useful diagrams that you’ve been building in your model. Adding in the Activity Diagrams or EFFBDs to your spec can greatly aid in understanding the source of the requirements, the logic behind the derived requirements and just generally help the reader understand the desired behavior of the system.
GENESYS Built Specification
So, what does it take to build a specification from your GENESYS model? Let’s start to explore that task a bit. The first thing to understand is how GENESYS is going to traverse the model and use the attributes and relational information you’ve entered into the model to build your spec.
Front Matter
The first parts of the generated specification from GENESYS is arguably the least model based, and the easiest to write. I like to call these sections the “front matter” of the specification. This is where you enter the paragraph text directly against the document in GENESYS. These are paragraphs like the Identification paragraph, the System Overview and the Document Overview sections. This text is written or copied directly into the fields available on the Document element and then placed in the spec by the report writer in the appropriate places.
Specification Setup
The GENESYS specification report begins with a document that is typed as a System/Segment Specification (hereby referred to as the SSS). It then follows the “references” relation to find any other document entities that should be included in the referenced document section of the specification. These are usually typed as either a government document or other, and when typed the report will place them in the appropriate section.
Moving on, GENESYS will follow the “reports on” relation from the document to find the top-level Component that this specification is reporting on. Remember, a specification is written to specify the procurement of some physical thing, so the relation between the document and the component is mandatory. The component being reported on is the starting point for the descent through the engineering meta-model. Typically, entities that are encountered during the descent will be placed in the document according to their number attribute, but if the number is empty then GENESYS will revert to an alphabetical order based on the name of the encountered entity.
States and Modes
From the component, the SSS report fans out following the relations in the database, if you have States and Modes modeled, GENESYS will place any Modes that are “contained by” the Component in the Required Mode segment, then it will look for State’s that the component “exhibits” and place those in the Required States section of the SSS.
System Capability Requirements
Next up in the flow is arguably one of the most important parts of the specification, and here is where GENESYS may do things slightly differently than what most specifications would do. “What’s so different here?” you’re probably asking? You may be thinking this is where all the Requirement entities we wrote and put in the database go? Connect the Requirements to the Component and I’m done, right? WRONG!😊
I’m going to digress a little bit here to explain why the assertion I just made on your behalf is incorrect. In GENESYS the function class is a specification class! What does that mean? Simply put, the function class is meant to be more than just a representation of the functionality needed, it’s intended to capture the functional aspects AND the written requirement text – the “shall” statement! (I can hear heads exploding out there right now, I’ll give your brains a second settle back in place – hang in there with me). The specification classes are meant to be the requirements in your specification.
The SSS report is designed to descend your functional behavior model. It will peel back your functional decomposition level by level and place the text you’ve entered in the description field into the SSS. This is why, for the SSS report to work correctly, your functions need to have the functional requirement “shall” statements written into the function entities description. Supporting text for the function can go in a rationale attribute if needed, or in another paragraph after the shall statement in the description attribute.
To be clear, the standard SSS Report in GENESYS is not going to pull functional requirements out of the requirement class directly, the report will follow the functional behavior decomposition, and pull the description attribute from the function for the 3.2 System Capability Requirements section. It is critical to write the functional shall statement in the description of the function to generate a specification in GENESYS with the default SSS report.
The SSS report will descend the functional hierarchy you’ve modeled starting from the root function allocated to the component the document is reporting on. This root function’s “decomposed by” relationship is then followed to pull the requirement statement out of the function’s descriptions. This means that having your behavioral hierarchy correct is essential to how the specification will turn out. If you have functions decomposing your root function that don’t belong in the specification, they will end up in the document. GENESYS is reading your behavior diagrams to build the spec – which is why in a previous blog post I wrote about the “Executable specification” – you can simulate your specification.
In the System Capability Section, GENESYS will also follow the “based on” relation to show the traceability between the parent requirement and the function being output. These will be output for each function that has a relationship made to a parent requirement and these are pulled from the Requirement class.
In my next installment of this series I’ll cover how GENESYS builds the constraint requirement section and the Interface sections of the standard SSS report. Part 3 of this series will cover the qualifications sections, Requirements traceability matrix, and how the SSS uses the behavior diagrams in the appendices of the specification. Modeling your systems behavior and physical aspects are a great way to develop the understanding of your system needed to develop a quality system and with a little bit more effort the documentation of your system can be built from your model at the click of a mouse button! As always, I hope this is helpful in deepening your understanding of another aspect of the GENESYS methodology.
