Merge branch 'main' into configurable_stream_extensions

.all-contributorsrc

@@ -68,6 +68,15 @@
       "contributions": [
         "doc"
       ]
+    },
+    {
+      "login": "Amiyah14",
+      "name": "Emily",
+      "avatar_url": "https://avatars.githubusercontent.com/u/45315891?v=4",
+      "profile": "https://github.com/Amiyah14",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.github/workflows/linting.yml

@@ -1,35 +1,31 @@
 name: Linting
 on:
-  # Note: onlyAnnotateModifiedLines only works correctly on PRs!
-  # If you need to run checks on push as well, create a separate workflow file.
   pull_request:
 
 jobs:
   prose:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
     - name: Vale
-      uses: errata-ai/vale-action@master
+      uses: errata-ai/vale-action@reviewdog
       with:
-        # We can modify these styles as we want
-        styles: |
-          https://github.com/errata-ai/Google/releases/latest/download/Google.zip
-        onlyAnnotateModifiedLines: true
+        # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
+        version: 2.29.2
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   build:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
-    - uses: actions/setup-python@v2
+    - uses: actions/setup-python@v4
       with:
         python-version: '3.x'
         cache: 'pip'

.gitpod.Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.10
+
+# 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
+
+WORKDIR /workspace
+
+# Needed for Vale (rst2html) and reStructuredText (rstcheck)
+RUN pip install rst2html rstcheck
+
+RUN mkdir -p vale && cd vale && wget https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz && \
+    tar -xf vale_${VALE_VERSION}_Linux_64-bit.tar.gz && cp /workspace/vale/vale /usr/local/bin/vale && cd ../
+
+# /home/gitpod/.local/bin ensures that Python packages like rstcheck can be found
+ENV PATH=/home/gitpod/.local/bin:$PATH
+
+# Create the gitpod user. UID must be 33333. https://www.gitpod.io/docs/configure/workspaces/workspace-image#use-a-custom-dockerfile
+RUN useradd -l -u 33333 -G sudo -md /home/gitpod -s /bin/bash -p gitpod gitpod
+
+USER gitpod

README.md

@@ -1,6 +1,6 @@
 [![Documentation Status][RTD badge URL]][RTD URL]
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation)
@@ -21,22 +21,26 @@ For more background, our end goal, and to let us know if you want to help, pleas
 
 To make a small change to the base language files for the documentation, use the 'edit file' button on the documentation and commit your changes. This creates a new Pull Request.
 
-To make more complex changes you need to clone this repository and work on your local computer.
-
-1. Install a code editor, [Visual Studio Code](https://code.visualstudio.com) is recommended as it automatically installs all the extensions you need.
-2. Install [Github CLI](https://cli.github.com/) which makes it much easier to work with Git commands
-3. Create a working folder on your local computer
-4. Open a terminal and navigate to that folder using the command `cd <path/to/folder>`
-5. Type `gh repo clone mautic/user-documentation` - you may be prompted to authenticate with GitHub the first time you do this
-6. Open the folder user-documentation that is created in your editor
-7. At the bottom left of your screen you will see the default branch called 'main' is showing as your active branch. Click this, and at the top of the page will show a box where you can select 'create a new branch'. Type a name which relates to the work you plan to do. Once you do this, the bottom left will change from 'main' to the name of the branch you created. At any time you can click back into that, and change back to 'main'.
-8. Now you are working on your own branch for this change, make the changes that you need to make by editing the files, which you should see on the left pane.
-9. Use the Source Control icon on the menu on the left, to view the files you have changed. Click the plus icon next to them to 'stage' them for committing. This allows you to save files in chunks, explaining what you're doing with each chunk, rather than en-mass. It makes it easier to reverse small parts in the future.
-10. If you're making any changes to text, remember to run the commands below to update the files for translations on Transifex and include those in your PR.
-11. Once you've committed all your changes, click the Publish Branch button. This might prompt you to create a fork of the repository - that's fine.
-12. Once you've published the branch, look for the Branches section in the accordion menu under the Source Control icon. Find your branch and hover over the icon which says 'Create pull request' and click it.
-13. This will take you to the web interface of GitHub, where you can give an appropriate title and description for the changes you are proposing.
-14. If you need to make changes in the future after review, switch back to this branch as mentioned in step 7. Make the changes, and then follow steps 9-12. Update the pull request when you have completed your changes and committed and pushed them, to ask the reviewer to re-review after the updates.
+To make more complex changes, follow the steps below:
+
+1. Install a code editor. [Visual Studio Code](https://code.visualstudio.com) is recommended as it automatically installs all the extensions you need.
+2. Install [Github CLI](https://cli.github.com/) which simplifies Git commands.
+3. Create a working folder on your local computer.
+4. Open a terminal and navigate to that folder using the command `cd <path/to/folder>`.
+5. Fork the `mautic/user-documentation` repository on GitHub by clicking on the fork button at the top right.
+6. Once forked, if you know your way around Git and you are are writing documentation for something which is specific to the latest version of Mautic, you should branch from `main`.  
+
+If you are writing documentation for a feature which is coming in a future release - e.g. 5.0 - then branch off the relevant branch for that release, which should generally speaking match the branch used in the main mautic/mautic repository - e.g. `5.x`.
+7. Type `gh repo clone [your-forked-repo-name]/user-documentation` to clone your forked repository to your local computer.
+8. Open the folder `user-documentation` that is created in your editor.
+9. At the bottom left of your screen, you will see the default branch called 'main' is showing as your active branch. Click this, and a box will appear at the top of the page allowing you to 'create a new branch'. Type a name which relates to the work you plan to do.
+10. Make your desired changes by editing the files, which you can locate on the left pane.
+11. Use the Source Control icon on the menu on the left to view changed files. Click the plus icon next to them to 'stage' them for committing. This lets you save and describe changes in chunks, making it easier to reverse specific changes in the future.
+12. If editing text, ensure to run necessary commands to update files for translations on Transifex and include those updates in your PR.
+13. Commit all your changes, then click the 'Publish Branch' button. This action might prompt you to create a fork of the repository if not done earlier.
+14. Under the Source Control icon, navigate to the 'Branches' section. Find your branch, hover over the 'Create pull request' icon, and click it.
+15. This action will direct you to the GitHub web interface where you can add an appropriate title and description for your proposed changes.
+16. If reviewers request changes, switch back to the branch (as explained in step 9). Implement the necessary changes and follow steps 11-14 again. After updating, commit and push your changes, then notify the reviewer to check the updated content.
 
 ### Generating translations files
 
@@ -101,6 +105,9 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Moongazer"><img src="https://avatars.githubusercontent.com/u/1685510?v=4?s=100" width="100px;" alt="Moongazer"/><br /><sub><b>Moongazer</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=Moongazer" title="Documentation">📖</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/patrykgruszka"><img src="https://avatars.githubusercontent.com/u/8580942?v=4?s=100" width="100px;" alt="Patryk Gruszka"/><br /><sub><b>Patryk Gruszka</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=patrykgruszka" title="Documentation">📖</a></td>
     </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Amiyah14"><img src="https://avatars.githubusercontent.com/u/45315891?v=4?s=100" width="100px;" alt="Emily"/><br /><sub><b>Emily</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=Amiyah14" title="Documentation">📖</a></td>
+    </tr>
   </tbody>
 </table>
 

docs/authentication/authentication.rst

@@ -48,6 +48,23 @@ The IDP may ask for the following settings:
 
 #. Custom attributes - Mautic requires three custom attributes in the IDP responses for the User Email, first name and last name. Username is also supported but is optional. Configure the attribute names used by the IDP in Mautic's Configuration > User/Authentication Settings under the 'Enter the names of the attributes the configured IDP uses for the following Mautic User fields' section.
 
+Example: Azure SAML SSO
+=======================
+
+1) Register new Enterprise applications by navigating to ``Create your own Application`` and then ``Integrate any other application you don't find in the gallery (Non-gallery)``
+2) Go to Single Sign-On
+3) ``Identifier (Entity ID)`` - this is the site URL located at the top of User/Authentication Settings. Copy this exactly as is to the IDP.
+4) ``Reply URL (Assertion Consumer Service URL)`` - Use ``https://example.com/s/saml/login_check``
+5) Download Federation Metadata XML from 3. SAML Certificates
+6) Upload the downloaded Federation Metadata XML to Mautic
+7) X.509-Certificate isn't required
+8) Use the following for the custom attributes fields:
+
+E-Mail: ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress``
+First Name: ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname``
+Last Name: ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname``
+Username (optional): ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress``
+
 Logging in
 ==========
 
@@ -62,4 +79,4 @@ To turn off SAML, click the Remove link to the right of the Identity provider me
 
 .. image:: images/authentication-settings.png
   :width: 800
-  :alt: Screenshot of the authentication settings section
+  :alt: Screenshot of the authentication settings section

docs/configuration/settings.rst

@@ -188,6 +188,8 @@ Mail send settings
     For more information see :doc:`Mailer is owner</channels/emails>`
 
 * **Service to send mail through** - Select the Email service provider you use, and enter your credentials. 
+
+See :ref:`here<contact's unsubscribe email preferences>` to set the Contact's Email subscription preferences.
 
 Default frequency rule
 ======================

docs/contacts/contacts_overview.rst

@@ -0,0 +1,70 @@
+
+Contacts
+#########
+
+
+Contacts are the central factor of a marketing automation platform. 
+
+These are all the individuals who have visited your websites or interacted with you in some way.
+
+Contact types
+**************
+
+There are two types of Contacts:
+
+Visitors (formerly anonymous leads)
+===================================
+
+Unidentified visitors to your site who haven't yet completed a Form or otherwise interacted with your site.
+
+Mautic tracks these Contacts, but usually keeps them hidden so as not to clutter up your view.
+
+Visitors are worth tracking, because these could be future customers. By tracking them before they have any interaction, you can retain a log of when they visited your site, which allows you to get a picture of their activity prior to engaging with you.
+
+You can use the filter in the Contacts screen to display only visitors by using the this command ``is:anonymous`` in the search bar at the top of the Contacts list.
+
+.. image:: images/contacts-anonymous.png
+   :alt: Screenshot of anonymous Contact
+
+**What you see** - Switching to the anonymous Contacts view displays the IP addresses for visitors to Landing Pages tracked with your Mautic tracking code. 
+If you have an IP lookup service :ref:`configured<miscellaneous settings>` in **Settings > System Settings > Miscellaneous Settings**, Mautic shows an approximate location of the Contacts. Mautic uses :xref:`MaxMind's` Geolite2 City by default. MaxMind approximates the location based on the Contact's Internet Service Provider, and may not be the exact location of the Contact.
+
+**Individual Contacts** - Click an IP address to display a Contact record, similar to known Contacts. If there's any information on an anonymous Contact, you can see it here. This data can include:
+
+* Landing Pages the Contact has visited
+
+* Forms submitted
+
+* Scoring
+
+* Data from Forms - which don't include the unique identifier, since that would make the contact known
+
+.. note:: 
+
+    * In **Settings > Configuration > Tracking Settings**, you can enable the **Do Not Track 404 error for anonymous Contacts** option to not track page hits on any 404 error page tracked by the tracking code. This option helps prevent tracking pages you're not interested in and filling the Contact logs with bot activity. See :ref:`Tracking settings<tracking settings>`
+
+    * Data for anonymous Contacts isn't available for segmentation or reporting. Once identified, the data is available, which applies to non-Campaign based Dynamic Web Content filters.
+
+
+.. vale off
+
+Standard Contacts
+=================
+
+.. vale on
+
+The second type of Contact is a known Contact. These Contacts have identified themselves via a Form or other source. You may also have more information about them from previous interactions, or from a third-party system such as a Customer Relationship Management (CRM) tool.
+
+As a result, these Contacts typically have a name, Email, and other identifying information associated with the Contact.
+
+These are Contacts which may have started as a visitor, but at some point provided additional information such as a name, Email address, social network handle, or other identifying characteristics which have enabled you to connect up the activity on your website with a known person. You can nurture these Contacts through the Mautic marketing automation platform, learn more about their behavior, and take specific actions as a result of this information.
+
+
+Changing the view
+*****************
+
+By default Mautic uses the **list view**, but you can also choose to switch to the **card view** also known as **grid view**, which uses avatars to depict the Contacts visually using cards. 
+
+If you'd like to see your Contacts in the card view, click the **C** button while you're looking at the Contact list. To go back to the table or list view, press the **T** key.
+
+The :ref:`Manage Contacts<managing contacts>` section provides more information on how you can work with Contacts in Mautic.

docs/contacts/custom_fields.rst

@@ -1,6 +1,107 @@
 .. vale off
 
-Manage custom fields
+Manage Custom Fields
 ####################
 
-.. vale on
+.. vale on
+
+You can manage Custom Fields through the Admin menu - click the cogwheel upper right-hand side of Mautic.
+
+.. image:: images/admin-menu.png
+    :align: center
+    :alt: Screenshot of Admin menu
+    :width: 200
+
+Custom Fields
+*************
+
+The **Custom Fields** page lets you view all existing Contact fields as well as any custom Contact fields you have created.
+
+.. image:: images/custom-fields.jpeg
+    :align: center
+    :alt: Screenshot of Custom Field
+
+|
+
+You'll notice the group column shows the specific field on the Contact profile. In the last column, you may see several icons which signify various properties of the field:
+
+.. image:: images/custom-field-icons.png
+    :align: center
+    :alt: Screenshot of Custom field icons
+
+|
+
+1. **Lock icon** -  The core installation uses these fields, you can't remove them.
+
+2. **List icon** - You can use these fields as filters for Segments.
+
+3. **Asterisks icon** - These fields are required when filling in the Contact Form
+
+4. **Globe icon** - You can update these fields publicly through the :doc:`tracking pixel</configuration/variables>` URL query see :doc:`Contact Monitoring</contacts/manage_contacts>` for more details.
+
+It's important to note that from Mautic 5, you won't be able to edit the default value for any Fields used to identify a Contact or Company, including:
+
+* Email
+
+* Company
+
+* First name
+
+* Last name
+
+* Social profiles
+
+* Unique identifier fields
+
+* Company name
+
+* Company Email
+
+* Company website
+
+* State
+
+* Country
+
+* City
+
+Published fields
+*****************
+
+There is a toggle switch which shows before each label title. You can find this type of switch throughout the Mautic UI for publishing and unpublishing items.
+
+.. only:: html
+
+   .. figure:: images/unpublish-fields.gif
+
+|
+
+.. vale off
+
+Adding a new Custom Field
+*************************
+
+.. vale on
+
+You can create additional custom fields and define the data type you want that field to hold. In addition to the data type you select the group for that particular field. This defines where the field displays on the Contact edit and detail view.
+
+.. image:: images/new-custom-field.jpeg
+    :align: center
+    :alt: Screenshot of New Custom Field
+
+|
+
+Creating Custom Fields via a command
+************************************
+
+When you create a new Custom Field for Contacts or Companies in Mautic, the system adds a new column to the database. For larger instances of Mautic, this operation can slow down, and the table remains locked while running. As a result, you can't make any changes until the system creates the field. The ``HTTP`` request may time out, causing the User Interface to report that the column exists even though Contact/Company updates may fail because the column is still missing.
+
+There is a way around this when you configure the processing of field creation in the background.
+
+Since :xref:`Mautic 3` there is an option you can set in your ``app/config/local.php`` file: ``'create_custom_field_in_background' => true``,.
+
+If you configure this option, the new Custom Field becomes visible in the list of Custom Fields. The custom field remains unpublished until you run the command ``bin/console mautic:custom-field:create-column``. This command creates the actual column in the table and publishes the field metadata.
+
+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.