Author Topic: Show return step in use case scenario documentation  (Read 1272 times)

Drew Tebs

  • EA Novice
  • *
  • Posts: 5
  • Karma: +0/-0
    • View Profile
Show return step in use case scenario documentation
« on: December 22, 2017, 02:12:30 am »
Dear all,

We have all our functional documentation in EA 13.5 including our use case scenario's.
Our current documentation generator works sufficient but not the way we truely want it to work.
There are 2 seperate problems I would like to fix.
See the code box below for what we've currently got, copied from the EA template.

Problem 1: "uses" and "results" only when present
With the current structure every step in the scenario has a line with "uses" and "results" but not every step has a "use" or a "result" defined.
The problem is that even though there isn't a "use" or "result" defined, the prefix/label is still shown.
Is there a way to only show the prefix/label when there is a "use" or "result" defined for that step?

Problem 2: No return visible from Exception scenario to Basic scenario.
It's possible to specify where an alternate/exception scenario returns to the basic scenario.
The activity diagram shows this nicely, but not the documentation.

I'm looking for an element in the Package>Element>Scenario>Structured Scenario>Exception called "returning to" or something like that.
The desired outcome look similar to this:

Basic scenario: Going outside
1) detect that it's not raining
          Alternate scenario: It's raining
2) open door
3) get out of the house

Alternate scenario: It's raining
1) Grab umbrella
Return to basic scenario step 2

Is there a way to display the italic line?

Thank you!

Current code:
Code: [Select]
package >
element >
scenario >

{ElemScenario.Type}: {ElemScenario.Scenario}
{ElemScenario.Notes}
structured scenarios >
{Scenario_Structured.Step} - {Scenario_Structured.Action}
Uses: {Scenario_Structured.Uses}
Results: {Scenario_Structured.Result}
exception >
{Exception.Type}: {Exception.Step} - {Exception.Name}
< exception
< structured scenarios
------
< scenario
< element
< package

Richard Freggi

  • EA User
  • **
  • Posts: 97
  • Karma: +4/-3
    • View Profile
Re: Show return step in use case scenario documentation
« Reply #1 on: December 22, 2017, 01:25:30 pm »
Hello Drew
you are making a very common error - trying to make a flow chart (a functional decomposition that includes some logic) with use cases.
It's not going to work - and it's not going to be useful for your team.
Use cases should only show WHO (actors) want to achieve WHAT goal (use case).  They should show the scope and requirements for your project.  For example 'Going outside' is unlikely to be a goal (unless you want to break out of prison, for example); 'Buy Xmas gifts' is a goal and going outside is how you achieve the goal if you need to get to the shopping mall to achieve it.  Use cases should not say anything about HOW the goals are achieved: sequence diagrams are used to show HOW.

I think your team may want to think about whether you want to use UML as the notation for your functional documentation; for example BPMN (not UML but supported by a free plugin in EA) is a good functional decomposition notation.

If you want to keep using UML, could I recommend some UML books such as 'Use case modeling' and 'Applying use cases' (Addison-Wesley).  Cheers!

Geert Bellekens

  • EA Guru
  • *****
  • Posts: 8470
  • Karma: +207/-26
  • Make EA work for YOU!
    • View Profile
    • Enterprise Architect Consultant and Value Added Reseller
Re: Show return step in use case scenario documentation
« Reply #2 on: December 22, 2017, 03:31:02 pm »
I do not agree per se with Richard.
Sure, your example is bogus, but I'm sure your real use cases are much more usable.

For 1: check out bookmarks. You can add a End and Start bookmark around the part that you want to leave out if it is empty.

For 2: It looks like you've used all available scenario fields. I don't think there much else you can do. Contact Sparx support to be sure. They can enter a feature request for you if indeed that feature is not available

Geert

Richard Freggi

  • EA User
  • **
  • Posts: 97
  • Karma: +4/-3
    • View Profile
Re: Show return step in use case scenario documentation
« Reply #3 on: December 23, 2017, 01:13:08 am »
Either way - strong request to Sparx team: please keep EA fully UML compliant - no 'dialects' or pidgin UML. 

Profiles are the right way to extend UML to a local 'dialect' if it is beneficial for  users... 

Drew Tebs

  • EA Novice
  • *
  • Posts: 5
  • Karma: +0/-0
    • View Profile
Re: Show return step in use case scenario documentation
« Reply #4 on: December 27, 2017, 10:02:57 pm »
Hey Richard and Geert,

For 1: I'll give the bookmarks a go but my first 5-minute attempt at it didn't work out so I'll have to put some more effort into it. I'll keep you guys updated.

For 2: The example provided was indeed bogus, a quick thing to jolt down to show the desired result (the line in italic). I think it's weird that this isn't possible yet. The information needed is obviously already present. Otherwise you wouldn't be able to specify it and see it in the activity diagrams. It is a mere question of how to get the already present information in the system on the paper in a understandable manner.

Geert Bellekens

  • EA Guru
  • *****
  • Posts: 8470
  • Karma: +207/-26
  • Make EA work for YOU!
    • View Profile
    • Enterprise Architect Consultant and Value Added Reseller
Re: Show return step in use case scenario documentation
« Reply #5 on: December 28, 2017, 08:05:41 pm »
Drew,

I think the exceptions (showing where another scenario starts) themselves are a relative recent addition to the RTF templates, so there's a good chance that Sparx hasn't implemented the join step in the RTF templates.
Worth a feature request I think.

If you can't wait for Sparx to implement it as a new feature then you are looking at using a fragment, but that is not going to be easy.
The structured scenario information is hidden in an xml field in the database, so unless you are a wizard with SQL you are probably looking at a script fragment to get the information you need.

Geert

Simon M

  • EA Administrator
  • EA Guru
  • *****
  • Posts: 6447
  • Karma: +55/-6
    • View Profile
Re: Show return step in use case scenario documentation
« Reply #6 on: January 02, 2018, 08:48:02 am »
Either way - strong request to Sparx team: please keep EA fully UML compliant - no 'dialects' or pidgin UML. 

Profiles are the right way to extend UML to a local 'dialect' if it is beneficial for  users...

Richard, in effect any extension can be thought of as a profile. It doesn't matter if it is represented as such within the tool or not. The scenarios originally implemented in EA more than 10 years ago are a composite stereotype property:
Code: [Select]
scenarios: EAScenario [0..*] {unordered, unique]
At the time, those were only a name, type and notes. A few years back the EAScenario object was extended to contain a sequence of steps. ie.
Code: [Select]
steps: EAScenarioStep [0..*] {ordered,
 unique}

In effect, everything that appears as a shape on a diagram has this local stereotype applied, even if it's not notated. The same stereotype also provides other optional collections like test cases, requirements, issues and simple fields like author, status, difficulty etc. fields. Even the database limitations applied to those fields can be expressed as OCL constraints.

Summary: Extra fields can always be expressed as a profile. It isn't an issue for UML compliance.
Simon

support@sparxsystems.com