Generating Reports from Model Data

hello everyone my name is Einstein and I am pleased to welcome you all to one boy and BSC double now go to this topic is generating reports from model data in this webinar you will learn how to master the creation of custom report templates for camera systems model of our days ago is mano a get to magic developer at the reduced and the list has been with new magic since late 2012 while contributing to the development of a model-based systems engineering environment he has aimed a lot of experience in systems and software engineering and girls also provides professional services to world while known plans of home at like abled for nong khiaw and siemens producing custom report templates is one of the strongest areas of across expertise besides professional services he has delivered training courses and workshops on report and place development before girl stands and let me tell you some generic information about veteran please note that night is being recorded and all the people who have registered to the webinar will be provided with a link to the governor's video on YouTube the school happen next week so if you must leave a session keep in mind that you will be able to watch its video also let me remind you by today's presentation and demo will take about 15 minutes and the questions answer section about them if you have questions you don't need to wait for a question answer section to ask them you can use during the entire session and let us glance along later on find your questions in the questions area you see in the current slide due to the limited time some questions may be less an answer in such case answers will be published later at nice page in written form so please welcome and closed doors cos and goodest and ready to start first of all thank you I stopped for a nice introduction and yes I'm now ready to start the presentation this webinar is all about report templates in magic draw platform first I will briefly explain what a template is and demonstrate how to generate actual documents from it then I will show you how to create your own custom report template but in order to complete it we will have to cover basic syntax of the LA City script which is used to develop the templates and finally we will look at the ways of accessing actual model data from magic draw so what is a report template it is a text file that describes what the output document should look like a template contains script which gets replaced with the actual data during the generation of a document and it also contains all the styling headers and footers or static text if any our report generation engine supports templates of various formats including Microsoft Word Excel PowerPoint documents HTML you can then present such documents to businesspeople to a users or colleagues who are not used to working with magic draw application all the data formats that are stored as plain text are also supported that includes XML JSON comma separated values and even your own custom formats such exported data can be imported to other tools that supports it magic draw installation already comes with a number of default report templates which you can use to generate documents it does not matter what is the format of a template the generation process is the same for all of them I will shortly then straight how to manually generate a document out of an existing report template using report wizard or right-click menu but I must mention that there also is a possibility to run a batch or shell script command so the generation itself can be automated for example users users work and commit data to the teamwork cloud during the day and then shell script execution could be scheduled at night to produce a new version of a document and maybe place it as a resource in some your internal network I am using Cameo systems model version 18.5 to demonstrate the generation process however the same report generation and creation concepts that you will see here also applies to magic draw itself and to other magical based products for example Kamel enterprise architecture the currently open project is a sample requirements project which comes with the CSM installation to generate a report select tools from the main menu and then click the report wizard menu item the dialog that you see lists all the templates that are currently available for generating templates are grouped by category and since we are working with requirements project let's expand the requirements category and select requirement report after selecting the desired template let's go to the next wizard step which allows us to select report data values of some report template variables has to be entered by the user so report data is a configuration which holds his values and there's always only a single configuration by default click the button variable to see what can be entered by the user in this I will not change with a fault configuration but I will create a new configuration by clicking new button let's name it report webinar now I will set some values for the variables I will enter my initials as the author of a document company name will be no magic and the purpose of this document will be for demonstration only this has to be done only once and the next time report wizard will remember the values for this report data now we can go to the next step which is selecting scope scope is a part of the model in the currently open project so only elements under the package is selected in this step will be included in the report I will select requirements package and then use plus sign to add it to the scope for the report so everything you see on the right side panel is actual scope of a report in this case it is the contents of the package requirements and the last step in this Vizard is the output options clicking the button on the right allows us to select the location of the generated document so in my case I will place it on my desktop and name it the same as my open project all the options other options here are okay and not that important at the moment so finally I will click generate button to create the output document as you see and the extension is offered to be appended to the filename automatically you can see that it takes a little while to export the diagrams and other data the bigger the scope the more time it could take to generate it and printing diagrams is usually quite a time-consuming task once the generation task is done we can now open our document and review a result as you can see all the values entered in the report wizard like offer company and if I scroll down a little bit the purpose of a document where inserted in the document if I scroll a little bit more I can find all the detailed information about the requirements that were included in the scope so only the requirements in scope can be found here you might also notice that a table of contents is not displayed yet so you have to update it manually so I clicked this field and will press f9 to update the table of contents this cannot be done automatically because complete document has to be generated to know the contents of it and this page the contents page is generated before all the dynamic content below as mentioned previously there is a quicker way to generate a report you can right-click some element in the containment tree and that element will become the scope of the report then navigate to the generate reports submenu and just pick and click the name for the template after clicking my new item only select location dialog appears to select the output file I will reuse the same one and override it you can view the generated document at once but what if a style of a contents of a default template does not suit your needs if it's just a few small adjustments then you might want to edit the existing template to do that let's get back to report wizard dialog let's make sure the correct template is selected in the tree and then just click open button this action opens the template file with a script that defines how dynamic content should be inserted if you make changes here and save the changes then the next document you generate from this template will already be affected you can change fonts or lay out the vote even caring about the script so now I will change the color of the title maybe increase the font size and I can add some spacing and while the title page seems quite straightforward if I scroll down a few pages below then you will see that there is much more mystery going on the bottom line is that creating or even editing the contents of a template is basically a programming task so at least fundamental programming skills are required to be able to edit this template we first have to understand the syntax of the script so that's why I will not spend a few minutes to get you acquainted with the velocity script velocity is Java based template engine which allows incorporating dynamic content the velocity script is a template language which can reference objects defined in Java language since model data is represented by Oracle's Java objects in magic draw so we can use methods of our own Java API velocity is created and developed by Apache and detailed information including the complete user guide can be found online the syntax of the lost script is relatively simple all variables are denoted by a dollar sign followed by an identifier that is the name of the variable name of a variable is case-sensitive VTL is an untyped language so variable can reference Java object of any type but a variable is empty until a value set for it we already saw when generating report that users can set values for some template variables in report wizard dialog like I did with the company name author and purpose another way is to assign the values directly in the script for that purpose set directive is used as of examples in the sly display here named variable is reference to Java string object object which is javis way of representing any text a floating number is assigned to the second variable version and after the third line the value of named variable will be changed to the same floating number 18.5 next very common directive is if statements as in many other languages it allows to do something only when the specified condition is true please pay attention a single end directive is always required to close the block it is mandatory the statement might optionally include a single else directive as well as any number of else if directives and for alternate for branches also it is important to know that all statement that start with a hash sign will be removed from the generated documents so if there's nothing else but script in some line that line will not be present at all to look through each element in collection for each directive is used there also must be an end to complete the block magichd report engine adds another interesting directive for row which is not a part of original velocity script this directive generates a new table row for each element in the collection for Excel spreadsheet reports it is also possible to generate columns when iterating using the for call custom direct before we look into real-life examples of the script I want to mention yet another important directive macro it is similar to a function it is a segment of reusable code when defined once it can be called repeatedly in different places of a template macro command can optionally have any number of input parameters so let's get back to the template which was opened with the intentions of editing now we can recognize that here is a macro defined also but it does not print anything out because all the statements start with hair sign it uses if statement and if that statement if that condition in the statement is true then another macro with this name is called also a new value is assigned to the variable resolved name but which this much of script might seem overwhelming right now so instead of analyzing and editing this template we will create a completely new one simple template just remember use the full template that comes with the installation and there is quite a few is a useful working example since each can be opened and viewed to create a new template we must first decide what the format of the document will be probably the most popular format is Microsoft Word document so I will now create a new empty document which will become the template script file and I will open it for editing we have to add some text to it and also script to make a report dynamic the title will be static text that never changes I will also apply it some styling for the title then we want something dynamic too so let's add author variable which should get replaced with the actual value when generating I will add more script later on but this script is enough to get something generated already make sure you save the changes before that to create report template out of a scripted document click new button in report wizard then the name of a new report can be entered as well as optional description and category fields finally I have to select the script file that I have just created after clicking create button a new entry is visible in the templates tree now let's click a button variable and add new variable we should type in offer exactly as we are using it in the script just without a dollar sign the default value will be unknown so that's it the template is created now we can generate it in the same manner as we did with default once earlier to do that I will create new report data which will contain the value for the author which in this case will be no magic in the next step I will select the whole project as a scope and to do that you have to select the add the route package to the selected objects but actually it does not matter just yet as we are not using scope in the script at all location of the output document has to be provided to I will simply name it output so let's generate the report and after it's done see what is the result as you can see offer variable was replaced with the correct and added content it is now time to pull some model data from magic draw project and include it in the report so how to reach the elements that were selected as the scope in the report wizard a few ways to do that during the report generation and numerous variables are preset with our values one of them is package scope which automatically contains a list of package elements that were explicitly selected as the scope of the report furthermore there is elements variable which contains the same selected packages plus all the own elements of any type recursively so it contains every last element in the scope also for every element type a separate variable is dynamically created and it's predefined containing only elements of that certain type so let's try this thread approach to access the requirement elements from script I will add a page break so our script goes not on the title page so now we learn that I will zoom in a little bit now we learn that requirement variable contains all requirement elements that are in scope in order to generate it we should use for each directive that we already saw so for each our requirement in list of all requirements and don't forget to put an end directive to close a block let's print name of the requirement and let's also add numbering to see that the number gets increased automatically for each entry so let's generate it and see if it works but this time generating I will use a shortcut which is dedicated for recently used reports luckily we can see all the requirement names numbered and print it out but what if we do what if we make an syntax error when typing for example what if we forget the end statement or what if we miss a closing parenthesis at the end it is not easy to script inside word application since it does not provide any highlighting or Auto completion for velocity so we have to be focused and now I will do this mistake intentionally and try to generate this report from magic draw as you can see we are getting an error unfortunately the error description provided by velocity engine can be quite misleading it mentions some lower sign and not the parenthesis that we've missed the line number is absolute so it does not match words line of the current page and can be also misleading I will close the error let's fix the script see if it works now it does work but you might notice that there there are empty lines this is unwanted and unexpected since we haven't added such formatting names should go one after another by looking at the script unwanted empty lines is a common problem these lines appear if a space or tab character is entered after or before the script statement accidentally from the VTL engines perspective and space is a normal output which cannot be ignored so it is included in its own line if there is nothing else there so enable showing off paragraph marks in word and look for trailing or leading spaces even if you have several statements in a row or a comment at the end of a line there should be no spaces in between so I will now enable paragraph marking by clicking this button in the words toolbar and then we can see that there is a space at the end of the for each statement so to fix our issue with that unwanted empty spaces I will remove a space save a template and this should fix our problem and the spaces are gone now what if we want to print other model properties of the requirement to like text or severity this can be done in a similar matter as name using the dot notation this is actually a shorthand notation and Java method get' name is called behind the scenes so this means the same but I recommend using the shorthand notation since it also results most stereotype tag values and derived properties so this way you don't have to care about the implementation details to make things work to print the value of almost any property of a model element it is enough to follow these two simple steps first view the properties in the specification dialog to locate the one that interests you each and every property that is listed under all properties mode is available for retrieval in the report template next convert the name of the property that you see to the Charlaine shorthand notation by removing the spaces and starting with a lowercase letter use this notation after a dot as can be seen in the slide to get the value of that property for the reference element let's use this approach to print more model properties in our report template so I will open specification window of a requirement we were able to print name of the requirement which is an UML property now we will print ID text and maybe also refined by they are already actually they are tagged values you can check that by clicking tags node in the specification so you can see these tags have slot values refined by is also a derived property which means that it is value is recalculated or the magic living relationship changes the model let's put all these properties in our report template I will use a table which has three columns for the properties and two rows the first row is for the heaters so it's just some static text and the script goes in the second row but instead of using for each statement we have to use four row statement to generate a new row in the table for each requirement so I will changes to four row and it ends with an row statement now we can access this variable in other columns of the same line - so here we can type our text to print the text and let's also try using the rules refined by let's test this code and see what we get the output is not completely as expected because the value of refined by property is not text it is actually a list of elements which is empty in most of the cases if I generate it for a smaller scope we might find some refine by with values so here it is so you can tell from the brackets in the output that this is a collection so brackets means a collection a list or an array and this is a list with a single element in it so also we can check in the model that property refined by is actually a list of elements so in the table we would like to print name of each element if there's n to do that we have to use full row directive I'm sorry for each directive and iterate through each element in the refine by property value we are not using four row because if there is multiple there are multiple elements in refined by value we want them all to be printed in the same row of this requirement this should get us the name I will repeat the generation process using keyboard shortcut and now the output looks like we want it now we can see names of refine by elements also some additional properties are available for use in script even if they are not present in the specification window in magic draw the complete table of such additional properties can be found in our documentation this slide includes just a few of them use dot image to print the image of a diagram or we can get element type in a human readable format using human type actually let's add this to our template in front of the name of the referent refined by elements I will also add L dot a human type and if we save and generate this the type of the element which is class is also included in front of a name one of rare situations when printing property with shorthand location rule will not work is if tag property of a stereotype would contain spaces in its name in such case a specific repel per method can be used it's called get stereotype property report variable is quite important and used widely it provides numerous utility methods to access and filter the model data here are just a few examples and again the full list is available in the documentation let's try and use a couple of the utility methods by changing our template so it prints only the requirements that are displayed in a selected single diagram so we already know that diagram variable should contain every diagram element which is in the selected scope so if we if we can assume that there will only be a single diagram in selected report scope we need to get the first element out of this collection to do that we should write get and provide 0 to get the first element but you might have a question how to know it why would this work so the answer is that this would work because diagram is actually referencing Java object of type or realist and the realist in Java has method get' but it might be difficult for you to guess that this is an ArrayList so there is a way to check that so each object in Java has a method yet class this method returns the object type of that object and the class is object itself it has method get' name using the shorthand notation this code can be changed to dot class not name so if we will temporary print this out it should gives us the name of the class of a reference object I will do it right now as you can see Java dot util dot ArrayList is printed so now you can know that this is a Java class you can find online documentation for it and then read all the methods that are available for calling including dot yet so let's get back to our tasks to printing requirements that are displayed in a single select diagram so to get that single select diagram we use this script and now let's set it to a variable called diagram notice that these variables differs only in capital D and lowercase D as I've mentioned before variables are case sensitive so these are two separate variables we got our diagram now we would like to get all the elements that are displayed in that diagram so this in case report is generated for the selected diagram to do that we will use reporter helper so diagram elements which means elements used displayed in the diagram will be report helper and we will use method called get diagram elements we have to provide the diagram as the parameter so again this method for the given diagram will return a collection of elements displayed in the diagram but we only want to print requirements in the table and as you can see magic draw the other type of elements there for example there is a glass there is a relationship so we have somehow to filter those diagram elements by type we can do that using another utility method from report helper so the requirements will be report dot filter element and this method takes two parameters fit first is the list of elements that we want to filter through which is all the diagram elements and the second is an array of human readable types so since it's an array we have to add square brackets and inside we can enter whatever types we want to filter for the types that we want to include so in our case is requirement it's the element type as seen in magic drop if we want or need we can place a comma and type in more types for example dependency if we needed dependency relationship but in our case we only need the requirement so now in the table instead of iterating through the predefined the requirement variable which contains all the points in scope in the report template scope we will replace it with requirements which we have just collected ourselves and to make things even more realistic let's also print the image of a diagram above the table this can be done by writing dot image for the diagram we have also haven't used if statement in our report so far so let's say we don't want to print the table at all in case there are no requirements in the selected diagram maybe in that case we want to print some text for example nothing to display so we have to write an if statement for these branches so if and I will leave the condition empty for now so if there are no requirements we want to print this text else so if there are any requirements if the condition evaluates to false we want to print the table and don't forget the end to close the if block now we might want to make the text read for the condition to check if the requirements are empty we could use Javas method again like yet but we will use another helper method from report report is empty this method returns to prove and the collection passed in collection is empty it also returns true if provided reference is null so if there is no value at all and if we provide a string that that means text to this method it will return true in case that text is empty so now I will change with change and save the changes and try to generate a report template to see if it actually works I will generate report for the open diagram and I hope to see all these requirements in the table the diagram is printed and below luckily we are getting the table of the requirements in the diagram so that works quite well please note that if we made some typing error for example we're checking we assigning to the wrong variable so I will miss type here no syntax error will be displayed in magic droven generating the report template with that template will still work but it will produce wrong output so if I generate for the broken report now I am getting red text so again you have to be really careful and focused because programming in Word is really difficult there are also a few other helper variables like report they are also ready to use project contains info about the open project sorter helper helps to sort elements by name ID or other text property date is booked for printing the date and time in any chosen format array provides a way to create a new empty list set or set since there is no way to construct new Java objects in the law state itself there are even more helper variables like file which is able to create additional output files let's try out date helper by printing the current date in the heater of our report template so I will double-click the healer to edit it when will type in Dave helper and use its get method we have to provide the date date for Matt sorry so it will be year month and day of month let's check what output we get and the date is included in the header of each page so that's what we have expected if the API provided by us is not enough you can create your own report tool with Java complex sorting algorithm or advanced string manipulation using regular expressions might not be available in velocity so Kristin Java code can be written in such cases jar file containing the implemented tool class has to be placed in a subdirectory next to report templates files finally the new helper class I'm sorry the new helper has to be imported using import directly before it it can be used in the velocity script so after the development of our template is complete we might want to share it to our colleagues clients or users in the report wizard we can use export button to export template to a file which can then be sent to others and then the given file can be imported using the report Wizards import button on their machine also if the users are working on the same project the template can be attached to the project itself using attach button if I attach this project this to the project it will create a copy and you also can see that there is an element representing this report template so you can commit the to the teamwork server for example and other users will start seeing it in report visit if I delete the touch template in the model it will also be gone from the report desert there is no attached report only the copy which is tort in file so I have only showed you how to create a new ripped report for Microsoft Word so what if Excel or XML base report is needed actually the process is almost identical to the one that we've tried here start with creating a file with the desired extension and then just put script in it let's say we need to export block elements as vocabulary resources using the resource description framework that is RDF format which is based on XML to do that simply create a template file with the RDF extension and then using any text or code editor add script that creates content dynamically the script might look as simple as shown so this script iterates through each block in the selected scope then it prints its name documentation properties also it use some custom imported tool which does not exist in my system and a method of the tool should replace the white spaces from the name of the block to conclude about I would like to say that report template development topic is very broad but the same can be said about the possibilities this process requires some knowledge and practice to master I encourage you to start at our tutorial section and try things for your own and then consult the user guide for the available data retrieval methods please also remember that every existing report template is also a working script example so thank you all for your attention girl girls for presentation and the demonstration it was very interesting and the currently I can see what we have no questions just many fangs for presentation and questions if we will provide the slider and the video to the attendees so I can repeat once more but yes we will provide you all related information in a brief time and right now we can say thanks once again and really hope to see you in upcoming diverse and good wine mean by everybody

Channel: No Magic

Views: 10,951

Rating: 5 out of 5

Keywords: Reports, Report Templates, Velocity Template Langauge, VTL, MagicDraw, Cameo Systems Modeler, Microsoft Word, Microsoft Excel, XML

Id: L2fbUqPzUyo

Length: 50min 53sec (3053 seconds)

Published: Mon May 29 2017