Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.
The Magnolia External Forms module allows you to replicate Web forms from a marketing automation tool as a Magnolia form and resubmit data back to the marketing tool. The module provides pre-configured templates for easy replication of Web forms. Editors can add a form on the page by selecting it from a list.
Installing
The Magnolia External Forms bundle consists of two modules:
- External forms: Provides functionality for rendering an external form as a Magnolia form and queues submissions in case the marketing tools is not available. Provides an API for defining external form services, connectors and parsers.
- External forms Infusionsoft: Example implementation of
ExternalFormService,ExternalFormConnectorandExternalFormParserfor InfusionSoft marketing tool. - External forms Eloqua: Example implementation of
ExternalFormService,ExternalFormConnectorandExternalFormParserfor Eloqua marketing tool.
See Installing a module on how to install the bundle using JARs or Maven dependencies. Once you have installed the module, configure the service for your desired marketing tool.
Magnolia External Forms module is not bundled with Magnolia. You can download it from our Nexus repository or include it in your custom webapp by adding following Maven dependency to your pom.
<dependency> <groupId>info.magnolia.extforms</groupId> <artifactId>magnolia-external-forms</artifactId> <version>1.1</version> </dependency>
if your marketing tool is Infusionsoft add just this Maven dependency. It includes the External Forms module automatically.
<dependency> <groupId>info.magnolia.extforms</groupId> <artifactId>magnolia-external-forms-infusionsoft</artifactId> <version>1.1</version> </dependency>
if your marketing tool is Eloqua add just this Maven dependency. It includes the External Forms module automatically.
<dependency> <groupId>info.magnolia.extforms</groupId> <artifactId>magnolia-external-forms-eloqua</artifactId> <version>1.1</version> </dependency>
Uninstalling
To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.
However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.
To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.
We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.
Configuration
The Form module is configured at /modules/external-forms.
Node name | Value |
|---|---|
external-forms | |
apps | |
config | |
commands | |
fieldTypes | |
dialogs | |
templates |
Mail configuration
Configure SMTP to enable mail sending. The External Forms module uses the Mail module to notify the user who submitted the form by email about successful or failed resubmission. See Queue submissions if marketing tool isn't available.
Service configuration
Configure External Form services in /modules/<external-forms-marketing-tools-custom-integartion>/external-form-service.
Implement the following interfaces, abstract classes and configuring your implementation classes in the module:
info.magnolia.extforms.services.ExternalFormServiceinfo.magnolia.extforms.connectors.ExternalFormConnectorinfo.magnolia.extforms.parsers.ExternalFormParserinfo.magnolia.extforms.form.engine.AbstractExternalFormDataBinder
The Infusionsoft module provides an example implementation with InfusionSoft and Eloqua.
| Node name | Value |
|---|---|
external-form-service | |
<your service> | |
externalFormConnector | |
class | <class that implements info.magnolia.extforms.connectors.ExternalFormConnector> |
externalFormParser | |
class | <class implements info.magnolia.extforms.parsers.ExternalFormParser> |
fieldMappings | |
class | <class that implements info.magnolia.extforms.services.ExternalFormService> |
externalFormDataBinderClass | <class that extends info.magnolia.extforms.form.engine.AbstractExternalFormDataBinder> |
Example: InfusionSoft service configuration
Please read how to generate Infusionsoft API Key.
| Node name | Value |
|---|---|
external-form-service | |
infusionsoft | |
externalFormConnector | |
apiKey | <your InfusionSoft API key> |
applicationName | <your InfusionSoft applicationName> |
class | info.magnolia.extforms.connectors.InfusionsoftExternalFormConnector |
externalFormParser | |
class | info.magnolia.extforms.parsers.InfusionsoftExternalFormParser |
fieldMappings | |
Referer | form_page |
inf_field_Email | |
clas | info.magnolia.extforms.services.InfusionsoftExternalFormService |
externalFormDataBinderClass | info.magnolia.extforms.form.engine.InfusionsoftExternalFormDataBinder |
Example: Eloqua service and rest-client configuration
Please read how to generate Eloqua encoded authentication key. You can also configure your siteName, username and password instead of encodedKey and Magnolia will take care about encoding.
Please read how to determine the URL for your Rest API 2.0 calls.
| Node name | Value |
|---|---|
rest-client | |
eloqua | |
clientFilters | |
authenticationFilter | |
class | info.magnolia.extforms.rest.filter.AuthenticationFilter |
encodedKey | <your Eloqua REST API encoded authentication key> |
baseUrl | <URL for your Eloqua REST API 2.0 calls, for example: https://www02.secure.eloqua.com/API/REST/2.0> |
class | info.magnolia.resteasy.client.RestEasyClientDefinition |
clientFactoryClass | info.magnolia.resteasy.client.factory.RestEasyClientFactory |
| Node name | Value |
|---|---|
external-form-service | |
infusionsoft | |
externalFormConnector | |
class | info.magnolia.extforms.connectors.EloquaExternalFormConnector |
restClientId | <your Eloqua REST client id> |
externalFormParser | |
class | info.magnolia.extforms.parsers.EloquaExternalFormParser |
fieldMappings | |
Referer | form_page |
emailAddress | |
clas | info.magnolia.extforms.services.EloquaExternalFormService |
externalFormDataBinderClass | info.magnolia.extforms.form.engine.EloquaExternalFormDataBinder |
Eloqua integration - REST API
All communication between Magnolia and Eloqua is made strictly over the REST API provided by Eloqua.
The following calls are utilized by the module:
/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.
Templates
The module installs two templates that integrate with existing STK templates and the Form module. The templates are configured in /modules/external-forms/templates.
External Form page template
External Form page template in /modules/external-forms/templates/pages/externalForm contains one autogenerated External Form component.
External Form component template
External Form component template in /modules/external-forms/templates/components/externalForm renders the external form from the marketing tool.
Form tab
Field | Description |
|---|---|
Title | Title displayed above the form. For example "Contact Us". |
Text | Introductory text displayed below the form title. |
Select external form | Fields for selecting the external form. The first field selects the service (marketing tool) where the external form resides. The second field selects an external form available in the service. |
Submit settings tab
Field | Description |
|---|---|
Error title | Title displayed when an error occurs. |
Waiting title | Title displayed when the form cannot be submitted to the marketing tool because the tool is unavailable. In this case the filled form is queued for later automatic submission. |
Waiting message | Additional information displayed below the waiting title. |
Page displayed after submission | Page to display after successful submission. If no page is selected, the page defined in marketing tool is used. |
Resubmit success email tab
The module sends a confirmation mail to user who filled the form in case automatic resubmission was successful. 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
This tab is the same as Resubmit success email tab with the difference that email is sent in case form validation fails during resubmission.
Queue submissions if marketing tool isn't available
The External Forms module provides queu form submissions if the marketing tool is not available. Pending submissions are automatically resubmitted using the scheduler module. The user who filled the form gets mail about success or failed resubmission.
The module resubmits forms once a day at 2 a.m. by default. You can changing cron expression defined in /modules/external-forms/config@cron.
Viewing queued submissions
Use the External Forms app to view queued submissions. Click Submit forms to resubmit manually. The action is configured in modules/external-forms/apps/external-forms/subApps/browser/actions/submit.
In the example above you can see two queued forms with status icons:
Red icon means that an error occurred during the form submission, for example status code 500 Service unavailable.
Yellow icon means that the form was submitted successfully (HTTP status 200 OK) but the page returned by the marketing is not recognized. The returned page is not a success page or a validation error page. It could be a page about the server being updated or such. The External Forms module does not know how to handle this state so it stores the form for later resubmission.
Overview
Content Tools