Reporting - Nested "Report Packages"

[MichaelJ]

Hi everyone,

Using the "Report Package" element in EA for grouping one or more "Model Document" (each one can have its own RTF template) is tremendously useful as each Model Document can specify their own RTF templates to use.

Our documentation scenario is as shown below:

(report package #1)
|---a -> PACKAGE_1_CONTENT
|---b -> PACKAGE_2_CONTENT
|---c -> (report package #2)
|-------d -> PACKAGE_3_CONTENT
|-------e -> PACKAGE_4_CONTENT


Q: Is it possible to add a report package as a child into a parent report package?

We wish to do this to maintain visual hierarchy/nesting and numbering levels in Table of Contents and relevant sections of the report. For example, report package #2 headings are "indented" when printed in the context of its parent package, but remain un-indented when printed by itself.

[Sunshine]

Not 100% clear on what you are asking about nesting but will attempt to answer your question.
You can have multiple model documents under a master document package.
You can use fragments and include them in a template

In a template if you use Header1 for a package and tick the child packages then as the report generator navigates down the packages it automatically changes Header1 to Header2, Header3 etc. accordingly. Note that it only goes to Header9

[MichaelJ]

Not 100% clear on what you are asking about nesting but will attempt to answer your question.
You can have multiple model documents under a master document package.
You can use fragments and include them in a template

In a template if you use Header1 for a package and tick the child packages then as the report generator navigates down the packages it automatically changes Header1 to Header2, Header3 etc. accordingly. Note that it only goes to Header9

Hi Sunshine,

Thank you for your response. Ok, we'll try what you've suggested. It definitely sounds like it will meet the described reporting scenario :-)

PS: I'm not sure how to attach an image into this forum reply without hosting it anywhere else... SMF framework used for this forum is really hobbled and doesn't support direct image uploads 


Below is a textual description of the functionality we hope to achieve:

• 2 report packages. Each package contains one or more document models. Each document model is assigned a unique RTF template.
  
• Embed one package into another so that its contents are printed together with the contents of the hosting package

Sample report output would look something like:

[Report Package A] 1. System Architecture

   [Report Package B] 1.1. Physical Overview

   [Report Package B] 1.2. Physical Data Process Flow

[Report Package A] 2. Business Considerations


Note: Report Package B can be printed separately and would therefore be defined in its own report package.

[Sunshine]

Okay lets see if this works
If you have model structure like this
Model
-->Package 1
-->Package 2
-->Package 3
-->Package 4

You can create a model document something like this
Master Document
-->Model Document X (Package 1, RTF Template A)
-->Model Document Y (Package 2, Package 3, RTF Template B)
-->Model Document Z (Package 4, RTF Template A)

Where RTF Template A has header 1 defined as first header style and RTF Template B has Header 2 defined as first header style. That should give you the desired result of nesting header levels.

If package 2 and 3 need different RTF template as the layout is different then just add another Model Document with the Package 3 and another RTF template.

Make sure your model documents are ordered in the project browser to get the desired order.

PS: I'm not sure how to attach an image into this forum reply without hosting it anywhere else... SMF framework used for this forum is really hobbled and doesn't support direct image uploads 

You need to the post an image on another site and use a link to the image.

Hope that helps

[MichaelJ]

...
Where RTF Template A has header 1 defined as first header style and RTF Template B has Header 2 defined as first header style. That should give you the desired result of nesting header levels.

If package 2 and 3 need different RTF template as the layout is different then just add another Model Document with the Package 3 and another RTF template.

Make sure your model documents are ordered in the project browser to get the desired order.
...

Hi Sunshine,

Thank you for your response We attempted your approach, and it works like a charm. 

The challenge is to move Package 2 and Package 3 as children of Package1 and maintain separate templates for each package. So, based on trial and error, we created a single Document Model and referred it to Package 1 (now with child package 2 and 3) and also assigned a template (RTF Template A). The report generator used the Document Model's template and applied the template to all three packages.

If we take the approach provided -- each package is referenced by its Document Model and respective template -- then this approach works a charm. This approach works as long as each package is not nested.

Do you think this scenario (nested packages with assigned template) is impossible(?) to achieve without hard-coding scripts or designing templates and fragments? Hard-coding is always a terrible approach and breaks easily the moment the Browser order of packages change.

However, if this ability is merely not yet supported, I'm happy to log this as a feature request. Unfortunately, as I'm sure many have experienced, logging feature requests is like throwing a surprise party… for yourself! Better that than the zero response/acknowledgement from the Sparx team. It's a silly mindset given that active community feedback ought to be welcomed.

Such feedback drives improvements to the product that has induced countless episodes of Stockholm-Syndrome.

[Sunshine]

Yes you should be able to do it by setting up your master and model documents like this and disable child packages in one report.

Master Document Package
   Model Document X [Using Report A starts at H1 header with Child Packages disabled]
      Attribute pointing to System Architecture Package

   Model Document Y [Using Report B starts at H2 header ]
      Attribute pointing to Physical Overview Package
      Attribute pointing to Physical Data Process Flow Package

   Model Document Y [Using Report C] starts with H1 header]
      Attribute pointing to Business Considerations Package

My advice though is don't structure you model like a document structure it like a model so you can produce many different documents from it.

[Modesto Vega]

Sunshine is right. You want to use Report Packages to structure your documentation and do not try to organise your models like your documentation.

You should be able to nest report packages but my suggestion will be to create a documentation stracture as follows:

[Report Package A] 1. System Architecture
----[Model Document B] 1.1. Physical Overview
----[Model Document C] 1.2. Physical Data Process Flow
[Report Package D] 2. Business Considerations
----[Model Document E] 2.1 [...]

Or
[Report Package A] 1. System Architecture
----[Model Document B] 1. System Architecture
----[Report Package C] 1.1. Physical Architecture
-------[Model Document D] 1.1. Physical Overview
-------[Model Document E] 1.2. Physical Data Process Flow
[Report Package F] 2. Business Architecture
----[Model Document G] 2.1 [...]

Having said this, I am also having trouble picturing what you are trying to do.

[MichaelJ]

Hi Modesto and Sunshine

Thank you for your input, really appreciated!

...
My advice though is don't structure you model like a document structure it like a model so you can produce many different documents from it.

Sunshine is right. You want to use Report Packages to structure your documentation and do not try to organise your models like your documentation.

Yes absolutely agreed with the statement to not structure our model like a matching report structure: advice well-heeded.

...
Having said this, I am also having trouble picturing what you are trying to do.

We're like to achieve this reporting scenario:

• Generate 2 Report Package instances -- for example, [Report Package C] and [Report Package F]
• Add one or more Document Models to each Report Package instance
• Create an "uber" Report Package instance -- for example, [Report Package A]
• Add the Report Packages from (1) to Report Package (3)
• Print the Report Package (3)

The generated report for the uber package does not contain any content. However, if we print [Report Package C] and [Report Package F] separately, then all is well.

...
[Report Package A] 1. System Architecture
----[Model Document B] 1. System Architecture
----[Report Package C] 1.1. Physical Architecture
-------[Model Document D] 1.1. Physical Overview
-------[Model Document E] 1.2. Physical Data Process Flow
[Report Package F] 2. Business Architecture
----[Model Document G] 2.1 [...]

Logically, this scenario seems "simple" enough but it does not seem to be, and it feels like there's juuuuuusssst one thing that is the "glue" to make this work. Just hope the glue has not hardened

[Modesto Vega]

[SNIP]
Logically, this scenario seems "simple" enough but it does not seem to be, and it feels like there's juuuuuusssst one thing that is the "glue" to make this work. Just hope the glue has not hardened

With regards to the "glue", holding all of this together it depends on what you are trying to document. The "glue" to hold of this together is different depending on whether you are documenting an enterprise architecture, a single system, or a collection of related systems that forms part of wider enterprise architecture.

My preference when structuring a repository for a medium to large organisation is to split the repository into 2 root models, one for Enterprise Architecture and another for Application Architecture, with the Application Architecture root model containing one package per system and the Enterprise Architecture root node containing a package describing the Business Context and another package portioning the enterprise architecture into domains/subject areas.

The advatange of this approach is that you can have as many system architectures, physical architectures and business architectures as you need.

I guess my key point is you do not have 1 architecture, any medium or large modern enterprise has many architectures at different levels of abstraction. The challenge is how to architect architectures.

Hope this makes sense. There used to be post in this forum discussing this in depth but cannot find it right now.