ServiceTechMag.com > Archive > Issue LV: October 2011 > Mapping Service-Orientation to TOGAF 9 - Part IV: Applying Service-Orientation to TOGAFs Service Contracts
Fillipos Santas

Filippos Santas

Biography

Filippos is an IT Architect for Credit Suisse Private Banking in Switzerland and a SOASchool.com Certified SOA Trainer, Analyst, Architect, Consultant, and Security Specialist. Additionally, he is certified by The Open Group on TOGAF 9 and by IBM on the Rational Unified Process V7.0. In the last 10 years, Filippos has been the lead for the analysis and architecture of a number of successful SOA projects and for transforming legacy architectures to service-oriented architectures, primarily in the financial sector. His achievements include the conceptual and physical design of the international insurance claims service network that connects insurance policies, customer companies and state authorities in 44 countries across the globe, combining legislation, business processes, business rules, business objects, knowledge bases and different platforms.

Filippos recent work with Credit Suisse has been as an SOA Architect, combining the profitable and established functionality of legacy systems with centralized business process services, decentralized business rule services, domain specific BOMs and entity services and end-to-end traceability to business requirements and processes.

Contributions

rss  subscribe to this author

Bookmarks



Mapping Service-Orientation to TOGAF 9
Part IV: Applying Service-Orientation to TOGAF's Service Contracts

Published: October 12, 2011 • Service Technology Magazine Issue LV PDF
 

In this series of articles we examine the correspondence and synergies of service-orientation and The Open Group Architecture Framework. In parts I and II of this article we went through the phases related to architecture definition, service design and implementation, architecture adoption and vision, the main roles, and the implementation and governance of multiple service inventories using hierarchies of the TOGAF ADM. In the process, we also examined the synergies between the two methodologies.

In the last article of this series we examine the level of abstraction that is necessary to apply service contracts in TOGAF, using service-orientation principles and patterns.


Service Contracts in SOA and TOGAF

One of the primary focal points of the service-orientation paradigm is the design and standardization of service contracts. In TOGAF and in SOA, the contracts are important in communicating and enforcing functionality, policy/structure requirements, and constraints between different pieces of heterogeneous software. The favorite metaphor used for describing the ability of service contracts to provide a healthy provider/consumer relationship, is the way in which business contracts establish an agreement and maintain trust in a commercial relationship between parties. The difference between service-orientation and TOGAF is how detailed this agreement is, and how the provider and consumer interact.

Service-orientation recommends a high level of abstraction for the information provided in the contract. This is because one service should be used by many different kinds of consumers (Service Reusability principle). In order to accomplish the desired level of abstraction without compromising the precision or usefulness of the information in the contract, service-orientation applies principles such as the Standardized Service Contract and the Service Loose Coupling early in the analysis process.

On the other hand, TOGAF considers contracts to be unique to a specific provider/consumer relationship, and they act as the container for both formal policies, as well as agreements that are unique to the parties. This implies that the contract published by the service provider is coupled to the consumer.


Technical Interfaces, SLAs and Capabilities

In service-orientation the technical interface is the part of the service contract. The technical interface provides the following:

  • meta information about the service
  • requirements (used by service consumers) for interacting with the service.

A technical interface includes a set of service capabilities (or operations). Each capability offers a subset of the functionality of the service. Service consumers invoke the capabilities in order to gain access to the desired functionality.

Additionally, the service contract includes a Service Level Agreement (SLA) with quality-of-service features, behaviors, limitations and potentially other human-readable documents.

TOGAF distinguishes between two kinds of contracts:

  • Operational contracts which specify the actual communication protocols and message formats.
  • Governance contracts between two business entities. These specify what interaction is needed, inputs, outputs, SLAs, OLAs, and KPIs. Governance contracts are the main concern at architectural level.

An important observation is that the operational contract in TOGAF corresponds to the requirements for interacting with the service in service-orientation. The technical contract in SOA also includes information about input and output structures, policies and operations. That is, the technical contract combines operational and governance aspects.

Furthermore, the technical contract is not restricted to apply only between two business entities: the technical contract specifies the required interaction, inputs, outputs and policies for many consumers of the service. Something similar can be said for the SLA and other human readable documents. In service-orientation, the SLA provided by the service applies to more than one consumer.


Service-Orientation Principles for Service Contracts

The application of service-orientation principles on the contract design ensures that service contracts (and services) can be used by many consumers, resulting in service reuse. There are eight design principles [REF-1, REF-2]

  1. Standardized Service Contract: Services within the same service inventory are in compliance with the same contract design standards.
  2. Service Loose Coupling: Service contracts impose low consumer coupling requirements and are themselves decoupled from the surrounding environment.
  3. Service Abstraction: Service contracts only contain essential information and information about services is limited to what published in service contracts.
  4. Service Reusability: Services contain and express agnostic logic that can be positioned as reusable enterprise assets.
  5. Service Autonomy: Services exercise a high level of control over their underlying runtime execution environment.
  6. Service Statelessness: Services minimize resource consumption by deferring the management of state information when necessary.
  7. Service Discoverability: Services are supplemented with communicative meta data by which they can be effectively discovered and interpreted.
  8. Service Composability: Services are effective composition participants, regardless of the size and complexity of the composition.

All of these principles, except for the Service Statelessness principle, contribute to the formation of the service contract. In particular, the two first principles, help to standardize and decouple the technical contract of each service, allowing for the "Contract First" design.

In the following sections we will see how they can be applied in the service contracts in TOGAF.


Service Profiles

Detailed analysis and design specification about a service is provided in standardized service profiles. Each service has one service-level profile and one capability profile for each of its capabilities. The attributes that correspond to these two profiles are provided in Tables 1 and 2.


Service Profile Attribute Description
Service Name
-
Purpose Description (Short) A concise, one sentence description of the service context and purpose.
Purpose Description (Detailed) A full explanation of the service context and its functional boundary with as many details as necessary.
Service Model Entity, Utility, Task, Orchestrated Task, or a custom variation.
Keywords Words ideally taken from an official service inventory-level taxonomy or vocabulary.
Version The version number of the service currently being documented
Status The development status of the service is expressed in this field using standard terms identifying a project lifecycle stage, such as "analysis," "contract design," "development," or "production."
Custodian How to reach the official service custodian or owner, as well as others that contributed to this documentation.

Table 1 – Service Profile Attributes

Capability Profile Attribute Description
Capability Name
-
Purpose Description (Short) A concise explanation of the capability's overall purpose and functional context (short description)
Logic Description A step-by-step description of the logic carried out by the capability.
Input/Output Definitions of a capability's allowable input and/or output value(s) and associated constraints.
Composition Role The execution of capability logic can place a service into various temporary runtime roles, depending on its position within service composition configurations.
Composition Member Capabilities A list of service capabilities composed by the capability logic. This provides a cross-reference to other service capabilities the current capability has formed dependencies on.
Keywords Similar to Service Keywords
Version Capabilities may be versioned with a number or with the version number appended to the capability name.
Status Same lifecycle identifiers used for services
Custodian Usually (but not always) this is (one of) the service custodian(s)

Table 2 – Capability Profile Attributes

Much of the information available in a service profile should remain hidden from potential service consumers, in order to avoid undesirable coupling of the consumers to the service design and implementation. Therefore service contracts typically contain only a subset of the data in a service profile.

More specifically, the attribute:

  • Detailed Purpose Description

...of the service profile, and the attributes:

  • Logic Description
  • Composition Role, and
  • Composition Member Capabilities

...of the capability profile (marked with red in the above tables) violate the Service Abstraction and Service Loose Coupling principles, and therefore should not be included in the service contract.

Furthermore, certain considerations should be made for choosing the appropriate values for the following attributes in service and capability profiles:

  • Service Name
  • Purpose Description (Short)
  • Keywords
  • Capability Name

Typically these attributes are parts of a service contract, and therefore they should respect the Service Abstraction and Service Loose Coupling principles, and they should facilitate the discoverability of services. Guidelines for putting appropriate values in the above attributes should be provided by applying the Standardized Service Contract principle.

Concluding the discussion about Service and Capability Profiles it is important to note that service-orientation recommends the use of Centralized Schemas for describing the types and structure of input and output messages. Centralized Schemas have direct impact on the following attributes:

  • Input/Output
  • Version

A new version of the schema may result in new versions for the service contracts. The propagation of versions from the schema to the contracts should be consistent (Service Standardization). Additionally, the Input/Output attribute references the required objects from the centralized schema, therefore, the Service Abstraction, Service Loose Coupling and Standardized Service Contract principles should apply to the schema as well.


Generic Attributes for All Meta Model Objects in TOGAF

The service contract template includes all the attributes that TOGAF defines for service contracts in a SOA [REF-3]. The attributes of the service contracts are also defined in the TOGAF content meta model [REF-3]. All objects in the meta model, including service contracts have a common set of attributes. These attributes are provided in Table 3.

The same considerations discussed previously for attributes of service profiles apply also to the attributes of the service contract template. Although among the common attributes there are no forbidden attributes, the values for the attributes:

  • Reference
  • Name
  • Description

...must satisfy the requirements of the following principles:


NOTE

Although not specific to Service Contacts, the selection of the type of the service should not describe its implementation. For example, a service type "Entity" is proper, but service types such as "Java" or "My Vendor Platform" violate both the Service Abstraction and the Service Loose Coupling principles in the contract, and therefore should be avoided.



TOGAF Attribute Definition SOA Profile Attribute
ID (or Reference) A unique identifier within the architecture information for cross-reference, clarity, and differentiation from other similar artifacts.
-
Description The name of the service should indicate in general terms what it does, but should not be the only definition. The description is a narrative of what the artifact is, what it does, and its relevance to the architecture. Purpose Description (short)
Type (or Category) The type of the service to help distinguish it in the layer in which it resides; e.g., data, process, functionality, presentation, functional. Service Model
Source The source of the artifact, which may be a person or a document, along with a date to support traceability of the architecture. Custodian
Owner The owner of the artifact is the name (person or group) who validates the details of this artifact; the person/team in charge of the service.

Table 3 – Common Attributes for all Metamodel Objects and Mapping to SOA


Other General and Business Attributes

The Business attributes in the service contract demonstrate that service contracts are between two entities in TOGAF. That is, if a service provider is used by N consumers, then it may have N contracts.

Service-orientation considers this approach the exception, rather than the rule. Agnostic Services should serve multiple consumers with the same contract. Nevertheless, the Concurrent Contracts pattern enables one body of service logic to expose multiple service contracts. This pattern is often used to accommodate different types of service consumers without having to convolute a single service contract.


TOGAF Attribute Definition SOA Profile Attribute
Version The version of the service contract. Version
RACI Responsible/Accountable/Consulted/Informed. Custodian
Service Name "Caller" Name of the consuming service. Capability: Composition Role
Service Name "Called" Name of the provider service.
Functional Requirements The functionality in specific bulleted items of what exactly this service accomplishes. The language should be such that it allows test cases to prove the functionality is accomplished. Purpose Description (Detailed)
Capability: Logic Description
Importance to the Process What happens if the service is unavailable.
Quality of Information Required Accuracy and Completeness of information. The quality that is expected from the service consumer in terms of input, and what quality is expected from the service provider in terms of output. Input/Output
Contract Control Requirements Level of governance and enforcement applied to the contractual parameters for overall service.
-
Result Control Requirements Measures in place to ensure that each service request meets contracted criteria.
-
Quality of Service Allowable failure rate.
-
Service Level Agreement Amount of latency the service is allowed to have to perform its actions.
-

Table 4 – Business Attributes for TOGAF Service Contracts and Mapping to SOA

Another observation is that in TOGAF the service contract resembles a combination of service and capability profile. It includes much information that often violates the Service Abstraction and Service Loose Coupling principles. In particular the values of the attributes:

  • Caller,
  • Called,
  • Functional Requirements,
  • Importance to the Process

...describe either run-time roles or are specific to a particular process. Agnostic services do not know anything about the processes in which they are invoked, and therefore, cannot provide the information required in these fields.

Additionally, detailed description of the functional requirements in the service contract introduces undesirable coupling between the service contract and the functions defined within the service. A better approach is to list the capabilities provided by the service, along with a short description for each of them, instead of describing the functional requirements.

The control requirements are part of the overall requirements for the service and should probably be standardized across the entire service inventory. The Domain Inventory pattern is here preferable instead of providing such information in the service contract.

Handling of the attributes Quality of Service and Service Level Agreement will be discussed in the following section.


Attributes for Non-Functional Requirements

In order to satisfy non-functional requirements similar to those in Table 5, service designers usually apply the Service Autonomy principle. If the service is agnostic, then all non-functional requirements should be considered and the implementation should support the load predicted in the future and during the peak periods. If the service cannot satisfy these requirements, then it cannot support the Service Reusability principle.

However, quality of service information needs to be reduced to reasonable levels by applying the Service Abstraction principle. Making promises on unrealistic levels such as availability close to " may result in implementations that do not allow for the service to evolve.


TOGAF Attribute Definition SOA Profile Attribute
Throughput Volume of transactions estimated; e.g., 100,000

Purpose Description (Detailed)

Typically found in an SLA

Throughput Period The period in which those transactions are expected, e.g., 100,000 per day.
Growth The growth rate of transactions over time
Growth Period The period in which the growth is estimated to occur; e.g., 10,000 per year.
Service Times The available hours/days the service is needed; for example, daily, 9 to 5 (excluding Holidays).
Peak Profile Short Term The profile of the short-term level of peak transactions; for example, 50% increase between hours of 10 to 12 am.
Peak Profile Long Term The profile of the long-term level of peak transactions; for example, 50% increase at month end.
Security Requirements (or Security Characteristics) Can execute this service in terms of roles or individual partners, etc. and which invocation mechanism they can invoke.
Response Requirements The level and type of response required. Response times that the service provider must meet for particular operations.

Table 5 – Attributes for Non-Functional Requirements


Attributes for Technical Information

Attributes with technical information correspond to elements of a technical interface. In more detail:

The different invocation mechanisms provided for a single service are supported by the Concurrent Contracts pattern. The invocation mechanism is always part of the technical interface.

On the other hand, strict invocation preconditions may result in services that cannot be reused in many contexts. Such preconditions are typically not adequate for agnostic services, but can be enforced by compositions or validation at the orchestration level. The Service Abstraction principle should be applied in order to eliminate validations that may be restrictive for the reusability of the service.

The Business Objects attribute can refer to the centralized schemas and is a mandatory attribute for every service contract.

Finally, the attribute Behavior Characteristics violate the Service Abstraction and Service Loose Coupling principles: the contract depends on the implementation. This attribute should not be part of the contract for an agnostic service. On the other hand, architectures may put a limit on the depth of service compositions in order to satisfy Service Autonomy. In such case, it may be necessary to know if the invoked service is a composition.


TOGAF Attribute Definition SOA Profile Attribute
Invocation This includes the URL, interface, etc. There may be multiple invocation paths for the same service. There may be the same functionality for an internal and an external client, each with a different invocation means and interface. Part of the Technical Interface
Invocation Preconditions Any pre-conditions that must be met by the consumer (authentication, additional input, etc.) Input/Output
Business Objects Business objects transferred by the service. Input/Output
Behavior Characteristics The criteria and conditions for successful interaction and any dependencies (on other service interactions, etc.). This should include any child services that will be invoked/spawned by this service (in addition to dependencies on other services). Composition Member Capabilities

Table 6

Other Attributes

The content meta model in TOGAF [REF-3] defines additional attributes for service contracts. These attributes involve primarily non-functional requirements and can be classified in three groups:

  • Group 1: Service quality characteristics, Availability characteristics, Manageability characteristics (control of state information), Serviceability characteristics, Performance characteristics, Reliability characteristics, Recoverability characteristics,
  • Group 2: Localability characteristics (Ability of a system to be found when needed),
  • Group 3: Privacy characteristics (data protection), Integrity characteristics, Credibility characteristics, Localization characteristics, Internationalization characteristics, Interoperability characteristics, Scalability characteristics, Portability characteristics, Extensibility characteristics, Capacity characteristics.

The requirements of Group 1 are typically satisfied by applying the Service Autonomy and Service Statelessness principles. As mentioned earlier, application of the Service Abstraction principle is mandatory in order to allow more room to the service for evolvement.

The Localability attribute in Group 2, is accomplished by the Service Discoverability principle.

The attributes in Group 3 are not specific to service-orientation, but their satisfaction by the service implementation contributes to the Service Reusability.


Conclusions

In this document we reviewed the attributes of the service contracts and profiles in service-orientation and TOGAF 9. The principles of Service Abstraction and Service Loose Coupling need to be applied to several attributes in TOGAF's service contracts. Some of the attributes do not respect service-orientation, and couple the service contract to other contexts.


References

[REF-1] SOA Principles of Service Design", Thomas Erl, Prentice Hall/PearsonPTR, www.soabooks.com/psd

[REF-2] Understanding Service-Orientation - Part II: The Principles. http://www.servicetechmag.com/I54/0911-4

[REF-3] TOGAF Version 9. The Open Group, 2009. http://www.togaf.info/togaf9/index.html