At WWDC 2009, Eric Hope talked about crafting the best iPhone apps at his iPhone User Interface Design session (the one where Cultured Code likened public speaking to kryptonite). The first step was coming up with an Application Definition Statement. It should define what your app is and what it isn’t. The statement should include a differentiator (your app’s strength), a solution (the problem you’re solving), and an audience (the people who care), or as my Ruby-esque notes read, “#{differentiator} #{solution} for #{audience}”. The goal of the statement was to focus your app. Mac apps could have a long list of features, but the iPhone was a far more constrained environment. Hope’s example was iPhoto. On the Mac, it views, edits, shares, prints, and what not; on the iPhone, it shares, nothing else.

That talk was almost three years ago. Things have moved forward. The iOS environment is less constrained, particularly with the iPad. Apps can do more, and iPhoto is a great example. In March, Apple released an iPhoto for iOS that contained editing abilities.

Retrospect for iOS has followed a similar path. What started as a very simple app has grown up a bit.

Retrospect for iOS 1.0

I wrote Retrospect for iOS 1.0 in December 2009, just for fun. For the Application Definition Statement, I came up with “a serious tool to monitor multiple Retrospect servers”. No control, just monitoring. I focused on activities. Viewing activities for a Retrospect server gives administrators a high-level view into what’s going on. If everything looks good, no action required; if not, they should launch Retrospect for Mac to dig deeper. Our designer hand-crafted a set of awesome icons, and we submitted it to the App Store.

The app was a moderate success. It was downloaded around 5,000 times and received a glowing review from Economist writer Glenn Fleishman (a long-time Retrospect user), who praised its “outstanding distillation”. The app didn’t do much beyond viewing activities, but it did that task well. Still, it didn’t replace Retrospect for Mac, and it didn’t support the iPad. Just as Apple updated its definition of what iPhoto for iOS was, I recently decided it was time for Retrospect for iOS 2.0.

Retrospect for iOS 2.0

What did the first version lack? Control. Complete monitoring. Better server support. iPad support. That’s the list I came up with in December 2011. I decided the app should display everything that the Mac version did: Activities, Past Backups, Scripts, Sources, Media Sets, Devices, and Reports. I even added badges to each report. I added full support for the latest Mac and Windows Retrospect servers and partial support for a couple versions before those. And I finally enabled control within the app: running scripts. I submitted v2.0 in February.

Close but not quite. While most of the new features were significant improvements, one failure erased all of those gains: syncing. Retrospect stores quite a bit of information, and when I expanded the list of items displayed on the iOS app, it translated into syncing times that were 10x to 100x longer. The UI prevented the user from looking at a server until it was synced, so the user might launch the app but then wait a long time before being able to monitor the server. Moreover, the iPad UI did not take advantage of the space. It looked like an iPhone app at “2x” but without the pixelation.

Retrospect for iOS 2.1

With v2.1, I fixed those two issues. Syncing is now done by item type. Users can view activities before media sets finish syncing. I also added split-screen support to the iPad UI to make better use of the space available.

This latest version of Retrospect for iOS is now available on the App Store. If you use Retrospect and have an iOS device, give it a try. It’s free.

Rails 3.0 handles routing errors (ActionController::RoutingError) differently than Rails 2.3. The middleware addition means the error is passed to ActionDispatch, instead of ApplicationController. A bit ago, I actually removed the catch-all route at the bottom of routes.rb because I thought the ApplicationController::rescue_from handled any routing errors. Not true. Rails 3.2 doesn’t resolved it either.

There is an open GitHub issue for it: “Can no longer rescue_from ActionController::RoutingError”. (In fact, it’s old enough to be an issue migrated from Lighthouse.) There are several solutions posted inline in the issue’s comments. José Valim from the Rails core team suggests simply adding the catch-all route back to routes.rb; others suggest overriding ActionDispatch::ShowExceptions::render_exception. All seem focused on rendering the 404 page manually. However, I wanted to make rescue_from work. My solution is the catch-all route and raising the exception manually.

# routes.rb

# Any other routes are handled here (as ActionDispatch prevents RoutingError from hitting ApplicationController::rescue_action).
match "*path", :to => "application#routing_error"

# application_controller.rb

rescue_from ActionController::RoutingError, :with => :render_not_found

def routing_error
  raise ActionController::RoutingError.new(params[:path])
end

def render_not_found
  render :template => "misc/404"
end

Apple’s iOS Mail has a universal inbox on iOS 4. Very handy in general, but its unread badges complete the feature. I frequently glance down the list of email addresses I have and know exactly what the state of my inboxes are. I never have to wonder how many new emails I have. I just check the numbers.

Recently, I needed to duplicate that feature for work. I found two existing solutions:

• TDBadgedCell (GitHub repo)
• DDBadgeViewCell (GitHub repo)

I ended up forking DDBadgeViewCell. It was concise, and I only needed to make a couple changes to it. Specifically, I wanted the badges to look exactly like Mail’s badges, in terms of alignment, colors, and shadows. I’ll go through my changes here, but you can check out my GitHub fork as well. See the image for the resulting look:

Badge color

I wanted to duplicate Mail’s look and feel, so I needed the exact colors that Mail uses for its badges. xScope made it easy.

UIColor *badgeColor = [UIColor colorWithRed:0.55 green:0.6 blue:0.69 alpha:1.];
UIColor *badgeShadowColor = [UIColor colorWithRed:0.45 green:0.49 blue:0.57 alpha:1.];

Badge shadow

If you look closely at Mail’s badges, you’ll notice the top part of the arc looks indented. The shadow gives the label a feeling of depth; the badge looks almost letter-pressed. To duplicate that look, I simply drew a darker oval one pixel higher than the original before drawing the real one.

// Draw the badge shadow.
CGContextSaveGState(context);
CGContextSetFillColorWithColor(context, currentBadgeShadowColor.CGColor);
CGMutablePathRef shadowPath = CGPathCreateMutable();
CGPathAddArc(shadowPath, NULL, badgeViewFrame.origin.x + badgeViewFrame.size.width - badgeViewFrame.size.height / 2, badgeViewFrame.origin.y + badgeViewFrame.size.height / 2, badgeViewFrame.size.height / 2, M_PI / 2, M_PI * 3 / 2, YES);
CGPathAddArc(shadowPath, NULL, badgeViewFrame.origin.x + badgeViewFrame.size.height / 2, badgeViewFrame.origin.y + badgeViewFrame.size.height / 2, badgeViewFrame.size.height / 2, M_PI * 3 / 2, M_PI / 2, YES);
CGContextAddPath(context, shadowPath);
CGContextDrawPath(context, kCGPathFill);
CFRelease(shadowPath);
CGContextRestoreGState(context);

Pixel Perfect

DDBadgeViewCell does an excellent job when there are three or more characters in the string. But as I wanted to display numbers, I needed to special-case the code a bit to get the pixels correctly aligned.

// Set up the badge's frame.
CGSize badgeTextSize = [self.cell.badgeText sizeWithFont:[UIFont boldSystemFontOfSize:18.]];
CGRect badgeViewFrame = CGRectIntegral(CGRectMake(rect.size.width - badgeTextSize.width - 24, (rect.size.height - badgeTextSize.height - 4) / 2, badgeTextSize.width + 14, badgeTextSize.height + 4));
if ([self.cell.badgeText length] < 3) {
    // Fix the width for 1-2 characters.
    badgeViewFrame = CGRectIntegral(CGRectMake(rect.size.width - 46, 13, 34, 25));
}

// Draw the badge shadow oval and the badge oval...

// Draw the number on the badge.
CGContextSaveGState(context);
CGContextSetBlendMode(context, kCGBlendModeClear);
if ([self.cell.badgeText length] == 1) {
	// CGRectInset cuts off the label by a couple pixels, so need a bit more tweaking.
	CGRect badgeTextFrame = CGRectInset(badgeViewFrame, 11, 2);
	badgeTextFrame = CGRectMake(badgeTextFrame.origin.x + 1, badgeTextFrame.origin.y, badgeTextFrame.size.width + 2, badgeTextFrame.size.height);
	[self.cell.badgeText drawInRect:badgeTextFrame withFont:[UIFont boldSystemFontOfSize:18]];
}
else if ([self.cell.badgeText length] == 2) {
	// CGRectInset cuts off the label by a couple pixels, so need a bit more tweaking.
	CGRect badgeTextFrame = CGRectInset(badgeViewFrame, 6, 2);
	badgeTextFrame = CGRectMake(badgeTextFrame.origin.x + 1, badgeTextFrame.origin.y, badgeTextFrame.size.width + 4, badgeTextFrame.size.height);
	[self.cell.badgeText drawInRect:badgeTextFrame withFont:[UIFont boldSystemFontOfSize:18]];
}
else {
	CGRect badgeTextFrame = CGRectInset(badgeViewFrame, 7, 2);
	badgeTextFrame = CGRectMake(badgeTextFrame.origin.x, badgeTextFrame.origin.y + 1, badgeTextFrame.size.width + 4, badgeTextFrame.size.height);
    [self.cell.badgeText drawInRect:badgeTextFrame withFont:[UIFont boldSystemFontOfSize:18.]];
    CGContextRestoreGState(context);
}
CGContextRestoreGState(context);

On the iPhone, it’s quite normal to have an app slide a sheet up to create something or change settings. But on the iPad, that same view should be displayed in a popover. In a universal app, the key is shared code and XIBs for both approaches.

The code below is all that I needed to have a Settings sheet appear correctly in both an iPhone and iPad app. I simply identify the device type and then either present a popover controller or a modal view controller, using the same XIB. Clean code. Consistent interface.

// Main View Controller
- (IBAction)showSheet:(id)sender {
	if ([[UIDevice currentDevice] userInterfaceIdiom] == UIUserInterfaceIdiomPad) {
		// iPad
		if (!self.popoverController.popoverVisible) {
			self.popoverController = [[[UIPopoverController alloc] initWithContentViewController:self.myNavigationController] autorelease];
			self.popoverController.popoverContentSize = CGSizeMake(400, 400);
			self.popoverController.contentViewController.contentSizeForViewInPopover = CGSizeMake(400, 400);
			self.popoverController.delegate = self;
			// Present the popover from the bar button.
			[self.popoverController presentPopoverFromBarButtonItem:self.navigationItem.rightBarButtonItem permittedArrowDirections:UIPopoverArrowDirectionAny animated:YES];
		}
	}
	else {
		// iPhone
		[self.navigationController presentModalViewController:self.myNavigationController animated:YES];
	}
}

- (void)popoverControllerDidDismissPopover:(UIPopoverController *)aPopoverController {
	[self.popoverController dismissPopoverAnimated:YES];
}

- (MyNavigationController *)myNavigationController {
	if (myNavigationController == nil) {
		self.myNavigationController = [[UINavigationController alloc] initWithRootViewController:self.mySheetController] autorelease];
	}
	return myNavigationController;
}

- (MySheetController *)mySheetController {
	if (mySheetController == nil) {
		self.mySheetController = [[MySheetController alloc] initWithNibName:@"MySheetView" bundle:nil] autorelease];
	}
	return mySheetController;
}

// Sheet View Controller
- (void)viewWillAppear:(BOOL)animated {
	self.contentSizeForViewInPopover = CGMakeSize(400, 400);
	[super viewWillAppear:animated];
}

Xcode 4′s “Build and Archive” feature is extremely convenient. With it, I can build a distribution version of an app and archive it away, so that later, in Xcode Organizer, I can click on that instance and submit it to the App Store. Brilliant for individual developers. But at my work, we wanted a bit more: automation and multiple IPAs from a single binary. Both are easy with xcrun, part of Apple’s Developer Tools. (Thanks to Stackoverflow for the pointer!)

Standardized Keys and Certificates

At work, we wanted a standard set of keys and certificates to use for official builds. I went through the standard Apple Developer Center process of creating a certificate signing request with Keychain Access to generate the local keypair, and I created a distribution certificate with that signing request and loaded that into Keychain Access. Then in Keychain Access, I exported the certificate as distribution.cer and the private key as distribution.p12. Xcode needs these two files to correctly use the provisioning profile.

One small hiccup was “login” versus “System” in Keychain Access. I easily imported those two exported files into the “login” keychain in Keychain Access. However, Keychain Access would not import the private key into the “System” keychain and gave the following error: “An error has occurred. Unable to import an item.” I needed to use the “System” keychain, as our build system runs with elevated privileges. To get around this error, I simply needed to import the certificate and private key via Terminal instead:

# Run in Terminal.
sudo security import /path/to/distribution.cer -k /Library/Keychains/System.keychain
sudo security import /path/to/distribution.p12 -k /Library/Keychains/System.keychain

Don’t forget to change the “Access Control” for the private key to “Allow any application to access this item” for “System.keychain”. Otherwise, you’ll get a build error about “user interaction is not allowed”.

At this point, I had a copy of the certificate and private key in “login” and “System” in Keychain Access. I simply needed two provisioning profiles based on that certificate: an ad-hoc profile and an app store profile. I generated both in the iOS Provisioning Profile, Adhoc.mobileprovision and Appstore.mobileprovision, and imported those into Xcode.

With the certificate, private key, and two provisioning profiles loaded up, automating the build was straight-forward. In fact, by selecting the correct default configuration (Xcode 3.2.6), I can simply run Xcodebuild with no arguments to generate an App Store distribution app bundle.

Multiple IPAs from a single binary

Automated builds are nothing new or novel. There are some great suggestions for how to structure your Xcode configurations to simplify automation. What I really wanted were two files at the end: App.AdHoc.ipa and App.AppStore.ipa, ready to be tested ad-hoc or submitted to the App Store. Enter xcrun.

Apple distributes xcrun as part of its Xcode Developer package. The command line utility will take an app bundle and convert it into an IPA file with the supplied provisioning profile. The key part is the supplied provisioning profile can be different from the original one. Here is how I call it:

xcrun -sdk iphoneos PackageApplication 
   /path/to/bundle/AppName.app 
   -o /path/to/bundle/AppName.ipa 
   --sign "iPhone Distribution" 
   --embed /path/to/certificate

With this command, I can run a build and then generate two IPA files: one for ad-hoc distribution or one for App Store submission. All with the same binary. The community and the tools have progressed a bit since furbo’s “The final test” in 2008.

Over-The-Air ad-hoc distribution

Apple added support for over-the-air (OTA) distribution in iOS 4. It’s the best way to distribute builds to QA, much better than syncing through iTunes. These instructions worked perfectly for me. You don’t need an Enterprise iOS account to do this; I think that simply lets you get around managing UDIDs. Seriously, it’s easy and awesome.

Amazon’s AWS S3 is awesome. However, there are times when the API makes certain tasks a bit hard. Today, I wanted to delete a bucket with 100k files. AWS does not support deleting a bucket with files inside; you have to delete the files first.

First, I tried aws/s3. It supports :force when deleting buckets, in case they have files in them. That call was taking a long time, so I poked around the code. Unfortunately, the gem didn’t make some magic API call. It just looped:

def delete_all
  each do |object|
    object.delete
  end
  self
end

Next, I tried to find out how geemus’s brilliant fog gem handles this need. It doesn’t, because providers don’t.

Finally, I gave up that one API call dream and looked for what other people do. They use pagination and threads, and I ended up forking SFEley’s s3nuke script from GitHub. In the process of porting his solution from RightAWS to Fog, I discovered that fog handles auto-pagination internally. No need to mess with is_truncated or :marker. Quite nice.

This Ruby script deleted an S3 bucket with 100k files in 15 minutes.

Simply go into System Preferences and click on “Sharing”. In “Sharing”, select “Internet Sharing” and click “Wi-Fi Options…” to configure the network name. Then, just check the box for “Internet Sharing”.

Very useful in some instances.

But today, I wanted a bit more: an short absolute date and lines changed. Seeing the number of lines that changed per commit gives a better idea about the magnitude of the changes. Changing the date format was easy; adding the number of lines that changed was harder.

Below is a gist for the Ruby script I wrote. Instructions on setting it up as a Bash alias are embedded in it.

I’ll describe the process I used to migrate around 6K bugs.

Tools

Bugzilla’s importxml.pl: Bugzilla does ship with an import script. However, it’s specifically designed for moving bugs from one Bugzilla instance to another. As input, it takes an XML file of one or more bugs, assuming you just used the XML export built into Bugzilla. Makes sense. It meant that I just extract all the issues from JIRA and reformat them into Bugzilla’s DTD. I found it very helpful to add the --verbose flag for better errors.

./importxml.pl --verbose bug.xml
# The log below represents a successful import.
OK: Bug http://example.com/bugzilla/show_bug.cgi?id=1 imported as bug 1.

http://example.com/bugzilla/show_bug.cgi?id=1

Bugzilla’s checksetup.pl: Bugzilla will check your setup with this script and let you know if you are missing any Perl modules. In particular, for importing, you will need XML::Twig. Oddly, when I started the import process, I found that I was still missing XML::Parser, so I had to install that from CPAN as well. Also, the script changed the ownership and permissions of the bugzilla directory such that it was no longer accessible on the web; I had to recursively revert those like so:

chmod -R 754 bugzilla
chown -R nobody:apache bugzilla

nokogiri: This handy Ruby gem allowed me to use XPath to search through the JIRA XML files and extract specific fields and values. It’s extremely useful. It installs effortlessly on Lion (10.7) with a simple gem install nokogiri. Unfortunately, I was using Snow Leopard (10.6). Installing the gem on that OS was a small battle in itself. Finally, I used this gist and then followed steps here. That worked for me. Here are some handy snippets of Nokogiri in action:

# Element contains
doc.xpath("//h1[contains(.,'Could not find issue with issue key')]")
# Element value
doc.xpath("//item/updated")[0].text
# Attribute value
doc.xpath("//item/reporter/@username").text
# Value of subelement for element
doc.xpath("//attachment").each do |attachment|
  attachment_id = attachment.attributes["id"].value
end

JIRA Issues: There are a couple ways to export issues from JIRA. One obvious way is to simply search for the issues you want and click “View” at the top to select a different format, like XML. While straight-forward, this method has two significant downsides. First, data loss: comments are not included. Second, size: thousands of issues take a long time to process as a single XML file, and neither JIRA nor Chrome seemed happy about the size.

An alternative to this export is using curl to export issues individually. This process includes comments and involves lots of quick JIRA queries. As an added bonus, I can avoid any XML SAX state logic that a single large XML file would have needed, so I can focus on transforming issues into bugs in isolation. Sweet.

# Extract JIRA issues. (Figure out how many issues to include.)
(1..1000).each do |i|
  # Use curl with credentials to extract each JIRA issue's XML.
  xml = %x[curl -u username:password https://jira.example.com/si/jira.issueviews:issue-xml/BUG-#{i}/BUG-#{i}.xml]
  # Save the XML to a file.
  f=File.new("BUG-#{i}.xml","w")
  f.write(xml)
  f.close
end

JIRA Attachments: In addition to the issues, I wanted to extract all of the attachments. Luckily, JIRA provides a standard HTTP API for getting these files. We just need all of the attachment IDs from each extracted JIRA issue to access its attachments. We’ll save those to an attachments directory. Bugzilla actually imports attachments as embedded base64 strings in the XML files, but we’ll address that later. For now, we just want to save the attachments out of JIRA.

# Download all the JIRA attachments. We'll need to convert them to base64 and provide them inline to Bugzilla.
Dir.mkdir("attachments") if !Dir.exists?("attachments")
(1..1000).each do |i|
  puts i
  # Open the JIRA issue.
  doc = Nokogiri::XML(open(File.expand_path("BUG-#{i}.xml")))
  # Find all the attachment references.
  doc.xpath("//attachment").each do |attachment|
    # Get the attachment ID and file name.
    attachment_id = attachment.attributes["id"].value
    file_name = attachment.attributes["name"].value
    # Get the attachment contents using curl.
    contents = %x[curl -u username:password https://jira.example.com/secure/attachment/#{attachment_id}/#{file_name}]
    # Save the attachment.
    Dir.mkdir("attachments/BUG-#{i}") if !Dir.exists?("attachments/BUG-#{i}")
    f=File.new("attachments/BUG-#{i}/#{attachment_id}_#{file_name}","w")
    f.write(contents)
    f.close
  end
end

Bugzilla Field Values: Bugzilla will not automatically create people, products, versions, components, or milestones during the import process. Those need to already exist. Otherwise, Bugzilla will use the default product and component. In my case, they did already exist, but the names had been changed. To handle these changes, I map JIRA strings to Bugzilla strings in my main script.

jira2bugzilla.rb

At this point, we have all the tools and the data we need to tranform JIRA issues into Bugzilla bugs. I committed the full jira2bugzilla.rb Ruby script to a GitHub repo. It doesn’t work out of the box, as there are quite a few instance-specific variables, but the script provides a nice base. I’ll touch on a couple points:

Attachments: Bugzilla expects attachments embedded in the XML file, so we need to convert our binary files into base64 strings and then include them inline. Below is Ruby code to convert to base64. Keep in mind that the import process takes far longer when attachments are included.

# Get the attachment ID and name.
attachment_id = attachment.attributes["id"].value
file_name = attachment.attributes["name"].value
# Figure out where we saved it.
attachment_path = "BUG/#{bug_id}/#{attachment_id}_#{file_name}"
# Encode the file as base64.
encoded_file = Base64.encode64(IO.read("#{attachment_path}"))

Description: While JIRA gives the bug description its own element (description), Bugzilla considers it the first comment on the bug. When rewriting the JIRA issues into a Bugzilla bug, I needed to migrate the description into the first comment.

Severity: JIRA doesn’t seem to have a notion of severity, so I assigned a default severity to all the bugs.

QA Contact: JIRA doesn’t seem to have a notion of QA contact, so when setting up the components, be sure to assign the default QA contact correctly. The import script will assign each bug to the correct person.

Again, see this GitHub repo for the full jira2bugzilla.rb script. I simply run ruby jira2bugzilla.rb in the directory with all of the JIRA XML issues.

Waiting for Import

At this point, we have converted all the JIRA issues into Bugzilla bugs. Next, we transfer them onto the Bugzilla server into a subdirectory of the bugzilla installation, like bugzilla/bugs/. To import the bugs, I ran the following one-liner. It finds all the XML files, sorts them alphabetically, and feeds each one by one into the Bugzilla import script.

find . -name "BUG-*.xml" | sort -n | xargs -n 1 ./importxml.pl --verbose &> bug-import.log

The script imported 6K bugs in two hours. However, I didn’t include attachments. When I tried to import a single bug with a 5MB attachment, it took around thirty minutes. With multiple gigabytes of attachments, I opted to not include them.

Most importantly, check the log. The above one-liner pipes all of the log information to bug-import.log. Run tail -f bug-import.log while it’s running to make sure the process is working. Grep through the output afterwards for terms like “Bad” or “Error” to ensure all the bugs were imported. With 6K bugs, most imported correctly, but a few did not.

Atlassian

I just wanted to highlight that migrating away from Atlassian’s JIRA is not a reflection of their product. I was simply tasked with making it happen. Frankly, Atlassian has been doing an amazing job at steadily growing into a vertically integrated company. They received $60M in VC funding in 2010 to grow their business, and they’ve scooped up businesses like BitBucket and SourceTree. Just a couple weeks ago, they announced that their main products will now be available as cloud services. Atlassian seems to have a long-term strategy that they’re executing very well.

I recently switched over to Google Apps at work, and one obvious move was migrating everyone to Google Talk/Jabber. Seemed easy enough. I was sure there would be a checkbox in the Domain Dashboard’s Settings for that. I just wanted every domain user to have everyone else show up in Gmail Chat, Google Talk, and Jabber. I eventually translated this goal into this search: “automatically invite and accept all shared contacts”. Nothing.

Google Apps does not provide that level of support for domain-based chat. The service doesn’t even let domain users see a list of the other domain users. The Google Apps Directory (analogous to Exchange’s global address list or GAL) is only available from search and auto-complete and from their API. (“Contact Sharing” is enabled by default.). Their Contacts app is just not as advanced as the rest of their awesome services. Which is fine. They do provide an API and an app store: Google Apps Marketplace. Marketplace has several highly-rated Contacts apps (like SherpaTools and Shared Gmail Contacts), and Jabber provides a mechanism to invite users. Problem solved.

Still, figuring all that out wasn’t fun. I read many help articles, forum posts, and API docs before I was able to map my problem onto Google’s solutions. Stepping back, here are three lessons to think about:

1 – Design Decisions

Google Apps is composed of apps and APIs. Ideally, both would be full-featured. Unfortunately, development resources are often far more finite than Product Managers and customers can bear. You have to prioritize some features (a full API) over others (a full Contacts app).

In this case, Google very clearly likes APIs. For years, Google Apps has provided an API for internal people (Domain Profiles) and for external people (Shared Contacts). While the Google Apps’ Shared Contacts UI needs a bit of love, the API and app store allows other companies to write third-party apps to solve this problem. I’m sure the Google Apps team is working on revising the contact manager, but they’re also busy shipping features like Google+ support.

Moreover, I could accomplish my goal. I enabled “Automatically accept chat invitations between users” under Settings/Chat (Premier only), and then I wrote a quick Ruby script to invite coworkers with Jabber:

Design decisions are choices. The Google Apps team chose a complete Contacts API over a full-featured Contacts app. Customers appreciate finite resources even less than Product Managers. The key is to keep them in the loop.

2 – Keep Communicating

Yes, there is a way to solve my chat invitation problem and to manage Shared Contacts. No, I didn’t know what I was looking for. Searching through Google Apps’ forum site, I found dozens of conversations about how woefully inadequate the contact manager was. Companies were resistant to switching from Exchange to Google Apps solely because they would miss so many nice contact management features. These thread span from mid-2009 to last week.

However, I didn’t find a single reply from a Google employee, pointing the thread in the right direction. Google Apps’ Help states their position plainly enough: “As an alternative to using the APIs, explore the Google Apps Marketplace for products that can help you manage Contacts through a user-friendly interface.” But all those customers need an official voice to guide them. The Google Apps team chose APIs over apps, but it hasn’t been telling anyone on its own forums. I only figured out what I should be searching for by reading those dozens of posts.

You might have a great service, a great API, great documentation, and great forums. But if you’re not in the forums, answering questions, pointing out documentation, how will your customers understand how to solve their problems? It’s your job to translate their problems into your solutions and to set expectations.

3 – Manage Expectations

Google Apps is an interesting service. It is a clear example of how difficult it is these days for corporate services to keep up with consumer ones, as Google is behind both of them. When Google+ debuted, a number of Google Apps customers were upset that the feature wasn’t immediately available on their Apps accounts as well. But Google Apps is a different service. It’s geared at businesses but used by a wide variety of people with wildly different expectations. The team needs to manage expectations better.

The Google Apps team is trying. In March 2011, they revealed their release schedule. Moreover, customers can now choose whether to get features immediately or on a scheduled cycle, and they can find out what’s next. Frankly, flipping through the schedules makes me appreciate how many services Google Apps covers now. Think about all those services they added a year ago. I bet it was a monumental task.

And yet, when I started my search for auto-invites for chat, I expected Contacts to be a full-featured app in the feature set, rather than a third-party tool. I resisted using the third-party tools, and it took me a bit to accept that the Google Apps team really wanted me to head in that direction, especially since they didn’t indicate it very clearly. My expectations were wrong.

Think about what expectations your customers have. Give them a forum to vent. You’ll quickly find out what they expect. Then do your best to manage those expectations.