Send Document as Email

OpenOffice.org

Document - ID	Specification Owner	Last Change	Status
	Oliver Braun	06/16/04	Final
Conforms to	
Applies to	OpenOffice.org
Task ID(s)	i21321, i15640, 103347, 109597, 114072
Category	Enhancement

Abstract

With “File – Send – Document as E-mail” OpenOffice.org offers functionality to open a new email composer window with the active document directly attached. OpenOffice.org 2.0 will greatly simplify the task of configuring the email client to be used for this feature.

i-Team Members (The specification owner is part of the i-Team)

	Name	E-mail Address
User Experience	Falko Tesch (ft) Christian Jansen (cj)	ft@openoffice.org cj@openoffice.org
Development	Oliver Braun (OBR) Tino Rachui (TRA) Carsten Driesner (CD)	obr@openoffice.org tra@openoffice.org cd@openoffice.org
Quality Assurance	Jörg Skottke (JSK) Andreas Treumann (ATR)	jsk@openoffice.org atr@openoffice.org
Documentation	Uwe Fischer (UFI)	ufi@openoffice.org

Approved for Implementation

	Approved by	Date
User Experience	Christian Janssen (CJ) Falko Tesch (FT)	21.04.04 15.06.04
Development	Tino Rachui (TRA) Oliver Braun	21.04.04 15.06.04
Quality Assurance	Andreas Treumann (ATR)	21.04.04 15.06.04
Documentation	Uwe Fischer	21.04.04
String Review	Elizabeth Matthis	05.05.04 15.06.04

Document Change History

Rev. Level	Change	Initials	Date
1.0	Initial release	obr	22.03.04
1.1	String updates	obr	20.04.04
1.2	More string updates, but also approvals	obr	26.04.04
1.3	String review	em	05.05.04
1.4	Finalized & screenshot update	obr	12.05.04
1.5	Minor updates to the implementation part	obr	08.06.04
1.6	Added error handling to change the existing error message	obr	15.06.04
1.7	Changed german translation of error message, added screenshot and renewed approvals.	obr	16.06.04
1.8	Updated command line spec	obr	14.09.04

Send Document as Email

Contents

Glossary	1

1	Motivation	1

2	User Scenarios	1

3	Goals	1

4	Requirements and Dependencies	1

4.1	Requirements	1

4.2	Technical Dependencies	2

5	Competitive Analyses	2

6	Detailed Specification	2

6.1	Windows ®	2

6.1.1	Dropping support for Mozilla < 1.4 and Netscape < 7.1	2

6.1.2	Enhanced MAPI support	2

6.1.3	Non MAPI email clients	3

6.1.4	Migration	3

6.1.5	Mail Invoking code	3

6.2	Unix	3

6.2.1	Dropping support for Mozilla < 1.4 and Netscape < 7.1	3

6.2.2	Auto-detecting email clients	3

6.2.3	Migration	5

6.3	G11n	5

6.4	Error Conditions	5

7	Future Tasks	5

8	Notes	5

9	References	5

Glossary

Term	Description
PDF	Portable Document Format
MAPI	Microsoft Messaging API
URI	Uniform Resource Identifier (http://www.w3.org/Addressing/), short strings that identify resources in the web (also known as “URL”).
GUI	Graphical User Interface
CDE	Common Desktop Environment, the former standard desktop of Solaris.
GNOME	GNU Network Object Model Environment (http://www.gnome.org/about/), the new standard desktop for Solaris and JDS.
KDE	K Desktop Environment (http://www.kde.org/whatiskde/), an alternative desktop for Unix, mainly supported by Novell/SuSE.

Motivation

Both “send document as email” feature implementations of OpenOffice.org 1.x have some significant drawbacks:

the Windows only MAPI implementation has to rely on the mapi32.dll found on the system. With some versions of this dynamic library OpenOffice.org crashes or hangs when the user chooses to use this feature.

the configuration for the up to now platform independent command line based implementation is incomprehensible and requires too much knowledge from the user.

User Scenarios

When choosing File -> Send -> Document as E-mail, the users default email client starts up with or just opens a new mail composing window, which already has a copy of the currently active document attached.

When choosing File -> Send -> Document as PDF Attachment, the currently active document is converted to PDF before it gets passed to the e-mail client.

Goals

The goal of this project is to provide the functionality described above with a minimum or no configuration effort for the average user and without any stability impacts on the product.

Requirements and Dependencies

Requirements

The e-mail client must support attaching a document to an empty email skeleton either via command line or via MAPI.

Technical Dependencies

The implementation described below needs platform / desktop specific configuration entries.

Competitive Analyses

On MS Windows ® nearly all applications use MAPI (and only MAPI) to communicate to the users email client. Applications like MS Office ® don't have a separate configuration entry for choosing a different email client than configured in MAPI.

Since release 3.1, KDE has the ability to set a preferred email client in the KDE ControlCenter. In release 3.1, changing this setting to something different then KMail does only work as expected in English locales, but 3.2 is expected to overcome this internationalization problem. Unfortunately the kmailservice command line tool does not accept attachment parameters and there also seems to be no way to query the configured mail client without being an KDE application.

Starting with release 2.4 GNOME does as well have a GUI to specify an e-mail client in the “Preferred Application” preferences.

Configuring another mail client than dtmail in CDE is a quite challenging task.

Detailed Specification

Windows ®

Dropping support for Mozilla < 1.4 and Netscape < 7.1

The primary reason for having the profile based command line mailer on MS Windows ® was that Mozilla 1.0 and Netscape 6 did not have MAPI support build in. But since MAPI support was reintroduced with Mozilla 1.2 and Netscape 7.0, this reason is no longer valid. However, to be consistent with the requirements on Unix (see 6.2.1), only Mozilla 1.4 and later as well as Netscape 7.1 will be supported.

As a consequence, the profile based command line mail support will be dropped on Windows ® and the Tools – Options - %PRODUCTNAME - External Programs tab page will be removed.

Enhanced MAPI support

To overcome the stability problems with the different mapi32.dll versions, OpenOffice.org 2.0 will no longer access mapi32.dll directly, but transparently delegate all MAPI requests to a dedicated executable called senddoc.exe, which ships with OpenOffice.org 2.0.

Although there is currently no UI that would require it, the underlying UNO services do support specifying additional email fields like to or cc, so it must be possible to pass values for those over the command line.

The executable understands the following command line options:

Option	Meaning	Remarks
--from foo@mail.com	specifies the sender's address	
--to foo.bar@mail.com	specifies an addressee of the email	
--cc foo.bar@mail.com	specifies a recipient of a carbon copy of the email	
--bcc foo.bar@mail.com	specifies a recipient of a blind carbon copy of the email	
--subject “my subject”	specifies the subject of the email	
--body “my body”	specifies the body of the email	
--attach file	specifies to attach a file to the email	
--mapi-dialog	specifies that the MAPI mailer should open a composer window	Windows only
--mapi-logon-ui	specifies that the MAPI mailer should bring up a logon UI if necessary	Windows only
--mailclient executable	specifies the mail client executable to use. The executable may be located in the user's PATH variable or specified as full path name.	Unix only - must be the first parameter

Files to attach to the message are passed to the client as system paths.

Specifying more than one recipient of the same kind should be done using multiple to,cc or bcc options. Any occurrences of the character `“` in body or subject might have to be escaped. ToDo: evaluate !!

Non MAPI email clients

As specified in 6.1.2, the default executable invoked from OpenOffice.org 2.0 is senddoc.exe in the office program directory. Whoever needs to use a non MAPI compliant email client on Windows ® has to manually set the Default value of the following Windows registry key

HKEY_CURRENT_USER\Software\OpenOffice.org\SendAsEMailClient

to point to an executable or batch files that complies to the command line specification of 6.1.2. However using this hooking mechanism is not recommended for end users and thus should not be documented in the online help.

Migration

Because all the email clients for the existing profiles are either no longer supported or did never exist on Windows ®, any configuration items below the node

org.openoffice.Office.Common/ExternalMailer/

will be ignored.

Mail Invoking code

The code invoking the SimpleSystemMail service used to work with a dedicated thread for this task to overcome some of the MAPI stability problems. This code is going to be simplified again.

Unix

Dropping support for Mozilla < 1.4 and Netscape < 7.1

With Mozilla/Netscape versions prior to 1.4/7.1, opening a composer window with a file already attached does only work if Mozilla/Netscape did not already run on that display. Support for this versions will be dropped of OpenOffice.org 2.0

Auto-detecting email clients

Dropping the cross-platform support of the command line mail client allows to include some additional logic in wrapping Unix shell script: the script will accept the command line specified in 6.1.2 (with the extensions of the last parameter being the email client to start) and convert it automatically into the command line needed by the specified client. As a consequence, the value of the configuration key

org.openoffice.Office.Common/ExternalMailer/Profile

will be ignored.

The GUI in Tools – Options - %PRODUCTNAME - External Programs will be simplified (by removing the profile selection list box) and moved to the Tools – Options – Internet section:

Pressing the “...” button opens the default file selection dialog with the initial directory set to the platforms default directory for binaries (/usr/bin on Unix).

String list

Item	English	German	Comments
Tools – Options – Internet tree entry	E-mail	E-Mail	
Fixed Text (heading)	Sending documents as e-mail attachments	Versenden von Dokumenten als E-Mail-Anhang	
Fixed Text	~E-mail program	~E-Mail-Programm	

Tab Order

Item	Label	Tab Order	Initial Focus
Edit Field	~E-mail program	1	yes
Button	...	2	no
Button	OK	3	no
Button	Cancel	4	no
Button	~Help	5	no
Button	~Back	6	no

Key Board Shortcuts

none.

Migration

Since the implementation re-uses the OpenOffice.org 1.x configuration key

org.openoffice.Office.Common/ExternalMailer/Program

no specialized migration will be necessary.

G11n

none.

Error Conditions

There exist versions of the mapi32.dll (e.g. from T-Online) which cause senddoc.exe and any other MAPI compliant program to crash. In this case and also if the user has not specified a supported e-mail client on Unix, the following error message will occur:

String list

Item	English	German	Comments
Title-Bar	%PRODUCTNAME %PRODUCTVERSION	%PRODUCTNAME %PRODUCTVERSION	
Fixed Text	%PRODUCTNAME was unable to find a working e-mail configuration. Please save this document locally instead and attach it from within your e-mail client.	%PRODUCTNAME konnte keine funktionierende E-Mail Konfiguration finden. Bitte speichern sie dieses Dokument lokal und senden es dann mit ihrem E-Mail Programm.	
Button	OK	OK	

Future Tasks

As soon as KDE and GNOME provide reasonable API to pass documents as attachments to the mail client which the user configured on the desktop, the UI for configuring an email client in OpenOffice.org can be removed.

There needs to be a way to hide the E-mail tab-page on Unix desktop environments where a SimpleSystemMail service will be implemented.

Specify if files should be passed as file urls or as system path when using –atach

Enhance error handling to open a save dialog from the error message. Possibly also open a file manager window to allow dragging the document into the e-mail client.

Notes

References

Send Document as Email

Page 6

http://specs.openoffice.org/appwide/desktop_integration/send_as_email.sxw

Oliver Braun

2004-02-17T15:27:20