funambol email connector quick start guide

8/6/2019 Funambol Email Connector Quick Start Guide

1/16

Funambol Email Connector

Quick Start Guide

Version 3.0

September 2006


2/16

Important Information

Copyright Funambol, Inc. 2006. All rights reserved.

The information contained in this publication is subject to US and international copyright laws and treaties. Except as permittedby law, no part of this document may be reproduced or transmitted by any process or means without the prior written consentof Funambol, Inc.

Funambol, Inc. has taken care in preparation of this publication, but makes no expressed or implied warranty of any kind.Funambol, Inc. does not guarantee that any information contained herein is and will remain accurate or that use of theinformation will ensure correct and faultless operation of the relevant software, service or equipment.

Funambol, Inc., its agents and employees shall not be held liable for any loss or damage whatsoever resulting from reliance onthe information contained herein.

Funambol and Sync4j are trademarks and registered trademarks of Funambol, Inc.

All other products mentioned herein may be trademarks of their respective companies.

Published by Funambol, Inc., 643 Bair Island Road, Suite 305, Redwood City, CA 94063


3/16

iii

EMAIL CONNECTOR QUICK START GUIDE

Contents

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Bundled Package or Individual Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Obtaining the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Configuring the Officer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Configuring the Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Creating a SyncSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Enabling Encryption/Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Modifying Log Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Making Log Settings Persistent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12


4/16

iv



5/16

1


Introduction

The Funambol email connector is a server extension that defines the way email messages aremade accessible to the Funambol DS Server for synchronization with SyncML clients. TheFunambol email connector provides both a POP-based SyncSource and an IMAP-based

SyncSource; these allow you to synchronize the Inbox folder and send email from the client(Outbox synchronization).

Bundled Package or Individual Download

The Funambol email connector software is included in the Funambol DS Server bundledpackage. This package is available for the convenience of those who want to quicklyimplement an operational synchronization server. For details on the server bundle, see theFunambol DS Server Administration Guide.

The email connector software is also available in the Funambol email connector archive file.This archive file is intended for those who do not use the bundled package (i.e., those who

have implemented the Funambol DS Server with their choice of application server, database,and so on). This document describes how to install and configure the email connectorsoftware in this environment.

Prerequisites

The requirements for using the Funambol email connector are as follows:

You have installed the Funambol DS Server, an application server, JDK/JRE, and a JDBC-compliant database on your system, or will obtain and install those components. Fordetails, see the Funambol DS Server Administration Guide.

JavaMail API the classes that comprise the JavaMail API are in the file mail.jar. Thisfile is provided in the email connector archive file. For details, see Installing theSoftware on page 2.

JavaBeans Activation Framework the classes that comprise the JavaBeans ActivationFramework are in the file activation.jar. This file is provided in the email connectorarchive file. For details, see Installing the Software on page 2.


6/16

2


Instal lation

This section provides details for obtaining and installing the software.

Obtaining the Software

The Funambol email connector software is available as follows:

Download Site: www.funambol.com/opensource/downloads.html

File: funambol-email-3.0.x.zip

Size: 4.5 MB

This archive file contains the email connector module and the inbox listener software.

Installing the Software

1. Unzip the funambol-email-3.0.x.zip archive file to a temporary directory. Extractingthe file creates the following directory structure:

The email connector files and inbox listener files are stored in separate directories. Fordetails on implementing the inbox listener, see the Funambol Inbox Listener Quick StartGuide.

The email connector module file is named funambol-email-3.0.x.s4j and is located inthe \Funambol\connectors\emaildirectory.


7/16

3


2. Copy the funambol-email-3.0.x.s4j file to the \modulesdirectory.

3. Using a text editor, open the \install.properties file.

4. Find the line that begins modules-to-install= in the Module definitions section. Thisline specifies, in a comma-separated list, the modules to install during installation.

5. Add funambol-email-3.0.x to the list (without the .s4j filename extension).

6. Save and close install.properties.

7. Install the module. Open a command prompt window and run the installation script bytyping the following at the prompt:

Windows

> cd

> bin\install-modules

Unix / Linux

> cd

> sh bin/install-modules.sh

During the installation you are prompted to create (i.e., rebuild) the database for theserver. Type n (no) if you have data in the database that you do not want to lose, such asyour existing users, mappings and previous synchronization information.


8/16

4


In addition, as the installation procedure installs each module, you are prompted torebuild that modules database. Accept or decline as appropriate, but for the emailconnector module that is being installed for the first time, you must type y (yes). Thisinitializes the database, creates the connector-specific tables, and registers the connectorwith the server. The EmailOfficer.xml file is also copied to the \config\com\funambol\server\securitydirectory.

8. The email connector requires that the JavaMail API JAR file (mail.jar) and the JavaBeansActivation Framework JAR file (activation.jar) are accessible by your applicationserver. If you are using JBoss or Tomcat, no action is required. If you are using a differentapplication server, you may need to copy these files to the library folder of yourapplication server. The files are available in the Funambol email archive file in thefunambol-email-3.0.x\Funambol\inbox-listener\libdirectory.


9/16

5


Configuration

This section provides details for configuring the software.

Configuring the Officer

The Officer is a Server JavaBean that is responsible for authenticating users and authorizingaccess to DS server resources. To set the Officer for the email connector, perform the following:

1. Start the DS Server and open the Administration Tool.

2. In the navigation pane on the left, expand the server and double-click Server settings. Theserver parameters display on the right as shown below:

3. In the Officer field, specify com/funambol/server/security/EmailOfficer.xml.

4. Click Save to save the configuration settings. For additional details on server settings, seethe Funambol DS Server Administration Guide.


10/16

6


Configuring the Connector

To configure the email connector, perform the following:

1. Start the DS Server and open the Administration Tool (if not already open).

2. In the navigation pane on the left, expand the server tree as follows: [server] > Modules >email > FunambolEmailConnector. The email connector parameters display on the rightas shown below:

Email Connector Configuration Parameters

3. Specify the parameter values and click Save to save the configuration settings.

Property Description

Mail Server Outgoing mail server URL.

Protocol Email protocol used by the Officer. Valid values: pop3,imap.

Port Email server port used by the Officer.

SSL Specifies whether the SSL protocol is used.

Keystore Path Path to the Java keystore for SSL (enabled when SSL ischecked).

Keystore Passphrase Password phrase for the Java keystore (enabled when SSLis checked).

Funambol DataSource Data source used by the caching system.

Filter Activation Specifies whether to activate filters.


11/16

7


Creating a SyncSource

To create an IMAP or POP3 SyncSource for the email connector, perform the following:


2. In the navigation pane on the left, expand the server tree as follows: [server] > Modules >email > FunambolEmailConnector and select Email Imap SyncSource or Email Pop3SyncSource. The parameters are identical for an IMAP or POP3 SyncSource; Email ImapSyncSource is shown selected below. Note that certain parameters are unavailable or read-only for each, and these differ depending on the protocol selected.

Email Connector SyncSource Configuration Parameters


Source URI The case-sensitive identifier of the SyncSource (e.g., mail).

Name The descriptive name of the SyncSource.

Outgoing Server Outgoing email server URL.

Port: default = 25 (SMTP).

Auth: if checked, the user credential is sent to the email

server to authenticate the outgoing mail.

Incoming Server Incoming email server URL.

Port: default = 110 (POP3), 143 (IMAP).

SSL Specifies whether the SSL protocol is used.

Keystore Path Path to the Java keystore for SSL (enabled when SSL ischecked).


12/16

8


3. Specify the parameter values and click Add to create the SyncSource.

Keystore Passphrase Password phrase for the Java keystore (enabled when SSLis checked)

Complete MailboxActivation

Specifies whether to synchronize the entire mailbox, oronly the main default folders Inbox, Outbox, Sent, Drafts,

and Trash (currently unavailable).

Inbox Folder Name Server label for the inbox folder. Supported for IMAP andPOP3. Check box on the right to synchronize (required).

Outbox Folder Name Server label for the outbox folder. Supported for IMAPonly. Check box on the right to synchronize (required).

Sent Folder Name Server label for the sent folder. Supported for IMAP only.Check the box on the right to synchronize (required).

Drafts Folder Name Server label for the drafts folder. Supported for IMAP only.Check the box on the right to synchronize (optional).

Trash Folder Name Server label for the trash folder. Supported for IMAP only.

Check the box on the right to synchronize (optional).Type Email object type information (read-only).

Supported Types Email object supported types information (read-only).

Supported Versions Email object supported versions information (read-only).

Encryption/Encoding Specifies whether to encrypt/encode email. If you selectthis box and save the settings, an entry for this SyncSourceis automatically added to the Data transformations table(see Enabling Encryption/Encoding on page 9) withdes;b64 transformation. If you uncheck the box and savethe settings, the SyncSource is removed from the Datatransformations table.

You can also set up email encryption/encoding manually;for details, see Enabling Encryption/Encoding onpage 9.



13/16

9


Enabling Encryption/Encoding

To encrypt/encode the communication between the email connector and a SyncML client(such as the Funambol Windows Mobile Plug-in), follow the procedure described below. Notethat you can also enable email encryption/encoding when you add or modify a SyncSource;for details, see Creating a SyncSource on page 7.


2. In the navigation pane on the left, expand the server and double-click Server settings.

3. In the right pane, locate the Data transformer manager parameter and click the Configurebutton (to the right of the field). The Data Transformer Manager Configuration Parametersdisplay as shown below:

4. In the Data transformation table at the bottom of the window, click the + icon in theupper right corner. This creates a new row at the bottom of the table.

5. In the Source URI column, specify the value of the Source URI (e.g., the string mail) of theSyncSource instance you created in the previous section.

6. In the Transformation column, specify des;b64 for the DES cipher and Base64 encoding.

7. Click Save to save the configuration settings.


14/16

10


Modifying Log Settings

To specify the level of information, output type, and so on for the email connector, perform thefollowing:


2. In the navigation pane on the left, expand the server tree as follows: Server settings >Logging and select funambol.email. The Logger settings display on the right as shown

below:

3. Specify the desired values and click Save to save the log settings.

For additional information on log settings, see the Funambol DS Server Administration Guide.


15/16

11


Making Log Settings Persistent

The first time the email connector is installed, the log settings are automatically configuredand can be accessed via the Administration Tool. At the file level, an entry was added to thethe \config\com\funambol\server\logging\Logging.xml file. Theentry is shown below:

Entry in Logging.xml:

true

1

true

INFO

100

funambol.email

logs/funambol_ds.email.log

The Logging.xml file mentioned above is rewritten when the server (or a module) isinstalled/re-installed. To maintain the above logging for the email connector, add these linesto the Logging.xml file in the \default\config\common\beans\com\funambol\server\loggingdirectory.


16/16

12


Resources

This section lists resources you may find useful.

Related Documentation

This section lists documentation resources you may find useful.

Funambol Inbox Listener Documentation

Funambol Inbox Listener Quick Start Guide: Read this guide for instructions on installing andconfiguring the inbox listener.

Funambol DS Server Documentation

The following documents form the Funambol DS Server documentation set:

Funambol DS Server Architectural Overview: Read this document for an overview of thearchitecture.

Funambol DS Server Administration Guide: Read this guide for instructions on serverinstallation, configuration, and administration.

Funambol DS Server Developers Guide: Read this guide to understand how to developextensions to the server.

Funambol DS Server SyncSource API: Read this reference guide for information on theSyncSource interface and related classes.

Funambol DS Server Quick Start Guide: Read this guide to install and run a simpledemonstration of synchronizing PIM data using the Funambol DS Server.

Funambol DS Server Module Development Tutorial: Read this tutorial for instructions onpackaging, installing and testing modules.

funambol email connector quick start guide

Documents