ATG CSC UI Customization

note: this is post three in my ATG CSC and why I hate it series:

UI Modification

Mostly customers using ATG CSC will want to make at least minor UI customizations. This could include providing information to CSRs about alternate payment types (PayPal, BillMeLater, Gift Cards), displaying customer loyalty program status, or more involved changes to support non-standard actions or flows.

Commerce Assist UI

When modifying the UI of the old Commerce Assist product, you basically ended up loading the DCS-CSR WAR into your own project (SVN/Eclipse), editing it’s JSPs directly, and deploying it out at the ATG install as part of your build process. While a little hacky, it was a very straight forward and simple process. Most of the JSPs were simple and used a small number of basic included files to support common fragments. Looking at a page in the Commerce Assist tool, and then tracking down which JSP you’d need to modify to change the page was very easy. The whole UI was driving using a single WAR filled with straightforward JSP files. With an Eclipse builder setup to call an ANT task that copies out the JSPs, you can actually see your UI changes in the Commerce Assist application in real time; no building, no bouncing. Simple.

ATG CSC UI

The new CSC tool’s UI is a much more complicated beast. The user interface is built dynamically using a mis-mash of JSPs and JSP fragments coming from two completely different WARs. The overall Service interface mostly comes from the agent.war, which is part of the Service module, where as commerce specific elements (such as order presentation and manipulation, catalog browsing, etc…) are pulled from the CSC’s DCS-CSR.war. There are many more JSP fragments and includes used, and the organization of the file is much more complex and confusing than the old Commerce Assist.

UI Framework Repository Data

The way the interface is built, how tabs and panels are presented, is managed via repository items in the database. These UI Framework items are the reason that you have to run a CA instance within CSC. This CA instance is used to deploy out the data used to build the UI. Until you setup CA and run a Full Deployment, you can’t even hit the CSC at all, since none of this data is available. Perhaps there is a good reason that these UI data elements need to be versioned and deployed from a workflow, independent of code/JSP development that makes sense in ATG Service, but within the context of CSC I doesn’t make any sense to me.

UI Components

Presumably in order to make UI customization easier, the JSPs (both from agent.war and DCS-CSR.war) include many fragments, and many of these fragments aren’t loaded via simple includes, but instead have includes referencing properties on Nucleus components. There are a number of undocumented components which each point to a JSP URI and a context root. For instance, a JSP representing a panel within the UI might include three sub-fragments by referencing three different ATG components, and doing each include based on properties of that component.

The premise is that instead of having to load the ATG WAR(s) into your project, and modify JSP files within the WARs, you can create a new custom WAR (myapp-csc.war), create new JSPs in that WAR for whatever overrides you need to make, and using the config layer override the URL and context root on the appropriate UI component. Then the parent JSP will include your custom JSP fragment from your WAR instead of the default JSP fragment.

This sounds great! Unfortunately it all breaks down about 5 minutes after you start actually looking at the JSPs.

The first issue is that many of the fragments you’d like to modify use a JSP (not DSP) include of a top.jspf file. You can’t just copy and paste the original JSP to your new JSP and modify it in place, because that include will fail and break most of the original functionality of the fragment. Because it’s a JSP include you can’t point it back at the original WAR context root. You have to copy the top.jspf into your war. However, agent.war and DCS-CSR.war have two different top.jspf files (in the same relative path), for instance one loads in the dsp taglib with a prefix of “dsp” while the other uses a prefix of “dspel” as well as many other differences. So assuming you want to override JSPs from both WARs, which is pretty likely, you have to copy in both, rename them, and reference the correct one for each of your custom JSPs. As far as I could tell, none of this was documented. Then you go ahead and setup your config layer overrides, build, and deploy.

The second issue is that there’s a great deal of logic and markup that is NOT in JSP fragments loaded in this way. As soon as you hit this scenario (which you will), you’re back to loading in the ATG WARs into your project, modifying the JSPs directly, and building out your customized versions of the WARs to the ATG install for assembly into the EAR. Only now you’re doing it on two WARs, not one.

As soon as you hit the second issue, you have to question the logic of using the configuration system at all, since it just adds more complexity, and you’re probably better off just working with the ATG WARs you have in your project.

Extensive markup and logic is hidden in tags

Then you’ll find some section of the UI that you need to change, only you can’t find the JSP that’s creating the markup. This is because there are JSP tags which include hundreds of lines of HTML output and JSP logic (DCS-CSR.war/WEb-INF/tags/displayOrderSummary.tag is a great example of this). So now you’re modifying tags as well as JSPs.

AJAX and DOJO

Another element that increases the complexity is that much of the interface is now AJAX driven, so pages are built and rebuilt via Javascript and AJAX calls, not just straight forward JSP. Figuring out how to make modifications to an AJAX driven UI is complex enough when its your own application and code, it’s MUCH harder when it’s two (two WARs) black boxes of DOJO magic with no documentation.

To summarize

In order to make relatively minor modifications to the CSC’s UI, you have to deal with:

1. UI Framework Data in the DB and deployed via CA
2. A custom WAR with JSP overrides and config files to override UI component properties
3. JSPs in DCS-CSR.war, which you’ve had to add to your project and edit directly
4. JSPs in agent.war, which you’ve had to add to your project and edit directly
5. Tags in both wars
6. Undocumented DOJO AJAX logic

It’s a real pain. I’m sure many of the changes were well intentioned, but in my experience when the rubber meets the road the new UI system makes customization and debugging much more difficult.