Page tree
Skip to end of metadata
Go to start of metadata

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 three 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.

Installing

Maven is the easiest way to install the module. Add the following dependency to your bundle:

<dependency>
  <groupId>info.magnolia.extforms</groupId>
  <artifactId>magnolia-external-forms</artifactId>
  <version>1.3.1</version>
</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>
  <version>1.3.1</version>
</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>
  <version>1.3.1</version>
</dependency>

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 nameValue

 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

email

 class

info.magnolia.extforms.services.InfusionsoftExternalFormService

 externalFormDataBinderClass

info.magnolia.extforms.form.engine.InfusionsoftExternalFormDataBinder
external-form-service

required

External form service configuration

infusionsoft

required

Name of external service.

externalFormConnector

required

External form connector node.

apiKey

required

Your Infusionsoft API key. See Infusionsoft API Key to generate your key.

applicationName

required

Your Infusionsoft application name. See Infusionsoft API Key to create your application.

class

required

InfusionsoftExternalFormConnector: implementation of ExternalFormConnector for Infusionsoft.

externalFormParser

required

External form parser node.

class

required

InfusionsoftExternalFormParser: Implementation of ExternalFormParser for Infusionsoft

fieldMappings

required

Field mappings node.

Map Infusionsoft fields to defined names. Mapped fields can be accessed in emails with Freemarker tags when configuring form settings.

Referer

required

Referer field in Infusionsoft. Use form_page in your configuration.

inf_field_Email

optional

This mapping allows your to access the inf_field_Email field with Freemarker tag ${email}.

class

required

InfusionsoftExternalFormService: implementation of ExternalFormService for Infusionsoft.

externalFormDataBinderClass

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 nameValue

 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.

clientFilters

required

Client filters node.

authenticationFilter

required

Authentication filters node.

class

required

AuthenticationFilter adds an authentication header to each request to the Eloqua API.

encodedKey

required

Your Eloqua REST API encoded authentication key. See Eloqua REST API - Authenticating to generate your key.

baseURL

required

URL for your Rest API 2.0 calls. See Determining Endpoint URLs for more.

class

required

RestEasyClientDefinition: Rest easy client class.

clientFactoryClass

required

RestEasyClientFactory: Factory class that creates RestEasyClient..

Service configuraion

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

Node nameValue

 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

email

 class

info.magnolia.extforms.services.EloquaExternalFormService

 externalFormDataBinderClass

info.magnolia.extforms.form.engine.EloquaExternalFormDataBinder
external-form-service

required

External form service configuration

eloqua

required

Name of external service.

externalFormConnector

required

External form connector node.

class

required

EloquaExternalFormConnector: Implementation of ExternalFormConnector for Eloqua.

restClientId

required

Your Eloqua REST client ID.

externalFormParser

required

External form parser node.

class

required

EloquaExternalFormParser: Implementation of ExternalFormParser for Eloqua

fieldMappings

optional

Field mappings node.

Map Eloqua fields to defined names.Mapped fields can be accessed in emails with Freemarker tags when configuring form settings.

Referer

required

Referer field in Eloqua. Use form_page in your configuration.

emailAddress

required

You can access the emailAddress field with Freemarker tag ${email}.

class

required

EloquaExternalFormService: implementation of ExternalFormService for Eloqua.

externalFormDataBinderClass

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: 

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

Node nameValue

 modules

 

 <custom-integration-module>

 

 external-form-service

 

 <service name>

 

 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>

Mail configuration

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:.

  1. To select the service (marketing tool) where the external form resides.
  2. To select the actual form configured 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 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 * ? *