How to Perform a Model-Based Review (MBR) - A Digital Transformation

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."[1] A picture of that page is shown in Figure 1.

For more templates like, DoD Milestone A, check out the Digital Curation Station. A meticulously curated collection of essential templates, documents, and architectures, saving you the hassle of searching for them yourself.

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.

Figure 1. DAU Website for the Milestone (MS) A Documents

Figure 2. MS Word version of the MS A Documentation Requirements

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.

Figure 3. Step 1: Configuring to capture 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.

Figure 4. Step 2: Paste information into parser

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.

Figure 5. Step 3: Preview of parsed information

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.

Obviously 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.

Figure 6. Milestone A Documents in Requirement Document Form

Figure 7. Milestone A Documents Artifact with Statements in Documents View

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.[2]

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.

Figure 9. Acquisition Strategy in Innoslate’s Documents View

Figure 10. Adding an Innoslate Diagram into the Entity Description Field

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.

Figure 11. Baselining Documents for Review

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.

Figure 12. Example of adding comments to a diagram

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).

Figure 13. Selecting the Comment Report in Database View

Figure 14. Comment Report Example

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 the 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 sometimes 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.

Figure 15. Use the State Machine Diagram to model the workflow process

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.

Figure 16. Add states as appropriate to model the complete workflow process

Figure 17. Complete workflow model

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.

Figure 18. Adding a new property (attribute) to the Artifact Class

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.

Figure 19. Completed adding a Status attribute to the Artifact Class

Figure 20. Adding Workflow for Artifacts

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.

To use this workflow, simply make the changes to the Status of the Artifact of interest. If you do this in conjunction with baselining the Artifact in Document View, then you can full configuration control over your review documentation.

Figure 21. Final Workflow for the Artifact Status

[1] See https://dap.dau.mil/mdid/Pages/Default.aspx?ms=2&acat=1&acatsub=1&source=All&type=chart0 accessed 2/14/2017.

[2] From https://dap.dau.mil/mdid/Documents/Acquisition%20Strategy%20Sample%20Outline.pdf accessed 2/14/2017.