Update docs: Adding Custom Fields to the Registration Page by sarina · Pull Request #1451 · openedx/docs.openedx.org

sarina · 2026-05-07T20:52:21Z

Continuing the PR begun in #1429

PR: openedx/frontend-app-authn#1595 Restore "Adding Custom Fields to Registration" How-To Guide Context
This PR restores the documentation guide for adding custom fields to the registration page in the Authn MFE. This guide was previously removed from the repository, but there is no clear trace of when or why it was deleted from the codebase.

The original file is: https://github.com/openedx/frontend-app-authn/blob/63d16364fc2aa6538dd876bd3f6fd5612a20d605/docs/how_tos/adding_custom_fields_to_the_registration.rst#b-add-fields-that-do-not-exist-in-the-user-profile-model

Problem
The documentation for extending registration fields is currently missing from the repository, making it difficult for operators to:

Understand how to add custom fields to the registration page Configure REGISTRATION_EXTRA_FIELDS properly
Extend the UserProfile model with custom fields
Integrate custom forms with the Authn MFE
This documentation is essential for organizations that need to collect additional user information during registration beyond the standard fields (email, username, password, name).

Documentation Location
The restored documentation is located at:

docs/how_tos/adding_custom_fields_to_the_registration.rst

Key Topics Covered
Introduction to custom registration fields
Difference between required and optional fields
Step-by-step configuration for existing fields
Advanced guide for custom UserProfile field extensions Backend and frontend integration requirements
Configuration examples for different deployment methods Testing
I followed up the instructions and everything is working as expected

PR: openedx/frontend-app-authn#1595 Restore "Adding Custom Fields to Registration" How-To Guide Context This PR restores the documentation guide for adding custom fields to the registration page in the Authn MFE. This guide was previously removed from the repository, but there is no clear trace of when or why it was deleted from the codebase. The original file is: https://github.com/openedx/frontend-app-authn/blob/63d16364fc2aa6538dd876bd3f6fd5612a20d605/docs/how_tos/adding_custom_fields_to_the_registration.rst#b-add-fields-that-do-not-exist-in-the-user-profile-model Problem The documentation for extending registration fields is currently missing from the repository, making it difficult for operators to: Understand how to add custom fields to the registration page Configure REGISTRATION_EXTRA_FIELDS properly Extend the UserProfile model with custom fields Integrate custom forms with the Authn MFE This documentation is essential for organizations that need to collect additional user information during registration beyond the standard fields (email, username, password, name). Documentation Location The restored documentation is located at: docs/how_tos/adding_custom_fields_to_the_registration.rst Key Topics Covered Introduction to custom registration fields Difference between required and optional fields Step-by-step configuration for existing fields Advanced guide for custom UserProfile field extensions Backend and frontend integration requirements Configuration examples for different deployment methods Testing I followed up the instructions and everything is working as expected

sarina · 2026-05-07T20:54:39Z

-Add Custom Fields to the Registration Page
-*********************************************
+**********************************
+Two Main Ways to Add Custom Fields


@efortish I'm confused by this document's structure. Theres' this heading "Two Main Ways to Add Custom Fields" but after these, there are two MORE headings, "Configuring Custom Registration Fields on the Back-End" and "Configuring Dynamic Registration Fields in Authn". How do they relate to each other?

sarina · 2026-05-07T20:55:12Z

+   the registration form, and optional fields will appear on the progressive
+   profiling form.
+
+Redefine Settings Above by Using the Tutor Plugin


@efortish why is using site configurations recommended over a Tutor plugin?

sarina · 2026-05-07T20:55:35Z

+additional actions that you need  to perform:
+
+#. Extend user profile model with new fields. An external plugin should be used for
+   this. **New fields must be migrated to the database.**


@efortish how is this migration performed, it's not described.

sarina · 2026-05-07T20:56:31Z

+#. Create a form with additional user profile fields and pass the path to this
+   form into ``settings``. The form can also be created in the Open edX plugin.
+   `Edx-cookiecutters <https://github.com/openedx/edx-cookiecutters>`_ can be
+   used for the plugin creation.


@efortish should this be the first step in this section? The first step says "Extend user profile model with new fields" but this step seems to actually describe creating a plugin. It's a bit confusing, if you could please elaborate.

sarina · 2026-05-07T20:57:09Z

+
+#. Install your custom form app and configure it in LMS. Follow the steps
+   outlined in the official Open edX documentation to configure custom
+   registration fields for your instance: `Customize the Registration Page <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/customize_registration_page.html>`_.


@efortish this link is broken, but appears to just be a link to this page. As-written this sentence doesn't make a ton of sense.

sarina · 2026-05-07T20:57:51Z

+   the ``ENABLE_DYNAMIC_REGISTRATION_FIELDS`` setting in the settings file. This
+   setting should be added to the plugin where the extension form is placed.
+
+   .. note:: See the context view for the Logistration page: `user_authn API Context View <https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/user_authn/api/views.py#L61>`_.


@efortish this link is broken I think because it's just a link to a line in the middle of a docstring. What should it link to?

sarina · 2026-05-07T20:58:04Z

+   .. note:: See the context view for the Logistration page: `user_authn API Context View <https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/user_authn/api/views.py#L61>`_.
+
+#. Add fields to the extended profile fields list. Add your `custom field
+   <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/retrieve_extended_profile_metadata.html>`_


@efortish this link is broken, but appears to just be a link to this page. As-written this sentence doesn't make a ton of sense.

sarina · 2026-05-07T20:58:49Z

+   to the ``extended_profile_fields`` list to ensure it is checked correctly
+   during registration.
+
+   .. warning:: If this step is missed, fields from the extension form will not be saved. For more information, please see the condition in: `helper.py <https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/user_authn/api/helper.py#L97>`_.


@efortish can you double check this links to the right line of code? https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/user_authn/api/helper.py#L97

musaabhasan

This restores an important operator guide for custom registration fields. I left one correctness note on the setting name because this is the kind of copy-paste detail that can make the documented configuration appear to apply while the Authn MFE still does not receive dynamic fields.

musaabhasan · 2026-05-09T17:15:50Z

+
+.. code-block:: python
+
+      ENABLE_DYNAMIC_REGISTRATION_FIELD = True,


This should be ENABLE_DYNAMIC_REGISTRATION_FIELDS with the plural FIELDS, and the same correction is needed in the second code block below. The singular setting name would be a no-op for operators following the guide, so they could complete the steps and still not enable dynamic registration fields. While touching this block, it would also be worth fixing required/optionl/hidden to required/optional/hidden.

Apgomeznext and others added 9 commits April 15, 2026 16:53

Update Pr

99bc5ca

PR fixes

786daa2

fix pr

364d2e2

pr fixes

d894e84

fix PR

8db52bb

pr fixes

1c48463

temp: Adjust RST to unbreak build

b2236c9

temp: Formatting and language fixes

39f7a8c

This was referenced May 7, 2026

Update docs: Adding Custom Fields to the Registration Page #1429

Closed

docs: adding custom fields documentation step by step openedx/frontend-app-authn#1595

Closed

sarina requested a review from efortish May 7, 2026 20:53

sarina commented May 7, 2026

View reviewed changes

musaabhasan reviewed May 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs: Adding Custom Fields to the Registration Page#1451

Update docs: Adding Custom Fields to the Registration Page#1451
sarina wants to merge 9 commits intomainfrom
sarina/1429

sarina commented May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

sarina May 7, 2026

Uh oh!

musaabhasan left a comment

Uh oh!

musaabhasan May 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		.. code-block:: python

		ENABLE_DYNAMIC_REGISTRATION_FIELD = True,

Conversation

sarina commented May 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

musaabhasan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants