Why MBSE Still Needs Documents

A lot of people are pushing Model-Based Systems Engineering (MBSE) in a way to just deliver models … and by models they mean drawings. The drawings can and should meet the criteria provided by the standards, be it SysML, BPMN, or IDEF. But ultimately as systems engineers we are on the hook to deliver documents. These documents (specifications) form the basis for contracts and thus have significant legal ramifications. If the specifier uses a language that everyone does not understand and only supplies drawing in the model they deliver, confusion will reign supreme. Even worse, if the tool does not enforce the standards and allows users to put anything on the diagram, then all bets are off. You can imagine that the lawyers salivate over this kind of situation.

But it’s even worse really, because not only are diagram standards routinely ignored, but so are other best practices, such as including a unique number on every entity in the database or a description of each entity. As simple as this sounds, most people ignore doing these simple things until later, if ever. This leads us to our first question:  1) Is a model a better method to specify a system?

This question requires us to look at the underlying assumption behind delivering models vs. a document. The underlying assumption is that the model provides a better communication of the complete thoughts behind the design so that the specification is easier to understand and execute. Which leads us to the next question: 2) Can a document provide the same thing?

Not if we use standard office software to produce the document. The way it is commonly done today is that someone writes up a document in a tool like MS Word and then that files is shipped around for everyone to comment on (using track changes naturally) and then all the comments are adjudicated in a “Comment Matrix.” Once that document is completed someone converts it to PDF (a simple “Save as …” in MS Word). In the worst case, someone prints the document and scans it into a PDF. Now we have lost all traceability or even the ability to hyperlink portions of the information to other parts of the design, making requirements traceability very difficult.

However, if you author your document in a tool like Innoslate, you can use its Documents View to create the document as entities in the database. You can link the individual entities using the built-in or user created relationships to trace to other database entities, such as the models in the Action Diagram, or Test Cases. This provides traceability to both a document and the models. In fact, the diagrams in Innoslate can be embedded in the document as well, thus keeping it live, reducing the configuration management problem inherent in the standard approach.

MBSE doesn’t mean the end of documents but using models to analyze data and create more informative documents. Using a tool like Innoslate lets you have the best of both worlds: documents and models in one complete, integrated package.

How to Make Requirements Approvals Using Innoslate

One question we often get is: does Innoslate do workflow? What people mostly mean by this question is how can they approve documents and requirements and be notified that that approval has occurred? How can we be sure the right person approved the item? Innoslate provides this capability using what we call “lightweight workflow.”

Lightweight work flow follows a simple process using the notifications, labels, history, and baselining features of Innoslate. The steps of that process are provided below.

Step 1: Setting up a signature block.

Most requirements approval occur at a document level. An example would be a standard operating procedure (SOP) for a project. The set of requirements are embedded in the SOP document. Innoslate provides templates for SOPs that can be used to develop them. You only need to access the SOP document (Menu/SOPs as seen below).

 

You can then select a blank document or the Standard Operating Procedure (With Guidelines) and the template will be produced.

In this template, there is a signature block. These can easily be separated in to separate blocks or you can break them out individually.

The screen shot below shows an example of breaking out the signature blocks. We have already added the information about the signatories of the SOP (Project Manager, Program Manager, and Division Manager).

Each manager may want to subscribe to one or more of these block for notification when it has been changed. Subscribing to an entity is easy and available from Entity View. Just select the entity and open the Entity View, as shown below.

In the Entity View of the signature of interest, select the “More” button and “Follow” the entity. The “Follow” tells Innoslate that you want to receive a notification anytime this entity is changed. When a change is made an e-mail will be sent to your e-mail address.

So, once the Project Manager approves of this entity, by adding the “Approved” label (note you may have to add this label as its not part of the standard label set), and the initials or a picture of the person’s signature can also be added at the same time, then an e-mail will be sent out to anyone subscribed to the entity. The e-mail below shows the notification I received from Innoslate.

Going back to the SOP and selecting the Project Manager entity, we see that the approved was made (see below).

The time and date of this approval and who approved it is recorded in the history of that entity, which is accessed from the Entity View using the “History” button (see below).

If you want to ensure that no changes occur elsewhere in the document after each approval, you can use the baselining feature (see the “Baseline” button at the top of the Document’s View).

This action will freeze the changes and only allow changes to the next version.

So using these techniques, Innoslate provides all you need to ensure that the requirements documents you produce follow your workflow.

How to Import Complex Documents into Innoslate

One of the first things you want to do when using a requirements or PLM tool is to import complex documents into the tool, so that you can begin analysis. Most documents have pictures, tables and other elements of information that you want to be able to access. Often these complex documents come as an Adobe Portable Document Format (PDF) file; other times they come as Comma Separated Values, MS Word and other formats. In this blog, we will deal with PDFs.

When bringing in a new document, we recommend starting with a new Innoslate project. Also, most documents are a result of non-uniform word processing, which means that import software has to deal with many different possible numbering schemes and formats. This fact makes getting a document into a toll very difficult. Fortunately, Innoslate’s Import Analyzer provides the means to overcome most of this problem, but you may want to do a little bit of work on the file first.

PDFs come in two forms: 1) scanned documents; and 2) selectable documents. The first one requires the use of Optical Character Recognition (OCR) software. We recommend Google’s as it seems to be one of the best, but many other tools for OCR are available. This process converts it into a selectable document.

Once you have the document in an editable PDF format and you have a copy of the latest version of Adobe Acrobat Pro, you can try to save the document as an MS Word file. Adobe tends to do a very good job converting documents this way. You may still want to go through and clean up the document, such as removing the table of contents and other unnecessary information.

After you have the document in the format you want, select the Import Analyzer from the Menu and follow the process of using the “Word (.docx)” tab, selecting the class for import (Next), and dragging the file into the window for import (Step 1). The upload and analysis process may take a minute or so, depending on the size and complexity of the document (Step 2). The analysis includes the creation of parent-child relationships (decomposed by/decomposes) as identified by the numbering scheme.

Once the upload and analysis are complete, just select “Next” and you can see a preview of the information as it has been captured (Step 3). If satisfied, then select save the entities into the database.

Step 1:

Step 2:

Step 3:

The end result of this process is the document being seen in the Requirements View. The analyzer includes any pictures and tables, if they were properly developed that way in the original document (see below).

 

 

If you already have another project to which you want to add this one to, you can export and re-import the Innoslate XML file, or (better) use the branching/forking capability (go to Database View and use the “Branch” button). When creating a new branch, instead of selecting a “New Project” use the “Target” drop down menu to select the project with which you want the document to merge (see right).

 

The process above is a best-case situation for complex documents. Sometimes, this approach to importing fails due to problems in the MS Word document itself.

The second way to import a PDF file is to use the “Plain Text (.pdf, .txt, etc.)” tab in the analyzer (shown below).

Here you need to give the Artifact (the entity that will store the uploaded document) a name, which you can edit later. Again, select the class type for import (we default to Requirements, since that usually what you are importing). Finally, we need to select the type of list contained within the document, again for the purpose of creating the parent-child relationships.

 

 

After clicking the “Next>” button, you can paste the copied text from the file into the space provided. After clicking the Next button on that screen, the analysis proceeds and then you can preview the results as before.

 

Finally, the worst-case scenario is a PDF document that cannot be easily imported using any of the Import Analyzer tools. Although this is rare, it does occur. Recently I was asked to import a portion of the US Code. For anyone who has seen it, it’s double column and contains a lot of unusual characters. So, I determined that the fastest way to bring it into the tool was by cutting and pasting objects into the Requirements View of an Innoslate Project. I used this as an opportunity to conduct analysis on the document as I went. Since I was not under a tight deadline (I had days to perform the task, not hours) and we ultimately wanted to perform requirements analysis anyway, this let me take blocks of text and treat them as Statements, instead of Requirements, when they really only provided context or breakup paragraphs that contained multiple requirements into individual entities to they could be separately traced. That effort took a person day and one half, while the other ones above had taken really only minutes, but no analysis was done.

 

All-in-all Innoslate provides the means to bring any and all information from the outside into the tool. You can then use that information to complete the rest of the lifecycle within the same tool environment (with no plug-ins required).