This chapter gives a basic introduction about the TYPO3 CMS extension "mautic".
Target Audience
This extension is intended for those who use the marketing automation tool Mautic. This manual will walk you through the steps of
connecting your TYPO3 installation to your Mautic installation, as well as how to utilize the features of the extension.
This chapter will show you how to install the mautic extension in your TYPO3 instance.
Installation via Composer
If your TYPO3 instance is running in composer mode, you can simply require the extension by running
composer require mautic/mautic-typo3
Copied!
Installation via Extension Manager
Open the extension manager module of your TYPO3 instance and select "Get Extensions" in the select menu above the upload
button. There you can search for mautic and simply install the extension. Please make sure you are using the latest
version of the extension by updating the extension list before installing the mautic extension.
Installation via zip file
First you need the Marketing Automation extension, which can be found here https://extensions.typo3.org/extension/marketing_automation/.
Download the zip file, upload it to the extension manager of your TYPO3 instance and activate it. Then download the Mautic extension
at https://extensions.typo3.org/extension/mautic/ and also upload this zip file to the extension manager of your
TYPO3 instance and activate it.
Note: Please do not use GitHub to export a zip file because dependencies are missing.
Configuration
Log in to your Mautic dashboard. Click on the little cog-wheel icon at the top-right of the screen. A menu opens,
select "API Credentials". Click "New" at the top right. Select the authorization protocol "OAuth 1.0a" or "OAuth2", that you want to use, fill in a name, and leave the Callback URI
field blank to restrict callbacks. Then hit "Save & Close" at the top right of the screen.
You should now have two keys, "Public Key" and "Secret Key". We will come back to them later.
Click the little cog-wheel icon at the top-right of the screen again, then click "Configuration". Scroll down to the
"CORS settings" section and add the URL of your TYPO3 instance in the "Valid Domains" field, also check that
"Restrict Domains" is set to Yes. Save the configuration.
Again in configuration, on the left side click the tab "API Settings". Set "API enabled?" to Yes. Save the configuration.
Before we continue you must clear Mautic's cache. This can be done by deleting the contents of the app/cache directory
on the server.
Go back to the TYPO3 backend and open the Mautic backend module. Select the right authorization protocol. Fill in the root URL of your Mautic installation. Then
fill the public and the secret key with the values we generated earlier in Mautic. Click save. A new button should now
pop up that reads "Authorize with Mautic". Click this button, then log in and accept. You will be redirected back to
your TYPO3 instance.
If all went well a green flashmessage should show you that the connection to the Mautic API was successfull.
Your extension has now been configured.
Override Configuration
All configuration made in the backend module can simply be overwritten in your configuration files:
This chapter will go through all the features the Mautic extension for TYPO3 provides.
Enabling the Mautic Tracking Script
To enable Mautic tracking on your TYPO3 frontend, navigate to the Mautic configuration module. On the settings
page there is a tab called "Tracking". In this tab check the "Enable Mautic user tracking" checkbox and save the
settings. This implements the default Mautic tracking script based on the base URL of your Mautic installation.
If you would like to customize the tracking script you can do so by parsing it into the "Override default Mautic
tracking script (without script tags)" field. If the default script suits your needs, leave this field blank.
Including Mautic Forms
To include an existing Mautic form into your TYPO3 frontend, create a new content element. Select the tab
"Form elements", then select "Mautic Form".
You can configure this content element like any other content element. At the bottom of the tab "General" you will find
a dropdown list of all the forms present in Mautic. You can select one, and then save your content element.
Adding this content element to a page will render the Mautic form on the frontend.
Syncing TYPO3 forms with Mautic
Instead of including forms from Mautic, the extension also allows you to sync your TYPO3 forms to Mautic. With this
feature you can keep using the TYPO3 Forms environment (EXT:forms) to create your forms, and make sure Mautic
receives all the relevant data.
To start creating a form, go to the Forms module. Click the "Create a new form" button at the top. You can now name your
form. Make sure to check the "Advanced settings" checkbox. Then click next.
In the next screen select "Mautic Form" under "Form prototype". Under "Start template" you can either select
"Blank form" to start with a blank form, or "Simple contact form" to start with a simple template form. We recommend
selecting the "Simple contact form" for the sake of this tutorial. then click next, and click next again.
You should now see the simple contact form before you in the form editor. Before we continue, let's save our form. By
saving we automatically let Mautic know that a form has been created or updated.
After saving, our form should also appear in Mautic. Let's check there if it is present. Go to Mautic and navigate to
Components -> Forms.
As you can see, the form has been created. You can have a look inside the form if you want, you will see that all the
fields are present too.
To make sure the form data is sent to Mautic when the form is submitted, the "Send to Mautic Form" finisher must be
added to the form. The demo form should already have this added.
Warning
IMPORTANT: If you want to have multiple finisher for your form, keep in mind that the order matters! Make sure to add the Mautic
finisher's first, and TYPO3 finisher like "Redirect to a page" or other 3rd party finishers after it! For example, if
by mistake the "Redirect to a page" is placed before the "Send to Mautic Form" finisher, the API call to Mautic never
happens and no data are submitted.
With this set, all data submitted to the form will automatically be saved in Mautic.
Now let's make sure Mautic knows what kind of data is submitted in the form fields. For instance, if you have a field
in which the user should enter his or her email address, we would like Mautic to know that we are dealing with an email
address in this specific field.
To do this, click on the field in the form editor. In the right hand side menu you will find a dropdown menu called
"Mautic Property Type". This dropdown will contain all the contact fields Mautic knows (including fields you have
created yourself in Mautic). Select "Contact: Email" in the dropdown and save the form.
Now Mautic knows that data submitted in this field must be treated as an email address. Let's have a look in Mautic and
see what it looks like. Navigate to the form in Mautic and click "Edit" in the top-right. Then navigate to the tab
"Fields".
It should show that the "Email" field has been linked to the contact property "Email".
That's it. You can do this for every field in the form.
Using Dynamic Content Elements
Dynamic content elements are content elemants that are hidden or shown based on the Mautic segment(s) a user is a
member of.
Before moving on to creating dynamic content elements we would first like to explain the structure and hierarchy of
the different objects associated with orchestrating dynamic content.
Mautic Segments
TYPO3 Personas
TYPO3 Dynamic Content Elements
Let's start with the Segments in Mautic. If you have used Mautic before, you should be familiar with segments. In short,
segments are groups of contacts/leads that have been created and/or filtered by the marketing logic defined
in your Mautic instance.
TYPO3 Personas are objects in TYPO3 that hold one or more Mautic segments. Personas can be seen as the "middle-man"
between Mautic segments and TYPO3 content elements. Content elements can be configured to only show for certain Personas.
This means the content elements are not directly tied to Mautic segments, but rather to a Persona. Which allows you
to effieciently configure groups of Segments and bind a content element to all of the immediately (via the Persona).
TYPO3 Dynamic Content Elements are content elements that are bound to one or more Personas. These content elements will
only show when the user is a member of one of these Personas.
Lets start creating one of these. First navigate to the List module and click the "Create record" button.
Select Marketing Automation -> Persona
Give your Persona a name and fill it in the title field. Now lets open the "Mautic" tab. It should look like the image below:
On the right we see a list of Mautic segments. This list comes directly from Mautic. If it is out of date, you can update
the list by clicking the refresh button right next to the list.
To add segments to your new Persona, simply click them. They should move into the list on the left. Repeat this with all
the segments you would like to add to this Persona. Then save the Persona. Our Persona is now ready.
Now we will go to the Page module. We are now going to add a Persona to a content element. Either create a new content element
or edit an already existing one.
Configure the content element to your liking. Once done, we will add the Persona. Go to the "Access" tab and scroll down.
There will be a section called "Limit to Targeting Personas". On the right we have all known Personas on the current page.
On the right we have the Personas bound to this content element. Once a content element is bound to a Persona (or more)
that content element will only show if the user is a member of (one of) the Persona(s). You can again click the Personas
in the right list, they will move to the left. Once you are happy with the configuration, save the content element.
Done. You have successfully created a content element that is shown/hidden based on information coming from Mautic!
Tagging
Assign tags to your contacts when the enter a page. Go into the settings of your page and choose the tab mautic.
If you already have some tags in your Mautic instance, you can synchronize them with TYPO3 by pressing the synchronize
Button. If you do not, just create a new tag on the fly and assign it to the page. The tag is automatically created in
Mautic, too.
Link Assets
You can link Mautic assets directly in TYPO3 using file relations or the link wizard. To start, you have to create a
new file storage within TYPO3. Open your TYPO3 backend and navigate to the list module, select the root page (pid = 0)
and add a new file storage. All you have to do is to select Mautic as driver and choose a name. We recommend to use
the processing folder of the TYPO3 default storage (e.g. fileadmin):
You can now link your assets:
About
This extension smoothly integrates Mautic into your TYPO3
instance. It allows you to create your own Mautic forms in TYPO3 or integrating the existing forms in your website.
Compatibility
You need access to an Mautic instance. We are currently supporting following TYPO3 versions:
Extension Version
TYPO3 v10 Support
TYPO3 v9 Support
TYPO3 v8 Support
4.x
🙋♂️
🙅♀️
🙅♀️
3.x
🙅♀️
🙋♂️
🙅♀️
2.x
🙅♀️
🙅♀️
🙋♂️
1.x
🙅♀️
🙅♀️
🙋♂️
.. scv-table:: Required Mautic Version
"4.x", "2.16.0"
"3.x", "2.14.2"
About Mautic
Mautic is a fully-featured marketing automation platform that enables organizations of all sizes to send multi-channel
communications at scale, and simultaneously personalize the experience for individual contacts. Mautic helps teams
gather important contact information, optimize and replicate campaigns, and ultimately, report on results. No other
solution compares to Mautic’s modern and flexible design which provides team members the freedom to move quickly and
adapt easily to changing business needs.
Contributing
You can contribute by making a pull request to the
master branch of the extension repository on GitHub. Or just
send us some beers 🍻...
Documentation
You are welcome to help improve this guide. Just click on "Edit on GitHub" on the top right to submit your change
request.
Changelog
This chapter provides an overview of changes. Take a deeper look on a version listed below, to see which bugs have been
fixed, which new features have been introduced, and what you should not use anymore.
We do plan a new major version 5 which will drop support for OAuth1. That new version will support TYPO3 versions
10 & 11 and Mautic 4. Since this is just an announcement we did not add any deprecated notices for the time beeing.
There will be a future release to include deprecation notices. Stay tuned.
Added
Added support for OAuth2, thus you can now choose between OAuth1 and OAuth2.
All Changes
This is a list of all changes in this release:
2021-09-13 [TASK] Do not break compatibility (Commit 2bc34d8 by Florian Wessels)
2021-09-13 [DOC] Update documentation (Commit 87a33ad by Florian Wessels)
2021-09-13 [TASK] Set version to 4.1.0-dev (Commit d5a42d8 by Florian Wessels)
2020-10-24 [BUGFIX] Initialize form persistence manager with all properties (Commit c0956f6 by Florian Wessels)
2021-09-13 [FEATURE] Introduce OAuth 2 Authorization (Commit 8a7b1a6 by yabid21)
2020-09-18 [TASK] Useuniqueclassnameswithinsvgfiles (Commit 3c793a4byFlorianWessels)
Copied!
Contributors
Following people have contributed to this release:
Yassine Abid
Florian Wessels
Thank you very much for your support. The next beer is on us! 🍻
Version 4.0.1 - 2020/06/03
This release is a regular maintenance release. It contains bugfixes only.
2020-06-03 [DOC] Add changelog for upcoming version (Commit ebb95f2 by Florian Wessels)
2020-06-03 [TASK] Add GitHub files (Commit acc5634 by Florian Wessels)
2020-06-03 [TASK] Adapt dependencies in ext_emconf file (Commit 20f1f78 by Florian Wessels)
2020-06-03 [TASK] Rename file (Commit 2f3080c by Florian Wessels)
2020-06-03 [BUGFIX] Adapt link to documentation (Commit e8cc977 by Florian Wessels)
2020-06-03 [TASK] Update dependencies (Commit 11f87d2 by Florian Wessels)
2020-05-04 [TASK] Set version to 4.0.1-dev (Commit 0f721f0 by Florian Wessels)
2020-05-04 [BUGFIX][DOC] Do not break layout (Commit d3775e9 by Florian Wessels)
Copied!
Version 4.0.0 - 2020/05/04
This is a feature release. Be careful when upgrading to this version as it contains breaking changes regarding the OAuth
authentication workflow. Please check your connection after upgrading to this version when using the forms, tags or
segments feature. Besides these points, this release also includes several bug fixes and new features like the TYPO3
v10 support and the linking to Mautic assets directly from TYPO3's link wizard.
2019-08-04 [RELEASE] Release of version 2.1.1 (Commit 9a182fa by Florian Wessels)
2019-06-05 [TASK] Set versions to 2.x (Commit af4bd92 by Woeler)
2019-06-05 [TASK] Add documentation (Commit 00fdfc8 by Woeler)
2019-05-24 [BUGFIX] Prevent boolean return value (Commit 7b1c516 by Florian Wessels)
2019-04-09 [TASK] Add missing license (Commit 62343fd by Woeler)
2019-04-08 [BUGFIX] Do not usesynclistpropertywhenthereisnoleadfield (Commit 9401346 byFlorianWessels)
Copied!
Version 2.1.0 - 2019/03/05
This release contains several bug fixes and introduces two features.
Version 2.0.0 is a complete overhaul of the Mautic extension for TYPO3. It includes many new features such as dynamic
content, OAuth and a stable sync with Mautic forms.
