What will we be doing?

Our goal during this sprint is to take a fresh look at key use cases and workflows, identify opportunities for improvement, review existing issue reports, proposed code changes (pull requests) on GitHub, and ideas from the Mautic forums.

Based on all this input, we aren’t just going to be prioritizing things – we’ll actually be implementing things! This is a great opportunity to join us in working to improve Mautic across many areas.

Who should join?

We’re hoping for 20-30 people to support the effort in Prague. Skills from all angles are needed, mainly:

• Experienced Mautic users: your insights into user experience are invaluable.
• Mautic developers: your coding skills are crucial for implementation.
• Anyone else! Marketing, design, documentation, testing – any perspective is welcome.

If you’ve never attended a Mautic event (and it’s geographically feasible for you to attend) this is the perfect place to get started!

Event details

• Start: Wednesday, July 9th, 12:00 AM CEST (no problem if you arrive later)
• End: Thursday, July 10th evening (most will stay for the night)
• Location: Impact Hub Praha D10, Drtinova 557/10, Smíchov, 150 00 Praha-Praha 5, Czech Republic. View on Map (Railway station is about 20 minutes away).

Sign up & support

Ready to join us in Prague? Sign up for free here: Sign Up for the Sprint!

Can’t make it to Prague? You now have two options: 

1. You can still help! We appreciate any contribution, big or small, to help cover event costs: Sponsor the Sprint (ideally €100,- or as much has you can)
2. You can attend remotely. As much as we would love to see you in person, we also would love to see you attend remotely and participate in the community sprint from the comfort of your (hopefully) cosy home.  

Shoutout

Let’s not forget to give a warm shoutout to the lovely people over at Impact Hub for giving us a nice NGO discount to run our sprint at their venue.  We can’t even begin to tell you how much we appreciate that.

Your feedback is important

Even if you can’t attend, please help us make the sprint a success by giving us your feedback / ideas on the most valuable quality improvements for Mautic: Give Us Your Quality Feedback!

We’re excited to work together to shape the future of Mautic!

We’re thrilled to announce a newly updated integration plugin with Pipedrive CRM. This replaces the current core plugin which is to be removed in Mautic 5.0. 

The new plugin represents a major change to cover the API deprecation announced by Pipedrive in November, 2022. It allows for seamless integration and opens up new opportunities for our users, and has been written using the updated and more robust Integration Framework for Mautic plugin development

Pipedrive original communication

Most Pipedrive API users should have been receiving the following original message since the API started to drop requests in December 2022.

We have detected that one of your API integrations is still using endpoint(s) GET /persons/find, which has/have been deprecated since March 31, 2021.

We will deactivate these endpoints in three intermediary stages over the next two months.

* Starting from December 13, 2022, 10% of requests to the deprecated endpoints will start failing.
* Starting from January 5, 2023, 50% of requests to the deprecated endpoints will start failing.
* Starting from February 6, 2023, the endpoints will no longer work at all.

Impact on current core Mautic plugin 

Mautic Community users currently using the existing plugin will have seen the integration stop working from February 6, 2023 concerning the synchronization of contacts (persons).

Knowing this, the Mautic Community Product Team has decided to remove the existing plugin from Mautic core on the next major version, Mautic 5.

How to install the new plugin

To install the plugin, follow the instructions on the public repository holding the code which is made available under an Open Source license. You will find two options to install the plugin; using composer, or downloading and installing manually the plugin in your Mautic installation.

Migration: the process we suggest you to follow

1. Prepare and configure your new plugin
2. Update your forms, campaigns and point trigger actions
3. Disable the old plugin
4. Fully enable the new plugin

Prepare and configure your new plugin

You can find the Plugin configurations under Configuration > Plugins > Pipedrive 2 plugin. This is the new plugin you will use for your Pipedrive integration.

Follow the instructions from the readme of the plugin to enable the features you like and authenticate your Pipedrive account.

Update your forms, campaigns and point trigger

Once your plugin is installed and enabled, if you use any form, campaign or point trigger to push contacts to your Pipedrive integration, you have to delete the previous actions and use the new action provided by the new plugin.

Disable old plugin

It’s time to say goodbye to the old integration

1. In Configuration > Plugins > Pipedrive, disable the plugin
2. In your Pipedrive configuration, delete any Webhook actions configured
3. Remove the commands (CRON jobs) of the old plugin

Fully enable new plugin

The show must go on! ?

After setting up the plugin configuration in the user interface, you must enable the commands (CRON job) according to the synchronization you expect.

Get news about this integration and/or contribute to it!

If you’re interested in learning more about the Mautic Pipedrive plugin and how it might evolve over time, you should ‘Star’ or ‘Watch’ the Github repository containing the plugin: https://github.com/Webmecanik/mautic-pipedrive-bundle.

You can also contribute to it by reporting Issues, suggest your improvements by proposing Pull Requests to it, or Sponsor the project. Maintainers will consider your highly valuable contributions.

Thank you for your continued support and we look forward to bringing you more exciting updates in the future.

Who is behind the Mautic Pipedrive Plugin

Webmecanik is a Mautic Community partner based in France. The Mautic Pipedrive Plugin is 100% compatible with a standard Mautic Community installation.

The second main community contributor for the last 5 years (see Community contributions reports for 2020, 2021, 2022), you can follow them on Linkedin and read more of their marketing automation tips on Webmecanik‘s blog.

Norman Pracht is the General Manager at Webmecanik and Mautic Community Product Team Leader.

If you love Mautic and use Trello, keep on reading as we talk about connecting the systems with this plugin. And at the same time you will connect sales and marketing as well. Manage your Mautic contacts in a clear and easy way – on a Trello board. Create a card for each contact and have your contacts’ information right at your fingertips. 

Are you new to Trello?

Trello is a Kanban board-centric easy-to-use project management and collaboration tool. The tool works like sticky notes on a whiteboard – in a very advanced manner. 

You can organize teams, projects, workflows and much more by simply dragging and dropping cards on your board. Many teams use Trello every day to keep everyone in the loop, help them stay organized and don’t miss a thing. 

Get started and create contacts in Trello as cards directly from Mautic

When you work through your leads in Mautic you can directly create a Trello card without leaving Mautic with the Mautic-Trello plugin and its Trello power up (plugin) counterpart.

How does this work? Mautic users can download it here for free in GitHub – this function is pre-installed for Aivie customers. After the installation, you will find the new function “Create Trello Card” in your menu for each lead. Just choose the name of the card, the list you would like to add the card to, and a due date.

Install and use the Trello Power Up

If you wish to access Mautic from within Trello, you will need to install the Trello Power Up. Power Ups are like plugins in Trello and can be installed with a click. In case you hit an issue anyway, our tutorial to install the plugin will help you out.

3 benefits of connecting Mautic and Trello

After you install the Power Up in Trello and the plugin in Mautic, you can link your Mautic contacts to a card in Trello (or create a new contact) and then view important details directly in Trello. 

Here are some advantages and some important use cases of the Aivie Trello Power Up: 

1. Add reminders and tasks to your contacts

You can add due dates directly within Mautic – without leaving it. Next time you check your Trello board, the contacts and all the information is simply there.

How we use it: When we see the need for a personal followup, we create a Trello card from Mautic and set a date. Then, every week we go through the contacts on the Trello board, filter for the due date, and initiate calls. So we always know when it’s the right time to reach out.

2. Build a sales funnel in Trello

The principle of Trello is to move cards forward as the tasks progress. The task here is: sales!… and everything that leads to it and beyond. 

You can have Trello lists for the more advanced stages of the sales funnel. From when a contact engages first in a personal conversation with your business to the commitment to a deal, and beyond the sale. Whether your business is in B2B or B2C does not matter, although we do recommend to select your prospects when you are in a high volume Ecommerce business to not overwhelm your Trello board. 

After each conversion, the card is moved forward. This way, you can see the sales funnel at a glance and have control over the most important contacts.

This Screenshot shows you how it might look to visualize your sales funnel on Trello. And with this new Mautic-Trello Plugin you can populate this board automatically.

3. See your relevant contact details in Trello

When you link a Mautic contact to a Trello card you will see the stage, points, tags and the last time they were active directly on the card. This way, your sales or marketing team has more information at the most convenient place at any point in time.

When you combine Trello Power Up with the Mautic-Trello plugin, you can also create cards directly from Mautic. Every card is created for one contact and, of course, shows the contact’s name in the title. 

How we use it: We at Aivie do lead scoring with Mautic using points and stages. This information is also displayed on the Trello card. This way, we can see immediately how interested one contact is in working with us. And maybe now is the right time to contact them again.

Who is behind the Mautic-Trello Plugin

Aivie is a Mautic community partner based in Switzerland. The Mautic-Trello Plugin and Power Up of the same name is 100% compatible with a standard Mautic instance.

Author

Adrian Schimpf is CEO and Head of Product of Aivie, a marketing automation tool from Switzerland for Europe. He designs digital channels and customer interactions with automation, AI and plugins.

He has 20 years of experience at the interface between customers and IT. Most recently as a product manager at Swisscom, previously in various roles at SMEs, start-ups and agencies. Software developer, user experience consultant, project manager, among others.

Adrian Schimpf is a CEO and Head of Product at Aivie. You can follow him on Twitter and read more of his marketing automation tips on Aivie’s blog.

Read more about how you can set your own rules to handle bounces and lead scoring, in addition to contacting customers based on their behavior, without the need to create campaigns or segments.

Marketing automation requires up-to-date contacts and the integration between Mautic and n8n is the missing link to get data from the most diverse systems and enrich Mautic. 

In this article, I will detail how n8n version 0.165.0 brings new features so you can manipulate Mautic in a simple and easy way.

This is my second contribution to Mautic node improvements in n8n and I am very happy to be able to collaborate with both Mautic and n8n communities. You can learn more about how to contribute in our Community and Get Involved sections.

Send emails directly to your leads

How many times have you thought about sending a specific email to a contact through some external action like an e-commerce order, subscription expiry or an alert using Mautic?

On n8n’s Mautic node you will find the action “Send e-mail”, which requests the contact ID and the email ID (campaign type). As soon as you run node, your contact will be sent the email, without using a campaign or broadcast.

In this way, the submission and engagement are recorded in the contact’s timeline.

Create your own rules to handle bounces

Mautic takes hard-bounces and applies the “Do Not Contact” flag to the corresponding contacts, but many companies take soft-bounce with a slightly different approach.

With n8n, all you need to do is receive bounce notifications for a webhook, perform some processing or validations in alignment with your policies, add notes and choose the most appropriate “Do not Contact” level.

You are free to choose the best way to handle hard-bounces, soft-bounces and complaints.

Lead Score like you’ve never seen

n8n also allows you to add or subtract points from a contact, opening doors to the most diverse external situations that can contribute to your Lead Score strategy.

Imagine that every time a contact makes a purchase on your e-commerce website, you can add a point to them – in addition to adding a comment, making it easier to identify them on the timeline

Handle your contacts with the n8n

The integration of Mautic within the n8n platform allows you to perform the most diverse actions:

• Create or Update Contacts
• Add Tags to Contacts
• Add or Remove a Contact from a Segment
• Add or Remove a Contact from a Campaign
• Add or Remove “Do Not Contact” from a contact
• Directly send a Campaign-type email to a contact
• Add or Subtract Points from a Contact

n8n is Mautic’s best open source partner for connecting external systems that can perform actions inside your Mautic.

You can plug Mautic into major CRM, email validation systems, contact enrichment, spreadsheets, SQL and NoSQL databases, receive data via webhooks or API and much more.

If you are thinking of connecting your Mautic to an external system, be sure to look for the n8n. It’s a free and open source system that you can run on your own server.

Luiz Eduardo de Oliveira Fonseca is a Devops and cofounder of Powertic. He is also with the Mautic Meetup São Paulo (Brazil) and the n8n Meetup São Paulo (Brasil). You can follow him on Twitter: @luizeof.

Many organizations are moving toward a GitOps-based approach to managing software, and the way that Mautic was configured from the Composer perspective was previously suboptimal for organizations who need to manage Mautic installation and deployment with Composer.

This also made it very difficult to apply patches – whether from Mautic or from the organization themselves – in a way that is commonly accepted as best practice.

Two other Strategic Initiatives – Mautic Next Generation and the Mautic Marketplace – depend on significant changes to our architecture for being able to decouple plugins and themes and also have them managed independently.

We announced the Composer Initiative as a Strategic Initiative in November 2020 and work started to determine how to move Mautic toward a more future-friendly configuration.

What we have done

This project has been led by Nick Veenhof from Dropsolid and we are extremely grateful for his knowledge and time in making this initiative a reality. Also, big thanks to Rahul Shinde, John Linhart, and Dennis Ameling for their support in testing, reviewing, and suggesting improvements; and to the Drupal project from which we have taken much inspiration!

Three things were kept in mind when deciding how to execute this project:

• Making the developer experience as smooth as possible
• Enabling a phased approach to decoupling from core
• Following established best practices

There are several key things to be aware of now that we have mostly completed this project.

1. While we have ‘technically’ decoupled the app directory, all plugins, and themes into separate repositories, you will still find them located in the original folders in github.com/mautic/mautic at this stage:
   1. This approach allows for a smooth development process as all the files and folders that you see in Mautic are in the same repository.
   2. In the future, we may consider removing some plugins that are not widely used from Core and enabling users to selectively install them via the marketplace.
   3. Those plugins will, at that point, become maintained by a separate Tiger Team.
   4. The mirror repositories are read-only, pull requests should be made against https://github.com/mautic/mautic, not the mirrors – you will receive a reply from the bot if you attempt to make a PR against a mirror.
2. Whenever a pull request is made which touches any of these files, the changes are automatically pushed down to the read-only mirror repositories thanks to the amazing tool SubTreeSplit by Tobias Nyholm.
3. We now have a composer.json file in /app (as well as in all plugin and theme directories) which is used to build Mautic when installing with Composer.
4. We now have the Recommended Project repository – https://github.com/mautic/recommended-project and the scaffold – https://github.com/mautic/core-composer-scaffold which allows you to manage dependencies and move files outside the web root directory if you wish to do so.

What happens when you build Mautic

As before, you can still pull down Mautic and use the composer install command to install dependencies. This will now be much faster thanks to the upgrade to Composer 2.

You will notice that we now have a requirement on mautic/core-lib – this is the /app folder. We also now pull in all of the plugins and themes individually however in this first phase, we are telling Composer to use the files which it finds in mautic/mautic rather than looking elsewhere for the files – this is a precursor to being able to move some of this outside of the core.

We have also added some configuration settings and we set the correct paths for the different types of resources we are pulling in – the app directory, plugins, and themes.

Within the app folder, we have an additional composer.json file (in fact, all plugins and themes also now have a composer.json file) which has some settings relating to the scaffolding.

How do you use the recommended project?

This recommended project template provides a starter kit for managing your Mautic dependencies with Composer.

Usage

Note: The instructions below refer to the global composer installation. You might need to replace composer with php composer.phar (or similar) for your setup.

After that you can create the project:

composer create-project mautic/recommended-project:4.x-dev some-dir --no-interaction

With composer require … you can download new dependencies to your installation.

cd some-dir
composer require mautic/mautic-saelos-bundle:~2.0

The composer create-project command passes ownership of all files to the project that is created. You should create a new git repository, and commit all files not excluded by the .gitignore file.

What does the template do?

When installing the given composer.json some tasks are taken care of:

• Mautic will be installed in the public-directory.
• Autoloader is implemented to use the generated composer autoloader in vendor/autoload.php, instead of the one provided by Mautic (public/vendor/autoload.php).
• Plugins (packages of type mautic-plugin) will be placed in public/plugins/
• Themes (packages of type mautic-theme) will be placed in public/themes/
• Creates public/media directory.
• Creates environment variables based on your .env file. See .env.example.

Updating Mautic Core

This project will attempt to keep all of your Mautic Core files up-to-date; the project mautic/core-composer-scaffold is used to ensure that your scaffold files are updated every time mautic/core is updated. If you customize any of the “scaffolding” files (commonly .htaccess), you may need to merge conflicts if any of your modified files are updated in a new release of Mautic core.

Follow the steps below to update your core files.

1. Run composer update mautic/core –with-dependencies to update Mautic Core and its dependencies.
2. Run git diff to determine if any of the scaffolding files have changed. Review the files for any changes and restore any customizations to .htaccess or others.
3. Commit everything all together in a single commit, so the public will remain in sync with the core when checking out branches or running git bisect.
4. In the event that there are non-trivial conflicts in step 2, you may wish to perform these steps on a branch, and use git merge to combine the updated core files with your customized files. This facilitates the use of a three-way merge tool such as kdiff3. This setup is not necessary if your changes are simple; keeping all of your modifications at the beginning or end of the file is a good strategy to keep merges easy.

FAQs

Should I commit the contributed plugins I download?

Composer recommends no. They provide arguments against but also workarounds if a project decides to do it anyway.

Should I commit the scaffolding files?

The Mautic Composer Scaffold plugin can download the scaffold files (like index.php, .htaccess, …) to the public/ directory of your project. If you have not customized those files you could choose to not check them into your version control system (e.g. git). If that is the case for your project it might be convenient to automatically run the mautic-scaffold plugin after every install or update of your project. You can achieve that by registering @composer mautic:scaffold as post-install and post-update command in your composer.json:

"scripts": {
"post-install-cmd": [
"@composer mautic:scaffold",
"..."
],
"post-update-cmd": [
"@composer mautic:scaffold",
"..."
]
},

How can I apply patches to downloaded plugins?

If you need to apply patches (depending on the project being modified, a pull request is often a better solution), you can do so with the composer-patches plugin.

To add a patch to Mautic plugin foobar insert the patches section in the extra section of composer.json:

"extra": {
"patches": {
"mautic/foobar": {
"Patch description": "URL or local path to patch"
}
}
}

How do I specify a PHP version?

This project supports PHP 7.4 as the minimum version, however, it’s possible that a composer update will upgrade some package that will then require PHP 7+ or 8+.

To prevent this you can add this code to specify the PHP version you want to use in the config section of composer.json:

"config": {
"sort-packages": true,
"platform": {
"php": "7.4"
}
},

Using a “staging” server – a replica of your production Mautic instance – to test whether an update is successful before applying it to production, is a best practice to prevent unexpected errors with your live marketing database.

In this article, you will learn how to clone your Mautic installation to a staging server and manually perform a Mautic update to the latest stable version.

The article assumes that you are running Mautic on a VPS or dedicated server (not shared hosting), where you have root access to the Linux command line to update Mautic. It also assumes that the MySQL database is on the same server as Mautic. Before getting started, make sure you have access to the following credentials handy:

• Root access to the Mautic server (root password and/or SSH key)
• Username and password to the provider dashboard (e.g. Amazon AWS, DigitalOcean, Linode, etc.) where your Mautic instance is hosted
• Access to where your DNS settings are managed. Usually your domain registrar (e.g. GoDaddy, NameCheap, etc.) – if you are using the registrar’s DNS service (e.g. nsXX.domaincontrol.com), or hosting company – if you have pointed your domain to your hosting provider’s nameservers.

If your hosting provider offers a “snapshot” or “image” option that is the simplest way to clone Mautic along with all of its dependencies (e.g. PHP and its related modules). This ensures that you are testing against the same web server and PHP versions on staging as in production. This way you can accurately see how the new version of Mautic would behave according to your specific server configuration.

Create a production server snapshot

Amazon AWS refers to this functionality as creating an EBS snapshot of the root volume of your EC2 instance (virtual server) running Mautic. Other providers, such as DigitalOcean call this taking a snapshot image of your Mautic Droplet. Either way, the hosting provider should allow you to launch a new virtual server based on the snapshot that is a clone of your original server. Prior to taking the snapshot however, you should ensure that you have disabled cron jobs by commenting out the Mautic-related cron jobs in the user-specific cron tab:

crontab -u www-data -e

or the system-wide cron tab

/etc/crontab

To comment out a crontab entry, simply add the # symbol at the beginning of the line.

This ensures that the staging server will not actually send out segment emails or trigger actions on published campaigns once it is switched on, which would be duplicated on your live server as well. After taking the snapshot you can safely remove the # symbols to re-enable cron jobs on your live instance.

Create a staging server based on the snapshot

Next, deploy the staging server using the snapshot that you have previously taken. The process for this will slightly vary based on the provider.

In AWS you would create a new EBS volume from the snapshot, then attach it as the root volume to a separate EC2 instance.

In DigitalOcean, you would create a new droplet and select the snapshot as the image that should be used as the droplet’s boot disk.

Point a separate ‘A’ record at the staging server

Note down the public IP address of the new, staging server, and for Amazon AWS, ensure that it has been added to a security group that allows inbound traffic on HTTP (80) and HTTPS (443) to the server.

From your domain registrar or managed DNS service (e.g. Route 53, Dyn, No-IP), create a new A record that points a staging subdomain (e.g. staging-mautic.example.com) at the public IP address of the staging server.

If you can configure the TTL (time to live) value you should set it to as low as possible (e.g. 300 seconds) so that the new record propagates across the Internet as rapidly as possible.

Modify staging server (e.g. Apache) configuration

After booting up the staging server, you’re still not quite done yet, because the new server is still listening for HTTP(S) requests from the domain or subdomain of the production instance. You need to change the VirtualHost URL in Apache or Nginx, as well as the site_url value in /path/to/mautic/app/config/local.php.

Most Mautic installations in the wild are running Apache. If you are using Ubuntu, your Apache configuration file is either located in /etc/apache2/sites-available or /etc/apache2/conf.d. If you are using CentOS or RHEL, your config file is located in /etc/httpd/conf.d by default.

Find the configuration file(s) with the ServerName value corresponding to your production Mautic URL and modify any instances of ServerName to the subdomain that you will be using for testing. If you are running Mautic on HTTPS, you should make sure to modify ServerName for both the port 80 and port 443 VirtualHost blocks. Depending on how it was set up, these VirtualHost blocks may be contained in two separate Apache config files.

If using HTTPS, also make sure to modify SSLCertificateFile, SSLCertificateKeyFile, and SSLCertificateChainFile values in the port 443 VirtualHost to refer to a path containing a valid SSL certificate for the staging subdomain.

If using Let’s Encrypt to obtain certificates, the directory structure is /etc/letsencrypt/live/subdomain.example.com/. Refer to the Let’s Encrypt Certbot documentation for instructions how to obtain a valid certificate for the staging subdomain.

Also, if you set up any 301 or 302 redirects in your VirtualHost files to redirect HTTP to HTTPS, remember to update those redirects with the staging subdomain as well.

ServerName staging-mautic.example.com

…

ServerName staging-mautic.example.com

…

SSLCertificateFile /etc/letsencrypt/live/staging-mautic.example.com/cert.pem

SSLCertificateKeyFile /etc/letsencrypt/live/staging-mautic.example.com/privkey.pem

SSLCertificateChainFile /etc/letsencrypt/live/staging-mautic.example.com/chain.pem

After making all of the changes above, restart the Apache server with the following commands.

Ubuntu: sudo service apache2 reload

CentOS: sudo systemctl restart httpd

Modify site_url in Mautic config on staging server

Using a text editor, change the site_url value in /path/to/mautic/app/config/local.php to reflect the staging site URL.  To prevent permissions errors, you should modify this file as the web server user (www-data on Ubuntu, apache on CentOS/RHEL) using the command (replacing username in both cases below with the appropriate web server user):

sudo -u username nano /path/to/mautic/app/config/local.php

Next, clear the Mautic cache so that the staging site URL takes effect.

sudo -u username php /path/to/mautic/app/console cache:clear

Test the Mautic update on the staging server

On the staging server, run the following commands to perform a Mautic update to the latest stable version, and bring the database schema into alignment with the latest version. If prompted whether to proceed at the doctrine migration or schema update steps, respond ‘y’ for yes (replacing user in all cases below with the appropriate web server user). 

Note: if you are updating to a release other than Stable (e.g. beta release) you will need to change the stability setting in the /path/to/mautic/app/config/local.php file.  Look for ‘update_stability’ and change to the relevant setting (e.g. ‘update_stability’ => ‘beta’).  If you haven’t previously saved the configuration settings in Mautic (settings > configuration) you may not see these settings until you save in the user interface for the first time.

sudo -u username php /path/to/mautic/app/console mautic:update:find 
sudo -u username php /path/to/mautic/app/console mautic:update:apply 
sudo -u username php /path/to/mautic/app/console doctrine:migration:status 
sudo -u username php /path/to/mautic/app/console doctrine:migration:migrate 
sudo -u username php /path/to/mautic/app/console doctrine:schema:update --dump-sql 
sudo -u username php /path/to/mautic/app/console doctrine:schema:update --force 
sudo -u username php /path/to/mautic/app/console cache:clear

Try the latest version of Mautic on the staging server

If you got the message in the console that Mautic has been updated to the latest version and you cleared the cache one last time after all of the commands in the previous step, you’re ready to test the latest version of Mautic.

Visit the staging Mautic URL in your web browser, login with your existing credentials, and verify the bottom right hand corner of the dashboard reflects a newer version of Mautic.

You should also make sure that no server errors are displayed by clicking on the “gear” icon in the top right-hand corner of the dashboard, then selecting System Info. Then, navigate to Error Log to ensure nothing unexpected is displayed there.

If you can navigate around the pages of the Mautic dashboard and check that features such as the visual editor are working properly, you may be ready to attempt an upgrade on your production server – after taking a backup, of course.

If you wanted to re-enable cron jobs (by uncommenting the lines in the crontab file) on the staging server to see the outgoing emails that would be generated by Mautic with the new version running in production, you would need to modify the email gateway settings to a test SMTP server such as MailHog, to prevent any live emails from actually being deployed.  

Please note this does not capture other channels such as push notification, browser notifications and text messages.

Otherwise, if there are errors, consider visiting the Mautic Community Forum for advice and troubleshooting tips from other community members, or hiring a Mautic support specialist or consultant to repair any server configuration issues before attempting the update on your live instance.

In this guide we will show you how to set up a local development environment for Mautic, using DDEV.

Installing Docker and DDEV

Before we can get started you will need to install Docker and Docker Compose. You can find documentation on how to correctly do this here.

Once those are installed we can continue with installing DDEV. You can find installation instructions for Linux, MacOS and Windows here.

Installing Mautic

Clone the Mautic repository into a folder of your choice. Once that is done make sure to install the Composer dependencies with composer install.

Starting DDEV and configuring Mautic

Use the command line and navigate to the root of your Mautic installation. Once there, run 

ddev config

It will ask you for a project name – you can leave it at the default, or give it a custom name. This is really up to you. For the purposes of this example, we will name this project mautic.

Next it will ask for the docroot of the project.

Since the index.php of Mautic is located in the root folder of the project, we can just go with the default value. Simply press enter.

After this it will ask for the project type. Enter php and hit enter again.

Everything should now be configured. We just need to change one more thing! Go to .ddev/config.yaml and you’ll find something similar to:

APIVersion: v1.13.1
name: demodir
type: php
docroot: ""
php_version: "7.3"
webserver_type: nginx-fpm
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
nfs_mount_enabled: false
provider: default
use_dns_when_possible: true
timezone: ""

… change the webserver type to the following:

webserver_type: apache-fpm

… add the following row (make sure to replace 7.3 with whichever PHP version you’re using!):

webimage_extra_packages: [php7.3-imap]

… and change the timezone to whichever timezone you’re in, for example:

timezone: "Europe/Amsterdam"

… you’ll have the following config.yaml file then:

APIVersion: v1.13.1
name: mautic
type: php
docroot: ""
php_version: "7.3"
webserver_type: apache-cgi
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
nfs_mount_enabled: false
provider: default
use_dns_when_possible: true
timezone: "Europe/Amsterdam"
webimage_extra_packages: [php7.3-imap]

Note: if you have Apache2 or nginx installed, and they are currently using port 80, ensure that you shut them down or change their ports before starting the DDEV instance. If you do not follow this step, starting will fail with an error message telling you that port 80 is already in use.

You can start DDEV by running 

ddev start 

on the command line. 

If this is your first DDEV instance this can take a bit of time to initialise, as it will need to pull all the containers. 

If you cloned Mautic from GitHub, you need to run composer install in order to get started. Run

ddev ssh
composer install

… and you should be good to go.

Once started you will find your project at mautic.ddev.site (in case you used a different project name it will be yourprojectname.ddev.site).

Navigating there in the browser should bring up the Mautic installation. Make sure that during the installation you use the following settings:

• Database port: 3306
• Database host: db
• Database name: db
• Database user: db
• Database password: db

You can now finish the installation process. Your local Mautic instance should be up and running!

To stop the containers, simply run 

ddev stop 

on the command line.

Opening Mautic’s development environment (index_dev.php)

Mautic has a development environment (index_dev.php) which shows a profiler toolbar at the bottom, shows more error details, and caches less (so you have to clear your cache less often). 

The only downside is that the development environment is designed to work on localhost only. Since DDEV uses Docker, which has a slightly different networking stack, we need to make a small change in the code to get index_dev.php to work on DDEV.

Open app/middlewares/Dev/IpRestrictMiddleware.php and replace this code snippet:

    /**
     * This check prevents access to debug front controllers
     * that are deployed by accident to production servers.
     *
     * {@inheritdoc}
     */
    public function handle(Request $request, $type = self::MASTER_REQUEST, $catch = true)
    {
        if (in_array($request->getClientIp(), $this->allowedIps)) {
            return $this->app->handle($request, $type, $catch);
        }

        return new Response('You are not allowed to access this file.', 403);
    }

… with this one:

/**
     * This check prevents access to debug front controllers
     * that are deployed by accident to production servers.
     *
     * {@inheritdoc}
     */
    public function handle(Request $request, $type = self::MASTER_REQUEST, $catch = true)
    {
        return $this->app->handle($request, $type, $catch);
    }

 That way, we bypass the IP restriction middleware (otherwise you’ll get an error “You are not allowed to access this file” when trying to access index_dev.php).

Now you should be able to open index_dev.php in your DDEV environment

Running Mautic CLI commands in DDEV

You can run Mautic CLI commands (like clearing cache) as follows:

ddev ssh

Then you can run CLI commands, for example:

bin/console cache:clear --env=dev
bin/console mautic:campaigns:update
etc.

Using MailHog to catch emails in DDEV

(update: MailHog is no longer available as an option)

Run

ddev describe

And it’ll show you the following at the bottom (example):

Other Services
--------------
MailHog:        http://mautic.ddev.site:8025
phpMyAdmin:     http://mautic.ddev.site:8036

You can use MailHog to catch all emails sent by Mautic (without having to use an SMTP server). In your Mautic email configuration, go to Email Settings and select “Other SMTP server”, then enter “localhost” and use port 1025. All emails will end up in MailHog.

 

Further useful DDEV tips and tricks

Here you can find some other useful things you might need later along the way.

SSH into the container

To SSH in to the web container, simply use 

ddev ssh 

on the command line. 

If you wish to directly execute a command inside the container without going in with ssh first you can use 

ddev exec yourcommandhere

Using Xdebug

You can use 

ddev exec enable_xdebug

and 

ddev exec disable_xdebug

respectively to turn Xdebug on and off.

Changing PHP versions

Navigate to .ddev/config.yaml and edit the parameter called php_version. Once that is saved, run 

ddev restart

Using additional PHP modules

Once DDEV has been set up, you can find its configuration in the .ddev folder. 

If you need an extra PHP modules enabled such as IMAP for example, you can add it doing the following:

Navigate to .ddev/config.yaml and find the following row:

webimage_extra_packages: [php7.3-imap]

So, if you want to add the php-imap package, you would add the package as above. You can add additional packages by comma-separating them. 

Now save this file and restart your DDEV instance by running 

ddev restart

Using PHPMyAdmin

A DDEV instance comes with PHPMyAdmin by default. To find out the location of the PHPMyAdmin instance of the current project, use 

ddev describe

This will give you a lot of information about your containers, including the URL to the PHPMyAdmin instance.

Running PHPUNIT tests

In Mautic 5, you need to create .env.test.local file that will configure the test environment. Here is the content of this file:

# .env.test.local
DB_HOST=db
DB_PORT=3306
DB_NAME=test
DB_USER=db
DB_PASSWD=db
MAUTIC_DB_PREFIX=
MAUTIC_TABLE_PREFIX=
MAUTIC_ENV=test
MAUTIC_ADMIN_USERNAME=admin
MAUTIC_ADMIN_PASSWORD=Maut1cR0cks!

Make sure that the database with name “test” exists. You can add a prefix if you want.

Then run the tests with:

composer test

or if you want to run a specific test then you can filter for it:

composer test -- --filter specificTest

Are you looking for ways to make a backup of your Mautic instance fast, easy and automatic? This tutorial will give you the ability to backup your Mautic database to your Dropbox account.

You will need the following:

1. Dropbox account
2. Backup script
3. Cron job
4. Basic knowledge of the command line (PC) or terminal (Mac)

Step 1: Dropbox Account

Sign-in or create a brand new account with Dropbox then go to https://www.dropbox.com/developers/apps on your web browser, and create a new Dropbox app. Fill in the information of the new app as shown below, and enter the app name use a name that will be easy to you to remember in case you have more apps.

After you have created a new app, you will redirect to new windows and you will see a button with the text Generated access token click and copy the access token.

Step 2: Backup Script

The script we going to use is made by Andrea Fabrizi kudos to this guy. To use Dropbox backup script, download the script and make it executable.

wget https://raw.github.com/andreafabrizi/Dropbox-Uploader/master/dropbox_uploader.sh
chmod +x dropbox_uploader.sh

Then run the following command;

./dropbox_uploder.sh

Next it will ask you to insert the generated access token. Insert the provided token and confirm. To verify that you have established the connection with Dropbox, run the following command;

./dropbox_uploder.sh info

Doing so should display your Dropbox Information;

Dropbox Uploader v1.0
> Getting info... 
Name:		Joan Nin
UID:		dbid:XXXXXXXXXXXXXXXXXXXXXXX
Email:		your-email
Country:	DO

Now let’s create a shell script that will make the import of our database.

Create a new directory db-backup and a .sh file.

cd
mkdir db-backup
nano  dbdump.sh

And copy and paste this info to the dbdump.sh file you create.

#!/bin/bash
sudo mysqldump -uMYSQLUSER -pMYSQLDATABASE-PASSWORD DATABASENAME > 
/root/db-backup/mautic.sql
## THIS LINE UPLOADS THE MAUTIC.SQL FILE TO THE DROPBOX DIRECTORY BACKUP-Mautic
./dropbox_uploader.sh upload /root/db-backup/mautic.sql /BACKUP-Mautic
## Removed THIS WILL REMOVE THE MAUTIC.SQL FROM YOUR SERVER
rm -r /root/db-backup/mautic.sql
#END

NOTE: Replace the italics text with your information.
MYSQLUSER = sql user
MYSQLDATABASE-PASSWORD = SQL Password
DATABASENAME = the name of the database you use in Mautic

Step 3: Cron Job

Now create a cron job that will automate this task for you. Using the crontab from your server create the following line;

### MAUTIC BACKUP
27 3 */15 * * echo "`date -u` `/root/db-backup/dbdump.sh`" >> /root/db-backup/status.log 2>&1

This line will run the backup “At 03:27 on every 15th day-of-month.” you can replace the with the time you prefer. Also this will create a log file with the date that the cron job will run. I think this is a pretty neat option for backup/audit.

And that’s it. A simple, yet effective way to backup your Mautic instance.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

We want to thank our community for offering insight into how they work with Mautic. Do you have a different process for backing up your Mautic instance? Comment below and let us know!

Also, if you’re interested, here’s a quick tutorial video on using CPanel to add a cron job.

Have you ever wondered if you could track more than just visits via the Mautic tracking script? I know I did, and in this article I will show you how we can use URL’s to track anything you want.

The Basics

Before we start let’s have a look at these two URL examples. This one is without extra parameter:

https://mydomain.com/page/test/

And here we have the same URL with an extra parameter:

https://mydomain.com/page/test/?email=johndoe@company.com

If you use for example MailChimp or CampaignMonitor to send out marketing emails, consider using this technique. Simply add the email address as a parameter at the end of the URL.

In php one can catch this parameter simply with a:

$email = $_GET[‘email’];

And then proceed to use that parameter for processing. However, there is also a clever way of using the Mautic Javascript to track visitors on your site. Only some slight modifications can make it send off any lead field you want to Mautic.

Get Tracking with Mautic

Here is the default script:

<script>
    (function(w,d,t,u,n,a,m){w&#91;'MauticTrackingObject']=n;
        w&#91;n]=w&#91;n]||function(){(w&#91;n].q=w&#91;n].q||&#91;]).push(arguments)},a=d.createElement(t),
        m=d.getElementsByTagName(t)&#91;0];a.async=1;a.src=u;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://mydomain.com/mtc.js','mt');

    mt('send', 'pageview');
</script>

In short, what this does is simply pass along the identification parameters such as IP address and device fingerprint, together with the page the user is visiting. Now have a look at the script below.

<script>
	function getUrlParameter(name) {
		name = name.replace(/[[]/, '\[').replace(/[]]/, '\]');
		var regex = new RegExp('[\?&]' + name + '=([^&#]*)');
		var results = regex.exec(location.search);
		return results === null ? '' : decodeURIComponent(results[1].replace(/+/g, ' '));
	};
	
    (function(w,d,t,u,n,a,m){w['MauticTrackingObject']=n;
        w[n]=w[n]||function(){(w[n].q=w[n].q||[]).push(arguments)},a=d.createElement(t),
        m=d.getElementsByTagName(t)[0];a.async=1;a.src=u;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://domain.com/mtc.js','mt');

	var email  = getUrlParameter('e');

	if(email !== ''){
		mt('send', 'pageview', {email: email});
	} else {
		mt('send', 'pageview');
	}
</script>

The first function is used to extract a custom parameter from the URL. You can use this function for any parameter you want. Just make sure to pass the correct name to the function. In our case the name is ‘email’.

Below that you can see the default part of the Mautic tracking script. This is not relevant for us. It does what it needs to do, no need to concern us with that for now. Below that you will see a new variable is created with the name ‘email’ and the value it will get is the URL parameter for ‘email’. This means that this variable will hold the content of the URL that comes after ‘?email=’, which should be the email address of the user.

Then we have a short if-statement. This statement simply checks if the email parameter is filled or not. If it is not (which is the case for people that visit your website without a newsletter link) it will simply pass along the usual parameters. But if the email parameter is present it will pass along the usual parameters together with the email address.

Sending a Custom Parameter

You can send this along by adding ‘{email: email}’ to the mt method. Keep in mind that the first string identifies the field you want to pass along. In this case we want to pass along the email, but this could also be any other field like firstname or lastname, or even a custom field you have created. The second string or value is the actual value that needs to be passed along. Since we put the value we got from the URL in the ‘email’ parameter we just write ‘email’ to indicated that we want to pass along the string inside this value.

Lastly, make sure you enable public updating for the fields you want to track using this method. If public updating is not enabled Mautic will simply drop the field. You can do this by going to the ‘Custom fields’ section, then selecting the field you want and changing ‘publicly updatable’ from ‘no’ to ‘yes’.

Congratulations! You can now track custom parameters on your website!

The Possibilities Are Endless

Using the Mautic tracking script this way opens up new ways to identify your contacts. Think about the contact points you have and how you can use them to track different data sets.

If you are using mailing tools like Mailchimp or CampaignMonitor it is super easy to add the add extra parameters to your newsletters. Simply append the extra parameter to all the URL’s in your mail and there you go! In fact, you can use any contact network on point you have and use this methods for the parameters at hand.

Security

We should not forget that we are still handing personal data here. If you are appending sensitive data to a URL make sure you think about handling the data safely. What you could do is hash the parameters and de-hash them in your website before you send them off to Mautic. This way anyone who might come across the link cannot read or use the parameters.

Also make sure to use https, also known as SSL if possible. This is simply an extra layer of security added to the request the user will make. Best practice is to use both SSL for your website as well as the connection between your website and Mautic. You will see in the examples above the I have used https in the code, and not http.

And there you go. Now you know how to track custom parameters with the Mautic tracking script. I cannot wait to see what creative ways you all come up with to use this!