diff --git a/docs/index.rst b/docs/index.rst index f5e34f8a0..ff6a0649a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -105,6 +105,13 @@ There are different types of documentation available to help you navigate your w categories/categories-overview +.. toctree:: + :maxdepth: 2 + :caption: Projects + :hidden: + + projects/projects-overview + .. toctree:: :caption: Channels :maxdepth: 2 diff --git a/docs/projects/images/add_entities_to_project_button.png b/docs/projects/images/add_entities_to_project_button.png new file mode 100644 index 000000000..512ab0231 Binary files /dev/null and b/docs/projects/images/add_entities_to_project_button.png differ diff --git a/docs/projects/images/assign_project_from_email.png b/docs/projects/images/assign_project_from_email.png new file mode 100644 index 000000000..a42309a0a Binary files /dev/null and b/docs/projects/images/assign_project_from_email.png differ diff --git a/docs/projects/images/create_new_project_form.png b/docs/projects/images/create_new_project_form.png new file mode 100644 index 000000000..12f5bff1e Binary files /dev/null and b/docs/projects/images/create_new_project_form.png differ diff --git a/docs/projects/images/delete_selected_projects.png b/docs/projects/images/delete_selected_projects.png new file mode 100644 index 000000000..7045fb268 Binary files /dev/null and b/docs/projects/images/delete_selected_projects.png differ diff --git a/docs/projects/images/delete_single_project.png b/docs/projects/images/delete_single_project.png new file mode 100644 index 000000000..5f920df9e Binary files /dev/null and b/docs/projects/images/delete_single_project.png differ diff --git a/docs/projects/images/edit_project_from_dashboard.png b/docs/projects/images/edit_project_from_dashboard.png new file mode 100644 index 000000000..da0f2f297 Binary files /dev/null and b/docs/projects/images/edit_project_from_dashboard.png differ diff --git a/docs/projects/images/edit_project_from_detail.png b/docs/projects/images/edit_project_from_detail.png new file mode 100644 index 000000000..0404aae6f Binary files /dev/null and b/docs/projects/images/edit_project_from_detail.png differ diff --git a/docs/projects/images/projects_list_view.png b/docs/projects/images/projects_list_view.png new file mode 100644 index 000000000..c45f260e2 Binary files /dev/null and b/docs/projects/images/projects_list_view.png differ diff --git a/docs/projects/images/remove_item_from_project.png b/docs/projects/images/remove_item_from_project.png new file mode 100644 index 000000000..57828fd0b Binary files /dev/null and b/docs/projects/images/remove_item_from_project.png differ diff --git a/docs/projects/images/search_projects_list.png b/docs/projects/images/search_projects_list.png new file mode 100644 index 000000000..c4555d947 Binary files /dev/null and b/docs/projects/images/search_projects_list.png differ diff --git a/docs/projects/projects-overview.rst b/docs/projects/projects-overview.rst new file mode 100644 index 000000000..9516f8944 --- /dev/null +++ b/docs/projects/projects-overview.rst @@ -0,0 +1,222 @@ +.. vale off + +Projects +######## + +.. vale on + +Projects give you one place to group everything that belongs to a single marketing initiative. Instead of hunting for the Campaigns, Emails, Segments, and other entities behind a launch, you assign them all to a Project and manage them together. A Project works like a folder that spans entity types, so you can see how the pieces of an initiative fit together and find related entities quickly. + +You can assign many entity types to a Project, including: + +.. vale off + +* :doc:`Assets ` +* :doc:`Campaigns ` +* :doc:`Companies ` +* :doc:`Dynamic Web Content ` +* :doc:`Emails ` +* :doc:`Focus Items ` +* :doc:`Forms ` +* :doc:`Landing Pages ` +* :doc:`Marketing Messages ` +* :doc:`Points ` +* :doc:`Segments ` +* :doc:`Stages ` +* :doc:`Text messages ` + +.. vale on + +.. vale off + +Managing Projects +***************** + +.. vale on + +To open the Projects list, select Projects in the left main menu. From here, you can create a new Project, open an existing one, and delete Projects you no longer need. The list shows each Project along with the number of entities assigned to it. + +.. image:: images/projects_list_view.png + :align: center + :alt: Projects list showing the New button and the Projects entry in the left menu + +| + +.. vale off + +Creating Projects +================= + +.. vale on + +To create a Project: + +#. Select **New**. +#. Give it a name and an optional description. + +.. image:: images/create_new_project_form.png + :align: center + :alt: Create new Project screen with Name and Description fields + +| + +Each Project name must be unique. If you enter a name that's already in use, Mautic displays 'A project with this name already exists.' and asks you to choose another. + +.. vale off + +Editing Projects +================ + +.. vale on + +You can edit a Project's name and description at any time. There are two ways to do this. + +#. **From the Projects list:** + + #. Click the three-dots icon next to the Project you want to edit. + #. Click **Edit** to open the Edit Project screen. + #. Edit the Project and click **Save** or **Save & Close** to save it. + + .. image:: images/edit_project_from_dashboard.png + :align: center + :alt: Projects list with the Options menu open and the Edit action highlighted + + | + +#. **From the Project's detail view:** + + #. Click the Project name to open its detail view. + #. Click **Edit** at the top to open the Edit Project screen. + #. Edit the Project and click **Save** or **Save & Close** to save it. + + .. image:: images/edit_project_from_detail.png + :align: center + :alt: Project detail view with the Edit button highlighted at the top + + | + +.. vale off + +Deleting Projects +================= + +.. vale on + +There are two ways to delete Projects. + +#. **To delete one or more Projects at once:** + + #. Select the checkbox of the Projects you want to delete. Selecting a checkbox automatically opens a blue banner on top of the table. + #. Click **Delete selected**. + #. Confirm the deletion. + + .. image:: images/delete_selected_projects.png + :align: center + :alt: Projects list with two Projects selected and the Delete selected banner + + | + +#. **To delete a single Project:** + + #. Click the three-dots icon next to the Project you want to delete. + #. Select **Delete**. + #. Confirm the deletion. + + .. image:: images/delete_single_project.png + :align: center + :alt: Projects list with the Options menu open and the Delete action highlighted + + | + +Deleting a Project removes the references to it from every assigned entity, but it doesn't delete the entities themselves. + +.. vale off + +Assigning entities to a Project +=============================== + +.. vale on + +There are two ways to assign entities to a Project. + +#. **From the entity** - When you create or edit a supported entity, such as an Email or a Campaign, use the Projects field to assign it to one or more Projects. If you have permission to create Projects, you can also type a new name in this field and select **Hit enter to create** to make a new Project on the spot. + + | + + .. image:: images/assign_project_from_email.png + :align: center + :alt: Email edit view with the Projects field used to assign the Email to a Project + + | + +#. **From the Project**: + + #. Open a Project and select **Add Entities to Project**. + + | + + .. image:: images/add_entities_to_project_button.png + :align: center + :alt: Project detail view highlighting the Add Entities to Project button + + | + + #. Choose the type of entity you want to add. + #. Select the entity you want to add to the Project. + +.. vale off + +Deleting entities from Projects +=============================== + +.. vale on + +To delete an entity from a Project: + +#. Click the three-dots icon next to the entity you want to remove. +#. Click the **Remove from project** button. +#. Confirm the removal. + +.. image:: images/remove_item_from_project.png + :align: center + :alt: Options menu on a Project entity showing the Remove from project action + +| + +.. vale off + +Finding entities by Project +=========================== + +.. vale on + +To see entities assigned to a Project, go to the Project dashboard. From the Projects list, select the Project's name or the entities label in the **# Entities** column. Both open the Project's detail view, where Mautic lists every assigned entity grouped by type. From here, you can also remove entities or add new ones. + +If you have many Projects, use the search bar at the top of the Projects list to find one quickly: + +#. Type the Project's name. +#. Press **Enter**. +#. Select the Project's name or its entities label to open it. + +.. image:: images/search_projects_list.png + :align: center + :alt: Projects list with a Project name typed in the search bar and the entities label highlighted + +| + +.. vale off + +Permissions +*********** + +.. vale on + +Projects use their own permission set, which you can grant per Role. To configure these permissions: + +#. Go to **Settings** > **Roles** +#. Open or create a Role +#. Find the **Project permissions** section. + +Alongside the standard **View**, **Edit**, **Create**, **Delete**, and **Full** permissions, there's a separate **Associate with other entities** permission that controls whether a User can attach entities to and detach entities from Projects. A User needs this permission to use the Projects field on an entity or the add and remove actions on a Project. + +For more information on creating Roles and configuring their permissions, see :ref:`Roles overview` and :ref:`Setting Role permissions `.