diff --git a/.all-contributorsrc b/.all-contributorsrc index a16e96ed..ab3259cf 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -104,6 +104,24 @@ "contributions": [ "doc" ] + }, + { + "login": "uadf", + "name": "CPweb", + "avatar_url": "https://avatars.githubusercontent.com/u/2785980?v=4", + "profile": "https://eglise.catholique.fr", + "contributions": [ + "review" + ] + }, + { + "login": "heebinho", + "name": "Renato Heeb", + "avatar_url": "https://avatars.githubusercontent.com/u/1469531?v=4", + "profile": "http://renatoheeb.com", + "contributions": [ + "doc" + ] } ], "contributorsPerLine": 7, diff --git a/.github/styles/Mautic/FeatureList.yml b/.github/styles/Mautic/FeatureList.yml index a0c65bd1..3b807561 100644 --- a/.github/styles/Mautic/FeatureList.yml +++ b/.github/styles/Mautic/FeatureList.yml @@ -49,6 +49,8 @@ swap: point groups: Point Groups plugin: Plugin plugins: Plugins + publish: Activate or Turn On + published: Active or Available report: Report reports: Reports role: Role @@ -59,7 +61,9 @@ swap: stages: Stages theme: Theme themes: Themes + unpublish: Deactivate or Turn Off + unpublished: Unavailable or Deactivated user: User users: Users webhook: Webhook - webhooks: Webhooks \ No newline at end of file + webhooks: Webhooks diff --git a/.github/styles/Vocab/Mautic/accept.txt b/.github/styles/config/vocabularies/Mautic/accept.txt similarity index 100% rename from .github/styles/Vocab/Mautic/accept.txt rename to .github/styles/config/vocabularies/Mautic/accept.txt diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index 6e08cd6e..a441dd8c 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -4,18 +4,26 @@ on: jobs: prose: - runs-on: ubuntu-latest + runs-on: ubuntu-22.04 # See https://github.com/errata-ai/vale-action/issues/128 before upgrading steps: - name: Checkout uses: actions/checkout@v4 with: fetch-depth: 0 + - uses: actions/setup-python@v4 + with: + python-version: '3.x' + cache: 'pip' + + - name: Install Python dependencies + run: pip3 install -r docs/requirements.txt + - name: Vale uses: errata-ai/vale-action@reviewdog with: # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience - version: 2.29.2 + version: 3.7.1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile index c345449f..e388e131 100644 --- a/.gitpod.Dockerfile +++ b/.gitpod.Dockerfile @@ -1,8 +1,7 @@ FROM python:3.11 -# Don't update to a higher version until this issue has been fixed: https://github.com/errata-ai/vale/issues/528 # Please keep version in sync with the version in .github/workflows/linting.yml for a consistent experience -ENV VALE_VERSION=2.29.2 +ENV VALE_VERSION=3.7.1 WORKDIR /workspace diff --git a/.gitpod.yml b/.gitpod.yml index 659fc24b..bdc51320 100644 --- a/.gitpod.yml +++ b/.gitpod.yml @@ -1,6 +1,5 @@ -# Since Gitpod doesn't support caching custom Dockerfiles yet, we temporarily -# use this once which has Python 3.9 and Vale preinstalled. -image: dennisameling/python-vale:latest +image: + file: .gitpod.Dockerfile tasks: - before: pip install -r docs/requirements.txt @@ -9,7 +8,7 @@ tasks: vscode: extensions: - ms-python.python - - lextudio.restructuredtext + - lextudio.restructuredtext@190.1.4 # See https://github.com/mautic/user-documentation/pull/334#issuecomment-2405922370 before upgrading. - trond-snekvik.simple-rst - errata-ai.vale-server - eamodio.gitlens \ No newline at end of file diff --git a/.vscode/settings.json b/.vscode/settings.json index 494ebbd1..7947ada3 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -5,5 +5,8 @@ "esbonio.sphinx.buildDir": "${workspaceFolder}/build", "esbonio.sphinx.confDir": "${workspaceFolder}/docs", "restructuredtext.pythonRecommendation.disabled": true, - "restructuredtext.preview.name": "sphinx" + "restructuredtext.preview.name": "sphinx", + "esbonio.sphinx.pythonCommand": "python3", + "esbonio.sphinx.buildCommand": "sphinx-build", + "esbonio.logging.level": "debug" } diff --git a/.well-known/funding-manifest-urls b/.well-known/funding-manifest-urls new file mode 100644 index 00000000..1f60e471 --- /dev/null +++ b/.well-known/funding-manifest-urls @@ -0,0 +1 @@ +https://github.com/mautic/mautic/blob/5.x/funding.json diff --git a/README.md b/README.md index 2150e23e..2794f7bf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![Documentation Status][RTD badge URL]][RTD URL] -[![All Contributors](https://img.shields.io/badge/all_contributors-11-orange.svg?style=flat-square)](#contributors-) +[![All Contributors](https://img.shields.io/badge/all_contributors-13-orange.svg?style=flat-square)](#contributors-) [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation) @@ -87,7 +87,7 @@ You can automatically build changes to rst files using a file watcher. [RST Cheatsheet]: [Sphinx Template]: [Sphinx Demo]: -[Vale]: +[Vale]: ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): @@ -111,6 +111,8 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d John Wick
John Wick
🐛 jagtapreshma
jagtapreshma
📖 Markus Heinilä
Markus Heinilä
📖 + CPweb
CPweb
👀 + Renato Heeb
Renato Heeb
📖 diff --git a/docs/campaigns/campaign_builder.rst b/docs/campaigns/campaign_builder.rst index 8c980c87..68c8403c 100644 --- a/docs/campaigns/campaign_builder.rst +++ b/docs/campaigns/campaign_builder.rst @@ -272,4 +272,34 @@ Actions and Decisions in Mautic require a :doc:`cron jobNon tracked link Unsubscribing ************* -Mautic has a built in means of allowing a Contact to unsubscribe from Email communication. You can insert the tokens ``{unsubscribe_text}`` or ``{unsubscribe_url}`` into your Email to have the text or the URL show at your desired location. The unsubscribe text token inserts a sentence with a link instructing the Contact to click to unsubscribe. +Mautic has a built in means of allowing a Contact to unsubscribe from Email communication. You can insert various tokens into your Email to provide unsubscribe options at your desired location: +- ``{unsubscribe_text}``: Inserts a sentence with a link instructing the Contact to click to unsubscribe. +- ``{unsubscribe_url}``: Inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not. +- ``{dnc_url}``: Inserts the URL to unsubscribe from all marketing messages when the preference center is activated. The unsubscribe URL token inserts the URL into your custom written instructions. @@ -255,7 +287,8 @@ For example: .. code-block:: html - Want to unsubscribe? + Manage your email preferences + Unsubscribe from all emails You can find the configuration of the unsubscribe text in the global settings. @@ -271,7 +304,7 @@ For example: View in your browser Bounce management -################# +***************** Mautic provides a feature which allows monitoring of IMAP accounts to detect bounced Emails and unsubscribe requests. @@ -284,7 +317,7 @@ Elastic Email, SparkPost, Mandrill, Mailjet, SendGrid and Amazon SES support Web .. vale off Monitored inbox configuration -***************************** +============================= .. vale on @@ -309,7 +342,7 @@ If sending mail through GMail, the Return Path of the Email is automatically rew If you select an Unsubscribe folder, Mautic also appends the Email as part of the "List-Unsubscribe" header. It then parses messages it finds in that folder and automatically unsubscribe the Contact. Webhook bounce management -************************* +========================= Since Mautic 5 all the Email transports use the same Webhook - sometimes called callback - URL: ``https://mautic.example.com/mailer/callback``. Please follow the documentation for the specific Email transport you've installed to get more information about the Webhook configuration. @@ -317,7 +350,7 @@ Since Mautic 5 all the Email transports use the same Webhook - sometimes called .. vale off Create a Segment with bounced Emails -************************************ +===================================== .. vale on @@ -370,4 +403,3 @@ This is because Mautic sends test Emails to a Mautic User and not to a Mautic Co Mautic Users can't unsubscribe and therefore the unsubscribe link looks like this: ``https://mautic.example.com/|URL|``. However, the link **does** work correctly when you send the Email to a Contact. Best practice is to create a Segment with a small number of Contacts to receive test Emails - for example, yourself - which ensures that you can fully test features such as unsubscribe behaviour. - diff --git a/docs/channels/focus_items.rst b/docs/channels/focus_items.rst index 54648637..bbec54b5 100644 --- a/docs/channels/focus_items.rst +++ b/docs/channels/focus_items.rst @@ -31,8 +31,6 @@ For each type of Focus Item, there are settings to configure which control the t :width: 400 :alt: Screenshot showing the engagement settings for Focus Items. -.. vale off - - **Animate** - When set to Yes, this applies a slide-in animation to the Focus Item. When set to No, the item appears without any kind of sliding motion. - **When to engage** - This setting controls the Focus Item shows. There are several options: - **Upon arrival** - As soon as a visitor lands on the page @@ -49,8 +47,7 @@ For each type of Focus Item, there are settings to configure which control the t - **Once per hour** - Show the Focus Item once every hour that the visitor is on your website - **Once per day** - Show the Focus Item once per day that the visitor is on your website - **Stop engaging after a conversion** - This option is only available for the types which track a conversion (Collect Data and Emphasize a Link). If set to Yes, the Focus Item no longer displays if the visitor has either submitted the Form (Collect Data type) or clicked on the link (Emphasize a Link type). - -.. vale on +- **Stop engaging after closing Focus** - This option is available for Focus Items and uses cookies. If set to Yes, the Focus Item no longer displays to the visitor after they have interacted with it, until they clear their cookies. Styles ====== @@ -157,13 +154,13 @@ When creating a new Focus Item, you can set the following fields: **Category** - Assign a Category to help you organize your Focus Items. -**Published** - Whether the Focus Item is available for use - published - or not available - unpublished +**Active** - Whether the Focus Item is available for use - active - or not available - inactive. .. vale off -**Publish at (date/time)** - This allows you to define the date and time at which this Text Message is available for sending to Contacts +**Activate at (date/time)** - This allows you to define the date and time at which this Text Message is available for sending to Contacts -**Unpublish at (date/time)** - This allows you to define the date and time at which this Text Message ceases to be available for sending to Contacts. +**Deactivate at (date/time)** - This allows you to define the date and time at which this Text Message ceases to be available for sending to Contacts. .. vale on @@ -198,7 +195,7 @@ You can use the menu on the sidebar to configure the Focus Item to your liking. Using Focus Items ***************** -Once you have created your Focus Item, you're ready to publish it to your website. If you're not quite ready for the Focus Item to go live but you need to get it set up on your website, you can set the Focus Item to Unpublished. +Once you have created your Focus Item, you're ready to activate it to your website. If you're not quite ready for the Focus Item to go live but you need to get it set up on your website, set the Focus Item to inactive. Deploying to a website ====================== diff --git a/docs/channels/images/emails/ab-translation-preview.png b/docs/channels/images/emails/ab-translation-preview.png new file mode 100644 index 00000000..97f82f60 Binary files /dev/null and b/docs/channels/images/emails/ab-translation-preview.png differ diff --git a/docs/channels/images/emails/email-excluding-segments.png b/docs/channels/images/emails/email-excluding-segments.png new file mode 100644 index 00000000..2835d84c Binary files /dev/null and b/docs/channels/images/emails/email-excluding-segments.png differ diff --git a/docs/channels/social_monitoring.rst b/docs/channels/social_monitoring.rst index 54417724..e977d25a 100644 --- a/docs/channels/social_monitoring.rst +++ b/docs/channels/social_monitoring.rst @@ -42,13 +42,13 @@ When selecting the Twitter Mention monitoring method, the following fields are a There are also the standard Mautic fields available: -**Published** - This allows you to set the published status of the Social Monitor. Unpublished Social Monitors won't collect new Contacts. +**Active** - This allows you to set the activation status of the Social Monitor. Deactivated Social Monitors won't collect new Contacts. .. vale off -**Publish at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. You might use this to coincide with an event, for example. +**Activate at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. You might use this to coincide with an event, for example. -**Unpublish at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. +**Deactivate at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. .. vale on @@ -69,13 +69,13 @@ When selecting the Twitter Hashtags monitoring method, the following fields are There are also the standard Mautic fields available: -**Published** - This allows you to set the published status of the Social Monitor. Unpublished Social Monitors won't collect new Contacts. +**Active** - This allows you to set the activation status of the Social Monitor. Deactivated Social Monitors won't collect new Contacts. .. vale off -**Publish at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. This might be used to coincide with an event, for example. +**Activate at (date/time)** - This allows you to define the date and time at which this Social Monitor is monitoring for new Contacts. This might be used to coincide with an event, for example. -**Unpublish at (date/time)** - This allows you to define the date and time at which this Social Monitor ceases to monitor for new Contacts. +**Deactivate at (date/time)** - This allows you to define the date and time at which this Social Monitor ceases to monitor for new Contacts. .. vale on diff --git a/docs/components/forms.rst b/docs/components/forms.rst index 8d472376..fc8e75ba 100644 --- a/docs/components/forms.rst +++ b/docs/components/forms.rst @@ -15,9 +15,9 @@ To create a new Form: #. Go to Components > Forms and click New #. Select the type of Form you wish to create * **Campaign Form** - Mautic allows you to trigger a Campaign with the submission of this type of Form. Campaign Forms have less actions directly associated with the Form submit actions - which happen immediately after Form submission - as most actions trigger as part of a Campaign workflow. - * **Standalone Form** - A more commonly used Form, this allows the execution of many submit actions immediately at the point of Form submission. + * **Standalone Form** - A more commonly used Form, this allows the execution of many submit actions immediately at the point of Form submission. -.. warning:: +.. warning:: Forms with a lot of submit actions - particularly when submitting to third party systems such as a Customer Relationship Management system - can have an impact on the Form submission time. This is especially the case if there are a lot of fields. Consider using a Campaign Form if you can wait for the cron job to trigger the actions. The following fields are available: @@ -38,11 +38,11 @@ The following fields are available: - **Kiosk mode** - If Yes, Mautic turns off tracking of Contacts created through the Form, so that the Form doesn't generate cookies or associate any IP address with the Contact record. Marketers may refer to this as 'data entry mode'. It's ideal for using at conferences or events where several Contacts may enter their information using the same device, as it prevents associating the activity on the device to Contacts. -- **Render style** - If Yes, the Form displays with the styling from either the selected Mautic Theme or the Attributes tab of the Form Fields. When No, the Form adopts the styling of where it's embedded. +- **Use Theme style** - If Yes, the Form displays with the styling from either the selected Mautic Theme or the Attributes tab of the Form Fields. When No, the Form adopts the styling of where it's embedded. - **Theme** - Select a Mautic Theme which has styling for a Form. This dictates the styling of the Form when added to an external website or Application if 'Render style' is Yes. -.. note:: +.. note:: Not all Themes include Form styling. Check the Features column on your Themes listing in the Theme Manager to see which Themes include styling for Forms. .. vale off @@ -85,7 +85,7 @@ To add a new field to your Form: - **Checkbox Group** - This field allows a visitor to select one or more options from a list using checkboxes. This field type can also provide a single checkbox - for example to gain consent to use cookies and send marketing Emails or other messages to the Contact. - .. note:: + .. note:: You can associate checkbox group fields with *boolean* and *select - multiple* fields, but not *select* fields. - **Date** - This field allows the visitor to select a date with a calendar picker. The formatting of the date applies the default setting in your Configuration. @@ -98,7 +98,7 @@ To add a new field to your Form: - **File** - This allows visitors to upload a file on the Form. - .. warning:: + .. warning:: When using the file upload field there is a limit of 1,000 submissions using the same filename. Note that you can attach the submitted files in the "Send Form result" action. - **HTML area** - This field allows marketers to add custom HTML to their Form. @@ -186,9 +186,9 @@ CAPTCHA :width: 600 :alt: Screenshot showing CAPTCHA Form properties -With a CAPTCHA field, the answer field should be blank if you are using this as a honeypot to trap spam submissions. This hides the field, and spambots try to populate the field with data. +With a CAPTCHA field, the answer field should be blank if you are using this as a honeypot to trap spam submissions. This hides the field, and spambots try to populate the field with data. -Mautic recognizes if there's data in a honeypot CAPTCHA field and understands that it can't be a human submitting the Form. +Mautic recognizes if there's data in a honeypot CAPTCHA field and understands that it can't be a human submitting the Form. To have a human answer a basic question or statement - for example ``What's 2+2`` or ``Enter 'CAPTCHA' here`` - you would enter the expected input in the answer field, in this case, ``4`` or ``CAPTCHA``. The field's label should be the question, or you can use the label CAPTCHA and then have the question as the input placeholder. @@ -233,16 +233,16 @@ When uploading a file within a Form there are several options under the properti Attributes ~~~~~~~~~~ - Attributes are CSS tags which change the styling of a particular Form. + Attributes are CSS tags which change the styling of a particular Form. -.. note:: +.. note:: Setting the Render Style to No on the Form means that Mautic ignores the styling in these fields. .. image:: images/forms/checkbox_group_attributes.png :width: 600 :alt: Screenshot showing the attributes for a checkbox group -- **Field HTML name**: this is the machine name of the field, populated automatically from the label. You can customise this field if the label is long. You reference this field is when connecting Mautic Forms to other Forms, or when using the Manual Copy function to manually add the Form to your website or app. +- **Field HTML name**: this is the machine name of the field, populated automatically from the label. You can customise this field if the label is long. You reference this field is when connecting Mautic Forms to other Forms, or when using the Self-hosted function to manually add the Form to your website or app. - **Label attributes**: this field changes the way the label text appears. You should use the format ``style="attribute: descriptor"`` to change the style. For example, to change the label to red, use ``style="color: red"`` or ``style="color: #ff0000"``. - **Input attributes**: changes the way any text inside the Form Field appears. This applies to the input placeholder text, text entered by the visitor submitting the Form, and the options for the select fields when Allow Multiple is Yes - including List - Country. - **Field container attributes**: this changes the Form Field. Use this to change the size of the box, fill color, rounded edges, or any other properties of the actual field. @@ -268,12 +268,58 @@ To change the order of fields on your Form: #. Click the field you would like to move #. Drag the field to a new location +.. vale off + +Progressive profiling +********************* +.. vale on + +Progressive profiling is a powerful feature used to reduce the length of Forms by hiding all the fields that are already known. This prevents your Contacts from feeling overwhelmed by massive Forms and even reduces the time it takes to fill out a Form if fields are already known to your Mautic instance and thus hidden for the Contact. + +Configuration of progressive profiling +====================================== + +There are two ways to configure a Form Field to only display when the asked values are unknown. + +First, choose the Form that you want to use for progressive profiling. Go to the Form Fields and open the field configuration of the field you want to use for progressive profiling. Change to the Behavior tab. Here, you can configure the behavior of the fields. + +.. note:: + It's always recommended to use the Email field, even if it's already known, because Mautic uses the Email as a unique identifier for Contacts. Additionally, ensure the submit button field is always visible. Otherwise, the Contact can't submit the Form. + +1. **Show when value exists**: +if set to 'No,' Mautic checks whether the value for this field exists in the database or if a previous Form submission provided it. If found, Mautic won't display the field in the Form. If set to 'Yes,' Mautic displays the field regardless of the existence of a value in the field. The default configuration for this option is 'Yes'. + +2. **Display field only after X submissions**: +if you have a Form that you'd like to use multiple times, with more fields appearing the more times a Contact fills it out, while still using only a single Form, the option 'Display field only after X submissions' is what you're looking for. As the name suggests, the field appears only after the Form has received X submissions. This feature pairs well with the ability to hide fields if the value is already known. + +For example, on the first time of completing the Form, it asks for the Email, first, and last name of a Contact. When the Contact fills out the Form a second time, it hides the first and last name fields, and instead, it prompts the Contact to fill in their Company and phone. + +.. vale off + +Limits of Progressive Profiling +=============================== +.. vale on + +**The search history limit** + +Mautic Forms which don't use progressive profiling are as fast as they can be. The HTML of the Form renders once, gets stored, and Mautic uses this "cached" HTML for the next Form load. When turning on progressive profiling for any of the Form Fields, the Form HTML might be different for each Contact. It can even change for each Contact after each submission. The impact of this is that you can't use Form-caching, and the Form load time is slower for a progressive profiling Form. + +Mautic imposed a limit of 200 submissions from which it searches for existing Form values. This limit aims to prevent possible long Form loading times or hitting the server time or memory limits when a Contact has several thousand Form submissions. Exceeding this limit might cause Mautic to display/hide the wrong fields for a Contact. + +**The embed type limit** + +Progressive Profiling Forms don't function if you embed your Form as static HTML. However, they work on Form preview, Form public pages, Forms embedded via JS, and Forms embedded via iframes. + +**The kiosk mode limit** + +When you switch the Form to Kiosk Mode, the Progressive Profiling features are turn off. In Kiosk Mode, the Form always creates a new Contact upon each submission and doesn't track the device submitting the Form. + Form actions ************ You may want to trigger certain actions to happen immediately after Form submission - this is what Form actions are for. This might include communications with the Contact, tracking, internal notifications, or other Contact management tasks. -.. note:: +.. note:: The Form actions available in Mautic are also available in Standalone Forms, which include more options as they're not associated with Campaigns. Campaigns tend to trigger most actions through Campaign actions so Forms associated with Campaigns only have a basic set of Form actions. - **Add to Company's Score**: if a Contact associated with a Company record in Mautic has submitted the Form, you can add or subtract Points to the Company's overall score. Company scoring in Mautic doesn't aggregate Points for all its associated Contacts. Any actions that you want to contribute to a Company's score must be explicitly set. Negative numbers are valid if you want to subtract from a Company's score based on a Contact submitting a Form. If the Contact isn't tracked and the Form doesn't include a field mapped to Company or Company Name - on the Company object - the Company has no Points awarded. @@ -288,7 +334,7 @@ You may want to trigger certain actions to happen immediately after Form submiss :width: 600 :alt: Screenshot showing the adjust Contact score Form action. -- **Modify Contact's Segments**: this action allows you to change a Contact's Segment membership when they submit a Form. Type in the name of the Segment to add the Contact to or remove the Contact from. You can use both fields at the same time, and can include multiple Segments in either or both fields. +- **Modify Contact's Segments**: this action allows you to change a Contact's Segment membership when they submit a Form. Type in the name of the Segment to add the Contact to or remove the Contact from. You can use both fields at the same time, and can include multiple Segments in either or both fields. Dynamic Segments based on filters update based on information in the Contact record automatically - you don't need add them to the Segment in a Form action. @@ -360,7 +406,7 @@ You can style the message itself as you like, and you can click to insert the su .. image:: images/forms/send_form_results.png :width: 600 - :alt: Screenshot showing the send Form results action. + :alt: Screenshot showing the send Form results action. .. vale off @@ -383,22 +429,22 @@ When working with Mautic Landing Pages or common Content Management Systems (CMS - **Mautic Landing Page**: ``{form= ID#}`` - **Drupal 7.x**: ``{mauticform id =ID# width=300 px height=300 px}`` - be sure to change the width and height to the appropriate size for your website. -.. warning:: - This shortcode doesn't work for Drupal 8.x - it's recommended to use the Automatic Copy option instead. +.. warning:: + This shortcode doesn't work for Drupal 8.x - it's recommended to use the Embedded option instead. - **Joomla!**: ``{mauticform ID#}`` - **WordPress**: ``[mautic type="form" id=ID#]`` -Automatic copy +Embedded ============== .. image:: images/forms/embed_form.png :width: 600 - :alt: Screenshot showing the options for embedding a Mautic Form. + :alt: Screenshot showing the options for embedding a Mautic Form. -The Automatic option for embedding Mautic Forms uses JavaScript and ensures that the Forms on your website are always up to date with what you have set in Mautic. If you make changes to the Form in Mautic, you don't have to worry about re-copying the Form code everywhere you use the Form. Features including auto-fill and progressive profiling **only** works with the Automatic option. +The Embedded option for embedding Mautic Forms uses JavaScript and ensures that the Forms on your website are always up to date with what you have set in Mautic. If you make changes to the Form in Mautic, you don't have to worry about re-copying the Form code everywhere you use the Form. Features including auto-fill and progressive profiling **only** works with the Embedded option. -.. note:: +.. note:: Before copying the code to embed your Mautic Forms, ensure that you are on the correct domain name - not a staging area or internal reference for example - as the Form embed code references the URL. Via JavaScript @@ -415,16 +461,16 @@ Via IFrame IFrames can be more difficult to use, and blocking by browsers is more likely, however there are sometimes where using an IFrame is preferable. Be sure to adjust the width and height for the space required to fit the Form. The visitor may need to scroll within the IFrame depending on the resolution of their browser. It's possible to display an error message in the event that the visitor's browser doesn't support IFrames, by editing the text between the ``

`` and ``

`` tags before copying the code and pasting it into your website. -Manual copy +Self-hosted =========== .. image:: images/forms/embed_form_manual.png :width: 600 - :alt: Screenshot showing the options for manually embedding a Mautic Form. + :alt: Screenshot showing the options for manually embedding a Mautic Form. -The manual copy option does provide more flexibility to extend Forms with JavaScript snippets and custom styling, however it's a manual process and any changes made within Mautic after copying the code won't be automatically reflected on your website unless you re-copy and paste the new HTML code. +The Self-hosted option does provide more flexibility to extend Forms with JavaScript snippets and custom styling, however it's a manual process and any changes made within Mautic after copying the code won't be automatically reflected on your website unless you re-copy and paste the new HTML code. -.. note:: +.. note:: Before copying the code to embed your Mautic Forms, ensure that you are on the correct domain name - not a staging area or internal reference for example - as the Form embed code references the URL. #. Copy the JavaScript code in the first box, and paste it into the head or body of your page. If you have multiple Mautic Forms on the same page, add this once only. @@ -459,7 +505,7 @@ Adding conditional fields to a Mautic Form Once you have created the required Custom Fields, add the parent field to the Form as detailed previously, and add the relevant information in the tabs. -.. note:: +.. note:: When using conditional fields, only ``Select``, ``Select - Multiple`` and ``Boolean`` field types are valid as the parent field. .. image:: images/forms/conditional_fields_1.png @@ -478,13 +524,13 @@ Once saved, an option displays to add a conditional field. :width: 600 :alt: Screenshot showing option to add a field based on the value of an existing field -In this example, select the ``Checkbox Group`` option, and under the Condition tab, choose ``including`` and ``Ford``. +In this example, select the ``Checkbox Group`` option, and under the Condition tab, choose ``including`` and ``Ford``. .. image:: images/forms/conditional_fields_4.png :width: 600 :alt: Screenshot showing selection of parent field -This means that when the visitor selects Ford, the Form displays this field. +This means that when the visitor selects Ford, the Form displays this field. There are two options: @@ -504,7 +550,7 @@ Once saved, the Form displays the conditional field nested underneath the parent Blocking Form submissions from specified domains ************************************************ -Sometimes it's necessary to block certain domains from submitting Forms - for example to restrict access to proprietary content and reduce the volume of unqualified leads. +Sometimes it's necessary to block certain domains from submitting Forms - for example to restrict access to proprietary content and reduce the volume of unqualified Contacts. Configuring blocked domains =========================== @@ -527,4 +573,4 @@ To apply domain name filtering on a Mautic Form, add an Email field to the Form :width: 600 :alt: Screenshot showing domain blocking used in a Mautic Form -It's advised to provide a helpful message to display if the visitor tries to use an Email address from a blocked domain, to help them understand what the problem is. \ No newline at end of file +It's advised to provide a helpful message to display if the visitor tries to use an Email address from a blocked domain, to help them understand what the problem is. diff --git a/docs/components/images/forms/embed_form.png b/docs/components/images/forms/embed_form.png index cb0449aa..d4eaf931 100644 Binary files a/docs/components/images/forms/embed_form.png and b/docs/components/images/forms/embed_form.png differ diff --git a/docs/components/images/forms/embed_form_manual.png b/docs/components/images/forms/embed_form_manual.png index 77ec10a3..fbc2e3bc 100644 Binary files a/docs/components/images/forms/embed_form_manual.png and b/docs/components/images/forms/embed_form_manual.png differ diff --git a/docs/conf.py b/docs/conf.py index 0e6c1ca5..cb73a4b8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -61,7 +61,7 @@ # -- Internationalisation configuration -locale_dirs = 'locale' +locale_dirs = ['locale'] # Please add links here that do not pass the "make checklinks" check. # A little context on the reason for ignoring is greatly appreciated! @@ -74,4 +74,13 @@ r"https://support.twilio.com/*", # This is a demo URL and should not be checked r"https://api-ssl.bitly.com/*", + #This domain blocks the checker. + r"https://linuxize.com/*", + # The GitHub Search UI requires users to be authenticated with session cookies, which we can't set up programmatically + r"https://github.com/search*", + # Requires authentication. + r"https://www.maxmind.com/en/accounts/current*", + # The URLs below broken and should be replaced by working ones. + r"https://staffwww.fullcoll.edu/sedwards/Nano/NanoKeyboardCommands.html", + r"https://blog.maxmind.com/search-results*" ] diff --git a/docs/configuration/command_line_interface.rst b/docs/configuration/command_line_interface.rst index 889c9979..b81fce05 100644 --- a/docs/configuration/command_line_interface.rst +++ b/docs/configuration/command_line_interface.rst @@ -90,7 +90,7 @@ These are the commands you may need to use in relation to your Mautic instance. - Rebuild Campaigns based on Contact Segments. - ``mautic:campaigns:update`` * - ``mautic:campaigns:trigger`` - - Trigger timed events for published Campaigns. + - Trigger timed events for active Campaigns. - * - ``mautic:campaigns:validate`` - Validate if a Contact has been inactive for a decision and execute events if so. @@ -104,6 +104,9 @@ These are the commands you may need to use in relation to your Mautic instance. * - ``mautic:contacts:deduplicate`` - Merge Contacts based on same unique identifiers - + * - ``mautic:contacts:scheduled_export`` + - Processes exports of Contacts to a CSV file and sends the results via Email. + - * - ``mautic:custom-field:create-column`` - Creates the actual column in the table - @@ -113,6 +116,9 @@ These are the commands you may need to use in relation to your Mautic instance. * - ``messenger:consume email`` - Processes mail queue - + * - ``mautic:fields:analse`` + - Analyze Custom Fields table and return table or file with results. See :doc:`/contacts/custom_fields`. + - * - ``mautic:import`` - If the CSV import is configured to run in background then this command will pick up the pending import jobs and imports the data from CSV files to Mautic. - diff --git a/docs/configuration/cron_jobs.rst b/docs/configuration/cron_jobs.rst index 433d6f21..239378b4 100644 --- a/docs/configuration/cron_jobs.rst +++ b/docs/configuration/cron_jobs.rst @@ -73,6 +73,8 @@ By default, the script processes Contacts in batches of 100. If this is too many You can also limit the number of Contacts to process per script execution using ``--max-events`` to further limit resources used. +Since Mautic 5.1, Mautic triggers Campaigns in order from newest to oldest. This allows you to process newer Campaigns with higher priority. + .. vale off **To send frequency rules rescheduled marketing Campaign messages:** Messages marked as *Marketing Messages* - such as Emails as part of a marketing Campaign - get held in a message queue IF frequency rules are setup as either system wide or per Contact. To process this queue and reschedule sending these messages, add this cron job: @@ -157,6 +159,21 @@ To import an especially large number of Contacts or Companies in the background, The time taken for this command to execute depends on the number of Contacts in the CSV file. However, on successful completion of the import operation, a notification appears on the Mautic dashboard. +.. vale off + +Export Contacts cron job +======================== + +.. vale on + +To export Contacts to CSV - sending the results via Email - use the following command: + +.. code-block:: bash + + php /path/to/mautic/bin/console mautic:contacts:scheduled_export + +The time taken for this command to execute depends on the number of Contacts in the CSV file. However, on successful completion of the export operation, Mautic sends an email with the link to download the CSV. + Webhooks cron job ================= @@ -166,6 +183,15 @@ If the Mautic configuration settings include Webhook batch processing, use the f php /path/to/mautic/bin/console mautic:webhooks:process + +Since Mautic 5.1 it's also possible to run the Webhooks cron job in 'range mode'. This allows you to specify a range of Webhook events to process in a single run. This can be useful if you have a large number of Webhook events to process and want to avoid running out of memory. + +To use this mode, you can specify the ``--min-id`` and ``--max-id`` options. For example, to process events for a Webhook with ID of 5, you can specify to only process the events for that Webhook with IDs between 1000 and 2000 using the following command: + +.. code-block:: bash + + bin/console mautic:webhooks:process --webhook-id=5 --min-id=1000 --max-id=2000 + .. _cron jobs: .. vale off @@ -315,6 +341,19 @@ These commands work with all available Plugins. To avoid performance issues when you can replace ``mautic:plugins:reload`` with ``mautic:plugins:install`` or ``mautic:plugins:update``. They're the same commands with different alias. +Exclude processed entities +************************** + +This feature is particularly useful for managing data and ensuring that entities aren't processed multiple times unnecessarily. The ``--exclude`` option prevents the specified action from re-processing entities that it has already processed.. This option is available for the ``mautic:campaigns:trigger``, ``mautic:campaigns:rebuild``, and ``mautic:segments:update`` commands. + +.. code-block:: php + + php /path/to/mautic/bin/console mautic:campaigns:trigger --exclude + +.. note :: + + This is particularly useful for scenarios where you want to avoid redundant processing of entities, such as preventing a Campaign or Segment action from executing multiple times for the same Contact. + Tips & troubleshooting ********************** @@ -338,22 +377,3 @@ Example output If you have SSH access, try to run the command directly to Select for errors. If there is nothing printed from either in a SSH session or in the cron output, verify in the server's logs. If you see similar errors to ``'Warning: Invalid argument supplied for foreach()' in /vendor/symfony/console/Symfony/Component/Console/Input/ArgvInput.php:287``, you either need to use ``php-cli`` instead of ``php`` or try using ``php -d register_argc_argv=On``. ` -Tracking script -############### - -After installation and setup of the :doc:`/configuration/cron_jobs` you're ready to begin tracking Contacts. You need to add a piece of JavaScript to the websites for each site you wish to track through Mautic. - -This is straightforward process, you can add this tracking script to your website template file, or install a Mautic Integration for the more common Content Management System platforms. - -Here is an example of the tracking JavaScript which you can access by clicking on **Tracking Settings** in the Global Configuration. - - -.. code-block:: javascript - - (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://example.com/mautic/mtc.js','mt'); - mt('send', 'pageview'); - -You should replace the site URL, ``example.com/mautic`` with the URL to your Mautic instance in the example provided, but it's recommended to copy the whole code block from the tracking settings in your Mautic instance. diff --git a/docs/configuration/images/export-settings.png b/docs/configuration/images/export-settings.png new file mode 100644 index 00000000..e342b2fb Binary files /dev/null and b/docs/configuration/images/export-settings.png differ diff --git a/docs/configuration/settings.rst b/docs/configuration/settings.rst index c580894c..d4b62162 100644 --- a/docs/configuration/settings.rst +++ b/docs/configuration/settings.rst @@ -335,12 +335,12 @@ See :ref:`here` to set the Contact's Em Default frequency rule ====================== +* **Do Not Contact more than each ** - This limits the number of Marketing Messages a Contact receives in a certain period of time day, week, month. Transactional messages don't count towards this limit. You can adjust this at the individual Contact level, either manually or by Preference Center setting. + .. image:: images/default-frequency-rule.png :width: 600 :alt: Screenshot showing Default Frequency Rule Configuration in Mautic -* **Do not contact more than each ** - This limits the number of Marketing Messages a Contact receives in a certain period of time day, week, month. Transactional messages don't count towards this limit. You can adjust this at the individual Contact level, either manually or by Preference Center setting. - .. note:: More information is available in the :doc:`Default Frequency Rule documentation`. @@ -394,7 +394,7 @@ Unsubscribe settings * **Show Contact preference settings** - Select **Yes** to direct the unsubscribe link to your configured Preference enter. If you haven't created a Preference Center, Mautic creates a default page based on the next 5 settings. The created page uses the default Theme for styling. -* **Show Contact Segment preferences** - Select **Yes** to allow a Contact to change which Segments they're part of on the Preference Center page. Segments won't display on the Preference Center page if they aren't published and public. +* **Show Contact Segment preferences** - Select **Yes** to allow a Contact to change which Segments they're part of on the Preference Center. Segments won't display on the Preference Center if they aren't active and public. * **Show Contact frequency preferences** - Select **Yes** to allow an individual to limit the number of Marketing Messages they receive on each Channel from the Preference Center. @@ -468,7 +468,16 @@ Import settings :alt: Screenshot showing Import Settings Configuration in Mautic * **Automatically import in the background if the CSV has more rows than defined** - If there are more than the specified number of rows in an import file, the CSV automatically sets to import in the background which requires a :ref:`cron job` to trigger. Set to 0 if you want to always import files in the background recommended for performance optimization. - + +Export settings +=============== + +.. image:: images/export-settings.png + :width: 600 + :alt: Screenshot showing Export Settings Configuration in Mautic + +* **Automatically export Contacts to CSV in the background** - If set to Yes, Mautic processes CSV exports of Contacts in the background and Mautic sends an Email with a link to download the file when it's processed. + Segment settings **************** @@ -627,9 +636,9 @@ Notification settings :width: 600 :alt: Screenshot showing Webhook Notification Settings Configuration in Mautic -If a Campaign or Webhook is automatically unpublished because of a high volume of errors, Mautic sends a notification alerting Users. +If a Campaign or Webhook is automatically deactivated because of a high volume of errors, Mautic sends a notification alerting Users. -* **Send notification to author** - Set this field to Yes to send an Email notification to the User who created the unpublished Campaign or Webhook. Deleted Users don't receive notifications. +* **Send notification to author** - Set this field to Yes to send an Email notification to the User who created the deactivated Campaign or Webhook. Deleted Users don't receive notifications. .. vale off diff --git a/docs/configuration/tracking_script.rst b/docs/configuration/tracking_script.rst new file mode 100644 index 00000000..77f5b826 --- /dev/null +++ b/docs/configuration/tracking_script.rst @@ -0,0 +1,23 @@ +.. vale off + +Tracking script +############### + +.. vale on + +After installation and setup of the :doc:`/configuration/cron_jobs` you're ready to begin tracking Contacts. You need to add a piece of JavaScript to the websites for each site you wish to track through Mautic. + +This is straightforward process, you can add this tracking script to your website template file, or install a Mautic Integration for the more common Content Management System platforms. + +Here is an example of the tracking JavaScript which you can access by clicking on **Tracking Settings** in the Global Configuration. + + +.. code-block:: javascript + + (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://example.com/mautic/mtc.js','mt'); + mt('send', 'pageview'); + +You should replace the site URL, ``example.com/mautic`` with the URL to your Mautic instance in the example provided, but it's recommended to copy the whole code block from the tracking settings in your Mautic instance. \ No newline at end of file diff --git a/docs/contacts/custom_fields.rst b/docs/contacts/custom_fields.rst index 06d4bf98..dd7c55a8 100644 --- a/docs/contacts/custom_fields.rst +++ b/docs/contacts/custom_fields.rst @@ -105,3 +105,51 @@ If you configure this option, the new Custom Field becomes visible in the list o This configuration helps prevent **http** request timeouts because it handles the long-running SQL query to create the new table column as a background task. To mitigate the table lock issue, run the command only once daily when you know that most of your audience is offline. With less traffic going into Mautic, the chances of encountering a problem are lower. + + +Analyzing Custom Fields to optimize tables +****************************************** + +Since Mautic 5.1 there is a command which allows you to analyze the Custom Fields and optimize the tables. This command is useful when you have a lot of Custom Fields and you want to optimize the size of VARCHAR fields. + +Using this command allows you to optimize the VARCHAR columns so that you can create more Custom Fields if you hit the hard limit on the Leads table and can't create more. + +Use the command: + +.. code-block:: bash + + bin/console mautic:fields:analyse -t + +Use the -t argument to see the output in tabulated form in the console. + +Use the following to export the data to a file: + +.. code-block:: bash + + bin/console mautic:fields:analyse > path/to/file.csv + +Locally defined countries and regions +************************************* + +Since Mautic 5.1 it's possible to define custom countries and regions via locally hosted JSON files. This is useful when you have a specific set of countries or regions that you want to use in your Mautic instance. You can define these in a file called ``countries.json`` or ``regions.json`` located in your defined ``upload_dir`` which is ``media/files`` by default. Example code snippets are below: + +.. code-block:: json + + [ + "Middle Earth", + "Fillory" + ] + +.. code-block:: json + + { + "Middle Earth": [ + "The Shire", + "Mordor" + ], + "Fillory": [ + "Castle Whitespire", + "Ember's Tomb" + ] + } + diff --git a/docs/contacts/images/notifications.png b/docs/contacts/images/notifications.png index f057e5cf..8e0d3b01 100644 Binary files a/docs/contacts/images/notifications.png and b/docs/contacts/images/notifications.png differ diff --git a/docs/contacts/import_contacts.rst b/docs/contacts/import_contacts.rst index b44d7c1d..d0c6fcca 100644 --- a/docs/contacts/import_contacts.rst +++ b/docs/contacts/import_contacts.rst @@ -172,13 +172,13 @@ How to stop a background import 2. In the top right corner of the Contacts page, open the sub menu of actions and select the :ref:`Import History` option. -3. Unpublish the import job you want to stop. The import changes :ref:`status` to Stopped. It finishes importing the current batch and then stops. +3. Deactivate the import job you want to stop. The import changes :ref:`status` to Stopped. It finishes importing the current batch and then stops. -4. To start the import again, publish it, and the background job continues with the next :doc:`cron job execution`. +4. To start the import again, activate it, and the background job continues with the next :doc:`cron job execution`. .. image:: images/import-publish.png :align: center - :alt: Screenshot of Import publish + :alt: Screenshot of Import activation | diff --git a/docs/contacts/manage_contacts.rst b/docs/contacts/manage_contacts.rst index 1612631c..6c7b84e6 100644 --- a/docs/contacts/manage_contacts.rst +++ b/docs/contacts/manage_contacts.rst @@ -57,7 +57,7 @@ Add new Contact | -This opens the new Contact screen, where you can enter all the information you have about the Contact. It also displays all published Contact fields when creating a new Contact. +This opens the new Contact screen, where you can enter all the information you have about the Contact. It also displays all available Contact fields when creating a new Contact. Use the tabs at the top to populate existing Custom Fields and social network profiles. diff --git a/docs/getting_started/how_to_install_mautic.rst b/docs/getting_started/how_to_install_mautic.rst index 6fbaa1e5..3d776c3d 100644 --- a/docs/getting_started/how_to_install_mautic.rst +++ b/docs/getting_started/how_to_install_mautic.rst @@ -333,6 +333,10 @@ With Composer you can add new dependencies to install along with Mautic: cd your-directory composer require mautic/mautic/helloworld-bundle +.. note:: + + As this method of installation moves the core app files into a folder called ``docroot`` from which Mautic runs, you should ensure that you configure your web server to serve files from this directory. This might mean updating your virtual host and/or NGINX configuration to have ``/docroot`` as the root directory. If you don't do this, it's likely you'll see errors when you try to access your Mautic instance. + The Composer ``create-project`` command passes ownership of all files to the created project. You should create a new git repository, and commit all files not excluded by the .gitignore file. .. vale off @@ -344,7 +348,7 @@ What does the Recommended Project template actually do? When installing the given ``composer.json`` the following occurs: -- Install Mautic in the ``docroot`` directory. +- Install Mautic in the ``docroot`` directory. See earlier note about updating your hosting configuration. - Autoloader uses the generated Composer autoloader in ``vendor/autoload.php``, instead of the one provided by Mautic in ``docroot/vendor/autoload.php``. - Plugins - packages of type ``mautic-plugin`` - are in ``docroot/plugins/``. - Themes - packages of type ``mautic-theme`` - are in ``docroot/themes/``. @@ -437,6 +441,10 @@ It's possible to change this folder to your own needs. In following examples, ``docroot`` moves into ``public``. +.. note:: + + Remember that you must also update your web server configuration to point to the new folder. + New installations ----------------- @@ -444,7 +452,7 @@ New installations .. code-block:: bash - composer create-project mautic/recommended-project:^4 some-dir --no-interaction --no-install + composer create-project mautic/recommended-project:^5 some-dir --no-interaction --no-install * Do a find and replace in the ``composer.json`` file to change ``docroot/`` into ``public/`` * Review the changes in the ``composer.json`` file to ensure that there are no unintentional replacements diff --git a/docs/getting_started/how_to_update_mautic.rst b/docs/getting_started/how_to_update_mautic.rst index 6f199407..9c8d2d7c 100644 --- a/docs/getting_started/how_to_update_mautic.rst +++ b/docs/getting_started/how_to_update_mautic.rst @@ -10,6 +10,9 @@ There are two ways to update Mautic: 1. Using the Command Line - recommended 2. Through the User interface +.. note:: + If you installed Mautic using Composer or switched to a Composer-based install, jump straight to the :ref:`Updating Mautic (Composer based installs)` section below. + If your instance is in production, has a large number of Contacts and/or is on shared hosting, it's **strongly** recommended that you update at the command line. .. warning:: @@ -22,42 +25,12 @@ Before you commence updating Mautic, **please ensure that you have a tested back This means that you have downloaded the files and database of your Mautic instance, and you have re-created it in a test environment somewhere and tested that everything is working as expected. This is your only recourse if there are any problems with the update. Never update without having a working, up-to-date backup. -Updating Mautic (Composer based installs) -***************************************** - -The Recommended Project attempts to keep all of your Mautic core files up-to-date. - -The project ``mautic/core-composer-scaffold`` updates your scaffold files whenever there is an update to ``mautic/core-lib``. - -If you customize any of the 'scaffolding' files - commonly ``.htaccess`` - you may need to merge conflicts if new release of Mautic results in changes to your modified files. - -Follow the steps below to update your core files. - -1. Run ``composer update mautic/core-lib --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 ``docroot`` remains 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 :xref:`kdiff3`. This setup isn't 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. - -5. Run the following commands to update your database with any changes from the release: - -.. code-block:: shell - - bin/console cache:clear - bin/console mautic:update:apply --finish - bin/console doctrine:migration:migrate --no-interaction - bin/console doctrine:schema:update --no-interaction --force - bin/console cache:clear - - Checking for updates at the command line ======================================== From Mautic 6, the default way to install, update and manage Mautic changes to Composer. -Since Mautic 4.2 deprecated the update feature within the Mautic User interface, you still receive a notification when a new version of Mautic is available until removal of this feature but it's recommended to update via the command line. +Since Mautic 4.2 deprecated the update feature within the Mautic User interface, you still receive a notification when a new version of Mautic is available until removal of this feature, but it's recommended to update via the command line. .. image:: images/gui-update-deprecated.png :width: 700 @@ -101,6 +74,42 @@ Next, a prompt displays asking you to run the command again with this additional php bin/console mautic:update:apply --finish +Updating Mautic (Composer based installs) +***************************************** + +The Recommended Project attempts to keep all of your Mautic core files up-to-date. + +The project ``mautic/core-composer-scaffold`` updates your scaffold files whenever there is an update to ``mautic/core-lib``. + +If you customize any of the 'scaffolding' files - commonly ``.htaccess`` - you may need to merge conflicts if new release of Mautic results in changes to your modified files. + +Follow the steps below to update your core files. + +1. Backup your ``composer.lock`` and ``composer.json`` file. If something doesn't work as expected during the ``composer update`` command, restore them and run ``composer install`` to return your codebase to the state it was in before attempting to update. + +2. Edit the ``composer.json`` file, and change all previous versions with the version you wish to update to for all Mautic packages. + + * If you are running ``5.0.4`` and want to update to ``5.1.0``, replace ``5.0.4`` with ``5.1.0`` for all packages that start with ``mautic/`` and currently use ``5.0.4``. + * You may also need to increase the versions of any other packages you have either manually added or added through :ref:`Mautic Marketplace`. + * If you haven't added any extra packages, you can also replace the entire ``composer.json`` file with the newer version from the `repository `_ that matches your desired target version. + +3. Run ``composer update --with-dependencies`` to update all packages. + +4. 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. + +5. Commit everything all together in a single commit, so the ``docroot`` remains in sync with the core when checking out branches or running ``git bisect``. + +6. 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 :xref:`kdiff3`. This setup isn't 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. + +7. Run the following commands to update your database with any changes from the release: + +.. code-block:: shell + + bin/console cache:clear + bin/console mautic:update:apply --finish + bin/console doctrine:migration:migrate --no-interaction + bin/console doctrine:schema:update --no-interaction --force + bin/console cache:clear Updating in the browser *********************** diff --git a/docs/index.rst b/docs/index.rst index 742ae22a..f9a9989d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,6 +54,7 @@ There are different types of documentation available to help you navigate your w configuration/maxmind_license configuration/command_line_interface configuration/cron_jobs + configuration/tracking_script configuration/variables configuration/settings configuration/shortener @@ -166,7 +167,6 @@ There are different types of documentation available to help you navigate your w plugins/clearbit plugins/connectwise plugins/fullcontact - plugins/gmail plugins/hubspot plugins/icontact plugins/mailchimp diff --git a/docs/links/github_search_ini.py b/docs/links/github_search_ini.py new file mode 100644 index 00000000..c0f165e7 --- /dev/null +++ b/docs/links/github_search_ini.py @@ -0,0 +1,7 @@ +from . import link + +link_name = "Mautic INI files" +link_text = "Mautic INI files" +link_url = "https://github.com/search?q=repo%3Amautic%2Fmautic+Dashboard+menu+language%3AINI" + +link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/links/knowledge_base_sf.py b/docs/links/knowledge_base_sf.py new file mode 100644 index 00000000..07bdadea --- /dev/null +++ b/docs/links/knowledge_base_sf.py @@ -0,0 +1,7 @@ +from . import link + +link_name = "Knowledgebase article on Salesforce" +link_text = "Knowledgebase article on Salesforce" +link_url = "https://kb.mautic.org/article/how-to-integrate-mautic-with-salesforce.html" + +link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/links/linux_ls_command_documentation.py b/docs/links/linux_ls_command_documentation.py index bdd1b6a8..01460326 100644 --- a/docs/links/linux_ls_command_documentation.py +++ b/docs/links/linux_ls_command_documentation.py @@ -2,6 +2,6 @@ link_name = "Linux ls command" link_text = "Linux ls command documentation" -link_url = "https://www.garron.me/en/go2linux/ls-file-permissions.html" +link_url = "https://en.wikipedia.org/wiki/Ls" link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/marketplace/images/composer-enabled.png b/docs/marketplace/images/composer-enabled.png index b5d5b63d..883e4fd6 100644 Binary files a/docs/marketplace/images/composer-enabled.png and b/docs/marketplace/images/composer-enabled.png differ diff --git a/docs/marketplace/images/marketplace-detail.png b/docs/marketplace/images/marketplace-detail.png index d5d8a7b2..c51805c3 100644 Binary files a/docs/marketplace/images/marketplace-detail.png and b/docs/marketplace/images/marketplace-detail.png differ diff --git a/docs/marketplace/images/marketplace-list.png b/docs/marketplace/images/marketplace-list.png index 5f50366b..ee920292 100644 Binary files a/docs/marketplace/images/marketplace-list.png and b/docs/marketplace/images/marketplace-list.png differ diff --git a/docs/marketplace/images/need-to-enable-composer.png b/docs/marketplace/images/need-to-enable-composer.png index 9f3d61ae..d85d2972 100644 Binary files a/docs/marketplace/images/need-to-enable-composer.png and b/docs/marketplace/images/need-to-enable-composer.png differ diff --git a/docs/plugins/gmail.rst b/docs/plugins/gmail.rst deleted file mode 100644 index 3bfedb8a..00000000 --- a/docs/plugins/gmail.rst +++ /dev/null @@ -1,47 +0,0 @@ -GMail -###### - -This plugin enables the Mautic Helper Chrome Extension to track emails sent to leads directly from GMail. - -Requirements: - -1. A publicly accessible Mautic installation. - -2. A GMail account (for email tracking). - -3. Mautic Helper Chrome Extension. - -Plugin Configuration: - -Follow these steps to configure the Plugin: - -1. Install the Mautic Plugin as usual. It'll appear on the Plugins page in Mautic. - -2. Click on the GMail Plugin button and enter a secret or key to validate the Mautic Helper Chrome Extension - -3. Install the Mautic Helper Chrome Extension from the Chrome Web Store - -4. Configure the extension using the options page that will automatically be displayed. (Remember to use the same secret you entered in Mautic) - -5. On the Chrome browser there will be a button that will notify of new events on the contacts timeline. - -6. To track an email sent to a lead, click the Track Email button on the Compose window in GMail - -7. This appends a tracking GIF to the email with the following syntax: ``[[MAUTIC_URL]]/index.php/gmail/tracking.gif?d=H4sIAAAAAAAEAIVRTW%2FCMAz9LRyCtgNVlFBpHHroWsRuk8ak7RpaUzqaGCUp0H8%2Fpy0TH4dJUZy892w921uLOvkCa8BGK2WLWi2dt6pUbM7PYPEcFainoFXdJKdBVvUy4quA9rxrNz9Q%2BCQ16HdgmeAenKewpfIU3lvfIO6nGyy75HNXO8LQAN3984R2X5tqMpkwnjOejrfg19%2FBJIHBJsskS3M1MOvOedChUA5HaPBAsp54a7UyBH%2BAw9YWECRrsMc6PHvFd2iR0NfW1QbcjUDwMjhctYqqq0YxkQU6SqMhNxi85GeoD8p0134zaBom%2By4ezlPMxTPFeCH5TLzI%2BdgizeEu5aIUQixmIubjSG5WAY8bC8kyC%2FvxSBX%2Flcvl3bT%2Fvr8k1oBgIQIAAA%3D%3D&sig=cf078d5b`` - -8. The Mautic Plugin will then validate the information using the secret to compare signatures and then attach that email to the contact’s profile as part of their activity history. If the lead or leads don't exist, they are created automatically - -.. vale off - -URL Parameter Length Issue -************************** - -.. vale on - -Please note that PHP setups with the Suhosin patch installed will have a default limit of 512 characters for get parameters. - -Although bad practice, most browsers (including IE) supports URLs up to around 2000 characters, while Apache has a default of 8000. - -To add support for long parameters with Suhosin add the following to ``php.ini``: - -``suhosin.get.max_value_length = 5000`` \ No newline at end of file diff --git a/docs/plugins/hubspot.rst b/docs/plugins/hubspot.rst index 47670225..4abf7ed5 100644 --- a/docs/plugins/hubspot.rst +++ b/docs/plugins/hubspot.rst @@ -30,7 +30,7 @@ Configure the HubSpot CRM Plugin .. note:: - Be sure to complete all steps before you publish the Plugin. + Be sure to complete all steps before you activate the Plugin. 1. Log in to Mautic instance. @@ -63,7 +63,7 @@ Configure the HubSpot CRM Plugin 9. Click **Save** to save the Plugin configuration. - * If you want to use the Plugin, set the *Publish* switch to **Yes**. Only do this when you have fully configured the Plugin settings. + * If you want to use the Plugin, set the *Active* switch to **Yes**. Only do this when you have fully configured the Plugin settings. 10. Set up the :ref:`cron job` if you haven't already configured it. diff --git a/docs/plugins/images/plugins-mailchimp-configure.png b/docs/plugins/images/plugins-mailchimp-configure.png new file mode 100644 index 00000000..9ebb5523 Binary files /dev/null and b/docs/plugins/images/plugins-mailchimp-configure.png differ diff --git a/docs/plugins/images/plugins-mailchimp-copy-api-key.png b/docs/plugins/images/plugins-mailchimp-copy-api-key.png new file mode 100644 index 00000000..1156e2d6 Binary files /dev/null and b/docs/plugins/images/plugins-mailchimp-copy-api-key.png differ diff --git a/docs/plugins/images/plugins-mailchimp-create-api-key-1-and-2.png b/docs/plugins/images/plugins-mailchimp-create-api-key-1-and-2.png new file mode 100644 index 00000000..2112a9a8 Binary files /dev/null and b/docs/plugins/images/plugins-mailchimp-create-api-key-1-and-2.png differ diff --git a/docs/plugins/images/plugins-mailchimp-create-api-key-3a.png b/docs/plugins/images/plugins-mailchimp-create-api-key-3a.png new file mode 100644 index 00000000..d69621d2 Binary files /dev/null and b/docs/plugins/images/plugins-mailchimp-create-api-key-3a.png differ diff --git a/docs/plugins/images/plugins-mailchimp-create-api-key-3b-and-3c.png b/docs/plugins/images/plugins-mailchimp-create-api-key-3b-and-3c.png new file mode 100644 index 00000000..7b1e6e66 Binary files /dev/null and b/docs/plugins/images/plugins-mailchimp-create-api-key-3b-and-3c.png differ diff --git a/docs/plugins/images/plugins.png b/docs/plugins/images/plugins.png index 32d1e59b..48589b1e 100644 Binary files a/docs/plugins/images/plugins.png and b/docs/plugins/images/plugins.png differ diff --git a/docs/plugins/mailchimp.rst b/docs/plugins/mailchimp.rst index 1015b220..99af2673 100644 --- a/docs/plugins/mailchimp.rst +++ b/docs/plugins/mailchimp.rst @@ -1,6 +1,73 @@ -.. vale off - MailChimp ######### -.. vale on \ No newline at end of file +This Plugin can send Contacts to MailChimp lists based on Contact actions or Point Triggers. + +Authorize +********* + +Get MailChimp API key +===================== + +1. Create a MailChimp account. +2. Go to *Account* / *Extras* / *API Keys* and create a new one. +3. Copy the created API Key. + + .. image:: images/plugins-mailchimp-create-api-key-1-and-2.png + :alt: Screenshot of MailChimp dashboard with arrows pointing at the Extras tab and the API Keys section + :align: center + + .. image:: images/plugins-mailchimp-create-api-key-3a.png + :alt: Screenshot of MailChimp dashboard with an arrow pointing at the Create API Key button + :align: center + + .. image:: images/plugins-mailchimp-create-api-key-3b-and-3c.png + :alt: Screenshot of the Name New API Key section with arrows pointing at the test and Generate Key button + :align: center + +.. vale off + +Authorize Mautic - MailChimp Plugin +=================================== +1. Fill in with your MailChimp's account **username** +2. Add the **API key** +3. Click on ***Save & Close*** + +Configure the Plugin +******************** + +.. vale on + +Navigate to the *Features* tab in the Plugin configuration modal box. You should see this note: + +.. vale off + +.. note:: + The Contact Field Mapping tab will appear after selecting a segment and will update after changing the selected segment. + + .. vale on + +.. image:: images/plugins-mailchimp-configure.png + :alt: MailChimp Plugin configuration + :align: center + +1. Select the Segment. + + If you don't have a Segment in MailChimp created yet, go to *MailChimp dashboard* / *Segments* / *Create List* and create one. + +2. Save the Plugin configuration +3. Open it again. + + The *Contact Field Mapping* tab should appear now. + +4. Configure the field mapping. + +Other configuration options +=========================== + +- **Push Contacts to this Integration** + +Mautic enables these options by default. If you leave them off, the Plugin won't push Contacts to MailChimp. + +- **Enable double opt in** - If MailChimp should send a confirmation Email to the Contacts added by this Plugin. The Contacts must confirm that they really want to join the Segment. +- **Send welcome Email** - Whether MailChimp should send the welcome Email. \ No newline at end of file diff --git a/docs/plugins/salesforce.rst b/docs/plugins/salesforce.rst index 0eb0f696..15fa132c 100644 --- a/docs/plugins/salesforce.rst +++ b/docs/plugins/salesforce.rst @@ -3,4 +3,6 @@ Salesforce ########## -.. vale on \ No newline at end of file +.. vale on + +Visit the :xref:`Knowledgebase article on Salesforce` for details on how to configure the Salesforce integration. diff --git a/docs/plugins/social_login.rst b/docs/plugins/social_login.rst index bc419dcb..6c138275 100644 --- a/docs/plugins/social_login.rst +++ b/docs/plugins/social_login.rst @@ -3,4 +3,8 @@ Social Login ############# + .. image:: images/twilio-sid-authtoken.png + :width: 400 + :alt: Screenshot of the SID and Auth Token fields + .. vale on \ No newline at end of file diff --git a/docs/plugins/vtiger.rst b/docs/plugins/vtiger.rst index cc8ef897..f85aa93b 100644 --- a/docs/plugins/vtiger.rst +++ b/docs/plugins/vtiger.rst @@ -31,7 +31,7 @@ To authenticate the Mautic Plugin to be able to communicate with Vtiger CRM you' * Vtiger username - The username, email address usually, which you use to log in to your Vtiger. -* Vtiger access key - The access key published in your Vtiger profile. To get it, go to Vtiger's **My Preferences**. The Access Key hash is at the bottom of the page. +* Vtiger access key - The access key activated in your Vtiger profile. To get it, go to Vtiger's **My Preferences**. The Access Key hash is at the bottom of the page. .. image:: images/vtiger-mautic.png :alt: Screenshot of Vtiger Mautic Integration @@ -49,9 +49,9 @@ Configure the Vtiger CRM Plugin .. vale on -If you want to use the Plugin, you have to publish it. +If you want to use the Plugin, you have to activate it. -1. Set the *Publish* switch to **Yes**. +1. Set the *Active* switch to **Yes**. 2. In the **Features tab** is Push Contacts to this Integration checkbox and it's checked by default. diff --git a/docs/plugins/zoho_crm.rst b/docs/plugins/zoho_crm.rst index 540f417f..67096e19 100644 --- a/docs/plugins/zoho_crm.rst +++ b/docs/plugins/zoho_crm.rst @@ -5,7 +5,7 @@ Zoho CRM .. vale on -Mautic can push a Contact to :xref:`Zoho CRM` based on :doc:`Actions ` or :doc:`points trigger`. +Mautic can push a Contact to :xref:`Zoho CRM` based on Campaign :ref:`Actions` or :ref:`Point triggers`. Language configuration warning ****************************** @@ -87,7 +87,7 @@ You can also configure other options: If the values are empty for the Mautic object, a value of 'Unknown' is sent. If the ZohoCRM field is a pick list, be sure the list values of Mautic's field match those of the field in ZohoCRM. -8. Set the Publish switch to **Yes**. +8. Set the Active switch to **Yes**. 9. Click **Save & Close**. .. vale on diff --git a/docs/points/images/points-action.png b/docs/points/images/points-action.png index 8c4c6409..7caaa8e8 100644 Binary files a/docs/points/images/points-action.png and b/docs/points/images/points-action.png differ diff --git a/docs/points/points.rst b/docs/points/points.rst index aa711ceb..e5acf2bb 100644 --- a/docs/points/points.rst +++ b/docs/points/points.rst @@ -1,16 +1,17 @@ -.. vale off Points ###### -.. vale on - Points provide a way for properly weighing Contacts. These Points have both triggers and actions. The following section outlines all the relevant term definitions, and a thorough understanding of how Points function. This helps make your overall marketing automation process successful using Points -Point actions +.. vale off + +Point Actions ************* -Point actions are those times when a Contact receives a change in their Point total. These actions can be either positive or negative Point changes and occur based on a particular action as you determine. +.. vale on + +Point Actions are those times when a Contact receives a change in their Point total. These actions can be either positive or negative Point changes and occur based on a particular action as you determine. To add a new action: @@ -27,29 +28,33 @@ To add a new action: * **Change Points (+/-)** - The value change to set for the action. The ``+`` isn't necessary when adding Points. When subtracting Points, add the ``-`` symbol. - * **When a Contact…** - This is the behavior or action the Contact must complete to trigger the action. + * **Actions taken by User** - This is the behavior or action the Contact must complete to trigger the action. 3. On the right side is more information: - * **Category** - Organize your Point actions based on their goals, Campaigns, etc. For more information, see :doc:`Categories`. All Points accumulate on a Contact record, regardless of Category. There is one Points score for each Contact. + * **Category** - Organize your Point Actions based on their goals, Campaigns, etc. For more information, see :doc:`Categories`. All Points accumulate on a Contact record, regardless of Category. There is one Points score for each Contact. - * **Published and Publish/Unpublish at date/time** - Once you have a Point action, Mautic awards Points when a Contact completes the action. Points aren't given for unpublished actions. If you have target behaviors that you want to award Points for within a certain time period, you can set the publish and unpublish dates + * **Active and Activate/Deactivate at date/time** - Once you have a Point action, Mautic awards Points when a Contact completes the action. Points aren't given for inactive actions. If you have target behaviors that you want to award Points for within a certain time period, you can set the activate and deactivate dates * **Is repeatable** - To award Points each time a Contact completes an action, select **Yes**. If you want to award Points **only** the first time someone completes the action, select **No** - this is the default. 4. Click **Save** or **Save & Close**. -Point triggers +.. vale off + +Point Triggers ************** +.. vale on + Once a Contact has accumulated a Point total, you may want to trigger an action with the Contact. You may create multiple triggers for different Point values. .. image:: images/points-trigger.png :alt: Screenshot of Points trigger -Creating Point Triggers is like creating Point Actions. The **Name**, **Description**, **Category**, and **Publish** options are all the same. The trigger fires based on the minimum number of Points. Set a number and decide if you want to **Trigger for existing applicable Contacts upon saving - if published**. +Creating Point Triggers is like creating Point Actions. The **Name**, **Description**, **Category**, and **Active** options are all the same. The trigger fires based on the minimum number of Points. Set a number and decide if you want to **Trigger for existing applicable Contacts upon saving - if activated**. -Once you have decided and entered those options, go to the **Events** tab. Here, you can trigger one or more events once a Contact has reached your predetermined Point total. These Point triggers and associated events are also fully customizable. +Once you have decided and entered those options, go to the **Events** tab. Here, you can trigger one or more events once a Contact has reached your predetermined Point total. These Point Triggers and associated events are also fully customizable. .. image:: images/trigger-events.png :alt: Screenshot of Points trigger events @@ -57,12 +62,12 @@ Once you have decided and entered those options, go to the **Events** tab. Here, Campaign triggers ================= -**Modify Contact's Campaigns** - Add a Contact to or remove a Contact from any Campaigns you have published. +**Modify Contact's Campaigns** - Add a Contact to or remove a Contact from any Campaigns you have activated. Contact triggers ================ -**Modify Contact's Segments** - Add a Contact to or remove a Contact from any Segments you have published. +**Modify Contact's Segments** - Add a Contact to or remove a Contact from any Segments you have activated. **Modify Contact's tags** - Add or remove any Tags on the Contact record. If a Tag doesn't exist, you may create a new one in the edit window for this event. diff --git a/docs/reports/images/mautic-report-details.png b/docs/reports/images/mautic-report-details.png index 201c6469..8d11dc29 100644 Binary files a/docs/reports/images/mautic-report-details.png and b/docs/reports/images/mautic-report-details.png differ diff --git a/docs/reports/images/scheduled-report.png b/docs/reports/images/scheduled-report.png new file mode 100644 index 00000000..382ad830 Binary files /dev/null and b/docs/reports/images/scheduled-report.png differ diff --git a/docs/reports/reports.rst b/docs/reports/reports.rst index a3f9057f..fc065d69 100644 --- a/docs/reports/reports.rst +++ b/docs/reports/reports.rst @@ -88,13 +88,13 @@ The parent data source provides a high-level summary of the data while the child * **Published** - Select **Yes** to ensure that the Report is active, ready to send when scheduled in the Report options. -* **System Report** - Select **Yes** so that all Users can access the Report. If set to No, only the owner of the Report and Users with permission to view others' Reports can see the Report. +* **Visible for all logged-in Users** - Select **Yes** so that all Users can access the Report. If set to No, only the owner of the Report and Users with permission to view others' Reports can see the Report. -* **Owner** - Select the owner of the Report to determine who can see the Report if the System Report setting is No. +* **Owner** - Select the owner of the Report to determine who can see the Report if the 'Visible for all logged-in Users' setting is No. * **Dynamic filters settings** - - Show opened by default - If you want to ensure that the date filters and filter options for any other Report filters are visible on a Report detail page without needing to open the filters drop-down, select Yes. For example, for an Emails Report, you might want to view dynamic filters for subject or sent date. + - Opened by default - If you want to ensure that the date filters and filter options for any other Report filters are visible on a Report detail page without needing to open the filters drop-down, select Yes. For example, for an Emails Report, you might want to view dynamic filters for subject or sent date. - Hide date range - To hide the date range filter so that Users can't change the dates that the Report displays data for, select to **Yes**. @@ -162,6 +162,12 @@ Alternatively, you can select Weekdays to send the Report on the first or last w Once you've set all of the options you'd like in the **Details**, **Data**, **Graphs**, and **Schedule** tabs, click **Save & Close** to save the Report. Clicking **Apply** saves the progress you've made on building the Report and keeps you in the edit mode. +You can identify scheduled Reports in the list of Reports from Mautic 5.1 and later by the paper aeroplane icon next to the Report name. + +.. image:: images/scheduled-report.png + :align: center + :alt: Screenshot of Mautic Scheduled Report showing a paper aeroplane icon + .. vale off Cron job to schedule Reports diff --git a/docs/requirements.txt b/docs/requirements.txt index 0a6fb17b..7a8a8cfb 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,11 +1,11 @@ # File: requirements.txt # Defining the exact version will make sure things don't break -sphinx==6.2.1 -sphinx_rtd_theme==1.2.0 +sphinx==8.0.2 +sphinx_rtd_theme==3.0.0 readthedocs-sphinx-search==0.3.2 -rstcheck==6.1.1 -myst-parser==1.0.0 -linkify-it-py==2.0.0 -esbonio==0.16.0 -attrs==22.2.0 +rstcheck==6.2.4 +myst-parser==4.0.0 +linkify-it-py==2.0.3 +esbonio==0.16.5 +attrs==24.2.0 diff --git a/docs/segments/images/create-segment.png b/docs/segments/images/create-segment.png index 8300b541..fce81391 100644 Binary files a/docs/segments/images/create-segment.png and b/docs/segments/images/create-segment.png differ diff --git a/docs/segments/images/filtering.png b/docs/segments/images/filtering.png index abe17c1f..266b9b14 100644 Binary files a/docs/segments/images/filtering.png and b/docs/segments/images/filtering.png differ diff --git a/docs/segments/manage_segments.rst b/docs/segments/manage_segments.rst index 3dfbece8..41606770 100644 --- a/docs/segments/manage_segments.rst +++ b/docs/segments/manage_segments.rst @@ -33,11 +33,11 @@ Creating a Segment :width: 700 :alt: Screenshot showing creating a Segment. -* **Public Segment** - This option determines if the Segment is available for all Users to see and use, or only the User who created the Segment. +* **Visible to other Users** - This option determines if the Segment is available for all Users to see and use, or only the User who created the Segment. * **Available in Preference Center** - If set to **Yes**, Contacts can see and opt into or out of the Segment on a **Preference Center** page. The Segments display if the Preference Center has the **Segment List** slot type. -* **Published** - If set to **No**, the Segment won't be available for use in filters for other Segments, as a Contact source in Campaigns, modify Segment actions, etc. You'll still see the Segment in your **Segment list**, but it essentially won't exist anywhere else in Mautic. +* **Active** - If set to **No**, the Segment won't be available for use in filters for other Segments, as a Contact source in Campaigns, modify Segment actions, etc. You'll still see the Segment in your **Segment list**, but it essentially won't exist anywhere else in Mautic. On the Details tab, static, and dynamic Segments also have the option to display a different public name for a Segment. @@ -436,6 +436,8 @@ Beside this you can specify your date with text. These formulas are **translatab * ``this week`` / ``last week`` / ``next week`` * ``this month`` / ``last month`` / ``next month`` * ``this year`` / ``last year`` / ``next year`` +* ``first day of previous month`` / ``first day of January 2022`` +* ``last day of previous month`` / ``last day of January 2022`` Example (Consider that today is ``2022-03-05``): @@ -444,6 +446,8 @@ Example (Consider that today is ``2022-03-05``): * ``Date identified equals last month`` returns all Contacts identified in the specified date range, for example 2022-02-01 - 2022-02-28. * ``Date identified greater or equal last year`` returns all Contacts identified 2021-01-01 and after. * ``Date identified greater than last year`` returns all Contacts identified after 2021-12-31. +* ``Date identified greater than first day of previous month`` returns all Contacts identified after 2022-02-01. +* ``Date identified greater than last day of previous month`` returns all Contacts identified after 2022-02-28. * ``Custom Contact date field equal birthday -1 day`` returns all Contacts identified every year on 03-04 (4th march). * ``Custom Contact date field equal anniversary -1 month`` returns all Contacts identified every year on 02-04 (4th february) @@ -496,15 +500,15 @@ It's necessary to configure the :ref:`cron jobs`. .. vale off -Deleting or unpublishing a Segment +Deleting or deactivating a Segment ********************************** .. vale on -Since :xref:`Mautic 4` there is a step when deleting or unpublishing a Segment to ensure that it's not required as a filter by an existing Segment. +Since :xref:`Mautic 4` there is a step when deleting or deactivating a Segment to ensure that it's not required as a filter by an existing Segment. .. image:: images/deleting-used-segment.png :width: 300 - :alt: Screenshot deleting or unpublishing a Segment + :alt: Screenshot deleting or deactivating a Segment -If you attempt to delete or unpublish a Segment which is in use by a filter in another Segment, an alert prompts you to edit the other Segment, removing the dependency before you delete the Segment. \ No newline at end of file +If you attempt to delete or deactivate a Segment which is in use by a filter in another Segment, an alert prompts you to edit the other Segment, removing the dependency before you delete the Segment. \ No newline at end of file diff --git a/docs/stages/stages.rst b/docs/stages/stages.rst index 19b35927..964fba97 100644 --- a/docs/stages/stages.rst +++ b/docs/stages/stages.rst @@ -30,7 +30,7 @@ Navigate to the **Stages** section in the left side menu, and then click **+New* **Category** - Assign a Category to help you organize your Stages. For more information, see :ref:`categories`. -**Publish options** - The dashboard widget doesn't display data for an unpublished Stage. In addition, the Segment filters or Campaign conditions don't display the Stage. To avoid using the Stage while building it, set a future publish date and time. If you want the Stage to become unavailable after a certain time, set the date and time for unpublishing. +**Activation options** - The dashboard widget doesn't display data for an inactive Stage. In addition, the Segment filters or Campaign conditions don't display the Stage. To avoid using the Stage while building it, set a future activation date and time. If you want the Stage to become unavailable after a certain time, set the date and time for deactivating. .. vale off diff --git a/docs/themes/manage_themes.rst b/docs/themes/manage_themes.rst index 923c5fc2..079dd7ae 100644 --- a/docs/themes/manage_themes.rst +++ b/docs/themes/manage_themes.rst @@ -104,6 +104,33 @@ To preview a Theme: .. vale off +Hiding a Theme +************** + +.. vale on + +Users can't remove default Themes, but they can hide them from the list of Themes in the Email and Landing Page builders. + +To hide a Theme: + +1. Log in to Mautic. + +2. Click the **Settings** icon. + +3. Click **Themes**. + +4. In the Themes section, locate the Theme that you want to hide. + +5. Select the drop-down before the Theme, and click **Hide**. + +6. Mautic moves the Theme to the bottom of the table and show it in grey, which hides it within builders. +.. vale off + +To revert this change open the context menu of the hidden Theme and click **Unhide**. +.. vale on + +.. vale off + Downloading a Theme ******************* diff --git a/docs/translations/translations.rst b/docs/translations/translations.rst index 3446001b..5322f1e7 100644 --- a/docs/translations/translations.rst +++ b/docs/translations/translations.rst @@ -89,7 +89,7 @@ GitHub has also an option to search for strings in the repository - it's not par Try searching for 'Dashboard menu' within the Mautic/Mautic repository, as there is special translation for the menu item and another for the page title. GitHub won't find the right translation when you search for just 'Dashboard' - it requires the full string. Next, use the filter to show only INI files. Here is the link to the search result: -`https://github.com/mautic/mautic/search?l=INI&q=Dashboard+menu `_ +:xref:`Mautic INI files` The first file found is ``app/bundles/DashboardBundle/Translations/en_US/messages.ini`` and there is the line ``mautic.dashboard.menu.index="Dashboard"`` within the file, which is text to override. diff --git a/docs/troubleshooting/file_ownership_permissions.rst b/docs/troubleshooting/file_ownership_permissions.rst index 45063e8f..f4693b9f 100644 --- a/docs/troubleshooting/file_ownership_permissions.rst +++ b/docs/troubleshooting/file_ownership_permissions.rst @@ -110,6 +110,6 @@ To reset the ownership of files and folders, use the following command - ensurin .. vale off -This command **ch-**anges **own-**ership, using the ``-R`` flag which means recursively - including all files/folders within that location. Read more about the :xref:`Linux chown command`. +This command **ch-** anges **own-** ership, using the ``-R`` flag which means recursively - including all files/folders within that location. Read more about the :xref:`Linux chown command`. .. vale on diff --git a/docs/troubleshooting/troubleshooting.rst b/docs/troubleshooting/troubleshooting.rst index ca338828..83b486ce 100644 --- a/docs/troubleshooting/troubleshooting.rst +++ b/docs/troubleshooting/troubleshooting.rst @@ -113,7 +113,7 @@ This error reported is: This means that the memory limit that Apache has available is too low. Edit the ``memory_limit`` in the ``php.ini`` configuration file. -Read more about this in :doc:`./troubleshooting/working_with_resource_limits`. +Read more about this in :doc:`/troubleshooting/working_with_resource_limits`. A required PHP extension is missing =================================== diff --git a/docs/users_roles/images/mautic-users.png b/docs/users_roles/images/mautic-users.png index f683039e..f4627972 100644 Binary files a/docs/users_roles/images/mautic-users.png and b/docs/users_roles/images/mautic-users.png differ diff --git a/docs/users_roles/managing_roles.rst b/docs/users_roles/managing_roles.rst index 2299e432..3b09aa67 100644 --- a/docs/users_roles/managing_roles.rst +++ b/docs/users_roles/managing_roles.rst @@ -57,7 +57,7 @@ To configure a Role, leave the **Full System Access** switch at **No** and click :width: 800 :alt: Screenshot showing Mautic Roles -5. Most permission Categories have options for **View**, **Edit**, **Create**, **Delete**, and **Publish**. Select checkboxes for the appropriate permissions for this Role. To select every checkbox and grant the User all permissions, select the **Full** option. +5. Most permission Categories have options for **View**, **Edit**, **Create**, **Delete**, and **Active**. Select checkboxes for the appropriate permissions for this Role. To select every checkbox and grant the User all permissions, select the **Full** option. Explaining the permission options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -72,15 +72,15 @@ There are several options for selecting permissions: * **Delete** - this allows the Users with this Role to delete resources in this part of Mautic -* **Publish** - this allows the Users with this Role to make resources in this part of Mautic available by publishing them +* **Activate** - this allows the Users with this Role to make resources in this part of Mautic available by activating them * **Full** - this allows the Users with this Role all of the permissions. There are permission levels relating to resources the User has created themselves, and those created by others: -* **Own** - this allows the Users with this Role to ``view/edit/delete/publish`` their own resources in this part of Mautic, but not those created by others +* **Own** - this allows the Users with this Role to ``view/edit/delete/activate`` their own resources in this part of Mautic, but not those created by others -* **Others** - this allows the Users with this Role to ``view/edit/delete/publish`` their own resources in this part of Mautic, and those created by others +* **Others** - this allows the Users with this Role to ``view/edit/delete/activate`` their own resources in this part of Mautic, and those created by others There are permission levels relating to being able to manage resources: @@ -92,6 +92,8 @@ There are permission levels relating to the editable fields in the Users section * **All** - this allows the Users with this Role to edit all fields relating to the Users section +Since Mautic 5.1 there is an additional permission relating to allowing Users of Mautic to export information. You can set this permission within the Contact, Forms, and Reports Permissions. If this permission isn't set, the User won't see the options for, or be able to export, information - such as lists of Contacts, Form submissions and Report data - from Mautic. + .. note:: User permissions restrict their view of dashboard widgets, resulting in them only seeing widgets for items or feature bundles they have permission to see.