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, from the ‘Element’ file menu, select ‘Scenarios and Rules’

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.

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!

If you recall the previous article, I walked through the process of setting up ‘Triggers’ to run scenarios through your state machine and set simulation variables at state or sub-state level to better represent your application. All of this information was available using the EA ‘variables’ or recording to the Console. We can go a step further and prototype a quick UI to represent our application and/or provide a ‘dashboard’ view of states and variables.

Setting up the state machine

the state machine from the previous post

Using the state machine I used last time, we need to create a place-holder ‘state machine’ element so we can reference it as a simulation start point.

Add a ‘User  Interface’ diagram to the appropriate place in the package browser.

add a user interface to the diagram

This will be our place-holder to put the state machine and User Interface elements.

On the diagram create a new state machine element.

create a new state machine element

Then right-click the newly created element and select your existing state machine diagram we created in the previous example.

select a composite state diagram

Locate the state machine diagram in the package browser.

Locate the state machine in the package browser

Now we can create a new User Interface diagram and add that as a frame on to the current diagram (keeps it neater and modular).

add another UI element on drag into onto the master canvas

And drag that on to the Model Default (or whatever you named the original) diagram canvas.

To complete the process of linking a UI to a simulation, we want to open the Execution Analyser and create a script. If you don’t have the window open, select ‘Analyzer’ – ‘Execution Analyzer’ to bring it back up

Show the Execution Analyzer

From the Execution Analyzer window, select to add a new script

Add a new simulation script to the Execution Analyzer

And they key step for us is the last tab, ‘Simulation’ and defining the ‘Entry Point’ and Input behaviour.

Select the ‘..’ icon to locate your state machine element for the Entry Point.

Define a state machine to be the simulation entry point

That sets the entry diagram we want to use for the simulation.

To connect the User Interface to the simulation, we need to define a behaviour (in JavaScript notation) to display the correct UI element.

The format of this command is as follows:

dialog.CreateOrder.Show = True;

where ‘CreateOrder’ is the name of User Interface we created earlier (‘CreateOrder’ in my example above).

As you may have guessed from the above JavaScript, the model simulation script will start the simulation on the ‘Validate Example’ state machine and as it’s first point of business, it will display the ‘CreateOrder’ User Interface we created.

Note: Another method of displaying the UI is to assign the same command (above) to the first transition of the state diagram (e.g. Initial –> Created in my example). Whichever method works for you!

Creating the UI and assigning actions to things!

So now we have a model simulation that will give us an actual rendered screen we should probably put something on it!

Open up the CreateOrder User Interface  we created earlier and lets start adding elements.

Using the Toolbox you can add standard UI elements or use the Win32 elements to add things onto your prototype. Here is a horridly rushed example of some text and a button (note the list of Win32 UI control types in the toolbox)

building a basic user interface

So now I’ve added a UI to the model and hooked it up using a simulation script, what happens if I run it? Well let see.

Going to back to the ‘Execution Analyzer’, right click the script and select ‘Start Simulation’

start the model simulation from the execution analyzer

What do we get?

example rendered UI element during a simulation

A ‘nicely’ rendered (I use the term nicely loosely of course!) dialog box that we mocked up but the button doesn’t do anything – lets fix that!

Adding Signal behaviours to Button and making our UI interactive

Head back to our CreateModel user interface and view the properties of the ‘No More Items’ button. On the ‘tagged values’ tab we want to add a new tagged value.

creating an OnClick action for the button

The naming of this tagged value is very specific and must always be named ‘OnClick’ with the following value ‘BroadcastSignal(“ “)

defining the trigger to use for the button

When the simulation is interpreted, EA will parse the above tagged value as a JavaScript function and attempt to fire the trigger “Signal Name”. So what we were doing before manually using the ‘Simulation events’ and ‘Waiting Triggers’ window in EA, we can no build into our interactive prototype to reasonable something more alike our application!

It is important to note that the trigger type must be ‘Signal’ for this to work. To check this, return to our state machine and find an appropriate transition. In my example we are using a button called ‘No more items’ which corresponds to following transition on my state machine.

locating the appropriate trigger

Bringing up the properties of this transition will allow me to view the Triggers associated with it.

checking the trigger type of the transition

Notice the type is ‘Signal’. Had this been one of the other trigger types our simulation would not register the event.

So when we run the simulation again, we can actually use the button on the UI to progress the simulation.

simulation before clicking the rendered button

Selecting the button progresses us further into the state machine as if we had used the ‘waiting triggers’ window in the bottom right of my example.

simulation progressed after selecting the rendered button

So you’ve now added some interesting tricks to your model but at this point you still might be thinking – “that’s all very well, but that isn’t all that useful to me”. Well the initial driver for me to head down this path wasn’t to create a prototype application based on my state machine but was in fact to provide a better view of the variables and states I was assigning throughout my model.

Introducing the Model Simulation Dashboard!

So go along with my very basic prototype I built an even simpler dashboard view which sits along side the prototype and displays the variable states (as recorded in the EA ‘Locals’ window) and any additional info I want to record in my simulation.

To this all I do is create a second UI diagram, and call this at the first transition (from Initial –> Created in my example)

linking a second UI for a ‘dashboard’ type view

dialog.Screen1.Show=true;
dialog.CreateOrder.Show=true;

In the above example, Screen1 (horribly named I know!) is my dashboard view and CreateOrder is the first UI screen from our example above.

What does that look like?

example of dashboard view alongside the running prototype

I have my dashboard running alongside my UI screens to give an alternative view of things I need to track at any given time.

Protip: You can change the stereotype of a Screen element to be a Win32Dialog and get additional properties, such as setting the window to be in the centre – very useful when using multiple Screens.

Protip: adding a centre position property to the screen element

All done!

Well thats the basics covered of adding a prototype UI to your model simulations and if there is further interest I can share some tips on making a more dynamic prototype in EA, hiding elements until required – but I shall save that for another day.

Hope that was useful to someone!

I had seen a demo on model simulation but the focus was more on a generated model from source rather than a hand fashioned UML model. This post is a walk through on the process and hopefully some takeaways from what I’ve learned.

Understanding complex systems

I came into a project that is well down the road to completion but sorely lacking in any concrete documentation which was becoming a pain point for everyone – and particularly for me – the new analyst tasked with helping out.

One of my first tasks was to document some ‘light’ form of a state model to get an idea of all of the possible scenarios and break down some of the complexity. I’ve iterated through several versions (or styles) of the state model trying to provide a simpler view of states and state transitions but the model was just very complicated and the diagrams were too busy. Understanding it myself was hard enough and trying to validate each of the scenarios was proving far too time-consuming.

States and multiple sub-states – too many paths!

My main problem was due to having states and multiple sub-states being dependent on single transitions. For example, we had something like this

OBJECT (super state life-cycle)

– sub item1 (sub state life-cycle)

– sub item2 (sub state life-cycle)

– shipping item (sub state life-cycle)

– other items (sub state life-cycle)

So for every transition, we could have movements of one or all of the sub-states, and depending on what states they were in, we could also have super-state changes.

example of super-state / sub-state model I quickly threw together to serve as an example

A threw together a quick example of what things (sort of!) looked like in our world – its a horribly rushed example but gets across the point.

Model simulation and simulation variables!

So I got to the point where I’d modelled enough states and sub-states that it was very difficult to validate the accuracy – so I decided to use a bit of smarts and try out model simulation.

I setup my workspace to get the simulation controls ready. It looks somewhat like this.

the simulation workspace configured to show variables, triggers and simulation console

With this setup we can kick off model simulations to run through transitions, select the required ‘trigger’ to choose paths and even save triggers to define pre-defined scenarios to run through. Note: I’ll post a separate article on how to do each step in more detail.

All of this is nothing new? Well that’s get into some simulation variables to track what’s going on at each point.

First of all, I’ve run through a created scenario manually (interpreted in EA language) by manually selecting the triggers as they come up. You can then save these as a trigger set and select to signal the triggers automatically – now we can fly through our models after defining our criteria.

model simulation in progress

The above shows a simulation in action as it goes through the path I defined manually and you can see the trigger sequence waiting to be fired to progress the simulation further.

showing the simulation console and ‘waiting triggers’ panel

What I end up at the end is a list of states / decisions / elements that I have passed through in the console log and a list of triggers that were fired.

For me this wasn’t all that useful – just a flat list of states and sub-states at a single level wasn’t;t really enough – plus there was more detail I wanted to capture that would make these even more useful.

Enter simulation variables

I stumbled on simulation variables when trawling through some EA help file about getting my simulations to work and instantly through of a use (more on that soon).

Given I am reverse engineering a model and not trying to do and model-driven development, I feel I can use simulation in this way but I certainly appreciate this is a hack job and not their intended purpose (sorry everyone!).

I added an operation to each state called ‘updateVars’ and added a behaviour to each to assign simple variable.

adding JavaScript simulation variables to add another layer of interactivity

EA uses JavaScript notation when performing UML model simulations, so we can just assign variables as we need them. Now you see why I had the variable window open before right?

Protip: To avoid cluttering up your diagram with all your updateVars on each state element – hide the operations from the diagram in the diagram properties. Un-tick the ‘Operations’ box under Show Compartments.

Protip – hide your operations from your state machine diagram to avoid clutter

So now that I have added simulation variables to my model, I can see what the states and sub-states are at any given point in the model – either by pausing or setting simulation break points (another great feature!).

example of paused simulation showing variables and waiting triggers

Writing to simulation console

Although simulation variables were interesting they didn’t really offer me much over what I had before – just a different way of viewing the same state/substate information. What I really wanted was to be able to use this concept to show other important things that are going on at certain steps.

Another cool feature Sparx have included here is being about to output to the simulation console so you can supplement the standard list of element names with your own text.

So at certain steps, I have UI actions or account deductions, that I wanted to bring into my model and highlight to my stakeholders where and when these were actually occurring. Strictly nothing to do with a state machine but I’m not here to win UML medals – just provide my stakeholders something they can understand!

So on one of the updateVars actions I can add another line like this:

adding extra information to the console log

The magic words here are Trace() which allow you to output a string to the console log. What does it look like in the simulation console? I’m glad you asked – it looks something like this.

seeing the Trace() output onto the simulation console

I ended up adding custom Trace() events for each state so I could better represent state /sub state movements and also record important events along the model.

Hopefully you followed along with me on this and I’ve had some interest regarding doing a screencast on the topic so please let me know in the comments if you’re interested and I’ll get one together.

This was an overview article to demonstrate the main features and I will come back and go through some of the steps I rushed through in more detail in the next post.

EA works by generating RTF documents of its content which many users prefer of the more interactive HTML renderings of that same content – either due to habit or function. While EA has countless benefits for analysis (just read this blog for many examples!) it doesn’t provide document versioning / differencing out of the box.

This is no problem at all since MS Word has all the differencing functionality we need to provide that same level of ‘track changes’ that we have all come to depend on (or hate!).

Lets define a scenario to frame our example:

The example scenario

Ok – so you generated a use case document from EA (Enquiry Use Case v0.1 rtf) and sent it around for an internal review the previous week and have been updating the EA model with the required changes. All of the feedback has been incorporated into the model and you proceed to generate a new version, this time calling it Enquiry Use Case v0.2.rtf.

So we now have two documents. The v0.2 document contains our updates but doesn’t contain any mark-up to distinguish what has changed which will annoy our reviewing stakeholders.

So what do we do? We turn to the powerful ‘compare’ functionality built into Microsoft Word of course!

In either word document, select the ‘Review’ tab on the ribbon, select to ‘Compare’ button and the ‘Compare’ button again.

Select the Word Compare function

Now we are presented with the comparison options that Word will use when parsing each document.

Word compare options

Original document – locate the v0.1 document

Revised document – locate the v0.2 document

Select the ‘More >>’ button to see further options

Ensure ‘Tables’ is ticked if your RTF template is set up to format using tables

Ensure ‘Show Changes in:’ option is set to New document

Ready? Hit ‘OK’ to generate a new document with the marked changes

example of generated comparison document

We now have a tracked changes displayed for two separately generated documents.

Whats the SharePoint connection? well..

SharePoint for document management

Maintaining document versions is a pain, especially when following a method of manually producing document change sets as above, so using SharePoint makes this a little easier.

Office’s built in SharePoint integration means we can overwrite our previous version with our newly generated model and let SharePoint handle the pain of version tracking.

CAVEAT: This only works when the document library settings for SharePoint are configured to force versioning (Document Library Settings -> Versioning Settings )

document library versioning settings

Make sure ‘Create major and minor (draft) versions’ is checked and

‘Require documents to be checked out before they can be edited? is set to ‘Yes’.

If you don’t have permissions to set the above, contact your SharePoint administrator and they can enable this specifically for the SharePoint document library that you are using.

With versioning configured, rather than saving locally and making sure we rename versions appropriately, we can simply save over the top of the existing version.

Save directly to SharePoint from Word

Select or type a ‘SharePoint’ in the dialogue and locate the existing document. It will prompt if you want to overwrite the existing document – confirm this and we are done.

We have overwritten the current version only and we can easily roll back to any previous as required – no messing around with file naming conventions, multiple documents sources and all the pains that exist without document management.

When we have multiple versions, Word gives us an added feature that we can use for our document comparing advantage.

All previous versions are accessible directly from Word (or any Office app).

We also get an added bonus feature under the ‘Compare’ function we demonstrated earlier.

compare specific version options when working from SharePoint document

Here we get the Major and Last Version options again but we also get the Specific Version option which allows to select ANY version – useful when you’ve updated several minor versions.

Now you should have one less reason not to use EA and few handy SharePoint document management tips to boot!

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.

Lets take a look at the standard project structure when we create a new EA project

Select ‘File’ -> ‘New Project’ and enter a file name and location for your project

Then select the type of model you wish to create for the purposes of this demo I’ve gone with ‘Requirements’ and ‘Use Case’

You should now have a blank project from which to build your model.

On your right (if you haven’t moved things around) you should be able see the (empty) project browser window.

You are presented with a blank model, with the first (root) element of the project named ‘Model’. If it helps, you can rename this element to something more appropriate, such as the name of the project, or stream of work.

At this point, think of the project browser as a form of folder structure where the ‘Model’ element is the C: drive and you will begin to create ‘packages’ under it to organise your work.

Tip: If you can’t see the project browser, hit ‘Alt + 0′ or ‘View’ -> Project ‘Browser’ from the file menu.

So now we want to build out some structure to the form the skeleton of our model. This will help guide users both viewing and adding to the model, and help when we move on to working with the document templates later on.

If you recall we selected this project  to be a ‘requirements and a use case model,’ so we now want to create a container package for each of these. So go ahead and make two packages, ‘Requirements Model’ and ‘Use Case Model’ under the ‘Model’ element.

To do this, make sure the ‘Model’ element is selected and click the small ‘folder’ icon on the project browser toolbar.

This will pop up a window to create a new view and ask to select a type. This really only affects the type of icons used for the package, but go ahead and select ‘Use Case’.

When you have added both packages, you should see something like the below image.

Note: The two package icons are different as I selected the ‘simple’ view icon for the requirements model package

There is another option here to create a package from a wizard – this may help your understanding of how to structure your models as it creates a number of elements by default.

To create a model from a wizard, right click the root element ‘Model’, and select the appropriately named ‘Add a New Model using Wizard’ option.

We are presented with the same window as earlier when we created a new project.

If you select ‘Use Case’ here and hit ‘OK’, it will go ahead and create another package named ‘Use Case Model’, this time with some pre-created elements thrown in to boot. Let’s go ahead and look at what its created.

Here you can see the elements generated by the wizard – a sample use case diagram, a package each for actors and use cases and same sample elements.

The generated use case diagram gives some explanatory text on what each element does and how it relates to other UML elements.

We can either start with this model and edit the generated elements or just start from scratch. For clarity, lets start from scratch by deleting the generated diagram and retaining the generated elements (Packages, Actors and Use Cases)

Right click the ‘Use Case Model’ diagram and select ‘Delete Use Case Model’

Now ensuring we have the ‘Use Case Model’ package currently selected, select the ‘New Diagram’ button within the project browser

EA will then bring up the new diagram dialog where you can select a type of diagram to create and prompt for a diagram name.

In the example below I have named it ‘Search for books’

So what does this have to do with project structure? Documentation in EA centres around having a well organised model therefore allowing the flexibility to generate documentation at the required level – either at the micro or macro level.

By containing our various elements within packages, appropriately structured and named, we can quickly generate highly specified, focused documentation or higher-level, broader documentation without the hassle of manually adding or removing content after generation.

Let’s build up our sample model a little more to represent what you would actually use.

Here I have added 5 ‘root’ packages that contain distinctly different models:

• Requirements – to hold the all important requirements model
• Use Cases – to hold the use case/user story expansions to met the requirements laid out in the requirements package
• Domain Model – a conceptual data modelling area to map out the data model. Can and should be supplemented with a a logical (physical data model as system is developed)
• State Transition Model – a later-stage model but important when rest of the model matures and complexities arise. Particularly useful when reverse engineering a system

The reasons for why this is important may not be immediately clear but should make more sense when it comes time to generate documentation from our model. More on that in my next article! In the mean time, happy building!

2012 was the year of me – largely spent travelling extensively in South America and then moving from Australia to London.

2013 the focus goes back  to work and bringing the blog back to life.

So at a high level, the goals:

• dust off the blog – change focus of blog to more general me and my work rather than the current ‘business analysed’ theme.
• the 750 words challenge – writing daily, even if not published
• publish the using EA series of articles
• publish thoughts on agile analysis
• publish thoughts on project ideas
• play more with ruby and js frameworks
• more focused/less-distracted work patterns
• travel more.. (continental Europe)

More on these later and am improved skin.

This article is intended to be supplementary to the provided Ariba documentation on the provided relay code (specifically the IIS-ASP relay) and based on my own experience of trawling through the code and hacking it into place.

The Ariba diagram

The above diagram is supplied by Ariba in the Remote Authentication Kit – Design Overview.doc

It explains the basic flow between the various components to authenticate a user in Ariba. The purpose of this post is not to re-iterate what is shown in the diagram but to dive further down into the workings of the relay for debugging and personal-sanity related reasons.

My Diagram – explains the various query string parameters of each hop

I believe there are two parts of the relay that aren’t well documented or explained. The first being how to encryption / decryption of challenge key works and secondly the details of the values being passed back and forward from the relay to Ariba. This might be stating the obvious for those who have worked with SSO and encryption methods before, but it wasn’t for me and I’m guessing it may be useful for someone else down the line also.

Setting up the relay and how the encryption works

The provided relay is a single page that retrieves the current user, encrypts a key sent from Ariba and sends them both (username and encrypted key) back to Ariba for authentication.

So lets back up a bit here – challenge key? Encryption what?

The keys – Public and Private Keys

I’m not going to get into the detail of public/private key architecture, but the provided solution provides a ‘keys\’ folder which contains two sample keys, public.pem and private.pem, along with a genkeys.bat batch file which will create fresh keys into these files (a compulsory step if not done already).

The private key is the one we hold dearly, and the relay page has a configuration line which directs to the location of that private.pem keyfile. It looks like this:

PrivKey = ConfigPath & “D:\pathto\keyfile\private.pem”

In my case, my integration server’s permissions were locked down too tightly and the application did not have access to read this file, and hence the solution did not work. In my experience, this is the single biggest cause of failure of the relay – not having appropriate permission to access the private key file or a mis-configured path in the above line and someone moves the key during deployment.

So what does the relay page do with the keys?

The query string and it’s parameters

Well to protect the integrity of the transaction and stop hijacked sessions, when the user first enters the Ariba URL they are taken to the Ariba portal, and if SSO is configured for that realm, the user is again bounced back to the SSO relay address configured (see above diagram – Hop #2). During this second hop, a unique challenge key is generated and returned to relay as a query string parameter.

This is shown as &key= in my diagram above.

The relay then retrieves the currently authenticated user (depending on your IIS configuration, but using integrated authentication is the best method) and stores that in another query string parameter &user=

This is the value that Ariba will use to match against a user record and provide access into the application.

The private key is used to encrypt a combination of the user and the challenge key given by Ariba, into a single encrypted value and return that to Ariba. No snooping users can decrypt the contents of that string because they are not in possession of the matching public key. This public key is configured in Ariba in order to decrypt the return values and authenticate the request and its integrity.

The user is then bounced back (3rd and final hop) with these details, &user= and &sig=, containing the current user and encrypted digital signature respectively. Ariba takes verifies the value of &sig= by decrypting it with the value given in the public string.

The encryption process in more detail – an optional dive into what is happening

As hinted in the title, this section is entirely optional and is intended to dive into the process of encrypting / decrypting the username and challenge key – specifically the how and the why and ways of trouble shooting when things don’t go so smoothly.

As explained above, the relay page encrypts the combined values of the Ariba-generated challenge key and the username of the logged in user. It does this encryption using the industry standard encryption toolkit, OpenSSL, using the pre-compiled Windows 32 distribution which includes openssl.exe (available here).

A line in the relay page defines the bath to openssl.exe, in a similar manner to the private.pem key file explained above:

OpenSSL= “D:\bin\openssl ”

So looking further down into the relay page code, the OpenSSL variable is called twice:

set oExec = WshShell.Exec(OpenSSL & “dgst -sha1 –sign “D:\keyfile\private.pem”)
oExec.StdIn.Write key & username
oExec.StdIn.Close
signature = oExec.StdOut.ReadAll()

Here the openssl.exe binary is called with the parameters “dgst –sha1” encode with a sha1 algorithm and “-sign” using the private key value of “D:\keyfile\private.pem”). It then sends the values of key (ariba generated challenge key) and username (value of currently authenticated user) and returns the encrypted version to the value of  “signature’”

The next block then encrypts the value of signature with another call to OpenSSL (so another call of openssl.exe) with the parameters of ” enc -base64″) to encode it into base64. This value is then stored into the variable “sigEncode”.

Finally this value, sigEncode returned to Ariba as a query string (value of &sig=” “), where Ariba uses the SSO configuration value stored for the realm’s public key.

Testing the process – the provided test pages

Fortunately Ariba have provided to test simulation pages in the \LoginTest\ folder to simulate both sides of the Ariba handshake. Providing the configuration values for authURI, OpenSSL and PubKey are correct in both login.asp and login_verify.asp, these pages can be utilised to simulate Ariba connections without having the configure SSO options within Ariba. This proves a useful mechanism that the relay page is functioning as intended before touching production settings.

Hopefully some of the above content was useful, if nothing else it provides a useful reference of my own learnings if I ever need to deploy the relay page again!

With this in mind, I started playing around with Django (I’d been toying with Python and natural language processing so Django was a natural extension) and then gave Rails a shot after hearing people buzzing about it for a few years.

“I came for rails but I stayed for Ruby”

I heard this phrase many times when reading through the mountains of posts on the subject and it couldn’t be more accurate. Like I said earlier, I’m not a developer but I can read and make vague sense of most mainstream languages but I have never seen anything so intuitive and obvious as Ruby. The syntax is clear, it doesn’t contain a lot of onerous escaping semi-colons or braces, or use excessive indenting, it just reads so cleanly. Conventions like using question marks (empty?) just make so much sense and makes reading and writing Ruby so easy.

Up and running with a new Rails app in 5 minutes

It really is incredibly easy to create a basic skeleton app in 5 minutes (assuming you have an environment setup already – which is max 30 minutes anyway!). Using generators and gems like awesome twitter-bootstrap gets you not just a basic skeleton but also an incredibly functional UI framework ready to build upon (I love you twitter-bootstrap!).

Less focus on arduous scaffolding, more time to prototype!

For me, the beauty of Rails is being able to quickly mock-up up an idea without spending several hours building the scaffolding before I can put in anything useful. I can draw a quick data model and a few UI sketches on paper and translate this into Rails in under 30 minutes to get my idea out of my head and into something *real*.

I’ve tried in the past to transpose my ideas in different ways, sketching UIs on paper, building PowerPoint/Prezi presentations of key concepts, Balsamiq mock-ups and stream-of-conscious sessions into text files, but they never went anywhere because they were always abstract – there was no ‘easy’ step to transition to something real. I’d always get lost / sidetracked choosing platforms, technology stacks and eventually find myself looking at a detailed jQuery library on some low-level UI element that probably had nothing to do with my app in the first place.

Something tangible, something flexible

Rails gives you powerful tools to get something out quickly and then build upon with a robust toolset (RSpec, Cucumber) to ensure you aren’t cutting corners and allows your 10 minute prototype can transition into a robust application.

Sure there is a learning curve, but its the easiest of the bunch (IMO) powered by a beautiful language and backed by a vibrant and vocal community.

Let the ideas flow…

With that said, lets see if any of my half-baked ideas eventuate into anything other than personal playgrounds – Github be ware, I feel a large amount of commits coming from this ‘non-developer’..

By definition, the title ‘business analyst’ is very vague and naturally differs significantly depending on the context, corporate environment and personalities involved. I meet a lot of people who call themselves business analysts but really have no formal ‘analysis’ skills, would stare blankly when you asked them what a use case was and haven’t heard of the UML acronym. Now I’m not saying that every self-described BA necessarily needs to understand these traditional methods, but I want to drill into what I perceive to be the role of a BA and not the misnomer perpetuated by recruitment agents with a lack of understanding of the role.

The context – IT/Technology projects

The context of my definitions relate to the world of the IT, or whatever industry buzzword you want to call it, where software is developed to solve business problems.

The role – the generalist ‘Business Analyst’

In a simplified project model, we have several role types; developers, business analysts, testers and project management (remember I said simplistic model!). Within this limited and generalised role scope, business analysts are defining the requirements and assisting the development team with what they need to develop the application and solve the business problem.

Yeah, yeah. We all know what a business analyst does – they define requirements. They write a business requirements document. They either have a deep domain knowledge or liaise closely with those that do, and churn out documents which the development team diligently read and build from, right?

Well, while this certainly true and works in some organisations, this is not a good model. A business analyst does need to be a subject matter expert (SME) and being a SME does not automatically qualify you as being a business analyst. The larger an organisation is, the more prevalent and accepted this notion seems to be and how blurred the line between business analyst and SME becomes.

The cross-functional team and generalised specialists

A good project team consists of good people, skilled resources who work well together and apply their various skills to solve the over business problem, tackling small obstacles and changing requirements throughout the project’s lifecycle. Agile teams talk strongly about having cross-functional team members and there is interesting debate on the notion of the ‘generalised specialist’.

According to Scott (Ambler), a generalizing specialist is someone with a good grasp of how things fit together and as a result of this they tend to have greater understanding of what the team is working on.

In my view, everyone on the project team should be a generalised specialist. A business analyst does not need to know how to write code and participate in performance testing, but understands the concepts, participates in team discussions and has a few specialities which are accepted and can utilised the team. It is not uncommon for a cross-functional BA to perform comprehensive data analysis and modelling or a developer assisting the test team by writing a test harness to expedite performance testing.

So what’s wrong with the SME-as-BA model?

Nothing as long as it conforms to the above principals. The problem occurs with BAs who have strong subject (usually from many years in the business) but not a good grounding in analysis principals, methodologies and can not bring other skills to the project team. These SME resources are of course crucial to the project to provide insight and understanding of business operations, they may not be the best fit for the business analyst role.

Cross functional is the key

So how does a BA operate without having adequate domain knowledge? By having a varied functional toolkit, a BA can use their elicitation, modelling, analysis and documentation skills to engage the relevant stakeholders and produce the right outcomes (which are typically requirements documents but may be much more than just a single BRD) tailored for their audience.

I think the last part of the above statement is crucial – ‘tailored’ for their audience. Who are you producing the document for, is it a large development team, an offshore team, a single developer? Do they understand UML, do they like UML, do they prefer requirement statements, do they ignore documentation and develop from phone calls (most likely!) and how would you mitigate this by providing tailored documentation?

There is nothing worse than the template zombie phenomenon. Find the template, keep the structure, replace the content. This not only bores to death anybody who gets past page 5, it also severely constrains the BA to a certain way of thinking. Sure your organisation may have a defined process complete with templates but these can always be built upon – not blindly followed.

Tailor to your audience and challenge when there is a better way!

You might call it idealist, but challenging the status quo isn’t mission impossible. If you project/organisation has written BRDs with requirement statements as bullet points for 10 years that’s not a good reason for continuing to do so. Why not propose a quick use case model to structure your thoughts? PM doesn’t like use cases? That’s okay, you need them as part of your workflow so can do a use case model at least to map your thoughts, get the structure for things and take a few people on your journey, showing them how its useful, why you do it and how it all links in. Your PM still might not like it, but the development team finds it useful to get context and so you can include it. If you have found yourself being dictated what deliverables you need to produce and what they contain, you are not alone! Its not a great environment to work in but there is scope to change minds, and even if that is too politically challenging, then there is always scope to utilise your own methods and practices that might be beneficial for the team.

Let’s face it, we’ve all used them (or at least heard others cursing at them) and likely been frustrated at a seemingly simple ‘save’ action taken an unnecessarily long amount of time. So why do a select few push their use so so strongly? Do the perceived benefits really outweigh the annoying overhead required in their day-to-day use? To answer the question let me first describe the ‘organic’ world of no document management.

Organic (or no) document management

Some organisations prefer not to, or simply haven’t found reason to, enforce use of a document management system. In such an environment, the main document ‘store’ will likely be the ubiquitous ‘network share’ – that extremely well-organized set of nested folders and wide assortment of filenames. The person who created and/or maintains the folder structure has no problem finding what they need (every other employee struggles and constantly emails for the same document link) and the systems works well until Mark from accounting (* no real names or job titles used of course!) accidentally deletes the project folder and the backup from yesterday loses your days work. Sarcasm aside, the system can work in smaller environments with less than 20 or so employees but even they would benefit from a more structured approach.

Versioning? (which version was that again)

Another familiar scenario: Once the document you were after has been located, you scratch your head and wonder if v0.13 is the current version or whether what John was saying about still using the approved v0.11 still holds true. A quick email/call/rush-to-his-desk would clear that up, but he’s not there….

We know the problem – multiple versions of the same thing and we usually go with the latest, which is always a best guess and there are many reasons why the highest version isn’t necessarily the right answer (pending PCR, unapproved feedback, draft mistakes in latest etc.). Explicitly knowing the right version to use without needing to ask saves time – and saves rework, but is it worth the hassle?

Concerns with document management systems

So why don’t people warm to the concepts of document management? Let’s take a look at a few common complaints:

• It takes too much time to make a simple save
• It asks for too much extra information
• It’s too slow
• I can’t figure out how to save something
• What’s a check in?

Most of the above issues are related purely to usability, with some down to implementation, but the main inhibitor always seems to the systems usability. A document management solution needs to be ubiquitous and provide no more (or only slightly more) effort than hitting the Word save icon.

Some of these issues are inherently present in the design of the solution, particularly from the bigger industry players, but a lot of pain can be saved in the implementation by not saddling the users with too much metadata to complete and providing seamless integration into MS Office and popular document creation products.

Cost vs. Benefits? Is the value proposition really worth it?

Without debating the pros/cons of particular product offerings (an entire post on it’s own), is the benefit of using a document management offering really worth the pain/annoyances of their day-to-day use?

To me the answer is a resounding yes, but proportional to the overhead required by the particular implementation. For me, coming from a technical SharePoint consulting background, I am able to easily setup a painless and *almost* seamless document management experience for my projects with the required admin access and up-front planning (or help from IT team to get what I need created)*. What takes a day (max) to create upfront before a project saves not just me, but each team member, multiple days of frustrating effort attempting to locate and share documents.

* I reference SharePoint as it is commonly available in organisations, but the same holds true for other platforms with configurable ECM/DMS functionality

It has benefit when working with co-located teams, multiple vendors with different networks, distributed authors of single documents, serving up different views of static content and provides a static baseline for activities such as traceability (a topic of discussion in upcoming posts).

To pain that is associated with document management in my view comes down largely to product selection and implementation decisions and I appreciate there isn’t a lot that the average user can do to influence in these cases, but that’s not to say it isn’t worth asking. There may be regulatory reasons for enforcing strict rules around document management but often in it’s a poor understanding of the user base and a medium between ease of use and information capture.

Is there a better way?

For now I think it depends entirely on your organisations current situation and strategic direction, but the potential for influence is strong. While cloud-based solutions will unlikely be the answer due to unanswered security questions take a look at your current options and see if there are options to streamline the process. The key to a successful document management solution lies with a single word: seamless.

New name, new content

In the spirit of revamping, I’ve renamed the blog to ‘Business Analysed (‘Analyzed’ if your from North America) to reflect the true domain of the blog, rather than SharePoint focus it once had. This will result in a slight decrease in traffic due to name and domain name change, but a redirect on the old site should help alleviate some of that load and build the numbers back up.

Updated Axure Content

A popular request in comments and emails has been to update the AJAX autocomplete widget which I made for Axure RP (a popular wireframing/prototyping tool) a year or so back. I have finally managed to source the necessary source files and time to update the widget to latest release 6.x and incorporate some of the feature requests/kinks from the v2 release.

Post can be found here: http://www.hamishking.com/2010/01/29/updated-ajax-style-autocomplete-v2-rplib-available-for-download/

Time permitting I may get to release the Axure lightbox widget also, but that post was intended to be informative rather than a packaged widget, but taking reader advice on that.

Post can be found here: http://www.hamishking.com/2010/01/28/replicating-ajax-style-lightbox-within-axure-prototypes/

More Axure content can be found here: http://www.hamishking.com/category/axure-rp/

Themes (and their progress)

Lastly, I am also updating the look of Business Analysed to complete the full site revamp, but have yet to settle on a definite look and am contemplating designing from scratch. During the next few days the appearance may change between visits as I refine the display – so apologies in advance for this.

Otherwise, expect to see some new posts here soon and perhaps a leak about my upcoming side project.

Bye!

I use it for the extended ‘Undo Send’ feature but also came across a few other interesting add-ins that I thought would be useful.

To get there, head into Gmail and go into ‘Settings’ from the top right of your screen.

Under settings there is an aptly named ‘Labs’ section which contains all of these little gems.

Scroll through the various labs in the list and if you’re looking for the extended Undo feature like me, it’s very near the bottom.

So what is this undo feature ? it simply allows you to ‘undo’ the sending of an email. By default this value is set to 5 seconds in Gmail so you need to be quick – OR if you like to have flexibility you can extend this to ’30 seconds’ to afford yourself more time to realise you sent your mail to wrong person or left in that obvious spelling mistake!

Other labs I added on first look were:  ‘Google Docs previews in mail’, ‘Google Maps previews in mail’, ‘Google Search’, ‘Got the wrong Bob?’, ‘Mark as Read Button’, ‘Title Tweaks’ and the aforementioned ‘Undo Send’.

Just a quick update to shed light on this handy tool set I stumbled across – hope you like!

Sound easy? Well everything works fine if you plan to use the default shapes provided by Visio (and map to SP Designer default actions/conditions). Using these you can build workflows as complicated or simple as you like and have full synchronization to and from SP Designer.

The problem with this method is that you are limited to the default actions and conditions that ship with the product. Now granted this default set is better than 2007′s offering but there will certainly be lots of cases where the default set simply does not do the required job and a custom action or condition is required.

Custom actions and conditions can used easily within SP Designer and work really if your building your workflow there but if your planning to import and use those custom actions in your Visio model then you might want to re-think your strategy. Visio will allow you import these custom actions and they are shown with their own shape but you are unable to reuse these custom shapes in other parts of your diagram.

How does it Visio block you from doing this?

Well if you look at the validation rule set for the SP Workflow template using the bVisual Validation Explorer from  David Parker- the SharePoint template has the following rules

The rule that we encounter when trying to reuse custom actions in your Visio model is Rule #14 ‘Custom action cannot be added to workflow diagram..’ (see table above).

So the rule set is preventing the reuse of custom actions/conditions for some unspecified reason. I’m sure there is a valid reason for blocking this (maybe the Visio team simply ran out of time?) but the rules are customisable, so you should just be able to edit or override the rule and be done with it, right?

Well no actually. As it happens there are two methods of performing diagram validation using Visio 2010 – deploying the rule sets into the Visio template or writing a Visio solution and burying the logic within the code to fire on the RuleSetValidated event (more info on the Visio Team Blog). Unfortunately for those of us wanting to customise the SharePoint validation rules the SP Workflow template uses the latter method and we are unable to view / modify the logic.

So if you are planning to develop complex and powerful workflows for SharePoint 2010 then you might want to rethink your approach and decide whether you will need to use custom actions / conditions or whether the default set will suit your purpose.

Having said this, it is still possible (and very useful) to use custom actions / conditions and build your workflow entirely within SP Designer then export out to Visio for workflow visualisation. This way you will have accurate workflow representation including all custom actions / conditions but you will not be able to make changes within Visio – it must be done at the SP Designer level.

I intend to look further into this matter to see if there is some way in which custom actions / conditions can be reused  and Visio be leveraged for complex workflow design so look out for updates in this space shortly.

Update 1: Nothing so far from TechNet forums but I’m  awaiting a response from Microsoft to see if there is anyway around this issue.

In my example I want to show how it is possible to use the selected Visio shape to filter a SP list to display contextually relevant information on the fly.

The list I have created has supplementary information that might be useful to the diagram – please note I made it up very quickly and should not reflect any system design! You can mock-up something similar to the list shown below or anyones interested I could upload it as a list template – just ask.

For this example I have also created a very simple Visio diagram of ‘entities’ which we are going to use as our filter criteria. Create a new Visio diagram and drop on a couple of shapes – it really doesn’t matter what type they are.

The main thing here is the Shape Data – if you are familiar with adding Shape Data  simply define a new data property called ‘Entity’  and type the entity name into the shape information panel.  For those you don’t know what I mean by this, see the steps below.

Right click the shape and select ‘Define Shape Data’. Remove any existing data properties and add a new one called ‘Entity’ as per the diagram below (removing the ‘Order’ text under Value as this is specific to the shape and is added in a later step).

Now with the ‘Shape Information Panel’ you should see the ‘Entity’ data property with a blank value and you can enter the entity value for each shape – which in this example is the same as our shape name. If you don’t know where the Shape Information Panel has got to, enable it by selecting ‘Task Panes -> Shape Data’ from within the ‘View’ ribbon.

At this stage you are possibly wondering why you can’t simply use the Shape Name – doesn’t  the Visio Web Access surface this by default?

Well yes it does but in my tinkering I could not find a way for the Shape Name to correctly filter the list using the Shape Name and after many attempts decided to follow the approach of using custom shape data. If you have figured out a method of using the Shape Name to filter then I’d love to know – hopefully it’s not just something within my environment!

Before moving on make you to add entity values for all your shapes using the shape information panel.

Save the example diagram as a Visio Web Diagram (*.vdx) using the ‘Save As’ function and upload to a document library on SharePoint.  The source data is now created so move on to creating the page and making the filter connection.

Create a new page either using web interface or SP Designer and add two web parts: Visio Web Access and the list you created earlier. I will run through the web interface method below.

Select ‘Site Actions’ -> ‘More Options’ and select ‘Web Part Page’

Select ‘Full Page’ Filtering as your layout, enter a name for your page and click ‘Create’

You will be looking at a blank web part page with a big button to ‘Add a Web part’.

First add the ‘Visio Web Access’ web part which will act as your placeholder for your Visio diagram.

Click the link that says ‘Click here to open the tool pane’ and either paste in the Web Drawing URL to the saved .vdx you uploaded earlier or navigate to it like below.

QUICK TIP: The ‘Override Web Drawing’s default initial view’ option in the web part settings (second configuration option) should be disabled if you are using a diagram with multiple tabs. Despite what you might infer from its name, when enabled, it always refreshes the diagram back to the first tab with each shape selection. My suggestion is to disable this option unless you specifically need the functionality or are using a diagram with only one tab.

The other web part option that needs to be set before we can move on is the ‘Expose the following shape data..” field.

Because we are using custom shape data to filter (i.e. not Shape Name, Shape ID etc) we need to tell the web part to expose this data in order to use it in our connection. In this field type in ‘Entity’ if your following my example, or the name of the data property you created in Visio. We can now use this value to send as a filter to our list web part.

The go back and add another web part for the list you created earlier. This is done by selecting the list from ‘List and Libraries’ Category. It must be pointed out that the list must exist in the same site for this method to work. If your list is in another location or SP Farm then you will need to build a Data View Web Part like I have run through in this article.

Now that both elements are on the page we can set up the web part connection to send the filter value from one to the other.

Make sure the page is in edit mode and select the web part settings drop down for the Visio Web Access web part and select ‘Connections’

The connection type we wish to make is the ‘Send Shape Data to’ which will send the value of the selected shape to the list.

This will bring up a new window with the two-step connection wizard.

Select the ‘Get Filter Values From’

Then select ‘Entity’ in both the provider and consumer field. Essentially you are defining what value is being passed from the Visio web part (in this case our entity shape data value) and the consumer field defines what column on the list is to be filtered based on this value (and again in this example it is also the entity column).

Now the connection is set up, when we select a shape on the diagram it passes the entity name from the shape data to list web part and filters the list accordingly.

In my example I’ve attempted to show how web part connections can be used to supplement an entity relationship style diagram with information from a SP list but this is just one of many possible applications. Now that you can capture ANY type of shape data and pass this to ANY web part – the doors really do open.

Currently I am looking into a documentation system that uses such references to make a set of interactive, highly linked and contextually relevant document with as little content management as possible. I will post more in this space as it progress but this article should prove to be a useful starting point.

First thing to note is REST must be enabled on your environment so before you go any further, check that the service is running through your web browser. To do this, simply paste the following into your browser and replace the bracketed variables with your SP URL and the name of the list you wish to use.

http://[yoursharepointURL]/_vti_bin/listdata.svc/[LISTNAME]

If that returns a result in browser that looks strikingly like an RSS feed – then great, the service is working. If not, then ask your SP Admin nicely to get REST enabled (or have a go yourself if you have access) and the SPDevWiki has a good article on how to do so here

Techy note: As an alternative to REST you can follow the same principles of this article and use a the list.asmx web service and a SOAP connection as your data source. Personally I find this method easier to build your data view web part but both methods have their merits.

So assuming REST is enabled – we will move onto creating the connection into SP Designer.

First, open up SP Designer and go to the data source window.

Select ‘REST Service Connection’ from the ribbon to create a new REST query. On the ‘General’ tab enter a relevant name and then on the ‘Source’ tab under ‘Select Connection Info’ use the following syntax to specify the URL:

http://[yoursharepointURL]/_vti_bin/listdata.svc/[LISTNAME]

Replace [yoursharepointURL] with your address and [LISTNAME] with the name of your list.  Randy Williams has a good article on using REST in SharePoint 2010 so check that for further information.

The main thing to understand here is the structure of the URL and how to define which list it points to. The intention of this article is to explain how to reference a list on a different site collection but you could use any REST enabled data source for the same purpose.

An issue I encountered when playing around is that windows authentication didn’t seem to work when trying to build a data view web part – so if you encounter this then I suggest specify your domain account in the ‘Login’ tab. See my brief post on this here.

The next thing to do is create a blank web part page in order to display the new data source. Go to the ‘Site Pages’ library or any pages library within your site and select ‘Web Part Page -> Blank Web Part Page’ from the ribbon as shown in the screen below.

Now add the data view web part to the empty web part zone. Make sure the focus is in the web part zone in order to see the ‘Insert’ ribbon.

From the ‘Insert’ ribbon select the ‘Data View’ button and then ‘Empty Data View’. You could select the REST connection by scrolling down the drop down list but I had a few issues with that and prefer to define it in a second step – if it works for you then by all means do it!

If you followed my method of adding an empty data view web part then you see a web part like this.

Right click the web part and select ‘Select a Data Source’ from the context menu.

Now select the REST connection to add the data connection to the Data Source details panel and begin building the data view.

If everything went smoothly then you should see a data in the data source details panel similar to my screen below. If you encountered a ‘non-specific error’ then please see my short post here and force the connection to use your credentials and not windows authentication. I haven’t seen a way around this as yet but will keep an eye out.

Now the data connection is setup it’s just a matter of selecting what fields to display on the web part. There are two ways of doing this and it should be a matter of preference as to which you use – either select ‘Add/Remove Columns’ from the ‘List View Tools – Options’ ribbon or select the columns from the data source details panel and drag them onto your web part.

You should end up with a data grid similar to the mine below depending on how many columns you selected and the structure of your data.

How you build your data view depends the structure of your source data and it’s beyond the scope of this article to detail the various methods but the point here is we have the ability to use data from a list external to the site collection. This is a big plus if your environment has multiple SharePoint deployments for various functions such as a corporate intranet and an Office Business Application (OBA) – and you need to lookup data between them.  It also provides an easier way to reference lists cross-site and I find this method easier than using SharePoint’s lists.asmx web service and SOAP – but that may just be a personal preference!

Hopefully the post is useful to those who haven’t worked with the data view part before and for those who have – hope there weren’t too many screen clips!

As always feedback and questions are more than welcome!

Creating the data source went smoothly but when I tried to use it in the DVWP it threw the following unhelpful error.

“The server returned a non-specific error when frying to get data from the data source. Check the format and content of your query and try again. If the problem persists, contact the server administrator.”

I checked the service in the browser and it was working fine – so a quick investigation identified authentication as the problem. I went back to the data source and forced the service to  use my domain account instead of the default windows authentication provider.

As soon as the authentication was forced and I refreshed my data connection – the DVWP pulled everything through perfectly.

This issue seems to be with SP Designer not recognising your domain account when using windows authentication. This work-around will do the job – although it must be pointed out this method sends your credentials unencrypted in the call. Not the type of thing you would put into a production environment but will at the very least get you up and running with REST services inside SharePoint 2010.

More to come on this topic soon, specifically around potential uses of the service and a detailed walk through (time permitting as always!)

This time I’d like to demonstrate Visio Web Access and its nice Silverlight UI that includes features like linking to sub-processes, presentation of the shape data via the shape information panel and the ability to switch between tabs. Visio 2010 now comes with the web drawing format (*.vdw) allows any diagram to be rendered in-browser and is easily done using the  ’Save As’ function and selecting the *.vdw format.

The Silverlight rendering allows the viewer to ‘zoom and pan’ around the Visio canvas, negating the need for scroll bars and allows large diagrams to be easily displayed on a single page.

It is hard to see from the static picture above but the user can easily drag around the interface, zoom in and out and interact with individual elements within the diagram. In the screen grab above the ‘Rule 2′ decision has a blue highlight indicating it has been selected and would display the shape information in the information panel.

The image below attempts to show the user panning to right hand side of the image and exposing the blank canvas at the top and right of the diagram.

The new ‘linked sub-process’ feature allows shapes to be linked to a sub-processes on a separate and Visio web access maintains this connection through hyperlinks. Using this technique you can have great click-through diagrams linking areas that previously were only accessible by manually switching tabs.

The Shape Information Panel displays shape and hyperlinks data for the currently selected shape.

There is also an option to open in Visio allowing you make edits and save changes back to the document library. These updates are reflected in the rendered version as soon as the document is checked back in to SharePoint. The same result can be achieved by uploading a new version of the .vdw and overriding the existing file.

Visio Web Access  renders tabs in separate canvases and provides a drop down control to navigate through the tabs provides an alternative to linked sub-processes  (although I suggest you utilise this where possible – it’s very user-friendly!). The above screen illustrates this control.

That was a quick look at Visio Web Access and I intend to return to the subject when I have explored the data linking and other cool new features available in SP2010.

Using SP2010′s enhanced rich text field, you can upload and add an image directly into the list without having to leave the page.

When editing the enhanced rich text field (whether editing a single item in the edit form or using the cool new ‘Inline Editing’ feature (explained here), you have the option to insert from the ‘Editing Tools’ menu.

This brings up the ‘Select Picture’ dialog where you can select a local image to upload and a library to stored the uploaded copy.

Then save the uploaded image and complete any metadata requirements.

The image is inserted into the SP list but is managed centrally within the chosen library.

A very handy feature that was missing from 2007 and I’m glad it has been addressed in 2010.