Marketing Automation module
Connector Pack | Marketing Automation Connector Pack |
---|---|
License |
|
Issues |
|
Maven site |
|
Latest |
1.0.4 |
Yes |
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 Sales Cloud. The Salesforce connector stores the captured leads as Lead objects in Salesforce. The Marketo connector stores them in Marketo.
Module structure
artifactID | Description |
---|---|
|
Parent reactor. |
|
Provides the foundation and the API for marketing automation. |
|
Provides the sample templating scripts and component definitions to quickly enable external forms in your Magnolia pages. |
|
Provides a default implementation to connect to Marketo. |
|
Provides a default implementation to connect to Salesforce Sales Cloud. |
Installing with Maven
Bundled modules are automatically installed for you.
If the module is unbundled, add the following to your bundle including your project’s <dependencyManagement>
section and your webapp’s <dependencies>
section.
If the module is unbundled but the parent POM manages the version, add the following to your webapp’s <dependencies>
section.
<dependency>
<groupId>info.magnolia.marketingautomation</groupId>
<artifactId>magnolia-marketing-automation</artifactId>
<version>1.0.4</version> (1)
</dependency>
1 | Should you need to specify the module version, do it using <version> . |
<dependency>
<groupId>info.magnolia.marketingautomation</groupId>
<artifactId>magnolia-marketing-automation-ui</artifactId>
<version>1.0.4</version> (1)
</dependency>
1 | Should you need to specify the module version, do it using <version> . |
<dependency>
<groupId>info.magnolia.marketingautomation</groupId>
<artifactId>magnolia-marketing-automation-marketo-connector</artifactId>
<version>1.0.4</version> (1)
</dependency>
1 | Should you need to specify the module version, do it using <version> . |
<dependency>
<groupId>info.magnolia.marketingautomation</groupId>
<artifactId>magnolia-marketing-automation-salesforce-connector</artifactId>
<version>1.0.4</version> (1)
</dependency>
1 | Should you need to specify the module version, do it using <version> . |
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 Sales Cloud
-
-
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 Sales Cloud. 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/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).
a) The default configuration is to create or update leads using API (see YAML line 17). This submittedActionType
property can only be used with submitBy: info.magnolia.mkautomation.marketo.forms.SubmitBy
. (line )
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
submittedActionType: createOrUpdate # Default is createOrUpdate. Another type can be createOnly, updateOnly, or createDuplicate
b) If you want to provide functionality equivalent to a Marketo Form submission and support, create a Fill out Form activity by replacing submitBy
(see YAML line 9) with info.magnolia.mkautomation.marketo.forms.SubmitForm
. This will sync leads to Marketo using API.
class: info.magnolia.mkautomation.definition.DefaultMarketingFormDefinition
type: marketo
enabled: true
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.SubmitForm
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: your-client-id
clientSecret: your-client-secret
Salesforce connection configuration
To use Salesforce web-to-lead functionality in Magnolia, you must have a working Salesforce account that supports the Web Services API. See the “Web Services API” row here (under All features > Connect sales info to any app): https://www.salesforce.com/editions-pricing/sales-cloud/.
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).
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. Select the tab relevant to your connector.
Property | Description | ||
---|---|---|---|
|
required
|
||
|
required, default is Enables the connector. Set to |
||
|
required Your marketing software solution: |
||
|
|||
|
|||
|
required, default is Implementation to retrieve all forms from your external marketing software solution. |
||
|
required, default is Implementation to retrieve forms by ID from your external marketing software solution. |
||
|
required, default is Implementation to retrieve forms by name from your external marketing software solution. |
||
|
required, default is Implementation to submit form by form name/id to your external marketing software solution.
Implementation to sync leads to Marketo and create a Fill out Form activity. |
||
|
optional Use |
||
|
|||
|
required default for Marketo is Implementation to retrieve leads based on a search query or filter from your external marketing software solution. |
||
|
|||
|
required Authentication URL for the external solution you want to connect to. |
||
|
required Base URL for the external solution you want to connect to. |
||
|
|||
|
required User name for your external solution. |
||
|
required Client secret for your external solution or the path to the Magnolia password manager. |
||
|
optional Filters the forms displayed.
For example, with these values set, only the Lead, Account and Contact forms are available in the Marketing Form dialog:
If the |
||
|
optional Path to the definition that configures if whole forms or form fields can be selected. Magnolia provides the following form definitions:
You can create your own Form definitions to suit your requirements. If the |
Property | Description | ||
---|---|---|---|
|
required
|
||
|
required, default is Enables the connector. Set to |
||
|
required Your marketing software solution: |
||
|
|||
|
|||
|
required, default is Implementation to retrieve all forms from your external marketing software solution. |
||
|
required, default is Implementation to retrieve forms by ID from your external marketing software solution. |
||
|
required, default is Implementation to retrieve forms by name from your external marketing software solution. |
||
|
required, default is Implementation to submit form by form name/id to your external marketing software solution. |
||
|
|||
|
required default for Salesforce is Implementation to retrieve leads based on a search query or filter from your external marketing software solution. |
||
|
|||
|
required Authentication URL for the external solution you want to connect to. |
||
|
required Base URL for the external solution you want to connect to. |
||
|
|||
|
required User name for Salesforce. |
||
|
required Password for Salesforce or the path to the Magnolia password manager. |
||
|
required User name for your external solution. |
||
|
required Client secret for your external solution or the path to the Magnolia password manager. |
||
|
optional Filters the forms displayed. For the Salesforce connector, the filter is based on Salesforce sObject form names.
For example, with these values set, only the Lead, Account and Contact forms are available in the Marketing Form dialog:
If the |
||
|
optional Path to the definition that configures if whole forms or form fields can be selected. Magnolia provides the following form definitions:
You can create your own Form definitions to suit your requirements. If the |
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:
-
Add the
formSelectorId
property to the/marketing-automation-<your-connector>/marketing-automations/<your-connector>.yaml
file. -
Set the value of the property to the path to the field selection definition.
Magnolia provides the following definitions out-of-the-box:-
defaultForm
- only forms can be selected (red rectangle in the image). -
fieldsSelectionForm
- form fields can be selected (blue rectangle in the image).The final set of selected fields for the marketing form can only originate from one form. You cannot select multiple fields from different forms.
-
-
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.yamlimplementationClass: 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
Property | Description | ||
---|---|---|---|
|
required
|
||
|
required Use a valid field alias name to reference a field type. |
||
|
required Vaadin
|
||
|
optional, default is When When |
||
|
optional, default is Defines whether the user can select nothing in the field. When |
||
|
optional, default is Makes the field required. An asterisk is displayed next to the field label. |
||
|
optional, default is Error message shown when |
||
|
optional Field label displayed to editors. The value can be literal or a key of a message bundle.
If you do not want to have any label, set the property to an empty string such as |
||
|
|||
|
required Use a valid field alias name to reference a field type. |
||
|
optional Left column label displayed to editors. The value can be literal or a key of a message bundle. |
||
|
optional Left column label displayed to editors. The value can be literal or a key of a message bundle. |
||
|
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.
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
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 |
---|---|
|
required |
|
required Defines the field type in JSONPath format. For example: |
|
required |
|
required For simple fields, such as
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:
Where: * |
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:
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 Sales Cloud. 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)
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> {
}
}
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>> {
}
}
Decorating MTK2 in a light module
MTK2 was introduced in Magnolia 6.2.10.
If you want to use the marketing form component with MTK2, you must decorate MTK2 and add the marketing form component as shown in the example below:
$magnolia.resources.dir
└── my-module
└── decorations
├── mtk2
│ └── templates
│ └── pages
│ └── basic.yaml
areas:
main:
availableComponents:
marketingForm:
id: marketing-automation-ui:components/marketingForm
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.
The final set of selected fields for the marketing form can only originate from one form. You cannot select multiple fields from different forms. |
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.4
Released on May 30, 2023.
This release brings an improvement to our Marketo connector that now allows you to add a new submit form feature (MKTAUT-138). We also improved the error message of the Pack when connectors are disabled or misconfigured (MKTAUT-132).
Marketing Automation module 1.0.3
Released on May 6, 2021.
This release brings full compatibility with Magnolia 6.2.4 as well as a bug fix for the marketing form component, which was not working: MKTAUT-130.
Marketing Automation module 1.0.2
Released on January 28, 2021.
This release brings full compatibility with Magnolia 6.2.2 as well as a security-related bug fix: MKTAUT-116
We keep the details of security-related fixes private in line with our security policy.
Contact our Support team if you need more information.
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 Sales Cloud, 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.4 |
6.2.4+ |
1.0.3 |
6.2.4+ |
1.0.2 |
6.2.2+ |
1.0.1 |
6.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. |
Module version | Marketo API |
---|---|
1.0 |
Tested against 2.2.0 |
Module version | Salesforce Lightening Platform REST API |
---|---|
1.0 |
Tested against 45.0 |