Defining the Technical Service Record

Here’s a topic for which I’d really like some community input, and I think it’s something that many of my readers have probably had to do, are doing, or would be interested in the result. If you’re adopting SOA, you’re likely using a Service Registry/Repository of one form or another. It can range from a set of scribbled notes on a whiteboard or post-its in some architect’s office/cube, to Excel, to one of the many vendor products available for this purpose. So, assuming you are actually using one of these mechanisms, what are you recording about your services, the consumers of those services, and how/where are you capturing the relationship between the two? In this post, I’m going to start with the first question, the answer to which constitutes what I call the technical service record. Please note that the focus of this is on services that have a programmatic interface, and not the broader business service or ITIL service space, although I am very interested in the overlap between this record and the service record that would existing in an ITIL v3 Service Portfolio.

Here’s a list of items that could be recorded about a service to get the discussion started. For each item, I’ve provided a description of what that item is, whether it is optional or not, the visibility of that item (public, consumers only, service manager only, etc…). Please contribute your thoughts on other attributes that could/should be captured along with its optionality (is that a word?) and visibility.

Attribute Description Required Visibility
Name Human-readable name of the service Yes Public
Description Human-readable description of what the service does Yes Public
Owner/Manager The person accountable (in the RACI sense) for the service. At a minimum, this is the person to contact in order to begin using the service. Yes Public
Question: Should the owner be public, or only visible to registered consumers? A registry/repository could facilitate interaction with a potential consumer without publicly revealing the owner’s name.
Interface Type (or should it be types?) The technical interface type, such as SOAP, REST, POX/HTTP, etc. Yes Public
Internal/External Is the service exposed internally, externally, or both? Yes Public
Note: External users can only see services exposed externally.
Service Type Taxonomy classification for purposes of mapping to technology platform Yes Internal Only
Production WSDL URL URL for the production WSDL (Required for Web Services) No * Consumers
Deployment Platform On which logical platform is the service hosted? No * Internal Only
Deployment Location What is the physical location(s) of the service? Preferably, this should be a link into the CMDB. No * Internal Only
Test Plan/Scripts A link to a test plan or specific test scripts for the service as provided by the provider. No * Internal Only
Performance Profile The expected resource utilization of the service. No * Internal Only
Development Cost The cost incurred in creating the service. No * Internal Only
Estimated Integration Cost Expected cost for consumers to integrate service usage. No * Internal Only
Current ROI Current development ROI generated based upon development cost, cost to integrate, and current number of consumers No * Internal Only
Status Status of the service: Planned, in development, in production, decommissioned) Yes See below
The visibility of this is directly tied to the state. For internal services, status is open to the public. For external services, a service should only be visible if it is in production.
Version The version of the service associated with this record. Yes Public
Created Date The date this record was created. Yes Internal Only
Modified Date The date this record was last modified. Yes Internal Only

Of course, now that I attempted to put this list down with some simple attributes, I’ve realized that whether or not things are required or visible to particular parties are dependent on the status of the service, whether it is exposed externally or not, the interface type, etc. It’s just hard to make that fit into an HTML table and still have this entry be readable. Anyway, if there isn’t anything proprietary or confidential about the structure of your service records, consider sharing it here. I promise to publish the end result of this effort here for all to share for free. This isn’t limited to Web Services, either. If you’re using REST, what information would you provide about the collection of resources that comprise the service to potential users of those services? I would guess that many of the above attributes would still apply, and could certainly be accessed themselves through a REST interface, since a serivce record is a resource in and of itself.

Thanks for your participation! If you’d prefer to send me your information directly without publicly posting it here, send me an email at todd at biske dot com or you can send me a direct message on twitter at toddbiske.

4 Responses to “Defining the Technical Service Record”

  • Eric Roch:

    Great post!

    This is the top level list we use (note there is a lot of detail under these bullets in practice):

    TRACEABILITY (back to requirements, use cases)

    A post on your post…

  • Thanks for your contributions, Eric. It’s nice to see that you’re willing to freely share a bit of information that might normally be reserved for your client base.

  • Todd – Thanks for bringing up this topic. This is generating some great replies and information.

    Here is additional information. A few of these are automatically available metadata constructs with web services and WSDL but then I do not look at just web services as services – I look at this more as a technology to define services.

    1) XML Schemas and sample XML for showing usage semantics (as semantics metadata are yet to be defined!!)
    2) Service Types Enumeration that includes Business Area Specific Business Services or an enterprise wide service or an extended-enterprise service
    3) Additional qualifies of whether it is a Composite Service or Basic Foundation Service
    4) Business Concept associated with the service
    5) Business activity type or a business process type that the service caters for – usually this is specific to an industry vertical.
    6) Industry Vertical Classification(Financial, Retail etc.) if applicable or else this is “Generic”
    7) Performance Metrics – (we do not use resource utilization as we do not have a metering policy – wish we did (!) but this records the average response time expected)
    8) Security Policy including Authorization Level required for invoking the service.
    9) Invocation mode – synchronous or asynchronous
    10) Business Exception Type – Data incosistencies or Not enough access

    surekha –

  • Peter Doyle:

    Hi Todd,

    Despite the fact that this piece is several years old, it’s still relevant and of interest – I have a question regarding governance of Service Operations – should I post it in response to this post, or is there a better way ?



Leave a Reply


This blog represents my own personal views, and not those of my employer or any third party. Any use of the material in articles, whitepapers, blogs, etc. must be attributed to me alone without any reference to my employer. Use of my employers name is NOT authorized.