The Email Settings and the Profiles APIs

Updating all signatures to make them adopt the same visually appealing style sounds like a perfect task to automate, however we’d still need to collect various pieces of information for each user, such as phone number or job title, and the Email Settings API has no knowledge of them.

The Google Apps Profiles API provides exactly what we are looking for and in the rest of this article we’ll see how to have the two APIs interact to reach our goal.

Let’s assume we want our signatures to look like the one in the screenshot below, with a bold name, italic job title and clickable link for the email address. Of course you can edit the style as you like with a bit of HTML skills:

Python is the programming language of our choice for this small script and we use the Google Data APIs Python Client Library to send requests to the Email Settings and Profiles APIs.

The first few lines of the script import the required libraries and set the values of the credentials that will be used to authorize our requests. You can find the consumer key and secret for your domain in your Control Panel, under Advanced Tools – Manage OAuth domain key. Remember to replace the dummy values in the script below with yours before running it:

import gdata.apps.emailsettings.client

import gdata.contacts.client

# replace these values with yours

CONSUMER_KEY = 'mydomain.com'

CONSUMER_SECRET = 'my_consumer_secret'

company_name = 'ACME Inc.'

admin_username = 'admin'

We’ll use 2-legged OAuth as the authorization mechanism and set the administrator’s email address as the value of the xoauth_requestor_id parameter, identifying the user we are sending the requests on behalf of.

The consumer key and secret plus the requestor id are the only parameters needed to create an OAuth token that we can pass to the Email Settings and Profiles clients:

# request a 2-legged OAuth token

requestor_id = admin_username + '@' + CONSUMER_KEY

two_legged_oauth_token = gdata.gauth.TwoLeggedOAuthHmacToken(

  CONSUMER_KEY, CONSUMER_SECRET, requestor_id)

# Email Settings API client

email_settings_client = gdata.apps.emailsettings.client.EmailSettingsClient(

  domain=CONSUMER_KEY)

email_settings_client.auth_token = two_legged_oauth_token

# User Profiles API client

profiles_client = gdata.contacts.client.ContactsClient(

  domain=CONSUMER_KEY)

profiles_client.auth_token = two_legged_oauth_token

Let’s define a class that generates the signatures for our users on the basis of a set of optional attributes (occupation, phone number, email, etc). This is the class you need to edit or extend if you want to change the style of the signatures for your domain. In the example below, the HtmlSignature() method simply concatenates some strings with hard-coded styling, but you may want to use a more elaborate templating system instead:

# helper class used to build signatures

class SignatureBuilder(object):

def HtmlSignature(self):

  signature = '%s' % self.name

  if self.occupation:

    signature += '%s' % self.occupation

  if self.company:

    signature += '%s' % self.company

  signature += 'Email: %s - Phone: %s' % (

      self.email, self.email, self.phone_number)

  return signature

def __init__(

    self, name, company='', occupation='', email='', phone_number=''):

  self.name = name

  self.company = company

  self.occupation = occupation

  self.email = email

  self.phone_number = phone_number

Let’s use profiles_client to retrieve a feed containing all profiles for the domain. Each call to GetProfilesFeed() only returns a page of users, so we need to follow the next links until we get all users:

# get all user profiles for the domain

profiles = []

feed_uri = profiles_client.GetFeedUri('profiles')

while feed_uri:

  feed = profiles_client.GetProfilesFeed(uri=feed_uri)

  profiles.extend(feed.entry)

  feed_uri = feed.FindNextLink()

At this point profiles will contain the list of users we want to process. For each of them, we instantiate a SignatureBuilder object and set its properties name, company, occupation, email and phone_number with the data for that user.

A call to the HtmlSignature() method of the SignatureBuilder instance will provide us with a properly formatted HTML-encoded signature.

# extract relevant pieces of data for each profile

for entry in profiles:

builder = SignatureBuilder(entry.name.full_name.text)

builder.company = company_name

if entry.occupation:

  builder.occupation = entry.occupation.text

for email in entry.email:

  if email.primary and email.primary == 'true':

    builder.email = email.address

for number in entry.phone_number:

  if number.primary and number.primary == 'true':

    builder.phone_number = number.text

# build the signature

signature = builder.HtmlSignature()

The Email Settings API client exposes a method called UpdateSignature to set the signature for a target user. This methods accepts two parameters, the username of the user to be affected and a string containing the signature. We just built the latter, so we only need the retrieve the unique username that identifies each user and that can be easily inferred from the entry identifier returned by the Profiles API, as described in the code and the comment below.

It is worth mentioning that you can also retrieve usernames with the Provisioning API, but for the sake of simplicity we’ll rely on this small hack:

# entry.id has the following structure:

# http://www.google.com/m8/feeds/profiles/domain/DOMAIN_NAME/full/USERNAME

# the username is the string that follows the last /

username = entry.id.text[entry.id.text.rfind('/')+1:]

It’s time to send the requests to the Email Settings API and update the signature:

# set the user's signature using the Email Settings API

email_settings_client.UpdateSignature(username=username, signature=signature)

For further details on what can be accomplished with the Google Apps APIs, please check our documentation .

Public data visualization with Google Maps and Fusion Tables

The Bay Citizen is a nonprofit, nonpartisan news organization dedicated to fact-based, independent reporting of issues in the San Francisco Bay Area. We are interested in visualizing public data that is useful to the local community. One such effort is our Bike Accident Tracker. In this post, I’ll present a simple example of how we used Google Maps and Google Fusion Tables to accomplish this.

This is what our accident map looks like:

Want to add our accident map to your site? Here is the code:

[php]<html style=’height: 100%’>
<head>
<script type=’text/javascript’ src=’http://maps.google.com/maps/api/js?sensor=false’></script>
<script type=’text/javascript’>
function initialize() {
var bc_office = new google.maps.LatLng(37.788901, -122.403806);
var map = new google.maps.Map(document.getElementById(‘accident-map’), {
center: bc_office,
zoom: 13,
mapTypeId: google.maps.MapTypeId.ROADMAP
});
var accidents_layer = new google.maps.FusionTablesLayer(433634);
accidents_layer.setMap(map);
}
</script>
</head>
<body onload=’initialize()’ style=’height: 100%; margin: 0px; padding: 0px’>
<div id="accident-map" style=’height: 100%’></div>
</body>
</html>[/php]

That’s it. To test this yourself, just save the raw file, open the file with a browser and you will have a copy of the accidents map running locally on your computer. The code mainly deals with setting up Google Maps, with one critical line that sets up Fusion Table integration:

[php]var accidents_layer = new google.maps.FusionTablesLayer(433634);[/php]

You can expand this integration by filtering the results through the use of Fusion Tables’ sql-like query syntax. As an example, to display accidents from May 2009, change the line above to look like this:

[php]var accidents_layer = new google.maps.FusionTablesLayer(433634, {
query: ‘SELECT FullAddress FROM 433634 WHERE Year=2009 AND Month=5’
});[/php]

A quick gotcha to point out here is that Google Maps v3 only supports a SELECT operation on the location value column. So the location query above works just fine, but the COUNT query needed to get the number of accidents does not work:

[php]’SELECT COUNT() FROM 433634 WHERE Year=2009 AND Month=5′[/php]

Instead, to get the number of accidents in this case, you can use the Fusion Tables API endpoint directly:

[php]https://www.google.com/fusiontables/api/query?sql=SELECT COUNT() FROM 433634 WHERE Year=2009 AND Month=5[/php]

You can see the actual response from the count query here. Because The Bay Citizen is built on the Django framework, we can leverage the Python libraries Google provides for query generation and API calls. Also, since the location query is so similar to the count query, I consolidated the filter logic so it happens on the server side using a jQuery AJAX call. As a result, when users apply a filter, they see an updated map and results bar all thanks to the following few JavaScript lines:

[php]$(‘#filter-form’).ajaxForm({
success: function(responseText, statusText) {
var data = $.parseJSON(responseText);
accidents_layer.setMap(null);
accidents_layer = new google.maps.FusionTablesLayer(433634, {
query: data.map_query});
accidents_layer.setMap(map);
$(‘#filter-results’).html(data.results);
}
});[/php]

I was really happy with this approach. The performance hit is negligible, the code is much cleaner, and the filter logic is rewritten in the programming language I currently know best (Python).

I hope this post gives you a taste of what it’s like to work with Google Maps and Fusion Tables. Also, please note that our data is public and can be referenced at Table #433634. This means you’re free to use the same data we do to develop and design your own map interface. When we update the data, your project will be updated as well.

From our end, we don’t have to worry about our servers being overloaded with data API and map generation calls that come from your project. So by all means, hack away, improve the design, and create a better version. All we ask is that if you do come up with something cool, please link back to us, let us know, and then maybe we can even work together.

Final Android 3.0 Platform and Updated SDK Tools

We are pleased to announce that the full SDK for Android 3.0 is now available to developers. The APIs are final, and you can now develop apps targeting this new platform and publish them to Android Market. The new API level is 11.

For an overview of the new user and developer features, see the Android 3.0 Platform Highlights.

Together with the new platform, we are releasing updates to our SDK Tools (r10) and ADT Plugin for Eclipse (10.0.0). Key features include:

  • UI Builder improvements in the ADT Plugin:
    • New Palette with categories and rendering previews. (details)
    • More accurate rendering of layouts to more faithfully reflect how the layout will look on devices, including rendering status and title bars to more accurately reflect screen space actually available to applications.
    • Selection-sensitive action bars to manipulate View properties.
    • Zoom improvements (fit to view, persistent scale, keyboard access) (details).
    • Improved support for layouts, as well as layouts with gesture overlays.
  • Traceview integration for easier profiling from ADT. (details)
  • Tools for using the Renderscript graphics engine: the SDK tools now compiles .rs files into Java Programming Language files and native bytecode.

To get started developing or testing applications on Android 3.0, visit the Android Developers site for information about the Android 3.0 platform, the SDK Tools, and the ADT Plugin.