Specification for Mail Merge (former 'Form Letters' in Petra 2.x)

WORK IN PROGRESS

THIS PAGE IS WORK IN PROGRESS!

Introduction

The proposed 'Mail Merge' functionality in OpenPetra should allow users to create a series of documents that are a merge between layout definition and data for the purpose of creating various 'mailings' to (usually multiple) recipients. Placeholders in the layout-defining document will be substituted with data, resulting in documents which are different for each Partner.
Such documents would typically be letters, but could really be any formatted document. The documents could end up printed, as a PDF document, or could get e-mailed to the recipients.

Background Information

What we call the upcoming ‘Mail Merge’ functionality in OpenPetra is called ‘Form Letters’ in Petra 2.x, the predecessor of OpenPetra.

Petra 2.x Implementation - 'Form Letters'

The way how the Form Letters work is powerful, flexible, supports good re-use and includes good abilities to parameterise a lot of things, but it is overly technical, cumbersome to use and not liked by most Petra 2.x users. To put it bluntly, many Petra 2.x users actually ‘fear’ the Form Letters facility because the concept behind the whole functionality is so abstract and technical! Form Letters is an area in Petra 2.x that is not easy to grasp for the average person who works on a PC in an office, and it is rather difficult to ‘master it’ even for quite advanced users in an office. (The whole concept might not look too bad when seen through software engineers' eyes, but software engineers are technicians and not average users in an office who just want ‘to get that mailing out’!)

To summarise the approach of Petra 2.x: it allows the re-use of definitions of Form Letter Bodies for various Mail Merges and allows to have them parameterised using the ‘Form Letter Design’ approach, and then further at print time with ‘Inside Address’, “Sender’s Name” and ‘Closing Text‘ and other layout options, plus it has the ability to utilise ‘Inserts’ to produce different texts or text sections for different Partners (and Inserts can be done in two ways!). That is where the flexibility of the Form Letter approach lies, but at the same time the complexity! It is suggested that one skim-reads the whole Chapter 6 of the Partner Module User Guide of Petra 2.x to get an overview of what can be done with Petra 2.x' Form Letter implementation and how it is achieved. That manual can be downloaded from here: http://www.openpetra.org/en/user-manuals

Primary Goals of the Proposed OpenPetra Implementation - ‘Mail Merge‘

With OpenPetra’s Mail Merge implementation we want to significantly reduce the complexity of what is known as Form Letters in Petra 2.x. At the same time we want to give the users more and better control over the layout, and especially take the pain out of the creation and maintenance of the layout of a mail merge document. To be able to achieve that we will need to change the approach that was taken in Petra 2.x quite drastically and quite likely remove some of the advanced functionalities which make the Petra 2.x approach that technical and complex.

The approach we want to take in OpenPetra is to be based on ‘mail merge documents’, which is the approach that is taken in standard word processing applications for PC’s (e.g. MS Word or OpenOffice Writer).

Disambiguation From Other 'Similar-sounding' Petra 2.x Features

Two of Petra 2.x's features sound as if they would be related to what will become the Mail Merge functionality of OpenPetra. However, they have a different purpose and are not to be confused with what should get implemented in OpenPetra!

Extract Mail Merge

Facility to export the relevant data in a form that one can then import into a word processor, spreadsheet, etc. in CSV format. Going that route rather than using Form Letters allows users greater flexibility in layout, etc. because they can use a word processor for the creation of the layout and the process of mail merging. That functionality is often just referred to as 'mail merge' in Petra 2.x!

Mailings

The Mailings Table contains a list of mailing events that one wishes to remember (to see the results). For example one may send out a special appeal for funds for a new building project and may wish to track the response to this particular letter. Also, a Partner Contact can be recorded for all Partners in a particular mass mailing by choosing a particular Mailing.

Implementation

The implementation will need to be done in several phases as Mail Merge represents a bigger subset of the features of OpenPetra, in fact it is seen as a Sub-Module of the Partner Module and will need to be implemented in that way.

Initial Plan for the Phases

Phase I

Investigation of Various Technologies for the Core Mail Merge Functionalities

Investigations into technologies that will be needed for supporting the biggest parts of the new implementation, namely the creation and parameterisation of the mail merge document and the production of mail-merged documents for the individual recipients out of the underlying mail merge data are to be undertaken.

The desired outcome is that one technology will be identified that

• satisfies the requirements that will be gathered from key users;
• statisfies the layout requirements (at least to a very large and acceptable degree);
• fulfills the technical requirements that will be drawn up;
  • incl. that the technology is seen 'fitting' to OpenPetra from a technical standpoint;
• a migration path for existing Petra 2.x Form Letters can be done for;
• that can be made to work in a suitable time frame.

Establishment of the Migration Path for Existing Form Letters

A challenge in changing the approach of how mail merging is done in Petra 2.x is that we will need to have a migration path to the new approach in OpenPetra.
The migration path will need to be approved by Project Management before Phase II can be started!

The desired outcome is that the details of the migration path are identified and documented and a rough technical design for the implementation will be written.

• Basically, Form Letters that are designed in an OM office with Petra 2.x will need to be accessible in some format in OpenPetra so they are not lost to that OM office with the move to OpenPetra.
  • that could mean various things, such as
    • merely having the ability to be able to look at examples of combinations of various Form Bodies and settings in Petra 2.x that are 'printed' into PDF documents at data conversion time so users in an office can see how they looked like in Petra 2.x;
    • creation of mail merge documents in OpenPetra that resemble combinations of various Form Bodies and settings in Petra 2.x;
    • etc. TODO

Assigned To: MarkP (with support of ChristianK [technology investigation] and WolfgangB [migration path])

TODO

Gathering of Requirements from Petra 2.x 'key users'

We will need to find 'key users' in OM that will help drawing up the business requirements that exist in typical OM offices today.

The desired outcome is that business requirements will be identified and documented and that advanced functionalities of Petra 2.x’s Form Letter implementation that we could afford to not take over into OpenPetra (if any) are identified.

Assigned To: WolfgangB (with support of AlwynV)

TODO

Phase II

Implementation of the OpenPetra Mail Merge Sub-Module

TODO

Creation of migration program for existing Petra 2.x Form Letters

TODO

Phase III

Testing

TODO

Approval

TODO

Requirements

Technological Requirements

TODO

Technical Requirements

TODO

Layout Requirements

TODO

Business Requirements of OM offices

TODO