Real-Life Service-Oriented Architecture (SOA) with D6

I contributed an article for EMC Proven Professional Knowledge Sharing 2008 entitled Real-Life Service-Oriented Architecture (SOA) with D6. It has now been published on EMC Education Services site. On the same topic, I also wrote an article on CMSWire.

For ease of access, the article is being made available here as well (with permission from EMC) – download article. The abstract of the article follows.

Abstract

Service-Oriented Architecture (SOA) facilitates composition of loosely-coupled services into new services and applications. SOA must deliver business and technical agility to be successful. In other words, SOA serves business goals other than the standard “potential cost reduction via technical changes.”

This article translates a real-life business goal into an SOA solution that includes a key service provided by D6 (EMC Documentum version 6). While the article is primarily technical, it keeps business drivers and context at the forefront.

Even as SOA is becoming mainstream, Enterprise Content Management (ECM) has become a key piece of the enterprise infrastructure puzzle. Explosive content growth has led Gartner to forecast a 12% annual growth in ECM software revenues for the next three years. EMC Documentum has been a leading player in the ECM space so it should come as no surprise that SOA has been adopted as one of the core principles of D6.

D6 provides Documentum Foundation Services (DFS) for plugging Documentum into an SOA solution. Documentation and articles about D6 and SOA typically focus on DFS features. While they are essential for using Documentum in an SOA solution, they need another complementary capability for completing the SOA picture – orchestration of services for composing new services or applications. This article explores implementation of a real-life business scenario via an SOA solution including Documentum as a key component.
Consider a business goal to reduce Days Sales Outstanding (DSO) defined as the average collection period of account receivables over a time period (typically quarterly or yearly). A large DSO value means that it takes longer for the business to collect payments. A process analysis reveals that invoice presentment and payment are the primary improvement opportunities. This article describes an SOA-based implementation of an Invoice Presentment and Payment Application. Documentum is used to manage payment-related documents such as invoices and payment receipts.

The article illustrates the following key aspects of such a solution:

  1. Using DFS for creating content-oriented services
  2. Orchestrating SOA services for composing applications or other services
  3. Addressing real-life concerns
Advertisements

“Authorization Failed” in DFS-based Service (D6)

The DFS SDK provides convenience Java classes for writing a consumer for a DFS-based web service. The consumer itself can also be a service. On the other hand, a consumer can also be written to use only the service WSDL without using any of the DFS SDK tools. If you are writing both a custom DFS-based service and its consumer using the SDK, things work out relatively smoother. Since the same set of tools are creating the consumer as well as the service, it can ensure that they are compatible in all aspects. If you decide to create the consumer using only the WSDL, then the onus is on you to make it work.

I created a custom DFS-based service staring with the sample AcmeCustomService. I also created a Java consumer using the SDK and it was able to interact with the service easily. Next, I generated a client stub (the plumbing for communicating with the service) based on the WSDL using AXIS2 tools. I wrote a simple client to invoke the service using the stub. I held my breath as I ran the client – only to get a SerializableException. Note that any server-side exception would show up as this exception on the client side. I added some logging and obtained "Authorization Failed" as the embedded message. Note that both the clients were talking to the same service deployment. A day’s worth of research didn’t yield anything concrete. Finally, I started browsing the generated code for the service.

In the file named xxWebService.java where xx was the name of my main service file, there was an annotation reading

@javax.jws.HandlerChain(file="authorized-service-handler-chain.xml")

I tried to locate this file but couldn’t find it in the project. Finally, I found this file in the service EAR file that was being packaged and deployed. Next to it I found a file named anonymous-service-handler-chain.xml. The difference between the content of these two files was a handler dealing with authorization. So, a web service authorization was taking place and the consumer code generated by the DFS SDK was taking care of it somewhere.

There were two options at this time – make the service anonymous or figure out the right way to authenticate the client. I had spent enough time trying to make this work so I decided to just make the service anonymous by altering the annotation to

@javax.jws.HandlerChain(file="anonymous-service-handler-chain.xml")

Then I repackaged the EAR and redeployed it. That was it! The AXIS2-based client worked perfectly. By the way, the DFS SDK-generated Java consumer also continued to work.

Authorizing the consumer will be a battle for another day.

Running DFS Sample Code for D6

D6 provides an SDK for developing custom web services and clients using DFS (Documentum Foundation Services). When I started playing with it, the first thing I wanted to do was to see that the sample code works. I also found that the DFS Development Guide describes the use of the SDK in good detail. The sample service that I tried was AcmeCustomService.

I ran into a few issues but they were not too much to overcome. Following are the key things to keep in mind if you are trying this for the first time:

  1. In the sample code, replace the host IP and port number everywhere with the correct values.
  2. The build.xml file refers to dfs.sdk.libs variable, but it is not defined anywhere. This can be added to the build.properties file. However, it is more appropriate to add it to the build.xml as follows:
    <property name="dfs.sdk.libs" value="${dfs.sdk.home}/lib"/>
  3. The packageService target packages the dfc.properties file from outside the AcmeCustomService folder. Any changes to the dfc.properties files under the AcmeCustomService/etc folder are ignored. These can be fixed as follows:
    <path location="${basedir}/etc/dfs.properties"/>
    <path location="${basedir}/etc/dfc.properties"/>
  4. I found this to be the easiest way to do the build:
    ant clean artifacts package