Acrobat User Community

Dynamically setting a submit by e-mail address

by: Thom Parker

It’s often convenient to submit form data by e-mail, and Acrobat provides a simple button action for doing this in both forms technologies--AcroForms and XFA (LiveCycle). However, to use this button action, the e-mail address has to be set at the time the form is created and it can’t be changed later. You’re out of luck, for example, if you want to CC the form data to an e-mail address on the form. Fortunately, Acrobat JavaScript can perform this same task, and it is much more flexible. In fact, JavaScript allows the e-mail submission to be configured in just about any way necessary.

E-mail possibilities

Acrobat provides four different functions for sending e-mail from a PDF (listed below). While all four functions are specifically AcroForm JavaScript functions, all of them also work in a LiveCycle form, so they can be used for scripting e-mail submission in both Acrobat forms technologies.

  • app.mailMsg() – This function sends an e-mail message with no attachments.
  • doc.mailForm() – This function sends the form data in FDF as a file attachment to the e-mail.
  • doc.mailDoc() – This function sends the entire PDF file as an e-mail attachment.
  • doc.submitForm() – This function can send form data in a variety of formats, including custom XML.

Each of these functions has inputs that allow the “To:,” “CC,” “BCC,” “Subject” and body parts of the e-mail to be set. The “app.mailMsg()” function is the only one that does not send form data as an attachment. It’s just for sending an e-mail. However, this doesn’t mean that it can’t send form data. A script can be written to place the form data into the body of the e-mail. Some legacy mainframe systems use exactly this method for transferring data.

All three of the functions--“app.mailMsg(),” “doc.mailForm()” and “doc.mailDoc()”--use similar arguments, so we’ll just look at one of these, the “doc.mailForm()” function. We’ll also look at the “doc.submitForm()” function, which is very different.

Using a value from a form field to CC the e-mail

In this example, the script will acquire a value from a form field and use that value as the CC address on an e-mail submission. To simplify the code, it will be assumed that the field value really is an e-mail address and so the script won’t include any e-mail address format validation.

The example actually acquires two e-mail addresses from the form. : The client e-mail address and an optional beneficiary e-mail address. So the submit function’s CC address is an e-mail list. Any of the e-mail address fields in a submit (cTo, cCC, or cBCC) can be a list of semicolon-separated addresses. This is the standard format used by SMTP, the standard and ubiquitous e-mail server.

Using the “doc.mailForm()” function:

Place the code below in the Mouse Up event of a form button. In order for this code to work, the form must have two text fields--one named "ClientEmail" and one named "BennyEmail.” You can use different field names on the form for the e-mail, but make sure to change the fields’ names used in the code to match the field names on the form.

// This is the form return e-mail. Its hardcoded
// so that the form is always returned to the same address
// Change address on your form
var cToAddr = "formsAdmin@BigCorp.com";
// First, get the client CC e-mail address
var cCCAddr = this.getField("ClientEmail").value;
// Now get the beneficiary e-mail only if it is filled out
var cBenAddr = this.getField("BennyEmail").value; if(cBenAddr != "") cCCAddr += "" + cBenAddr;
// Set the subject and body text for the e-mail message var cSubLine = "Form X-1 returned from client";
var cBody = "Thank you for submitting your form.\n" + "Save the mail attachment for your own records";
// Send the form data as an FDF attachment on an e-mail
this.mailForm({
	bUI: true,
	cTo: cToAddr,
	cCc: cCCAddr,
	cSubject: cSubLine,
	cMsg: cBody
});

Notice that the line of code that sends the e-mail (the last line) doesn’t have any hard-coded inputs, except for the first one. This first input, “bUI,” must always be set to true when this function is used from within a document script. All of other inputs, the e-mail inputs, are set up as variables in the code above this line. These are the values you will need to change to customize this code for your form. In this example, all values except for the “ccAddr” are set to static values, but any one of them could be built dynamically from fields on the form. For example, if the form has fields for entering the client’s first and last name, then this line of code could be used to dynamically build the subject line.

var cSubLine = "Form X-1 returned from " + this.getField("ClientFirstName").value + " " + this.getField("ClientLastName").value;

Using the “doc.submitForm()” function

The “doc.submitForm()” function is a general-purpose, data-submission tool. It can submit to server scripts or e-mail, and in a large variety of formats. If an e-mail address is used, then all the e-mail information is placed in the e-mail URL. There are no individual function inputs for the To, CC, Subject, and Body parts of the e-mail. But the “doc.submitForm()” function does have quite a menagerie of inputs for controlling how the data is submitted. In the code below, it is set up to submit the data in XML format.
Place the code below in the Mouse Up event of a form button. In order for this code to work, the form must have two text fields, one named "ClientEmail" and one named "BennyEmail.”

// This is the form return e-mail. Its hardcoded
// so that the form is always returned to the same address
// Change address on your form
var cToAddr = "formsAdmin@BigCorp.com";
// First, get the client CC e-mail address
var cCCAddr = this.getField("ClientEmail").value;
// Now get the beneficiary e-mail only if it is filled out
var cBenAddr = this.getField("BennyEmail").value;
if(cBenAddr != "") cCCAddr += ";" + cBenAddr;
// Set the subject and body text for the e-mail message
var cSubLine = "Form X-1 returned from client"; var cBody = "Thank you for submitting your form.\n" + "Save the mail attachment for your own records";
//** Send the form data as an XML attachment on an e-mail
// Build the e-mail URL
var cEmailURL = "mailto:formsAdmin@BigCorp.com?cc=" + cCCAddr + "&subject=" + cSubLine + "&body=" + cBody;
this.submitForm({
	cURL: cEmailURL,
	cSubmitAs:"XML",
	cCharSet:"utf-8"
});

The first part of this code is identical to the last example. After all, regardless of which function sends the e-mail, all the standard parts of an e-mail have to be provided. So these things will be the same in any e-mail script. The difference is in how the inputs to the e-mail function are built.

In this case, the e-mail CC address, subject line, and body are all set up as URL query parameters. The other inputs to the “doc.submitForm()” function control how the submit data is formatted. The “cSubmitAs” parameter controls the overall formatting. It has several possible values. In this code, the data is being sent in a generic XML format. The “cCharSet” parameter guarantees the character formatting of the XML is all standard 8-bit ANSI.

LiveCycle (XFA) variation

Both examples above can be used in a LiveCycle form with only two minor changes. First, LiveCycle form fields are organized differently than AcroForm form fields, and they have a different access mechanism. So, the code that builds the CC address has to be changed to use the LiveCycle method for acquiring a form field value.

The second change is acquiring the AcroForm document object. Remember that the e-mail functions are AcroForm JavaScript functions of the AcroForm document object. In an AcroForm script, the “this” keyword refers to the Document Object, so using the submitForm function is written as “this.submitForm().” But in a LiveCycle script, the “this” key refers to the object to which the script is attached. LiveCycle JavaScript does provide access to the AcroForm scripting model, and it provides access to the AcroForm Document Object through the “event.target” property. You can in fact use just about any AcroForm document function or property in a LiveCycle form by referencing it with “event.target” instead of “this,” as you would do in an AcroForm script. Here’s how the code for the first example would be modified for use in a LiveCycle form, assuming the e-mail address fields are in a subform named “ClientInfo.”

// This is the form return e-mail. Its hardcoded
// so that the form is always returned to the same address
// Change address on your form
var cToAddr = "formsAdmin@BigCorp.com";
// First, get the client CC e-mail address
var cCCAddr = ClientInfo.ClientEmail.rawValue;
// Now get the beneficiary e-mail only if it is filled out
var cBenAddr = ClientInfo.BennyEmail.rawValue; if(cBenAddr != "") cCCAddr += ";" + cBenAddr;
// Set the subject and body text for the e-mail message
var cSubLine = "Form X-1 returned from client"; var cBody = "Thank you for submitting your form.\n" + "Save the mail attachment for your own records";
// Send the form data as an FDF attachment on an e-mail
event.target.mailForm({
	bUI: true,
	cTo: cToAddr,
	cCc: cCCAddr,
	cSubject: cSubLine,
	cMsg: cBody
});

Conclusion

That’s all there is to it. Creating dynamic e-mail submissions is simply a matter of collecting the e-mail data from the form fields and then applying that information to the available e-mail functions.

The full scripts for all the examples including some extras can be found in these example files: “DynamicEmail_AcroForm.pdf” and “DynamicEmail_XFAForm.pdf.” For more information about the functions used in this article, see the Acrobat JavaScript reference. Also take a look at the JavaScript Corner article Submitting Data; it provides more detail on the “doc.submitForm()” function.

1 Acrobat JavaScript Reference
http://www.adobe.com/devnet/acrobat/javascript.html

2 XFA Object Reference
http://partners.adobe.com/public/developer/xml/topic.html