From 458375cb4230ea43140a07a88d481f967941ac9e Mon Sep 17 00:00:00 2001 From: Luis Felipe Castano Date: Thu, 10 Oct 2024 17:48:55 -0500 Subject: [PATCH 01/24] docs: add users api docs --- docs/how_to/users_api.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/how_to/users_api.rst diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst new file mode 100644 index 000000000..3d9ea90da --- /dev/null +++ b/docs/how_to/users_api.rst @@ -0,0 +1,15 @@ +# Creating custom registration fields + +## Description + + + +## Tenant settings + +To make this work, we must add the following settings to the microsite where we want to add the fields: + +### Example: Adding a custom field + +If, for example, we want to add the field `Organization name`, we will have to do the following: + +1. Add the field name, `org_name` for example, to `extended_profile_fields`. This indicates that `org_name` will be saved as an extended profile field. From 6095607c264e1256b5d97f7596e5fa4a63963776 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Fri, 11 Oct 2024 17:24:13 -0500 Subject: [PATCH 02/24] docs: add custom registration fields doc --- docs/how_to/users_api.rst | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 3d9ea90da..d64d7c99a 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -1,15 +1,38 @@ -# Creating custom registration fields +Extra Profile Fields +========== -## Description +**Creating custom registration fields** +**Tenant settings** +Add the following settings to the microsite where we want to add the fields: -## Tenant settings - -To make this work, we must add the following settings to the microsite where we want to add the fields: - -### Example: Adding a custom field +Example: Adding a custom field If, for example, we want to add the field `Organization name`, we will have to do the following: 1. Add the field name, `org_name` for example, to `extended_profile_fields`. This indicates that `org_name` will be saved as an extended profile field. + +.. code-block:: json + + "extended_profile_fields": [ "org_name" ] + +2. Add org_name to REGISTRATION_EXTRA_FIELDS, indicating whether the field is hidden, optional, or required: + +.. code-block:: json + + "REGISTRATION_EXTRA_FIELDS": { + "org_name": "required" + } + +3. In this step, we will create the custom field as a dictionary. In this case, we are going to create a text field for org_name. We must indicate: name, type, and label as the minimum: + +.. code-block:: json + + "EDNX_CUSTOM_REGISTRATION_FIELDS": [ + { + "name": "org_name", + "type": "text", + "label": "Organization name" + } + ] From 41fc41be90829a47ea8b79cf08063ee79a8085e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Fri, 11 Oct 2024 17:57:54 -0500 Subject: [PATCH 03/24] docs: add user create, update and get --- docs/how_to/users_api.rst | 130 +++++++++++++++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 2 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index d64d7c99a..3026a3388 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -1,5 +1,104 @@ -Extra Profile Fields -========== +Users API Documentation +======================= + +**Get User** + +URL: ``/eox-core/api/v1/user/`` + +Method: GET + +Query Params: + + username (String) + + email (String) + +Example: + + http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe + + http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com + + +Response Example: + +.. code-block:: json + + 200 OK + + { + "account_privacy": "private", + "profile_image": { + "has_image": false, + "image_url_full": "http://tenant-a.local.edly.io:8000/static/images/profiles/default_500.png", + "image_url_large": "http://tenant-a.local.edly.io:8000/static/images/profiles/default_120.png", + "image_url_medium": "http://tenant-a.local.edly.io:8000/static/images/profiles/default_50.png", + "image_url_small": "http://tenant-a.local.edly.io:8000/static/images/profiles/default_30.png" + }, + "username": "johndoe", + "bio": null, + "course_certificates": null, + "country": null, + "date_joined": "2024-07-18T17:19:10Z", + "language_proficiencies": [], + "level_of_education": null, + "social_links": [], + "time_zone": null, + "name": "John Doe", + "email": "johndoe@example.com", + "id": 6, + "verified_name": null, + "extended_profile": [], + "gender": null, + "state": null, + "goals": "", + "is_active": false, + "last_login": null, + "mailing_address": "", + "requires_parental_consent": true, + "secondary_email": null, + "secondary_email_enabled": null, + "year_of_birth": null, + "phone_number": null, + "activation_key": "0511129811d04152bdb3ae49fa64c0eb", + "pending_name_change": null + } + + +**Create User** + +URL: ``/eox-core/api/v1/user/`` + +Method: POST + +Body: + +.. code-block:: json + + { + "username": "johndoe", + "email": "johndoe@example.com", + "fullname": "John Doe", + "password": "p@ssword" + } + +Response Example: + +.. code-block:: json + + 200 OK + + { + "email": "johndoe@example.com", + "username": "johndoe", + "is_active": false, + "is_staff": false, + "is_superuser": false + } + + + +**Extra Profile Fields** **Creating custom registration fields** @@ -36,3 +135,30 @@ If, for example, we want to add the field `Organization name`, we will have to d "label": "Organization name" } ] + + +**Update User** + +URL: ``/eox-core/api/v1/update-user/`` + +Method: PATCH + +Body: + +.. code-block:: json + + { + "email": "johndoe-updated@example.com", + "password": "updated-p@$$w0rd" + } + +Example: + + http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/ + +Response Example: + +.. code-block:: json + + 200 OK + From 7b4a95d046cc14a451acd7dc4ac3b50e4df3b567 Mon Sep 17 00:00:00 2001 From: Luis Felipe Castano Date: Tue, 22 Oct 2024 11:26:19 -0500 Subject: [PATCH 04/24] docs: add improvements --- docs/how_to/users_api.rst | 211 +++++++++++++++++++++++++++++++++++--- 1 file changed, 196 insertions(+), 15 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 3026a3388..e1ec7cbcb 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -100,41 +100,161 @@ Response Example: **Extra Profile Fields** +The User API supports the use of extra and custom registration fields for both Create and Update operations. This allows for flexibility in managing user profiles with additional fields beyond the default ones, ensuring that tenants can extend user data as needed. + **Creating custom registration fields** **Tenant settings** -Add the following settings to the microsite where we want to add the fields: +To add custom or extra registration fields for a specific tenant, you'll need to configure the following settings: Example: Adding a custom field +------------------------------ If, for example, we want to add the field `Organization name`, we will have to do the following: -1. Add the field name, `org_name` for example, to `extended_profile_fields`. This indicates that `org_name` will be saved as an extended profile field. +1. Add the field name, `org_name` for example, to `extended_profile_fields` setting. This indicates that `org_name` will be saved as an extended profile field. + + .. code-block:: json + + "extended_profile_fields": [ "org_name" ] + +2. Add `org_name` to `REGISTRATION_EXTRA_FIELDS` setting, indicating whether the field is hidden, optional, or required: + + .. code-block:: json + + "REGISTRATION_EXTRA_FIELDS": { + "org_name": "required" + } + +### Note on Hidden Fields + +Fields that are set as `hidden` in the configuration will not be visible in the registration form or user profile, and they **cannot be updated through the API**. + +If you attempt to update a field that is marked as `hidden` using the API, the update will be ignored, and no changes will be applied to that field. + +3. Define the custom field by creating it as a dictionary inside the `EDNX_CUSTOM_REGISTRATION_FIELDS` setting. In this case, we are creating a text field for `org_name`. You must specify at least the `name`, `type`, and `label`: + .. code-block:: json + + "EDNX_CUSTOM_REGISTRATION_FIELDS": [ + { + "name": "org_name", + "type": "text", + "label": "Organization name" + } + ] + +Once the field is configured, it can be included in the body of both `POST` (to create a new user) and `PATCH` (to update an existing user) requests. + +**Types of Custom Fields** +-------------------------- + +You can create various types of fields to customize the registration form, depending on the type of input you want to collect. Here are some examples: + +**Text Field** + +A simple text input field, used for collecting short text responses like a PIN or Student ID: + +.. code-block:: json + + { + "name": "pin_id", + "type": "text", + "label": "PIN / Student ID:" + } + +**Checkbox** + +A checkbox field, often used for consent or binary choices: .. code-block:: json - "extended_profile_fields": [ "org_name" ] + { + "name": "data_consent", + "type": "checkbox", + "label": "I wish to receive information about courses, events, etc." + } + +**Select (Dropdown)** -2. Add org_name to REGISTRATION_EXTRA_FIELDS, indicating whether the field is hidden, optional, or required: +A dropdown field that allows users to choose from a predefined list of options. You can also set a default value: .. code-block:: json - "REGISTRATION_EXTRA_FIELDS": { - "org_name": "required" - } + { + "name": "company_dependence", + "type": "select", + "label": "Establishment dependency.", + "options": ["Municipal", "Subsidized private", "Paid private"], + "default": "Municipal" + } + +**Field Visibility Options** +---------------------------- + +When configuring additional registration fields, there are several visibility and requirement options that can be used: + +- **`required`**: The field is displayed and must be filled out by the user. +- **`optional`**: The field is displayed as part of a toggled input field list, and it is not mandatory to fill it out. +- **`hidden`**: The field is not displayed to the user. +- **`optional-exposed`**: The field is displayed along with the required fields, but filling it out is not mandatory. This option provides more visibility than `optional` while still keeping the field optional. -3. In this step, we will create the custom field as a dictionary. In this case, we are going to create a text field for org_name. We must indicate: name, type, and label as the minimum: +**Testing `optional-exposed`** + +If you want to use and test the `optional-exposed` field type, make sure to add it to the configuration. For example, you can set a field to `optional-exposed` like this: .. code-block:: json - "EDNX_CUSTOM_REGISTRATION_FIELDS": [ - { - "name": "org_name", - "type": "text", - "label": "Organization name" - } - ] + "REGISTRATION_EXTRA_FIELDS": { + "org_name": "optional-exposed" + } + +In this case, the `org_name` field will be displayed alongside required fields, but it won't be mandatory for the user to fill out. This can be particularly useful for fields that are not crucial but should be easily visible to users during registration. + +**Example Usage** + +Here is an example configuration using all the types, including `optional-exposed`: + +.. code-block:: json + + "REGISTRATION_EXTRA_FIELDS": { + "confirm_email": "hidden", + "level_of_education": "optional", + "gender": "optional-exposed", + "year_of_birth": "optional", + "mailing_address": "optional-exposed", + "honor_code": "required" + } + +In this example: +- `gender` and `mailing_address` are set to `optional-exposed`, making them visible alongside required fields but not mandatory. +- `honor_code` is `required`, ensuring it must be filled. +- `level_of_education` and `year_of_birth` are optional and shown in a secondary list. +- `confirm_email` is hidden from the registration form. + +**Including the custom field in a POST request:** + +.. code-block:: json + + { + "username": "johndoe", + "email": "johndoe@example.com", + "fullname": "John Doe", + "password": "p@ssword", + "org_name": "Tech Solutions" + } + +**Including the custom field in a PATCH request:** + +.. code-block:: json + + { + "email": "johndoe-updated@example.com", + "org_name": "New Organization Name" + } + +By following these steps, the `org_name` field will be correctly handled during user creation or update. + **Update User** @@ -162,3 +282,64 @@ Response Example: 200 OK +**EOX_CORE_USER_UPDATE_SAFE_FIELDS** +------------------------------------ + +This setting changes that allow specific user profile fields, considered as 'safe', to be updated. These "safe" fields are defined in the setting `EOX_CORE_USER_UPDATE_SAFE_FIELDS`. + +### Safe Fields Update + +The `EOX_CORE_USER_UPDATE_SAFE_FIELDS` setting specifies which fields in the user profile can be updated without requiring additional permissions. + +Example configuration of `EOX_CORE_USER_UPDATE_SAFE_FIELDS`: + +.. code-block:: json + + "EOX_CORE_USER_UPDATE_SAFE_FIELDS": [ + "bio", + "profile_image", + "language", + ] + +### Update User Endpoint Enhancement + +A modification was also made to the update user endpoint, allowing it to filter users by `username` or `email`. This makes it easier to identify and update a specific user directly using one of these parameters. + +To use the filtering capabilities, the endpoint can be accessed as follows: + +**URL**: ``/eox-core/api/v1/update-user/`` + +**Method**: PATCH + +**Query Parameters**: +- `username`: Specify the username of the user to update. +- `email`: Specify the email of the user to update. + +**Example Usage**: + +.. code-block:: http + + PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/?username=johndoe + + PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/?email=johndoe@example.com + +**Example Body**: + +.. code-block:: json + + { + "bio": "Updated user bio.", + "language": ["en", "es"] + } + +**Response Example**: + +.. code-block:: json + + 200 OK + + { + "username": "johndoe", + "bio": "Updated user bio.", + "language": ["en", "es"] + } \ No newline at end of file From ccf700a237570ff49b23dbd0ee99ba67c7e40f66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:06:32 -0500 Subject: [PATCH 05/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index e1ec7cbcb..4ea8ddc94 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -134,6 +134,7 @@ Fields that are set as `hidden` in the configuration will not be visible in the If you attempt to update a field that is marked as `hidden` using the API, the update will be ignored, and no changes will be applied to that field. 3. Define the custom field by creating it as a dictionary inside the `EDNX_CUSTOM_REGISTRATION_FIELDS` setting. In this case, we are creating a text field for `org_name`. You must specify at least the `name`, `type`, and `label`: + .. code-block:: json "EDNX_CUSTOM_REGISTRATION_FIELDS": [ From 7f3ef542e060cbee54154e87e7fdd90a9023afdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:07:28 -0500 Subject: [PATCH 06/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 4ea8ddc94..2a36c9ddd 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -195,7 +195,7 @@ A dropdown field that allows users to choose from a predefined list of options. When configuring additional registration fields, there are several visibility and requirement options that can be used: -- **`required`**: The field is displayed and must be filled out by the user. +- **required**: The field is displayed and must be filled out by the user. - **`optional`**: The field is displayed as part of a toggled input field list, and it is not mandatory to fill it out. - **`hidden`**: The field is not displayed to the user. - **`optional-exposed`**: The field is displayed along with the required fields, but filling it out is not mandatory. This option provides more visibility than `optional` while still keeping the field optional. From adccc15f635f4a2a2f866b5745bd7d0c3d8936b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:07:56 -0500 Subject: [PATCH 07/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 2a36c9ddd..85d165637 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -313,6 +313,7 @@ To use the filtering capabilities, the endpoint can be accessed as follows: **Method**: PATCH **Query Parameters**: + - `username`: Specify the username of the user to update. - `email`: Specify the email of the user to update. From c3af398695fe66e44553d15e7e5689e804358c34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:08:23 -0500 Subject: [PATCH 08/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 85d165637..8fad26ce5 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -228,6 +228,7 @@ Here is an example configuration using all the types, including `optional-expose } In this example: + - `gender` and `mailing_address` are set to `optional-exposed`, making them visible alongside required fields but not mandatory. - `honor_code` is `required`, ensuring it must be filled. - `level_of_education` and `year_of_birth` are optional and shown in a secondary list. From 7002f92ead94bc6e68b82fefdc7ab125e8c872a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:09:11 -0500 Subject: [PATCH 09/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 8fad26ce5..e845473fd 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -202,7 +202,7 @@ When configuring additional registration fields, there are several visibility an **Testing `optional-exposed`** -If you want to use and test the `optional-exposed` field type, make sure to add it to the configuration. For example, you can set a field to `optional-exposed` like this: +If you want to use and test the ``optional-exposed`` field type, make sure to add it to the configuration. For example, you can set a field to ``optional-exposed`` like this: .. code-block:: json From 18b9e53601bfd560a0198adce3e062558d22d2eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:09:53 -0500 Subject: [PATCH 10/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index e845473fd..0c18c8f07 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -145,7 +145,7 @@ If you attempt to update a field that is marked as `hidden` using the API, the u } ] -Once the field is configured, it can be included in the body of both `POST` (to create a new user) and `PATCH` (to update an existing user) requests. +Once the field is configured, it can be included in the body of both ``POST`` (to create a new user) and ``PATCH`` (to update an existing user) requests. **Types of Custom Fields** -------------------------- From 06b24b53bc962f7ecf250967a1e35b60c7132bc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:10:30 -0500 Subject: [PATCH 11/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 0c18c8f07..f4aefd8e7 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -198,7 +198,7 @@ When configuring additional registration fields, there are several visibility an - **required**: The field is displayed and must be filled out by the user. - **`optional`**: The field is displayed as part of a toggled input field list, and it is not mandatory to fill it out. - **`hidden`**: The field is not displayed to the user. -- **`optional-exposed`**: The field is displayed along with the required fields, but filling it out is not mandatory. This option provides more visibility than `optional` while still keeping the field optional. +- **optional-exposed**: The field is displayed along with the required fields, but filling it out is not mandatory. This option provides more visibility than ``optional`` while still keeping the field optional. **Testing `optional-exposed`** From 6274290626992550576e0846b22591cae783b984 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:11:29 -0500 Subject: [PATCH 12/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index f4aefd8e7..0c4ce497d 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -200,7 +200,7 @@ When configuring additional registration fields, there are several visibility an - **`hidden`**: The field is not displayed to the user. - **optional-exposed**: The field is displayed along with the required fields, but filling it out is not mandatory. This option provides more visibility than ``optional`` while still keeping the field optional. -**Testing `optional-exposed`** +**Testing optional-exposed** If you want to use and test the ``optional-exposed`` field type, make sure to add it to the configuration. For example, you can set a field to ``optional-exposed`` like this: From f512c976ba299366b761095120b6a48e363d9278 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 13:30:42 -0500 Subject: [PATCH 13/24] docs: add users api docs --- docs/how_to/users_api.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 0c4ce497d..3f83e62c3 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -15,6 +15,8 @@ Query Params: Example: +.. code-block:: http + http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com @@ -127,7 +129,7 @@ If, for example, we want to add the field `Organization name`, we will have to d "org_name": "required" } -### Note on Hidden Fields +**Note on Hidden Fields** Fields that are set as `hidden` in the configuration will not be visible in the registration form or user profile, and they **cannot be updated through the API**. @@ -276,6 +278,8 @@ Body: Example: +.. code-block:: http + http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/ Response Example: @@ -289,7 +293,7 @@ Response Example: This setting changes that allow specific user profile fields, considered as 'safe', to be updated. These "safe" fields are defined in the setting `EOX_CORE_USER_UPDATE_SAFE_FIELDS`. -### Safe Fields Update +**Safe Fields Update** The `EOX_CORE_USER_UPDATE_SAFE_FIELDS` setting specifies which fields in the user profile can be updated without requiring additional permissions. @@ -303,7 +307,7 @@ Example configuration of `EOX_CORE_USER_UPDATE_SAFE_FIELDS`: "language", ] -### Update User Endpoint Enhancement +**Update User Endpoint Enhancement** A modification was also made to the update user endpoint, allowing it to filter users by `username` or `email`. This makes it easier to identify and update a specific user directly using one of these parameters. @@ -345,4 +349,4 @@ To use the filtering capabilities, the endpoint can be accessed as follows: "username": "johndoe", "bio": "Updated user bio.", "language": ["en", "es"] - } \ No newline at end of file + } From 83ad3705393f0d74508ba500200a5a459e10300c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 16:05:19 -0500 Subject: [PATCH 14/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 3f83e62c3..05dbd6027 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -17,9 +17,9 @@ Example: .. code-block:: http - http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe +POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe - http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com +POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com Response Example: From db57bd88be65c7b49e53494c95bd5fa701bdd87d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Tue, 22 Oct 2024 16:06:18 -0500 Subject: [PATCH 15/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 05dbd6027..bf87bf7d4 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -129,11 +129,11 @@ If, for example, we want to add the field `Organization name`, we will have to d "org_name": "required" } -**Note on Hidden Fields** + **Note on Hidden Fields** -Fields that are set as `hidden` in the configuration will not be visible in the registration form or user profile, and they **cannot be updated through the API**. + Fields that are set as ``hidden`` in the configuration will not be visible in the registration form or user profile, and they **cannot be updated through the API**. -If you attempt to update a field that is marked as `hidden` using the API, the update will be ignored, and no changes will be applied to that field. + If you attempt to update a field that is marked as ``hidden`` using the API, the update will be ignored, and no changes will be applied to that field. 3. Define the custom field by creating it as a dictionary inside the `EDNX_CUSTOM_REGISTRATION_FIELDS` setting. In this case, we are creating a text field for `org_name`. You must specify at least the `name`, `type`, and `label`: From 755194f264039285ed000f0469e2c3329969cd0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Wed, 23 Oct 2024 17:05:25 -0500 Subject: [PATCH 16/24] fix: format --- docs/how_to/users_api.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index bf87bf7d4..4188b67cd 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -113,15 +113,15 @@ To add custom or extra registration fields for a specific tenant, you'll need to Example: Adding a custom field ------------------------------ -If, for example, we want to add the field `Organization name`, we will have to do the following: +If, for example, we want to add the field ``Organization name``, we will have to do the following: -1. Add the field name, `org_name` for example, to `extended_profile_fields` setting. This indicates that `org_name` will be saved as an extended profile field. +1. Add the field name, ``org_name`` for example, to ``extended_profile_fields`` setting. This indicates that ``org_name`` will be saved as an extended profile field. .. code-block:: json "extended_profile_fields": [ "org_name" ] -2. Add `org_name` to `REGISTRATION_EXTRA_FIELDS` setting, indicating whether the field is hidden, optional, or required: +2. Add ``org_name`` to ``REGISTRATION_EXTRA_FIELDS`` setting, indicating whether the field is hidden, optional, or required: .. code-block:: json @@ -135,7 +135,7 @@ If, for example, we want to add the field `Organization name`, we will have to d If you attempt to update a field that is marked as ``hidden`` using the API, the update will be ignored, and no changes will be applied to that field. -3. Define the custom field by creating it as a dictionary inside the `EDNX_CUSTOM_REGISTRATION_FIELDS` setting. In this case, we are creating a text field for `org_name`. You must specify at least the `name`, `type`, and `label`: +3. Define the custom field by creating it as a dictionary inside the ``EDNX_CUSTOM_REGISTRATION_FIELDS`` setting. In this case, we are creating a text field for ``org_name``. You must specify at least the ``name``, ``type``, and ``label``: .. code-block:: json @@ -198,8 +198,8 @@ A dropdown field that allows users to choose from a predefined list of options. When configuring additional registration fields, there are several visibility and requirement options that can be used: - **required**: The field is displayed and must be filled out by the user. -- **`optional`**: The field is displayed as part of a toggled input field list, and it is not mandatory to fill it out. -- **`hidden`**: The field is not displayed to the user. +- **optional**: The field is displayed as part of a toggled input field list, and it is not mandatory to fill it out. +- **hidden**: The field is not displayed to the user. - **optional-exposed**: The field is displayed along with the required fields, but filling it out is not mandatory. This option provides more visibility than ``optional`` while still keeping the field optional. **Testing optional-exposed** @@ -212,11 +212,11 @@ If you want to use and test the ``optional-exposed`` field type, make sure to ad "org_name": "optional-exposed" } -In this case, the `org_name` field will be displayed alongside required fields, but it won't be mandatory for the user to fill out. This can be particularly useful for fields that are not crucial but should be easily visible to users during registration. +In this case, the ``org_name`` field will be displayed alongside required fields, but it won't be mandatory for the user to fill out. This can be particularly useful for fields that are not crucial but should be easily visible to users during registration. **Example Usage** -Here is an example configuration using all the types, including `optional-exposed`: +Here is an example configuration using all the types, including ``optional-exposed``: .. code-block:: json @@ -231,10 +231,10 @@ Here is an example configuration using all the types, including `optional-expose In this example: -- `gender` and `mailing_address` are set to `optional-exposed`, making them visible alongside required fields but not mandatory. -- `honor_code` is `required`, ensuring it must be filled. -- `level_of_education` and `year_of_birth` are optional and shown in a secondary list. -- `confirm_email` is hidden from the registration form. +- ``gender`` and ``mailing_address`` are set to ``optional-exposed``, making them visible alongside required fields but not mandatory. +- ``honor_code`` is ``required``, ensuring it must be filled. +- ``level_of_education`` and ``year_of_birth`` are optional and shown in a secondary list. +- ``confirm_email`` is hidden from the registration form. **Including the custom field in a POST request:** @@ -257,7 +257,7 @@ In this example: "org_name": "New Organization Name" } -By following these steps, the `org_name` field will be correctly handled during user creation or update. +By following these steps, the ``org_name`` field will be correctly handled during user creation or update. @@ -295,9 +295,9 @@ This setting changes that allow specific user profile fields, considered as 'saf **Safe Fields Update** -The `EOX_CORE_USER_UPDATE_SAFE_FIELDS` setting specifies which fields in the user profile can be updated without requiring additional permissions. +The ``EOX_CORE_USER_UPDATE_SAFE_FIELDS`` setting specifies which fields in the user profile can be updated without requiring additional permissions. -Example configuration of `EOX_CORE_USER_UPDATE_SAFE_FIELDS`: +Example configuration of ``EOX_CORE_USER_UPDATE_SAFE_FIELDS``: .. code-block:: json @@ -309,7 +309,7 @@ Example configuration of `EOX_CORE_USER_UPDATE_SAFE_FIELDS`: **Update User Endpoint Enhancement** -A modification was also made to the update user endpoint, allowing it to filter users by `username` or `email`. This makes it easier to identify and update a specific user directly using one of these parameters. +A modification was also made to the update user endpoint, allowing it to filter users by ``username`` or ``email``. This makes it easier to identify and update a specific user directly using one of these parameters. To use the filtering capabilities, the endpoint can be accessed as follows: @@ -319,8 +319,8 @@ To use the filtering capabilities, the endpoint can be accessed as follows: **Query Parameters**: -- `username`: Specify the username of the user to update. -- `email`: Specify the email of the user to update. +- ``username``: Specify the username of the user to update. +- ``email``: Specify the email of the user to update. **Example Usage**: From 88cb88be0af3bbceb14186df39f9639200b2445c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Wed, 23 Oct 2024 17:22:54 -0500 Subject: [PATCH 17/24] fix: format --- docs/how_to/users_api.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 4188b67cd..636a11222 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -17,9 +17,9 @@ Example: .. code-block:: http -POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe - -POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com + POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe + + POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com Response Example: @@ -280,7 +280,7 @@ Example: .. code-block:: http - http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/ + PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/ Response Example: From 29941c0cee701273929b74293b59282165840659 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Fri, 25 Oct 2024 14:47:28 -0500 Subject: [PATCH 18/24] fix: format Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 636a11222..929fb4080 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -291,7 +291,7 @@ Response Example: **EOX_CORE_USER_UPDATE_SAFE_FIELDS** ------------------------------------ -This setting changes that allow specific user profile fields, considered as 'safe', to be updated. These "safe" fields are defined in the setting `EOX_CORE_USER_UPDATE_SAFE_FIELDS`. +This setting allows specific user profile fields, considered as 'safe', to be updated. These "safe" fields are defined in the setting ``EOX_CORE_USER_UPDATE_SAFE_FIELDS``. **Safe Fields Update** From 356ef1246416deaa9e78b3146c82eab918b3d913 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Fri, 25 Oct 2024 14:48:39 -0500 Subject: [PATCH 19/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 929fb4080..1f4754ef1 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -154,7 +154,7 @@ Once the field is configured, it can be included in the body of both ``POST`` (t You can create various types of fields to customize the registration form, depending on the type of input you want to collect. Here are some examples: -**Text Field** +**Text** A simple text input field, used for collecting short text responses like a PIN or Student ID: From 3d31868b516d62afc67f4d48b8c199e6edd20534 Mon Sep 17 00:00:00 2001 From: Luis Felipe Castano Date: Fri, 25 Oct 2024 14:50:45 -0500 Subject: [PATCH 20/24] docs: uodate user doc ubication --- docs/how_to/users_api.rst | 54 +++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 1f4754ef1..3d718e9b2 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -98,6 +98,32 @@ Response Example: "is_superuser": false } +**Update User** + +URL: ``/eox-core/api/v1/update-user/`` + +Method: PATCH + +Body: + +.. code-block:: json + + { + "email": "johndoe-updated@example.com", + "password": "updated-p@$$w0rd" + } + +Example: + +.. code-block:: http + + PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/ + +Response Example: + +.. code-block:: json + + 200 OK **Extra Profile Fields** @@ -260,34 +286,6 @@ In this example: By following these steps, the ``org_name`` field will be correctly handled during user creation or update. - -**Update User** - -URL: ``/eox-core/api/v1/update-user/`` - -Method: PATCH - -Body: - -.. code-block:: json - - { - "email": "johndoe-updated@example.com", - "password": "updated-p@$$w0rd" - } - -Example: - -.. code-block:: http - - PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/ - -Response Example: - -.. code-block:: json - - 200 OK - **EOX_CORE_USER_UPDATE_SAFE_FIELDS** ------------------------------------ From a4b9240c5ca0ffa9b316eb0bf4879a0affe5dd40 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Fri, 25 Oct 2024 14:51:48 -0500 Subject: [PATCH 21/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 3d718e9b2..1b50bb226 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -7,11 +7,10 @@ URL: ``/eox-core/api/v1/user/`` Method: GET -Query Params: - - username (String) +**Query Parameters**: - email (String) +- ``username`` (String): Specify the username of the user to retrieve. +- ``email`` (String): Specify the email of the user to retrieve. Example: From 959696e513a4ec00fb1e7d211b3e99846fb1a609 Mon Sep 17 00:00:00 2001 From: Luis Felipe Castano Date: Fri, 25 Oct 2024 14:58:28 -0500 Subject: [PATCH 22/24] docs: update location of sections --- docs/how_to/users_api.rst | 124 +++++++++++++++++++------------------- 1 file changed, 63 insertions(+), 61 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 1b50bb226..c57d22fa8 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -174,6 +174,69 @@ If, for example, we want to add the field ``Organization name``, we will have to Once the field is configured, it can be included in the body of both ``POST`` (to create a new user) and ``PATCH`` (to update an existing user) requests. +**EOX_CORE_USER_UPDATE_SAFE_FIELDS** +------------------------------------ + +This setting allows specific user profile fields, considered as 'safe', to be updated. These "safe" fields are defined in the setting ``EOX_CORE_USER_UPDATE_SAFE_FIELDS``. + +**Safe Fields Update** + +The ``EOX_CORE_USER_UPDATE_SAFE_FIELDS`` setting specifies which fields in the user profile can be updated without requiring additional permissions. + +Example configuration of ``EOX_CORE_USER_UPDATE_SAFE_FIELDS``: + +.. code-block:: json + + "EOX_CORE_USER_UPDATE_SAFE_FIELDS": [ + "bio", + "profile_image", + "language", + ] + +**Update User Endpoint Enhancement** + +A modification was also made to the update user endpoint, allowing it to filter users by ``username`` or ``email``. This makes it easier to identify and update a specific user directly using one of these parameters. + +To use the filtering capabilities, the endpoint can be accessed as follows: + +**URL**: ``/eox-core/api/v1/update-user/`` + +**Method**: PATCH + +**Query Parameters**: + +- ``username``: Specify the username of the user to update. +- ``email``: Specify the email of the user to update. + +**Example Usage**: + +.. code-block:: http + + PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/?username=johndoe + + PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/?email=johndoe@example.com + +**Example Body**: + +.. code-block:: json + + { + "bio": "Updated user bio.", + "language": ["en", "es"] + } + +**Response Example**: + +.. code-block:: json + + 200 OK + + { + "username": "johndoe", + "bio": "Updated user bio.", + "language": ["en", "es"] + } + **Types of Custom Fields** -------------------------- @@ -285,65 +348,4 @@ In this example: By following these steps, the ``org_name`` field will be correctly handled during user creation or update. -**EOX_CORE_USER_UPDATE_SAFE_FIELDS** ------------------------------------- - -This setting allows specific user profile fields, considered as 'safe', to be updated. These "safe" fields are defined in the setting ``EOX_CORE_USER_UPDATE_SAFE_FIELDS``. - -**Safe Fields Update** - -The ``EOX_CORE_USER_UPDATE_SAFE_FIELDS`` setting specifies which fields in the user profile can be updated without requiring additional permissions. - -Example configuration of ``EOX_CORE_USER_UPDATE_SAFE_FIELDS``: - -.. code-block:: json - - "EOX_CORE_USER_UPDATE_SAFE_FIELDS": [ - "bio", - "profile_image", - "language", - ] - -**Update User Endpoint Enhancement** - -A modification was also made to the update user endpoint, allowing it to filter users by ``username`` or ``email``. This makes it easier to identify and update a specific user directly using one of these parameters. - -To use the filtering capabilities, the endpoint can be accessed as follows: - -**URL**: ``/eox-core/api/v1/update-user/`` - -**Method**: PATCH - -**Query Parameters**: - -- ``username``: Specify the username of the user to update. -- ``email``: Specify the email of the user to update. - -**Example Usage**: - -.. code-block:: http - - PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/?username=johndoe - - PATCH http://tenant-a.local.edly.io:8000/eox-core/api/v1/update-user/?email=johndoe@example.com - -**Example Body**: - -.. code-block:: json - { - "bio": "Updated user bio.", - "language": ["en", "es"] - } - -**Response Example**: - -.. code-block:: json - - 200 OK - - { - "username": "johndoe", - "bio": "Updated user bio.", - "language": ["en", "es"] - } From 9353b9973f16b88ae2886d1e78a10650ec432644 Mon Sep 17 00:00:00 2001 From: Luis Felipe Castano Date: Fri, 25 Oct 2024 17:18:48 -0500 Subject: [PATCH 23/24] docs: add types of custom fields --- docs/how_to/users_api.rst | 48 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index c57d22fa8..792eea555 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -280,6 +280,54 @@ A dropdown field that allows users to choose from a predefined list of options. "default": "Municipal" } +**Email** + +An input field specifically for email addresses. + +.. code-block:: json + + { + "name": "user_email", + "type": "email", + "label": "Email Address:" + } + +**Textarea** + +A larger text area for longer input, useful for comments or descriptions: + +.. code-block:: json + + { + "name": "user_feedback", + "type": "textarea", + "label": "Your Feedback:" + } + +**Plaintext** + +A field to display static, non-editable information in a form: + +.. code-block:: json + + { + "name": "terms_info", + "type": "plaintext", + "label": "Please read the terms and conditions carefully before proceeding." + } + +**Password** + +An input field that hides the typed information, typically used for passwords: + +.. code-block:: json + + { + "name": "user_password", + "type": "password", + "label": "Password:" + } + **Field Visibility Options** ---------------------------- From 67e7e5243b69a1400caa4a182aef651ea84241af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Luis=20Felipe=20Casta=C3=B1o?= <78836902+luisfelipec95@users.noreply.github.com> Date: Mon, 28 Oct 2024 10:14:25 -0500 Subject: [PATCH 24/24] docs: add improvements Co-authored-by: Bryann Valderrama <64033729+BryanttV@users.noreply.github.com> --- docs/how_to/users_api.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/how_to/users_api.rst b/docs/how_to/users_api.rst index 792eea555..519e6f24a 100644 --- a/docs/how_to/users_api.rst +++ b/docs/how_to/users_api.rst @@ -16,9 +16,9 @@ Example: .. code-block:: http - POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe + GET http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?username=johndoe - POST http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com + GET http://tenant-a.local.edly.io:8000/eox-core/api/v1/user/?email=johndoe@example.com Response Example: