docs: Update retirement docs

Add some details around extending retirement steps

scripts/user_retirement/docs/driver_setup.rst

@@ -1,6 +1,5 @@
 .. _driver-setup:
 
-#############################################
 Setting Up the User Retirement Driver Scripts
 #############################################
 
@@ -65,19 +64,16 @@ For example: ``['RETIRING_CREDENTIALS', 'CREDENTIALS_COMPLETE', 'CREDENTIALS',
 a pre-instantiated ``retire_learner`` method in the ``CredentialsApi``, then set
 the user's state to ``CREDENTIALS_COMPLETE``.
 
-********
 Examples
 ********
 
 The following are some examples of how to use the driver scripts.
 
-==================
 Set Up Environment
 ==================
 
 Follow this `readme <https://github.com/openedx/edx-platform/tree/master/scripts/user_retirement#readme>`_ to set up your execution environment.
 
-=========================
 List of Targeted Learners
 =========================
 
@@ -93,7 +89,6 @@ state for the time specified ``cool_off_days``).
        --output_dir=learners_to_retire \
        --cool_off_days=5
 
-=====================
 Run Retirement Script
 =====================
 
@@ -110,4 +105,3 @@ several INI files, each containing a single line in the form of ``USERNAME
 
 
 .. include:: ../../../../links/links.rst
-

scripts/user_retirement/docs/extending_retirement.rst

@@ -0,0 +1,14 @@
+.. _extending-retirement:
+
+Extending The Retirement Pipeline
+#################################
+
+Often times Open edX is used in conjunction with other systems. For example, a university may have an email provider that is used to contact students. In this case, it may be desirable to extend the retirement pipeline to include a step that calls the email provider's deletion API when a user is retired in Open edX.
+
+Currently, the retirement code only supports a handful of services (LMS, Ecommerce, Course Discovery, and some historical 3rd party providers) so it is necessary to add your extension point to one of those services or to have a separate process that uses the retirement APIs outside of the pipeline scripts that currently exist.
+
+There are two main ways to extend the retirement pipeline in its current form:
+
+#. Inside the LMS, a Django Signal is emitted when a user is retired. You can create an edx-platform plugin that listens for this signal and take appropriate action from the LMS. The signal is named `USER_RETIRE_LMS_MISC` and it is defined in `openedx.core.djangoapps.user_api.accounts.signals`.
+
+#. Use the retirement APIs to find recently retired users and have an entirely out of band process to propagate them out in the time period between when the user is retired and when the retirement data is completely removed from the system. This would involve using or replicating `utils/edx_api.py`'s LmsApi to find users (ex: `get_learners_by_date_and_status` method to find users in the `COMPLETE` status that were last touched in the last 24 hours). You could then use the returned user data to find the user in the external system and delete them. This method does not provide the same guarantees as the first, but it does allow for more flexibility in the actions that can be taken.

scripts/user_retirement/docs/implementation_overview.rst

@@ -1,6 +1,5 @@
 .. _Implmentation:
 
-#######################
 Implementation Overview
 #######################
 
@@ -11,11 +10,10 @@ these services. As a consequence, to remove a user's PII, you must be able
 to request each service containing PII to remove, delete, or unlink the
 data for that user in that service.
 
-In the user retirement feature, a centralized process (the *driver* scripts) 
-orchestrates all of these requests. For information about how to configure the 
+In the user retirement feature, a centralized process (the *driver* scripts)
+orchestrates all of these requests. For information about how to configure the
 driver scripts, see :ref:`driver-setup`.
 
-****************************
 The User Retirement Workflow
 ****************************
 
@@ -49,9 +47,8 @@ possible states required by all members of the Open edX community.
 This example state diagram outlines the pathways users follow throughout the
 workflow:
 
-.. graphviz::
-    digraph retirement_states_example {
-        ranksep = "0.3";
+.. digraph:: retirement_states_example
+   :align: center
 
         node[fontname=Courier,fontsize=12,shape=box,group=main]
         { rank = same INIT[style=invis] PENDING }
@@ -69,7 +66,6 @@ workflow:
             labelloc = b  // put label at bottom
             {rank = same ERRORED COMPLETE ABORTED}
         }
-    }
 
 Unless an error occurs internal to the user retirement tooling, a user's
 retirement state should always land in one of the terminal states.  At that
@@ -78,7 +74,6 @@ point, either their entry should be cleaned up from the
 administrator needs to examine the error and resolve it. For more information,
 see :ref:`recovering-from-errored`.
 
-*******************
 The User Experience
 *******************
 
@@ -103,7 +98,6 @@ enabled, allowing account deletions to queue up.  The
 ``ENABLE_ACCOUNT_DELETION`` feature in django settings toggles the visibility
 of this section.  See :ref:`django-settings`.
 
-================
 Third Party Auth
 ================
 

scripts/user_retirement/docs/index.rst

@@ -1,13 +1,12 @@
 .. _Enabling User Retirement:
 
-####################################
 Enabling the User Retirement Feature
 ####################################
 
-There have been many changes to privacy laws (for example, GDPR or the 
-European Union General Data Protection Regulation) intended to change the way 
-that businesses think about and handle Personally Identifiable Information 
-(PII). 
+There have been many changes to privacy laws (for example, GDPR or the
+European Union General Data Protection Regulation) intended to change the way
+that businesses think about and handle Personally Identifiable Information
+(PII).
 
 As a step toward enabling Open edX to support some of the key updates in privacy
 laws, edX has implemented APIs and tooling that enable Open edX instances to
@@ -22,7 +21,7 @@ the basic setup, but also to offer some insight into the implementation of the
 user retirement feature in order to help the Open edX community build
 additional APIs and states that meet their special needs. Custom code,
 plugins, packages, or XBlocks in your Open edX instance might store PII, but
-this feature will not magically find and clean up that PII. You may need to 
+this feature will not magically find and clean up that PII. You may need to
 create your own custom code to include PII that is not covered by the user
 retirement feature.
 
@@ -33,6 +32,6 @@ retirement feature.
    service_setup
    driver_setup
    special_cases
+   extending_retirement
 
 .. include:: ../../../../links/links.rst
-

scripts/user_retirement/docs/service_setup.rst

@@ -1,6 +1,5 @@
 .. _Service Setup:
 
-#####################################
 Setting Up User Retirement in the LMS
 #####################################
 
@@ -9,7 +8,6 @@ in the Open edX LMS.
 
 .. _django-settings:
 
-***************
 Django Settings
 ***************
 
@@ -36,13 +34,13 @@ defining *derived* settings specific to Open edX. Read more about it in
      - ``'retired.invalid'``
      - The domain part of hashed emails. Used in ``RETIRED_EMAIL_FMT``.
    * - RETIRED_USERNAME_FMT
-     - ``lambda settings: 
+     - ``lambda settings:
        settings.RETIRED_USERNAME_PREFIX + '{}'``
      - The username field for a retired user gets transformed into this format,
        where ``{}`` is replaced with the hash of their username.
    * - RETIRED_EMAIL_FMT
-     - ``lambda settings: 
-       settings.RETIRED_EMAIL_PREFIX + '{}@' + 
+     - ``lambda settings:
+       settings.RETIRED_EMAIL_PREFIX + '{}@' +
        settings.RETIRED_EMAIL_DOMAIN``
      - The email field for a retired user gets transformed into this format, where
        ``{}`` is replaced with the hash of their email.
@@ -61,8 +59,6 @@ defining *derived* settings specific to Open edX. Read more about it in
      - True
      - Whether to display the "Delete My Account" section the account settings page.
 
-
-=================
 Retirement States
 =================
 
@@ -79,10 +75,10 @@ state at the beginning, and ``COMPLETED``, ``ERRORED``, and ``ABORTED`` states
 at the end of the list.  Also, for every ``RETIRING_foo`` state, there must be
 a corresponding ``foo_COMPLETE`` state.
 
-Override these states if you need to add any states.  Typically, these 
+Override these states if you need to add any states.  Typically, these
 settings are set in ``lms.yml``.
 
-After you have defined any custom states, populate the states table with the 
+After you have defined any custom states, populate the states table with the
 following management command:
 
 .. code-block:: bash
@@ -114,13 +110,12 @@ list in settings.
 
 .. _retirement-service-user:
 
-***********************
 Retirement Service User
 ***********************
 
 The user retirement driver scripts authenticate with the LMS and IDAs as the
 retirement service user with oauth client credentials.  Therefore, to use the
-driver scripts, you must create a retirement service user, and generate a DOT 
+driver scripts, you must create a retirement service user, and generate a DOT
 application and client credentials, as in the following command.
 
 .. code-block:: bash
@@ -144,7 +139,6 @@ in Django settings:
 
    RETIREMENT_SERVICE_WORKER_USERNAME = 'retirement_service_worker'
 
-************
 Django Admin
 ************
 
@@ -162,7 +156,7 @@ that relate to user retirement.
      - ``/admin/user_api/retirementstate/``
      - Represents the table of states defined in ``RETIREMENT_STATES`` and
        populated with ``populate_retirement_states``.
-   * - User Retirement Requests 
+   * - User Retirement Requests
      - ``/admin/user_api/userretirementrequest/``
      - Represents the table that tracks the user IDs of every learner who
        has ever requested account deletion. This table is primarily used for
@@ -173,7 +167,7 @@ that relate to user retirement.
 
 In special cases where you may need to manually intervene with the pipeline,
 you can use the User Retirement Statuses management page to change the
-state for an individual user.  For more information about how to handle these 
+state for an individual user.  For more information about how to handle these
 cases, see :ref:`handling-special-cases`.
 
 .. include:: ../../../../links/links.rst

scripts/user_retirement/docs/special_cases.rst

@@ -1,6 +1,5 @@
 .. _handling-special-cases:
 
-######################
 Handling Special Cases
 ######################
 
@@ -19,8 +18,9 @@ re-tried.  You can do this using the Django admin. In this example, a user
 retirement errored during forums retirement, so we manually reset their state
 from ``ERRORED`` to ``ENROLLMENTS_COMPLETE``.
 
-.. graphviz::
-    digraph G {
+.. digraph:: retirement_states_example
+   :align: center
+
       //rankdir=LR;  // Rank Direction Left to Right
       ranksep = "0.3";
 
@@ -48,7 +48,6 @@ from ``ERRORED`` to ``ENROLLMENTS_COMPLETE``.
       }
 
       ERRORED -> ENROLLMENTS_COMPLETE[style="bold,dashed",color=black,label=" via django\nadmin"]
-    }
 
 Now, the user retirement driver scripts will automatically resume this user's
 retirement the next time they are executed.