I was inspired to write this post by Ian Mitchell from eaDocX’s use case discussion at today’s European EA User Group in London. It got me thinking about traps I’ve fallen into and tips that aren’t immediately obvious when starting out with the structured scenario editor.

1. Writing unstructured text first and generating structure

This one I think is the biggest time saver and deserves it’s spot at the top of this list. While the rigid structure of the structured editor has many benefits, free-flowing writing and focusing on content is not one of them – and in my opinion it should be the focus of effort of the first draft of content.

My advice? When writing up the skeleton of your use case stick to the standard ‘Description’ tab to get all your content on paper. Don’t worry about numbering lines, just get it down! Key here is your writing can be fluid and you can capture the detail of your use case flow without having to worry about structure.

creating unstructured use case detail first

Once you’ve got your basic content on paper its a simple two clicks to create a structured scenario. Right click –> Create Structure From Notes –> New Line Delimited.

and transform it into structured scenario steps

Transforms into..

generated structured from free-form use case

Having gone down the path of creating scenarios solely in the structured scenario editor initially – personally I find the process to stilted for my workflow. Having to stop at the each step, add new step, move cursor, get distracted by the context references and whether EA has incorrectly assigned a Actor icon to a system step.. Maybe it’s just my workflow but I prefer to get the basic content down first – then play with the structure.

2. Context references – the magical linkage between elements

Context references is where I first saw the benefit of using the structured scenario view. It allowed me to add references to my model, enforce a standard vocabulary and promote re-usability  – all really good things.

So how does it work?

In our example before we had no references, just plain text. So lets reword the ‘user’ into something more realistic, select it and right click it to see what we can do with it.

defining new elements from use case text

So I’ve renamed user to Librarian and now I can create a new element for this new actor I’ve defined.

select the appropriate element type – in this case its an Actor

Select the Use Case Toolset to find the ‘Actor’ element and notice the name has already been pre-populated for you. The actor element has been added to the project browser as well so it can be re-used – bonus!

Now that we have established this reference it will be used every time the word ‘Librarian’ is entered into the use case text – both in the main scenario or any alternate/exception flows.

This works for existing model elements as well, simply select the text as before but instead of creating a new element, select ‘Insert context reference’

or for existing elements, simply insert a context reference and find the element in the project browser

3. Working with the scenario editor as a window

When you want to quickly flick between scenario content it is pain to have to open a use case via the properties, switch the scenarios tab, and view the structure, only to find it was the wrong use case element and have to open 3 more use cases and repeat the process before you find the step you were looking for.

It can handy to display the scenarios editor as a separate window rather than an inline element.

To do this in EA v10, from the ‘Element’ file menu, select ‘Scenarios and Rules’  (in v9 it can be found in  ’View’ ->’More element tools’ – thanks to Rafal Dmowski for pointing this out)

working with the scenario and rules window

This will popup the scenario and rule window as a separate dialogue which you can have open while you flick between multiple use case elements, either from the canvas or the project browser.

make it a popup window to allow navigation from the diagram canvas

4. Define a glossary to give further context

If you have ever added items to EA’s severely under-utilised glossary, you will have noticed these terms appear underlined and referenced many places within EA.

To add terms to the glossary, hit Alt + 2 or select ‘Project’ –> ‘Glossary’ from the file menu and start adding terms. (Note: you may need to add a glossary type first before you can save a anything – hit the .. and enter a glossary name!)

adding glossary terms for a richer model

I’ve gone and added a few terms to my sample glossary and now lets take a look at our scenario from before.

all terms within glossary referenced throughout the model

I should point out here that this is not limited to just the structured scenario but any field where the term is used – EA will underline the item to show a reference to a glossary item has been made.

So whenever the cursor is rolled over the underlined term – a definition is displayed!

quick referenced on cursor hover

5. Changing those scenario type names

Now the standard set of scenario types might be best practise and perfectly fine for your modelling needs – but I have found some engagements where the need to use further granularity for types. Previously this was fine before structured scenarios came along as you could name your scenario and type however you pleased but with structured comes rules.

To edit these types, Select ‘Settings’ –> ‘General Types’ from the file menu

adding scenario types to your model

and you are presented with the following screen.

default model types

This presents the default set of types which can be added to. Let’s add one called fatal exception – perhaps not a great example but it illustrates my point.

adding a custom type

Now return to our scenario view and see what this does.

new type available in the scenario list

Not much other than add a new type to dropdown. EA thinks in the main 3 types still but you can trick it into accepting your new exception type.

Drill into your alternate exception by double clicking it in the ‘entry points’ dialogue.

Try changing the type of this from it’s existing ‘Alternate’ to our new ‘Fatal Exception’.

switching over an existing exception scenario to use new type

Saves ok – great news!

So while EA will only allow you two ‘create’ the two standard sub types, you can simply swap these out for your own custom types as afterwards – semi-circumventing the process.

This may go somewhere towards getting around the ‘no alternate, alternates’ problem discussed before.

In a previous post we looked at using the de-facto standard for importing data into EA – the CSV import. Now while this method works, it is a pain and comes with the limitations of using a CSV based format – one wrong comma can throw off your entire data set!

I’ve been meaning to write about the wonders of eaDocX for a while now but it seems this is my first opportunity to sing its praises. eaDocX does away with the horrendously outdated RTF functionality that EA uses and replaces it with the new standard XML  based .docx format

In additional to the huge host of benefits from using .docx (I’ll write about them soon I promise!), the corporate edition comes with much-needed Excel integration. We can use the power of Excel to import/export data from EA without having to be constrained by CSV.

Lets take a look!

So when you have eaDocX installed, it appears as an extension.

We can select a package and open in Excel – hooray!

Open packages directly in Excel with eaDocX!

This hands the reigns over to eaDocX to take the package XML and recreate it in a .xlsx document. What does this look like? It looks an instance of Excel with all elements in your package listed

Packaged viewed within Excel

Notice the ‘Element’ listing on the left. This defines the type of element to be included, which in our example is the default ‘Package’ and ‘Requirement’ which suits our example of importing requirements quite nicely!

Click on the ‘Columns’ tab to select the attributes to display for each element.

select columns to display for the selected elements

I’ve selected a few extra columns to display for this example, namely adding the alias, description and status.

Once you’ve selected the extra columns, hit the big EA –> button to export these new columns into Excel.

adding requirement-related columns

To make changes to this and re-import is easy! Simply make the changes directly into the Excel and hit the middle button ‘EA =’ to perform a comparison on your changed data and the EA package.

making changes and performing a comparison with the EA package

I’ve gone and changed the status of some requirements to ‘Active’ and the comparison has highlighted the change cells.

To import these back into EA, you guessed it, the 3rd and final button, EA <-

If I know look at my requirements in the ‘Package Browser’ I can see all of my requirements have had their statuses updated to ‘Active’ – magic!

seeing the changes applied back into EA

A practical application of importing and re-importing

If you’ve read some of my other articles, this is the part where I say, well that’s interesting, but how is it useful? Well wait no more friend, I shall reveal.

In most organisations (unless your already deep in EA world or love your Rational Suite) the requirements are written up in either Word or Excel and have various levels of ‘document management’ applied to it to keep it maintained.

My first step in most projects is to remove the risk and import a reasonable baseline document into EA to begin building a solid model. This works well the first time, but requirements being requirements, they tend to change over time and you may not have the luxury of enforcing maintenance through EA. If that’s the case, you need a repeatable process to keep the EA requirements in sync with any externally managed ‘artifact’ (typically the ubiquitous Word document).

Providing you have a stable requirement number (I hope for at least that much!) you can always keep things maintained.

A Worked Example  – Team Foundation Server (TFS) synchronisation

I use this example for TFS but in can be applied to any external system using a reference number.

We have a lot of requirements stored in TFS and updates managed through its version history, so at any given point in time the TFS item will have the latest status and description of the requirement.

We can export the list of TFS requirements into Excel easily (handy MS product integration), but the old copy-and-paste method works just as well if an export function exist for your external system. We end up with a output something like this

an example out of TFS requirements in Excel

The title here is generally longer than this but we have a structure which is Client – Req# – Short Name so I can quickly strip out the rest to get just the Req number as above.

Now that I have something like that, I can use the power of VLOOKUP in Excel to retrieve the value of the TFS item from my eaDocX Excel version. Confused? Let me explain in pictures.

I write a VLOOKUP function to lookup the value of the requirement ID (REQ-001) and find the associated column for the TFS ID.

=VLOOKUP(B17,’Raw text’!$C$2:$G$217,1,FALSE)

If your unfamiliar with VLOOKUPS, essentially its using the value of B17 (the requirement ID), looking into the worksheet ‘Raw text’ between cells C2 and G217 for a match and returning the value in the 1st column which is a validation check to ensure the right record is return. The FALSE at the end ensures an exact match is made (not a partial)

So what happens when we do this for our data set?

VLOOKUP returning the relevant TFS tasks for each requirement

I know have a list of requirements with their corresponding TFS item # – magic!

Now VLOOKUPs can be tricky, so I add an extra validation step to the one I mentioned above – performing a simple check between the requirement ID return in the VLOOKUP and the original requirement to ensure they are the same. if not, we must be returning the wrong value.

What does this look like?

=CELL=CELL

That’s it! it will return TRUE if they match or FALSE if not. Rinse and repeat for all cells.

adding a bit of basic validation

Protip: I often use a conditional formatting rule to mark FALSE records in red to make life a bit easier.

When I’m happy everything is in order lets import back into EA.

But wait, where would I store such a value? Well this is precisely what tagged values are and should be used for.

So head to any requirement and view its tagged values.

tagged values

None? That’s okay, we need to add a new one.

adding a new tagged value for the TFS #

Don’t enter a value but give it a useful name.

Now when we return to our eaDocX Excel view, we should be able to see our tagged value in the list of available columns.

selecting the tagged value to be part of the export to excel

Look there he is!

Export a new version to Excel.

all blanks because nothing has been added yet

A column full of blanks? Excellent. Now we can add our data from the VLOOKUP before and sync it back to EA

Run the Compare function.

performing the compare

A whole column of blue changes – that’s what we want.

Hit the import function to sync these back into EA.

Back in the Package Browser we can see these changes have been applied

seeing the TFS #s in the package browser

This can be repeated for other properties such as status, development effort, assignee etc but be careful how much you use because it is additional overhead to maintain.

My motivation for keeping both TFS and EA in sync is to give the power and flexibility of using EA to model, analyse and output static documents for clients while retaining the familiar interface of TFS for the development team.

Note: It must also be repeated that when importing at scale the validation of data becomes important as it can be quite easy to accidentally overwrite things – so don’t neglect the validation checks and be sure before you commit changes!

A closing note

Hopefully that’s a clear enough explanation of how to use the functionality provided by Excel integration from Ian and the eaDocX team and I’ll be back to write-up more on the even more useful documentation generation and document management capabilities it offers – but until then this will have to suffice!

I want to share a quick guide to importing existing requirements into Enterprise Architect in order to start building traceability and management structure over your requirements.

In a lot of organisations, requirements definition takes the unsophisticated form of either a word or excel document. This is typically due to existing templates, familiarity and availability of Microsoft Office or lack of experience in alternative options.

In either case, you can take these flat formats and import them into EA with a relatively easy and repeatable process – as I will show you below.

At the least, I would expect a requirements document to have the following items per requirement statement:

• Requirement number
• Requirement definition
• Priority

• Owner

Can also include other details that you wish to track about a given element, such as category, project phase t-shirt size – it could be anything!

If the document is currently in MS Word, then copy and paste the requirements portions into Excel, and tidy up formatting as necessary until you have just the relevant requirement columns.

Set up EA CSV Import Definition

First, Create a top level container package to hold our requirements.

Select the top level item (normally ‘Model’ unless you’ve renamed it) and click the ‘New Package’ icon. Give it an appropriate name – ‘Requirements’ works for me.

Then, right click on the newly created package and select ‘Import/Export’ -> ‘CSV Import/Export’.

This will be display the CSV Import/Export window where you can select a file to import and a template to use. Seeing as we having created a template yet, we will need to do that first.

So where it says ‘Specification’ and there is a button to the right ‘Edit/New’ – click that.

Now we are on the specification page we can provide the details for our template and define the fields we want to create for our requirements.

• Fill out the Specification name and notes fields as appropriate.
• Ignore the default filename.
• Set the default direction to import
• Under default types enter: ‘requirement’. This states that every element we want to import will be a requirement element.
• Make sure the ‘Preserve hierarchy’ is unchecked (only for first import – it’s important later on when running an updated CSV back into EA!)

With me so far? Great!

Now for the available fields. This lists the standard elements and allows you to select the EA properties you wish assign from your import file.

Typically my ‘selected fields’ look this (in order):

• Name
• Alias
• Type

• Notes

optionally include other items such as

• Phase
• Priority

The order of which these are sorted is imported because this will exactly match the columns in your import spreadsheet.

So if you’re following along with my example, I had the following columns in my import file:

• Requirement number
• Requirement definition
• Priority
• Owner

So what we are doing here is a mapping from import file -> EA property.

So let’s return to our specification fields and run through each:

Name - for this I normally truncate the definition at a certain length and use that as the name, but you can write an appropriate name if you feel the need – not plausible for long lists of requirements (100+).

Tip – Use the following excel formula to truncate to 60 characters and copy and paste down the column: =LEFT(B2,60) replacing B2 with the requirement definition.

It is also important to then copy and paste the VALUES only over top so we don’t end up importing the formula into EA!

Alias - I use the requirement number for this, so switch this around so requirement #s are displayed in the 2nd column.

Type – this is the column EA will use to determine the type of element to create, so in our case they will all be requirement. copy and paste this down the column to every requirement row has the word ‘requirement’.

Notes - This is the key column which will contain the body of your requirements. You have some formatting issues if you had rich text from a word document, but its worth the time to clean this up at some point, although arguably easier to do this within EA.

The other columns for here are optional and you can pick and choose appropriate EA properties to map your other data too – do this at your discretion based on project needs.

If you can’t find an appropriate EA property, then create a tagged value and assign it to the specification

Save the specification and we are ready to import!

Importing the file with our specification

Before we can import the file into EA, we need to take our freshly re-worked excel file and save as a .CSV

Select File -> ‘Save As’ and select the CSV format.

Now back on the ‘Import/Export’ window, select the newly created specification, check the direction is ‘Import’.

Under the file, locate the import file you saved in the above step.

When you’re ready to go – hit ‘Run’. (Make sure you have closed the CSV file from the earlier step otherwise EA will throw an error saying it can’t open the file)

Success! We should now have a list of imported elements under the package you selected earlier

Stay posted for my follow up article on how to update and managed changes to requirements while retaining structure!

Hope that was helpful.