Template for UseCase

[Pawel Zubkiewicz]

Hello,

I'm designing template for UseCases. I'm using Structered Scenario thing and I like it very much from desinger perspective. However from template reports perspective it's not so excellent.

So I have this structure of sections: Package -> Element -> Scenario -> Structured Scenario -> Exception.

This allows me to generate document with each step of the use case scenario. Also last exception section allows me to put information about alternative flow for that step but only in "basic path" main scenario.
When template evaluates alternative scenario called "Invalid e-mail address" I can't figure out how to put information about where this scenario starts and when joins back main scenario.

What I want to achieve in generated document with similar structure:

Code: [Select]

Header: Main scenario: ABC
1. Step 1
2. Step 2, Alternative 2a - alternative scenario XYZ - joins at 1.
3. Step 3

Header: alternative scenario XYZ
This scenario starts at step 2 of main scenario and joins back at step 1.
1. Step 1
2. Step 2
3. Step 3
4. Step 4
I managed to have everyting except This scenario starts at step 2 of main scenario and joins back at step 1. sentence in alternative scenario sub-chapter.

I tried to approach this witch custom Fragment, but (to my surprise) EA does not allow me to insert fragment inside Scenario section. (I can insert any fragment inside Element section though).

Any help will be appreciated  8-)

[Geert Bellekens]

I've sent in a feature request to Sparx to make that information available in the templates.

If you can't wait for that I'm afraid you'll have to write the whole scenario section yourself in a custom fragment.

Geert

[Pawel Zubkiewicz]

I've sent in a feature request to Sparx to make that information available in the templates.

Wow, you asked for feature which clearly could be scripted  
I hope you also asked for decent numbering of alternative scenario steps, like:
2a
3a

If you can't wait for that I'm afraid you'll have to write the whole scenario section yourself in a custom fragment.

Actually I don't even know if that's possible or at least I can't imagine it. You can't include fragment inside other fragment which makes it particularly hard when dealing with collections.

And we have a lot of collections here
1. Structured Scenarios are stored as Collection in Element class, further more,
2. each Structured Scenarios has a Collections of ScenarioSteps
3. each ScenarioStep has a collection of ScenarioExtension

Those ScenarioExtension objects contain information that I really want to put in generated document.

Even if I write a script for this, and execute it by a fragment then as you said I will have to also implement whole Use Case scenario template by myself, so acutally it's possible but not worth it :-(

[Geert Bellekens]

so acutally it's possible but not worth it :-(

We came to exactly the same conclusion so we currently live with the limits of the standard fields available.

Geert

[Pawel Zubkiewicz]

Since we are talking about UseCase template. Another thing I would love to have in a generated document is a WireFrame diagram (mock-up) connected to the particular use case.

I understand that unless I will put my mockup diagram in the same package (or even inside/under usecase element) than it's impossible to include mock-up (from different package) without writing my own Document Generator in C# or Java?
Or is there some clever way to do it?

Let's assume I have such project structure

Code: [Select]

1. Project
1.1 UseCase Model
1.1.1 UC1
1.1.2 UC2
1.2 Mockups
1.2.1 Mockup 1 (connected with UC1)
1.2.2 Mockup 2 (connected with UC2)

[Geert Bellekens]

The way we do it is to include model sections in our virtual document;
My virtual document sortof looks like this:

- Document X
 - UseCaseA part 1
 - UseCaseA Diagram
 - UseCaseA part2
 - UseCaseA Req x BP matrix
 - UseCaseB part 1
 - UseCaseB... etc...

Each section is either populated with a refence to a package, or with an SQL Search.

That saves a lot of headscratches trying to fit everything into one big template.

As a finishing touch I create the virtual document with a script based on the use cases inside a boundary on the selected diagram, but that is just the icing on the cake, not essential to the way this works.

Geert

[Pawel Zubkiewicz]

Hi Geert,

Virtual documents are very powerful and ideal (in my opinion) solution for generating huge documents that include multiple views, for example Software Architecture Document, Business Requirements Document etc.

However, I want to give my analysts a tool(template) that will allow them to generate documentation just for subset of all use cases.
The real work scenario
1. Business creates change request
2. After preliminary analysis we know that this changed request impacts two requirements, let's say REQ011 and REQ121.
3. Further more, those two requirements are realized by two use cases : UC012 and UC033.
4. Analyst does changes to requirements, use cases and associated mockups.

Now I want to have simple solution that allows to generate document that will contain only changed things. I don't want to do report by "last modification date" here. Assuming that I have my model well organized and everything is traced to each other, I should be able to select in Project Browser (or search results) those two use cases UC012 and UC033, hit F8 and generate a document that will contain only elements in a scope of change.

5. Finally, analyst gives a generated document to dev team, so they know what to do.


When I will have "clever" template for UseCase specification that includes realized requirements by UseCase (I have that now) and associated mockups (I don't have that) I will achieve what I need.

By using Custom SQL in fragment it's easy to find associated mockups with UseCase. However as far as I know it's extremely hard / impossible to include a diagram that way.

Maybe you have an idea how I should approach that problem?

[Geert Bellekens]

Hi Pawel,

The only feasible way I know is to use virtual documents.
I would make a script that creates the virtual document based on the selection of use usecases (or another criterium)

That allows you to create a structure with different sections for each use case, one section for the details, one section for the GUI mocups, one section for ...

Geert

[Pawel Zubkiewicz]

Script that creates virtual document... didn't know it's even possible :-)
Will look into that when I will have time.

On the other hand if Sparx would add a possible to include diagram found by SQL into generated document our life would by much simpler :-)

Thank you Geert.

[Geert Bellekens]

Here are some of the helper functions I wrote to create virtual documents

Code: [Select]

function addMasterDocument (packageGUID, documentName)
      dim domainName
      dim splittedDocumentName
      splittedDocumentName = Split(documentName)
      domainName = splittedDocumentName(Ubound(splittedDocumentName))
      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 = domainName
      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 = masterDocumentPackage
end function

function addMasterDocumentWithDetails (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 addMasterDocumentWithDetails = masterDocumentPackage
end function

function addModelDocumentForDiagram(masterDocument,diagram, treepos, template)
      dim diagramPackage as EA.Package
      set diagramPackage = Repository.GetPackageByID(diagram.PackageID)
      addModelDocumentForPackage masterDocument,diagramPackage,diagram.Name & " diagram", treepos, template
end function

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.Update
end function

function addModelDocument(masterDocument, template,elementName, elementGUID, treepos)
      addModelDocumentWithSearch masterDocument, template,elementName, elementGUID, treepos,"ZDG_ElementByGUID"
end function


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 if
end function
Geert

[Robert Sheridan]

As an alternative to scripts: I have created a library of empty virtual docs, the users then use cut and paste to create a copy which they then populate with the package links by dragging and dropping on to the diagram.

[Geert Bellekens]

I've documented my approach, including an example model and use case template in this article: Tutorial: Generate complex documents from Enterprise Architect with a two-step semi-automated approach

Geert

[Drew Tebs]

I realise this is an old thread but the problem / request still exists partially. When looking at the scenario's you can specify when a step joins back to the basic flow. How do you show this in the generated documentation? The activity diagram shows the return to the basic flow but not the text version.

EA is currently in version 13.5 so I wonder if there have been any updates on this topic so far. This is the sole downside my higher-ups can think of why we shouldn't put all our use cases in EA.

Thank you,

The original post:

Hello,

I'm designing template for UseCases. I'm using Structered Scenario thing and I like it very much from desinger perspective. However from template reports perspective it's not so excellent.

So I have this structure of sections: Package -> Element -> Scenario -> Structured Scenario -> Exception.

This allows me to generate document with each step of the use case scenario. Also last exception section allows me to put information about alternative flow for that step but only in "basic path" main scenario.
When template evaluates alternative scenario called "Invalid e-mail address" I can't figure out how to put information about where this scenario starts and when joins back main scenario.

What I want to achieve in generated document with similar structure:

Code: [Select]

Header: Main scenario: ABC
1. Step 1
2. Step 2, Alternative 2a - alternative scenario XYZ - joins at 1.
3. Step 3

Header: alternative scenario XYZ
This scenario starts at step 2 of main scenario and joins back at step 1.
1. Step 1
2. Step 2
3. Step 3
4. Step 4
I managed to have everyting except This scenario starts at step 2 of main scenario and joins back at step 1. sentence in alternative scenario sub-chapter.

I tried to approach this witch custom Fragment, but (to my surprise) EA does not allow me to insert fragment inside Scenario section. (I can insert any fragment inside Element section though).

Any help will be appreciated  8-)

[Geert Bellekens]

You can get that info. Check the Exception section in the Structured Scenario section.

Geert