Developing Synergy Connectors

When first introduced, webOS Synergy set a new standard for accessing and managing personal data. Synergy brings together information from multiple sources automatically, so everything is in one place. Sign in to your Facebook, Google, Microsoft Exchange, LinkedIn, and Yahoo! accounts, and information populates your phone automatically. Facebook friends' birthdays show up in your contacts. Work and personal calendars appear side by side. IM and text messages are combined into a single conversation.

In webOS 2.0, HP/Palm is opening Synergy up to third-party developers so your customers can pull more of the Web onto their phones. You will be able to develop Synergy connectors for Contacts, Calendar, and Messaging -- and, later, for other webOS data types as well. With Synergy, you can let your users:

Creating a Synergy Connector

Okay, now that we have the marketing chat out of the way, what actually is involved in creating a Synergy connector?

A Synergy connector is packaged and delivered via the App Catalog, just like an app, and has three components:

  1. A JavaScript service (Synergy service). Please note that in previous documentation this may have been referred to as a "Transport" or "Transport service".

  2. A configuration file containing callbacks and metadata (account template file).

  3. A JavaScript app -- This is currently required for packaging, but it can be a stub app with no functionality and can be hidden from the Launcher.

In terms of coding, a Synergy connector, at its core, involves creating an account with the Account Manager and storing db8 data objects.

Account Manager

The Account Manager service -- com.palm.service.accounts -- provides central account and credentials management on the device. The account objects it manages serve as proxies for real provider accounts, such as those on Facebook, Google, or Linked-in. Providers give users capabilities such as contacts, calendar, and messaging. Synergy connectors can use the Account service when interacting with external account providers.

db8

db8 is an addition to the webOS JavaScript Framework's current storage methods designed to meet the needs of robust, high-performance applications. db8 is a service -- com.palm.db -- available on the device bus that interfaces to an embedded JSON database. db8 stores kind objects and data objects. Kind objects define the owner, schema, and indexes for data objects. Once you create a kind object, you can then store data objects of that kind.

Kinds can extend other kinds. If you create a kind that extends the Contacts kind and write data objects to that kind, they will appear in the webOS Contacts app. The same is true for Calendar and Messaging.

Minimal Synergy Connector

A very minimal Synergy connector could, theoretically, be implemented in 3 steps:

  1. Create a provider account that has at least one capability (contacts, calendar or messaging) with the Account Manager service. You can do this with a createAccount call.

  2. Create a db8 kind that extends the Contacts, Calendar or Messaging kind. You can do this with db8's putKind call.

Calendar apps have to extend two kinds -- one for events and one for the calendar itself (since accounts could have more than one calendar).

  1. Write data objects to your extended kind. These objects must have an associated account ("accountId") field. You can do this with db8's "put" call.

The objects you store will then appear in either the Contacts, Calendar or Messaging app. You could do all of the above steps with a Mojo app that uses "serviceRequest" to call the Account Manager and db8 services.

Typical Synergy Connector

Though you could build your own separate UI, a typical Synergy connector completely integrates with one or more of the Contacts, Calendar and Messaging apps. These webOS apps provide menus for adding a provider account and all additional processing is done through your JavaScript Synergy service.

JavaScript Services

Currently, webOS apps have access to a rich set of application and system services available on the public bus. With webOS 2, third-party developers can now "roll their own" services. JavaScript services strengthen webOS support for background processing and add new capabilities such as low-level networking, filesystem access and binary data processing to the webOS technology stack.

The popular Node.js runtime environment is built into webOS 2, allowing you to develop both webOS apps and services in JavaScript. Developers can write services using a rich-set of JavaScript libraries. Besides the open-source Node.js, these include webOS' Node.js add-ons and Foundation libraries of utility JavaScript APIs.

Synergy Service

A Synergy service connects to an outside data source for login and syncing. The Synergy service provides an account template containing, besides metadata, callbacks the Account Manager invokes when creating, deleting or modifying one of its account objects. The Synergy service also provides a callback to implement syncing with an outside data source.

Syncing and Data Mapping

Synergy connectors can implement their own methods for authenticating and syncing with an outside data source as well as mapping data to conform with webOS' Calendar, Contacts and Messaging data objects. The webOS Contact data objects conform to the Portable Contacts 1.0 spec. The webOS Calendar event objects conform to RFC 5545. The Calendar kind does not adhere to any particular standard.

Alternatively, connectors can make use of the sync framework and data mapping utilities provided with webOS' loadable libraries -- "mojo.transport" and "mojo.transport.sync" -- to implement this.

Next Steps

A logical place to begin is to step through the Creating a Synergy Contacts Package tutorial. This will step you through the basics of creating and installing a Synergy app/service/account package, integrating with the webOS Contacts app, implementing a bare-bones Synergy service, and authenticating and syncing with an outside data source, in this case, Plaxo, an online address book and social networking site (http://www.plaxo.com).

After that, you should look at our sample Synergy connector that also syncs with Plaxo, but, this time, makes use of our loadable libraries for syncing and data mapping. We also provide a sample Calendar Synergy connector that uses the sync framework you can preview.

Additional Documentation