External Forms module

The Magnolia External Forms module allows you to render a form configured in a third-party marketing-automation tool as a Magnolia form and submit the data back to the marketing tool.

The module includes a preconfigured component that allows editors to select third-party forms and add them to pages.

Bundle

The Magnolia External Forms bundle consists of four modules:

• External forms: Provides functionality to render external forms as Magnolia forms.
• External forms Infusionsoft: Example implementation for the Infusionsoft marketing tool. 
• External forms Eloqua: Example implementation for the Oracle Eloqua marketing tool.
• External forms IBM: Example implementation for the IBM Watson Campaign Automation tool.

Installing

<dependency>
  <groupId>info.magnolia.extforms</groupId>
  <artifactId>magnolia-external-forms</artifactId>
</dependency>

For Infusionsoft add this Maven dependency. It includes the External Forms module automatically.  

<dependency>
  <groupId>info.magnolia.extforms</groupId>
  <artifactId>magnolia-external-forms-infusionsoft</artifactId>
</dependency>

For Eloqua add this Maven dependency. It includes the External Forms module automatically.  

<dependency>
  <groupId>info.magnolia.extforms</groupId>
  <artifactId>magnolia-external-forms-eloqua</artifactId>
</dependency>

For IBM add this Maven dependency. It includes the External Forms module automatically.  

<dependency>
  <groupId>info.magnolia.extforms</groupId>
  <artifactId>magnolia-external-forms-ibm</artifactId>
</dependency>

External Forms module

The External Forms module provides functionality to render external forms configured in the third-party marketing tool as Magnolia forms. If the external service is unavailable, submissions are queued in the External Forms app for resubmission.

The module is configured in /modules/external-forms .

Infusionsoft implementation

You can connect to Infusionsoft by configuration.

The External Forms Infusionsoft module provides an example configuration in /modules/external-forms-infusionsoft/external-form-service .

Eloqua implementation

The External Forms Eloqua module provides an example implementation for the Oracle Eloqua marketing tool.

Eloqua REST API

All communication between Magnolia and Eloqua is made strictly over the REST API provided by Eloqua.

The module uses the following calls:

/assets/forms @GET
/assets/form/{formId} @GET
/assets/optionList/{optionListId} @GET
/data/form/{formId} @POST

To extend the range of provided REST calls, add new annotated calls using configured client. Have a look at the code for more call examples.

REST client configuration

The Eloqua rest client configuration is in /modules/external-forms-eloqua/rest-client .  

Service configuration

The service configuration is in /modules/external-forms-eloqua/external-form-service .

IBM Web Forms implementation

You can connect to forms created in IBM Watson Campaign Automation.

The IBM forms module is configured in /modules/external-forms-ibm/external-form-service.

 If your forms contain GDPR-sensitive data, see GDPR and external forms where a GDPR IBM Watson Campaign Automation sample is explained. 

IBM External Form component

The IBM implementation has a dedicated, separate component.

The component definition is in /modules/external-forms-ibm/templates/components/externalForm and extends /modules/external-forms/templates/components/externalForm . 

Configuring form settings

Form settings are configured in the External Form component.

Form tab 

For the description of the other fields of the component see the part External Form component below.

Implementing your own marketing tool

The ExternalFormsmodule includes an API to define external form services, connectors and parsers.

Implement the following interfaces and abstract class to implement a new service: 

• info.magnolia.extforms.services.ExternalFormService ( ExternalFormService )
• info.magnolia.extforms.connectors.ExternalFormConnector ( ExternalFormConnector )
• info.magnolia.extforms.parsers.ExternalFormParser ( ExternalFormParser )
• info.magnolia.extforms.form.engine.AbstractExternalFormDataBinder ( AbstractExternalFormDataBinder )

Here's a skeleton of what your module configuration should look like.

Mail configuration

The module uses the  Mail module  to send emails.  Configure SMTP to enable email sending.

External Form component

The module installs the External Form component that integrates with the Form module to render the external form configured in the marketing tool.

The component definition is in  /modules/external-forms/templates/components/externalForm .

Configuring form settings

Form settings are configured in the External Form component.

Form tab

Submit settings tab

Resubmit success email tab

The module sends a confirmation email to the user when automatic resubmission succeeds. You can use Freemarker tags such as ${inf_field_Email} in the message to reference form fields. You can also map form field names to other names in the fieldMappings node in the Service configuration. For example, map the field name inf_field_Email to email and then access the field with Freemarker tag ${email} .

Resubmit validation error email tab

The module sends an email to the user when automatic resubmission fails. This tab is the same as  Resubmit success email tab.

Automatic resubmission

If the marketing tool is unavailable and form submission fails, forms are queued for automatic resubmission. The user receives one of two emails configured in the External form component notifying them about the success or failure of the resubmission.  The module uses the Scheduler module to resubmit pending submissions automatically.

Forms queued for resubmission can be viewed and resubmitted manually in the External Forms app.

Resubmission status:

	An error occurred during the form submission, for example status code 500 Service unavailable.
	The form was submitted successfully (HTTP status 200 OK) but the page returned by the marketing is not recognized. The returned page is neither a success page or a validation error page. It could be a page about the server being updated or the like. The External Forms module does not know how to handle this state so it stores the form for later resubmission.

Resubmission scheduling is configured in /modules/external-forms/config@cron . By default the module resubmits forms once a day at 2 a.m.