Client Integration Mini-Checklist for Services

May 27, 2012

Working with clients who are consuming your services? Here is a mini-checklist of questions to ask:

  1. While executing request/reply on the service interface is there a timeout value set on the call?
  2. Is there code/logic to handle SOAP Faults /system exceptions when invoking the service?
  3. Is building service header separated from the payload? This will facilitate reuse across services that share common header parameters
  4. If there are certain error codes that the calling code can handle, is there logic for each of them?
  5. Is the physical end point information (URL string for HTTP, Queue connection and name for MQ/EMS) stored in an external configuration file?
  6. Is UTF-8 encoding used while sending XML requests to the service i.e. by making use of platform-specific UTF encoding objects?
  7. If using form-encoding are unsafe characters such as ‘&’, ‘+’, ‘@’ escaped using appropriate %xx (hexadecimal) values?
  8. While processing the service response is the logic for parsing/processing SOAP and service-specific headers decoupled from processing the business data elements?
  9. Is the entire request/reply operation – invocation and response handling logic – encapsulated into its own class or method call?
  10. While performing testing, is the appropriate testing environment URL/queue manager being used?
  11. Is a valid correlation id being used in the service request? This is very essential for aynchronous request/reply over JMS (JMS Header) or HTTP (callback handler)

Leave a Comment » | General, SOA | Tagged: , , , , , , | Permalink
Posted by vijaynarayanan

Software Reuse Quick Tip #26

July 10, 2010

Tip #26 – Build Reusable Services

The following are useful tips when designing and implementing reusable services.

Expose only logical data attributes and “standardized” values to external consumers in the service contract. This will ensure that the data service has maximum flexibility to change physical system implementations underneath and the consumer will not be adversely impacted.

Reuse business object schemas across data service operations and while preparing WSDL documents. This will ensure logical data model alignment as well as consistent definition of business objects simplifying consumption and maintenance effort.

Expose event driven publication services for data propagation to downstream consumers using standard publication messages. This will greatly reduce (and potentially eliminate) the need for source specific messages and needless data transformations. Standard publication messages could be versioned and new consumers could be added via configuration on a messaging broker without requiring development effort.

Provide multiple flavors of services based on commonly used use cases for the data service. A light flavor of a service will be useful for clients who do not want to parse a large business object message returned by the full flavor.

Strive for abstraction of data source specific semantics in order to insulate the consumer from physical data source processing/logic. This practice applies to identifiers, data values, data structures, and data orchestration logic that could be coupled to a physical source if proper care isn’t taken.

Prefer reliable transports when invoking data services asynchronously. Although it is possible to simulate asynchronous processing using transport protocols such as HTTP it is not advisable to do so. In the event the data consumer becomes unavailable messages are lost.

Leave a Comment » | Design, Reuse, SOA | Tagged: , , , , | Permalink
Posted by vijaynarayanan

Checklist for Testing Service Capabilities in your SOA

April 17, 2010
checklist

Download Checklist

Here is a checklist for ensuring that your service capabilities are unit tested effectively.   These questions can come in handy when validating test coverage or when doing code reviews with fellow team members. I have used this checklist extensively in all my SOA development efforts and has helped with improving the quality of the services. The check list covers:

  • functional testing
  • error handling
  • data validation/formatting
  • performance testing
  • data binding/transport interfaces

Feel free to add/customize this checklist based on your team’s unique needs. I hope you find this resource useful!

Leave a Comment » | Reuse | Tagged: , , , , , , , | Permalink
Posted by vijaynarayanan

12 Practices to Consider When Pursuing Systematic Software Reuse

April 15, 2010

Systematic reuse is hard because it isn’t a problem that technology alone can solve. It requires a various practices that have to be executed in a coordinated manner across teams and projects.  Here is a starter list of practices to consider for success with systematic reuse:

  • allocating resources including changes to budgeting practices for funding shared capabilities
  • setting up appropriate incentives for developers, technical leads, and management staff
  • creating a roadmap for increasing organizational agility – reduced time to market, increased flexibility, increased quality – across multiple processes and applications.
  • recognizing failure signs and course-correcting – not only for large initiatives but for individual asset development as well. Don’t forget the need to involve your consumers in addressing delivery and integration challenges.
  • utilizing product line management techniques for identifying, managing, capturing, and realizing variability in business capabilities.
  • explore reuse opportunities not only business functionality but also with IT processes such as bug tracking, problem management, incident management etc.
  • align reuse efforts closely with other initiatives such as service oriented architecture, business process management, master data management etc.
  • Provide training to developers, technical leads, and development managers on what is available, what is being planned, and how the resuable asset inventory is managed/evolved. Make your teams buy-into the effort.
  • Look for reuse opportunities throughout the entire development cycle- not just during implementation! You can reuse requirements, analysis patterns, domain models, business processes, as well as documentation.
  • Aligning reusable assets with business goals/objectives. Remember: the rationale for reuse is to reduce costs and increase revenue for your firm.
  • Communicate reusable assets within your immediate team, then your department, before taking it organization-wide. Without a support and maintenance strategy in place, your reuse efforts cannot be sustained.
  • Address Non Functional Requirements (scalability, reliability, etc.) when creating resuable assets.

Does this resonate with your experience? what is missing in this list?

1 Comment | General, Planning, Reuse | Tagged: , , , , , , , , | Permalink
Posted by vijaynarayanan

5 Tips When Managing Multiple Service Versions

November 28, 2009

Many teams that build service capabilities have to manage multiple versions – this is a problem for any shared asset really – be it a library, component, or service. Using extensible schema contracts (also referred to as Consumer Driven Contracts) you can design service contracts that allow both provider to evolve and consumer to integrate in a flexible manner. In this post, I want to suggest five additional tips when managing web services:

1. Figure out how many versions your team will support concurrently. Too little will force all your consumers to be on a single version and too many will become a maintenance nightmare for you (the provider). In past implementations, I have maintained upto 3 versions while actively moving all service consumers towards one target version. A related approach is to have multiple flavors for your service capability one that returns data that most consumers want, the second that provides the minimal set of attributes, and a third flavor that returns the full list of data items. This may or may not be possible in your case, but something to consider when designing contracts.

2. Figure out how you are going to support multiple versions as a service provider. You can use xml schema namespaces to indicate versions: http://some-company.com/services/CustomService_ver1_0.xsd, ver1_1.xsd and so on. Consider creating a service adapter that can translate back and forth between a new service implementation and the existing one. This can potentially help you with one server side implementation of the functional logic and still service your current and new consumers. This adapter component can perform necessary data transformations, error code & error message translations, and massage response with data attributes as appropriate.

3. Communicate the change in the service capability and gauge the appetite with existing consumers for their ability to absorb the changes in the same release time frame that you are targeting to drop your new version. If you co-ordinate the release, you can get them to new version when you go live. However, for mission critical applications you will want to support both your current and new version concurrently for a small time period before switching the old one off.

4. When you design forward-compatible schemas, you can test the data-binding against multiple platforms. For example, use WSDL2Java if you are using Apache Axis in Java or wsdl.exe if you are in .NET and generate appropriate web service proxy classes and data binding classes. What i have done is to implement JUnit and NUnit automated test cases that run everytime there is a new WSDL or service contract (XSD) change. This will not only validate the service functional logic, but also the forward-compatibility of existing clients. Make sure your when you generate bindings that you generate with both the new schema/wsdl (your updated version) and the existing schema/wsdl files (the version currently used by production clients).

5.  Establish lightweight service governance – it is critical to plan how many service flavors and versions you will support, when will they get upgraded, deprecated, decommissioned, etc. and communicate those with your consumers. Identify checkpoints in your development process where contracts can be reviewed and service behavior can be discussed openly. The well thought out service orientation strategy is a benefit for both the provider and the consumers in your organization.

What other tips/techniques have you used?

Like this post? Subscribe to RSS feed or get blog updates via email.

tweet this add to del.icio.us post to facebook

Leave a Comment » | Design, Reuse, SOA | Tagged: , , , , , , | Permalink
Posted by vijaynarayanan

Prefer Real-time Capabilities Even If Your Consumers Don’t

November 25, 2009

Build near real-time capabilities even if your consumers don’t want them. Your consumer may not want a real-time interface or maybe unable to integrate with one. It is tempting to just go for a batch based solution because, that is what your consumer is asking for. For now at least. However, if you build one off batch file extracts or directly expose your legacy system to make one consumer happy, you will encounter the ill effects of tightly coupled systems.

There are several approaches to achieve long-term reuse goals and address the immediate customer need:

  1. Publish a standard message that you will want to treat as a reuse candidate going forward. A subscriber can drain, accumulate messages, transform them to a customer-specific format, and and append it to a file. A scheduled job or process can transfer this file to your customer.
  2. Create a reusable service capability that provides the data in the target format that you want to maintain/evolve going forward. You can create a batch process that shares the same interface that the real-time service uses.  Note: volume is a critical factor here though – you don’t want to make several atomic calls when it is more efficient to fetch data in bulk. You could have a configurable parameter for fetching multiple records at a time – the real-time service can use a much smaller number when compared to the batch process.
  3. For large data volumes,  consider populating a read-only data store using database replication. File extracts can then be driven off this new database. This has the advantage of reducing load on your operational data stores at the same time facilitating additional consumers who might prefer a SQL interface or a file extract based solution. Downsides: additional moving parts and increased cost for a new data store.

When you build real-time capabilities,  adding consumers doesn’t involve too much effort. Are there additional approaches to pursue?

Like this post? Subscribe to RSS feed or get blog updates via email.

tweet this add to del.icio.us post to facebook

Leave a Comment » | Design, Reuse, SOA | Tagged: , , , | Permalink
Posted by vijaynarayanan

The Systematic Software Reuse Roadmap

November 8, 2009

In an earlier post, I outlined the four key ingredients for agile software reuse. One of which is the reuse roadmap. In this post I want to share an example roadmap and illustrate how they tie into other business and IT objectives. The idea is to start at the ad-hoc state (where there is little or no reuse) and move to truly utilizing systematic reuse across multiple projects.

Phase 1-Ad-hoc - In this initial phase there is little or no awareness of reusable assets, and there is very little customer integration expertise. Consumers have low awareness of what assets are available. Systematic reuse efforts not considered and there is a lack of alignment between project deliverables, reuse strategy, and business objectives. Applications within the same domain do not share assets i.e. there is a lot of duplicate code.

reuse roadmap

View Reuse Roadmap

Phase 2-Aware - In the second phase, legacy capabilities and processes are mined for building assets. Agile practices are minimally aligned to the reuse strategy. Consumers seek reusable assets for applications in the domain and rudimentary product lines take shape. Communication about reusable assets have improved and awareness is increasing.

Phase 3-Ready – In this phase, asset inventory expands task, entity, and utility capabilities. User stories are analyzed within a product line context and additional assets are built iteratively. Agile practices specifically code reviews, refactoring, iteration planning, and pair programming used to identify and refine assets in a continuous fashion. Consumers increasingly use reusable assets to build applications and start to co-create assets. Additionally, assets are used across multiple applications in the domain. A few business process flows start to leverage reusable assets.

Phase 4-Systematic – This is when your systematic reuse program starts to really reap rewards. Asset inventory expands to include additional capabilities in your domain. Assets are used to automate many more business processes and they provide variability mechanisms to meet business needs. User stories and iteration planning are well aligned with reuse strategy which facilitate iterative reusable asset development. Additionally, several assets built by refactoring legacy capabilities and communication about reusable assets are available. Finally, consumers are actively engaged in asset co-creation, retrieval, and consumption and supported by a mature integration function.

Like this post? Subscribe to RSS feed or get blog updates via email.

tweet this add to del.icio.us post to facebook

Leave a Comment » | agile, Planning, Reuse | Tagged: , , , , , | Permalink
Posted by vijaynarayanan

Software Reuse Quick Tip #22

November 6, 2009

Tip #22 – Ensure Service Capabilities Stay Effectively Decoupled

The rationale for contract-first services (as opposed to code-first) is to effectively decouple service capabilities from needless implementation-specific, vendor-specific, and data-source specific realizations. You put the initial service capability out and ensured that the contract is decoupled – no legacy system specific details, no database-vendor or technology platform-specific attributes are present and your consumers are happy.  So, are you done? Well, no…because we all know that the technology environment, business requirements, regulations, and continuous innovations are the realities of modern development. You have to be careful not to succumb to these pressures and tread towards needless coupling. It is very easy to add one more attribute or element to your service contract and not pay attention to tight coupling being introduced.

As you add new versions, introduce enhancements, and make bug fixes take care not to introduce needless coupling. You can tie in code reviews – focused specifically around service contracts – to ensure this happens as part of your overall governance strategy. I will post detailed examples for this quick tip in a follow up post.

Like this post? Subscribe to RSS feed or get blog updates via email.

tweet this add to del.icio.us post to facebook

Leave a Comment » | agile, Reuse, SOA | Tagged: , , , , | Permalink
Posted by vijaynarayanan

Free E-book: Tips When Purusing Agile Software Reuse

October 24, 2009

Here is a free e-book on tips when pursuing agile software reuse. It introduces the rationale for software reuse, the need for agility, and lists twenty quick tips to help you succeed with your initiatives. Enjoy!

Tips When Pursuing Agile Software Reuse
agile_software_reuse_ebook

Like the ebook? Subscribe to RSS feed or get blog updates via email.

3 Comments | agile, Reuse | Tagged: , , , , , , , | Permalink
Posted by vijaynarayanan

Reuse-Friendly BPM Capabilities

October 21, 2009

I have been stressing the need for integrating various concepts for succeeding with systematic reuse. BPM is no different. In an earlier post I introduced reusable BPM integration capabilities. In this post I want to list additional capabilities that you can build as part of BPM initiatives:

  • Mature your integration function that helps consumers integrate, use, and discover business process assets. This includes activities, sub-processes, as well as end-to-end business processes. Provide sample source as well as integration documentation to applications that need to leverage your processes. Do remember developers may not understand the differences in interacting with a stateful business process!
  • Significant alignment with information architecture logical model. Your activities that invoke system steps leverage logical data schemas and data types. If you start to reuse sub-processes within your high-level flows this will become second nature.
  • Ensure that your BPM assets are aligned with key performance indicators (KPIs) – if your business wants to analyze time taken between a particular set of steps you might need to persist, report, compute on this data. Why not use a reusable component that can persist updates from any business process?
  • Business process models and orchestrations developed are more standards compliant and adhere to key BPM and SOA standards. The higher the interoperability of SOA assets, the easier it is to reuse them in your business processes.
  • Expand coverage of business processes hosted in the BPM layer – including processes that involve internal clients, external clients, data governance/compliance etc. You will start identify reusable assets over time. For example, two business processes might require fetching customer data or updating customer address or calculate customer worth to the company and so on. Every such need is an opportunity for reuse.
  • Comprehensive modeling and representation of all relevant business processes including placeholders for manual steps, batch jobs, etc. Even if your existing process isn’t transformed completely from manual to one that is fully automated in real-time identify these steps explicitly. At the very least, you can use reusable components that deal with batch jobs (kick off FTP session or create a temporary file and copy to a particular location etc.)
  • Expanded number of event driven services for your business process. The higher the number of events the greater the likelihood of additional consuming applications getting to reuse data and notifications.
  • Support standardized alerts associated with human workflow steps (delegation, escalation, routing, pause/resume task etc.). Your BPM infrastructure can provide configurable capabilities for these steps.
  • Create scripts that perform continuous integration including smoke tests, unit tests, performance tests etc. If your business process are service-enabled, you can run a battery of service requests to instantiate, update, remove process instances.

Like this post? Subscribe to RSS feed or get blog updates via email.

Slide 2

ØWe are completely focused on Enterprise Account Opening and supporting Account Opening – support complex business process orchestrations.
ØWe are not methodically building a collection of reusable building blocks of assets in the business process layer that will help us for the future
§Data service wrappers, PMWS wrappers, Work in progress (WIP) API,  event processing
ØWe have built a set of components to configure events for a business process, capture metrics and perform administrative functions.
ØNot all business process logic is in business process layer for Enterprise Account Opening
ØWeb service the de facto metaphor of integration. Business processes are accessed on demand using  request/reply
ØSchema Contracts
§Schemas, data types, web service contracts are minimally aligned with information architecture logical data model resulting in a missed opportunity to align ourselves deeper with the information architecture direction.
§There is significant of data type, business object reuse across services and event handler orchestrations
ØSeveral utilities for testing, deployment, and continuous integration capabilities
ØClient integration happens on a per-project basis. This often results in increased pressure on the development team leads, lack of knowledge sharing across projects with respect to service integration/behavioral issues

tweet this add to del.icio.us post to facebook

Leave a Comment » | BPM, Design, Reuse, SOA | Tagged: , , , , , , , , | Permalink
Posted by vijaynarayanan

« Previous Entries
Follow

Get every new post delivered to your Inbox.