Agent Address Book

Overview

This specification defines the XML format of Agent's address book. Agent's address book is stored as contact.xml in Agent's data directory. Developers interested in integrating with Agent's import utility should read the Import Procedures section at the bottom.

Go here for the Revision History.

Conventions

  • WIP - Work In Process. This section of document is being edited so it is subject to change.
  • TBD - To Be Determined. A decision must still be made.
  • Proposed - Refers to items that have yet to be agreed upon, but are in the specification as proposals.

Spec To-Do List

  • Document the metadata section on contact.xml.

Example

<?xml version="1.0" encoding="utf-8"?>
<contact source="import">
   <fn>Chris Beck</fn>
   <folder>Family</folder>
   <folder default="true">Work</folder>
   <adr context="Work">
      <value>P.O. Box 1212, Carlsbad, CA 92011</value>
   </adr>
   <bday>5.11.64</bday>
   <email context="Work">chris@work.com</email>
   <email context="Home" format="blank">chris@work.com</email>
   <email context="Home" format="custom" comment="Boom Boom">chris@hockey.com</email>
   <nickname context="Home">crypto</nickname>
   <org context="Work">Forte Internet Software</org>
   <tel type="Work">858.555.1211</tel>
   <tel context="Work" type="fax">858.555.1212</tel>
   <tel context="Work" type="pager">858.555.1213</tel>
   <tel context="Home" type="mobile">858.999.3000</tel>
   <user-defined context="my-context">my-value</user-defined>
   <notes>Directions to office:
L on Main
R on South
2nd Driveway</notes>
</contact>

Contact Property Tags

General Properties of Tags

All the tag names are lowercase. All XML node data is stored as content, except in the case of <adr>. That value for that tag is stored in a <value> subnode. Multi-valued types are stored as comma-separated values for now.

<contact> · a container of properties for a single contact.

<contact id="cc7c2cae-713f-438a-a822-5cf33d00b8c0" type="domain" source="routing">

id · a guid for the contact that is generated internally by Agent. Export programs should not assign this property.

mempersonauid · an internal id for the persona used when communicating with this contact. Export programs should not assign this property.

source · where the contact originated from. Export programs should not assign this property.

"import" · the contact was imported from another program. This value is set automatically by Agent's importer.

"reply" · the contact was created as a side-effect of replying to an email. This is referred to as contact memorization and can be controlled using Agent's Tools | Options command.

"routing" · the contact was created as a side-effect of routing an inbound email. This is referred to as Route by Identity (RBI). Agent detects the sender as a new contact and lets you train that contact to route and file to a specific folder.

[blank] · contact was created manually.

type · a contact node can be one of the following types:

"domain" · the contact is a domain. Domains are used for junk detection, inbound routing, and outbound filing. Domains are typically not supported by other email programs.

"inboundmailinglist" · represents an inbound mailing list such as a listserv. Inbound mailing lists are used for junk detection, inbound routing, and outbound filing. Agent provides special handling of email headers when routing and replying to inbound mailing lists.

"outboundmailinglist" · represents an outbound distribution lists when a single email message can be sent to multiple contacts. Agent can protect the identities of the recipients with the fieldtext tag.

[blank] · when this attribute is omitted, the contact represents a person or organization. This is the most common case.

<fn> · the full name of the contact, domain, or list. There should be only one fn tag per contact. Eventually Agent will distinguish between the sub-parts of a full name (e.g., prefix, first, middle, last, suffix). These will appear as separate sibling tags.

<fn>Chris Beck</fn>

<folder> · the folder assigned to the contact for routing and filing. A contact can have one or more folder assignments. Multiple folder assignment give Route by Identity the flexibility to make routing different routing decisions for contacts based on the other identities (e.g., CC) on the message.

<folder>Family</folder>
<folder default="true">Work</folder>

default · when present and set to "true", this folder is the default or tie-breaking folder for routing and filing. Only one folder can have this attribute.

<notes> · a free-form text-only notepad. This property can contain embedded newlines for formatting. It cannoted contain embedded objects or formatting commands found in other notepad programs.

<notes>Directions to office:
L on Main
R on South
2nd Driveway</notes>

<adr> · a physical address such as a street or postal box. This property can contain embedded newlines for formatting. The value for this property is stored in a special <value> sub-node. Eventually Agent will distinguish between the sub-parts of an address (e.g., city, location, country, postal code). These will appear as separate sibling tags of <value>. Unlike full name (which can only have one instance), a contact can have more than one address. Hence, the <value> tag.

<adr context="Work">
   <value>P.O. Box 1212, Carlsbad, CA 92011</value>
</adr>
<adr context="Work">
   <value>P.O. Box 1212,
Carlsbad, CA 92011</value>
</adr>

context · a user-defined label for describing the context in which this property is used. By default, Agent is configured for two contexts: "Home" and "Work". However, the user can create as many contexts as they like. Agent will keep a memorized list of the contexts in contact.xml for consistent data entry. When importing data from another program the context attribute makes it easy to map address books that have a fixed notion of home and work contexts. Context is optional and can be applied to any of the reamining tags.

<bday> · a birthday. There is no implied structure on the formatting of this date.

<bday>5.11.64</bday>

<email> · an email address

<email context="Work">chris@work.com</email>
<email context="Home" format="blank">chris@work.com</email>
<email context="Home" format="custom" comment="Boom Boom">chris@hockey.com</email>

format · the way format that this email address will be formatted when composing a message:

"blank" · there is no name in the comment portion of the email address (e.g., <chris@work.com>).

"custom" · the user spedified a custom name in the comment portion of the email address (e.g., Boom Boom <chris@work.com>).

"name" · the contact's full name is used in the comment portion of the email address (e.g., Chris Beck <chris@work.com>).

comment · the custom comment when email's format="custom".

excludefrompicker · when present and set to "true", this email address will not appear in the email address picker.

<nickname> · an alias that can be used to address this contact. If a context is provided, then the alias applies only to values (e.g., email address) that have that context.

<nickname context="Home">crypto</nickname>

<org> · an organization or company name

<org context="Work">Forte Internet Software</org>

<tel> · a telephony device.

<tel type="Work">858.555.1211</tel>
<tel context="Work" type="fax">858.555.1212</tel>
<tel context="Work" type="pager">858.555.1213</tel>
<tel context="Home" type="mobile">858.999.3000</tel>

type · a contact node can be one of the following types. These types correspond to the vCard specification:

"fax" · fax machine.

"mobile" · cellular or mobile phone.

"pager" · pager.

"tty" · teletype.

[blank] · when this attribute is omitted, the telephone type is unknown or represents a land line.

[user-defined] · a user-defined property that does not have any built-in semantics. This gives the user complete control over describing the properties of a contact. This also gives export programs totall flexibility in capturing all the properties from other address books. Agent will keep a memorized list of the user-defined property tags in contact.xmlfor consistent data entry.

<user-defined context="my-context">my-value</user-defined>

Import Procedure

Agent's contact information is stored in contact.xml in Agent's data directory. This XML file can be viewed and consulted as a reference, however, developers should never write to this file.

Automated Procedure

Developers who want to seamlessly import contact data into Agent should write their data to aabimport.xml in Agent's data directory. Agent will detect the existence of that file and prompt the user to import. This gives the user control of any merge behavior for duplicate contacts.

TBD - how does the developer determine where Agent's data directory is located?

Manual Procedure

Users can manually import an xml file using Agent's command, File | Import and Export | Import Address Book.

Revision History

Rev Date Notes
1.0.1 7.29.06 Revised for schema changes with personas being at the contact level, not the email level.
1.0.0 6.8.06 Initial version.