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!

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

Prerequisites

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.

Requirements

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.

Stakeholders

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.

Services in ArchiMate

Services are very important parts of the ArchiMate modelling language. This blog shows some ways we can represent and utilize services.

The Difference Between A Service And A Product

Its important to understand the difference between a service and product. I have seen in many places those terms have been interchanged. Product management must have a common understanding to architects, although this doesn’t mean we necessarily need to expose ArchiMate to Product managers. The whole point of ArchiMate is to provide a common modelling language to enable clear communication.

Figure 1

A product is a collection of services and a contract. A product element lives in the business layer. Normally we connect our services to the outside world through the business layer.

Products are composite elements that aggregate or compose any of these elements in archimate:

  • Business Service
  • Application Service
  • Technology Service
  • Business Passive Structure Elements
  • Data Objects
  • Technology Objects

They are pretty clearly defined in Chapter 8 of the ArchiMate Manual.

Services

A business service represents an explicitly defined exposed business behavior.

Although services are also defined in the ArchiMate Manual I don’t think it does them justice.

In point of fact all services are explicitly defined exposed behavior; be it a business service, an application service or a technology service. These services are very important in large organisations. Take a look at this layered view. Its a typical layered view used to show how the Business, Application and Technology fit together for a fictional web hosting service.

Figure 2

It doesn’t show a complete picture – because of course actors and processes in the business layer are likely to connect into the other layers. We do not have to put every element on every view – we use what we need to tell a story. To work more directly with services we can abstract out from the view above:

Figure 3

In figure 3 we are showing only services, and its important to understand the relationships here, and the concepts. You can see A platform service is realized by either Microsoft Azure or an Amazon Web Service. I could have said they were both specializations of a platform service. I prefer to do use the realization because it would have meant drawing specialization relations in the opposite direction which isn’t as intuitive to read.

Abstract Services

In Figure 3 the platform service is abstract. We only want to represent just enough architecture. Azure & Amazon Web Services have commonalities. They use virtual machine managers, and virtual hard disks to realize virtual servers. You can see this in figure 4:

Figure 4

The technology view is showing a number of things. If we had not abstracted to convey this information we would have to create two separate views – One for Microsoft Azure & one for Amazon Web Services. We want to avoid this.

Having that level of abstraction makes it easy to add a new technology service and enables us to be flexible. Lets modify figure 3.

Figure 5

You can see we added Google Cloud and System Centre. Rather than having to create two additional technology views, we need to do nothing, because we have defined the platform service in figure 4.

Over Engineered Products

In big organizations its very easy to get to a point where you are over engineering. In the examples i have shown so far I have been showing a single business service (web hosting service). You can see, that regardless of which platform is used, or which technology, we still only need a single business service, because what we deliver is the same.

In some organizations the product portfolio can be overly complex. For example I have seen limitations in financial models which have lead to breaking things down into products where perhaps they should not be. In Large organizations different services are often provided by different business units which can mean that because of the different units having different levels of responsibility, products might be created in each unit. Something like this can happen:

Figure 6

Because product management processes tend to specify a need for business services we can end up having to unnecessarily create products and business services. This can be a huge cost and complexity overhead. All services need established interfaces, all products have their own team of staff, and services need interfaces defined between each other.

Figure 6 could have existed in an undocumented way. Drawing a view like this makes it clear where complexity exists that does not need to and is one way an EA can show value – reducing unnecessary services and better defining interfaces between the services at the different layers.

Pricing Services

When we have taken away the detail and drawn our services like in figure 5, it becomes significantly more easy to figure how we want to bill things. If we start from figure 5 we might end up representing our pricing components as below

Figure 7 – Adding pricing components.

Defining Interfaces

Back in Figure 2, we showed some interfaces. At a business level our website hosting service is accessible via Email or Web Portal. The Web Portal is realized by a application interface (HTTP Interface) into the website application service. In this case what we are saying is the business service does nothing except expose out the application services.

In the examples I have shown its clear that interfaces should exist for some of the services. that I haven’t detailed in. When I create a layered view I am typically picking and choosing elements, rather than using all connected elements to a service. Other views, such as service realization views, or application cooperation views may show how these interfaces to services exist in more detail.

Functions

Functions are internal behavior units that we do not expose to the outside world. In figure 4 we showed how a technology service was realized. Such a view may have been created by our internal platforms team. The Virtual Machine Manager Function might be very important to talk about to that internal team but would not be something that the sales or product development team need to talk about. If we were to need to relate the virtual machine manager to another team, then we would have created it as a service.

Summing It up…

In future blogs I will be building a lot on the usage of services, because there’s a huge amount that can be done with them. This blog only scratches the surface. Services can be used to reduce complexity and make architecture more light weight and agile. They enable us to focus our architecture efforts. If you are practicing any kind of large scale architecture they are essential.