Working with Email

 

Configure the email system. 1

What is an email resource? 1

Creating an email resource. 1

Resource Fields 3

Resource fields toolbar 3

Email resource toolbar 4

Using the email resource. 4

Adding the resource to the form. 4

Mapping email resource fields to form fields 4

Sending the email 4

How line feeds are handled with HTML messages 5

 

See also: How Resources Work

 

 

Configure an email account

Before you can send email messages from the Ebase system, you must first create an email account which represents a connection to a specific email server.

                       

What is an email resource?

Each email resource represents a single email message to be sent. You can substitute values from the form at runtime into any of the email parameters: text, sender, reply to, recipients etc.

 

Each email resource contains two sections:

 

·         Email message section where you configure the text, subject, recipients etc of the email message

·         Resource Fields section which contains a list of substitutable fields. One field is required for each substitutable variable within the email message section. A build fields icon  is supplied to create these resource fields for you once you have completed the email message section. These fields are then mapped to the form fields to enable the system to perform the dynamic runtime substitution of values. Table data can be included within an email message by specifying a single substitutable variable and then populating this variable using a script or by invoking a Velocity template. This technique can also be used for messages that have a lot of HTML formatting.

 

Creating an email resource

Right click in the designer tree and select New > Email Resource.

 

 

 

Resource Description allows you to provide a description for this resource.

 

Email Account specifies the email account used to send this message.

 

Success of this Email is critical allows you to specify what happens if the email cannot be sent successfully. If checked, the requesting form will terminate with an appropriate message. If unchecked, behaviour depends on the programming language:

 

·         FPL: the requesting form will resume operation and the system variable $COMMAND_STATUS will contain 'ERROR'

·         Javascript: the sendmail() method returns false

 

When using Javascript, it’s advisable to always check this option, then catch and handle any errors e.g.

 

try {

  resources.myEmail.sendmail();

}

catch (e) {

  // handle error

}

 

HTML Message allows emails to contain HTML mark-up, e.g. <b>mytext</b> would make mytext bold. Click here for additional information on how line feeds are handled with HTML messages.

 

From is required and should be a valid user on the email server.

 

Reply to is optional; when specified this address will be used as the reply address instead of the From address.

 

The remaining fields To, Copies to:, Blind copies to:, Subject, Message are the standard email fields. Note that when sending or copying an email to more than one address, addresses specified in the email resource must be separated using semicolons. e.g. fred@xyz.com;joe@xyz.com. If you would like to substitute more than one form field variable into one of these email fields, then enter the form field names in the email resource separated by spaces e.g. Copies to might appear as: &&CC_USER1 &&CC_USER2 &&CC_USER3. Additionally, a single form field can contain a list of addresses to be substituted, in which case each address should be separated by either a semicolon, a comma or a space e.g. &CC_USERS might contain "fred.jones@abc.com, john.smith@xyz.com".

 

The example above shows the correlation between the substitutable variable and the field name. The To: field contains &&EMAIL_ADDRESS and a field is defined with the name EMAIL_ADDRESS. At runtime, this value will be substituted with the value of the form field which is mapped to this resource field. In this example, one of the form fields is the email address of the end-user and the form will be sent to this id.

 

Resource Fields

The fields Type, Length, Dec. digits cannot be changed and are present only for compatibility with other resource types.

 

If the Required checkbox is ticked, the sendmail script statement will fail unless a value exists for the mapped field.

 

Resource fields toolbar

 

* Add a resource field

* Delete selected resource fields

 Build fields: this is a labour saving device to that will create the resource fields for any substitutable variables found in any of the email message fields

 

 

Email resource toolbar

 

 

*  Save: saves the email resource.

*  Verify email resource: checks that the resource fields have been defined correctly i.e. a resource field exists for each substitutable variable (prefixed by &&).

*  Maintain Documentation

*  Show information: dates for creation, last update and import of this Email Resource.

*  Shows this help page.

 

 

Using the email resource

Adding the resource to the form

Add the Email Resource to the Resources View in the form.

Mapping email resource fields to form fields

To create mappings automatically between form fields and a resource fields, import the resource fields into the form using the Import fields from external resource icon on the Fields View toolbar of the form editor. This will create new form fields of the appropriate type and length and will also create the mapping.

 

To create mappings manually, select the resource in the Resources View then click on the mappings icon on the Resource View toolbar.

 

Table data can be included within an email message by specifying a single substitutable variable and then populating this variable using a script command or by invoking a Velocity template.

 

Sending the email

The email will actually be sent (and substitution of variables occurs) when the script command sendmail or API method EmailResource.sendmail() is executed.

 

FPL:

API based language (Javascript):

Syntax:

 

sendmail email_resource_name [ with attachments expression1, expression2, ...];

 

e.g. sendmail HB_END;

 

Any script issuing a sendmail command may test the result by interrogating the value of system variable $COMMAND_STATUS, which will contain either 'OK' or 'ERROR'.

 

Use one of the following methods on EmailResource:

 

// send a message

boolean sendmail();

// send a message with file attachments

boolean sendmail(String[] attachmentFilePaths);

// send a message with file attachments and inline text attachments

boolean sendmail(String[] attachmentFilePaths, String[] attachmentTexts);

 

All methods return true if the message has been sent successfully, and return false if there was a failure but the Email Resource is not marked as critical. If the Email Resource is marked as critical, any failure will throw a FormRuntimeException which can be caught.

 

e.g.

 

try {

  resources.HB_END.sendmail();

}

catch (e) {

  // handle error

}

 

See javadoc for further examples.

 

 

 

How line feeds are handled with HTML messages

When email messages contain mapped form fields, it is possible that the variable form field data to be substituted into the message may contain line feeds e.g. it may have been entered into a textarea by the user and might represent an address. When this occurs, and the HTML option is checked, the system converts carriage return/line feed sequences to HTML new line sequences <BR>.

 

While this will normally produce the required result, there may be occasions when this conversion is not required e.g. the email message may have been read from a file that contains carriage return/line feed sequences that are not intended to be visible to the end user, such as between adjacent lines containing HTML tags. In this scenario, the resulting email message will contain more new line sequences, <BR>, than is intended. However, the Ebase system has no means of distinguishing between form fields that require this conversion and those that do not.

 

In the scenario described above, when unwanted <BR> sequences are generated, it is recommended that the carriage return/line feeds are removed prior to invoking sendmail by using the replacelinefeeds() function as shown in the example below.

 

set MESSAGE_1 = formattemplate('formattedemail.vm'));             //build email format

set MESSAGE_1 = replacelinefeeds(MESSAGE_1);                      //remove carriage returns & line feeds

sendmail EMAIL_MESSAGE;                                           //send the email