Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata
DownloadNexus
EditionEnterprise
LicenseMNA
IssuesJIRA
SupportEnterprise
Maven siteExternal Forms

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, ExternalFormConnector and ExternalFormParser for InfusionSoft marketing tool.
  • External forms Eloqua: Example implementation of ExternalFormServiceExternalFormConnector and ExternalFormParser for 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

 Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

(warning) 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

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.ExternalFormService
  • info.magnolia.extforms.connectors.ExternalFormConnector
  • info.magnolia.extforms.parsers.ExternalFormParser
  • info.magnolia.extforms.form.engine.AbstractExternalFormDataBinder

The Infusionsoft module provides an example implementation with InfusionSoft and Eloqua.

Node nameValue

 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 nameValue

 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

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 nameValue

 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 nameValue

 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

email

 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.