Model Based Document Generation User Manual
Contents
1. Specification of MBDG The MBDG contains a list of specific MBDG properties MALLA rr gt History O The follow Model Based Document Generation User Manual l m E The Follow EE Documentation Hyperlinks Es Bi nf Bj 3 Usage in Diagrams Inner Elements El MBDG Tags Xref A SEWG glossary Model Based Document Gel Constraints a AEE Forward Figure 4 17 Xref value added Step 3 Add lt token gt tag In the paragraph where you have just added the Xref tag value Add a keyword lt token gt in the paragraph text where you want to reference the biblioentry from Step 4 Adding multiple lt token gt tag Multiple references from a paragraph can be done by adding the keyword lt token gt as many times as the number of your referenced values Example if you repeat step 1 2 and you have added multiple Xref values like so SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 31 Team 2011 12 23 a P gt paragraph The following table clarifies which elements can be added and where specifying the native SysML l Se ze He OH _ Specification of MBDG The MBDG contains a list of specific MBDG properties y a aiy i i gt History E The follow Model Based Document Generation User Manual T m a E The Follow H E Documentation Hyperlinks a a at B 3 Usage in Diagrams ge Inner Elements2. Explanations The MagicDraw SysML plugin is implemented using stereotype extensions based on the OMG SysML specification AND it employs the unique Domain Specific Language DSL Customization engine of MagicDraw UML N A IN N OMG SYSML 1 1 specification More Information about OMG SysML MagicDraw UML website No Magic online Eschool las START To start exploring the sample double click here Explanations Figure 4 10 a figure diagram 4 9 1 Adding comment text example A comment text can be added to a figurelmage or figureDiagram by 1 specifying the comment value in the figureDiagram Image documentation And 2 setting the appearance of this comment text to make the comment appear before or after the diagram like the given image below SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 24 Team 2011 12 23 E E Documentation Hyperlinks Usage in Diagrams Multiple Add Example T exampleMulti Model Based Document Ge MED Scale P lt undefined gt Figure 4 11 commentText Use after value set this image shows how the appearance of the comment text can be customized to appear before or after the figurelmage Diagram by setting the Use Text tag values accordingly SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 25 Team 2011 12 23 z z Se a aT e IMM x BY MagicDraw UML 17 0 ModelBasedDocume
3. Diagram StereotypesAndBlocks shows such a table where the selected element types are Block and Stereotype and the columns show name documentation and members CAVEAT if the width of the generic table columns is not adjusted manually the size is not properly set in MagicDraw as of 17 0 SP3 and the generation will fail Therefore the column width has to be adjusted the first time the table is created null a IN ae documentation of the CapacityEquation 2 CapacityContext j figureDiagram Name Documentation The documentation of the CapactiyContext To scale a graphic to fit the available width in printed output use width 100 and scalefit 1 attributes For indented text as in a list the available width is from the current indent to the right margin To keep a graphic for printed output at its natural size unless it is too large to fit the available width in which case shrink it to fit use scalefit 1 width 100 and contentdepth 100 attributes To scale a graphic to fit the available width in printed output use width 100 and scalefit 1 attributes For indented text as in a list the available width is from the current indent to the right margin To keep a graphic for printed output at its natural size unless it is too large to fit the available width in which case shrink it to fit use scalefit 1 width 100 and contentdepth 100 attributes unnamed2 pca
4. The boolean value useQueryText is set to true transmitPressure This is just like the query above but in tabular representation Notice the operation descriptions appearing in the table Operation Description transmitPressure This operation transmits the pressure Table 4 5 WirelessTire PressureMonitor 4 11 3 Properties This is a Query on the properties of the referenced elements shown in tabular representation Package Wheel owner baseClassifier Table 4 6 WirelessTire PressureMonitor Package HSUV Structure owner SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 36 Team 2011 12 23 baseClassifier WheelHubAssembly Table 4 7 FrontWheel This query shows the property query type in tabular format Notice how since two queryTypes have been selected property and owner they both get displayed as rows in a single table operations and receptions in the SUV model are not particularly well documented in this case Table 4 8 ICECommandinterface_if 4 11 4 Documentation When a query of type documentation is used the element name appears in boldface followed by its fully qualified name in parenthesis followed by its documentation if available on a new paragraph This example has the userT ext field set to true The representation field value is ignored WirelessTire PressureMonitor HSUVModel Wheel WirelessTire PressureMonitor This device monitors the pressure of the Tires using
5. lt section gt gt EH Generate PDF lt lt section gt gt E ao Adding a Bibliography lt lt section gt gt BBY Adding a Revision History lt lt section gt create Paragraph create Bibliography create Query 3 So Using Generic Tables lt lt section gt gt create FigureDiagram create Figurelmage create m Using the Edit Panel The background why an Edit Panel is needed and useful when is the action available how to call it Where does it appear by default It be resized closed reopened relocated What level of refresh can be Next Previous 7 Case Sensitive 1 07 PM a 372012 De sli re Figure 4 5 editPanel1 4 4 Adding a part to the book Part can be added under a Book element by selecting SE2 create Part option under MBSE menu see Figure 3 1 DocBook Definitions Part can contain subsections and paragraphs User can specify part name and its components 4 5 Adding a Bibliography A Bibliography specify the referenced documents for a book A bibliography element can be added under a Section element by selecting SE2 createBibliography A dialog will appear where the user SE2 Model Based Document Generation User Manual Challenge Team can specify the bibliography name A Bibliography can contain many biblioentry elements The user can specify the Abbrevation of each biblioentry
6. structure prose and references to various types of system elements also present in the same artifact The modeling tool is MagicDraw and the software is installed as a plug in This documents explains how to use the document generation plugin for MagicDraw The plug in is used to transform a document which is stored in a Sys ML UML model into an XML file conforming with DocBook for further usage Most typically the document will be converted to PDF 1 3 Glossary Definitions and Conventions For a definition of book chapter section part paragraph etc please refer to the documents in Section 2 2 Reference Documents 1 4 Abbreviations and Acronyms MBDG Model Based Document Generation 1 5 How this document was made This document was generated from a SysML model archived in the Teamwork Server RD3 The model is essentially an augmented version of the example model for a Hybrid Sport Utility Vehicle which the MagicDraw manufacturer ships with its product Notice that the SysML model does not need to be archived in a Teamwork Server for this software to work The HSUV model was chosen since it is fairly complete and contains elements which allow to show all features of the MBDG plug in Since in most cases only the rendering is shown in this document and no detailed explanation can be easily given the reader is encouraged to look at the model directly to fully understand what is happening behind the scenes 1 6 C
7. 01 1 Challenge Page 33 Team 2011 12 23 bdd Package Wheel amp Block diagram for the Wheel Package WheelHub4ssembly Applied Stereotype Uniform CaValueProperty k Defining Structure of the hybrid SUV System pr N Previous dA Next Figure 6 17 Figure B 19 Assembly 1 LugBoltJoint 5 Figure 4 20 Defining structure of power subsystem The following subsections provide examples of rendering for various settings of the queries fields which are printed in boldface when sensible SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 34 Team 2011 12 23 Select Element Select search for or create an element a m Search for an element by using list or tree views To find an element type text or wildcard A 4 ei a tri into the Search by name input field Search elements by their qualified names or use A camel case when searching if the appropriate mode is enabled GEA Search by name Type 447 matches Found E Tire Blocks TireBead Block E TireMountingRim Block E wheel Blocks E wheeldssembly Blocks E wheelHub ssembly Block 3 WirelessTire PressureMonitor Blocks by mzampare dsd DE Baddsde 3 esroalz er to navigate the system model and select the elerment to be queried The latter may be a Figure a Require ExternalObject External be HyvbridSuy Systeme Load Cancel Figure 4 21 mbseSelectionExample An ex
8. 28 Team 2011 12 23 The example will show how a biblioentry can be referenced Step 1 Create a paragraph element This can be done by selecting SE2 create Paragraph option under the MSBE menu Step 2 Add Xref values Open the paragraph s specification dialog and click add values for the Xref tag like the image below E paragraph In order to add a chapter B to a book A the following sequence of steps must be followed in the E di A nn Specification of MBDG The MBDG contains a list of specific MBDG properties E B Documentation Hyperlinks gad a Usage in Diagrams Bz Z fS Inner Elements E MBDG Tags Constraints 0 U Er EZ nnna Xref ser can add a reference from within the paragraph The xref can reference elements like Sections Diagrams etc lt lt token gt gt keyword must be put in the paragraph respectively E Figure 4 15 Edit option of Xref Tag SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 29 Team 2011 12 23 After selecting Edit option a new dialog will appear where the user can browse different elements to be referenced in our case we will select a Biblioentry element Select search for or create elements o y Search for an element by using list or tree views To find an Moo am element type text or wildcard into the Search by name a J input field Search elements by their qualified names or use os e Ju E A
9. A u 12 Ay JAST CIONS urraca 13 4d A NOLS On Ihe User interac a a AAA AAA AA 13 4 2 Adding a book to your model ocoococccccoccccccconcnnccconcnnoncnnonncnnnnonnnnnnnnnnnnnonnnnnnncnnnnnnnnnos 15 4 3 Usna the Edi Panel A a 16 4 4 Adding apart tothe DI inle 17 4 5 Adding a BIDIIOGrA DAY a een eae led eine piece eae dle einen ati 17 4 6 Adding a Revision History ccccececcecceceeceeceeeeceeceececeeceececeeceeceeeeseeseeeeseeseeaeeeeseegees 19 4 2 AGING a Chapter toa Dar Or DOOK za ee 19 4 8 SAGGING Dal agains wt are e ee een 20 4 9 Inel cding extemal IMAG CS a ei 21 4 9 1 Adding comment text example zu2u0202s02sen een nnennnnn nennen nennen nennen nennen 23 4 9 2 Setting Figure Size and Width 2222 mar A 25 4 10 Adding internal references u240440202002nenne nn nenne nnen nennen nnnnnennnnnnennen nenne nnnennenn 26 4 10 1 Adding lt token gt references example 2z22u220240240en ano nn en ann nnennnnn nennen nennen 27 411 Adding QUESTE S miiia nce tad ee een 31 Ad Requlremenis rien 35 41122 Operans see ee ee ee ee 35 Ato ROD SIUC Sn AAA Ria tates 35 4 1 kA DOCUMENT as nine ee die deren cia Lab 36 ENS ROS a lb a 36 AMO CONS naciona 36 AN POW POC ISS ang 38 4 118 Part PrOBEHIES oriei a a ie is 39 A TL9 Malle Propellessens area 39 AO Example USA 6 ne eek 40 4 12 Using Generie Tables si aa a A ei 43 AN en elle 45 ATA Adding a Table Parag
10. Package bookComponent SE add Preface paragraph Chapter Comment blockElements SE add Paragraph paragraph Section Comment blockElements SE add Paragraph section Chapter Package Sections SE add Section Revision History Book Package revhistory SE add Revision History Revision Entry revhistory Class revision SE create Revision Entry Biblio Entry bibliography Class biblioEntry SE create Biblio Entry Table 4 1 4 1 A note on the user interface All the functionality supplied by the MBSE plugin is implemented in Actions which are triggered from the context menu from MagicDraw containment tree Actions are available depending upon the type and permissions read write or read only on the currently selected element For example the action to create a Book element will not be available when a chapter is selected whereas the vice versa creating a chapter is true if the book is currently editable SE2 createChapter SE2 create Preface SE2 Generate DocBook Figure 4 1 contextMenu Each element when created can be customized in its specification dialog The specification dialog will have a sub menu called MBDG under this menu the user can edit different tags of those element for e g for Book user can specify its name components and authors etc Also MBDG sub menu will appear in the quick properties menu under the containment tree SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 14 Tea
11. a wireless connection Care should be taken that in general the documentation of a Model Element will include the comments attached to such element Some of these relationships may not always be displayed in diagrams and be therefore difficult to detect 4 11 5 Ports This is a query on the ports of a selected block lf the representation type is not specified it defaults to table epc ice trsm eepc etrsm eice Here is a variant in tabular format other fields unchanged This is the documentation for the epc port ice ICEDatalnterfacelffis is the documentation for the ice port eepc IFS EPC This is the documentatioon for the eepc port etrsm IFS TRSM This is the documentation for the etrsm port eice IFS_ICE This is the documentation for the This is the documentation for the eice port IFS_ICE Table 4 11 PowerControlUnit Ports This is the documentation for the trsm port 4 11 6 Constraints A query on the constraints like this one in tabular format show the Constraint Parameters of a given constraint Block their type and description SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 37 Team 2011 12 23 AccelerationEquet oi F M P t mThis is the This describes the Acceleration documentation of the constraint Equation property for acceleration pwr PowerEquation tp hp wheel power drag This is documenting the friction PowerEquation ConstrainBlock VelocityEquationv ae mph v
12. n detla v v n oie PositionEquationx n 1 A n delta x This is a comment anchored to gt ee t the Position Equation which will appear in the documentation of the Constraint Block Table 4 12 StraightLineVehicle Dynamics Constraint Properties bdd Package HSU Analysis Defining Straight Line Vehicle Dynamics Mathematical Constraints N N Previous gt a Next gt constraint Figure B 30 Figure B 32 StraightLineVehicle Dynamics En parameters comment This is a commert anchored to the whlpwer Horsepwyriunit hp pos vel acc constraints constraints constraints constraints PowerEquation PositionEquation VelocityEquation AccelerationEquation itp whlpwr Cdv Cttwtr ix n 1 x n v mph 5230 3600 delta t iv n 1 J n a g 32 3600 5280 detta t a 550 32 tp hp delta t ty AAA A parameters parae parameters parameters whipwr Horsepwriunit hp v Yekunit mph delta t Time unit sec tp Horsepwr unt hp i Real x Dist unit ft a Accel unit g tw Weight unit Ib Cd Real delta t Timejunit sec vi Welfunit mph a Accel unit g Cf Real delta t Time unit sec tw Weightiunit lb tp Horsepyer unit hp v Vel unit mph Figure 4 23 This is not used The queried Constraint Block appears in the Diagram in Figure Figure 4 23 This is not used A query of the same type and to the same Constraint Block but in paragraph format l
13. properties constraints ports receptions operations etc to be displayed in the table SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 42 Team 2011 12 23 Specification of MBDG The MBDG contains a list of specific MBDG properties History JE q Model Based Document Generation User Manual Instructions e MBDG H E Documentation Hyperlinks Usage in Diagrams P 2 E EHE Element Representaton Show Queried Element Documentpti Property Use Query Text Show Types Documentation Show Properties Documentation Show Qualified Name Xref Type the type attribute determines which nodes of the queried model element are rendered If the type is equal property the selected properties in the property attribute of the query are rendered Type here to filter properties Forward al f e Figure 4 26 queryDialog3 This image shows the Type tag value that can be specified by the user to query different type of information Additional information regarding the documentation of elements types or properties can be chosen to display as a new column in the
14. table This can be done by editing the tag values shown in the following image SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 43 Team 2011 12 23 Specification of MBDG The MBDG contains a list of specific MBDG properties History E q Model Based Document Generation User Manual Instructions e a E5 q E E Documentation Hyperlinks Usage in Diagrams Inner Elements Tags Type documentation Constraints Element E Environment HS5U YModel Representation Show Queried Element Documentation Property Use Query Text A lt undefined gt Show Types Documentation A undefined gt Show Properties Documentation Show Qualified Name ae Undefined gt Forward Figure 4 27 queryDialog4 4 12 Using Generic Tables MagicDraw offers the possibility to create generic tables which contain any kind of information of model element e g documentation its members its operations etc The generic tables can be referenced in a document and are converted into native Docbook tables A tableDiagram element needs to be created in the model which references the generic table The tableDiagram can have a caption text by default the name of the generic table is taken SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 44 Team 2011 12 23 Table 4 20
15. the buttons to create new elements For example adding a Paragraph to a Section would entail e creating a Comment element e Stereotyping it as paragraph e adding the Comment element to the tag blockElements of the Section As already mentioned this tedious work can be automated using the Actions from the user interface Paragraphs can be edited in plain text or using the HTML editor of MagicDraw The HTML editor provides more text formatting capabilities like e Bold text e Italic Text e Underlined It also allows nested ordered lists in a paragraph 1 Item 1 2 Item 2 3 Item 3 Or even nested bullets and ordered lists e bi e b1 1 e b1 2 e b2 e b2 1 e b2 1 1 item 1 SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 21 Team 2011 12 23 a item 1 1 b item 1 2 2 item 2 Simple tables can be created with the HTML editor within a paragraph However they cannot be referenced with a x reference For x reference a separate table stereotype element must be used as described in Section 4 13 Adding Tables element 1 1 element 1 2 element 2 1 element 2 2 element 3 1 element 3 2 e itemi 1 item 1 e item2 2 item 2 Table 4 2 4 9 Including external images The addition of external images involves multiple steps A Class or Block element needs to be created An external image may be then assigned to it simply by dragging and dropping it from the desktop or f
16. to difficulties in figuring out which their respective ordering in the final document will be This problem is addressed in the Section 4 3 Using the Edit Panel where a pseudo WYSIWYG display is presented SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 12 Team 2011 12 23 3 5 Model organization e The document should be a MagicDraw project or module e Create per document a single module e Use the modules describing you system you need for the documentation e Do NOT make a document part of your system module e The document module shall depend on the system module but not the other way round SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 13 Team 2011 12 23 Chapter 4 Instructions The following table clarifies which elements can be added and where specifying the native SysML elements plus the stereotypes and the tagged values which need to be modified The Addendum is the type of docbook element which needs to be added the Container Stereotype represents the stereotype which should be applied to the container for an addendum of that type to be added In turn the addendum is nothing but a native UML element of type Addendum Type The Container Stereotype has a Tag where the Addendum is added to by means of the Action specified in the last column Addendum Container Addendum Type Tag Action Stereotype chapter Book Package bookComponent SE add Chapter preface Book
17. under the bibliography by editing the Abbrev Prefix tag under MBDG sub menu in the specification dialog In the following image AD is set as the abbreviation Specification of MBDG The MBDG contains a list of specific MBDG E El Documentation Hyperlinks i E Usage in Diagrams E Template Parameters E E Inner Elements Relations Tags Constraints MEDG El MBDG Abbrev Prefix Biblio Entry o SEWG glossary Model Based Document Ge A Biblioentry can be added to a Bibliography by selecting SE2 create Biblio entry option The following Forward Figure 4 6 bibliographyDialog dialog will appear where the user can specify a biblioentry details SE2 UM 01 1 Page 18 2011 12 23 PRA aN E bibliography AD SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 19 Team 2011 12 23 Enter Biblioentry Name Enter Biblioentry Title Enter Issue Number Enter Product Number Enter Publication Date Figure 4 7 biblioentryDialog 4 6 Adding a Revision History A Revision History is a list of the existing revisions for a book A Revision History element can be added under a Book element by selecting SE2 createRevisionHistory A Revision History can contain many Revision elements There is only one Revision History per book A Revision can be added to a Revision History by selecting SE2 create Revision En
18. MBDG Tags ME O SEWG glossary Model Based Document Get re Constraints A DocBook 5 The Definitive Guide Model Bas Name Description Back Forward Help ir __ u Figure 4 18 Multiple Xref Values two biblioentries to be refrenced We have added two biblioentry references Now we must add the keyword lt token gt 2 times in the paragraph text For e g This is a reference lt token gt this is the 1st reference this is also a reference lt token gt this is the second reference In this way the user will be able to create internal references which can be done not only with a biblioentry but also a section chapter figures etc 4 11 Adding Queries A query is a mechanism to extract information from several types of system model elements and render it in document s prose SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 32 Team 2011 12 23 Support exists for different typs of queries operations ports constraints and visualization styles table or paragraph as shown in diagram Figure 3 1 DocBook Definitions where the characteristics of queries are displayed in more detail The following fields must be specified when adding a query element the system model element whose characteristics the query will report upon type the query type can take up the values operations ports documentation constraints properties useQueryText a boolean specifying whether the tex
19. QueryTypeKind documentation element NamedElement 1 ordered representation QueryResutRepresentationKind 1 table showQueriedElementDocumentation Boolean true contentdepth Integer 100 T to the last parent element e g book property Property Typekind 0 Ps useQueryText Boolean true stereotype stereotype This also generates orphaned proxies when modularizing showTypesDocumentation Boolean 1 true tableP h tableDi showPropertiesDocumentation Boolean true ableraragrap abletiagram showQualifiedName Boolean false Comment Class showDefaultValue Boolean 19 98 xref xreference 0 J ordered ble DiagramTable 0 1 stereotype xreference stereotypes stereotypes Element figureDiagram figurelmage Comment Comment diagram Diagram imageContainer Class sa useText usageTextKind useText usageTextKind enumeration ResultRepresentationKind stereotypes query Comment type QueryTypeKind documentation element NamedElement 1 iordered representation QueryResultRepresentationKind 1 table showQueriedElementDocumentation Boolean true property PropertyTypekind 0 useQueryText Boolean true showTypesDocumentation Boolean 1 true showPropertiesDocumentation Boolean true showQualifiedName Boolean false showDefaultYalue Boolean Figure 3 1 DocBook Definitions The solution to the describe
20. SE2 Challenge Team INCOSE MBSE Initiative Model Based Document Generation User Manual SE2 UM 01 ISSUE 1 2011 12 23 Owner Michele Zamparelli Manager Michele Zamparelli Project Manager Robert Karban Name Date Signature SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 2 Team 2011 12 23 SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 3 Team 2011 12 23 Authors Change Record Section Reason Initiation Documents Remarks Paragraph affected 2012 08 21 al tmital Revision SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 4 Team 2011 12 23 Table of Contents A a acto ctes cme Aac dan a aa A kac odes a a 6 AECI tas 6 1 2 PUMO SE lor tacna 6 13 Glossary DETIMLONS and Conventons ae A sees 6 1 4 Abbreviations and Act nyms A ns 6 1 5 FIOW this document was Made a 6 1 6 GODYHONL seen esse e is ea od ES AO 6 2 Related Document 8 2 1 ADPlIG able DOCUMENTS nee ee en bata a EE 8 2 2 Reference Doclmenis hfe AA teat S 8 OH OVEIVICW seh halen a a ie cee ee oe te ieee ee ae ee tel ee ie eee nee ted he ole 9 a ms Oe 110121 0 Seem tee me tatty a Sena eary eee oe Serene a ena eee Miner yeaa Seen ee me eae i eee 9 3 2 1 MDIEMENIANON ee een reset 11 3 3 PAV APTA SS are 11 3 4 A simple Use Case adding a Chapter ococcoccoccncccccocnoconconcnncnncnnconcnncnnnoncnnnoncnnnnnnoncnns 11 8 52 Model organ ZAI OI zen
21. ample of selection can be see in Figure Figure 4 21 mbseSelectionExample SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 35 Team 2011 12 23 4 11 1 Requirements req Package HSU Y Requirements Previous a Next gt Index 3 HSUV Specification Figure B 10 Figure 6 12 requirements requirement gt requirement gt Ergonomics Qualification Capacity requirements requirements requirements requirement gt requirements requirements requirements requirements requirements Emissions Braking Acceleration OffRoadCapability FuelEconomy SafetyTest CargoCapacity FuelCapacity PassengerCapacity Es Establishing HSU Requirements Hierarchy requirement gt Eco Friendiness Y requirements Performance ld R1 2 1 Text The vehicle shall meet Ultra low Emissions vehicle standards Figure 4 22 Irrelevant since not used When a query is made to an element of type Requirement or derived query type is ignored and the requirement ID name and textual content are displayed in the customary tabular or paragraph form Table 4 4 Emissions This is a a query on the same requirement element as above but in paragraph format null null 4 11 2 Operations This is an example of a query where the operations of a Block from the HSUV model are displayed in paragraph form
22. ble is created below Table 4 21 Table Paragraph 1 c5 internal ref to Section 4 10 Adding internal references Table 4 21 Table Paragraph 1 4 15 Changing the ordering of elements The ordering of each docbook elements like chapter section paragraphs or diagrams can be changed by drag and drop action The elements in the Edit Panel tree can be drag and drop to be placed at a SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 46 Team 2011 12 23 new location under the same parent or different parents Note that the movement should be conformed to DocBook profile for e g a paragraph cannot be moved under a bibliography element 4 16 Generating the final Document In order to generate your DocBook document you must select an element of type book in your model there might be more than one in there from the content tree and use the action MBSE gt SE Generate DocBook The final artifact of the generation process is a standard PDF file produced by means of XSL transformation from a generated XML file These two steps are available as separate actions from the user interface with the Actions Generate PDF Generate XML respectively A third step Generate XML to PDF is available to carry out the XSLT step only The specific XSLT to be used can be selected from MagicDraw from the menu Options then Environment and then selecting the MBSE group which looks like in Figure 4 28 x
23. d appear in the list in the MBSE submenu The book stereotype in the DocBook profile has a variety of tags which get rendered primarily on the front page of the resulting PDF document These are e Document Number self explanatory e Issue Date the issue date for the document Issue a string containing the number of the issue for this document book e owner the document owner rendered on the front page SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 16 Team 2011 12 23 e Work Package Manager WPManager a reference to an element stereotyped by lt lt Author gt gt which represents the Work Package Manager releaser this is rendered with the corresponding field after Owner and Work Package Manager In the ELT xsl template it is rendered to Head of Project Office in the SE2 xsl template it is rendered to Releaser e Authors the complete list of authors rendered on the second page These tag contains references to elements stereotyped by lt lt Author gt gt publisher this string is used by the rendering for the header and footer for any page but the first one in this model it is set to SE2 Challenge Team e Programme a string which appears on the front page above the title of the document in this model it is set to INCOSE MBSE Initiative Notice that the title of the document is the name of the element of type lt lt book gt gt The following diagram shows the dialog that wi
24. d situation consists in creating a model of the document possibly though not necessarily in the same artefact mdzip file where the system model is stored Existing system model elements have then unique identifiers A subset of the DocBook ontology is mapped to model elements using a dedicated SysML profile Figure 3 1 DocBook Definitions shows a class diagram of such a profile where the stereotypes correspond to those elements which normally appear in a DocBook conform XML document Stereotypes were created for a minimal subset of DocBook elements SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 11 Team 2011 12 23 3 2 Implementation Once the DocBook standard maintained by OASIS http www oasis open org home index php is chosen as a basis for development the functionality for code generation is implemented by means of a software plug in to the modeling tool using the tool s own customization facilities open API In addition a SysML profile for DocBook was created which is available for usage at ESO s Teamwork Server The suggested architecture is largely tool independent the software presented here is a specialization for the MagicDraw case Stereotype tags are used to reference to system element models text is entered in comments which can be visualized in diagrams and references to model element or diagrams can be selected using the tool navigation facilities 3 3 Advantages 1 c
25. ding query type This is one such example in tabular form where all documentation types have been turned on mixture Real in Documentation for the mixture A Real value type represents Flow Property the mathematical concept of a real number A Real value type may be used to type SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 39 Team 2011 12 23 values that hold continuous quantities without committing a specific representation such as a floating point data type with restrictions on precision and scale A Real value type represents the mathematical concept of a real number A Real value type may be used to type values that hold continuous quantities without committing a specific representation such as a floating point data type with restrictions on precision and scale Table 4 17 FS_ICE Flow Properties 4 11 8 Part Properties Part type Panbo iypeDos oo loe intemaiCombustonengine emotional ElectrioMotorGeperator acocialatigra Accelerator Of o ep BatenPack Cid This is the documentation of the unit which controls the power at Bien trem Transmission masw fa o CAN ECT 2 ETE ooo foe o e foe o o foe o IS CIC Table 4 18 PowerSubsystem Part Properties 4 11 9 Value Properties Type Property Doc Type Doc temperature pressure SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 40 Team 2011 12 23 fuelPressure A Real val
26. e Page 45 Team 2011 12 23 base Element UML Standard Profile UML2 Metamodel Classes Kernel Element 5 tableDiagram diagramTable UML Standard Profile MagicDraw Profile Diagram Table 0 1 base_ Class UML Standard Profile UML2 Metamodel Classes Kernel Class captionText String 0 1 base Element UML Standard Profile UML2 Metamodel Classes Kernel Element base Element UML Standard Profile UML2 Metamodel Classes Kernel Element base Element UML Standard Profile UML2 Metamodel Classes Kernel Element base Element UML Standard Profile UML2 Metamodel Classes Kernel Element Table 4 20 Diagram StereotypesAndBlocks 4 13 Adding Tables TBD 4 14 Adding a Table Paragraph A table paragraph can be created through invocation of SE2 create Table Paragraph command under Section or Chapter elements etc The aim of creating a table paragraph is to allow user to reference the table through a query mechanism or in normal paragraphs see Section 4 10 Adding internal references as well as adding a caption to the table which would not be possible through normal html tables Invoking the SE2 create Table Paragraph command user will be asked to fill the caption of the table and then the plugin will generate an empty stub html table in which the user can edit it normally During the conversion process generating a pdf this html table is converted into a Docbook conform table An example ta
27. e in the paragraph will need to refer to the desired elements SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 27 Team 2011 12 23 The following image shows the Xref tag under MBDG sub menu in the specification dialog of a paragraph User can edit the value of Xref tag to reference as many elements as possible user must note that the element to be added must be labeled matches in the dialog For e g if the Xref tag has 5 xref values meaning the user has referenced 5 elements then in the paragraph text the user must add the keyword lt token gt 5 times in the same order as when the elements were referenced This way 5 references will be created in that paragraph when the user generates the DocBook j n A ee i P paragraph All the functionality supplied by the MBSE plugin is implemented in Actions which are triggered Lim Specification of MBDG The MBDG contains a list of specific MBDG properties History E All the fu Model Based Document Generation User Manual In un a Sc FJ teschap rnd testbook EE BEE Figure 4 14 xrefDialog 4 10 1 Adding lt token gt references example In this example we will illustrate a step by step guide on how a lt token gt reference can be created inside a paragraph This reference mechanism can be done against tables figures or biblioentry etc SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page
28. ecursive add of elements in a folder can also be done by selecting Add recursively option SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 15 Team 2011 12 23 P Select Author Select search for or create elements Search for an element by using list or tree views To find an element type text or wildcard into the Search by name input field Search elements by their qualified names or use camel case when searching if the appropriate mode is enabled Selected elements 2 MZA Model Based Document Generation User Manga Search by name A E MBSE plugin Info 23 matches oder Customization For DocBook Customization For DocBook 44 2 ma H Ep ESO MBDG Authors Library modelLibrary ESO MBDG Authors Librar oder MD Customization for SysML MD_customization_For_SysML mdzip 2 EE Model Based Document Generation User Manual books i AMC Blocks authors 2 authors by cjesdabo A RKA Blocks authors H E rnd 5 matches oder Templates MBDG Document Templates 20 match EE UML Standard Profile UML_Standard_Profile xml 2 match Load 4 Single Selection Figure 4 3 exampleMulti 4 2 Adding a book to your model In order to add a book to your model simply look for a package where you have write permission e g any package if you re not using teamwork server for configuration control and right click in the context menu The action SE add book shoul
29. ereotypes stereotypes stereot stereot preface chapter section ae j f ay stereotype Package Package Package Package Package division gt prefaceSection section 0 ordered prefacePara paragraph 0 ordered sections section 0 ordered blockelements blockelement 1 ordered blockelements blockelement 0 ordered subsection section 0 ordered bibliography bibliography Package A stereotypes stereotypes stereotypes stereotype bibliography blockelement xreference Package part g Package Element Element biblioEntry biblioEntry 0 Kordered components component 0 ordered Bi Be abbrevPrefix String RD ial a stereotypes paragraph aed aed stereotypes c nt formalexample biblioEnt ommen Element y xref xreference 0 J ordered Class issueNumber String as a pubDate String E comment a ag having associations has drawbacks when modularizing books stereotype stereotypes stereotypes i authors etc query figure table 5 RR m Comment Element Element assuming that the navigation is always downwards and that a component never needs to know which book it is contained in both captionText String 0 1 participants in an association have association ends b Also the backward association end will always contain the reference type
30. final PDF file p MagicDraw UML 17 0 elBasedDoc on mc i b BE gt File Edit View Layout Diagrams Tools Analyze Teamwork Window Help x Ral CE BS Pa El En E BE E Model dDocumentGeneration m v Y AAA w i Edi Panel _ DEHAN SP Software Architect x He Cont Sa Inher 9 Diag lt gt Mode sear Stru Sianacol rn Taldytap SE add Section SE add Revision History SE create Revision Entry EFT piodel based VOCUMEeNC Generation User Manual DOOK gt 11 5 _Tables 6 5 External Images E E Future Enhancements a E Installation chapter E E E MagicDraw Plugin section d ce E3 Oxygen section Package Sections Package fan gt chapter revhistory revision 1 A note on the user interface E E Transformation XSL section EE Instructions chapter 4 o Mm i r 35 Zoom E Documentation Properties Documentation ue x Documentation of lt none gt alli recia cada ao Adding paragraphs lt lt section gt gt E Induding external images lt lt section gt gt Generate Document lt lt section gt gt C Adding internal references lt lt section gt gt ion 4 2 Adding a book to your model Open Specification Dialog Select in containment tree dust EE i ion 4 7 Gene create Section Documentation is not allowed C Adding Queries lt
31. fined gt Show Types Documentation E undefined gt Show Froperties Documentation E undefined gt Show Qualified Name E undefined gt Name Description Type here to filter properties Back Forward Figure 4 24 queryDialog SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 41 Team 2011 12 23 Specification of the query like specifying the output format to be a table or paragraph can be done by editing the Representation tag value like the image below Environment Specification of MBDG The MBDG contains a list of specific MBDG properties MBDG MBDG Type Element Representation Show Queried Element Documentatio Property Use Query Text Show Types Documentation Show Properties Documentation Show Qualified Name documentation E Environgeot a e table paragraph A l O O O O UOU E zunde E lt undefined gt A lt undefined gt E lt undefined gt Xref Forward Figure 4 25 queryDialog2 Representation tag to set the output appearance of the element in table or paragraph format The type of information to be displayed in the table or paragraph can be specified through editing the Type tag values User can choose the element s documentation
32. ll appear when the user click SE add book option Additional information like Programme WP Manager or Authors can be added from the MBDG sub menu in specification dialog of the book Multiline Dialog t zn N Enter Book Name Enter Document Number Enter Issue Enter Issue Number Figure 4 4 bookDialog 4 3 Using the Edit Panel The Edit Panel is an extended feature of the MBSE plugin which provides a user interface elements to preview the document before generating the final PDF file The Edit panel allows operations such as re arranging the order of the elements e g chapters sections paragraphs under the same parent or different parent movements may be performed via drag and drop actions within the limitations provided by the DocBook profile e g a paragraph cannot be moved under a bibliography element The preview shows how the document will look like when it is generated as a PDF and also includes scaled diagrams and tables The Edit Panel for a Book element can be by invoking SE2 Show Edit Panel command in the MBSE plugin for Book Element The generated preview allows the user to navigate through the documents by a document tree sublevel contents chapters sections can be opened hierarchically Th Edit Panel also provides a content pane right side which illustrate each element information in more detail The preview information in the content pane is updated automatically when the user updates the contents in the
33. m 2011 12 23 book Model Based Document Generation User Manual Specification of MBDG The MBDG contains a list of specific MBDG properties i Model Based Document Generatio H E Pocumentation Hyperlinks Usage in Diagrams Template Parameters H E Inner Elements Introduction Model Based Document Sen Related Documents Model Based Docume Overview Model Based Document Genera Instructions Model Based Document Gene Installation Model Based Document Gene Maintenance Model Based Document Gen Known Problems Model Based Document Future Enhancements Model Based Docu 1 E 50 566 999 8X 2011 05 14 E ELT PROGRAMME Publisher ESO E ALT A MZA Model Based Document Generation RKA Model Based Document Generation L Owner A MZA Model Based Document Generatio Wp Manager AQ BBA Model Based Document Generatio Releaser amc Model Based Document Generati Q Type here to filter properties Back Forward Figure 4 2 specificationDialog The following example shows how Authors components can be added to a Book The specification dialog will show matches of possible components to be added e g 23 matches The user can toggle between multiple selection or single selection R
34. model for e g changing a name of a chapter or section or changing the content of a paragraph etc Also delete and undo operation is supported by the content pane Elements like figurelmage figureDiagram and figureTables etc are rendered in the content pane in a scaled form with its description this is just to provide the user with an idea of how the PDF file will look like SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 17 Team 2011 12 23 User can perform a right click action on each element to invoke the MBSE actions context menu for e g right clikcing on a Section will give you an option for creating pargraph as show in the following figure image query etc this applies for other elements as well Double clicking on composite element like Chapter and Sections in the content pane will cause the element to expand collapse The Edit Panel also provides a search functionality with case sensitive option search can be done by typing into the search box and browsing through search results by next and previous button For the first version of the Edit Panel a refresh button is provided and should be used when a user tries to reorder the block elements in the model which does not get reflected in the Edit Panel The Edit panel does not take into account the information generated by the queries for e g some querys that generate a table of paragraph are not shown in the Edit Panel and can only be observed in the
35. n camel case when searching if the appropriate mode is anshlaA pf UNSPECIFIED gt Ae MESE plugin Infos 222 matches EA Customization For DocBook Customization For DocBook mdzip 137 HEA ESO MBDG Document Library modelLibrary ESO MBDG Document Lil EFA MD Customization for SyvsML MO customization For SysML mdzip 3 G E Model Based Document Generation User Manual book T Future Enhancements chapters E Installation chapters matches E Instructions chapter 30 matches EJ Introduction chapters 6 matches Known Problems chapters EJ Maintenance chapters 3 ma ches EJ Overview chapters 5 mafotes PJ Related Documents chapters 6 matches FH Applicable Documents sections maior AD biblio sh Lnafch E Jsews glossary biblioEntry by cjesdabo E Reference s 9 matches H E rnd 45 mafotes H E Templates MBDG Document Templates mdzip 40 masohes H Ep UML Standard Profile UML Standard _Profile xrnl 2 maich E E E Load Multiple Selection Figure 4 16 Dialog for choosing referenced element After selecting the element you will notice that in the paragraph specification dialog Xref tag will have a new referenced value like the image below SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 30 Team 2011 12 23 P gt paragraph The following table clarifies which elements can be added and where specifying the native SysML l al
36. ntGeneration mdzip ModelBasedDocumentGeneration 43 C Users Chakajkla workspace MBSEPlugin test EX File Edit View Layout Diagrams Options Tools Analyze Teamwork Window Help x OE id amp C us dDocumentGeneration m y 5 fail E E EE AM Dama EAE System Engineer zer gt Be C In 29 Di lt gt M 24 se E St Containment 12 9 x pr AU a Crapter coe part ur DUDA ST H E Adding a part to the book section E E7 Adding internal references section H E Adding paragraphs section H E Adding Queries section E EJ Anote on the user interface section 4 Changing the ordering of elements se o B E Generate Document section H E Generate PDF section AE Including external images section COLE m jenen C4 a Diagram figureDiagram iE The additi paragraph In order t paragraph po iE The follow paragraph B EPA Takraductian schantor MT EJ Properties EJ Comment Text goes here Logged in as cjesdabo gt E Figure 4 12 commentText2 Comment text goes here this image illustrates how a comment text can be added by simply editing the documentation text of the figurelmage element 4 9 2 Setting Figure Size and Width A figurelmage or Daigram can be set to scalefit or increase or decrease its dimension This can be done by setting the Scalefit tag or Width tag value For e g t
37. o reduce the image size by 50 percent we can set the Width tag value to 50 like the image below SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 26 Team 2011 12 23 PSA d P figurelmage Comment text goes here this image illustrates how a comment text can be added by simply edit Specification of MBDG The MBDG contains a list of specific MBDG properties y El my He Lpr l fabe a gt History Os Comment te Model Based Document Generation User Manual an L Comment te H E Documentation Hyperlinks azl a See get Usage in Diagrams i Mur Inner Elements Comment text Constraints Image C E j ommentText2 Model Based Document 3 MEDS fa Fl lt undefined gt Use Text Ein Width Na a oe av IN e a Figure 4 13 widthDialog 4 10 Adding internal references Any model element which is stereotyped with xreference can be referred to During generation each document element besides paragraphs is given a unique ID which corresponds to its location in the containment tree In order to add one or more references from within a pragraph the keyword lt token gt hereafter always written wit space characters only necessart in order for it to appear properly in this manual and not to be used otherwise will have to be added as many times as references are desired Correspondingly the xref tagged valu
38. onsistent integration of system model and system documentation 2 direct linking to model elements also diagrams from the document 3 changes of diagram names are automatically reflected in the document 4 using proper definition of the stereotype associations only compatible elements can be selected to compose the document e g a figure references diagrams a chapter references paragraphs 5 the documentation is at the same time navigable in the model and printable 6 documents are modeled in a tool independent way 7 A plugin is needed to generate DocBook XML 3 4 A simple Use Case adding a chapter In order to add a chapter B to a book A the following modifications are needed in the model 1 Create a package B for the chapter give it a name 2 Stereotype package B by lt lt chapter gt gt 3 Modify properties of lt lt book gt gt element A by adding a reference to B e g modifying the tagged value to include B in its list In order to increase the usability of the product all these steps have been incorporated into actions in this case the SE2 Add Chapter action which is available through the plugin Users familiar with modeling tools will probably be acquainted with the issue that the containment tree the tree explorer on the left of the main window normally orders items according to a lexicographic ordering and not in temporal one In other words repeating the above steps for multiple chapters would soon lead
39. ooks like this acc AccelerationEquation pwr PowerEquation vel VelocityEquation pos PositionEquation This is documenting the PowerEquation ConstrainBlock Mame nant CI UC Table 4 13 PowerEquation Constraints This is documenting the PowerEquation ConstrainBlock SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 38 Team 2011 12 23 whipw CTA EN a m Y Table 4 14 PowerEquation Parameters 4 11 7 Flow Properties This query differs from the previous one merely in that the types documentation has been switched off Property Type Dir Property Doc mixture Real in Documentation for the mixture Flow Property Table 4 15 FS_ICE Flow Properties This flowProperties query has the showDocumentation for the properties themselves switched off mixture in A Real value type represents the mathematical concept of a real number A Real value type may be used to type values that hold continuous quantities without committing a specific representation such as a floating point data type with restrictions on precision and scale throttlePosition in A Real value type represents the mathematical concept of a real number A Real value type may be used to type values that hold continuous quantities without committing a specific representation such as a floating point data type with restrictions on precision and scale Table 4 16 FS_ICE Flow Properties Flow Properties may be queried with the correspon
40. opyright The software described in this document is subject to the following copyright statement SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 7 Team 2011 12 23 c INCOSE SE2 Challenge Team for Telescope Modeling 2011 Copyright by ESO HOOD TUM oose GfSE All rights reserved This library is free software you can redistribute it and or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation either version 2 1 of the License or at your option any later version This library is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE See the GNU Lesser General Public License for more details You should have received a copy of the GNU Lesser General Public License along with this library if not write to the Free Software Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 8 Team 2011 12 23 Chapter 2 Related Documents 2 1 Applicable Documents Bibliography AD1 SEWG glossary GEN SPE ESO 50000 0023 Issue 1 2010 2 2 Reference Documents Bibliography RD1 DocBook 5 The Definitive Guide by Norman Walsh for DocBook V5 0 Version 1 1 Updated 20 May 2010 RD2 http www docbook o
41. p Sum Vi V1 Vol V2 Vol V3 Vol vc SysML Blocks Real ad HSUVModel HSUV Structure AutomotiveDomain 1 cap HSUVModel HSUV Analysis CapacityEquation imageContainer UML Standard Profile UML2 Metamodel Classes Kernel Class useText DocBookProfile usageTextKind base Comment UML Standard Profile UML2 Metamodel Classes Kernel Comment base Element UML Standard Profile UML2 Metamodel Classes Kernel Element captionText SysML Blocks String 0 1 scalefit Boolean true width Integer 100 contentdepth Integer 100 base_ Element UML Standard Profile UML2 Metamodel Classes Kernel Element base Element UML Standard Profile UML2 Metamodel Classes Kernel Element base Element UML Standard Profile UML2 Metamodel Classes Kernel Element diagram UML Standard Profile UML2 Metamodel Classes Kernel Diagram useText DocBookProfile usage I extKind base Comment UML Standard Profile UML2 Metamodel Classes Kernel Comment base Element UML Standard Profile UML2 Metamodel Classes Kernel Element captionText SysML Blocks String 0 1 scalefit Boolean true width Integer 100 contentdepth Integer 100 base_Element UML Standard Profile UML2 Metamodel Classes Kernel Element base Element UML Standard Profile UML2 Metamodel Classes Kernel Element SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challeng
42. raph esse ae 45 4 15 Changing the ordering of elements u240242202802n0en neo nn nn nenne nenn nennen nme nn nennen 45 4 16 Generating th final Document 2 A ie ee 46 5 IHSlallall on Steinen een ee een 47 Sde Magic Draw PlUgn asien 47 9 2 lrans ornal on XS Lernen Reue 47 8 Maltenalica ee ES AA AA ATA sie 48 6A Extension POCO OU reed 48 6 2 Fault identification proceda ener eae cad at eat a eet ete 48 6 3 Diagnostic tools and procedures cccececceeceeseeeceeceee eee eceeaeeeeseeeeeeeeeeeeeaeeeeaeeaeeeesenaes 48 Te KNOWN wed O16 19 0 Lo tod RC 49 SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 5 Team 2011 12 23 8 Future Enhancements SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 6 Team 2011 12 23 Chapter 1 Introduction 1 1 Scope This document is the user manual for a software plug in to the MagicDraw UML SysML modelling tool It also briefly addresses the Model Based Document Generation technique in general and the rationale for such a plug in This document assumes some familiarity with generic UML concepts most notably stereotypes 1 2 Purpose This document explains how to install and use a software add on to the MagicDraw UML SysML modeling tool which allows users to extract a printable formatted document from a properly edited model The parts of the model from which the document is extracted shall in general contain
43. rg tdg5 en html docbook html 5 RD3 ESO SDD Teamwork Server installation for MagicDraw RD4 Magic Draw User Manual 17 0 SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 9 Team 2011 12 23 Chapter 3 Overview In current systems engineering developments printed documentation is culturally the primary artifact for information interchange including contractual purposes Recently though system models have shown their usefulness for several system engineering activities and engineers have started maintaining descriptive models of systems using SysML gradually enhancing them with details and enriching them with different points of views and perspectives Such models live therefore a separate autonomous life with respect to printed documentation and authors often find themselves having to copy amp paste diagrams or other information into documents In other words two sources of information Model and Document have to be maintained and get out of sync very easily Document generation engines velocity template have typically hard coded references to model elements and diagrams whereas the solution suggested here makes relocation renaming changes and even deletions in the model transparent to the final document artefact 3 1 Concepts A DocBook book is essentially a set of containers containing other containers or terminal elements which can be primarily textual paragraphs or querie
44. rom a web browser or using the selector from the specification panel In both cases the image gets added to the image property of the Class In order then for the external picture to appear in the final outcome a figurelmage elements needs to be created in the chapter or section using the available Ul commands for section The SE2 create Figure Image first asks for a figure caption and then pops up a selector for the Class itself The figure caption is used for the title The figurelmage element is rendered in XML and PDF with the image it refers to It is recommended to put all external images in a dedicated package SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 22 Team 2011 12 23 Example of a Hybrid SUV 12 Volt battery Engine Control Module Power Electronics Battery Pack Regenerative Braking Electric Motor Generator Figure 4 9 HSUV img SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 23 Team 2011 12 23 e Hybrid Sport Utility Vehicle sample project for the MEM SysML plugin of MagicDraw UML MEA Index Index with explanations Explanations This sample problem for the MagicDraw UML SysML plugin is extracted from the OMG SysML 1 1 specification case study which describes the development of a Hybrid gas electric powered Sport Utility vehicle SUY Some diagrams have also been added in order to provide further explanations and modeling tips
45. s to system elements see Section 4 11 Adding Queries The ordering obviously matters for the final artifact and is obtained from the ordering of the tags in the module SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 10 Team 2011 12 23 package DocBookProfile E DocBook_Definition DocBook_Definition stereotype docbookdocument Package Creation date 4 6 10 11 11 AM O N Modification date 4 13 12 12 29 PM stereotypes stereotypes set article Package Package book book 2 ordered sections section 0 ordered stereotype stereotypes revhistory stereotype stereotype book gt al ig Er Package Pack author xreference Package Element Element divisions division 0 J ordered wert nn bookComponent component 0 ordered pec as issue String documentNumber String issueDate String stereotype releaser author 1 component programme String 1 E ELT PROGRAMME NamedElement publisher String authors author 1 owner author 1 A wp Manager author 1 revhistory revhistory 1 revisionEntry revisionEntry 0 ordered stereotypes revisionEntry Class author author 1 date String reynumber String revremark String revdescription String organization String stereotypes st
46. sform by adding different logo and different rendering of the book information specific to ESO EELT project Furthermore you select if a Draft Watermark is added SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 48 Team 2011 12 23 Chapter 6 Maintenance 6 1 Extension Procedure After initial release changes to this plug in will have to be coordinated by the SE2 Challenge team members 6 2 Fault identification procedure Not applicable 6 3 Diagnostic tools and procedures SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 49 Team 2011 12 23 Chapter 7 Known Problems e DO NOT copy paste from word into HTML hidden formatting instructions are copied as well cut amp paste into ASCII FIRST and then turn on HTML e Very rarely the edit panel displays the document twice SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 50 Team 2011 12 23 Chapter 8 Future Enhancements e Add a shortcut key for the generation e Direct editing of paragraphs in preview panel e Drag n drop of diagrams directly into the preview panel e More sophisticated queries The file chooser for book generation should only display XML files
47. sltSelector A file chooser permits the selection of the appropriate XSLT file The currently shipped XSL transformations are briefly outlined in Section 5 2 Transformation XSL If the model which you re using is coming from the Teamwork Server a file chooser dialog will appear Once the file has been chosen the generation will start no progress bar is available and the plug in will notify you of the successful completion with an acknowledgment pop up The file chooser remembers the selected directory across multiple generations Notice that the chosen directory will be populated with all the images which are required to produce the XML and PDF files The presence of many diagrams and external images may contribute significantly to the generation time A RRA Pdf Style sheet E ad Pdf Draft Mode W true Figure 4 28 xsitSelector SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 47 Team 2011 12 23 Chapter 5 Installation 5 1 MagicDraw Plugin The plugin can be downloaded from SourceForge at http sourceforge net projects mbse4md Please consult the README file for complete installation instructions 5 2 Transformation XSL In MagicDraw s Options gt Environment gt MBSE you select the appropriate transformation file e ESOTransform xsl e SE2Transform xsl refines ESOTransform by adding different logo and different rendering of the book information e ELTTransform xsl refines ESOTran
48. t of the query entered as a body of the corresponding Comment element shall be used in line in the document representation this may be either tabular or paragraph the meaning is self explanatory property this can take up the values owner baseClassifier realizedinterface classifierBehavior This is only used when the type field is set to properties Table 4 3 If the named referenced element is a requirement it is handled as such and the value of query type is entirely ignored As specified in Figure 3 1 DocBook Definitions queries are a special type of paragraph and may be added in all places where a paragraph is allowed and may be intermixed with paragraphs with no restrictions Additional query types like listing all elements represented in a diagram are possible but not implemented at this stage When queries are created using the Actions from the context menu a selector pops up to allow the user to navigate the system model and select the element to be queried The latter may be a Figure a Requirement or a Block The other fields of a query must be instead entered using the specification dialog for the query itself The elements used in the following examples are the Block WirelessTire Pressure Monitor and PowerControl Unit from the HSUV Model used as an example The following two Figures show two diagrams in which the elements appear respectively SE2 Model Based Document Generation User Manual SE2 UM
49. try option The following dialog will appear where the user can specify the Revision details Enter Revision Info Enter Rev Date 2012 02 22 Enter Rev Number 1 Enter Rey Remarks Enter Rev Description Cancel Figure 4 8 revisionentryDialog By clicking on the Select Author button a pop up window will be opened to chose existing elements in the model which are stereotypes with author The name of the selected author will then appear on the left field The issue number for the entire book is taken as a default for the Revision Number field Revision date remarks and description may be entered as needed the latter being used in the rendering to PDF to list the sections chapters which have been modified in this revision 4 7 Adding a chapter to a part or book A Chapter is the basic element of a Book It can contain queries figures diagram or image paragraph and subsections Chapter can be added by selecting SE2 createChapter option under MBSE menu SE2 Model Based Document Generation User Manual SE2 UM 01 1 Challenge Page 20 Team 2011 12 23 4 8 Adding paragraphs Paragraphs are the primary docbook element for holding prose text Paragraphs may be added using the SE2 create Paragraph action from the Context Menu Or as for any other DocBook element may be added editing the specification of the corresponding containing element by opening its specification searching for the blockElements tag and using
50. ue type represents the mathematical concept of a real number A Real value type may be used to type values that hold continuous quantities without committing a specific representation such as a floating point data type with restrictions on precision and scale Table 4 19 Fuel Value Properties 4 11 10 Example Usage A query can be added by selecting SE2 create Query option Query can only be added under a section and chapter When the add query option is selected the user will be asked to select the element to be queried Later on changes to specification of a query can be done by changing the values of query tags in MBDG sub menu in the specification dialog Specification of query properties Specify properties of the selected query in the properties specification table Choose the Expert or All options from the Properties drop down list to see more properties H E Documentation Hyperlinks BS Be Properties Expert gt Customize E Usage in Diagrams Inner Elements E Owner Fy Example Usage Model Based Document Generatio 2 Constraints Applied Stereotype gt query Comment DocBookProFile 2 Element Annotated Element Use text Body 2 Format Image re To Do Documentation El MBDG Element Le FuncionalWMewpont HSU videdel Hay ems Property Representation Type documentation Use Query Text Fl lt undefined gt Xref Show Queried Element Documentation E unde
Download Pdf Manuals
Related Search