From 450a965d64b14f38e1d3058012b1603c735537cd Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Fri, 6 May 2022 15:33:47 -0400 Subject: [PATCH] suggested doc changes for #7492 - single sorted list of settings - single copy of commands in admin guide - cross link related sections of User and API guide - keep branding images directives together (Oliver was right) - style/consistency tweaks --- .../7492_muting_notifications.md | 8 ++- .../source/admin/user-administration.rst | 49 +++++++------- doc/sphinx-guides/source/api/native-api.rst | 2 + .../source/installation/config.rst | 66 ++++--------------- doc/sphinx-guides/source/user/account.rst | 2 + 5 files changed, 49 insertions(+), 78 deletions(-) diff --git a/doc/release-notes/7492_muting_notifications.md b/doc/release-notes/7492_muting_notifications.md index ca298aab1ae..e67991b8334 100644 --- a/doc/release-notes/7492_muting_notifications.md +++ b/doc/release-notes/7492_muting_notifications.md @@ -1 +1,7 @@ -This release has a new feature that allows users to control which notifications they receive. How to enable this feature and which options can be set by the admins is described in the [Letting users manage receiving notifications section of the Admin Guide](https://guides.dataverse.org/en/latest/admin/user-administration.html#letting-users-manage-receiving-notifications). +This release has a new feature that allows users to control which notifications they receive. How to enable this feature and which options can be set by the admins is described in the [Letting users manage receiving notifications section of the Admin Guide](https://guides.dataverse.org/en/latest/admin/user-administration.html#letting-users-manage-receiving-notifications). + +## New DB Settings + +- :ShowMuteOptions +- :AlwaysMuted +- :NeverMuted diff --git a/doc/sphinx-guides/source/admin/user-administration.rst b/doc/sphinx-guides/source/admin/user-administration.rst index db489f9e8b7..2c3911482c2 100644 --- a/doc/sphinx-guides/source/admin/user-administration.rst +++ b/doc/sphinx-guides/source/admin/user-administration.rst @@ -76,46 +76,49 @@ Using the API token 7ae33670-be21-491d-a244-008149856437 as an example: You should expect the output ``DELETE 1`` after issuing the command above. +.. _mute-notifications: -Letting users manage receiving notifications --------------------------------------------- +Letting Users Manage Notifications +----------------------------------- -You can let users manage which notification types they wish to receive by using the following setting: +See :ref:`account-notifications` in the User Guide for how notifications are described to end users. + +You can let users manage which notification types they wish to receive by setting :ref:`:ShowMuteOptions` to "true": ``curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:ShowMuteOptions`` -This enables the new feature in the notifications page. The users can then select which in-app notifications and/or e-mails they wish to receive out of the following list: +This enables additional settings for each user in the notifications tab of their account page. The users can select which in-app notifications and/or e-mails they wish to receive out of the following list: +* ``APIGENERATED`` API token is generated * ``ASSIGNROLE`` Role is assigned -* ``REVOKEROLE`` Role is revoked -* ``CREATEDV`` Dataverse is created -* ``CREATEDS`` Your dataset is created -* ``CREATEACC`` Account is created -* ``SUBMITTEDDS`` Submitted for review -* ``RETURNEDDS`` Returned from review -* ``PUBLISHEDDS`` Dataset is published -* ``REQUESTFILEACCESS`` Access to file is requested -* ``GRANTFILEACCESS`` Access to file is granted -* ``REJECTFILEACCESS`` Access to file is rejected -* ``FILESYSTEMIMPORT`` Dataset has been successfully uploaded and verified -* ``CHECKSUMIMPORT`` Dataset had file checksums added via a batch job * ``CHECKSUMFAIL`` Checksum validation failed +* ``CHECKSUMIMPORT`` Dataset had file checksums added via a batch job * ``CONFIRMEMAIL`` Email Verification -* ``APIGENERATED`` API token is generated -* ``INGESTCOMPLETED`` Ingest is completed +* ``CREATEACC`` Account is created +* ``CREATEDS`` Your dataset is created +* ``CREATEDV`` Dataverse is created +* ``DATASETCREATED`` Dataset was created by user +* ``FILESYSTEMIMPORT`` Dataset has been successfully uploaded and verified +* ``GRANTFILEACCESS`` Access to file is granted * ``INGESTCOMPLETEDWITHERRORS`` Ingest completed with errors +* ``INGESTCOMPLETED`` Ingest is completed +* ``PUBLISHEDDS`` Dataset is published * ``PUBLISHFAILED_PIDREG`` Publish has failed -* ``WORKFLOW_SUCCESS`` External workflow run has succeeded -* ``WORKFLOW_FAILURE`` External workflow run has failed +* ``REJECTFILEACCESS`` Access to file is rejected +* ``REQUESTFILEACCESS`` Access to file is requested +* ``RETURNEDDS`` Returned from review +* ``REVOKEROLE`` Role is revoked * ``STATUSUPDATED`` Status of dataset has been updated -* ``DATASETCREATED`` Dataset was created by user +* ``SUBMITTEDDS`` Submitted for review +* ``WORKFLOW_FAILURE`` External workflow run has failed +* ``WORKFLOW_SUCCESS`` External workflow run has succeeded After enabling this feature, all notifications are enabled by default, until this is changed by the user. -You can then shorten this list by configuring some notification types (e.g., ``ASSIGNROLE`` and ``REVOKEROLE``) to be always muted for everyone and not manageable by users (not visible in the user interface) with the following setting: +You can shorten this list by configuring some notification types (e.g., ``ASSIGNROLE`` and ``REVOKEROLE``) to be always muted for everyone and not manageable by users (not visible in the user interface) with the :ref:`:AlwaysMuted` setting: ``curl -X PUT -d 'ASSIGNROLE,REVOKEROLE' http://localhost:8080/api/admin/settings/:AlwaysMuted`` -Finally, you can set some notifications (e.g., ``REQUESTFILEACCESS``, ``GRANTFILEACCESS`` and ``REJECTFILEACCESS``) as always enabled for everyone and not manageable by users (grayed out in the user interface) with the following setting: +Finally, you can set some notifications (e.g., ``REQUESTFILEACCESS``, ``GRANTFILEACCESS`` and ``REJECTFILEACCESS``) as always enabled for everyone and not manageable by users (grayed out in the user interface) with the :ref:`:NeverMuted` setting: ``curl -X PUT -d 'REQUESTFILEACCESS,GRANTFILEACCESS,REJECTFILEACCESS' http://localhost:8080/api/admin/settings/:NeverMuted`` diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 5c56166dd6a..75cc5e0999c 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -2836,6 +2836,8 @@ Show Info About Single Metadata Block Notifications ------------- +See also :ref:`account-notifications` in the User Guide. + Get All Notifications by User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/sphinx-guides/source/installation/config.rst b/doc/sphinx-guides/source/installation/config.rst index 8251489728d..9e3cba2ab39 100644 --- a/doc/sphinx-guides/source/installation/config.rst +++ b/doc/sphinx-guides/source/installation/config.rst @@ -657,6 +657,10 @@ The image below indicates that the page layout consists of three main blocks: a |dvPageBlocks| +.. To edit, use dvBrandingCustBlocks.drawio with https://app.diagrams.net +.. |dvPageBlocks| image:: ./img/dvBrandingCustBlocks.png + :class: img-responsive + Installation Name/Brand Name ++++++++++++++++++++++++++++ @@ -2719,75 +2723,29 @@ To remove the override and go back to the default list: ``curl -X PUT -d '' http://localhost:8080/api/admin/settings/:FileCategories`` +.. _:ShowMuteOptions: + :ShowMuteOptions ++++++++++++++++ Enables muting of the notifications by the users. By default, this setting is "false" and users cannot mute any notifications (this feature is not shown in the user interface). -This setting is a boolean value. To turn the feature on: - -``curl -X PUT -d 'true' http://localhost:8080/api/admin/settings/:ShowMuteOptions`` - -To remove the override and turn this feature off: - -``curl -X PUT -d 'false' http://localhost:8080/api/admin/settings/:ShowMuteOptions`` - -The existing notification types are as follows: -* ``ASSIGNROLE`` Role is assigned -* ``REVOKEROLE`` Role is revoked -* ``CREATEDV`` Dataverse is created -* ``CREATEDS`` Your dataset is created -* ``CREATEACC`` Account is created -* ``SUBMITTEDDS`` Submitted for review -* ``RETURNEDDS`` Returned from review -* ``PUBLISHEDDS`` Dataset is published -* ``REQUESTFILEACCESS`` Access to file is requested -* ``GRANTFILEACCESS`` Access to file is granted -* ``REJECTFILEACCESS`` Access to file is rejected -* ``FILESYSTEMIMPORT`` Dataset has been successfully uploaded and verified -* ``CHECKSUMIMPORT`` Dataset had file checksums added via a batch job -* ``CHECKSUMFAIL`` Checksum validation failed -* ``CONFIRMEMAIL`` Email Verification -* ``APIGENERATED`` API token is generated -* ``INGESTCOMPLETED`` Ingest is completed -* ``INGESTCOMPLETEDWITHERRORS`` Ingest completed with errors -* ``PUBLISHFAILED_PIDREG`` Publish has failed -* ``WORKFLOW_SUCCESS`` External workflow run has succeeded -* ``WORKFLOW_FAILURE`` External workflow run has failed -* ``STATUSUPDATED`` Status of dataset has been updated -* ``DATASETCREATED`` Dataset was created by user +For configuration details, see :ref:`mute-notifications`. + +.. _:AlwaysMuted: :AlwaysMuted ++++++++++++ Overrides the default empty list of always muted notifications. Always muted notifications cannot be unmuted by the users. Always muted notifications are not shown in the notification settings for the users. -This setting is a comma-separated list of the notification types. - -To override the default empty list with ASSIGNROLE, REVOKEROLE: - -``curl -X PUT -d 'ASSIGNROLE,REVOKEROLE' http://localhost:8080/api/admin/settings/:AlwaysMuted`` - -To remove the override and go back to the empty list: +For configuration details, see :ref:`mute-notifications`. -``curl -X PUT -d '' http://localhost:8080/api/admin/settings/:AlwaysMuted`` +.. _:NeverMuted: :NeverMuted +++++++++++ Overrides the default empty list of never muted notifications. Never muted notifications cannot be muted by the users. Always muted notifications are grayed out and are not adjustable by the user. -This setting is a comma-separated list of the notification types. - -To override the default empty list with REQUESTFILEACCESS, GRANTFILEACCESS, REJECTFILEACCESS: - -``curl -X PUT -d 'REQUESTFILEACCESS,GRANTFILEACCESS,REJECTFILEACCESS' http://localhost:8080/api/admin/settings/:NeverMuted`` - -To remove the override and go back to the empty list: - -``curl -X PUT -d '' http://localhost:8080/api/admin/settings/:NeverMuted`` - -.. To edit, use dvBrandingCustBlocks.drawio with https://app.diagrams.net -.. |dvPageBlocks| image:: ./img/dvBrandingCustBlocks.png - :class: img-responsive - \ No newline at end of file +For configuration details, see :ref:`mute-notifications`. diff --git a/doc/sphinx-guides/source/user/account.rst b/doc/sphinx-guides/source/user/account.rst index 4c343ff85d4..d2f9334d552 100755 --- a/doc/sphinx-guides/source/user/account.rst +++ b/doc/sphinx-guides/source/user/account.rst @@ -155,6 +155,8 @@ The My Data section of your account page displays a listing of all the Dataverse You can use the Add Data button to create a new Dataverse collection or dataset. By default, the new Dataverse collection or dataset will be created in the root Dataverse collection, but from the create form you can use the Host Dataverse collection dropdown menu to choose a different Dataverse collection, for which you have the proper access privileges. However, you will not be able to change this selection after you create your Dataverse collection or dataset. +.. _account-notifications: + Notifications -------------