Report strategy question

[ChrisMW]

I've been asked to create a report and I'm running into a problem. It's a simple package structure, an element, with a composite diagram and child elements. The thing is, I want to only report a particular type of those child elements.

My initial attempt was to simply create to fragments, each with the right filters and use those. But then I noticed that you can't use fragments in child elements    I tried adding both fragments to the element section, which almost works, the parent element fires, then it goes through the children and only the second fragment gives output. However, when done, it does not return to the first fragment, but simply keeps running the second fragement.

I think it would work if I could add a fragement to either a child element or embedded element section, but I can't. Does anyone have a suggestion? Creating a report package won't really solve the problem, the hierarchy I am reporting on is ok, but I need to filter different elements for the elements that are a child of another element.

I've added a small screenshot from the project browser. My top level contains 2 diagrams and a couple of packages. The ones labeled Qx .... contains Archimate plateau elements, in some of the plateau's there are deliverables. I want to traverse all plateau's and within the plateau, the deliverables. One complicating factor is that these are all class elements with an Archimate stereotype.

I tried creating a filter that simply lists only the two stereotypes I want, but when I create the filter and use the 'one of' option, it does list some Archimate stereotypes, but not the ones I want. I then added the ones I wanted, but the iteration was missing quite a few items.

I could create a report package, but then the deciding unit is a package and I don't have sub packages. Perhaps sub reports would work? I haven't used them before, so not sure. Does anyone have a good suggestion?

Rgds Chris

http://www.widdows.nl/ea_report.jpg

[Geert Bellekens]

Hi Chris,

I've had great success with Virtual Documents for complicated things like that.
I wrote some of it down in a article on my website: Tutorial: Generate complex documents from Enterprise Architect with a two-step semi-automated approach

I hope this helps

Geert

[ChrisMW]

Hi Geert,

Yes, possibly that would work, I've used Virtual Documents before. The trouble I'm having is that to report on interesting things I need to be in the element section, but there seems to be no way to tell the report engine to use different sets on different levels. If I leave the child elements section empty, it uses the elements definition, but when I added bespoke items to the child element section, I cannot access links etc.. just the element attributes. The easiest way to fix this allow fragments in the child element section (Virtual documents work great with packages, but tend to be better in reporting on the same hierarchy in different ways, or combining different, non-hierarchical packages to the same template / report section). For that matter, fragments should also be enabled for child packages I guess. Another 'trick' would be to just put all the fragments in the element section and let the filtering produce fragment output or not. That does actually work, but it does not traverse all elements, I notice the first fragment fires, then the second (for the children) and then it just keeps firing the second fragment.

With virtual documents my main issue would be how to get the hierarchical report I want (plateau -> deliverable) without having to set up 2 model documents per plateau. In fact, I'm not even sure you can include elements into model documents, I've so far only added packages.

So I am trying to re-think the project structure, which is almost proving a little hard....... I can of course ask for a change to the report writer, but that doesn't solve my immediate need.

[Geert Bellekens]

Hi Chris,

The "trick" I use to get a single element as the source of a model document is to use an SQL search that returns a single element.

A downside of this approach might be that you need a lot of model documents if you need to report on a lot of elements.
I overcome that downside by scripting the virtual document creation.

With the combination of virtual documents, scripts and fragments I have been able to meet all the (craziest) requirements for documents so far.

In some cases my script even creates custom diagrams in the virtual document package with the sole purpose of being included in the document.

Geert

[ChrisMW]

Hi Geert,

My scripting experience is limited. But actually I found that one of the fragments from my original attempt was including child elements. When I removed that, it seems to have solved the problem with traversing the elements. Now the main element loop has two fragments, each with specific layout and filtering options and each fragment 'fires' when the correct element is encountered. This is pretty simple, and fits with what I thought should work. I just missed that one check mark. Right now I am almost where I want to be, so I'll explore this further.

Thank you for your suggestions.

Chris

[Uffe]

Hi Chris,


A different approach is to take control of the generation process yourself by scripting it. I've done this for several clients.

The starting point would be a browser script called "Generate Document" or similar, which checks what type of element it is being called on and then uses the DocumentGenerator class to invoke the necessary templates in the correct order. Of course, the script can also follow connectors, loop through child elements, etc.

This approach circumvents the structural limitations of the built-in generation process, at the cost of having to implement the model traversal yourself. Sometimes worth it, sometimes not. But if you're having trouble with child elements and element filtering, this is the way I'd go.

HTH,


/Uffe

[ChrisMW]

This sounds an interesting alternative. Perhaps not for this problem, but this might a usefull approach to have in one's arsenal. Any chance of hello world kind of example?

[Uffe]

What - and give away all my trade secrets?

Weeelll, alright. But only because it's my birthday.

Here's a simple hello-world type example of a document generation project browser script in VBScript. To get started, create a browser script and replace all its contents with this.

It won't run out of the box (unless by a staggering coincidence you've got two templates named "My title page template" and "My first chapter template"), so read it and make the necessary adjustments and completions before you try to run it.

Cheers,


/Uffe

Code: (VBScript) [Select]

option explicit

' Sample EA document generation script.
' (c) Happy Path AB 2016.
'
' Open source; free to use, modify and redistribute.
' Intended for instructional purposes only.
' Provided as-is; no liability accepted; no support given.

!INC Local Scripts.EAConstants-VBScript

' Prompts the user for a file name using the standard dialog.
' If an empty string is returned, the user has clicked Cancel.
function PromptForFileName(dirName, suggestedFileName)
dim fileName
fileName = Repository.GetProjectInterface().GetFileNameDialog(suggestedFileName, "*.docx", 1, 2, dirName, 1)

' This check for a proper file suffix is incomplete.
' Creating a better one is left as an exercise for the reader.
if (fileName <> "" and InStr(fileName, ".") = 0) then
fileName = fileName & ".docx"
end if

PromptForFileName = fileName
end function

' Generates a document. Mostly empty, this is where Your Code Goes.
sub GenerateUseCaseDocument(docGen, element)
' Style sheet is optional. It can be set before the document is created.
' This particular style sheet is supplied by Sparx as part of the EA installation.
docGen.SetStyleSheetDocument("Numbered Headings - Black")
docGen.NewDocument("")

' Actual document generation is a matter of traversing the model structure
' and applying the right templates.
' Note that this way of generating a document does not affect the relationship
' between templates and template fragments. If a template which contains a
' template fragment is specified in a call to DocumentGenerator.DocumentElement,
' the fragment gets invoked as normal. DocumentGenerator calls should never refer
' to template fragments, only to "full" templates.

Session.Output "    Title page"
docGen.DocumentElement element.ElementID, 0, "My title page template"

Session.Output "    Table of contents"
docGen.InsertBreak breakPage
docGen.InsertTableOfContents()

Session.Output "    Chapter 1"
docGen.InsertBreak breakPage
docGen.DocumentElement element.ElementID, 0, "My first chapter template"

' And so on and so forth. There are plenty of examples of code for traversal
' of model structures out there, so that's omitted here as well.

' When all templates have been invoked, we don't need to do anything here.
' The whole document is now contained in the DocumentGenerator object.
end sub

' Performs post-processing of document in Microsoft Word.
' Actually only opens and closes the document file, since the Word API is
' outside the scope for this example.
sub PostProcessDocument(fileName)
dim wordApp
dim wordStarted
on error resume next
set wordApp = GetObject(, "Word.Application")
if (err.Number = 0) then
wordStarted = false
else
set wordApp = CreateObject("Word.Application")
wordApp.Visible = False
wordStarted = true
end if
dim doc
set doc = wordApp.Documents.Open(fileName)
' Document manipulation code goes here.....
' ... and when we're done:
doc.Close(-1)
if (wordStarted) then
wordApp.Quit()
end if
end sub

sub OnProjectBrowserScript()
dim treeSelectedType
treeSelectedType = Repository.GetTreeSelectedItemType()

Repository.EnsureOutputVisible("Script")

' The outer select statement checks what the user right-clicked in the project browser.
' The DocumentGenerator class has methods for generating document sections from diagrams,
' elements and packages. Only elements are accepted in this example.
select case treeSelectedType
case otElement
dim element as EA.Element
set element = Repository.GetTreeSelectedObject()

' The inner select statement checks what specific element type was selected.
' Within each case, it would make sense to check the stereotype as well, but
' that's omitted in this example.
select case element.Type
case "UseCase"
' First, prompt the user for the target document file.
dim fileName
fileName = PromptForFileName("C:", element.Name)

if (fileName = "") then
Session.Output "Document generation cancelled."
else
' Set up the document generator.
dim docGen as EA.DocumentGenerator
set docGen = Repository.CreateDocumentGenerator()

' Generate the document
Session.Output "Generating use case document for " & element.Name
GenerateUseCaseDocument docGen, element

' Once all the templates have been invoked, save the document to the selected file.
Session.Output "Writing use case document to " & fileName
docGen.SaveDocument fileName, dtDOCX

' At this point, the document is generated and we can stop here.

' After the document's been saved, the script can go on to open it in
' Microsoft Word for post-processing. This is entirely optional, but often useful.
Session.Output "Post-processing document..."
PostProcess fileName

Session.Output "Document generation complete."

' Once any post-processing is complete, we can open the document.
' This is of course also optional, but in my experience useful more often than not.
CreateObject("WScript.Shell").Run("Winword.exe """ & fileName & "")
end if

' Catch-all case for when the script has no code to generate a document for the
' selected element type / stereotype.
case else
Session.Prompt "No document type defined for «" & element.Stererotype & "» " & element.Type
end select

' Catch-all case for when the user right-clicked something we don't have a generation process for.
case else
Session.Prompt "This script does not support items of this type.", promptOK
end select
end sub

OnProjectBrowserScript


[Geert Bellekens]

Hi Uffe,

Happy birthday!

As you might know I started an open source VBScript library for Enterprise Architect on github: https://github.com/GeertBellekens/Enterprise-Architect-VBScript-Library
Would you be interested in contributing to this library, or if not, would you mind if added your example script?

Thanks

Geert

[Uffe]

Hi Uffe,

Happy birthday!

Why, thank you. 

As you might know I started an open source VBScript library for Enterprise Architect on github: https://github.com/GeertBellekens/Enterprise-Architect-VBScript-Library
Would you be interested in contributing to this library, or if not, would you mind if added your example script?

Sure, I'll put it up there. In a day or two. Gotta get rid of this hangover first... 

/U

[Geert Bellekens]

Cool, thanks.

Geert