How do I manage changes to the Onyx Employee Portal UCW?

With Onyx CRM version 6.0 and Consona CCM 7.0, you have a great feature called UCW (UI Configuration Workbench). There are several benefits to using the UCW. The Onyx Employee Portal 6.0 Technical Guide lists the main ones as:

Ease of configuration: UCW provides WYSIWYG configuration of many areas in OEP, enabling you to configure, compile, and test your configurations, including changes to user navigation and form presentation and behavior.

Custom OEP pages for different teams: Using UCW and OEP Profiles, you can configure the same OEP page differently for different teams in your organization, enabling profile-based user navigation and page presentation and behavior. You can apply your UCW configurations to one or more custom UIs (accessed via the related OEP profiles) or to all custom UIs at once (using the baseline UI accessed with the Global profile).

Upgradeability: When you configure OEP using UCW, you ensure that your UI configurations will be upgraded to the next version of OEP without requiring you to rewrite or re-implement your modifications. Customizations that are implemented outside of UCW, however, are not automatically applied when OEP is upgraded.

However, while the technical documentation has some best practices and tips and tricks, what isn’t well-documented is how to work with the UCW so that you can more effectively manage your UI changes. This post will show you how to split your UI changes into layers.

Following the approach I am about to describe has the following benefits:

• Several developers can simultaneously work on different UI features at the same time (in different developer environments) without causing any dependency issues or needing to “check out” or lock files.
• Changes to one area of the UI can be deployed without worrying about changes in other areas.
• Splitting the changes into layers means that you can “throw away” or remove whole areas of customizations without needing to manually edit the global delta xml files or delete your changes through the UI.

How does this work?

It’s very simple. When you make changes in the Onyx / Consona UI, the UCW framework is tracking those changes and adding all of your actions to one file called global_delta.xml. This file is found here:

EmployeePortal\ucf\data\layers\active

By default, all of your changes live in this file, whether they are changes to the company edit screen, the incident edit page, or the powerpage. This is undesirable and means that all of your customizations have dependencies and only one person can work on UCW at a time, even if you have several development environments, so it’s best to break up the work into custom layers.

Before your start, please add your Onyx UI files to source control! There are many choices and a lot of them are free. We use Assembla’s hosted Subversion repositories.

To add a custom layer, follow these steps:

1. Navigate to EmployeePortal\custom\ucf\data\layers.
2. Create an empty folder with your layer name. For example, if you want to add a layer for the company powerpage, name this folder companypowerpage.
3. Navigate to EmployeePortal\ucf\data\configuration.
4. Add the path to your layer to the layers.xml file. Set the sequence number so that this comes before the active layer and after the onyxvalidation layer. Adjust the sequence number of the following layers. In the screenshot below, we have added two custom layers: one for the company powerpage and one for the company edit screen.

The first time you edit your new layer:

1. Navigate to EmployeePortal\ucf\data\layers\active – ensure that this is empty!
2. Make your changes to the layer you are configuring.
3. Move (not copy) the global_delta.xml file that has been generated in the ucf\data\layers\active folder back to the folder you created within custom\ucf\data\layers

Each subsequent time you edit your new layer:

1. Navigate to EmployeePortal\ucf\data\layers\active – ensure that this is empty!
2. Move (not copy) the global_delta.xml file within custom\ucf\data\layers over to the ucf\data\layers\active folder
3. Make your changes to the layer you are configuring.
4. Move (not copy) the global_delta.xml file that has been modified in the ucf\data\layers\active folder back to the folder you created within custom\ucf\data\layers

That’s it! Now you can effectively separate all of your Onyx UI changes into a more manageable structure.

The Fuss about Test Driven Development

There has been a lot of debate about the benefits, or otherwise, of Test-Driven Development (TDD). In this short post, I will attempt to enumerate some of the benefits, and show that practicing TDD means that your code becomes an asset to the business, instead of a liability. I will also point you to a few resources that will help you get started with TDD.

What is Test Driven Development?

Most people have heard the term Test-Driven Development (or TDD), but not everyone seems to understand what it means, so we’ll start with a brief definition:

Test-driven development (TDD) is a software development technique that relies on the repetition of a very short development cycle: First the developer writes a failing automated test case that defines a desired improvement or new function, then produces code to pass that test and finally refactors the new code to acceptable standards.

The Four Rules of TDD

Robert C. Martin, wrote a famous blog post that defined the three rules of test driven development.

You are not allowed to write any production code unless it is to make a failing unit test pass.

You are not allowed to write any more of a unit test than is sufficient to fail.

You are not allowed to write any more production code than is sufficient to pass the one failing unit test.

While Bob mentions refactoring as part of the TDD cycle in his post, I think it’s important enough to be its own rule. So rule 4 reads:

4.  You should refactor your code once the tests pass.

It’s a technique that needs to be witnessed and practiced to really be used effectively. The steps are very small, with each cycle lasting perhaps five minutes at most. This means that you make lots of tiny steps towards your goal throughout your day, but each step is a “mini-milestone”, because once you get to the Green bar (or to the step where all of your test are passing), your code is in a known good state. This makes it simpler to return to that good known state via the undo button if you take a wrong turn and can’t get the next test to pass. This is a really refreshing change from spending hours in the debugger trying to figure out where you went wrong!

There are many productivity benefits to TDD that outweigh the additional time taken to create the tests. These include working code, less time debugging and a suite of automated regression tests that can be ran at any time. In addition, the tests allow us to change, or refactor the code without fear of breaking it.

One final point before I move on to discuss how to get started: TDD generates unit tests, but unit testing is not the same as TDD! In TDD, the tests come first, before the code they are testing and are automated. In unit testing, the tests typically come after the code, and are not always automated.

Code Katas

Given all of these benefits, it should be a no-brainer to decide whether or not to adopt this practice. And yet, there have recently been some debates about its effectiveness. I’m not going to recount these debates here, as my philosophy is “just do it”. If you want to know if TDD works, but you are worried about the amount of time it would take to investigate, then follow the kata approach. Wikipedia defines a kata as:

Kata (型 or 形, literally: “form”) is a Japanese word describing detailed choreographed patterns of movements practised either solo or in pairs.

While katas are most often associated with martial arts, it has also become a popular phrase for working with code. Again, from Wikipedia:

Code Kata is a term coined by Dave Thomas… A code kata is an exercise in programming which helps hone your skills through practice and repetition.

If you are interested in learning about TDD and code katas, simply set aside a short amount of time each day and start to experiment. To get you started, here are a few resources:

• Dave Thomas has posted several katas on his Code Kata website.
• Some screencasts of katas from the Software Craftsmanship website.
• Robert C. Martin’s screencast of his Prime Factors kata in Ruby.

In addition, you should really beg, steal or borrow (or alternatively, just buy) these books:

• Test Driven Development: By Example by Kent Beck
• Clean Code: A Handbook of Agile Software Craftsmanship by Robert C. Martin
• Refactoring: Improving the Design of Existing Code by Martin Fowler

In the future, we’ll be posting articles about different unit testing frameworks and techniques; until then, good luck getting started with TDD!

Jasmine – JavaScript Unit Testing Framework

I recently joined a project which includes a substantial amount of user interface web development. I have typically been involved in projects as a middle tier/database developer, or at most extending an existing user interface using pre-packaged software. I want to utilize the same TDD (Test Driven Development) approach to UI coding as well and this led me down the path to find a JavaScript Unit Testing Framework that is as robust as NUnit *and* is actively maintained. Doing a Google search led me to find the Jasmine Unit Testing Framework by Pivotal Labs that satisfied both criteria (latest code update was 10/5/2010!). Below are some of the key points that piqued my interest in this framework.

• Suites – allows grouping of Specs (Tests). Included is also the idea of Nested Suites.
• Disabling – Easily disable Specs or Suites by, without having to comment out code
• Matchers – built in support for numerous expectations (Assertions) such as .toBe(), .toBeNull(), .toBeTruthy(), toBeFalsy() etc. Ability to easily add Custom Matchers (assertions).
• Setup and Teardown fixtures – beforeEach() can execute at the beginning of a suite or before every single spec. Similarly afterEach() can execute after all specs have been executed in a suite or after every spec. In addition, there is support for an after() method to be requested during a single spec execution and will execute regardless if a spec finishes successfully or not.
• Spies – Jasmine integrates ‘spies’ that permit many spying, mocking, and faking behaviors. Some interesting methods that can be invoked on spies:spyOn(x, ‘method’).andCallThrough(): spies on AND calls the original function spied onspyOn(x, ‘method’).andReturn(arguments): returns passed arguments when spy is called

  spyOn(x, ‘method’).andThrow(exception): throws passed exception when spy is called

  spyOn(x, ‘method’).andCallFake(function): calls passed function when spy is called

• Asynchronous Specs – Ability to invoke a function and have Jasmine wait for a period of time, checking the result of the function call in order to execute the spec.

While these are the high level features of Jasmine, they provide a robust framework similar to what I have come to expect from compiled code testing frameworks. I will post examples of how to use Jasmine in future blog posts.

Happy Testing!

Watts Humphrey, 1927 – 2010

I just read that Watts Humphrey has passed away at the age of 83. My thoughts are with the family and friends of this great man, who cared deeply about improving software engineering processes. He founded the Software Process Program at Carnegie Mellon University and wrote several books on understanding and improving the process of developing software.

There’s an obituary from the university here: http://www.cmu.edu/news/archive/2010/October/oct28_wattshumphreyobit.shtml

Rest in peace, sir.

The Waterfall approach to reading

I was chatting to my wife the other evening and started to discuss reading lists. I wondered aloud how many years I had to live (30? 40? 50?), and was thinking about how many more books I would be able to read in that time.  A book a week for 40 years would mean I could read about 2,000 more books in my lifetime.

A quick search netted this wonderful article from the Guardian Online: 1000 novels everyone must read, so that was a great starting point.

I thought about how the task of building a reading list would look like if I approached the task like a software project.

The Waterfall Approach

1. Use the Guardian article, Amazon reviews and recommendations to create the complete list of 2,000 books I am going to read.
2. Prioritize the list.
3. Buy all of the books in the list.
4. Work through the list, reading the books in order.

Now deciding ahead of time what you are going to read for the next forty years is clearly ludicrous, as so much will change in that time.  My interests and priorities will change. The world will change. The available books will change. Even the cost and technologies for delivering books will change. All of this means that making decisions now about events far in the future is a pointless and expensive exercise, as most of the books in the list would go unread.

The Agile Approach

1. Decide how far ahead you want to plan – far enough to avoid running out of books to read, but not so far as to make change costly.
2. Make a much shorter list of books to read.
3. Prioritize the list.
4. Buy the first few books in the list.
5. Keep updating this shortlist as your interests change and new books are published.

This approach has the advantage of having less overhead to maintain (a few books instead of 2,000), cheaper (less cost and inventory up front) and more flexibility (the list can change more easily over time).

Don’t plan in detail too far ahead, but be prepared for change

On many software projects, we are asked to plan iterations and projects months and even years into the future. This is as foolish as planning your reading list far in advance.

Just as most of the 2,000 books in our waterfall reading list would probably go unread, by the time we get to the end of a long software project, we know so much more about what we need to do and so much has changed that a lot of the later detailed planning has to be completely redone as it is worthless and out of date.

I’m not saying it’s worthless to have high level plans – in fact this is really important. We need to know if certain things have to be lined up ahead of time (for example communicating release plans and outages, getting users trained, making sure other teams are ready for the downstream affects of our changes) and we need to know when the last responsible moment to make those decisions will be.

We also often need to provide our customers with a ballpark idea of the costs and schedule of a project (is it a week? a month? a year?) before the project begins, but we shouldn’t treat this as being cast in stone. The plan has to be flexible enough to change with the landscape. The cost and schedule estimates need to be improved and updated as time goes on, as uncertainties about the project are reduced (I’ll write more about this in another blog post).

While a high level plan is a good thing, what is foolish is detailed design, task planning, assignment and estimating for items far in the future of a project. While this may give the illusion of control and predictability, it is just that: an illusion. In fact it’s harmful to have that level of detail because the more design artifacts and task details that need to change in a project, the higher the overhead of maintaining these details and the more rigid the project will become.

Just like keeping your reading list short and easy to change, you should keep your iterations and detailed project plan short. This will give you a flexible plan that can adapt as the project progresses.

For more ideas about shrinking your iterations, see my recent blog post on the topic.