Marketing Automation module
Customer data Unbundled: Extension License: Special license[1]
License |
|
Issues |
|
Maven site |
|
Latest |
2.0.0 |
Yes |
The Marketing Automation integration framework 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
Maven is the easiest way to install the module. Add the following to your bundle:
<dependency>
<groupId>info.magnolia.marketingautomation</groupId>
<artifactId>magnolia-marketing-automation</artifactId>
<version>2.0.0</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>2.0.0</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>2.0.0</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>2.0.0</version> (1)
</dependency>| 1 | Should you need to specify the module version, do it using <version>. |
|
There is an issue when using the Marketing Automation module.
Since module version Use the following dependency exclusion as a workaround if you want to use the Marketing Automation module: |
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 integration framework 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.
Licensing
The associated framework is included with your DX Core license and is free of charge. However, this extension is paid and requires an additional special license.
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).
-
The default configuration is to create or update leads using API (see YAML line 17). This
submittedActionTypeproperty can only be used withsubmitBy: 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-
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) withinfo.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-secretSalesforce 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/.
Licensing
The associated framework is included with your DX Core license and is free of charge. However, this extension is paid and requires an additional special license.
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:fieldsSelectionFormConnection 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
formSelectorIdproperty to the/marketing-automation-<your-connector>/marketing-automations/<your-connector>.yamlfile. -
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 don’t 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: falseConfiguring 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: $.defaultValuefieldsMappingConfiguration:
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: datetimeField 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: 300Configuring 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.yamlareas:
main:
availableComponents:
marketingForm:
id: marketing-automation-ui:components/marketingFormUsage
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.
Changelog
The changelog gives you an overview of the changes made to the Marketing Automation module at each release.
This changelog covers the 2.x branch of the Marketing Automation module. For the 1.x changelog, see here.
|
Compatibility
| Module version | Magnolia CMS version |
|---|---|
2.0.0 |
6.3.0+ |
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 |
|---|---|
2.0 |
Tested against 2.2.0 |
1.0 |
Tested against 2.2.0 |
| Module version | Salesforce Lightening Platform REST API |
|---|---|
2.0 |
Tested against 45.0 |
1.0 |
Tested against 45.0 |
Issues
Missing VerticalFormLayoutDefinition
The missing definition is indicated by the following error:
2024-09-18 15:30:22,560 WARN agnolia.transformer.ClassPropertyBasedTypeResolver: Encountered the 'class' property but failed to resolved the type from its value: [info.magnolia.mkautomation.ui.layout.VerticalFormLayoutDefinition]
java.lang.ClassNotFoundException: info.magnolia.mkautomation.ui.layout.VerticalFormLayoutDefinition
at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:445) ~[?:?]
at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:592) ~[?:?]
at groovy.lang.GroovyClassLoader.loadClass(GroovyClassLoader.java:862) ~[groovy-4.0.22.jar:4.0.22]
at groovy.lang.GroovyClassLoader.loadClass(GroovyClassLoader.java:736) ~[groovy-4.0.22.jar:4.0.22]