Since Model-Based Systems Engineering (MBSE) is all the rage today, one aspect of MBSE that often gets ignored is the need to use the database capability to support reviews. Often, we pretend that the modeling tools are there just to produce the documents from the database, but the primary value of MBSE comes from having an interactive medium for reviews as well as development of the design information.
If you use a tool like Innoslate® you will find many features that enable Model-Based Reviews (MBRs). Innoslate has a “Documents View” that provides a means to develop documentation in a human-readable form within the tool and enabling linkages directly to the live diagrams and other aspects of the database. This feature simplifies the reviews significantly and enables more of an “in-process review” approach. In addition, Innoslate® provides a means for reviewers, who have “read only” access to the project, to post comments on diagrams and at the entity level. Those comments can be directly responded to within the tool so that both the designer and reviewer can see the questions and answers in one place. A report of these comments can also be downloaded and provided to those who can’t (or won’t) access the model directly.
Below, we show a quick look at how to go about setting Innoslate up to perform a MBR.
Capturing the criteria
The first step is to capture the criteria into the tool. We do this by identifying the review criteria used by the customer. For example, if we want to support a Milestone A review at DoD, we would go to the Defense Acquisition University website that provides that information. In this case the “Milestone Document Identification (MDID) page. A picture of that page is shown in Figure 1.
We can capture the information shown in this figure by copying the document names shown and copying them to a MS Word document or directly into Innoslate’s Import Analyzer. With a little manipulation and adding a number scheme we can create a new document within Innoslate to reflect this information. Figure 2 shows an example in MS Word.
The next step is to add this information into Innoslate’s Import Analyzer. We do this by copying the information and using the Import Analyzer (Plain Text tab) to bring the information into the tool as Statements. Select the Import Analyzer from the Innoslate Menu, then select the “Plain Text” tab. The first step is the configuration step. Figure 3 shows this step.
We add the name of the Artifact, in this case “Milestone A Documents, and select the class (Statement), and finally select the Multi-Level List type to match the numbering of the information.
Once we complete this portion, we select the “Next >” button to go to Step 2. In step 2 we paste the information copied from the MS Word document (or directly from the website) and make sure it looks correct. Figure 4 shows this step.
Selecting “Next>” again moves the process on to Step 3. Figure 5 shows the results of Step 3. The parsing may take several seconds to complete.
This process will result in displaying the information as a Requirements Document (see Figure 6). You may want to leave it as a Requirements Document or you can change the document type, by giving it a different label. We can also add information about each document (obtained from the definitions on the original DAU website). The result is shown in Figure 7.
If you have other requirements for a particular review, you can use the same process for adding that criteria. If you have more, you may want to create a master document that has all the criteria. Then all you have to do is direct the reviewers to this master document. It can become the review checklist. In the case above, this is the master list for the DoD MS A review, so we will proceed from this list.
Adding the Document Content
Once we have all the criteria established, we can now add the specific documents that must be created to meet these criteria, such as the Acquisition Strategy, by linking between the list of MS A documents and the individual documents. From the DoD website, we can obtain the Acquisition Strategy Template provided by DoD. A portion of this template in MS Word form is shown in Figure 8.
Figure 8. MS Word Template for the DoD Acquisition Strategy Document.
By using the same technique for capturing the criteria, we can also capture this template in Innoslate. The result can be seen in Figure 9.
In this figure, we can see the same information as in the MS Word template, but already a new figure has been put in place of the original OV-1 example from the template. This OV-1 is an Asset Diagram from Innoslate. It was inserted using the “+” menu with the “Image” option available when selecting the description field because the diagram is in another project. When you select “Image” it will prompt you for the type of diagram (in this case we select the Asset Diagram) and then the specific asset diagrams available. Clearly this diagram must be created first, which we did using the DoDAF Dashboard in Innoslate in a different project. You can then establish a hyperlink between the image and the diagram by using the URL of the diagram. If you right-click on the image you can then open the link in a new tab or window, as shown in Figure 10.
Now we can treat the Acquisition Strategy just like we would in MS Word, including bolding, italics, underline, subscripts, and superscripts, as well as adding tables and other information. If we want to link to a particular entity, not a diagram, we can use the hyperlink in the “+” menu as well. So, you can effectively do most of what you do in a word processing tool within Innoslate. The real benefit comes from being able to link between these Statements and other aspects of the database, including Risk and Decision entities.
We recommend baselining each document you create, once it’s been approved, prior to the milestone review. That way you can track any changes between the original pre-MS-A document and post. To baseline the document, simply select the “Baseline” button in the tool bar. You will then be presented with a drop down to give it a name. In Figure 11, we show that name to be “Pre-MS A Draft.” Push the blue Create button and the document is baselined, turning the yellow bar to blue. Note that this action cannot be undone, as organizations will use this as part of a legal process to ensure integrity of documentation.
Reviewing the Models
Once the documents and models have been completely setup and baselined, you can now provide access to the project to the reviewers. We recommend sharing the project as “read only” with reviewers. Then the reviewers can navigate the models and post comments in the diagram views or directly in the individual entity views. For example, if a reviewer needed to review and comment on the OV-1 in the Acquisition Strategy, they would initially start at the overall criteria Artifact (Milestone A Documents) in documents view, then select the Acquisition Strategy hyperlink to open a new window with that document. Then they would scroll down to the OV-1 diagram. Selecting that diagram then would open another window with the Asset Diagram that contains the OV-1 as shown in Figure 12. The reviewer then selects the “Comments” tab and posts a comment in the window provided (see upper left of Figure 12). If necessary, a designer could respond directly to the comment right at this point. So, you could develop an interaction between the review team and the developers, if desired. How many times have you received a comment and wondered “what did they mean by that?!” Obviously, such interactions would have to be tempered, but it could be very valuable in reducing the lack of clarity that often occurs in a review.
To obtain a summary of the comments, just go to Database View (see Figure 13) and select the Comment Report. The output of that report is a tabbed spreadsheet with all the entities, their descriptions, and comments (Figure 14).
Thus, we have not only the comments and answers in one simple place, but it is also accessible directly in the database as well.
Taking this approach to reviews will reduce the time and cost of reviews and increase the quality of the results of the reviews. It also means that you can establish more “in-process” reviews rather than wasting weeks in preparing for a review. Also, the results of all the previous reviews will be accessible to everyone who needs access. You can always un-share with people who you don’t want to have access to the database. I think you will see the benefits of MBRs after the first review.
Adding Artifact Workflow
Often, we want to control the approval cycle of the document at the Artifact level, rather than requirement by requirement. To set this up, we may first want to model the workflow prior to modifying the schema to include this new workflow. We can create this model using the State Machine Diagram. To create this diagram from scratch, just go to Diagrams View and select this diagram type from the list of New Diagrams. You will be prompted for the number, name, and a description field. Then a blank canvas for the diagram will appear. Just use the pallet at the left to drag and drop the Initial, Final (which is actually the end state, not necessarily the Final state of the document as we will see below), and states of interest to the canvas. An example is shown below in Figure 15.
The line connecting the Initial state to the Draft state is created by selecting Initial state and then the green circle it. Drag the green circle toward the Drat state and a line begins to appear. Once you connect it to the Draft State you can change the name, number, and description in the sidebar. These represent the actions of making a transition from one state to another.
Go ahead and create the other states as seen in Figure 16. Note we created a “Final” state that is different from the end point “Final” concentric circles. You can use this when there is no end state as well.
Finally, connect all the appropriate boxes to each other with transition actions as before. The end result may be something like Figure 17. Note that the last transition in Figure 17 will likely mean that there is no changes allowed from the Archived state. You may want a transition back to Revision or even Draft state. That’s totally up to you and your management process.
Now once we are happy with the model, we can easily translate it into the workflow portion of the Schema Editor.
To edit the schema we must first add a Status attribute to the Artifact class. We do this by selecting the Schema Editor from the menu and then the Artifact class from the Classes for editing. Once you have the Artifact class schema ready for editing, just add a new property using the “Add Property” button. Figure 18 shows the resulting screen.
The Workflow process uses enumerated attributes. So we simply change the Property name from “Property (3)” to “Status”, the Type to “ENUMERATION”, add the choices, which are your states from the State Machine Diagram, and then select which one of the is the default option from the initial (new) state, in our example “Draft.” The result can be seen in Figure 19. Don’t forget to hit “Save” as Innoslate® will not make schema changes without a positive saving of the updated schema.
Now all we have to do is add the transitions (from our State Machine Diagram) using “Add Transition” drop down box at the top right of each state. Then for each transition, we will identify who we want to be able to make the transition from one state to another (Permissions), who is to be notified when such a transition occurs, and if we want to lock the entity after the transition. A resulting screen for the model we created above is shown in Figure 21. Note that you can easily delete any mistakes by using the black “X” at the far right end of the row. Also, note that this feature is only available to an Owner of the Project. It schema modification to the Artifact class can also be setup at the Organizational Level.
 See https://dap.dau.mil/mdid/Pages/Default.aspx?ms=2&acat=1&acatsub=1&source=All&type=chart0 accessed 2/14/2017.
 From https://dap.dau.mil/mdid/Documents/Acquisition%20Strategy%20Sample%20Outline.pdf accessed 2/14/2017.