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?

Dear @sarina
Agree, should we merge the context of those 2 extra headings in the main 2 headings? Because I see that is a good explanation about how to configure it.

What do you think? I'm not completely into how to design this kind of documentation so I'd love to hear what you think.

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 , Honestly I do not know, I've been always using a tutor plugin in real environments to set this, however I think the original author of this guide thought that with site_configurations through the admin could be easier, maybe.

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.

Dear @sarina

Actually, In my personal case I have an external application which extends edx-platform it has its own migrations that are run automatlely when we run tutor dev/local launch or runing tutor local exec lms bash -c "./manage.py lms migrate" beacuse the app is installed in INTALLED_APPS.

Idk how the original author was extending the profile/user model but I think it was something similar.

What you think?

Maybe we can add a brief explanation saying something like I said before.

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.

I think the same, actually I think the form's creation should have its own document and just reference it here because it is describing how to create the plugin indeed.

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?

I'll investigate because I have no idea where it should be aiming.

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.

Actually the name is FIELDS in plural, youre right, it is a typo on this documentation.

sarina · 2026-05-15T19:30:15Z

@efortish could I get a review on this?

efortish

Dear @sarina

IMO this guide is useful but it has a lot of gray areas, unfortunately I do not have full context on what was the intention of the original author, besides that I think we are not far of having this ready, just a little tweaks to make it more clear.

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

efortish reviewed May 21, 2026

View reviewed changes


		.. 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!

efortish May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

Choose a reason for hiding this comment

Uh oh!

sarina commented May 15, 2026

Uh oh!

efortish left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

efortish May 21, 2026 •

edited

Loading