Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
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
Maven is the easiest way to install the module. Add the following dependency to your bundle:
For Infusionsoft add this Maven dependency. It includes the External Forms module automatically.
For Eloqua add this Maven dependency. It includes the External Forms module automatically.
For IBM add this Maven dependency. It includes the External Forms module automatically.
Pre-built jars are also available for download. See Installing a module for help.
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.
Node name | Value |
|---|---|
external-forms | |
apps | |
config | |
commands | |
fieldTypes | |
dialogs | |
templates |
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.
| Node name | Value |
|---|---|
external-form-service | |
infusionsoft | |
externalFormConnector | |
apiKey | <Infusionsoft API key> |
applicationName | <Infusionsoft applicationName> |
class | info.magnolia.extforms.connectors.InfusionsoftExternalFormConnector |
externalFormParser | |
class | info.magnolia.extforms.parsers.InfusionsoftExternalFormParser |
fieldMappings | |
Referer | form_page |
inf_field_Email | |
class | info.magnolia.extforms.services.InfusionsoftExternalFormService |
externalFormDataBinderClass | info.magnolia.extforms.form.engine.InfusionsoftExternalFormDataBinder |
external-form-service | required External form service configuration |
| required Name of external service. |
| required External form connector node. |
| required Your Infusionsoft API key. See Infusionsoft API Key to generate your key. |
| required Your Infusionsoft application name. See Infusionsoft API Key to create your application. |
| required InfusionsoftExternalFormConnector : implementation of ExternalFormConnector for Infusionsoft. |
| required External form parser node. |
| required InfusionsoftExternalFormParser : Implementation of ExternalFormParser for Infusionsoft |
| required Field mappings node. Map Infusionsoft fields to defined names. Mapped fields can be accessed in emails with Freemarker tags when configuring form settings. |
| required Referer field in Infusionsoft. Use |
| optional This mapping allows your to access the |
| required InfusionsoftExternalFormService : implementation of ExternalFormService for Infusionsoft. |
| required InfusionsoftExternalFormDataBinder extends AbstractExternalFormDataBinder for Infusionsoft. |
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.
| Node name | Value |
|---|---|
rest-client | |
eloqua | |
clientFilters | |
authenticationFilter | |
class | info.magnolia.extforms.rest.filter.AuthenticationFilter |
encodedKey | <Eloqua REST API encoded authentication key> |
baseUrl | <URL for your Eloqua REST API 2.0 calls, for example: https://secure.p02.eloqua.com/API/REST/2.0 > |
class | info.magnolia.resteasy.client.RestEasyClientDefinition |
clientFactoryClass | info.magnolia.resteasy.client.factory.RestEasyClientFactory |
eloqua | required Eloqua rest client configuration. |
| required Client filters node. |
| required Authentication filters node. |
| required AuthenticationFilter adds an authentication header to each request to the Eloqua API. |
| required Your Eloqua REST API encoded authentication key. See Eloqua REST API - Authenticating to generate your key. |
| required URL for your Rest API 2.0 calls. See Determining Endpoint URLs for more. |
| required RestEasyClientDefinition : Rest easy client class. |
| required
RestEasyClientFactory
: Factory class that creates |
Service configuraion
The service configuration is in /modules/external-forms-eloqua/external-form-service.
| Node name | Value |
|---|---|
external-form-service | |
eloqua | |
externalFormConnector | |
class | info.magnolia.extforms.connectors.EloquaExternalFormConnector |
restClientId | <Eloqua REST client ID> |
externalFormParser | |
class | info.magnolia.extforms.parsers.EloquaExternalFormParser |
fieldMappings | |
Referer | form_page |
emailAddress | |
class | info.magnolia.extforms.services.EloquaExternalFormService |
externalFormDataBinderClass | info.magnolia.extforms.form.engine.EloquaExternalFormDataBinder |
external-form-service | required External form service configuration |
| required Name of external service. |
| required External form connector node. |
| required EloquaExternalFormConnector : Implementation of ExternalFormConnector for Eloqua. |
| required Your Eloqua REST client ID. |
| required External form parser node. |
| required EloquaExternalFormParser : Implementation of ExternalFormParser for Eloqua |
| optional Field mappings node. Map Eloqua fields to defined names. Mapped fields can be accessed in emails with Freemarker tags when configuring form settings. |
| required Referer field in Eloqua. Use |
| required You can access the |
| required EloquaExternalFormService : implementation of ExternalFormService for Eloqua. |
| required EloquaExternalFormDataBinder extends AbstractExternalFormDataBinder for Eloqua. |
IBM Web Forms implementation
You can connect to forms created in IBM Marketing Cloud.
If you prefer creating forms in Magnolia, see IBM Marketing Cloud connector#Externalforms. The page also describes personalization and mail sending based on the data retrieved from the IBM Marketing Cloud.
The IBM forms module is configured in /modules/external-forms-ibm/external-form-service .
| Node name | Value |
|---|---|
external-form-service | |
ibm | |
externalFormConnector | |
sharedCookies | |
SESSION | SESSION |
SP_IDENTITY | SP_IDENTITY |
SP_PAGE_VISIT | SP_PAGE_VISIT |
VIEW | VIEW |
externalFormParser | |
class | info.magnolia.extforms.parsers.IbmExternalFormParser |
class | info.magnolia.extforms.services.DefaultExternalFormService |
externalFormDataBinderClass | info.magnolia.extforms.form.engine.DefaultExternalFormDataBinder |
external-form-service | required External form service configuration |
| required Name of external service. |
| required External form connector node. |
| Cookies which can be shared between Magnolia and IBM, e.g. to identify the current user when pre-filling the forms . |
| required IbmExternalFormConnector : implementation of ExternalFormConnector |
| required External form parser node. |
| required IbmExternalFormParser : Implementation of ExternalFormParser |
| required DefaultExternalFormService : implementation of ExternalFormService |
| required DefaultExternalFormDataBinder extends AbstractExternalFormDataBinder |
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
Field | Description |
|---|---|
Title | Title displayed above the form. |
Text | Introductory text displayed below the title. |
Form URL | A URL of the IBM External Form. |
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.
| Node name | Value |
|---|---|
modules | |
<custom-integration-module> | |
external-form-service | |
<service name> | |
externalFormConnector | |
class | <class that implements |
externalFormParser | |
class | <class implements |
fieldMappings | |
class | <class that implements |
externalFormDataBinderClass | <class that extends |
Mail configuration
The modules 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
Field | Description |
|---|---|
Title | Title displayed above the form. For example "Contact Us". |
Text | Introductory text displayed below the title. |
Select external form | Fields for selecting the external form:
|
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 is unavailable. The form is queued for later automatic resubmission. |
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 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..
Node name | Value |
|---|---|
external-forms | |
config | |
cron | 0 0 2 1/1 * ? * |
Overview
Content Tools