- Step 1: Create the virtual document with a script
- Step 2: Generate the document from the virtual document
Document generation is important in most organisations that work with Enterprise Architect. Storing information in the model is good, but most stakeholders still require documents.
Documents are using as a tool for validation, as a work order, or just to give you an overview of a specific set of thing in the model. The main advantages of a document versus a model is that it has a limited scope and a linear order. You can read a document from start to finish, whereas you cannot do that with a model. Documents are, and will always be an important tool in developing applications.
Enterprise Architect comes with a sophisticated document generator that has seen great improvements in the last versions (v10, v11, v12). You also get a standard set of document templates that will quickly generate a document for a part of your model.
The problems arise however the moment you try to do something a bit more sophisticated with the document templates. Get information from different packages, use different templates for the same (set of) elements, etc… You will quickly realize that the approach of having one large template that generates the whole document is not useful for real-world document requirements.
Luckily EA has an alternative to the single template approach: Virtual Documents
Free Download
I’ve put together an example model and an MDG to demonstrate this approach. The MDG contains all scripts, templates and SQL Searches to generate a decent Use Case Document.
After you open the Hotellio.eap file, right click on the Reservations use case diagram and choose Create Use Case Document
Then select the package to store the virtual document in and fill in the version.
Finally select the «master document» package and press F8 so start the document generation. Make sure to select the correct cover page and style sheet
Virtual Documents
Virtual Documents are used to define the contents of a document as a set of individual sections, each with its own source and template.
There are two types of elements that are used for virtual documents
- Master Document
Represents the document to be printed. You can give it some parameters that can be used in the document itself such as title, Version, Status, etc… - Model Document
Represents a section in your document. The model document gets an RTFTemplate, and you have to define a source for this section. The source tell us which element(s) from the model should be used in this section. There are two ways to define the source. You can either drag one or more packages onto it, or you can fill in the Model Search and Search Term.
Master Documents get stored in the model as stereotyped packages and they contain stereotypes classes to represent the Model Documents
In the project browser this looks like this
.
The Master Documents get the stereotype «master document» They contain tagged values to store things like ReportAlias, ReportTitle. Event though you can assign an RTF template to the master document this seems to be pointless since it gets ignored when printing a document.
Model Documents get the stereotype «model document». The links to the packages that serve as the source for a model document are created by dragging the package from the project browser onto the model document. This creates an attribute that maintains the link to the package.
Tagged values are used to indicate the template to use, the model search to use, and the search value to use on that search.
This mechanism of model documents allows you to very precisely control what will be printed in the document.
Templates
RTF templates are stored in the Resources section of your model. In order to see and manage them enable the resources view using View|Resources
Templates for document that have a package as source can start from the package tag and access all element, diagram etc.. in that package.
If your source is an SQL search that returns elements your template content can be placed in the element section
SQL Search
The SQL search I use to select a single element based on its GUID this following:
|
1
2
3
4
5
6
7
8
9
|
select c.ea_guid AS CLASSGUID,c.object_type AS CLASSTYPE,c.name AS Name, c.stereotype AS Stereotype,package.name AS PackageName ,package_p1.name AS PackageLevel1,package_p2.name AS PackageLevel2,package_p3.name AS PackageLevel3 from ((((t_object c inner join t_package package on c.package_id = package.package_id) left join t_package package_p1 on package_p1.package_id = package.parent_id) left join t_package package_p2 on package_p2.package_id = package_p1.parent_id) left join t_package package_p3 on package_p3.package_id = package_p2.parent_id) wherec.ea_guid like '<Search Term>' |
Printing
When you select the Master Document you can open up the document generation dialog by pressing F8
Here you can set the cover page, table of contents, and the style sheet to use.
Side note: Invest in the style sheet. It will save you time and frustration afterwards. It is difficult, and awkward to set styles using the RTF editor, but if you do it once in the stylesheet you don’t have to to it over and over again in each template. Also make sure to create your own “normal” style and call it “my normal” or something like that. Use this instead of the regular “normal”. There seems to be some weird behavior associated by the “normal” style, so I learned it’s best not to use it at all.
Then press generate, and the document generator will create one big document containing
- The cover page
- The table of contents page
- All model documents in the order they appear in the project browser.
If you are not happy with the content of the document, or the order of the model documents then you can change them in EA and re-print the document.
One of the advantages is that the content of the document is stored in EA. So after a revision of the model you can print exactly the same content again and compare it with the previous version.
Automatically generate virtual documents
Using virtual documents like that is all nice and good, but it still requires quite a lot of work to assemble the virtual document itself. For a somewhat realistic document you easily end up with tens of model documents, all pointing to different element or packages, and different template.
And you have to repeat that process for all the different documents you want to generate.
Doing the same thing over and over again is exactly what computers are build for. Instead of having to assemble the virtual document manually we will write a little script to do it for us.
The first thing well need to do is to make the Master Document package. This VBScript function does that for us.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
function addMasterDocument(packageGUID, documentName,documentVersion,documentAlias) dim ownerPackage as EA.Package set ownerPackage = Repository.GetPackageByGuid(packageGUID) dim masterDocumentPackage as EA.Package set masterDocumentPackage = ownerPackage.Packages.AddNew(documentName, "package") masterDocumentPackage.Update masterDocumentPackage.Element.Stereotype = "master document" masterDocumentPackage.Alias = documentAlias masterDocumentPackage.Version = documentVersion masterDocumentPackage.Update 'link to the master template dim templateTag as EA.TaggedValue for each templateTag in masterDocumentPackage.Element.TaggedValues if templateTag.Name = "RTFTemplate" then templateTag.Value = "(model document: master template)" templateTag.Notes = "Default: (model document: master template)" templateTag.Update exit for end if next 'return set addMasterDocument= masterDocumentPackageend function |
Then we need to make the Model Documents.To make one with a Package as source we use this function
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
function addModelDocumentForPackage(masterDocument,package,name, treepos, template) dim modelDocElement as EA.Element set modelDocElement = masterDocument.Elements.AddNew(name, "Class") 'set the position modelDocElement.TreePos = treepos modelDocElement.StereotypeEx = "model document" modelDocElement.Update 'add tagged values dim templateTag as EA.TaggedValue for each templateTag in modelDocElement.TaggedValues if templateTag.Name = "RTFTemplate" then templateTag.Value = template templateTag.Notes = "Default: Model Report" templateTag.Update exit for end if next 'add attribute dim attribute as EA.Attribute set attribute = modelDocElement.Attributes.AddNew(package.Name, "Package") attribute.ClassifierID = package.Element.ElementID attribute.Updateend function |
To make one with an SQL Search as source we use this function
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
|
function addModelDocumentWithSearch(masterDocument, template,elementName, elementGUID, treepos, searchName) dim modelDocElement as EA.Element; set modelDocElement = masterDocument.Elements.AddNew(elementName, "Class") 'set the position modelDocElement.TreePos = treepos modelDocElement.StereotypeEx = "model document" modelDocElement.Update dim templateTag as EA.TaggedValue if len(elementGUID) > 0 then for each templateTag in modelDocElement.TaggedValues if templateTag.Name = "RTFTemplate" then templateTag.Value = template templateTag.Notes = "Default: Model Report" templateTag.Update elseif templateTag.Name = "SearchName" then templateTag.Value = searchName templateTag.Update elseif templateTag.Name = "SearchValue" then templateTag.Value = elementGUID templateTag.Update end if next else 'add tagged values for each templateTag in modelDocElement.TaggedValues if templateTag.Name = "RTFTemplate" then templateTag.Value = template templateTag.Notes = "Default: Model Report" templateTag.Update exit for end if next 'no GUID provided. Set masterdocument package ID as dummy attribute to make the template work dim attribute as EA.Attribute set attribute = modelDocElement.Attributes.AddNew(masterDocument.Name, "Package") attribute.ClassifierID = masterDocument.Element.ElementID attribute.Update end ifend function |
The the last script we is one to actually use these functions in order to create the virtual document. In the example provided I’ve split the script in two parts. One part that remains in the library, and one script that is put in the Diagram Group so we can call it from a diagram directly.
The script in the Diagram Group takes care of getting the user input
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
|
option explicit!INC Bellekens DocGen.UseCaseDocument' Script Name: Create Use Case Document' Author: Geert Bellekens' Purpose: Create the virtual document for a Use Case Document based on the open diagram' Copy this script in a Diagram Group to call it from the diagram directly.' Date: 11/11/2015'sub OnDiagramScript() dim documentsPackage as EA.Package 'select the package to generate the virtual document in Msgbox "Please select the package to generate the virtual document in",vbOKOnly+vbQuestion,"Document Package" set documentsPackage = selectPackage() if not documentsPackage is nothing then ' Get a reference to the current diagram dim currentDiagram as EA.Diagram set currentDiagram = Repository.GetCurrentDiagram() if not currentDiagram is nothing then createUseCaseDocument currentDiagram, documentsPackage.PackageGUID Msgbox "Select the Master Document and press F8 to generate document",vbOKOnly+vbInformation,"Finished!" else Session.Prompt "This script requires a diagram to be visible", promptOK end if end ifend subOnDiagramScript |
The script in the library will use the functions mentioned above to start building the virtual document
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
!INC Local Scripts.EAConstants-VBScript!INC Bellekens DocGen.DocGenHelpers!INC Bellekens DocGen.Util'' Script Name: UseCaseDocuemnt' Author: Geert Bellekens' Purpose: Create the virtual document for a Use Case Document based on the given diagram' Date: 11/11/2015'dim useCaseDocumentsPackageGUIDfunction createUseCaseDocument( diagram, documentsPackageGUID) useCaseDocumentsPackageGUID = documentsPackageGUID 'first create a master document dim masterDocument as EA.Package set masterDocument = makeUseCaseMasterDocument(diagram) if not masterDocument is nothing then dim i i = 0 'use case diagram part 1 addModelDocumentForDiagram masterDocument,diagram, i, "UCD_Use Case Diagram" i = i + 1 'add Actors dim diagramPackage as EA.Package set diagramPackage = Repository.GetPackageByID(diagram.PackageID) addModelDocumentForPackage masterDocument, diagramPackage, diagram.Name & " Actors", i, "UCD_Actors" i = i + 1 ' We only want to report the use cases that are shown within the scope boundary on this diagram 'get the boundary diagram object in the diagram dim boundaries set boundaries = getDiagramObjects(diagram,"Boundary") Session.Output boundaries.Count 'get the use cases dim usecases if boundaries.Count > 0 then set usecases = getElementsFromDiagramInBoundary(diagram, "UseCase",boundaries(0)) Session.Output "boundary found" else set usecases = getElementsFromDiagram(diagram, "UseCase") end if 'sort use cases alphabetically set usecases = sortElementsByName(usecases) 'add the use cases i = addUseCases(masterDocument, usecases, i) Repository.RefreshModelView(masterDocument.PackageID) 'select the created master document in the project browser Repository.ShowInProjectView(masterDocument) end ifend functionfunction makeUseCaseMasterDocument(currentDiagram) 'we should ask the user for a version dim documentTitle dim documentVersion dim documentName dim diagramName set makeUseCaseMasterDocument = nothing diagramName = currentDiagram.Name 'to make sure document version is filled in documentVersion = "" documentVersion = InputBox("Please enter the version of this document", "Document version", "x.y.z" ) if documentVersion <> "" then 'OK, we have a version, continue documentName = "UCD - " & diagramName & " v. " & documentVersion dim masterDocument as EA.Package set masterDocument = addMasterDocumentWithDetails(useCaseDocumentsPackageGUID, documentName,documentVersion,diagramName) set makeUseCaseMasterDocument = masterDocument end ifend function'add the use cases to the documentfunction addUseCases(masterDocument, usecases, i) dim usecase as EA.Element for each usecase in usecases 'use case part 1 addModelDocument masterDocument, "UCD_Use Case details part1", "UC " & usecase.Name & " Part 1", usecase.ElementGUID, i i = i + 1 'get the nested scenario diagram dim activity as EA.Element set activity = getActivityForUsecase(usecase) 'add scenario diagram if not activity is nothing then addModelDocument masterDocument, "UCD_Use Case Scenarios Diagram", "UC " & usecase.Name & " Scenarios diagram", activity.ElementGUID, i i = i + 1 end if 'use case part 2 addModelDocument masterDocument, "UCD_Use Case details part2","UC " & usecase.Name & " Part 2", usecase.ElementGUID, i i = i + 1 next 'return the new i addUseCases = iend functionfunction getActivityForUsecase(usecase) set getActivityForUsecase = getNestedDiagramOnwerForElement(usecase, "Activity")end functionfunction getInteractionForUseCase(usecase) set getInteractionForUseCase = getNestedDiagramOnwerForElement(usecase, "Interaction")end functionfunction getNestedDiagramOnwerForElement(element, elementType) dim diagramOnwer as EA.Element set diagramOnwer = nothing dim nestedElement as EA.Element for each nestedElement in element.Elements if nestedElement.Type = elementType and nestedElement.Diagrams.Count > 0 then set diagramOnwer = nestedElement exit for end if next set getNestedDiagramOnwerForElement = diagramOnwerend function'sort the elements in the given ArrayList of EA.Elements by their name function sortElementsByName (elements) dim i dim goAgain goAgain = false dim thisElement as EA.Element dim nextElement as EA.Element |