ISO Compliance – An Architect’s Perspective

ISO Compliance gets a bad wrap. People roll their eyes, are bored by it, and often don’t see the relevance of it. I wanted to share my perspective on this and address some misconceptions.

International Standards Organisation (ISO) create documents that provide requirements, specifications and guidelines that can be used to ensure materials, products, and processes are fit for purpose.

Although I focus a little on ISO standards here you can apply my thoughts to most standards.

ISO Compliance & internal company process

Its a no-brainer that to be compliant to international standards such as ISO 20000, 9001, and 27001 we need to consider them in our processes. We should have processes for checking compliance and often compliance needs results in changes to our operational processes. Checking compliance basically involves taking a standard, turning it into a set of requirements and then going different exercises of requirements realization, or maybe even scoring your processes against criteria in a similar way to what I described in scoring documentation. My previous blogs on those subjects are just describing one of many approaches you can take.

Its important to ensure company processes validate compliance when they first create their processes but also whenever they change them. You cannot just implement standards and forget about them, because as processes change, so can the level of compliance to standards.

In many cases an ISO compliance certification in one country does not equate to having that certification in all countries. Just because your company may hold an ISO 20000 certification, this does not necessarily mean that it holds that certification in the country you are working in.

Adhering to standards isn’t just the job of a security or quality team. In order to really gain the benefits from ISO standards many different roles and stakeholders need to be considered or involved.

Compliance & Architecture

Its important for architects to be aware of which ISO standards a company states it is compliant to. It has a direct impact on both design and implementation in some cases. Its normal to want to short cut the compliance process. There are a few ways to do this;. One way is to create one set of master requirements that aggregates the requirements from all the relevant standards into a set of non functional requirements (NFRs) Those architecture and security NFRs need to be considered when both designing and implementing solutions, and mechanisms should be put into place to make sure that happens.

As an example – ISO 20000 asks that as part of release management a testing environment exists. An architect should plan for this when building implementation and migration architecture.

It is could be very easy to miss this requirement if architects are not aware of the international standards or company NFRs. These requirements are actually architecture concerns from a security and compliance perspective. Architecture concerns have to be managed in an architecture design.

Just as ISO standards can effect implementation and migration architecture they can also effect core architecture design. GDPR is a hot topic – around security of personal information, but for example ISO 27001 provides standards around all information security management.

Its not just a tickbox excercise

Compliance to standards may seem boring and just a pointless paper exercise and when you view it that way it starts to lose its value. The ISO standards have been put together by groups of smart people, that have developed a set of practices to mitigate risk and avoid pains they may have personally been exposed to.

I have heard from some managers in the past that “You cant expect architects to read a whole ISO standard”. Even if you have good non functional requirements from your quality and security teams I would recommend architects pick up at least one ISO standard and read it all. My personal favorite is ISO 42010 (The International Standard for Architecture Description). Read through an ISO and think about the value it’s recommendations give and the pains you would get from not following each recommendation.

For example, ISO 42010 talks about ensuring architecture concerns are framed by at least one viewpoint. If they were not, then the needs of our stakeholders might be missed. Things might not be managed and potentially a customer may notice it. Maybe even a major incident may happen – there could be a huge cost or risk.

If you start to read through a standard and maybe entertain yourself trying to imagine what kind of disaster may have happened that lead someone to write those sentences you may find yourself with a new appreciation of them.

In thinking about what is written in the different standards rather than blindly checking requirements off a list we can get more value from them, and we can learn from the mistakes of others.

Its an opportunity for group fun!

Those running a security, quality or architecture team wanting to get people engaged in ISO compliance could run a workshop with key stakeholders, and get them a little hands on with the risk management side of things.

If you lay out a set of requirements that have been distilled from an ISO standard, it stands to reason that not meeting those requirements poses a risk. If you are using a simple mechanism to validate compliance you could easily establish standard risks against each and every requirement being missed, and start to estimate impact and cost. Getting stakeholders involved in defining risk gives them a deeper more intimate engagement with risk management, and can also help later when those compliance processes are in use.

Its hard to argue that a risk is not valid, if you are the person that defined the standard risk is the person that violated it.

A message to all architects

If you are designing architecture, you need to be aware of standards you promise to adhere to for your customers. and within your own organization. If you cannot name all the standards your company promises to be compliant to, you need to at least be fully conversant with architecture and security non functional requirements. As architects we have a responsibility to ensure we are managing architecture concerns

Don’t think of ISO compliance as being a boring paper exercise. Think of it as an opportunity to take steps to ensure you have an easier, more relaxing, higher quality life at work.

Scoring Documentation Completion

This blog demonstrates a quick and easy way to score documentation completeness and improving quality which is more accurate than guesstimating,

The Goal

To be able to with a reasonable degree of accuracy estimate how complete documentation is, and to not need to take more that 30 minutes per document to do that. I need a balance between speed and detail.

Its not always the job of an EA to actually do these assessments but as an EA its good to get an understanding of documentation that’s based on an assessment rather than a guess at how complete something is, so I often teach this approach.

Some of the benefits of this approach

In following a structured approach we get

  • Better understanding of expectations. When the document authors understand the things we want to see the chances of getting them increases
  • Easy to visualize status – because we are quantifiable we can easily report status in a number of ways visually.
  • Better trace ability of progress – because again, being quantifiable means we can show improvement over time.
  • More realistic assessment of completion. Normally when i ask someone how complete something is they say 70 or 80% but when you start to look its often not so – people want to naturally please other people and tend to often give higher estimates, or sometimes do not think of the detail involved. This mechanism forces people to look at the work in more detail than if you were to “guesstimate”
  • Raises other quality issues. In doing an assessment like below you are reading and aligning to a set of criteria, which are the things that are important to you. Normally when If run a quick assessment i will come up with half dozen or so comments along side the review.

The End Result

I am looking to get an overall percentage of completion – performing an assessment of something i normally end up with a table which will look a little like this:

Figure 1 – A resultant score of several architectures.

Bear in mind the table is only an example. If I was creating scoring for high level design I may have more detail. You can see across the top I have listed some different architecture documentation. In this example its possible that a project may be composed of several teams working to deliver different things to a customer.

Going down on the left is the breakdown of the things we want to see in the document (Lets call them documentation areas). Each area is given a score of 0 to 5 based on some simple criteria which I will show in a while.

Another important thing to note is this is an estimation of completeness as a percentage and not necessarily work. Some of the things I give points for take longer than others. Reading through an assessment can help estimate the remaining work though.

An Overview Of The Process

The process i use is normally fairly simple. I normally pick a few people that will be assessors and give them an hour of training time with me. We run through a live document together and I explain what each document area means – and this description is normally supported with a template. So for each document we are assessing we normally have one template filled out – and we may go back several times over the course of a project to run the assessments again.

The assessment will happen between the assessor and the document owner. They run through each criteria and agree scores together and make notes to agree improvement areas. It can be done without the document author but i find that the communication between an author and and assessor in a meeting is more personal than just sending a filled in assessment. It also gets better commitment for improvement and enables the assessor to explain each criteria and answer questions.This can also be done as a peer to peer exercise.

I make sure that all people referred to in an assessment (approvers, technical validators) have actually reviewed the work and are aware of its state throughout the process.

Creating An Assessment Template

Its really easy to create a template that can be used for assessing the documentation. It can be done in any format – as a confluence page, as a word document, or as a google form, or Microsoft form for even easier collation.

Minimum Header Information

We always need to know as a minimum:

  • What is assessed – the document name normally – with a version number. I normally keep a copy of the actual document assessed with an assessment, rather than a URL to the current version of a document.
  • Who the assessor was – Just the name of the person who is running the assessment.
  • The document / design author – The person that is actually doing documentation work.
  • When the review was performed – just a date
  • A link back to any previous versions of the same assessment – If you are automating this process for a project in google forms for example the link back to a previous version might not be explicitly stated – you could calculate it if you know what was assessed and when. so if we did three separate reviews of the same thing it would have three different rows of data in your google forms.

The Criteria information

Normally I will expect to see this information each one of the different criteria

  • The criteria – The criteria we are assessing.
  • A short description of the criteria – normally a paragraph just to clarify things
  • The agreed score – using the scoring mechanism below
  • The scored mnemonics – I explain what each letter means in the scoring section.
  • The name of the person that approves the work – has to be a person with approval authority – not normally a project manager. Projects are transitory and end. The architecture normally gets delivered to someone in operations, and they should approve it.
  • The name of the person that technically validated things – normally a technical person who is not the author – its good to get a technically competent person from another team if possible.
  • Notes – any helpful information captured during a review.

In a very large project with multiple architects involved in an assessment I might also add the need for the Architect name, and the individual date You can see part of an example in figure 2:

Figure 2 – A partial example of a template

Scoring Documentation Areas

The Score

I apply a very simple scoring system; the order I show here is the order I assess on. I don’t normally assess something is fully complete until its partially complete. I don’t assess language before something is fully complete, and so on.

You don’t allow people to be their own technical validator or approver.

Figure 3 – The scoring

Short here is a mnemonic letter I use to show easily in assessments what I gave points for. So if something is at least partially addressed a point is given – an extra point is given once its fully addressed.

The Math

The math for calculating percentages in figure 1 is simple, but i will just mention it

  • There are 9 different things to assess and a maximum score of 5 points for each area – giving 45 points total as a possible score.
  • Row 14 is just a sum of the proceeding rows.
  • Row 15 is the percentage calculation – so we are calculating what percentage of 45 is in row 14. For column B that would be =(100*B14)/45

Summing It Up

This has been a quick introduction to how I approach doing quick assessments of documentation status when in large complex projects. Its not perfect but it is fairly flexible and quick and easy to implement. Its saved me many hours of having to do more in depth reviews before teams are ready to do so.

I hope this helps someone out there!

Modelling Information Flow In ArchiMate

With regulation such as GDPR being in force to protect our users, properly understanding information flow becomes essential. This blog shows some of the ways we can model information flow.

An Overview

There are a couple of different ways we can represent information flow that I touch upon in this blog – I would suggest you use the technique that you prefer but be consistent with it. I don’t normally use more than one method in a model package, unless I have a specific reason to do so.

Using Flow Relationships

I will start with a layered view like have used on several other blogs – our web hosting service serves as a practical example.

Figure 1 – Layered View

The layered view contains both internal and external elements – we will look at them separately. Although Figure 1 shows a layered view I might use to communicate the big picture, as it stands it would need some more detailing before I can fully map information flow.

Mapping Service Flow

In order to properly understand the flow of information between services we need to establish the service interfaces. If my layered view doesn’t have interfaces on – I need to consider and add them. In the example above we have at already done that between the business and application levels – you can see that in figure 2:

Figure 2 – Services and Interfaces

The first thing I will do is look at anywhere the interfaces are serving another element:

Figure 3 – Focusing On Serving relationships.

These areas are effectively where external information flow is happening. I will be looking to replace these serving relationships with flow relationships. In this view i would possibly make an exception though. The service relationship between the HTTP interface and the website hosting interface tells me that there is a relationship between the two. I might normally look further into detailing out the web hosting service to determine how the HTTP interface is used, but in the case of the view above I have answered the question already – its serving the incident management process.

Some architects do not model interfaces against services all the time – myself included. Its dependent on a number of factors; I want to do “just enough architecture”. If we took the interfaces out of the equation we can still map information flows from services to other services.

Considering other relationships

I will also consider the realization relationships in the same way as I look at serving relationships – in this example though I have only an application interface realizing a business interface. the business web portal is only exposing the application layer functionality and there’s no actual data transfer between the layers to consider. Sometimes association relationships should also be looked at.

Putting the flows onto the diagram

Once I have identified the relationships i am interested in I then start to put the information flows onto the diagram. and thinking about information flows. I reorganized the view a little because I decided its not enough to understand which process has access – I want to also understand which role. I then removed the serving relationships from the view, but I didn’t delete them – they are still valid for other views.

The result was this view

Figure 4 – Flows in a layered view

I have labeled the flow arrows, but do not forget that each relationship can also have documentation – where you can further specify what that information means. When looking at application level interfaces, I might want to also think about specific ports we use – and I may either show it on the actual view or in the documentation for the relationship. I chose to not show ports on the view above because I don’t want to turn my ArchiMate views too technical; in some cases depending on who your stakeholder is you may want to do things differently and include the port numbers on the labels.

Breaking things down

I broke my initial diagram into two parts to make the blog a little bit less cluttered as I focus into part of it, and that’s ok. In the same way as I have now shown flow between business and application layers, I could do the same between the application and technology layers. To keep diagram complexity down sometimes we break things into smaller chunks. The initial layered view showed how they all fit together at the highest level.

Identifying issues

Doing this information flow exercise highlighted some design issues. The second I came to create a flow from website support to the HTTP interface I realized I should be using HTTPS. I could either change that element (which effects the whole model) or I could establish a second interface.

Because in this modelling exercise I am focusing on information flow between elements other issues come up too. For example – when I am looking at the website support role – I ask myself the question what if the HTTP interface into the website application service isnt enough to diagnose a problem? In the old days I might add an Remote desktop Interface – but if I am using third party cloud providers to provide the underlying service this might not be an option – instead I might define a separate special admin interface.

These questions came up just through looking at the information modelling on a layered view. Information flow could also be shown on a whole range of other views. When you actively focus on different component parts of the view and their relationships, thinking in terms of what kinds of relationships fit and why, we quite often see new things.

Associating Passive Objects

Figure 4 could have been written another way:

Figure 5 – Layered view with passive elements.

Here I created some passive objects – (Business objects & data objects). Doing this has an advantage over flow relationships – if I am reusing elements in different views then I can easily get an understanding for example where Admin Login Credentials are used throughout my model.

You may have noticed I have web pages as a business object and an data object. That’s because conceptually in the view they are at two different levels. at the business level web pages are a concept, but they are made more tangible at the application layer.

Another important thing to note is that some of these relationships do not denote the direction of information flow. For example – the HTTP interface is Serving Website Support – this does not mean that admin credentials are flowing from the HTTP interface to the website support role.

Information Location

I can easily add Locations to my view to make it a bit more complete from a GDPR perspective:

Figure 6 – Layered View With Locations

Normally those elements are orange, but for me that’s a complete aesthetic color clash so i changed it. There’s nothing in the ArchiMate rule book that says you cannot do that!

Modelling Internal Information Flows (and Application Cooperation)

In the same way as we can show information flows on a layered view we can do the same thing on many other views – such as service realization views, technology views and so on. Remember sometimes we might want to have two viewpoints showing the same things in different ways for different stakeholders. We might have a normal service realization view, and one for GDPR compliance work. We can use exactly the same approach as i showed on the layered views with most other views. I would take copy of the view and start removing relationships from the view (not the model) replacing them with flows.

With regards to application cooperation views, they can be done at different layers of detail dependent on need. the best application cooperation views include processes, events, interactions and services. They do not include interfaces and are internal views. As a bare minimum I would expect to see interaction between application components and the services – as an example:

Figure 7 – Basic Application cooperation view with information flows.

Figure 7 doesn’t really show the cooperation! I am focusing on data flow rather than any causal relationships and elements. This works as a starting point. I have seen some architects do variations on figure 7. Some people like to emphasize the more important information flows.

Other architects do not include what they consider to be less important flows, and produce more abstract views. For example the web page request – is a good example of low level communication that is essential to a low level view but may not be important if we are trying to provide stakeholders an overview.

Personally I like the level of detail in figure 7.

Using Access Relationship.

Where accesses relationships are possible within different views they should be used if those views are for presenting information flow. The access relationship is a data dependency relationship in ArchiMate. its indicating that a process, function, interaction, service or event does something with a passive object.

Using The Path

The Technology layer has an element for representing flow of information – the path. Take a look at figure 8:

Figure 8 – Web Data Transmission

You can see here I have represented the path information takes to get from the web server to the end user by creating a Web Data Transmission path. Note that the two end points are not considered to be part of the path. This is because the path denotes to path from end to end – when we reuse the Web Data Transmission element we are likely to want to use it to convey transmission from many different end points.

Summing it up…

Most views can be remodeled to include information flow, and going through the process of doing so will enhance your understanding of information flow and risk.

I focused mostly on business and application layer within this blog but the same practices apply when working with the technology layer

When doing High Level Design Work as a minimum I like to see either the basic information flows in the application cooperation views, or information flows in the layered view.

Having these information flows enables us to ensure compliance to different regulations and gives us the ability to do some very cool things with risk management.

Creating High Level Designs

High level design is a subject of much discussion in pretty much every organization I have worked with. The question “How Much Is Enough?” is often put to me. This blog addresses this question.

If you ever have to bring a High Level Design (HLD) to me for review – this blog is a good read because it sets a level of both design and review expectations. I promised a colleague I would publish this blog, so it was written in a bit of a rush and I may go back and update it later.

HLD Overview
Figure 1 shows the key areas in a HLD.

What is a High Level Design?

I normally break architecture down into 3 basic levels

  • Conceptual Architecture – Is a single view that sets the scope of the architecture at the highest level of abstraction
  • High Level Design – Is something in the middle. It gives us the answers to all the fundamental questions, whilst normally staying at a level of abstraction from actual technology implementations.
  • Low Level Design – Is architecture at its lowest level – which can include actual machine and network configurations, and exactly how things are implemented


Its not practical to build designs without putting them into the context of the business. Architecture is about building a solution which solves the needs of our stakeholder. With that in mind there is some related documentation we should have.

A Business Case

The business case is basically setting the scene for what we expect from the architecture. If an architecture isn’t providing a benefit to our business we shouldn’t be doing it.

Bear in mind, this doesn’t necessarily mean that the benefit is profit. Whatever the benefit is, it needs to be stated, it needs to be clearly defined in a way that is measurable and not subject to opinion.

“We need to make a lot of profit” may be a true statement – but “we will make 1 million Euros in the first year” – is a lot more clear.

The business case is establishing the goals, and business requirements. It basically needs to lay out what it is thats being proposed, and the value we get from it.

Basic Business Case Validation

When assessing business cases I am normally looking to see also the reason behind the numbers. If a product states it will make a million Euros per year i want to see the rationale behind that number, and to see that such numbers are realistic. The most realistic cases are based on existing numbers.

If Microsoft reports an 64% growth in Azure sales, it doesn’t mean its partners see the same growth. Growth and profit are influenced by many factors including how fast you can get an idea from idea to realization, and how well your solution can be scaled.

For basic validation of business cases I normally think as TELOS related questions.

A good business case demonstrates the thinking behind the numbers. If it states we need to hit a revenue target then these goals are part of our architecture motivation.

The key takeway here:

If you don’t have a clearly defined business case, then you cannot know that any technical design or service design will be fit for purpose.

A Conceptual Architecture

Conceptual architectures can come in many forms – I am normally looking for a single view in ArchiMate that shows the concept of the business case architecture. I normally am focusing on scope.

A conceptual architecture for a product normally shows the product and the services within it (Like a product view), as well as showing the key application components, or technology layer components relating to the product, as well as the teams that support it, and other related products & dependencies. In product service architectures i am normally showing Business Application and Technology layers, but not showing data or information flows. This is because of how we use conceptual architectures as part of business validation – adding relationships and information flows makes it messy.

In a non product related conceptual we make sure the view we provide hooks into the current existing architectures (services or products normally.

With any architecture I am looking to ensure It has considered the architecture aspects.


I recently wrote about Architecture Concerns and will not go into too much detail. For any architecture, having a defined set of requirements to validate is essential. This can take many forms (such as User Stories). This could also be done in a set of ArchiMate views.

Basic Requirements Validation

I want to see the following when I validate a HLD:

  • A set of requirements – which are clearly defined and unambiguous.
  • Documented evidence of requirements management – Showing how requirements have been managed, and pointing to where in the architecture requirements have been realised.
  • Considerations from all the stakeholders perspectives. Lets break that out separately.
  • Consideration of incoming and outgoing requirements – we need things from other teams – for those things we need agreements with respective teams. On the flip side we may also have requirements towards us. If our solution uses monitoring for example, the monitoring team may require a specific agent to be installed on something.
  • TELOS – As mentioned in the business case phase a more detailed look into TELOS is warranted as part of the high level design to ensure that our requirements consider Technical, Economic, Legal, Operational, and Scheduling needs.


When we talk Stakeholders its very easy to be preoccupied with just the customer or the end user but in reality many teams or people either provide something to your architecture, or require something from it.

ISO 42010 has a good list of potential stakeholders of a system which includes users of the system, designers of the system, owners of the system – the list goes on. As a minimum need to know that an architecture will meet these needs:

  • Customer – this includes different roles within customer organization – for example the end user cares if they get a easy to use continuous service – where as the person that is buying the service from you wants to be able to show their management how well the service is used, or the value it brings.
  • Internal Business – around revenue and profit for example. or if its needed for strategic reasons we need to keep tract of that kind of things. Sales teams may also have concerns with architecture.
  • Internal Ops Team – They need to be able to operate the solution the architect gives them in an efficient way – there are normally Staffing, Training, Capacity, monitoring, and procedural related requirements for example.
  • Partner – If we are using partners a business interface needs to be established with them – a set of requirements together with an SLA is a fantastic way to do this.

Validating the Architecture Model

One thing to note is the old adage “If its not documented, it doesn’t exist”. Its important for all information around your architecture to be stored together. a High Level Design can be produced completely in an Archimate model, or maybe part of a document (I discuss this in Designing Architecture Through Document Templates.

Our High Level Design is telling a story. Effectively all those prerequites we have described are setting a challenge. Its the job of architecture to describe a solution that addresses all the needs of a challenge.

Regardless of if you chose to use a document or an ArchiMate model, or in Word, the story needs to be threaded together in a single solution. There may be multiple parts – such as several prerequisite documents, but they need to be referenced together in one place.

Within any solution or service design there are normally many meetings, and its essential we track decisions that are made in a single space that is available for all. Where i currently work i normally track all decisions relating to a specific architecture on a single page so its easy to follow. Its ok to reference external sources for things liike requiremetns or supporting information, but when this is done you have to consider the following

  • Ensure there is version control so we know what version of a particular document or source we are referring to on our design. normally when i am doing a review meeting i will take a copy of related documents and store them together so that there is a timeless copy that cannot be interfered with
  • You have to know your stakeholders and ensure they all have access. I have lost count of the times information has been locked up so i cannot see related information.

I also want to ensure as far as possible that i do not duplicate information – its better to refer to master information sources for things when required.

If we are creating an entire high level design in ArchiMate you have to remember to document the model. We are not using our architecture tools to produce diagrams, we are using them to produce views of architecture. Our tools enable us to document the architecture view, to explain what we are showing, as well as the elements and relationships. Remember to address the audience.

Covering Architecture Aspects

Remember just as with our conceptual an architecture has to address architecture aspects. This doesn’t mean i have to address them all in a single place in the architecture – but I do have to ensure that we consider all aspects and not only technology. For example you may address processes and roles in many different views.

A minimum set of views

For those of you that do not know where to start I present to you a minimum set of views to consider. We do not document or create views just for the sake of having them. There may be reasons why you wish to use other views, or deviate from this structure. Thats Ok.

Lets take a look at some of the views I would expect to see. in an archimate model:

We will walk through this bit by bit. An ABB is an Architecture Building Block. Normally I prefer to deal with architecture at a service level but there are times where thats not practical. In those cases related architecture may be together in a grouping box which is named something to explain what it is. For example I might have everything relating to application monitoring described (including its interfaces, triggers and processes) in a grouping box named “Application Monitoring”. You would use a grouping box where you might want to represent a group of elements that are cross layer. Some of our application monitoring processes may be business related or technology related for example. Where possible I prefer to use services or functions to ABB’s.

Conceptual Architecture or Layered Views

The order of things I am showing can happen in two different ways. where I work currently normally at the point architecture begins a business person has already got a conceptual idea in their head and want to start there. Our product management teams are used to working in a specific way – I normally have to start by asking what is it they are trying to do, and then when I understand what – I am wanting to understand why.

Conceptual architectures are normally a good starting point when you are in this situation, as are layered views. I normally take a service focused approach to building architecture. Take a look at my Services In Archimate blog – it shows some layered views.

I normally start with a conceptual view and then refine and define services from there. Every Service or function I have defined at the upper level needs further detailing:

  • It should appear in a requirements realisation view
  • It should appear in a Service realisation view
  • It should appear in a implementation and migration view.

I do not necessarily have to see all services defined in their own service realization views, although I often will. As a rule of thumb if i have more than 30 elements in a view i am asking myself if I need to split it into sub views. Again remembering each view tells a story it may make sense to group together several services in the same service realization view if several services are realized in the same way – or if theres another logical reason to do so.

Requirements and Rationale

Working with requirements realization views, my key element of focus is the requirement. Working with motivations views I like to ensure i have the drivers, goals, and requirements clearly defined. other elements just supporting the story of how a need (driver) leads to a set of requirements that will achieve a goal.

In my Planning Work With Archimate blog i talk a bit about creating motivation views for stakeholder concerns, and I also show a level of motivational modelling in my User Stories blog. Those mechansims are good for capturing different concerns from different stakeholders, but the important thing to note here is that we need to align the motivation model with the actual business case.

I already described the order i do things in normally because its the quickest way to deliver some value in my particular case. However, an excellent approach is to start with a motivational view, to create some requirements realization views from that where i figure exactly which services and processes I need to put in place to meet the requirements.

All requirements need to be shown to be managed within an architecture design. If we are working with ArchiMate we do not necessarily need to see every requirement on a view – its ok to group together requirements on the view to make it more manageable:

Figure 3 – Requirements realization

The above (Figure 3) is OK- if in the documentation for those requirements you link back to a source where those requirements are all managed together – so we can easily see the working status of each underlying requirement.

The important thing here is that requirements are mapped to their respective areas of architecture. Figure 3 showed a very high level view – I would expect in such a case we would also need other requirements realization views to show more detail because although figure 3 gives me a level of confidence that we are managing requirements, it doesn’t really tell me how.

As an example. Consider customer requirements/user stories for our Web Hosting product:

Figure 4 – Example User Stories

The point I am trying to make is different requirements may be realized in very different ways. There are different ways we could address each of the needs of our stakeholders, and we need to show in the high level design that we have considered them. If we have 100 requirements for an application by all means group them together, and put them in a single element, but only if it makes sense to do that, and you can show in other documentation how each requirement is handled separately.

Sometimes the choices we make do not appear to make sense. For example, if we had chosen to have a manual business process for billing rather than an automated application process. There might be a good reason – like not having resources to do the automation, or maybe the billing is only once a year and a 2 minute job in another system and doesn’t justify the expense. That’s a business decision. Such a decision quite often gets made in a meeting, maybe minuted and dropped into an email and forgotten about. It is vitally important that decisions are tracked in a work log and not just in a meeting; I have seen thousands of hours burned because of a decision not being tracked and then trying to track back with the relevant people how and what was decided. Sometimes people leave positions in an organization and sometimes you never find out why. Its wasted time that can be easily avoided with a little discipline.

Take a look at my blog on Requirements Realization Views if you are interested in going into more detail.

Business, Data, Application, Technology

Borrowing from TOGAF – Business, Data, Application, Technology, we need to ensure we describe these layers of information. We could do this in a detailed layer view – but I normally break things down into several views.

The Service Realization

Every Service has a service realization view (Several can be part of a single view). This may be small if a service is provided by a third party – because then you are only defining the business interface – but regardless we need a complete picture.

The service realization view is showing how the business layer connects into the application layer. In our web service hosting example, our business service might be realized by two different application components – Apache & Internet Information Server (IIS).The view shows how this service is provided.

The Business Process View

In my blog on Aligning Archimate to BPMN – I introduced the idea of creating process overviews, such as this one:

Process Overview
Figure 5 – A Process Overview

In a high level design I don’t expect to see fully defined processes. For the business processes I only want to understand:

  • What the process is
  • How the process connects to the rest of the architecture
  • What events trigger the process
  • What the possible outcomes of the process are
  • Which roles or people provide the process

Normally this can be done a lot quicker than actually fully defining a process.

The Technology Usage View

Within the service realization I have identified a number of different application layer items (Apache & IIS) which should exist within a technology usage view. The technology usage view is connecting the application layer to the technology layer. I might have a simple view which shows how IIS is served by a technology device – or the scenarios could be more complex – for example we may be using virtualization.

Application Usage or Cooperation Views

These views are useful for seeing how application elements connect together, and how they tie into application data elements and flow of information, which is a good baseline for work with GDPR for example. If you have data elements in the Information Structure Views its good to show them here if it makes sense to. When looking at HLD’s I normally like to see both of these views – however sometimes I find application cooperation and service realization views have a little bit of overlap when people model these views.

The Technology View

The technology views show how our technology layer fits together. Following our example if we have technology devices for Apache and IIS I would want to understand how they fit together and are connected via a network.

At this point I would remind people we are still looking to build high level designs. I am not normally going down to the point i have IP addresses. Quite often with services we offer them with a variety of different service levels, and dependent on the service level we may have different technology views. For example, our best service level might necessitate us to build a technology architecture that has complete redundancy and multi site. Our lowest service level may be a single server in a data center. Model the common scenarios.

Information Structure Views

These views show basic information structures/taxomomies relating to the architecture. We create structures that make sense in the context of what we are producing. For example, if we are implementing a new service in service now then we need to determine a CMDB structural template, or maybe even a service now structure. We can lay out the relationships between the data elements and can even document the relationships to explain why they exist.

For more complex structures we could of course use something like a UML class diagram – but most of the time the structures I use are simpler. Figure 1 showed a simple information structure in the business layer, but of course we can create information structure views in the Business, Application and technology layers, or structures to show how they are related. Take a look at figure 6

Figure 6 – An information Structure View

I chose to use a Grouping box rather than create individual compositions to each data object. Depending on how i was going to use this architecture model I might have done it the other way, but we should visualize in a way that makes sense to our stakeholders.

There is a balance to be had. In a high level design we do not want to go to too much detail – Figure 6 has value because in our fictional example it shows our audience the configurations that we will need to support and helps set scope. We can see clearly that we would need to define two virtual machine templates and a standard network configuration for implementing our basic Apache – and we might chose to reuse these elements. The view gives context to some data objects that would need to be defined in the implementation views.

For more complex structures we could of course use something like a UML class diagram – but most of the time the structures I use are simpler. Figure 1 showed a simple information structure in the business layer, but of course we can create information structure views in the Business, Application and technology layers, or structures to show how they are related.

Relating to information structure is information flow. Its important to document how information flows throughout your architecture. I talk about how you might approach this in my Modelling Information Flow In Archimate blog.

Project & Lifecycle

I talk about modelling projects in my blog Planning Work In Archimate. That blog covers the basic minimums I would expect to see in order to understand a project and its road map. It doesn’t cover more complex concepts such as using plateau’s to represent different states of architecture. I will save that for a future blog.

Using Vendor Or Other Reference Architectures

I am fine with the idea of reusing with pride; several vendors have standard reference architectures. Just because a vendor has a standard reference architecture or a standard set of best practices, it doesn’t mean our job is done.

We still have requirements that need to be realized and we still need to cover the architecture aspects when using a vendor architecture. We also probably need to establish a proper interface and set of requirements for the vendor.

Summing It Up…

Theres a lot of things that go into any architecture design and this is only one approach to creating one. The reality is, that depending on your requirements the amount of emphasis you put into different areas of architecture radically change – for example if we are using Amazon Web Services as a provider of our technology platform we might not need to fully define that platform – although it may still need a small amount of architecture – just for us to state we use the technology level services from Amazon, and maybe what the interfaces into those services are. There could also be related requirements realizations needed of course.

I’ve done my best in this blog to address a fairly complex subject in a relatively short blog. The approach in the blog isn’t perfect, but its one I have developed and used over time to meet the requirements placed upon me by various stakeholders.

Implementing a High Level Design, as described here goes a long way towards creating a solid design that mitigates risks and significantly reduces cost to business.

Requirements Realization Views

One of the most essential but often overlooked views to have on architecture is requirements realization. This blog explores this subject and one way we can work with them.

I show one way of working with Requirements Realization Views – Its not the only way. Doing this can save huge amounts of time and money by avoiding a need to redo things.

If you have read ISO 42010 the International standard for architecture description, you will know that every architecture view is intended to frame the concerns of its stakeholders.

Architecture isn’t about drawing pictures. Whist defining a view of technology is important, it is more important is understanding the reason why. We learn this in math class as children. The answer to a math question gives you points, but you also get points for showing work.

The Requirements realization view is one way to show how a solution meets the needs of its stakeholders.

I show below some example views and one way of working that can be used with BiZZdesign’s Enterprise Studio. Its the tool I use most often, so I leverage some of its benefits in my workflow. All the things I show can be done with other tools, some tools make this easier than others.

An Example View

Figure 1 – Requirements Realization View

The example above is a basic requirements realization view. Its at a high level – its showing that a product is meeting several requirements. The level of detail we go to depends very much on the benefit it would provide. The view in figure 1 – may serve as a good introduction to anyone wishing to understand the design from the Web Hosting Product. For the purposes of a high level introduction to business stakeholders that might be enough, but how do we know what is above is true?

The next level of detail

Each of the requirements in figure 1 is obviously a collection of other requirements – I might define them in architect, or I might just reference another source. For example – business unit requirements may exist and be managed in a system like Confluence. This might be a more accessible place for stakeholders to manage them if we do not want to go though the trouble of teaching everyone ArchiMate.

The next level of detail in ArchiMate

Personally, I do not always ask for everyone to go to the next level of detail in ArchiMate, because in a complex project with many moving parts it doesn’t always make sense, especially when you have different architects at different levels of maturity, especially when you have several thousands of requirements in a project

That said, there are advantages to mapping your requirements in Archimate. I know one or two architects that do it.

Using Enterprise Studio

Here tools can set you apart. Importing requirements from excel into an architecture model can be fairly easy in some tools. I am using BiZZdesigns Enterprise Studio (BES). – which makes it easy to import and update requirements if I create them using New > Multiple – I can then copy and paste in from excel. I could have done this other ways too and its probably worth the time taken to do that.. You end up with a lot of requirements on a view like this:

Figure 2 – Requirements

You might think in this case that this isn’t very helpful – its just a bunch of numbers – but what i did was import the requirement ID’s as names and I put the actual descriptions in the description or documentation field. In this way when I have many requirements I can make them smaller and more manageable on screen.

To actually see detail of each requirement I can switch on tooltips – so the documentation pops up when I mouse-over the requirement, or I can use labels.

Figure 3 – A requirement labelled.

So why bother?

Once I have the requirements on my canvas i can group them together – to organised them in different ways for different stakeholders. Something like in figure 4:

Figure 4 – Grouping Requirements

When I have done the above in big projects I have sometimes identified requirements that are not managed at all. In the example above you can easily see uncategorized requirements. They are not connected to anything and can easily be forgotten. Just by itself it makes the pain of the exercise worth while. I can also at this point prioritize them and then I normally take these requirements and connect them into a series of implementation and migration views.

Every requirement needs to be realized some how. I can pretty easily either script, or create a property table in Enterprise Studio to see requirements that are not realizing things as an extra level of validation. If we have mapped our requirements into groups, and created views for each group, then we should easily be able to see things that are not realized anyway. Back in figure 4 we did our mapping, and as a result of the mapping for example we may have decided to have 5 realization views:

  • Customer Requirements Realization View
  • Architecture NFR Realization View
  • Security NFR Realization View
  • Business Unit Requirements Realization View
  • Orphaned Requirements Realization View

Mapping Requirements to the Realization

Now with the prep work completed we get to the important part. Our Customer Requirements Realization View might look like something in figure 5.

Figure 5 – Customer Requirements Realization

Lets look closer at figure 5.

The standard web hosting solution

I make use of the grouping element in ArchiMate to represent architecture building blocks. Its enables me to keep things neat – I could have course have hidden this level of detail in another view & just connected in the Web Hosting Product. In this case I felt the services create value. I do not need the detail to know exactly which servers are being used but I can tell that this will be an Azure hosted solution, running on Linux. If you read my blog on services, you should at this point start to see the value of hiding architecture behind the externally facing services.

Standard Services Contract

Some requirements are covered by our standard products and some by our standard agreements. To use the ISO 42010 language again – Its important to see that concerns are all framed within one or more viewpoints. This means even if its obvious to us that something is covered in the standard contract we should state it. What is obvious to me is not necessarily obvious to a coworker.

Customer CRM

Of course I could put as much or as little detail as I need into this view. I am telling a story, which I talk about in my Improving Archimate Modelling Blog. The important thing to remember is that all requirements need to be realized in a view, but again not always the same view. Because we are telling a story we need to be consistent with the level of detail.

Locking Down Requirements

Before starting requirements realization its important to have requirements management under control. Its a separate subject, but you need to ensure that requirements are not significantly changing during a project, or the workload significantly increases.Going through the process of redrafting your realization view will provide benefit and avoid confusion.

Some Common Challenges

I have sometimes seen requirements realization being missed as a step. Sometimes people just create a technical solution, and say “yes” that meets the requirements after a first read through, Then later they realize it doesn’t because they didn’t look to this level of detail and are forced to go through a very expensive exercise of fixing things.

I have also seen things mess up because requirements management is seen as being a project managers job. Yes, those guys are responsible to ensure requirements are met, but not how they are met. I see the job of organizing requirements in a way that makes sense to the solution as being an essential part of an architects job. If you look at the TOGAF ADM for example you will see requirements management at the heart of everything..Its partly a separate conversation but I would also encourage architects to work with project managers to organize requirements in a way that makes sense, because it makes requirements realization a lot easier and reduces risk,

Another common issue if focusing too much on customer requirements. Its really common for organizations to have a customer first approach – but this doesn’t mean we should not consider our own needs. Business requirements are important, as are the architecture and security ones for example. If we do not consider them, issues will occur later – because they are there to mitigate risk. Some non functional requirements will relate to documentation and I can easily create a view for architecture deliverable requirements realization. In projects architects should ensure time is given to manage non customer requirements.

Summing It Up

I cannot stress the importance of doing requirements realization. In this article i focused mostly on doing requirements realization in ArchiMate, but we can actually do it in other ways. I wrote about the challenges of Designing Architecture Through Document Templates before – I personally try to avoid that for the reasons I state in that blog.

Requirements show us “what” needs to be done by “who”, and “when”. Requirements Realization shows us “how”. This is a message I think all architects should take to heart and communicate out to other stakeholders.

Yes, running through thousands of requirements can be boring but taking the time to properly manage and realize them can result in very high quality work. Requirements Realization can be cool.