Add audit log docs, fixes #65

user-manual/add-edit-content/archival-descriptions.rst

@@ -8,6 +8,10 @@ Archival Descriptions
    :height: 18
    :width: 18
 
+.. |gears| image:: images/gears.png
+   :height: 18
+   :width: 18
+
 Archival descriptions are one of the core :ref:`entity-types` in AtoM and
 provide users with invaluable contextual infomation about the resources held
 by an :term:`archival institution`.
@@ -96,6 +100,7 @@ to:**
 * :ref:`change-display-standard`
 * :ref:`add-alternative-id`
 * :ref:`rename-title-slug`
+* :ref:`view-modification-history`
 * :ref:`Move an archival description <move-archival-description>`
 * :ref:`Delete an archival description <delete-archival-description>`
 
@@ -1260,6 +1265,100 @@ the filename of a linked digital object will be covered on the
 
 :ref:`Back to top <archival-descriptions>`
 
+.. _view-modification-history:
+
+View the modification history of an archival description
+========================================================
+
+AtoM has a basic audit log for archival descriptions that can be enabled by an
+:term:`administrator` in |gears| **Admin > Settings > Global** - see: 
+:ref:`enable-audit-logging`. 
+
+Once enabled, AtoM will capture basic information (including date, type, 
+associated user, and/or associated description) when archival descriptions are 
+created or modified. 
+
+.. IMPORTANT:: 
+
+   For :term:`archival description` modifications to be tracked by AtoM, an
+   :term:`administrator` must **first** have enabled the 
+   :ref:`enable-audit-logging` setting. Any description creation or modification 
+   events prior to enabling the setting will not be tracked. 
+
+After the setting has been enabled, authenticated (i.e. logged in) users with 
+sufficient :term:`permissions <access privilege>` can see the modification 
+history of an archival description using the "More" button found in the 
+:term:`button block` at the bottom of a description's :term:`view page`. To do
+so: 
+
+1. Navigate to the :term:`view page` of the archival description whose audit log
+   you would like to see. You can do this by :ref:`browsing <browse>` or
+   :ref:`searching <search-atom>` for the :term:`archival description` - see
+   :ref:`Access content <access-content>` for more information on navigation
+   in AtoM.
+2. In the :term:`button block` at the bottom of the description's view page, 
+   click on the More menu, and select "View modification history."
+
+.. image:: images/more-mod-history.*
+   :align: center
+   :width: 80%
+   :alt: The more menu in AtoM, expanded to show the "View modification history"
+         option.
+
+.. NOTE::
+
+   If the "View modification history" option is not present in the More menu, 
+   this is likely because the audit log has not been enabled by an 
+   :term:`administrator`. See: :ref:`enable-audit-logging`.
+
+3. AtoM will redirect you to the Modifications :term:`view page` for the related
+   archival description. The page includes a table with 3 columns: 
+
+   * **Date**: Includes the date and time the change was made. The date and time 
+     values are determined based on the PHP time zone settings, which can be 
+     modified by a system administrator in the ``apps/qubit/config/settings.yml`` 
+     configuration file. For more information, see: 
+     :ref:`customization-config-files`.
+   * **Type**: Either Creation, or Modification. Deletions and other events are 
+     not currently tracked. 
+   * **User**: The :term:`username` of the user associated with the modification. 
+     Note that for administrators, these usernames will appear as hyperlinks - an
+     administrator can click the hyperlink to navigate to the related user's 
+     :term:`profile <user profile>` page, where a full history of that user's 
+     desrciption modifications can be seen. For more information, see: 
+     :ref:`user-modification-history`. 
+
+.. image:: images/mod-history-1.*
+   :align: center
+   :width: 80%
+   :alt: An image of the Modification history page for an archival description
+
+.. NOTE:: 
+
+   For records created or modified via actions performed via the command-line 
+   interface (such as a CSV import, etc), no associated :term:`username` will 
+   be shown. In the image above, the record was created via a command-line EAD
+   XML import - as such, the User field for the associated modification is 
+   empty. 
+
+4. The number of results included in the Modifications page is determined by 
+   the :ref:`results-page` setting in |gears| **Admin > Settings > Global**. 
+   If there are more results than the results per page setting, AtoM will 
+   display a pager at the bottom of the page, to allow you to page through 
+   the results.  
+
+.. image:: images/mod-history-2.*
+   :align: center
+   :width: 80%
+   :alt: An image of the Modification history page for an archival description
+
+.. SEEALSO::
+
+   * :ref:`enable-audit-logging`
+   * :ref:`user-modification-history`
+
+:ref:`Back to top <archival-descriptions>`
+
 .. _move-archival-description:
 
 Move an archival description

user-manual/administer/manage-user-accounts.rst

@@ -318,6 +318,162 @@ A new user can also be added to AtoM from the :term:`view page` of any other
 
 :ref:`Back to top <manage-user-accounts>`
 
+.. _user-modification-history:
+
+View a user's description modification history
+==============================================
+
+AtoM has a basic audit log for archival descriptions that can be enabled by an
+:term:`administrator` in |gears| **Admin > Settings > Global**. Once enabled, 
+AtoM will capture basic information (including date, type, associated user, 
+and/or associated description) when archival descriptions are created or 
+modified. 
+
+.. IMPORTANT:: 
+
+   For :term:`archival description` modifications to be tracked by AtoM, an
+   :term:`administrator` must **first** have enabled the 
+   :ref:`enable-audit-logging` setting. Any description creation or modification 
+   events prior to enabling the setting will not be tracked. 
+
+Authenticated (i.e. logged in) users can see their own modification history by
+navigating to their profile page. Additionally, an :term:`administrator` can 
+see the description modification history of any user by navigating to their
+:term:`user profile` page. 
+
+**Jump to:**
+
+* :ref:`view-own-mod-history`
+* :ref:`view-user-mod-history`
+
+.. SEEALSO::
+
+   * :ref:`enable-audit-logging`
+   * :ref:`view-modification-history`
+
+.. _view-own-mod-history:
+
+Viewing your own modification history
+-------------------------------------
+
+If you are logged in, and the audit log has been enabled by an 
+:term:`administrator` in |gears| **Admin > Settings > Global**, then you can 
+view a log of all your creation and modification events associated with archival 
+descriptions in AtoM. To do so: 
+
+1. Click your :term:`username` in the :term:`header bar`, at the upper
+   right-hand corner of the page
+2. A :term:`drop-down menu` will appear with the option to log out, or
+   navigate to your :term:`user profile` - click on "Profile"
+
+.. image:: images/click-profile.*
+   :align: center
+   :width: 85%
+   :alt: An image of a user clicking on the Profile option
+
+3. You will be redirected to your user profile :term:`view page`. If 
+   description logging has been enabled, then you will see a section at the 
+   bottom of the profile labelled "Editing history" - click the heading to 
+   expand the section.
+4. When expanded, the Editing history :term:`area <information area>` will
+   display information about recent creation and modification events
+   associated with your :term:`username`, organized into a table. The Title 
+   column will include a hyperlink to the related description. The Date column 
+   will show the date and time the modification was made. The Type column has 
+   2 possible values - "creation" and "modification."
+
+.. image:: images/audit-log-editor.*
+   :align: center
+   :width: 85%
+   :alt: An image of the Editing history of a user account
+
+.. TIP::
+
+   The date and time values are determined based on the PHP time zone
+   settings, which can be modified by a system administrator in the
+   ``apps/qubit/config/settings.yml`` configuration file. For more
+   information, see:
+
+   * :ref:`customization-config-files`
+
+5. The number of results included in the Editing history pane is determined by
+   the :ref:`results-page` setting in **Admin > Settings > Global**. If there
+   are more results than the results per page setting, AtoM will display 
+   "Previous" and "Next" buttons at the bottom of the table for navigation. 
+
+.. image:: images/audit-log-admin.*
+   :align: center
+   :width: 85%
+   :alt: An image of the Editing history of a user account
+
+
+.. _view-user-mod-history:
+
+Viewing other user's modification histories
+-------------------------------------------
+
+If the audit log has been enabled by an :term:`administrator` in |gears| 
+**Admin > Settings > Global**, then an administrator can view the 
+:term:`archival description` editing history of any :term:`user account` in 
+AtoM. To do so: 
+
+1. In the :term:`main menu` located in the :term:`header bar`, click the
+   |gears| :ref:`Admin <main-menu-admin>` menu and select "Users" from the
+   :term:`drop-down menu`. This will take you to a list of current user
+   accounts.
+
+.. image:: images/admin-users.*
+   :align: center
+   :width: 30%
+   :alt: An image of the Admin menu
+
+2. AtoM will redirect you to the List users page, where you can find, edit,
+   and delete existing users, as well as add new users.
+
+.. image:: images/browse-users.*
+   :align: center
+   :width: 80%
+   :alt: An image of the List users page
+
+3. Select a user from the list that appears on the page by clicking on the
+   :term:`username`. AtoM will direct you to that :term:`user's profile <user
+   profile>` :term:`view page`.
+4. If description logging has been enabled, then at the bottom of the user's 
+   profile :term:`view page`, you will see a section labelled "Editing history" 
+   - click the heading to expand the section.
+5. When expanded, the Editing history :term:`area <information area>` will
+   display information about recent creation and modification events
+   associated with the selected user, organized into a table. The Title 
+   column will include a hyperlink to the related description. The Date column 
+   will show the date and time the modification was made. The Type column has 
+   2 possible values - "creation" and "modification."
+
+.. image:: images/audit-log-editor.*
+   :align: center
+   :width: 85%
+   :alt: An image of the Editing history of a user account
+
+.. TIP::
+
+   The date and time values are determined based on the PHP time zone
+   settings, which can be modified by a system administrator in the
+   ``apps/qubit/config/settings.yml`` configuration file. For more
+   information, see:
+
+   * :ref:`customization-config-files`
+
+5. The number of results included in the Editing history pane is determined by
+   the :ref:`results-page` setting in **Admin > Settings > Global**. If there
+   are more results than the results per page setting, AtoM will display 
+   "Previous" and "Next" buttons at the bottom of the table for navigation. 
+
+.. image:: images/audit-log-admin.*
+   :align: center
+   :width: 85%
+   :alt: An image of the Editing history of a user account
+
+:ref:`Back to top <manage-user-accounts>`
+
 .. _edit-user:
 
 Edit an existing user

user-manual/administer/search-updates.rst

@@ -67,10 +67,32 @@ administrators can easily add new updates to the clipboard for export.
    - if you flip the "Type" to a different :term:`entity`, the Repository filter 
    will be hidden. 
 
-6. If searching for *Archival description*, set "Publication status" to either
+6. If an :term:`administrator` has enabled the archival description audit log
+   (via the :ref:`enable-audit-logging` setting in |gears| **Admin > Settings 
+   > Global**), then an additional "User" filter will be available. This is an
+   autocomplete field linked to user accounts, that will allow you to filter 
+   the results returned based on the modification history of a specific user. 
+   To filter results by a specific user, start typing the target :term:`username`
+   into the autocomplete field, and select the matching result from the 
+   drop-down field that will appear below. 
+
+.. image:: images/updates-user-filter.*
+   :align: center
+   :width: 90%
+   :alt: An image of the User filter on the Description updates page in AtoM
+
+.. NOTE::
+
+   The User filter will not be visible on the Description updates page if the
+   audit log has not first been enabled via the Global settings. Only changes
+   that have occurred **after** the audit log has been enabled will return
+   results when the User filter is used on Description updates. For more 
+   information, see: :ref:`enable-audit-logging`. 
+
+7. If searching for *Archival description*, set "Publication status" to either
    *published* or *draft* records, or both (i.e. *All*).
 
-7. Select the range of time you for which you want to return results, using
+8. Select the range of time you for which you want to return results, using
    the Start and End date fields in the Date range area. When you click into
    one of the fields, AtoM will display a drop-down graphical date-picker you
    can use to select the desired date; alternatively, you can type a date into
@@ -81,7 +103,7 @@ administrators can easily add new updates to the clipboard for export.
    :width: 90%
    :alt: An image of the Datepicker on the Description updates page in AtoM
 
-8. When you have configured the filter options as you wish, click the "Search"
+9. When you have configured the filter options as you wish, click the "Search"
    button to apply them - AtoM will reload the page and display your results
    below the filters. Alternatively, you can click the "Reset" button to clear
    the existing values from the filters.
@@ -93,12 +115,12 @@ administrators can easily add new updates to the clipboard for export.
    results per page, but an :term:`administrator` can change this. For more
    infomation, see: :ref:`results-page`.
 
-9. You can add results directly to the :term:`Clipboard` using the links in
-   the right-hand column of the results table. To add all the results
-   displayed on a page, click the "All" link at the top of the column. For
-   more information on working with the Clipboard, see: :ref:`clipboard`.
+10. You can add results directly to the :term:`Clipboard` using the links in
+    the right-hand column of the results table. To add all the results
+    displayed on a page, click the "All" link at the top of the column. For
+    more information on working with the Clipboard, see: :ref:`clipboard`.
 
-10. You can click on the blue hyperlinked names in the Title column to navigate
+11. You can click on the blue hyperlinked names in the Title column to navigate
     directly to a specific record.
 
 .. seealso::
@@ -108,5 +130,6 @@ administrators can easily add new updates to the clipboard for export.
    * :ref:`archival-institutions`
    * :ref:`terms`
    * :ref:`functions`
+   * :ref:`enable-audit-logging`
 
 :ref:`Back to top <search-updates>`