# Account Manager Data Types

Data Type | Description | Ref'd by | APIs
--- | --- | --- | ---
Account | Account object stored in db8 database. Serves as proxy for real provider (i.e., Google, Facebook, etc.) account. Account credentials are kept separately in encrypted storage. |  | getAccountInfo
capability | Provider capability (i.e., contacts, email, calendar, etc.) object. Contains callbacks and metadata. | Template |
CredentialsObj | Contains provider credentials such as password and authorization token. Object can contain any fields the developer wants it to have. | Template | writeCredentials readCredentials
CustomValidatorObj | Custom validator object. | Template |
DbKindsObj | Names of db8 kinds for different sub-accounts. Synergy service owners typically use this to inform apps of what data types to expect. For example, the Google template might specify "com.palm.contact.google:1" so a Contacts app knows what to create for a new contact. | Template |
IconObj | Icon object. Contains image name and location. | Template |
Template | Template object. Each Synergy service that wants to interact with the Account Manager service stores a file containing this object in `/usr/palm/public/accounts`. (This location is for 3rd party apps.) Contains callbacks and metadata. At Account service start-up, this file is scanned and registered. |  | listAccountTemplates

## Account

Account object stored in db8 database. Serves as proxy for real provider (i.e., Google, Facebook, etc.) account. An account can store data about multiple provider capabilities (i.e., contacts, email, calendar, etc.). Each capability provider object has its own callbacks and metadata. Account credentials are kept separately in encrypted storage.

### Schema

    {
       "templateId"          : string,
       "username"            : string,
       "beingDeleted"        : boolean,
       "capabilityProviders" : capability array
    }

### Elements

Element | Required | Type | Description
--- | --- | --- | ---
templateId | Yes | string | Synergy service's template ID, i.e., `com.palm.yahoo`.
username | Yes | string | User name.
beingDeleted | Yes | boolean | Is account being deleted flag.
capabilityProviders | Yes | capability array. | A provider (Google, Facebook. etc.) can have many capabilities (contacts, calendar, email, etc.) Each has an object with data and callbacks for account creation, deletion, modification and so on.

### Example

Note that the example includes the "_kind", "_id", and "_rev" fields that db8 automatically assigns when an Account object is created.

    {
       "_kind"        : "com.palm.account:1",
       "_id"          : "2+Ph",
       "_rev"         : 3554,
       "_sync"        : true,
       "beingDeleted" : false,
       "capabilityProviders"  :[ {"_id":"22Jt",
                                  "capability":"MAIL",
                                  "id":"com.palm.eas.mail",
                                  "icon":{"loc_32x32":"/usr/palm/public/accounts/com.palm.eas/images/easmail32.png",
                                          "loc_48x48":"/usr/palm/public/accounts/com.palm.eas/images/easmail48.png"},
                                  "implementation":"palm://com.palm.eas/",
                                  "onCreate":"palm://com.palm.eas/accountCreated",
                                  "onDelete":"palm://com.palm.eas/accountDeleted",
                                  "subKind":"com.palm.email.eas:1"}
                               ],
       "templateId"   : "com.palm.something",
       "username"     : "ChuckWagon@something.com"
    }

## capability

Provider capability (i.e., contacts, email, calendar, etc.) object. Contains callbacks and metadata.

### Schema

       {
          "id"             : string,
          "loc_name"       : string,
          "icon"           : iconObj object,
          "capability"     : string,
          "alwaysOn"       : boolean,
          "implementation" : string,
          "validator"      : string,
          "config"         : any,
          "onCreate"       : string,
          "onEnabled"      : string,
          "onDelete"       : string,
          "onCredentialsChanged" : string,
          "readOnlyData"   : boolean,
          "dbkinds"        : DbKindsObj object
          ... other fields ...
       }

### Elements

Element | Required | Type | Description
--- | --- | --- | ---
id | Yes | string | Capability ID.
loc_name | No | string | Localizable string, i.e., "Google Calendar"
icon | No | IconObj | Capability's icons and locations.
capability | Yes | string | Capability name, i.e., "CALENDAR"
alwaysOn | No | boolean | Should users not be allowed to turn this capability off flag. Default is `false`.
implementation | No | string | Method that implements capability.
validator | No | string | Method that implements credential validation.
config | No | any | Opaque config object sent to validator.
onCreate | No | string | Callback invoked when Account service creates account in db8.
onEnabled | No | string | Callback invoked when Account service has enabled or disabled a capability for an account. This happens when an account is created or modified.
onDelete | No | string | Callback invoked when Account service deletes account object in db8. Callback should clean-up any data it is storing locally for account.
onCredentialsChanged | No | string | Callback invoked when Account credentials change.
readOnlyData | No | boolean | Is capability data read-only flag. Default is `false`.
dbkinds | No | DbKindsObj | d8 kind objects associated with different accounts.

### Example

       {
          "id"             : "com.palm.gdata.calendar",
          "loc_name"       : "Google Calendar",
           "icon": {
               "loc_32x32" : "images/gtalk32x32.png",
               "loc_48x48" : "images/gtalk48x48.png",
               "splitter"  : "images/gtalk_transport_splitter.png"
           },
          "capability"     : "CALENDAR",
          "implementation" : "palm://com.palm.googlesync/gdata/calendar",
          "validator"      : "palm://com.palm.googlesync/gdata/calendar/checkCredentials",
          "onCreate"       : "palm://com.palm.googlesync/gdata/calendar/onAccountCreate",
          "onEnabled"      : "palm://com.palm.googlesync/gdata/calendar/onCapabilityEnabled",
          "onDelete"       : "palm://com.palm.googlesync/gdata/calendar/onAccountDelete",
          "onCredentialsChanged" : "palm://com.palm.googlesync/gdata/calendar/credsChanged",
          "readOnlyData"   : true
       }

## CredentialsObj

A credentials object can be anything you want. The fields below are included just as a guide.

### Schema

    {
       "password"   : string,
       "authToken"  : string,
       ...other fields...
    }

### Elements

Element | Required | Type | Description
--- | --- | --- | ---
password | No | string | Password
authToken | No | string | Authorization token from provider.

### Example

    {
        "password": "hhh6666uy",
        "authToken": "*37580&^"
    }

## CustomValidatorObj

### Schema

    {
       "customUI" : {
                      "appId" : string,
                      "name"  : string
                    },
       "address" : string
    }

### Elements

Element | Required | Type | Description
--- | --- | --- | ---
customUI | Yes | inline object, see two elements below | Contains app name and method.
customUI.appId | Yes | string | App ID, i.e., "com.palm.app.mail".
customUI.name | Yes | string | Validate method name, i.e., "validate".
address | Yes | string | URI to call when user changes credentials, i.e., "palm://com.palm.imap/validate"

### Example

    {
       "customUI" : {
                        "appId": "com.palm.app.mail",
                        "name": "validate"
                    },
       "address" :  "palm://com.palm.imap/validate"
    }

## DbKindsObj

Kind objects in db8 define the indexes and access control for stored JSON data objects. You must specify the kind when accessing data objects of that kind.

Synergy service owners typically use this to give their apps some hint as to what data types they expect. For example, the Google template might specify "com.palm.contact.google:1" so a Contacts app knows what to create for a new contact.

### Schema

    {
       "contact"       : string,
       "email"         : string,
       "task"          : string,
       "immesssage"    : string,
       "imcommand"     : string,
       "calendar"      : string,
       "calendarevent" : string,
       ...other kinds...
    }

### Elements

Element | Required | Type | Description
--- | --- | --- | ---
contact | No | string | Contact kind name.
email | No | string | Email kind name.
task | No | string | Task kind name.
immessage | No | string | IM message kind name.
imcommand | No | string | IM command kind name.
calendar | No | string | Calendar kind name.
calendarevent | No | string | Calendar event kind name.

### Example

    {
        "contact"      : "com.palm.contact.google:1",
        "email"        : "com.palm.imap.email:1",
        "task"         : "com.palm.task.eas:1",
        "immessage"    : "com.palm.immessage.libpurple:1",
        "imcommand"    : "com.palm.imcommand.libpurple:1",
        "calendar"     : "com.palm.calendar.google:1",
        "calendarevent": "com.palm.calendarevent.google:1"
    }

## iconObj

### Schema

       {
          "loc_32x32",
          "loc_48x48",
           ... (and so on if desired by HI in the future)
       }

### Elements

Element | Required | Type | Description
--- | --- | --- | ---
loc_32x32 | Yes | string | Relative localizable path to 32x32 icon.
loc_48x48 | Yes | string | Relative localizable path to 48x48 icon.

### Example

    {
       "loc_32x32"  : "images/gtalk32x32.png",
       "loc_48x48"  : "images/gtalk48x48.png",
       "splitter"   : "images/gtalk_transport_splitter.png"
    }

## Template

Template object. Each Synergy service that wants to interact with the Account Manager service must have an installed template file containing callbacks and metadata. At Account service start-up, this file is scanned and registered.

Third-party apps creating services that interact with the Account Manager are required to be packaged with an `account-template.json` file containing this object along with accompanying metadata such as account icons and localized text.

### Schema

    {
       "templateId"            : string,
       "loc_name"              : string,
       "loc_usernameLabel"     : string,
       "loc_passwordLabel": localizable password field label string (optional, default="Password" e.g. "PIN"),
       "icon"                  : IconObj,
       "hidden"                : boolean,
       "config"                : any,
       "validator"             : string | CustomValidatorObj object,
       "readPermissions"       : array of string,
       "writePermissions"      : array of string,
       "onCapabilitiesChanged" : string,
       "onCredentialsChanged"  : string,
       "disableRemove"         : boolean,
       "capabilityProviders"   : capability array
        ... other user-defined fields ...
    }

### Elements

Element | Required | Type | Description
--- | --- | --- | ---
templateId | Yes | string | Template ID.
loc_name | Yes | string | Localizable name, i.e., "Google".
loc_usernameLabel | No | string | Localizable username field label. For example: "Email Address". Default is "Username".
loc_passwordLabel | No | string | Localizable password field label string. Default is "Password".
icon | Yes | IconObj | Location of app's icons.
hidden | No | boolean | Default is false.
config | No | any | Opaque configuration objects sent to validator. Typically, this is populated with server configuration data.
validator | No | string | Callback or CustomValidatorObj
readPermissions | No | string array | Array of IDs of apps who can read credentials. Not currently implemented.
writePermissions | No | string array | Array of IDs of apps who can write credentials. Not currently implemented.
onCapabilitiesChanged | No | string | Method to call when account capabilities change.
onCredentialsChanged | No | string | Method to call when account credentials change.
disableRemove | No | boolean | Should users be allowed to remove this account flag. Default = `true`.
capabilityProviders | Yes | capability array | Account capabilities

### Example

    [ {
       "templateId": "com.palm.google",
       "loc_name": "Google",
       "icon": {
                 "loc_32x32": "images/google-32x32.png",
                 "loc_48x48": "images/google-48x48.png"
         },
       "validator": "palm://com.palm.service.contacts.google/checkCredentials",
       "capabilityProviders": [
       {
           "capability" : "CONTACTS",
           "id"       : "com.palm.google.contacts",
           "loc_name": "Google Contacts",
           "implementation": "palm://com.palm.service.contacts.google/",
           "onCreate": "palm://com.palm.service.contacts.google/onCreate",
           "onEnabled": "palm://com.palm.service.contacts.google/onEnabled",
           "onDelete": "palm://com.palm.service.contacts.google/onDelete"
       },
       {
           "capability": "MESSAGING",
           "capabilitySubtype": "IM",
           "id": "com.palm.google.talk",
           "loc_name": "Google Talk",
           "icon": {
               "loc_32x32": "images/gtalk32x32.png",
               "loc_48x48": "images/gtalk48x48.png",
               "splitter": "images/gtalk_transport_splitter.png"
           },
           "implementation": "palm://com.palm.imlibpurple/",
           "onEnabled": "palm://com.palm.imlibpurple/onEnabled",
           "serviceName":"service_gtalk",
           "dbkinds": {
                "immessage":"com.palm.immessage.libpurple",
                "imcommand":"com.palm.imcommand.libpurple"
           }
        }
     ]
    }