Formalising system description using templates

This page is published under the terms of the licence summarized in the footnote.

All free-to-read materials on the Avancier web site are paid for out of income from Avancier’s training courses and methods licences.

If you find them helpful, please spread the word and link to the site in whichever social media you use.

 

In 2008, the British Computer Society (BCS) standard reference model for enterprise and solution architecture model was based on a generic meta model of general system theory concepts.

This was/is akin to the generic meta model that underpins the ArchiMate Language (later published as a standard by The Open Group).

And it can be roughly aligned with the more loosely defined concepts of TOGAF.

Are the models the truly aligned? This paper is the last of several papers addressing that question.

It was written primarily to clarify the BCS model by providing documentation templates.

But it may help you interpret ArchiMate and TOGAF concepts as well.

Contents

Enterprise system elements (recap) 1

The four templates to be discussed. 2

System behaviour 4

Processes. 4

Services. 6

System structure. 12

Components. 13

Interfaces. 16

FAQS. 21

 

Enterprise system elements (recap)

The word “architect” comes from the Greek “master builder”, and in enterprise and solution architecture, the buildings are “systems”.

“Enterprise architecture regards the enterprise as a system, or system of systems” (TOGAF)

Architecture descriptions are formal descriptions of a system.” (ArchiMate® 2.1 Specification, The Open Group.)

 

Two fundamental system modelling premises are set out in UML 2.1:

1.      “all behavior in a modeled system is ultimately caused by actions executed by so-called “active” objects”

2.      “behavioral semantics only deal with event-driven, or discrete, behaviors”

 

Enterprise architecture is about activity systems that are:

·         event-driven, and composed of

·         actors (structural elements) that communicate and cooperate in

·         activities (behavioural elements) and maintain information about the

·         state of those actors and activities

 

The table below presents a conceptual framework of generic system elements.

ArchiMate/BCS

Grid

Behavioural view

What a system does

Structural view

What a system is made of

External view

requirements of

external entities

Events/Services

each encapsulates the processing

of a discrete event or service request.

Interfaces

each is a facade that presents

services for access by clients

Internal view

the workings of

the system

Activities/Processes

each comprises one or more activities that

respond to an event or meet a service request.

Actors/Components

each is a subsystem that

performs process steps.

 

One architect’s whole system is another’s component in a wider system, so this model can be applied at any level of granularity.

There is a fifth kind of system element: an object: an item or structure that is used, moved or made by processes.

 

What is the difference between a service and an interface? At what level of granularity should we document services?

What is the difference between a service and a service level agreement?

What is the difference between a process and a component? At what level of granularity should we document processes?

This paper attempts to provide some answers.

 

The best way to understand what an architectural entity represents is to understand what its distinguishing attributes are - how it is documented and how it relates to other entities.

The basic proposal here is that if you can describe a given architectural entity using

·         a flow chart - then it is a process - which can be encapsulated by a service.

·         a Service contract template (without any internal process flow) - then it is a service.

·         an Actor/Component definition template - then it is a component - which can be encapsulated behind an interface.

·         an Interface template (without showing any internal activities or resources) - then it is an interface.

The four templates to be discussed

Note the dependencies section at the bottom of each template.

The principle is to documented relevant inter-entity dependencies at the client/consumer end.

So a server/supplier entity can be documented regardless of who needs it.

But you should still be able find the relevant the needy entities by searching for them.

All is generic and to be adapted to needs.

Process

Process template – or use case definition template (must be adapted to the circumstance)

Signature

 

Name

Inputs

Outputs or results (*)

Trigger

The event that causes the process to start

Rules or

Semantics

Preconditions - the state of the system in which the process is allowed

Post conditions - the state of the system after the process is complete (*)

Process flow

The flow of the process may be defined in narrative, as main and alternative paths.

Or else in a diagram

·         A conventional process flow chart, or

·         Activity diagram, or sequence diagram (UML), or

·         Business process diagram, or Application behaviour diagram (ArchiMate).

·         Business process modelling notation (BPMN)

Non-functional

qualities

 

Response time

Throughput

Availability (derived from reliability and recoverability)

Integrity

Scalability

Security

Serviceability

Etc.

Other non-functionals, dependencies and commercials.

Dependencies

Services needed by the process?

Interfaces needed by the process?

Actors/Components needed by process?

Processes needed by the process?

 

Service

Service contract template (must be adapted to the circumstance)

 

Signature

 

Name

Inputs

Outputs or results (*)

Trigger

The event that causes the process to start

Rules or

Semantics

Preconditions - the system state in which the process is allowed

Post conditions – the system state after the process is complete (*)

Non-functional

qualities

 

Response time

Throughput

Availability (derived from reliability and recoverability)

Integrity

Scalability

Security

Serviceability

Etc.

Other non-functionals, dependencies and commercials.

Dependencies

Interfaces needed by the service?

Actors/Components needed by the service?

Processes need by the service?

Services needed by the service?

 

Actor/Component

Actor/Component definition template (must be adapted to the circumstance)

Name

 

Interface definition

Note: a component may have several interfaces, documented separately

Language spoken

Terms used to request and receive services (if not defined in individual service contracts)

Logical services

Services clients can request of this component.

Access details

Location and connection details clients need to access services

Non-functionals

Location, space, power, skills and other attributes needed (if not documented for each service).

Interfaces

Interfaces offered by this component (if more than one)

Dependencies

Services needed by the Actor/Component?

Interfaces needed by the Actor/Component?

Processes needed by the Actor/Component?

Components needed by the Actor/Component?

 

Interface

Interface definition template (must be adapted to the circumstance)

Name

 

Language spoken

Terms used to request and receive services (if not defined in individual service contracts)

Logical services

Services clients can request of this component.

Access details

Location and connection details clients need to access services

Non-functionals

Location, space, power, skills and other attributes needed (if not documented for each service).

Dependencies

Services needed by the interface?

Actors/Components needed by the interface?

Processes needed by the interface?

Interfaces needed by the interface?

 

System behaviour

Architectural entities are classified into behavioural and structural.

Behavioural (aka dynamic) elements are performed by or accessed via structural elements.

The BCS reference model distinguishes two behavioural concepts: process and service.

Processes

Enterprise architecture is about repeatable, deterministic processes.

A process is logical sequence of one or more steps that leads to a discrete result or value.

A process can be formalised and described in a flow chart with a start and an end.

A process can be executed by one or many Actors/Components.

A process can be decomposed into shorter processes.

What is a process?

 

Process in TOGAF

 “Process should normally be used to describe flow.” 

“A process represents flow of control between or within functions and/or services - a sequence of activities that together achieve a specified outcome - decomposed into sub-processes.”

“Activity: A task or collection of tasks that support the functions of an organization.

For example, a user entering data into an IT system or traveling to visit customers.”

 

A business process is:

·         a sequential flow of activities that runs from trigger to result

·         an end-to-end unit of activity performed by one or more business functions, roles or organisation units

·         a behavioural element, representable in a flow chart or UML sequence diagram.

 

By contrast, a business function is:

·         a node in a function/capability decomposition structure – in which a bottom level (elementary) function corresponds to an activity in a process.

·         a group of activities that are cohesive (usually, requiring the same resources, be it data or skills) with no specified time sequence.

·         an element in an activity structure - an active structural element - a kin to a class in a UML class diagram.

 

Process in ArchiMate

"Behaviour concepts represent the actual behaviour, i.e., the processes and activities that are performed." (The Anatomy of the ArchiMate Language).

 

 

ArchiMate’s generic entities include “behavior element” that is, “a unit of activity performed by one or more active structure elements.” Specific kinds of behaviour element are:

·         Business function/process

·         Application function

·         Infrastructure function.

 

The term function is one of the most ambiguous in all of architecture description. See “What about functions and functionality?”

 

Process in Avancier Methods

Process: One or more activities, triggered by an event or service request, leading to a result or output.

The activities can be arranged under a logical control flow, and are performed by one or more components.

Architects have various ways to define a process: a flow chart, use case definition, interaction diagram or service contract.

How to document a process?

Business processes and software processes can be defined using much the same kind of process specification.

A common form of process contract is a use case.

A use case template wraps the description of a process flow inside the attributes of a service contract (highlighted in yellow below).

The process flow itself can be documented in various styles.

 

Process template – or use case definition template (must be adapted to the circumstance)

Signature

 

Name

Inputs

Outputs or results (*)

Trigger

The event that causes the process to start

Rules or

Semantics

Preconditions - the state of the system in which the process is allowed

Post conditions - the state of the system after the process is complete (*)

Process flow

The flow of the process may be defined in narrative, as main and alternative paths.

Or else in a diagram

·         A conventional process flow chart, or

·         Activity diagram, or sequence diagram (UML), or

·         Business process diagram, or Application behaviour diagram (ArchiMate).

·         Business process modelling notation (BPMN)

Non-functional

qualities

 

Response time

Throughput

Availability (derived from reliability and recoverability)

Integrity

Scalability

Security

Serviceability

Etc.

Other non-functionals, dependencies and commercials.

Dependencies

Services needed by the process?

Interfaces needed by the process?

Actors/Components needed by process?

Processes needed by the process?

 

(*) See later “Results: ambiguities in the meaning of outputs and post conditions.”

What is a meta process?

A meta process is a process about processes.

E.g. the process of documenting a business process at specification time, or the process of monitoring business processes at operation time, as in Business Process Management.

Services

Enterprise architecture is about defining systems that provide services to their clients, customers or other external entities.

A service is a process that a client can request to achieve a discrete result or value.

A service encapsulates a process.

A service can be accessed via one or more interfaces.

What is a service?

This section includes three definitions of "service" that are reasonably consistent with each other.

Service in ArchiMate

“a unit of functionality that  a system exposes to its environment, hides internal operations, provides a value; accessible through interfaces.”

 

All components, interfaces, processes and services have a value to system owners and users, but the value provided by a service is the outcome of a valid service request, which takes the form of a system output and/or a system state change.

 

Specific kinds of service are:

·         Business service

·         Application service

·         Infrastructure service.

 

Named examples from the ArchiMate standard include

·         Policy Creation, Premium Payment,

·         Claim Registration, Claim Payment,

·         Document Printing, Document Scanning.

 

In ArchiMate, services are realised by processes, but can be defined in service contracts without detailing all the processes that deliver them.

 

“The service concept represents a unit of essential functionality that a system exposes to its environment.

For the external users, only this external functionality, together with non-functional aspects such as the quality of service, costs etc., are relevant.

If required, these can be specified in a contract or service level agreement.” (ArchiMate Language Primer).

 

Note that in the templates below, a service contract (defining functional and non-functional attributes) is applicable to a unitary process, whereas the term service level agreement is widely used to mean a legal contractual document covering many discrete services - yet also sometimes used to mean a specific non-functional requirement.

Service in TOGAF

“an element of behavior that provides specific functionality in response to requests from actors or other services.”

 

Specific kinds of service are:

·         Business service

·         Information system service

·         Platform service.

 

“A logical representation of a repeatable business activity, has a specified outcome...

is self-contained, is a ‘‘black box’’ to its consumers.

E.g.

·         check customer credit

·         provide weather data

·         consolidate drilling reports’’.

 

Again, the idea is that a service can be defined without detailing the process (or processes) that deliver it.

 

Terms used in our template

Terms used in the TOGAF 9 service template (sadly removed in version 9.1)

Signature

 

Name

 

Inputs

“Business objects: Business objects (data components) transferred by the service.”

Outputs or results (*)

[Missing: Documented either in Business objects above or Functional requirements below.]

Trigger

The event that causes the process to start

 

Rules or

Semantics

Preconditions - the system state in which the process is allowed

“Invocation preconditions: pre-conditions that must be met by the consumer (authentication, additional input, etc.).”

Post conditions – the system state after the process is complete (*)

“Functional requirements: what this service accomplishes: allows test cases to prove the functionality is accomplished.” (*)

Non-functional

qualities

 

Response time

“Service Level Agreement [sic!] the amount of latency the service is allowed to have to perform its actions.”

Throughput

“Throughput: volume of transactions estimated; E.g. 100,000 per day.”

Availability (derived from reliability and recoverability)

“Service times: the available hours/days the service is needed; for example, 9 to 5 weekdays (excluding Bank Holidays).”

Integrity

 

Scalability

“Growth: growth of transactions over time (estimate based on service take-up and business growth); e.g., 10,000 per year.”

Security

“Security requirements: Who can execute this service in terms of roles or individual partners, etc.

 

and which invocation mechanism they can invoke.”

Serviceability

 

Etc.

Other non-functionals, dependencies and commercials.

“Behavior characteristics: The criteria and conditions for successful interaction and any dependencies on other service interactions, etc..”

 

Service in Avancier Methods

Service: The external view of the process that responds to a singular event or service request.

A service encapsulates processes needed to deliver the desired result, and is describable using a service contract (that obscures the internal workings – the components and processes - that provide the service).

E.g.

·         Haircut, Shampoo, Manicure

·         Book theatre seat, Register purchase order

·         HTTP get, put, post or delete operation

·         Transaction start, commit or rollback

How to document a service contract?

Business services and software services can be defined using much the same attributes.

Below are two definitions of the attributes you might document in a service contract.

The service contract template above lists attributes under three headings: signature, semantics or rules and non-functionals.

The table lists the attributes in TOGAF 9’s service contract template under the same headings.

 

Service contract template (must be adapted to the circumstance)

 

Signature

 

Name

Inputs

Outputs or results (*)

Trigger

The event that causes the process to start

Rules or

Semantics

Preconditions - the system state in which the process is allowed

Post conditions – the system state after the process is complete (*)

Non-functional

qualities

 

Response time

Throughput

Availability (derived from reliability and recoverability)

Integrity

Scalability

Security

Serviceability

Etc.

Other non-functionals, dependencies and commercials.

Dependencies

Interfaces needed by the service?

Actors/Components needed by the service?

Processes need by the service?

Services needed by the service?

 

* Results: ambiguities in the meaning of outputs and postconditions

If I invoke the service to book a train ticket, I guess the system will respond by sending output messages to

·         me, and my bank.

·         the train seat booking agent, and their bank.

·         the train operator.

 

Which of those entities are inside and outside the system being described depends on where we draw the boundary.

 

We could divide the direct results of an event or service request into:

·         outputs returned to the original servicer requester.

·         outputs sent to other entities.

·         outputs to, or updates of, a shared data space – which can be read by any entity with access to that shared data space.

·         other post conditions - changes to the internal state of the service provider – which can be interrogated by any entity who interacts with the service provider.

 

And what about the indirect results of an event or service request? That is, the outcomes that happen when external entities use the outputs given to them?

Those outcomes may be the main purpose of the system.

(E.g. I actually get a seat on the train.)

 

There are ambiguities here: internal system state changes overlap with system outputs and their outcomes in the environment.

E.g. The effect that an external entity desires may be an internal system state change.

And external entity may be sent an output message signalling whether an internal state change has been achieved or not.

Examples

Business domain example 1

A business service offered by Barber shop Enterprise Inc.

Signature

 

Name

Haircut

Inputs client should provide

Required hair length

Required hair style

Desired outputs or results

Client’s hair in required style and length (see also post conditions)

Semantics or rules

 

Preconditions - the state of the system in which the event is allowed

Barber shop resources ready

Barber available

Post conditions - the state of the system after the event is complete

All due monies received

Some degradation of physical resources.

Non-functionals

 

Response time

30 minutes

Throughput

6 per hour

Availability

90% waiting times less than 20 minutes from 09.00 to 17.00

Integrity

97% no complaint or refund

Scalability

Security

 

Serviceability

 

Etc.

Other non-functionals, dependencies and commercials.

30 dollars

 

Business domain example 2

A business service offered by a car hire company

Signature

 

Name

Car hire

Inputs client should provide

Pick up location and time

Return location and time

Required car type

Desired outputs or results

Use of car for duration required

Semantics or rules

 

Preconditions - the state of the system in which the event is allowed

Instance of required car type available at pick up location with full tank

Deposit received

Post conditions - the state of the system after the event is complete

Car at return location with full tank of petrol

Some miles on the clock

Some depreciation of car value

All due monies received

Non-functionals

 

Response time

90% of bookings < 5 minutes

Throughput

See location capacity

Availability

See location opening times

Integrity

See break down service terms and conditions

Scalability

 

Security

Car must be locked when not being driven

Serviceability

See car servicing arrangements

Etc.

Other non-functionals, dependencies and commercials.

 

 

Business domain example 3

A business service offered by an IT Service Provider

Signature

 

Name

Software development

Inputs client should provide

Requirements catalogue

Desired outputs or results

Software package that passes UAT

Semantics or rules

 

Preconditions - the state of the system in which the event is allowed

Human and technology resources available

Post conditions - the state of the system after the event is complete

All due monies received

Project lessons learned

Marketing case study

 

Response time

1 month for15 function points

Throughput / capacity

100 developers

Availability

100% (back up capacity provided by associates)

Integrity

Product quality assured UAT

See issue handling procedures

Scalability

200 developers in one year

Security

See IP and security terms

Commercials

See day rates

Etc.

 

Infrastructure domain example

An infrastructure service offered by an infrastructure component

Signature

 

Name

get

Inputs client should provide

Remote file name

Local file name

Desired outputs or results

Reply = OK or Fail (see post conditions)

Semantics or rules

 

Preconditions - the state of the system in which the event is allowed

Remote computer can be reached.

Remote file exists in the current remote directory.

Post conditions - the state of the system after the event is complete

Remote file copied to (or on top of) local file current local directory.

Non-functionals

 

Response time

30 seconds

Throughput / capacity

20 per minute

Availability

99.99%

Integrity

100% perfect file copy

Scalability

Up to 100 per minute

Security

No encryption

Serviceability

 

Etc.

Other non-functionals, dependencies and commercials.

 

 

How to show a service in a diagram? See postscript 1.

What is a meta service?

A meta service is a services about service, e.g.

·         show me the interface, or menu of services, you offer

·         tell me how to invoke service x

·         tell me the cost or other non-functional characteristic of service x.

 

A meta service can generate an alert or graph about data aggregated from several services or components, e.g.

·         number connected to an application/server/firewall/network device.

·         bandwidth used by routers

·         power consumption of servers

·         HTTP response time

·         CPU occupancy rate.

How else might the term service be used?

To infrastructure architects, a service is often the availability of all a component’s various functions/capabilities.

E.g. an HTTP server provides an HTTP service.

 

Similarly, to some business architects, a service is the availability of all an organisation’s various functions/capabilities.

E.g. The Marketing department provides a Marketing service.

 

Be wary of EA diagrams that show a component and a service in 1-to-1 correspondence.

The service may be a relabeling of the component, or an interface to it, rather than a discretely requestable service of the kind defined above.

See postscript 1.

System structure

Architectural entities are classified into behavioural and structural.

Structural elements are deployed in locations to do work - to deliver the behaviour required of the system.

The BCS reference model distinguishes two structural concepts: component and interface.

Components

A component is a subsystem that can be deployed in a location and execute one or more processes.

 A component can be decomposed into smaller components.

What is a Actor/Component?

Enterprise architecture is very much about standardisation of the roles that components play in performing required processes to deliver required services.

In effect, in architecture definition, the component is the role it is defined as playing.

 

Component in ArchiMate

The ArchiMate generic meta model includes: “Active structure element: an entity capable of performing behaviour.”

 

Specific kinds of active structure element are

·         business role

·         application component

·         infrastructure node: system software or computing device.

 

Component in TOGAF

In TOGAF: the term “building block” is used with wider and narrower meanings.

It is used loosely to mean any architectural entity in the TOGAF meta model, including not only components but also processes, goals and locations.

 

“Building block” is also used more narrowly to mean a component, to

“represent a (potentially re-usable) component of business, IT, or architectural capability that can be combined with other building blocks to deliver architectures and solutions”

 

E.g. in TOGAF, an application component is an encapsulation of application functionality.

A technology component is an encapsulation of technology infrastructure.

 

Note this complication: TOGAF describes logical components separately from physical components.

It assigns services to logical components, and then assigns logical component to physical components.

In some places, it appears that a logical component is akin to an interface; in other places it appears to be merely an abstract candidate component description.

 

TOGAF’s logical architecture building blocks include:

·         Functions: units of business capability at all levels of granularity.

·         Roles: the expected functions of actors.

·         Logical application components.

·         Logical technology components.

 

Physical solution building blocks include:

·         Organization: a self-contained unit of resources with line management responsibility, goals, objectives, and measures.

·         Actor: A person, organization, or system that has a role that initiates or interacts with activities; for example, a sales representative who travels to visit customers.

·         Actors may be internal or external to an organization.

·         In the automotive industry, an original equipment manufacturer would be considered an actor by an automotive dealership that interacts with its supply chain activities.

·         Physical application components.

·         Physical technology components.

 

Component in Avancier Methods

A component type is a role, defined in essence by: the services it can offer externally, the activities it can perform internally and the resources it needs.

 

A component instance is a subsystem that can be deployed in a location and execute one or more processes.

A component instance is an actor capable of playing a role.

“May be a person, a human activity system or a software system.

E.g. BACS, salesforce.com, a sales executive, a customer, an auditor.”

 

In a restaurant, the component types include waiter, cook, oven and dishwasher.

 

(There is a limit to how far you can push the analogy between human and computer activity systems, since humans are inventive and flexible.

In the fuzzily-defined human activity system that is a restaurant, an actor employed to be a waiter may behave spontaneously and be asked to play another named role – say dishwasher.)

How to document a Actor/Component definition?

A complete definition defines both external and internal views of a component or role.

(Object-oriented software designers will at this point think of a class specification.)

 

Actor/Component definition template (must be adapted to the circumstance)

Name

 

Interface definition

Note: a component may have several interfaces, documented separately from the component

Language spoken

Terms used to request and receive services (if not defined in individual service contracts)

Logical services

Services clients can request of this component.

Access details

Location and connection details clients need to access services

Non-functionals

Location, space, power, skills and other attributes needed (if not documented for each service).

Interfaces

Interfaces offered by this component (if more than one)

Dependencies

Services needed by the Actor/Component?

Interfaces needed by the Actor/Component?

Processes needed by the Actor/Component?

Components needed by the Actor/Component?

 

How far to complete a Actor/Component definition? If you document only the name and external view, then the definition might be called a logical component, or an interface.

 

TOGAF says: “at an early stage, a building block can simply consist of a name or an outline description.

Later on, a building block may be decomposed into multiple supporting building blocks and may be accompanied by a full specification.”

 

How to show components and interfaces in a diagram?

The value of separating interface boxes from component boxes is to show where one interface hides several components, or one component has several interfaces.

Where they are one-to-one, drawing separate boxes may be overkill.

How to assign processes to a Actor/Component?

"Behavioural concepts are assigned to structural concepts, to show who or what displays the behaviour." (ArchiMate Language Primer).


The term "assign" can also be used the other way around.

"The active structure concepts can be assigned to behaviour concepts, to show who (or what) performs the behaviour." (The Anatomy of the ArchiMate Language).

 

The presumption in most methodologies (E.g. in TOGAF) is that required behaviours (services and processes) are defined before the structures (interfaces and components) needed to execute them.

It is normal to assign the many processes provided by a system to fewer components (which might take the form of roles, machines, applications, platform technologies).

Given 100 processes, whether you assign them to 5 large components or 20 small ones makes no difference to the processes the system is capable of executing.

 

Assignment of processes to components is a somewhat arbitrary design decision.

Looking for a logical grouping, you could reasonably assign to one component

·         All the processes required by one external client or customer.

·         All the fine-grained processes involved in one “end-to-end” process

·         All the processes provided by a component you purchase.

 

If you purchase components, you risk assembling a system in which different components can perform the same process, and some components can perform processes you don’t want.

If you employ human components, you may expect them to use their inventiveness and flexibility to do the right thing regardless of what your specification says (sic).

What is Structured Analysis?

Q) When is a business function not a function (in the process sense)?

A) When it is discussed using the language of an EA framework in which a business function is a business component, role or capability, rather than a business process.

TOGAF says that Structured Analysis identifies the key business functions within the scope of the architecture, and maps those functions onto the organizational units within the business.

See Avancier Methods for more about how business processes, business functions and business roles are defined in traditional or conventional structured analysis.

Interfaces

Perhaps the biggest debatable question in these papers is whether an interface is best described as:

·         a menu – a passive structural element - an abstract specification listing service offered

·         a water – an active structural element - a role that presents a menu - a facade component that accepts service requests and directs them for processing

 

In ArchiMate, it appears that an interface is the latter - a facade - it is a point of access - found at a specific location.

Here also, an interface is a facade - a point of access to a collection of one or more discrete services – including location and connection details.

An interface can expose (make accessible) one or more services.

An interface encapsulates a component.

What is an interface?

The British Computer Society (BCS) reference model for enterprise and solution architecture points out that the word interface has many possible meanings, distilled here as:

  1. A façade that presents one or more services for access by clients
  2. A passive service contract or catalogue.
  3. A data flow or message between sender and receiver components.
  4. The protocol standards or technologies use to exchange data.
  5. The physical channel or medium via which data flows are passed.

 

ArchiMate says of interfaces:

·         “a point of access where services are made available to the environment”.

·         “Services are accessible through interfaces, which constitute the external view on the structural aspect.”

·         “hide the internal structure of the service provider”.

 

Specific kinds of interface in ArchiMate are:

·         “Business Interface: declares how a business role can connect with its environment.

·         “Application interface: declares how a component can connect with its environment.

·         “Infrastructure interface: a point of access where the functionality offered by a node can be accessed by other nodes and application components.”

 

The interface of one role, application or node may include or many discrete services.

And conversely, one service can be exposed by more than one interface.

 

"An interface is a (physical or logical) location where the functionality of a service is exposed to the environment.” (The Anatomy of the ArchiMate Language).

 

To enable a client of a service (an external entity in the environment of the system) to access a service, the interface must declare location and connection details for each service it declares to be accessible.

 

A component whose job is to expose what might be called a "system interface" is often called façade component.

Such an external-facing façade component may encapsulate and be implemented by any number of internal components.

 

“Although for the external users only the external view is relevant, the design of organisations or systems and their internal operations and management also requires knowledge about the internal realisation of the services and interfaces." (ArchiMate Language Primer).

 

An external-facing interface hides the internal structure of a system; it is realised or implemented by internal components.

Every component can be encapsulated behind an interface.

It is not normal practice to divide every component into two – a façade component and an active worker component – 

but it is normal to separate the external and internal features of a component in its specification.

 

In TOGAF, the term interface is ambiguous, but in the “interface catalogue” and most places it is number 3 in the BCS list above; it is a data flow to, from or between application components.

 

In Avancier Methods, an interface is 1 in the BCS list above.

You can think of it as a waiter (a façade component) that presents a menu of requestable services.

 

(Humans are inventive and flexible. An earlier paper discussed the limit to how far you can push the analogy between human and computer activity systems.

In the fuzzily-defined human activity system that is a restaurant, an actor employed to be a waiter may behave spontaneously and be asked to play another named role – say dishwasher.)

 

How to document an Interface?

Below is a simple interface definition template, excluding the details you may record for a façade component that presents the interface.

 

Interface definition template (must be adapted to the circumstance)

Name

 

Language spoken

Terms used to request and receive services (if not defined in individual service contracts)

Logical services

Services clients can request of this component.

Access details

Location and connection details clients need to access services

Non-functionals

Location, space, power, skills and other attributes needed (if not documented for each service).

Dependencies

Services needed by the interface?

Actors/Components needed by the interface?

Processes needed by the interface?

Interfaces needed by the interface?

 

Each named service can be defined separately in a service contract.

In a simple case, all the services in the interface definition share the same non-functional requirements, but that is not the general case.

Suppose the interface itself is "available" 99% of the time.

Its various services may be less available; each may have different dependencies on different lower-level services, each with their own non-functional requirements.

 

Business domain example: the standard interface for a barber shop run by Barber shop Enterprise Inc.

Each named service can be defined separately in a service contract.

Barber shop interface

Interface Name

Barber shop

The interface implemented in each of our chain of barber shops by barbers we employ using resources we provide.

Logical services

Haircut

 

Shampoo

 

Haircut + shampoo

A coarse-grained service that aggregates the meanings/rules of two services above, with different non-functionals.

Manicure

 

Access details

Address

99 Main Street

Telephone number

999 999 999

 

Infrastructure domain example: an  interface definition that includes the “get” service defined earlier in a distinct service contract.

File Transfer Protocol (FTP) with a selection of services offered

FTP

An interface implemented by a platform component whose role is to copy files to and from computers.

 

The following services are expressed as in the common FTP utility program on a UNIX computer.

Service name

Summary description of service contract

?

to request help or information about the FTP commands

ascii

set the mode of file transfer to ASCII

bye

exit the FTP environment (same as quit)

cd

change directory on the server computer

close

terminate a connection with another computer

delete

delete (remove) a file in the current remote directory (same as rm in UNIX)

get ABC DEF

copies file ABC in the current remote directory to (or on top of) a file named DEF in your current local directory.

get ABC

copies file ABC in the current remote directory to (or on top of) a file with the same name, ABC, in your current local directory.

help

request a list of all available FTP commands

mget

copy multiple files from the server computer to the client computer; you are prompted for a y/n answer before transferring each file

mput

copy multiple files from the client computer to the server computer; you are prompted for a y/n answer before transferring each file

open

open a connection with another computer

put

to copy one file from the client computer to the server computer

quit

exit the FTP environment (same as bye)

rmdir

to remove (delete) a directory in the current remote directory

 

Note about this FTP interface:

·         each listed service may have its own rules and non-functional requirements (defined in its service contract).

·         “help” is a meta service

·         there are two names for one of the services

·         most services trigger what appears at this level to be a single activity, but some trigger a process requiring further steps from the client before it completes.

What is a Service Level Agreement (SLA)?

Conventionally (in ITIL and elsewhere) an SLA is a legal document or other formal interface definition that defines the services a client can request of a server.

It commonly starts with some definitions and legal mumbo jumbo, then goes on to list - perhaps in a schedule at the end – a menu or one or many discrete services of the kind that could be defined using the service contract form above.

 

A SERVICE LEVEL AGREEMENT TEMPLATE

General terms and conditions

Definitions and Interpretation

Term of Agreement

Service Provider’s Obligations

Client’s Obligations

Fees, Payment and Records

Provision of the Services

Service and Agreement Monitoring

Performance Management and Monitoring

Confidentiality

Intellectual Property Rights

Termination

Post-Termination

Liability and Indemnity

Force Majeure

Nature of the Agreement

Severance

Relationship of the Parties

Notices

Law and Jurisdiction

Schedules include

List of individual Services with the following Measurable Qualities

·         Service Levels

·         Performance Monitoring

·         Performance Reports

·         Fees and Payment & Penalty Fees

·         Etc.

 

An ambiguity and potential source of confusion arises when the term service level agreement (SLA) is used to mean one or more non-functional requirements.

E.g. TOGAF uses the term SLA to mean response time.

How to assign services to an interface?

"Behavioural concepts are assigned to structural concepts, to show who or what displays the behaviour." (ArchiMate Language Primer).

Note however, that the term "assign" can also be used the other way around.

 

"The active structure concepts can be assigned to behaviour concepts, to show who (or what) performs the behaviour." (The Anatomy of the ArchiMate Language).

 

There is a presumption in most methodologies (E.g. in TOGAF) that required behaviours (services and processes) are defined before the structures (interfaces and components) needed to execute them.

It is normal to package the many services (which you might call abstract operations) provided by a system into fewer interfaces (which might take the form of contracts, user interfaces, web services, APIs whatever).

Given 100 services, whether you assign them to 5 large interfaces or 20 small ones makes no difference to the overall functionality available to external clients of the system.

 

Assignment of services is a somewhat arbitrary design decision.

Looking for a logical grouping, you could reasonably collect into one interface.

·         All the services required by one external client role or business function.

·         All the fine-grained services clients require to execute one “end-to-end” process (which might itself be encapsulated behind a more coarse-grained service at a higher level of system description).

·         All the services provided by one component within the system.

 

You could in theory create interfaces for each of these clashing views, since one service may appear in several interfaces, but that is probably overkill in practice.

Are business rules shareable between architectures?

Rules are usually defined in architecture descriptions as:

·         Preconditions and/or post conditions of services (or process steps)

·         Constraints on and/or derivation rules for data items.

 

Wherever two systems (described in two architectures) share the same services or data items, the associated rules can be shared between architectures in the form of shared architecture description artefacts, most obviously:

·         A shared service catalogue

·         A shared canonical data model.

FAQS

Will a named entity always be represented the same way in a diagram?

No.

Suppose your diagram notation offers different symbols/boxes for process, service, component and interface.

First, as a reader of an architectural diagram you have to consider: Does the diagram drawer attach the same meanings to service, process, component and interface as I do? And even then, a given entity may been shown in different ways in different diagrams.

What is a Web Service?

In software architecture, in Web Services Definition Language, a Web Service is a façade component that presents a menu of operations for access by clients.

Each operation is a unitary process that provides a value - as the ArchiMate definition says of a service.

E.g. check customer credit returns the value accepted or rejected.

Each operation is definable by a service contract.

So, the most natural correspondence between the language of Web Services and the language of ArchiMate is this:

 

WSDL term

BCS and ArchiMate term

Web Service

Interface

Operation

Service

 

Q) When is a web service not a service? A) When it is discussed using the language of an EA framework in which a web service is documented as an interface and a web service operation is documentable using a service contract.

What is an FTP Service?

Is it a process, service, component or interface? The answer depends on what you are trying to describe.

FTP could be the name of a component or an interface in the infrastructure layer.

It could be an attribute of a data flow or a service in the application layer.

 

FTP could reasonably appear in an infrastructure architecture layer diagram as the name of:

·         an FTP component, system software, in or on an operating system

·         the interface to an FTP server node/component

·         an artifact deployed to a server node/component

·         an annotation on a network connection or "used by" arrow.

 

FTP could also reasonably appear in an application architecture layer description as the name of:

·         an attribute of a data flow between application components

·         an attribute of a service (E.g. an operation in a web service).

 

So, FTP may be represented in a diagram in various ways.

But – in our terms - the one thing you don’t expect to see is “FTP Service” shown as a Service.

FTP is not a unitary process that provides a value to a client.

A service is requestable FTP operation such as “get”.

When you bundle FTP operations together, it is not a coarse-grained service, it is rather an interface or a component.

 

In practice, I have seen FTP as the name of an attribute of an application service, and as the name of system software component deployed to a virtual node, itself deployed to one or more physical nodes.

 FTP is an interface, but I have yet to see it as the name of an interface (tennis racket) box in a diagram.

 Wouldn't that be overkill in most practical architecture diagrams?

What is a Network Interface Controller (NIC)?

Is it a process, service, component or interface? Wikipedia offers several definitions of interface (computing), as a point of interaction.

The three definitions that fit our model best are:

 

"User interfaces provide a means of input, allowing the users to manipulate a system, and output."

 

"A Network interface is an interface between two pieces of equipment or protocol layers in a network.

A network interface will usually have some form of network address.

This may consist of a node Id and a port number or may be a unique node Id in its own right.

Network interfaces provide standardised functions such as passing messages, connecting and disconnecting etc. etc."

 

"Interface in object-oriented programming is a protocol… a common means for unrelated objects to communicate with each other.
These are definitions of methods and values which the objects agree upon in order to cooperate.
The protocol is a description of:

·         The messages that are understood by the object.

·         The arguments that these messages may be supplied with.

·         The types of results that these messages return.

·         The invariants that are preserved despite modifications to the state of an object.

·         The exceptional situations that will be required to be handled by clients to the object.

If the objects are fully encapsulated then the protocol will describe the only way in which objects may be accessed by other objects.

 

We have labelled four core concepts: Process, Service, Component and Interface.

So, which of these is a network interface controller (NIC)?

 

Wikipedia says: "A network interface controller (NIC) is a computer hardware component that connects a computer to a computer network."

 

OK but you may say Wikipedia has no reference model.

Each Wikipedia entry is written on its own; there is no standardisation of what component or interface means.

Nevertheless, in our terms, a protocol (such a FTP, HTTP) defines an interface.

So a NIC is indeed most naturally regarded as a component.

It is a network node that can host many interfaces, each for a specific protocol (associated with a node Id and port number).

What is Service-Oriented Architecture (SOA)?

Everything said so far is generic; it can be applied to any human or computer activity system.

It predates modern software design by decades.

It includes statements of principle that general systems theorists like von Bertalanffy and Ross Ashy would have been comfortable with in the 1950s.

Since the turn of the century it has been fashionable to promote SOA. But what does it mean? Find the SOA papers at Avancier.co.uk.

What does “coarse-grained” mean?

How do you assess the granularity, the size and/or complexity, of a process? There is no simple answer.

Are we talking about the system in description or the system in operation?

Do we measure the process by counting the steps and conditions in its definition?

Or measure it as including all “lower-level” processes it depends on?

 

·         It might be assumed that business processes are more coarse-grained than the application processes they require, which are in turn more coarse-grained than the infrastructure/ platform processes they require. But client and server roles might be reversed; a single “coarse-grained” application process may require a business process to be executed before the application process can complete

 

·         It might be assumed that application processes at the human-computer interface (use cases) are more coarse-grained than subordinate automated processes - provided by one small-scale application component to another. But the longer process seen by the human may be a lot simpler than any of the automated services it relies on.

 

What is a coarse-grained service? It is defined here as a higher-level service that depends on lower-level services to complete and return a specified value (an output and/or system state change).

 

But the term is used so loosely it undermines the conceptual differences between service, interface and component.

Consider for example, the term “FTP Service”.

FTP is not a unitary process providing a value to a client.

Rather, it is a collection of requestable processes -  FTP operations such as “get” – each a discrete service.

 

If you group some sheep together, the aggregate is not a coarse-grained sheep, it is a flock.

When you bundle FTP operations together, it is not a coarse-grained service, though it might well be an interface or a component.

Components and interfaces may offer many services, but they are not themselves services.

 

So, how do you assess the granularity, the size and/or complexity, of one requestable service? There is no simple answer.

Are we talking about the system in description or the system in operation? Do we measure the service by counting elements in its definition, or measure it as including all “lower-level” services and operations it depends on?

 

Which is more the most coarse-grained service? Tell me the time? Check customer credit? Theatre seat booking? Transaction commit? It may be impossible to tell.

A service contract can be short and simple, yet hide large and complex internal workings.

A service requester need not know, and may not be able to find out, how much work is done behind the scenes.

 

However, you (being clever and knowledgeable) probably do know something of what goes on behind the scenes in examples listed above.

Or you think you do.

 

Tell me the time.

·         If you request this service of a human, you know it requires the extremely complex biochemistry, knowledge, cognition processes and vocalisation ability of a human being, and so might regard it as a coarse-grained service.

·         If you ask the same of a computer, you may guess the internal processing is relatively simple, and regard it as a relatively fine-grained service.

 

Transaction commit.

·         If you request this service of a discrete database it probably involves (wild guess) 10,000 elementary executable operations at the operating system level.

·         If you ask the same of a distributed database it requires (wild guess) 1,000,000 elementary executable operations at the OS and network level.

 

It might be assumed that business services are more coarse-grained than the application services they require, which are in turn more coarse-grained than the infrastructure/ platform services they require.

But client and server roles might be reversed; a single “coarse-grained” application service may require a human business service to be executed before the application service can complete.

 

Service granularity varies within one architecture domain.

Application services at the human-computer interface (use cases) are more coarse-grained than subordinate automated services - provided by one finer-grained application component to another.

 

How big is a process? How big is a service? How big is an application component? We would have to agree how to measure the size and complexity before we could answer.

There are no simple or widely agreed answers to such questions.

What is the right level of granularity of system description?

The general answer is - the level at which architects, sponsors and important stakeholders believe the architecture description is complete enough that the costs, benefits and risks are well enough understood (the cone of uncertainty has narrowed enough) to proceed to the next stage of design, solution selection or development.

 

What is the right granularity of process definition/decomposition?

The right level of detail or granularity in the specification is the level at which clients express their required processes, and so scope the system.

And there are two more specific answers in Avancier Methods:

·         Decompose business processes to the OPOPOT level

·         Decompose application processes to the transaction (commit unit) level.

 

Given a large system, where the number of discrete processes is too large to be documented in given time and resources, the architect must prioritise, attend to the most important or mission-critical and architecturally significant (complex, costly or risky in some other way).

 

You could provisionally cluster required processes into groups.

But the name of that group is generalisation or a draft component name rather than a process name.

 

What is the right granularity of service definition/decomposition?

The right level of detail or granularity in the specification of provided services is the level at which clients express their required services, and so scope the system.

 

Given a large system, where the number of discrete services is too large to be documented in given time and resources, the architect must prioritise, attend to the most important or mission-critical and architecturally significant (complex, costly or risky in some other way).

 

You could provisionally cluster required services into groups.

But the name of that group is likely to be a generalisation or a draft interface name rather than service name.

How are these ideas used in an EA methodology?

Enterprise architecture (EA) is focused on enabling and improving business roles and processes that are repetitive and deterministic enough to be systematised and digitised.

In other words, it does not focus on roles and processes that are informal, ad hoc and continually changing.

 

The natural starting point for all systems analysis and design is a systemic or holistic view.

 

1.      identify the input/output services that clients require of the system.

2.      define the processes needed to provide those services.

3.      define the components needed to execute the process.

4.      package the services into interfaces for presentation to clients.

 

Note that an interface is a distinct kind of entity (rather than a coarse-grained service).

Should we merge architectural entities in one-to-one correspondence?

Design involves choosing the level of abstraction for specification, deciding how architectural entities will be hierarchically composed and decomposed, and relating them to each other.

 

The obvious reason to separate the external and internal views of a system is hide internal complexity,

to hide several internal processes behind one external-facing service contract, or hide several internal components behind one external-facing interface.

If the external view is one-to-one with the internal view, then it does not hide complexity.

 

Note however that external and internal concepts can always be paired off; they can be specified at the same level, in one-to-one correspondence.

 

·         Every process can be encapsulated behind a service contract.

·         Every component can be encapsulated behind an interface definition.

 

This leads to redundancy in graphical models that use different symbols for the two concepts (two boxes where one would do).

So my in-practice suggestion is:

·         How to show components and interfaces in a diagram? The value of separating interface boxes from component boxes is to show where one interface hides several components, or one component has several interfaces.

·         Where they are one-to-one, drawing separate boxes may be overkill.

·         Where an interface is bound to a component at one location, the two may be described together in a Actor/Component definition, and shown in a diagram as a one component box.

·         Similarly, how to show a processes and services in a diagram? The value of separating service boxes from processes boxes is to show where one service hides several processes, or one process implements several services.

·         Where they are one-to-one, drawing separate boxes may be overkill.

·         Where one service is implemented by one process, the two may be described together using a “use case” template, and shown in a diagram as one process box

Can we use formal system description notations in abstract diagrams?

This paper emerged out discussions about:

·         the meanings of the five entities in ArchiMate generic meta model.

·         how those semantics are inherited or extended in three specific instances of that generic model in the meta model that defines the ArchiMate language

·         what it means to abstract the description of a large and complex system.

 

Clearly, the large enterprises and systems we are talking about do feature discrete events and services that are recognised by key stakeholders (clients or customers of the system).

Examples in the ArchiMate standard examples include “scan document” and “print document”.

 

It does not matter how large the enterprise/system is, whether clients want ten or ten thousand such services, or how complex the system's internal processes and component structure are.

Client/customers know what atomic, discrete, services they want to request (or they come to know as we work with them to define a system).

The services are the "external behaviour" they require; they define the scope of the system we are to buy or build for clients.

 

When we model a discrete event or service (say, Register purchase order), we can and often do specify very particular facts.

Attributes may include for example, preconditions, post conditions, response time, and transaction cost.

 

The first trouble is, given a system featuring a thousand discrete events and services, we need to abstract.

If we are to show the system scope to system and stakeholders (not just end users and builders), we must abstract from the bottom level of documentation in diagrams or views of the system.

 

We can abstract by drawing one or more higher level diagrams that simply omit less important events and services.

Or we might build a generic model featuring super-type or meta events and services.

In these cases, the rich semantics of the box and line symbols in a language like UML or ArchiMate may still be useful.

 

People often abstract by grouping elementary architectural entities - by aggregation or composition.

Then the second trouble is: an aggregate does not have the same attributes as a discrete architectural entity, a menu is different from a menu item, a flock is different from a sheep.

Since an aggregate does not have the same attributes as a discrete architectural entity – it cannot be documented using the same template.

 

If the architectural entities in diagrams are aggregates, then the rich semantics of the box and line symbols in language like UML or ArchiMate are not so useful.

Having grouped services into an interface or other kind of aggregate, it may not be meaningful to speak of the aggregate as having preconditions, post conditions, a response time, or a transaction cost (except at a meta service level).

 

As we abstract diagrams to show higher level aggregates and generalisations, not only does the content get lighter (fewer boxes and lines), but the meanings get lighter - the semantics of the diagrams become fuzzier and fuzzier.

As we abstract, inter-box relationship lines degenerate to bland association lines.

 

At a high level of abstraction, we might use UML or ArchiMate symbols to draw the diagrams (since we use them at a lower level).

But if we are no longer using the symbols with their meaning in the language standard, then might we better avoid using a language with such rich semantics? Or else, use a restricted subset of UML or ArchiMate?

 

 

Footnote: Creative Commons Attribution-No Derivative Works Licence 2.0         01/12/2015 19:47

Attribution: You may copy, distribute and display this copyrighted work only if you clearly credit “Avancier Limited: http://avancier.co.uk” before the start and include this footnote at the end.

 

No Derivative Works: You may copy, distribute, display only complete and verbatim copies of this page, not derivative works based upon it.

For more information about the licence, see  http://creativecommons.org