Marco Fränkel

Marco Fränkel

Biography

Marco Fränkel is a SOASchool certified SOA Architect at Xebia B.V. in the Netherlands, and has almost 15 years professional experience as a software-developer and architect. For the past 3 years he has been assigned to the Dutch Chamber of Commerce, where he developed a SOA-based Integration Layer Framework and takes lead in the adoption of SOA as a methodology.

Contributions

rss  subscribe to this author

Bookmarks



A Methodological Approach to Entity Service Modeling Published: May 29, 2013 • Service Technology Magazine Issue LXXII PDF

Abstract: When it comes to the service delivery lifecycle, service modeling is the part of the analysis phase during which service candidates are produced before the physical definition and development [REF-1]. Unfortunately, this phase is skipped completely in a lot of SOA projects so that the definition of a service is based either directly on the demands of the service consumer (contract-to-functional coupling) or the API of the underlying code (contract-to-logic coupling). Both coupling types are considered "negative" and should be avoided in order to maximize the governance independence of the service contract [REF-2]. This article describes a practical method to prevent its occurrence, using a real-life case study.

Introduction

Ideally, the modeling of an entity-centric business service is based on its known and predictable usage. That's why SOA follows the example of commercial product design, which applies expert judgment to determine the most suitable type and quantity of logic to be provided by a service [REF-3]. In his book Service-Oriented Architecture: Concepts, Technology and Design, Thomas Erl provides a step-by-step process that can be used to conceptualize the services and their capabilities, based on decomposing business process definitions [REF-1].

Although this method definitely has its perks and can produce (if done properly) a nicely balanced service inventory blueprint, it can be a bit too complex for people that are not that well-versed in the area of service-orientation. It may also take up a lot of time, especially when the supporting business process documentation is not up to par and the analysts need to gather additional information first. In such cases the project members may decide to drop this method altogether in lieu of following their instinct, all in the name of "getting things done fast."

During my assignment at the Dutch Chamber of Commerce, I came up with a method for modeling entity service candidates based on a list of functional requirements. It can be used as an alternative to the aforementioned "business process definition decomposition" method when there is insufficient time for the top-down approach, and/or when it's clear that the resulting service has a very distinct functionality so there is no or little risk of denormalized services.

Additionally, the fact that it can provide quick results makes it a good fit to the SCRUM-driven approach used by a lot of IT companies these days. Finally, it can be performed by analysts and architects that are less experienced when it comes to modeling services.

I'll start the article first by describing the method. After that, I'll dive into the case and the way the method was applied to solve the problem it represents. I'll end by looking a little bit beyond the base method.

Description of the Method

The method I am proposing consists of five straightforward steps:

img

Figure 1 - The five steps of the method are shown.

1. Gather Concrete Requirements

The functional requirements are collected and, if possible and/or necessary, completed. It is best for the requirements to be as specific as possible.

2. Define Abstract Requirements

In this step the gathered concrete requirements should be rewritten into more abstract requirements. It might very well be possible that two or more concrete requirements will result in the same abstract requirement.

3. Extrapolate Abstract Requirements

Based on the abstract requirements, a number of binary choices can be deduced. All possible combinations are listed in a matrix and checked for validity. Invalid combinations are removed from the list.

4. Define Capabilities

By first normalizing and then denormalizing the leftover combinations, the capabilities of the service candidate can be defined.

5. Validate Results

As a final step, the service candidate can be validated against the original requirements. Also, if more requirements came up during the process, they can be used to validate if the service candidate is indeed future proof.

Case Background

The method has been tried and tested in an actual project that had the goal of helping customers find a company name unique to the branch they're in, using so-called ISIC records. The International Standard Industrial Classification of All Economic Activities (ISIC) is a United Nations system for classifying economic data [REF-4] that can be applied to assign a specific class to a company. Each class furthermore belongs to a specific group, each group to a specific division and each division to a specific section.

The records themselves are stored in a local database table, containing only the fields named ISIC Code, Description, Registration Date, Start Date and End Date.

Before I joined the project, it was decided that this data should be retrieved by applications through a Web service with a single operation. This operation would make it possible to select one or more elements using the input message described in the following XSD (List 1):

	
<xs:element name="getResult">
   <xs:complexType>
    <xs:sequence>
      <xs:element name="sectionCode" type="xs:string" minOccurs="0"/>
      <xs:element name="divisionCode" type="xs:string" minOccurs="0"/>
      <xs:element name="groupCode" type="xs:string" minOccurs="0"/>
      <xs:element name="classCode" type="xs:string" minOccurs="0"/>
      <xs:element name="sectionsInResponseIndicator" type="xs:boolean"/>
      <xs:element name="divisionsInResponseIndicator" type="xs:boolean"/>
      <xs:element name="groupsInResponseIndicator" type="xs:boolean"/>
      <xs:element name="classesInResponseIndicator" type="xs:boolean"/>
      <xs:element name="includeExpiredElementsIndicator" 
	  type="xs:boolean"/>
    </xs:sequence>
  </xs:complexType>
</xs:element> 

List 1 – The original input message definition.

This is a typical example of contract-to-logic coupling, as the XSD was derived from existing solution logic. The situation threatened to worsen when there was talk about a possible database schema alteration and the fact that the XSD would also be required to change. Fortunately by then, the project functional analyst had come to the conclusion that there might be a better way and asked me to step in. I studied the problem and came up with a suitable method after some back-and-forth discussions with the team.

The next paragraphs describe how that method was applied when working on the case in question.

1. Gather Concrete Requirements

The following requirements were known at the time the project commenced:

  1. It should be possible to request a specific element based on an ISIC code.
    • i.e.: select a section, filter on only sections in response
  2. It should be possible to request a list of all sections/divisions/groups/classes.
    • i.e.: select everything, filter on only sections in response
  3. It should be possible to request a list with a combination of all sections/divisions/groups or classes.
    • i.e.: select everything, filter on only sections and classes in response
  4. It should be possible to request a list of classes based on a supplied section-, division- or group code.
    • i.e.: select a section, filter on only classes in response

It should be possible to take historical data (expired codes) into account for all requests.

2. Define Abstract Requirements

The concrete requirements can be rewritten as follows:

  1. It should be possible to request a homogeneous element using a code.
  2. It should be possible to request a list of homogeneous elements without using a code.
  3. It should be possible to request a list of heterogeneous elements without using a code.
  4. It should be possible to request a list of homogeneous elements using a code.

It should be possible to take history in account. Several comments on these requirements are as follows:

  • A code can be a class, group, division or section code.
  • A result can consist of either a single element or a list of elements.
  • An element/list of elements can be homogeneous, where information about only one type of element is returned.
    • This doesn't have to be the type of the requested element per se. Based on the division code, the descriptions of all underlying classes can be requested at once.
  • An element/list of elements can be heterogeneous, meaning information about multiple types of elements is returned.
    • i.e.: based on a certain division code, the descriptions of all underlying groups and classes can be requested at once
  • Sending a request without using a code is equal to selecting all elements.
    • a list of elements is effectively selected, and it is not possible to select a single element without using a code
  • Sending a request using a code is equal to selecting a single element.
    • it is not possible to select a list of elements using a code, although it is possible to select a list of sub-elements

Selecting versus Requesting

During the development of this method, it became clear that the presence of the indicators made defining the possible capabilities a tad harder. This because they can influence the result in such a way that the original request is hard to determine. That's why the focus is on which elements can be selected, and not which elements can be requested.

The relationship between these can be described as follows: the correct information can be requested by selecting one or more elements, and then filtered using the indicators.

For example, it is possible to request type A (i.e. a list of classes) by selecting type B (i.e. a group) and applying the correct filtering.

3. Extrapolate Abstract Requirements

The following binary choices can be deduced from the previous list:

  • supplying a code (yes or no)
  • selecting an element (single or a list)
  • composition of the elements (homogeneous or heterogeneous)
  • history (yes or no)

This leads to 24 = 16 possible combinations, as shown in Table 1 (red is an invalid combination, green is valid).

Code Singular / List Homogeneous / Heterogeneous History
1 no singular homogeneous yes
2 no singular homogeneous no
3 no singular heterogeneous yes
4 no singular heterogeneous no
5 no list homogeneous yes
6 no list homogeneous no
7 no list heterogeneous yes
8 no list heterogeneous no
9 yes singular homogeneous yes
10 yes singular homogeneous no
11 yes singular heterogeneous yes
12 yes singular heterogeneous no
13 yes list homogeneous yes
14 yes list homogeneous no
15 Yes list heterogeneous yes
16 yes list heterogeneous no

Table 1 – The 16 derived combinations are shown.

The combinations are validated against the previously stated comments. It is not possible to select a singular element without using a code, making 1-4 invalid. It is also not possible to select a list using a code, making 13-16 invalid.

This leaves eight possible valid combinations, which can be translated into the following requirements:

  • It should be possible to select a list of homogeneous elements without using a code, including historical data (5).
  • It should be possible to select a list of homogeneous elements without using a code, excluding historical data (6).
  • It should be possible to select a list of heterogeneous elements without using a code, including historical data (7).
  • It should be possible to select a list of heterogeneous elements without using a code, excluding historical data (8).
  • It should be possible to select a single homogeneous element using a code, including historical data (9).
  • It should be possible to select a single homogeneous element using a code, excluding historical data (10).
  • It should be possible to select a single heterogeneous element using a code, including historical data (11).
  • It should be possible to select a single heterogeneous element using a code, excluding historical data (12).

4. Define Capabilities

In principle, all of the possible requests can be based directly on these eight valid requirements. Note that the practice of normalizing before denormalizing achieves several additional benefits.

Table 2 lists the valid combinations:

Code Singular / List Heterogeneous / Homogeneous History
5 no list homogeneous yes
6 no list homogeneous no
7 no list heterogeneous yes
8 no list heterogeneous no
9 yes singular homogeneous yes
10 yes singular homogeneous no
11 yes singular heterogeneous yes
12 yes singular heterogeneous no

Table 2 - The 8 valid combinations.

Two things can be concluded:

  1. History doesn't play a role (both options are always valid).
    • Combinations 6 (same as 5), 8 (same as 7), 10 (same as 9) and 12 (same as 11) can be removed.
  2. The composition of the elements does not play a role (both options are always valid).
    • Combinations 7 (same as 5) and 11 (same as 9) can be removed.

The following combinations are leftover:

Code Singular / List Heterogeneous / Homogeneous History
5 no list homogeneous yes
9 yes singular homogeneous yes

Table 3 – The resulting combinations after normalization are listed.

The two combinations can be translated into the next capabilities:

  • selectElements – select a list of elements without using a code
  • selectElement – select a singular element using a code

There are several ways of declaring the type of element that should be selected when composing the selectElement capability. One solution is to have all four code parameters as part of the input message (List 1), but always having only one used. Another possibility is to have just one code parameter and then derive the correct type from its value, or to add an extra "type" parameter.

A more elegant solution, however, is to have separate capabilities per code type to produce the candidate service (Figure 2):

img

Figure 2 – The resulting service candidate.

5. Validate Results

There are a number of examples on how to use this service at the end of this article. The following table shows how to map the original requirements to those examples (Table 4):

Requirement Examples
It should be possible to request a specific element based on an SBI code. selectSection (1), selectDivision (1), selectGroup (1), selectClass (1)
It should be possible to request a list of all sections/divisions/groups/classes. selectElements (2)
It should be possible to request a list with a combination of all sections/divisions/groups or classes. selectElements (1), selectElements (3)
It should be possible to request a list of classes based on a supplied section-, division- or group code. selectSection (3), selectDivision (3), selectGroup (3)
It should be possible to take historical data (expired codes) into account for all requests. Not included in examples.

Table 4 – The mapping of the original requirements to the solution.

A number of supplementary requirements came up during the project. Instead of adding these to the list of original requirements, it was decided to use them as a validation mechanism.

Requirement Examples
It should be possible to request a list of divisions/ groups or classes based on a supplied section-, division- or group code. selectSection (3), selectDivision (3), selectGroup (3)
It should be possible to request a list with a combination of divisions/groups and/or classes based on a supplied section-, division- or group code. selectSection (2), selectDivision (2), selectGroup (2)

Table 5 – The mapping of additional requirements to the solution.

This leads to the conclusion that the aformentioned service candidate is future proof.

Dealing with Restrictions

During the project a number of restrictions that should not have been possible surfaced. Taking these into account can lead to a situation in which the scope of the service interface would be too limited when such restrictions loosened up later on. As long as it doesn't concern specific business logic, it is best to implement this kind of restrictions client-side. Another solution is to regulate by filtering the output-messages.

Room for Future Adjustments

It may later become apparent that the five capabilities do not provide enough direction, meaning that it will not always be clear how to retrieve a list of classes per section. In those cases, the set of capabilities can be extended based on the next possibilities:

  • request all elements of a certain type from the complete table
  • request all elements of a certain type from the parent collection
  • request a specific element of a certain type

This results in two specific capabilities to request a section, three to request a division, four to request a group and even five capabilities to request a class, resulting in a total of 14 capabilities. The service can be split into four services (one for each type) using the Service Decomposition pattern, to prevent it from becoming "top-heavy" [REF-3].

img

Figure 3 – The additional service candidates are defined.

Here the new services are responsible for "pre-filling" certain request parameters if necessary, and of course for composing the correct operations.

Note that a number of variants are imaginable here. The 14 "new" capabilities can become part of the same service or even be added to the original ISIC service. The choice should be based on matters such as maintainability, versioning, and so forth.

Conclusion

The method proposed in this article is still relatively immature, but it has already delivered results that are much more in-line with the Service Reusability and Service Loose Coupling principles than the standard method, or rather lack thereof, that so many SOA projects seem to use.

The method may not be as extensive as the "business process definition decomposition" method described by Erl, but on the plus side it does have a lower difficulty threshold and will especially shine in the cases in which the bottom-up service delivery strategy is applied. It can also act as an extension to Erl's method during the "apply service-orientation" step by providing a good way to improve the reusability of entity service candidates.

The method will probably be less suitable when it comes to modeling utility services, given that their functional context is difficult to determine. It also won't work for task services, as their non-agnostic nature conflicts with the general idea behind this method.

References

[REF-1] Erl, Thomas. Service-Oriented Architecture: Concepts, Technology, and Design. Toronto: Prentice Hall, 2005.

[REF-2] Erl, Thomas. SOA Principles of Service Design. Toronto: Prentice Hall, 2008.

[REF-3] Erl, Thomas. SOA Design Patterns. Toronto: Prentice Hall, 2008.

[REF-4] United Nations Statistics Division – Classification Registry: http://unstats.un.org/unsd/cr/registry/regcst.asp?Cl=27

Acknowledgements

I wish to thank my colleagues Maurits Rijk and Gero Vermaas for reviewing my article, and Gerbrand van der Vooren for being my soundboard when I was developing the method.