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

The Marketing Automation Connector pack allows you to capture leads on your website. This feature is commonly called web-to-lead.

Use the Marketing Automation modules to connect your third-party marketing software solution to Magnolia.  Render a form configured in your marketing software solution as a Magnolia form and automatically send the lead data back to your solution. We provide out-of-the-box connectors for Marketo and Salesforce. The Salesforce connector stores the captured leads as Lead objects in Salesforce. The Marketo connector stores them in Marketo. 

Module structure

artifactIDDescription

magnolia-marketing-automation-parent

Parent reactor.

magnolia-marketing-automation

Provides the foundation and the API for marketing automation.

magnolia-marketing-automation-ui

Provides the sample templating scripts and component definitions to quickly enable external forms in your Magnolia pages.

magnolia-marketing-automation-marketo-connector

Provides a default implementation to connect to Marketo

magnolia-marketing-automation-salesforce-connector

Provides a default implementation to connect to Salesforce.

Installing

Maven is the easiest way to install the modules. Add the following dependencies to your webapp. All the other necessary dependencies will be brought in automatically:

<dependency>
  <groupId>info.magnolia.marketingautomation</groupId>
  <artifactId>magnolia-marketing-automation</artifactId>
  <version>1.0.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.marketingautomation</groupId>
  <artifactId>magnolia-marketing-automation-ui</artifactId>
  <version>1.0.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.marketingautomation</groupId>
  <artifactId>magnolia-marketing-automation-marketo-connector</artifactId>
  <version>1.0.1</version>
</dependency>

<dependency>
  <groupId>info.magnolia.marketingautomation</groupId>
  <artifactId>magnolia-marketing-automation-salesforce-connector</artifactId>
  <version>1.0.1</version>
</dependency>

Configuration

This section explains how to configure the connection between the Marketing Automation module and your external marketing software solution. Essentially, you:

  • Provide connection details for your external solution.
  • Map your external solution fields to Magnolia field types.
  • Configure the cache if necessary.

You can create or edit the configuration in the JCR or the File System (YAML) under <module-name>/marketing-automations/<definition-name>.

Before you configure the connection, make sure you know:

  • Which solution you want to connect to. Default implementations are provided for:
    • Marketo
    • Salesforce
  • The relevant URLs to connect to your external marketing software solution.  
  • Connection credentials for your solution.

The Marketing Automation Connector Pack provides out-of-the-box connectors to the Marketo and Salesforce. If you use another third-party marketing software solution, you can write your own implementation to configure your own connector.

Marketo connection configuration

To use Marketo forms in Magnolia, you must have a working Marketo account.

Credentials

You need Marketo credentials to access the forms. Credentials consist of two parts: 

  • clientId
  • clientSecret

You can configure these credentials in the /marketing-automation-marketo-connector/marketing-automations/marketo.yaml file.

Alternatively, you can add the clientSecret part of your credentials to your Magnolia instance in the Password manager app and reference the path in the configuration.

Connecting

Add your connection configuration to the connections list (see YAML line 12).

Magnolia provides a default implementation to retrieve forms and leads from Marketo (YAML lines 4-11).

/marketing-automation-marketo-connector/marketing-automations/marketo.yaml
class: info.magnolia.mkautomation.definition.DefaultMarketingFormDefinition
enabled: true
type: marketo
implementation:
  forms:
    all: info.magnolia.mkautomation.marketo.forms.All
    byId: info.magnolia.mkautomation.marketo.forms.ById
    byName: info.magnolia.mkautomation.marketo.forms.ByName
    submitBy: info.magnolia.mkautomation.marketo.forms.SubmitBy
  leads:
    searchBy: info.magnolia.mkautomation.marketo.leads.SearchByFilterType
connection:
  baseUrl: https://641-OQJ-158.mktorest.com
  authUrl: https://641-OQJ-158.mktorest.com/identity/oauth/token
  clientId: b96f40ff-38fb-4832-ab80-080c067debe7
  clientSecret: client_secret_or_path_to_password_manager
formSelectorId: marketing-automation-ui:fieldsSelectionForm

Salesforce connection configuration

To use Salesforce web-to-lead functionality in Magnolia, you must have a working Salesforce account.

Credentials

You need the following Salesforce credentials: 

  • clientId
  • clientSecret
  • username and password

You can configure these credentials in the /marketing-automation-salesforce-connector/marketing-automations/salesforce.yaml file.

Alternatively, you can add the clientSecret and password parts of your credentials to your Magnolia instance in the Password manager app and reference the path in the configuration.

Connecting

Add your connection configuration to the connections list (see YAML line 12).

Magnolia provides a default implementation to retrieve forms and leads from Salesforce (see YAML lines 4-11).

/marketing-automation-salesforce-connector/marketing-automations/salesforce.yaml
class: info.magnolia.mkautomation.definition.DefaultMarketingFormDefinition
enabled: true
type: salesforce
implementation:
  forms:
    all: info.magnolia.mkautomation.salesforce.forms.All
    byId: info.magnolia.mkautomation.salesforce.forms.ById
    byName: info.magnolia.mkautomation.salesforce.forms.ByName
    submitBy: info.magnolia.mkautomation.salesforce.forms.SubmitBy
  leads:
    searchBy: info.magnolia.mkautomation.salesforce.leads.SearchByQuery
connection:
  baseUrl: https://mianlien.my.salesforce.com/services
  authUrl: https://login.salesforce.com/services/oauth2/token
  credentials:
    username: email@email.com
    password: password_or_path_to_password_manager
  clientId: 3MVG96_7YM2sI9wT5awWympuHDV97wt6AsbvT1ILMqMWXfUgSfB0e4SztxStXnyjskXpQC571mKsUx2qddJiw
  clientSecret: client_secret_or_path_to_password_manager
selectedForms:
  - Lead
  - Account
  - Contact
formSelectorId: marketing-automation-ui:fieldsSelectionForm

Connection configuration properties

These are the properties used to configure a connection to your external marketing software solution. The properties required vary depending on your solution (see Required for column in the table below).

PropertyDescriptionRequired for

class

required

info.magnolia.mkautomation.definition.DefaultMarketingFormDefinition

All
enabled

required , default is false

Enables the connector. Set to true to enable.

All

type

required

Your marketing software solution: marketo or salesforce

All
implementation
All

forms


All

all

required , default is info.magnolia.mkautomation.<salesforce/marketo>.forms.All

Implementation to retrieve all forms from your external marketing software solution.

All

byId

required , default is info.magnolia.mkautomation.<salesforce/marketo>.forms.ById

Implementation to retrieve forms by ID from your external marketing software solution.

All

byName

required , default is info.magnolia.mkautomation.<salesforce/marketo>.forms.ByName

Implementation to retrieve forms by name from your external marketing software solution.

All

submitBy

required , default is info.magnolia.mkautomation.<salesforce/marketo>.forms.SubmitBy

Implementation to submit form by form name/id to your external marketing software solution.

All

leads



searchBy

required ,

default for Salesforce is info.magnolia.mkautomation.salesforce.leads.SearchByQuery

default for Marketo is info.magnolia.mkautomation.marketo.leads.SearchByFilterType

Implementation to retrieve leads based on a search query or filter from your external marketing software solution.

All
connection

authUrl

required

Authentication URL for the external solution you want to connect to.

All

baseUrl

required

Base URL for the external solution you want to connect to.

All

credentials



username

required

User name for Salesforce.

Salesforce

password

required

Password for Salesforce or the path to the Magnolia password manager.

Salesforce
clientId

required

User name for your external solution.

All
clientSecret

required

Client secret for your external solution or the path to the Magnolia password manager.

All
selectedForms

optional

Filters the forms displayed.  For the Salesforce connector, the filter is based on Salesforce sObject form names.

(warning) The values are case sensitive.

For example, with these values set, only the Lead, Account and Contact forms are available in the Marketing Form dialog:

- Lead
- Account
- Contact

If the selectedForms property isn't set or if it's empty, all forms are displayed.

All
formSelectorId

optional

Path to the definition that configures if whole forms or form fields can be selected.

Magnolia provides the following form definitions:

  • marketing-automation-ui:defaultForm
  • marketing-automation-ui:fieldsSelectionForm

You can create your own Form definitions to suit your requirements.

If the formSelectorId property isn't set or if it's empty, only whole forms can be selected in the dialog

All

Enabling form field selection

If you want your editors to be able to choose individual fields rather than whole forms, you must enable field selection in the Marketing Form dialog and provide a definition to configure the display.

Magnolia provides basic definitions out-of-the-box:

  • defaultForm - only forms can be selected. 
  • fieldsSelectionForm - form fields can be selected.

However, you can create your own form definitions to suit your requirements under: /marketing-automation-<your-module>/marketing-formselectors/<configured form>.yaml

In the samples provided, field selection is enabled by default in the Salesforce example and not enabled in the Marketo example.

To enable form field selection:

  1. Add the formSelectorId property to the  /marketing-automation-<your-connector>/marketing-automations/<your-connector>.yaml file.
  2. Set the value of the property to the path to the field selection definition.
    Magnolia provides the following definitions out-of-the-box:
    1. defaultForm - only forms can be selected (red rectangle in the image). 
    2. fieldsSelectionForm - form fields can be selected (blue rectangle in the image).
  3. Edit the samples or create your own form definition under /marketing-automation-<your-module>/marketing-formselectors/<configured form>.yaml.
    For example:

    /marketing-automation-ui/marketing-formselectors/fieldsSelectionForm.yaml
    implementationClass: info.magnolia.mkautomation.ui.form.MarketingSwitchableSubFormView
    properties:
      marketingForm:
        $type: comboBoxField
        filteringMode: STARTSWITH
        textInputAllowed: true
        emptySelectionAllowed: false
        required: true
        requiredErrorMessage: marketing-automation-ui.form.field.validation.message.required
        label: marketing-automation-ui.editForm.marketingForm
        datasource:
          $type: formOptionListDatasource
      marketingFields:
        $type: marketingTwin
        label: marketing-automation-ui.editForm.marketingTwin
        leftColumnCaption: marketing-automation-ui.editForm.marketingTwin.leftColumnCaption
        rightColumnCaption: marketing-automation-ui.editForm.marketingTwin.rightColumnCaption
        datasource:
          $type: fieldOptionListDatasource
        validators:
          - name: requiredFields
            $type: requiredFieldsValidator
Properties used in the example
PropertyDescription
implementationClass

required

info.magnolia.mkautomation.ui.form.MarketingSwitchableSubFormView

$type


required

Use a valid field alias name to reference a field type.

filteringMode

required

Vaadin  FilteringMode . Available values are  contains and startswith

textInputAllowed

optional, default is false

When true, the user can type into the field to filter the available items. The filteringMode property defines how the options are filtered.

When false, the field just shows the current selection.

emptySelectionAllowed

optional, default is false

Defines whether the user can select nothing in the field. When true, an empty item appears to the user.

required

optional , default is false

Makes the field required. An asterisk is displayed next to the field label.

requiredErrorMessage

optional , default is validation.message.required

Error message shown when required is set to true and the user saves an empty field. The value can be literal or retrieved from the message bundle with a key. Use alphanumeric characters in literal values.

label

optional

Field label displayed to editors. The value can be literal or a key of a message bundle.

If you do not provide the property, Magnolia will fall back to a generated i18n key.

If you do not want to have any label, set the property to an empty string such as label: "" in YAML.

datasource


$type

required

Use a valid field alias name to reference a field type.

leftColumnCaption

optional

Left column label displayed to editors. The value can be literal or a key of a message bundle.

rightColumnCaption

optional

Left column label displayed to editors. The value can be literal or a key of a message bundle.

validators

optional

List of field validator definition items.

Disabling form pre-filling

Form pre-filling is an option offered by many marketing automation solutions. Pre-filling is when values previously entered by a visitor in a form are loaded into the corresponding form fields on a subsequent visit.  By default, form pre-filling is enabled in Magnolia. 

You can disable this feature by adding a formPrefillingEnabled property set to false in your connector configuration under <module-name>/marketing-automations/<definition-name>.

...
formPrefillingEnabled: false

Configuring field mapping between your external solution and Magnolia

Map your fields to HTML field types in the marketing-automation-<marketo/salesforce>-connector/config.yaml file. 

Marketo example:

/marketing-automation-marketo/config.yaml
fieldsMappingConfiguration:
  dataTypeField: $.dataType
  fieldsMapping:
    currency: text
    checkbox:
      name: booleanCheckbox
      value: $.defaultValue
      label: 
      defaultValue: $.defaultValue
    date: date
    datetime: datetime
    double: number
    email: email
    hidden: hidden
    profiling: hidden
    int: number
    number: number
    phone: tel
    select:
      name: select
      value: $.fieldMetaData.values[*].value
      label: $.fieldMetaData.values[*].label
      multiSelect: $.fieldMetaData.multiSelect
      defaultValue: $.defaultValue
    string: text
    textarea: textarea
    url: url
    checkboxes:
      name: checkbox
      value: $.fieldMetaData.values[*].value
      label: $.fieldMetaData.values[*].label
      defaultValue: $.defaultValue
    radioButtons:
      name: radio
      value: $.fieldMetaData.values[*].value
      label: $.fieldMetaData.values[*].label
      defaultValue: $.defaultValue

Salesforce example:

fieldsMappingConfiguration:
  dataTypeField: $.type
  fieldsMapping:
    string: text
    boolean:
      name: booleanCheckbox
      value: $.label
      label:
      defaultValue:
    textarea: textarea
    double: number
    phone: tel
    email: email
    url: url
    address: text
    currency: number
    int: number
    reference:
      name: select
      value: $.picklistValues[*].value
      label: $.picklistValues[*].label
      defaultValue:
    picklist:
      name: select
      value: $.picklistValues[*].value
      label: $.picklistValues[*].label
      defaultValue:
    multipicklist:
      name: select
      value: $.picklistValues[*].value
      label: $.picklistValues[*].label
      multiSelect: true
      defaultValue:
    date: date
    datetime: datetime

Field mapping properties

Property

Description
fieldsMappingConfigurationrequired

dataTypeField

required

Defines the field type in JSONPath format. For example: $.dataType gets the dataType field type.

fieldsMapping

required

leftValue: rightValue

required

For simple fields, such as string: text

  • The leftValue represents the data type returned from your external marketing software solution. 
  • The rightValue maps to HTML field types, for example string: text means the field type string from your external marketing software solution is rendered as an <input type="text"... /> field in the browser.

You can list as many field mappings as required. 

For complex HTML fields that need extra values, such as select fields or checkboxes, you can also configure additional values. For example:

  select:
      name: select
      value: $.fieldMetaData.values[*].value
      label: $.fieldMetaData.values[*].label
      multiSelect: $.fieldMetaData.multiSelect
      defaultValue: $.defaultValue
Where:
  • select – Field type returned by the provider.
  • name – Magnolia HTML field type, for example select
  • value – Value for the field options (for select, checkbox, radio type fields) in JSONPath format. For example:  $.fieldMetaData.values[*].value
  • label – Label for the field options (for select, checkbox, radio type fields) in JSONPath format. For example:  $.fieldMetaData.values[*].label
  • multiSelect - For a field with multiple options. For example: $.fieldMetaData.multiSelect
  • defaultValue – The property that stores the default value. For example: $.defaultValue

See Marketo field types documentation and Salesforce field types

Configuring the cache

By default, the cache is enabled and content pulled from your external solution is updated every 300 seconds (5 minutes). 

You can enable or disable the cache and change the frequency via YAML:

/marketing-automation/config.yaml
cachingDefinition:
  enabled: true
  invalidateInSeconds: 300

Configuring your own connector

Magnolia provides an API to enable the Magnolia author instance to get form and lead data from your external marketing software solution. We provide out-of-the-box implementations to connect to Marketo and Salesforce. If you want to connect to another third-party solution, you must write your own implementation.

You can integrate with another third-party marketing software solution using the following interfaces provided by the marketing-automation submodule:

  •  info.magnolia.mkautomation.common.marketingforms (for forms)
  • info.magnolia.mkautomation.common.marketingleads (for leads)
MarketingForms.java
package info.magnolia.mkautomation.common;

import info.magnolia.mkautomation.function.SubmitSupplier;
import info.magnolia.mkautomation.function.Supplier;
import info.magnolia.mkautomation.function.SupplierByOptional;

import lombok.AllArgsConstructor;
import lombok.Data;

/**
 * Provides API to operate on {@linkplain Form} objects.
 */
@Data
@AllArgsConstructor
public class MarketingForms {

    private All all;
    private ById byId;
    private ByName byName;
    private SubmitBy submitBy;

    /**
     * Supplier interface for getting all external forms.
     */
    public interface All extends Supplier<Form> {
    }

    /**
     * Supplier interface for external form searched by id.
     */
    public interface ById extends SupplierByOptional<Form, Form.Id> {
    }

    /**
     * Supplier interface for external form searched by name.
     */
    public interface ByName extends SupplierByOptional<Form, Form.Id> {
    }

    /**
     * Supplier interface for post a external form.
     */
    public interface SubmitBy extends SubmitSupplier<Form> {
    }
}
MarketingLeads.java
package info.magnolia.mkautomation.common;

import info.magnolia.mkautomation.function.SupplierByOptional;

import java.util.Map;

import lombok.AllArgsConstructor;
import lombok.Data;

/**
* Provides API to operate on {@linkplain Lead} objects.
*/
@Data
@AllArgsConstructor
public class MarketingLeads {

private SearchBy searchBy;

/**
* Supplier interface for external lead searched by parameters.
*/
public interface SearchBy extends SupplierByOptional<Lead, Map<String, String>> {
}

}

Usage

The magnolia-marketing-automation-ui submodule provides a sample Marketing Forms component that is available in the Basic page template by default. 

Sample page component

When you add the Marketing Form component to a page, a sample dialog enables you to select the connector you have configured. Once you select the connector, you can choose the form and, if you have enabled form field selection, the form fields you want. 

 

When field selection is enabled, note that:

  • If there are required fields for the form type you selected, you must select them in Magnolia.
  • You cannot remove required fields in Magnolia, you must remove them from the original form in your external marketing software solution if required. 
  • You cannot reorder the fields you select in Magnolia. They are displayed as they were designed in your external marketing software solution.

When field selection is not enabled, the form fields are defined directly in your external marketing software solution and you only select the form in the dialog.

Once you have added a form to a page, you can publish the page and make it available to your website users. Data entered by your users in the rendered form is sent directly back to your external marketing software solution.

Progressive forms are supported by Magnolia if they are enabled in your external marketing software solution.


Release history

Marketing Automation module 1.0.1

Released on July 21, 2020.

This release provides bug fixes including a fix for a null pointer exception:

[ MKTAUT-112 ] - Reinitialising the connection may cause a NPE

Marketing Automation module 1.0

Released on April 6, 2020.

Initial release of the Marketing Automation Connector Pack for integrating with third-party marketing software solutions, such as Marketo and Salesforce, so that you can use your forms or form fields directly in Magnolia and efficiently collect data about your prospects and customers. 

See Marketing Automation Connector Pack for an overview of the functionality provided.

Marketing Automation Connector Pack compatibility

Module version

Magnolia CMS version

1.0.16.2.2

1.0 

6.2

A note about connector compatibilty

The third-party versions listed below are the versions Magnolia has developed and tested against. If you don’t see a particular version listed, it simply means that we do not routinely test on it.

If you are using another version of the third-party tool and run into compatibility issues, please contact our Support team

Module versionMarketo API
1.0Tested against 2.2.0
Module versionSalesforce API
1.0Tested against 45.0