Anyone who has done code development in a team will be familiar with the idea of branching and merging. It’s a way to allow programmers to collaborate on a complicated set of code, without falling-over each other. Someone takes a copy (“branch”) of some code, modifies it, and merges it with the original copy when they are finished. Good code management systems help to see where their changes and those of others – who may have changed the same code - have caused problems, which is why branch/merge is how almost all coding teams work.

This is only important to EA modellers because it’s one of the most common requests we see from new EA users: – why can’t I do branch/merge with EA?

Up to now, the answer has been ‘because it’s hard’, and indeed a full branch/merge solution for EA would be way, WAY more complicated than one just for code, and therefore probably un-usable.

But can we get most of the benefits of a code-style branch/merge with EA, without a 100% fool-proof solution?

With EA v13 we may just have a solution: not a 100% solution, but one which has 10% of the function but which may deliver 90% of the benefits.

A real-life scenario

In a recent client engagement (details changed to protect the innocent) we had a small team of modellers (30+) working on a large but quite simply-structured model.

Let’s say they were writing Use Cases. What could be simpler?

For readers who don’t write use cases, replace ‘use case’ with your favourite EA element type (Requirement, Business Process, SysML Block – they all have the same issue).

Team #1 created:

Team #2 then produced this:

Let’s think about what Team#2 just created:

• Team #2 have re-used ‘UseCase3’ from the team 1 model (you can tell from the namespace below it). What they wanted to say was ‘we’re using UseCase3 – the exact one which the other team modelled’ – so this is perfect.
• But Team 2 also have an actor called Actor1. This doesn’t look to have been re-used from Team 1 – (clue: no namespace below it). It’s just a new Actor which happens to have the same name. So they created a new actor, called it “Actor1”, and started modelling.

Now my client spotted this one a mile away. Carrying on like this is going to cause huge problems down the road. They were predicting 80+ actors (real-life, individual roles) and if every team created their own duplicate with the same name, this would rapidly become chaos. They would lose the ability to say ‘what Use Cases does Actor1 get involved with?’ But which ‘Actor1’ are they talking about?

The “Master Elements” solution

So they did the smart thing, and created a master set of Actors, in a locked part of the model. And told teams to re-use those actors.

And replace any of their own duplicate versions of those actors with the master ones:

The Team #1 model now looked like this:

That means when we ask which Use Cases Actor1 is involved with (by the EA function ‘insert related elements'), EA tells us:

…which is the combination of team#1 and #2s models, as they are both using the same Actor instances from the common set.

Much more useful – and the best argument for ‘why EA is 1000% better than Visio’.

So, problem solved? Well not quite.

These diagrams and documents which show ‘related elements’ are useful for understanding what happening in a project, so they started creating more of them, but started to get things like this:

Now we can say this isn’t great use case practice, but it’s what happened when they enforced the ‘use the common actors’ rule. The master actors get connected to everything –

• completed use cases,
• partially completed ones,
• ... and ones which are just some ideas the modeller is playing with.

If I want to find out the use cases which really use Actor1, which have a status which means they are suitable for me to think about, then we need something in between the chaos of ‘invent your own’ and ‘always re-use’.

We need an intermediate state of ‘using Actor1’: something like – ‘I’m intending to use Actor1, but I’m not ready to tell the world what I’m doing’.

In the case of this customer – using EA12 – they had to create duplicate Actors with the same name, then, once they were happy, manually merge their ‘temporary’ and ‘reusable’ Actor1s. An alternative would be to give each Use Case a status, but this means we can’t use ‘insert related elements’ quite as simply.

So not a great solution.

Then along came v13

EA V13 has introduced the idea of ‘time-aware EA’. Looking past the rather grand title, it does provide a small amount of function which should make this problem a lot simpler.
So now, here is the same story, using EA V13.

1. The first team creates their model as before, and, as today, adds their new Actors into the ‘shared actors’ - having first checked with the model manager that they haven’t been used before.
2. The next team wants to use Actor1, but they aren’t ready to use the ‘real’ one: they will only do that once they have passed some future milestone.
   So they drop the shared ‘Actor1’ onto their diagram, then create a clone of it:
   
3. Right-click on the actor, and select ‘Clone element as new version’. Note this is EA v13 function, not available in previous versions.
   Using numeric versions doesn’t seem useful here, as EA doesn’t check for duplicate version numbers, so we suggest using the name of the team, or some other string which lets people identify why this clone is being created:
   
4. This diagram now looks like:
   
5. To see the magic which EA has done in the background, try dropping the original Actor1 back onto the diagram:
   
   EA has created a new element, with all the same characteristics as the original, but with two differences:
   - it has a ‘version’ set to ‘Team 2’:
   
   And has a <<trace>> connector back to the original Actor.

   The nature of this connection is worth explaining:   In an EA diagram, it’s a dotted-line (“dependency”) with a stereotype of <<trace>> In the EA traceability view, the connection is called “depends on” In the EA database, and in eaDocX which use the EA API, the connector type is <<trace>> Abstraction

    

6. With this simple technique, we can now have the best of both worlds:

   a. Team 2 can carry on modelling, adding whatever crazy stuff they need to add to their cloned Actor1, and ‘real’ Actor1 users won’t see it
   UNLESS

   b. Those users choose to follow the <<trace>> connector, and find whatever use cases Team 2 are working on.

   This is (fairly) easy using EITHER the EA traceability view:

   

   You just need to know that the <<trace>> connector which EA created when we cloned the Actor appears as a ‘needed by’ relationship in the traceability window. Here, there are two teams which have create clones of Actor1.

   OR

   c. Tools like eaDocX1 are OK to print ‘multi-hop relationships’ like this, in lots of different ways. For example, we can document the ‘master’ element and its related elements, then also its clones, and their related elements.

Note to Sparx Systems: Next Steps?

Now that we have this starting point, I’d like to suggest that we need some improvements to the EA UI which will allow us to go further:

• Implement a simple ‘merge’ function to move all the connectors from a back-level element to a new one. Saves me having to drop old + new onto the same diagram, with ALL their connected elements, and move the connectors one at a time from old to new.
• Better diagram filters to show/hide different versions more simply
• Associating the current ‘version’ text field with something more interesting – another EA element e.g. an Archimate Plateau, or some other project-related ‘thing’, so that we can find out ‘all things associated with version X.Y’ without having to start writing SQL
• Native EA support for the function that eaDocX lets us do already (as shown above): ‘show the clones for this element’, ‘show me what’s related to those clones’. These are now important functions, and shouldn’t need me to create a document to see them easily.

Conclusion

The V13 ‘time aware’ function is limited, but it is a start, and it does show the way to achieving what EA users have wanted for a long time – the ability to have multiple ‘versions’ of the same thing in a model at the same time.

This has many more implications for EA users, as it opens-up new ways of using EA. We can now allow teams to explore new ideas without messing-up the model for other uses, and keep track of those explorations using standard EA techniques.

A Tale of Two Cities

Four countries[1], three days, two European EA user groups. This is the EA User Group on tour, September 2015. These are my observations of the events, with hints for future attendees and organisers, and some cautionary tales.

We’ll always have Paris

Today is an unusual day. We're at an EA User Group meeting, but only as spectators. Normally, we're involved in some more active role: speaking, organising, sometimes both. But today is different. This is the 12th northern hemisphere UG meeting: two in Canada, one in USA, 4 in UK, three in Germany, one in Switzerland. And I’ve been to them all. But this is the first one mostly in a language which I stopped learning when I was 14.

It's a lovely early autumn morning in the city by the Seine. We're at the Viseo offices right by the river, just outside the centre. Guillaume Finance from Viseo is doing my presentation, so I can sit back and relax. We first-language English speakers are so lucky that the world speaks our language: I hardly ever find myself in meetings which aren’t in English, so this is a treat.
 

Had an interesting dinner last night with some of the other speakers. This is one of the perks of speaking at these events - meeting the other speakers over dinner. It’s a chance to find out what they know which they won’t talk about in a public meeting. And there are usually ways of using EA that I never dreamed about. Last night I found out about how to use EA to organise the logistics of the French sugar-beet harvest.

Today is an opportunity to look at the presentations in a new way. Since my schoolboy French is nowhere near good enough to understand what's happening, I can concentrate on looking at the pictures on the slides, observing the body language and style of the presenters, and watching the reaction of the audience.

We're not off to a great start. The first presenter arrives 10 minutes late. Not bad, given the terrible Paris traffic, but just enough to give the organisers heart-failure. Tip for anyone presenting at a UG - if you're on first, get there in time. Or bring your own para-medic. Luckily Guillaume survived.

Reading slides which aren't in my language makes me appreciate EA's diagrams so much more. Even though the text in the boxes isn't familiar, the layout and notation translate surprisingly well. At least, I think so.

But it can't translate the jokes, so I just laugh when everyone else does.

You also can't rehearse the technology too much. The presenter’s worst nightmare: the tech which worked fine last night now doesn’t when we come back after lunch: the projector is having an afternoon nap. Hasty rearrangement of schedule.

We have the eaDocX exhibition stuff setup in the lobby of the building. Jackie gets chatting to a French guy, on his way out to have a smoke. He’s nothing to do with the UG, never heard of EA. But he decides it looks interesting. I see him later at the back of Guillaume’s presentation. I wonder what he thought?

eaDocX a la Francaise

A strange sensation, to hear my own presentation delivered in another language. OK, so not exactly my presentation, but a much-improved version from Guillaume, but recognisably mine. I wonder what he's saying. Everyone seems to be listening.

I've got used to the idea of demonstrating my own software. It's as stressful as watching my own children on stage: they are my responsibility, but I’m totally out of control of their performance. And it’ll be my fault if it goes wrong.

So now I've found something even more stressful. Watching somebody else demonstrating your own software, where you don't understand what they’re saying, much less understand the questions the audience are asking. Is it going well? Are the crowd 'getting' what he's saying? I have no idea. But so far, at least the tech is behaving itself. And he's making it do much more than I normally do. He's just smarter…

At least nobody has walked out yet. Wait a minute. There's one going now. He probably has a train to catch. Maybe. They're asking questions now. I'm at the back, so I can't tell if they are happy about it or not.

Hopefully Guillaume won't ask me any questions, in any language. Hang on. Guillaume is smiling now. He seems to be happy with the way he's answering the questions. And there are lots of questions. Not sure yet if that's a good thing. At least they didn't just applaud at the end and go straight to coffee. Finally over – they do applaud, and Guillaume looks happy. Relief?

No time to hang around. Off to Gare du Nord, and the Thalys to Brussels. Exotic picnic on the move - baguettes and beer. No chance even to congratulate Guillaume and his team, which is a pity, because the organisation was faultless.

Factoid of the day: they don’t use the French language version of EA, since apparently it’s been translated by Quebecois, not Frenchman, so sounds weird to them.

Friday – it must be Belgium

Interesting chat last night with Geert and Sander (Hoogendoorn) about life, EA, and everything, over some excellent Belgian beer. Off to the venue today. Another splendid one. It really makes all the difference to a UG if there’s enough space for everyone to mingle around, and also have spaces to go and hide away for a 1:1 chat. And have lunch and coffee, and space for the sponsors exhibitions. This venue was built as hospital, never used, and is now the HQ for a Belgian trades union. Loads of space, and all very new and shiny. Just as well, as there’s a big crowd.

All talks in English today. Sander told us all about microservices. I’d not come across them before, but after an hour of listening (only an hour?), I feel like an expert. But he lied to us: he said he had 120 slides, but I’m sure he missed a few. Hardly more than 100. All great stuff.

Then straight into our presentation. Lots of technology: 2 laptops, an iPad, and a link to a server in London. This time the tech let me down: laptop decided to freeze over at the ‘ta da’ moment, which rather ruined the effect. Still, the audience were very understanding. After that some more talks. Always great to hear other people struggling with similar issues to my customers. I think potential speakers underestimate the power and usefulness of a simple ‘this is what happened to us’ story. I’m always re-assured by these, even if they might not seem interesting to the speaker themselves. We don’t need speakers to deliver research papers on super-smart bits of EA – just an interesting story is great.

The finale was Daniel from Lieber Lieber doing a talk about EA 12. Well, not exactly EA 12. More EA 12.1, which was handily (not!) released the day before. This has happened before, with EA 12 – announced the day before a UG meeting. Must be a coincidence: I don’t think Sparx HQ are that bothered about UG meetings to do it on purpose.  So Daniel bravely showed us the fruits of his 24 hours of experience with 12.1, and did a great job under the circumstances.

So that’s it – off to the airport, and back home in the small hours of Saturday. A huge thank you to the organisers: Guillaume and Geert, who despite having young families and full-time jobs, still organised two excellent events. And to their teams, and the donors of the venues, and the sponsors. We know what hard work it all is, but these are great events for making friends in the EA world, finding out new stuff, and generally joining in the growing conversation which is the EA User Group.

If you’d like help in organising your own UG meeting, don’t ask permission, just get started. We have lots of help and advice available – contact This email address is being protected from spambots. You need JavaScript enabled to view it. for her cheat-sheet, filled with the learnings from the 12 meetings we’ve been involved with. Here’s to the next one!

This tutorial is about a strange corner of UML - and of EA - which you may have noticed, but perhaps not used.

But it's one which has a surprising power to make your models easier to understand and to manage, AND which can deliver new insights to your stakeholders.

Instance Classifier

The Instance Classifier relationship has a special status in EA, but it's special in a way we can use to our advantage, without necessarily knowing what it means in deep UML-speak (which is beyond both the scope of this article, and the authors knowledge).

If you come across the idea at all, it will be where you have drag/dropped a Class onto a diagram, then, when EA asks you do you want a 'link' (i.e. the Class itself) or an 'Instance', you choose 'Instance'.

 EA will then associate the new instance with the Class it came from. And this is where the strangeness begins. 

For a start, the relationship between the new instance (object) and it's Class is not implemented as a Connector - that is, as a line on a diagram. It's a special relationship, which is hard-coded into the EA data model. More important, in UML and in EA, any Element can have another element as its 'Classifier'.

It seems likely that was originally intended just to allow an instance of a Class (and Object) to be connected to its Class. Very sensible. But we can also use this 'special' relationship for other purposes. But first let's look at how this special relationship gets handled by EA.

The diagram above shows two classes, and two objects. But the Object Elements don't have any relationship to the classes.  These were created as new Objects directly, not by dragging/dropping the Class and selecting 'instance'. They are just disembodied instances of some un-specified class, and so not very meaningful.

In the diagram above, we've create Instance#1 as an instance of Class3: you can see that by the name of the Class appearing after the name of the instance, in proper UML style. Instance#1 : Class3

So Instance#1 isn't just some random instance: it's an instance of Class3.

But notice that there is still no connector shown on the diagram: it's the ":Class3" which tells us there is an 'Instance Classifier' relationship between the two.

But there's more..

We have the Knowledge

Showing it

Seven ways to organise your EA models so that other people can understand them

Ian Mitchell, ian@eaDocX.com

• If you have spent many hours creating a great EA Model, hopefully you want the rest of your organisation to use it as well. But how can you make it readable?
• Or maybe have you just picked-up a model which you created a few years back, only to be baffled by your own work. What exactly was this model all about, and where has all that great stuff gone ?
• Or perhaps you’ve inherited a model from someone else who isn’t available to tell you what’s in it. How are you supposed to sort out what’s complete and useful, from the ‘other stuff’?

Over the years, we’ve come across all of these several times, and have developed a few tricks to avoid them.

If you have more techniques for helping other people to understand your models, please email Ian at eaDocX dot com.

1         A Package is not a Bucket

The most important ‘thing’ in Enterprise Architect is definitely the Package. It’s also the simplest. Just a folder with stuff in it, right?

Wrong.

The Package or rather the family of Packages which you create, say more about your model than anything else. If you just use them as a bucket to put things, then you’re missing-out on a critical way to communicate the intent of your model.

Some rules for Packages:

• Sensible names. It may seem amusing to call a package ‘new stuff’, but nobody else will ever look there to find anything. If it’s ‘new stuff which was invented in the meeting..’ then call it that. 
• Descriptions. A Package without a description isn’t just half-dressed, it’s practically naked. There is always something you can say about what’s in the package, where it came from, whether it’s finished or not.
  I suggest that anyone who creates a package in a shared model and doesn’t add a description should buy the coffees for all of next week.

• Authors. Enterprise Architect will make the Author of the Package the person who created it. But go further, and make the Author the Owner of the information in it. So, even if someone is totally confused at what’s in the package, they can always email the author…

2       Notes, notes, notes

I’ve been teaching UML and other modelling techniques for more than 15 years, so apologies to all former students for repeating this. If you’re in that select group, can you remember the most important UML (or BPMN, or SysML..) modelling construct ?

The Note.

The humble note.

They don’t cost anything, they never run out, and they can communicate more about whyyour diagrams look the way they do than anything else.

Add them to elements, to links, to anywhere you can think of. But make sure to keep them up-to-date: a diagram with misleading notes is worse than one with no notes at all.

3       Single-purpose Packages

If you’re going to follow the rules above, and describe what’s inside each package, then having one, or a small number, of different types of ‘thing’ in a folder is sensible: it’s easier to find things, and easier to write a quick description.

This also becomes important if you are going to document your model using a document generator – either RTF or eaDocX.

A Package with one type of thing in it can be documented as a simple table, with the Package name becoming a title for the table.

4       Different things get different stereotypes

The idea of the Stereotype is one of the key ideas of UML, which EA has extended to cover all the other model types it supports. So whether you’re creating SysML diagrams, BPMN business processes or Use Cases, you can use stereotypes.

So use them.

A stereotype is just a ‘special kind of’ thing. So if you have use cases which are sometimes complete (all scenarios filled-in) then make them <<fully dressed>>Use Cases, or if not <<partially dressed>> . So a reader finding one of these will know whether it will be completed or not: they know what to expect.

The same can be true of any other element. Using a stereotype can tell your readers what they are looking at.

Stereotyping also makes it easier for documentation tools like eaDocX to change how they format their outputs. For example, a <<fully dressed>> Use Case should print its scenarios, and highlight where they are missing – that’s an error. But <<partially dressed>>Use Cases don’t need to.

5        Status is everything, or Somewhere to Play

When you read a model, probably the most common problem is that you don’t know what the status of something is: a diagram, an element, or a whole package of the model.

Is this completed, signed-off and implemented, or just some ideas I had over coffee one day?

So using the EA ‘Status’ fields (with some sensible values) is really, really useful to readers.

Why not have an area of the model which is just a sandpit? Somewhere where modellers can try things out, and to which no standards apply. Readers are not encouraged to look in these packages. Everything is work-in-progress or incomplete.

Equally, the areas which are for ‘real’ content DO obey all the local rules: packages must have descriptions, only the approved stereotypes are used etc.

6       Public and Private diagrams

The great power of EA is that it allows us to create links between all kinds of elements, depending on what kind of problem we’re trying to solve.

There are several ways to create these links: the Relationship Matrix is a quick way, but diagrams are also very common. And this creates a problem for the reader.

Are they looking a ‘proper’ diagram, which they are supposed to understand, or is this a diagram which you just created to establish some relationships, and isn’t really for public use?

So get used to naming diagrams so that this is obvious, and to prevent accidental printing of these diagrams in documents.

Pick a naming convention for ‘do not print’ documents: we add ‘hidden’ in front of the document name. We’d like to use a diagram stereotype, but that doesn’t appear in the Project Browser. So ‘My untidy diagram’ becomes: ‘Hidden – my untidy diagram’. We also tick the box in the diagram properties to “Exclude image from RTF Documents”. Both the EA RTF generator and eaDocX will take this to mean ‘don’t print in any document’.

So now you’re free to create as many untidy diagrams as you like, and readers will know to ignore them.

7        Pick a meta-model, write it down, and stick to it

This final piece of advice is really a summary of all the others.

Each idea we’ve discussed above contributes to your meta-model.

If that sounds like a scary, super-technical idea, it isn’t.

All of your EA models already have a meta-model, whether you know it or not. The meta-model just says what kinds of ‘stuff’ is in your model.

• What kinds of elements have you used? e.g Requirements and Use Cases, but not internal requirements,
• How have you linked them together?  
• What stereotypes have you used, and what does each one mean?
• How have you used things like Element Tests, the Glossary, or Project Tasks?

..so not really complicated. The meta-model is just your local modelling standards.

If you want to find out what your meta-model is, use the eaDocX Model Expert. It will draw a diagram of all the element types, stereotypes and links in your model. Be prepared for a surprise! Big models can be complicated!

This is a good reason to make your meta-model clear and simple. Pick a small number of elements, stereotypes and links, and use them consistently.

Communicating the meta-model is critical: one which only you understand is no use. It MUST be written down, preferably in the model itself, and taught to all of your team.

AND kept up-to-date, as your modelling style evolves, as it will certainly do.

At the end of a dark tunnel, in a quiet corner of industrial London, we gathered at secret location. From the outside, it looked like a set from a 60's spy film. Deserted railway sidings, occasional glimpses of shadowy figures in the distance.

But inside and anonymous shed, it was more like the Starship Enterprise. Shiny hi-tech, bright lights and the largest tube map ever seen.

 It was the second Sparx System Enterprise Architect European User Group meeting, Wednesday 15th May 2013, Transport for London training centre.

 More than 100 delegates, from 50 companies and organisations in 8 countries met to share ideas and experiences and to get to know other EA users.

"It was worth coming just for the discussion I had before even the first speaker started" one delegate told me. "And I've got the rest of day!" she added.

Jackie Mitchell, Programme Manager for the event and CEO of sponsors eaDocX opened the session.

 "This is probably the largest collection of Sparx EA talent ever assembled". And it probably was.

 Doug Rosenberg opened the session with talk on using - or rather not using - Agile for large projects. How much Agility would you like, when your life depends on the software working correctly?

We then split into 3 parallel sessions, with talks on SysML & BPMN, Use Cases and MDGs, EA Navigator and Analyser Workbench, but mostly tales of how different people have used EA. There were stories of project triumphs, a few minor disasters, but these quickly because learning points, and mostly lots of discussions over coffee.

Some stars of the worldwide EA community were among the speakers. Geert (When do I find time to sleep) Bellekens, undisputed champion of the Sparx user forum, gave two talks. The first on his EA Navigator extension, and the second on his current project experiences on a huge, multi-language EA model, and showed why tools like EA Navigator can help when things get complicated.

Peter (50 EA Tricks) Doomen, gave up his birthday to share even more tricks. How many more does he have? Will he ever run out ? I saw some hard-core EA experts sitting at the back of his session taking furious notes.

 Jackie Mitchell illustrated her talk on EA for Project Managers by describing some great project failures, and how EA could have helped avoid them. She didn't suggest that Project managers had to be EA users, but showed how our EA information can help them run better projects. 

Phil Chudley from sponsors Dunstan Thomas dazzled us with both his boundless energy and his encyclopaedic knowledge of EA, with his talk on EA & BPMN. So much good stuff, I'm going to have to go over that one more slowly offline...

Roman Bretz, came all the way from Nuremberg  from another sponsor LieberLieber, and started by encouraging us to think about using languages that our customers can understand – Russian, German, English, UML, SysML, he had them all covered – before describing his work with executable models.

Ian Mitchell from eaDocX, did two sessions: the first one on using the EA Structured Scenario editor for use cases. Despite falling off the stage at one point, Ian kept his cool and thinks he managed to introduce some Hidden Gems that even Peter D. hadn’t seen before.

Ian’s second talk described his experiences on a large telecoms project. “How to do less work, have more fun and become (a bit) famous doing it” was a subject that ticked a lot of boxes with the audience.

Daniel Siegl, also from LieberLieber explored how EA can be used as a fully-functional development environment, with debugging and everything! He also let split that Sparx, keen to 'eat their own dogfood', not ONLY use EA to do their development: not just the analysis and design, but the code & test as well !

Knut Paulsen, from Evry, described how he and his team have implemented EA over several years in their organisation, writing customisations and supporting user groups in various roles and functions across Norway.

And finally Paul Hewitt from Visure Solutions (our final Sponsor) showed how integrating EA with Visure brings requirements lifecycle management capability to projects.

All in all, a great day - I wished I could have spoken to more people, as everyone seemed to have an interesting story to tell.

If you'd like to get involved with running an EA USer Group meeting near you, then please contact us via eausergroup.com. There's already talk about meetings in Belgium, France, Nordics and New York

Ian Mitchell, Bath, UK.

Colouring your EA models isn't just a matter of making your diagrams pretty. Colour can add clarity and accuracy to your models, and make it easier for the consumers of you knowledge to understand what you mean. 

This paper reviews some of the ways you can use colour, to show structure and status in your EA Models, and provide guidance and insight for specific groups of users.