In systems engineering practices, system design and analysis have been historically performed using a document-centric approach. In a document-centric approach, stakeholders produce a number of documents that represent their respective views on the mission or system under development. Given the ad-hoc, disparate, and informal nature of natural language documents, these views can quickly become inconsistent. Currently, dependencies between these views [2] are often implicit or informally defined in supplementary documents. Additionally, documents are often accompanied by a variety of engineering models that are siloed. It is often difficult to trace provenance across the different, distributed sources of information and verify their consistency. A significant amount of time is consumed by engineers searching for up-to-date information from other stakeholders.

In a document-centric approach, rigor in engineering work is lost in the transition from engineering design and analysis to engineering documents. Once the documents are delivered, the engineering portion of the work is disconnected from the resulting artifacts. For example in the following thought experiment, Simulink model data and system requirements are merged at the point of document writing and never represented in a managed engineering environment. The design represented in the Simulink Model responds to requirements captured in DOORS and is usually manually managed with some kind of traceability matrix in a document without managing the configuration of requirements or design elements. Furthermore, elements of the design and requirements are referenced in the engineering documentation but they are neither configuration managed nor formally traceable to the engineering source.

Numbers, statements, and conclusions are now siloed and disconnected from the original engineering data, resulting in the last author serving as the source of truth, and implying a loss of value of the intellectual property. It requires an immense overhead to maintain consistency and perform impact analysis as one must arduously rediscover the previous engineering work instead of immediately progressing to the next engineering task. Using documents to inform engineering design or analysis is not rigorous because it is difficult to audit the original source of data and decisions that were made.

OpenMBEE is an integrated set of software applications and services which replaces silos of information with consistent, traceable, and precise engineering models and documents. Information is mutually consistent and correspondent. Using transclusions, the platform upgrades a document-based process with a model-based engineering environment. Transclusion is the rendering of model information inline with unstructured narrative in model-based documents. The next figure illustrates this concept. In the first step, a piece of engineering information, shown in blue, exists in models, processes, and documents and is initially disconnected. In the second step, transclusions are used to create linked-data documents that close the gap between model and documentation, ensuring that they are mutually consistent and correspondent. In the third step, those documents are made available in a collaborative space where engineers author, review, modify, and release those documents according to the access granted to their respective roles in each linked model.

OpenMBEE constructs linked-data documents by using the Document Generator (DocGen) query language and MDK [1] to gather relevant model data to produce views. DocGen is a module of MDK that constructs and generates views that consist of model elements collected by the DocGen query language. The model elements are sourced from different modeling languages and the views conform to the IEEE/ISO 42010 view and viewpoint paradigm [2]. The method by which data is extracted out of and/or synced with applications and services are adapted for its conventions and native workflows. For example, in the case of the Cameo Systems Modeler client changes are tracked and transparently synchronized bidirectionally with MMS while the MATLAB MDK “toolbox” allows users to integrate the provided MMS element pull and push functions directly into their MATLAB code. The data is version controlled in the MMS repository and rendered as an editable document in the View Editor web application. The model can be accessed through a rich modeling tool such as Cameo Systems Modeler, MATLAB or Mathematica, through an HTTP-based REST API [7], or an analysis platform such as Jupyter [8].

The following figure shows how the OpenMBEE concepts map to the implementation.

OpenMBEE’s implementation allows the engineer to focus on technical and engineering work by concurrently editing both the model and document, thus reducing cost and time by preventing duplication of work and automatically keeping the documentation and models consistent. Sharing the documents in a collaborative web application reduces inconsistent data while improving accessibility of model data to stakeholders.

DocGen [5][6] provides a structured representation of documents while still allowing incorporation of unstructured data into structured engineering data. This mechanism dramatically lowers the barrier for modeling by enabling a process referred to as model hardening, by which engineers can incrementally add formalism to their models as their thinking matures from concept to design.

Transclusions can synthesize data for engineering when the information is not simply hyperlinked, but referenced in place. Therefore, the link to the authoritative source of information is preserved and maintained. The use of transclusions also provides a new means of measuring the maturity of the captured information overall referred to as model hardness. For example, early in the lifecycle models are often boxes and lines without semantics, have little to no scope, or are developed without external context. Those boxes and lines are gradually transformed into formal system models as abstractions are defined and the problem analysis progresses. Systems Engineering documents are largely narrative but reference model data informally, e.g. by cut and paste, which is error prone and difficult to trace. OpenMBEE addresses this problem by its transclusions, i.e. allowing the authors directly embed model data into the narrative and keep it under version control. Early lifecycle documents which are generated or related to these models typically utilize a relatively low number of transclusions. By the end of the life-cycle, the interconnection and use of models and structured data should be rich, which is evidenced by a large number of transclusions. Unstructured data indicates sections of the engineering design which require more development. A mature and structured model enables projects to define more focused rules and policies for verification of the model. The corresponding documents therefore include more transclusions from the model in the late life-cycle.

References

[1] DocGen, https://github.com/Open-MBEE/mdk/tree/support/3.x/src/main/dist/manual

[2] ISO/IEC, ISO/IEC 42010:2011, Systems and software engineering - Architecture description

[3] ISO/IEC, ISO/IEC 15288:2008(E), Systems and Software Engineering – System life cycle processes, International Organisation for Standardisation/International Electrotechnical Commission, February 1, 2008

[4] INCOSE “International Council on Systems Engineering.” http://www.incose.org

[5] Delp, C, Lam, D, Fosse, E., Lee, C., Model Based Document and Report Generation for Systems Engineering, IEEE AC, 2013

[6] Jackson, M., Delp C., Bindschadler, M., Sarrel M., Wollaeger, R., Lam, D., Dynamic Gate Product and Artifact Generation from System Models, IEEE AC, 2011

[7] REST, https://en.wikipedia.org/wiki/Representational_state_transfer

[8] https://www.jupyter.org