GNU Info

(eudc)Creating BBDB Records

---

Next: Server/Protocol Locals Prev: Multi-server Queries Up: Usage

---

Enter node , (file) or (file)node

Creating BBDB Records
=====================

   With EUDC, you can automatically create BBDB records (*note BBDB:
(bbdb)Top.) from records you get from a directory server.  You do this
by moving point to the appropriate record in a query result display
buffer and invoking the command `M-x
eudc-insert-record-at-point-into-bbdb' with the keyboard binding
`b'(1), or with the menu.  EUDC cannot update an existing BBDB record
and will signal an error if you try to insert a record matching an
existing one.

   It is also possible to export to BBDB the whole batch of records
contained in the directory query result with the command `M-x
eudc-batch-export-records-to-bbdb'.

   Because directory systems may not enforce a strict record format,
local server installations may use different attribute names and have
different ways to organize the information.  Furthermore BBDB has its
own record structure.  For these reasons converting a record from its
external directory format to the BBDB format is a highly customizable
process.

 - Variable: eudc-bbdb-conversion-alist
     The value of this variable should be a symbol naming an alist
     defining a mapping between BBDB field names onto directory
     attribute names records.  This is a protocol-local variable and is
     initialized upon protocol switch (Note: Server/Protocol Locals).
     The alist is made of cells of the form `(BBDB-FIELD .
     SPEC-OR-LIST)'.  BBDB-FIELD is the name of a field that must be
     defined in your BBDB environment (standard field names are `name',
     `company', `net', `phone', `address' and `notes').  SPEC-OR-LIST
     is either a single mapping specification or a list of mapping
     specifications.  Lists of mapping specifications are valid for the
     `phone' and `address' BBDB fields only. SPECs are actually
     s-expressions which are evaluated as follows:

    a string
          evaluates to itself

    a symbol
          evaluates to the symbol value.  Symbols corresponding to
          directory attribute names present in the record evaluate to
          the value of the field in the record

    a form
          is evaluated as a function.  The argument list may contain
          attribute names which evaluate to the corresponding values in
          the record.  The form evaluation should return something
          appropriate for the particular BBDB-FIELD (see
          `bbdb-create-internal').  `eudc-bbdbify-phone' and
          `eudc-bbdbify-address' are provided as convenience functions
          to parse phones and addresses.

   The default value of the PH-specific value of that variable is
`eudc-ph-bbdb-conversion-alist':

     ((name . name)
      (net . email)
      (address . (eudc-bbdbify-address address "Address"))
      (phone . ((eudc-bbdbify-phone phone "Phone")
                (eudc-bbdbify-phone office_phone "Office Phone"))))

   This means that:

   * the `name' field of the BBDB record gets its value from the `name'
     attribute of the directory record

   * the `net' field of the BBDB record gets its value from the `email'
     attribute of the directory record

   * the `address' field of the BBDB record is obtained by parsing the
     `address' attribute of the directory record with the function
     `eudc-bbdbify-address'

   * two `phone' fields are created (when possible) in the BBDB record.
     The first one has `Phone' for location and its value is obtained by
     parsing the `phone' attribute of the PH/QI record with the function
     `eudc-bbdbify-phone'.  The second one has `Office Phone' for
     location its value is obtained by parsing the `office_phone'
     attribute of the PH/QI record with the function
     `eudc-bbdbify-phone'.

 - Function: eudc-bbdbify-phone phone location
     This is a convenience function provided for use in
     `eudc-bbdb-conversion-alist'.  It parses PHONE into a vector
     compatible with `bbdb-create-internal'.  PHONE is either a string
     supposedly containing a phone number or a list of such strings
     which are concatenated. LOCATION is used as the phone location for
     BBDB.

 - Function: eudc-bbdbify-address addr location
     This is a convenience function provided for use in
     `eudc-bbdb-conversion-alist'.  It parses ADDR into a vector
     compatible with `bbdb-create-internal'.  ADDR should be an address
     string of no more than four lines or a list of lines.  The last
     line is searched for the zip code, city and state name.  LOCATION
     is used as the phone location for BBDB.

   Note that only a subset of the attributes you selected with
`eudc-default-return-attributes' and that are actually displayed may
actually be inserted as part of the newly created BBDB record.

   ---------- Footnotes ----------

   (1) This key binding does not actually call
`eudc-insert-record-at-point-into-bbdb' but uses `eudc-try-bbdb-insert'
instead.