[ Data Export ]

External Account Processing #

Introduction #

The external account processing operations in Max2 write details of a set of accounts to a temporary file then, optionally, execute an external program to process that file. The temporary file can be in one of a family of related file formats described in Appendix D - Export Account Information File Format.

The external account processing operation to be performed is chosen by selecting the appropriate menu item from the Main Window's Report menu's External Account Processing sub-menu:

External account processing is a very configurable mechanism which, at the time of writing, is used for e-mailing statements to individual members and e-mailing messages, optionally with attachments, to groups of members.

Menu Items #

As shown above, the External Account Processing... sub-menu contains four items. These can be configured to perform any of the external account processing operations but their intended uses are given below. New operations can be added by editing the MAIN.FRM to add a new menu item with an appropriate profile name (perhaps with appropriate default settings in subroutine GetProfile in EACCPROC.BAS), as discussed under Configuration.

Menu Item Operator Level Profile Name Intended Use
Export Statement Transactions... Browser Export Statements Write out a simple file with the account transaction details for use by some other program.
EMail Statements... Manager EMail Statements Send one message to each of the selected accounts' holders containing a statement for the current month.
Bulk EMail... Full Entry or Instructor Supervisor Bulk EMail Send one message to all of the holders of the selected accounts containing optional text and optional attachments.
Send SMS Text Messages... Full Entry or Instructor Supervisor SMS Text Send an SMS message to the mobile phones of the holders of the selected accounts. At the time of writing a suitable program to perform this function has not been provided so, by default, this operation just opens the output data file in Windows Notepad.

Operation #

This section describes normal usage to perform an external account operation. See below for configuration options accessed via the Advanced Options... button.

Account Selection #

When one of the Report menu's External Account Processing options is selected an account selector is displayed to defined the accounts which are to be processed. A typical choice would be to use the Standard Selections menu's Ordinary Members To Be E-Mailed option.

Options Dialog #

Then the External Account Processing Options dialog is displayed.

File Name is the name of the temporary file which will be exported. Except in the case of a simple export with no external processing, the file name cannot be changed.

Subject is the subject to be added to e-mail messages sent. In the case of statements it is used as the prefix of the message subject; text including the account number and the month is added to the end. For non-email file formats the subject field is disabled and not used.

Message Text is the body of the message text to be included in e-mail and SMS messages. For statements the text is included, centred and in bold, at the foot of the statement with the default text being taken from the most recently printed statements. For simple account detail export there is no message text so this item is disabled.

For bulk e-mail the body of the message is taken from this text if any is given. If the message text is left blank then the first attachment is used as the message body if it is of a suitable type (text/plain or text/html) otherwise a blank message body is sent.

Attachments is only enabled for the e-mail export formats. It contains a list of extra files to be attached to the message to be sent (e.g., a PDF newsletter). For bulk e-mail the first "attachment" can be used as the body of the message (see Message Text, above). The list can be updated using the Add and Remove buttons. There is further discussion of attachments, particularly the file types, in Attachment Processing

File Export #

When OK is pressed on the options dialog box the options are saved to the .INI files and the account details file is written.

There are a few errors which can arise during this operation. A typical one is an attempt to send an e-mail message to an account for which no e-mail address is available. Some of these allow the operation to be continued but it is usually best to cancel, fix the problem (i.e, change the account selection or update the account details) and try again.

External Processing #

In the case of a simple file export, once the file has been written the operation is complete as far as Max2 is concerned. Further processing of the file needs to be carried on by other means.

The common case, however, is that an external program is to be run automatically to process the exported account information. The details of the program are set up in the Advanced Options as described under Configuration.

The only external program in regular use at the time of writing is the emailer, written in Java, and described in Appendix E - External EMail Program. See that description for more information on further operation.

The external program is run separately from Max - further Max processing can be done while it's running.

Configuration #

Storage #

The configuration information is stored in both of the .INI files associated with the database (Max2DB.ini in the database directory and Max2.ini in the Windows directory) as described in Database Organization.

The sections are only present if they're needed but the ones which can be in the files are:

Here's an example with the two commonly used profiles and both of the shared options sections:

[EMail Statements]
Format=2
ProcessorType=2
Processor=EMailMsgSender
ProcessorParams=-d

[Java Options]
VMExe=C:\Windows\Java.exe
ClassPath=C:\Max2\Bin\Max2Java.jar
Params=

[EMail Options]
SMTPServer=smtp.xxx.com
Reply=office@bookergc.nildram.co.uk
From=max2@bookergc.nildram.co.uk
UndisclosedRecipientAddress=undisclosed@bookergc.nildram.co.uk

[Bulk EMail]
Format=3
ProcessorType=2
Processor=EMailMsgSender
ProcessorParams=-d

The Format parameters indicate the format of export file to be written. The ProcessorType parameters indicate the general type of external program to be run: none, Windows executable or Java program. The Processor is the name of the Windows executable or the name of the Java class. The other parameters should be apparent from setup dialogs described below.

Setup #

The dialog boxes to setup the external account processing are accessed via the Advanced Options... button on the External Account Processing Options dialog. This is only available to Manager level operators.

The first dialog shown sets up the options for the current external account processing profile:

File Format selects the format of file to export (one of those in Specific File Syntaxes).

Processor Type selects the general form (Windows executable or Java program) to be executed, if any.

Depending on the processor type selected the remaining parameters specify the program to run and the parameters to include on the command line before the name of the exported file.

A problem which can arise is that the command line which is composed can finish up being too long. There is a limitation for Windows (at least for 16-bit apps, which Max2 is) of 128 characters per command line.

The Java Options and EMail Options buttons access configuration information which is shared by the profiles to which they apply. These buttons are only enabled when they apply to the current profile - Java Options depending on the processor type and EMail Options on the file format.

This dialog sets the information needed to run external processes written in Java.

The class path, if it's not empty, is passed to the virtual machine using the command-line -classpath parameter. If a class path is specified in the dialog box then this is prefixed with the CLASSPATH environment variable which was set when Max2 started. If no class path is specified in the configuration then no -classpath parameter is passed to the JVM - presumably it'll pick up any CLASSPATH environment variable for itself. This could be a good wheeze if the command line gets too long - leave out the -classpath parameter at the cost of having to ensure that the CLASSPATH environment variable is set before Max2 is run.

The normal case is to set the class path to reference just the fully qualified path of the installed Max2Java.jar file.

These options apply to the file formats intended for sending statement and bulk e-mail.

The Mail (SMTP) Server field should be set to the domain name of the outgoing mail server. This is usually determined by the internet service provider used for the internet connection (and may well be different from the mail server used for incoming mail).

REPLY TO: address is used to set the address that recipient's email clients will use if they choose to reply to the message. This should be set if it is different from the FROM address.

FROM: address sets the sender that the recipients will see for the message.

Undisclosed recipient address is used for bulk emails where a single message is sent to more than one club member. Many people do not like their e-mail address to be visible to arbitrary people so all of the listed recipients of the e-mail are listed as BCCs. However, technical an RFC 2822 e-mail message is supposed to have at least one TO address (though quite a lot of software ignores this). This field will be used to fill in a "dummy" TO address for these purposes. It is useful, though, to set it to a sensible address so that a copy of the message can be seen as confirmation that it was sent properly.