Art & Science of Being an IT Architect

Still More on Reverse Engineering Code into UML Diagams

Judging by the unexpectedly large number of hits on my recent posting about reverse engineering Java into UML diagrams, I am not the only one interested in this topic. Along the same lines, I found this pretty cool demo of reverse engineering UML sequence diagrams from Sparx Systems. I haven't actually used the tool but what appears to be different with the reverse engineering capability of their Enterprise Architect tool is that it will generate diagrams via runtime execution. It also let you manually step through your code as it executes in a debugger type presentation. This would let you control how far “down in the weeds” you want your sequence diagram to go. For example, do you really want to include that call to the Integer class?
Copyright © 2006 by Philip Hartman - All Rights Reserved
The postings on this site are my own and don't necessarily represent IBM's positions, strategies, or opinions.

Reverse Engineering of UML Class and Sequence Diagrams from Java

About a year ago I had to stop work on an interesting project. There were just too many projects going on at one time, not enough resources to work on them all, and the other projects were more important from a political point of view. The project involved our B2B application making a call to a service provided by a 3rd party outside the firewall. One of the developers had built some great Java code to do this right before we stopped work.
I recently picked that project back up again and needed to dig into that code, understand how it worked, and create some design documentation for the overall project. I also had just recently made a conscious effort to upgrade my object modeling tool from Rational XDE to Rational Software Architect (RSA).
I decided I would start by reverse engineering the Java code to create a class diagram. I had done this numerous times as a Rational Rose and Rational XDE user in the past so I had no worries. I managed to import the source code and began fumbling through the menu options looking for reverse engineering features. I got a sinking feeling at first that someone at Rational had taken the reverse engineering features away. I found numerous transformations for forward engineering from UML class diagrams into something else (like Java). It was not obvious, however, what to do if I already had the Java code and wanted to go in the reverse direction. I had a sinking feeling inside. Had the Model Driven Development / Model Driven Architecture adherents at Rational lost their minds? Had they taken those reverse engineering features away on purpose? Was this a heavy handed means of forcing the whole world to adopt a “forward engineering only” view of the application development process?
Luckily, I was able to determine that Rational had not lost its collective mind. Yes, it was indeed possible to reverse engineer code into a diagram and as I got more into it, I decided it was actually an improvement.
I highly recommend a meaty white paper I found on developerWorks called “The new IBM Rational design and construction products for Rose and XDE users” by William T. Smith, a Product Manager supporting model driven development at IBM Rational brand software. From it I discovered that many reverse engineering capabilities were available in RSA (as well as Rational Software Modeler (RSM)) and they appear to be significant improvements over what I was used to in Rose and XDE. There is a great deal of new terminology to get used to, however.
Here is a quick summary of what I learned about reverse engineering using RSA

I can select Java classes of interest with my mouse and quickly reverse engineer a class diagram by “visualizing” a “Topic Diagram”. This diagram can be synchronized with code as the code is modified.
I can “harvest” classes from the topic diagram and paste them into a separate UML diagram.
I can mix “pure” UML classes and harvested classes on the same diagram and the tool will mark classes reverse engineered from code with a glyph in the upper left hand corner.
There is a new “Browse Diagram” capability which allows the user to explore existing code by quickly generating class diagrams “on the fly” showing classes related to a selected class. Selecting a different class on this diagram will generated yet another diagram on the fly with all classes related to that class. This quick navigation from one diagram to another is a great way to “get to know” code someone else wrote. You can control which kinds of relationships are included when the class diagrams are created and how many levels (up to 3) removed from the selected class in the center of the diagram. I made great use of this on my project.
(Drum roll please!) I can reverse engineer Java method bodies into UML Sequence Diagrams by “visualizing” a “Static Method Sequence Diagram.” This type of program understanding tool has long been missing from UML modeling tools. It will be a windfall to any poor soul who must maintain/modify poorly documented Java code created by someone else who is perhaps no longer around. The only downside is that if the method makes any calls to low-level Java classes like “Integer” those method calls will clutter the generated diagram. But.. think of the time you’ll save!
Together, these reverse engineering capabilities will just about take away the last excuses for not having design documentation match the “as implemented” state of the Java code. It really is easy to create both class and sequence diagrams and rapidly document both the static and dynamic behavior of “as is” Java software.
Copyright © 2006 by Philip Hartman - All Rights Reserved
The postings on this site are my own and don't necessarily represent IBM's positions, strategies, or opinions.

On War and Aggessive Project Schedules

I recently attended a 3-day "Business Design Assurance" or BDA held by my client. On the first day it was clear that there were still a lot of unresolved issues and the desired delivery date of the rollout to the first country was a risk. There was a lot of talk along the lines of "we can't go live without XXX!" A certain Senior Vice President could not attend the second day of the BDA but had the following as a message posted on the wall when everyone arrived for the second day of discussion.
"A good plan today violently executed is better than a perfect plan next week!"
General George S. Patton
The postings on this site are my own and don't necessarily represent IBM's positions, strategies, or opinions.

Perils of Over-Customizing SAP-Broken Reports

I've been around clients for some great discussion on the perils of over-customizing SAP lately. I hope to collect some of the lessons learned here for your reading enjoyment and career enrichment.
Here's a comment made by a country sales manager at a meeting I attended in May 2007.
"They told us that the new SAP system would have over 160 reports out-of-the-box that we could use to run our business and we didn't plan on having to create a lot of custom reports. Now they tell us that's not true. Almost all the out-of-the-box reports are broken. Almost every report we need must be a custom development."

It seems this company made some customizations to their base SAP system (ECC) when they were only operating in a only single country and were focused only on a transactional, commodity type business model. They then moved into multiple countries and began to look closely at big, relational customers and value-added services. To support this, they planned to create a new CRM system running on top of their existing ECC. They were not happy to find out that their legacy of prior ECC customizations "broke" a lot of the standard SAP reports.
I'd love to hear from other people who might have an SAP over-customization lesson to share.
Copyright © 2007 by Philip Hartman - All Rights Reserved

The Global Lifestyle Time Challenge

I had a subtle career milestone today. Today I became fully aware that I was now "Global" ... with a capital "G" I think.

At about 6:30 am Central time I checked email at home before leaving for the airport. I saw an email from a business leader in the UK which set off alarms in my head that an important business decision my client needed to make was not being addressed. Knowing that a politically important deadline is approaching, I fired off a "this is a big issue!" email designed to alarm my readers that something important was not happening.

About 8 am Central time today I was waiting for a flight at the airport and my cell phone went off. It was that same business leader in the UK who took notice of my alarm. I don't know about you, but I don't get cell phone calls from people I've never met from other countries every day.

Shortly after arriving at my destination on the East Coast of the US, I scheduled a web meeting for tomorrow morning between people in Baltimore, Raleigh, California, and Beijing.

Later I was on a call between the US and Canada talking about interfaces to a system in China.

Still later I discussed architecture diagrams showing system components in Rochester (NY), Boulder, Dallas, Tulsa, Phoenix, Hong Kong, Beijing, and Toronto. I tried to figure out if the component in Hong Kong was really necessary. Could it be co-located with the rest of the stuff in Beijing?

I ate a hurried dinner of Tandoori Takki with two co-workers. One is a Norwegian citizen born in China but holding an American green card and the other was born in India but has been working in the US for a while. My history is boring compared to theirs.

Five minutes after checking into my hotel, I joined a conference call between the US and China but the co-worker from China didn't make the call. My co-worker later came online in China on instant messenger later and I pinged him about the call he missed. It turned out he was double booked for that timeslot. Heavy sigh. When are we going to solve time zone issues for calendars? I made sure he had the information for the web meeting in 9 hours.

This globalization thing isn't all its cracked up to be. Exactly when is it I am supposed to have some calm moments to think? When is it I am supposed to get more exercize like my doctor told me? Will the guy in California get up to make the web meeting at 6 am his time? Did I even have a right to call a web meeting that required someone to be there at 6 am? Will the guy in Beijing who has to join at 9 pm his time have a decent Internet connection? Did I have a choice on the time given that the guy we want to talk to was available then and it was a comfortable 9 am for him? Will my flight home on Friday be on time so I can make my daughter's piano recital? How early do I set my alarm clock for tomorrow? Early enough to hit the hotel treadmill or late enough to get another hour of sleep?

I have another trip to China coming up in two weeks. It is still fun for now. I can see how this could get old. I would love to hear how my readers in similar situations are handling the demanding hours, encroachment upon personal time, cultural differences, etc.

FYI, globalization has been a frequent topic of mine. You might take a look at some previous posts such as:

The Globalized I/T Architect
Are All the Good I/T, Science, and Engineering Jobs Going Overseas?
Word from the China Front
Copyright © 2007 by Philip Hartman - All Rights Reserved
The postings on this site are my own and don't necessarily represent IBM's positions, strategies, or opinions.

Learn to Love Your SAP IDoc

Over a year ago, I had a post in which I discussed how difficult it is for a custom application development person like myself to get adjusted to projects based on a packaged application like SAP. It had the somewhat humorous title How to Talk to an SAP Consultant (If You Must).
If you keep reading this post, you will see that I am now starting to understand some of the SAP terminology which once seemed so incomprehensible. I hope you will find this post helps accelerate your own understanding of SAP if you are thrust into it like I was.
I now have become all too familiar with the SAP interfaces for external system known by the name "IDoc".
SearchSAP.com provides the following definition:
IDoc (for intermediate document) is a standard data structure for electronic data interchange (EDI) between application programs written for the popular SAP business system or between an SAP application and an external program.
Being relatively new to the SAP world, these complex documents reminded me of database schemas generated by the old Computer-Aided Software Engineering (CASE) tools with many cryptic table names and field names that only an automated tool could keep track of.
For example, suppose you want to create an order from an external system in the Customer Relationship Management (CRM) module of SAP. What would you expect the interface to be called? How about something like "Create Order"? Wrong! My client's CRM team first instructed us to use a standard IDoc going by the rather unintuitive name of "CRMXIF_ORDER_SAVE_M02". Shortly later, they decided that this standard IDoc would not meet all their business requirements and they created a new IDoc from the standard one and gave it a name they prefixed with a "Z" and added a different ending. I will stick with the standard create order IDoc for this post, however.
Ok, suppose you get past that detail, get into the right IDoc and start looking for the data representing the order header. Do you find it under something like "Order Header" or "Order"? No! Try looking for something SAP calls a "segment" and whose name is "E101CRMXIF_BUSTRANS".
help.sap.com has this to say about segments:
Segments form the basic building blocks of an IDoc type and are used to store the actual data.
A segment type is the name of a segment and is independent of the SAP release.
The segment definition is the release-specific name of a segment. By combining the segment type and the release, the required segment definition can be determined: This way, you can assign segment definitions from previous releases to an IDoc type in the current release. This may be necessary if, for example, the partner is using an older release which supports your current IDoc type but not your current segment definitions. You then have to "reset" these in the Partner profiles .
This segment type name is not completely random but is based on the phrase "business transaction" instead of order. I believe the addition of "E101CRMXIF_" to the beginning makes the segment type release-specific and specifies the segment definition.
Each segment can in turn have multiple fields. Some of these fields can contain data defined by another segment. These can be optional or mandatory. One segment can have a 1:1 or 1:n relationship with another segment. For example, the standard E101CRMXIF_BUSTRANS segment looks like this when I look at it in the XML editor of Rational Software Architect v7 (though truncated to what would display on my screen and still be readable): Note that the order segment has many individual elements (mostly strings) followed my many references to other segments. The graphical representation looks a lot like an object model or database design.
An entire SAP IDoc can be huge! The entire IDoc for orders includes well over 200 IDoc segments. After I used my XML editor to format the XML schema of CRMXIF_ORDER_SAVE_M02 so that it was neatly indented and had line feeds before each level of nesting, the resulting XML schema file was a mere 38257 lines long.
If your next project takes you down to the implementation level of SAP, I hope you're a detail-oriented person.
Copyright © 2007 by Philip Hartman - All Rights Reserved
The postings on this site are my own and don't necessarily represent IBM's positions, strategies, or opinions.