Merge pull request #1 from himeshsiriwardana/pr-5604

separated onboarding options to a separate doc

Author: bhagyasakalanka

en/asgardeo/docs/guides/users/manage-users.md

@@ -4,97 +4,9 @@ This guide walks you through the process of managing a user account. An owner or
 
 ## Onboard users
 
-There are three ways to onboard a user:
+{{product_name}} provides multiple ways to onboard users to your organization. You can add users individually or in bulk using a CSV file. You can also allow users to self-register.
 
-- The user can self-register via the My Account portal or the login page of an application if self-registration is enabled in the organization. Learn how to [configure self-registration]({{base_path}}/guides/user-accounts/configure-self-registration/).
-- An administrator can onboard users from an on-premise user store by [connecting a remote user store to {{ product_name }}]({{base_path}}/guides/users/user-stores/configure-a-user-store/).
-
-    !!! note
-        If the remote user store access type is read-only, you cannot update the user profiles of users onboarded from this read-only user store.
-
-- An administrator can onboard users from the {{ product_name }} Console.
-
-Let's look at how administrators can onboard users from the {{ product_name }} Console.
-
-### Onboard a single user
-
-1. On the {{ product_name }} Console, go to **User Management** > **Users**.
-2. Click  **Add User** > **Single User** and provide the following details:
-
-    ![Add user]({{base_path}}/assets/img/guides/users/add-user-form.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
-
-    - **Email (Username):** A unique email address to identify the user.
-    - **First Name:** First name of the user. You can add/change this later.
-    - **Last Name:** Last name of the user. You can add/change this later.
-
-    !!! note
-        You can include additional user details such as phone number, address, and other custom attributes when onboarding a user. This is done via
-        [attribute configurations]({{base_path}}/guides/users/attributes/manage-attributes/#configure-attributes).
-
-    !!! note
-
-        - A username is always unique to the organization and you can't change the username once it is created.
-        - Instead of using the email as the username, you can [configure the username]({{base_path}}/guides/user-accounts/account-login/username-validation/) to be an alphanumeric. Then, you will be asked to enter an alphanumeric username between the configured minimum and maximum lengths.
-        - The existing users who have already registered with their email address as the username can continue to use it to access applications, instead of having to create a new username.
-
-3. You can either request the user to set the password or set one on the user's behalf.
-
-    - **Invite user to set their own password:**
-
-        - **Invite via email:** If this option is selected, an email with a confirmation link will be sent to the provided email (username). The user can use the confirmation link to set up a new password.
-
-        - **Invite offline:** If this option is selected, the administrator will receive an invite link at the end of user registration. This link can be shared with the user.
-
-    - **Set a password for the user:**
-            If this option is selected, the administrator can set a password for the user. The user can change this password from the [My Account Portal]({{base_path}}/guides/user-self-service/customer-self-service-portal/).
-
-4. Add the user to a group in the next step. You will not see this option if you haven't created any groups in {{ product_name }}.
-5. Click **Finish**.
-
-    !!! note
-        If you have selected **Invite offline** or decided to **set a password for the user**, you can copy the corresponding information at the **Summary** page of the wizard and share with the user.
-
-### Onboard multiple users
-
-In addition to adding a single user, you can onboard multiple users at once, either manually or by using a CSV file. This is especially useful for large organizations that seek efficiency.
-
-![Add multiple users]({{base_path}}/assets/img/guides/users/add-multiple-users-form.png)
-
-!!! note
-    Importing multiple users is only supported for the Asgardeo-provided **DEFAULT** user store.
-
-#### Add multiple users manually
-
-1. On the Asgardeo Console, go to **User Management** > **Users**.
-2. Click **Add User** > **Multiple Users**.
-3. Switch to the **Manual** tab.
-4. Enter the email addresses of the users you want to invite. Press **Enter** after each email to add it to the list.
-5. Under Groups, select the group(s) from the dropdown to which users will be added during the import.
-6. Click **Add** to send out the invitations.
-
-An email with a confirmation link will be sent to the provided email addresses, allowing the users to set their own passwords.
-
-#### Add multiple users using a CSV file
-
-1. On the Asgardeo Console, go to **User Management** > **Users**.
-2. Click **Add User** > **Multiple Users**.
-3. Switch to the **File Based** tab.
-4. Click **Upload CSV File** or drag and drop a CSV file into the designated area.
-5. Ensure your CSV file is formatted correctly, with headers that correspond to user attributes. These attributes must be mapped to local attributes.
-
-   - A sample CSV file format would include: `username, givenname, emailaddress, groups`
-
-   - For example:
-
-       ```
-       username,givenname,emailaddress,groups
-       user1,john,[email protected],group1|group2
-       user2,jake,[email protected],group2
-       user3,jane,[email protected],group1
-       ```
-
-6. Click **Import** to add the users to the system.
-7. An email with a confirmation link will be sent to the provided email addresses, allowing the users to set their own passwords.
+To learn more about onboarding users, see [Onboard users]({{base_path}}/guides/users/onboard-users/).
 
 ## Assign groups
 A user can be assigned to different [groups]({{base_path}}/guides/users/manage-groups/) in the organization. Groups can be used to restrict the user's access to resources.
@@ -401,183 +313,4 @@ To filter users by account status:
     - **Pending email verification**: Filters users who haven't yet verified their primary email addresses.
     - **Pending mobile verification**: Filters users who haven't yet verified their primary mobile numbers.
 
-        ![Filter users by account status]({{base_path}}/assets/img/guides/users/filter-users-by-account-status.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}
-
-## Add users with email verification
-
-1: Enable email verification
-
-!!! abstract ""
-
-        curl -X 'PATCH' \
-        'https://api.asgardeo.io/t/<org_name>/api/server/v1/identity-governance/VXNlciBPbmJvYXJkaW5n/connectors/dXNlci1lbWFpbC12ZXJpZmljYXRpb24' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "operation": "UPDATE",
-            "properties": [
-                {
-                    "name": "EmailVerification.Enable",
-                    "value": true
-                }
-            ]
-        }'
-
-2: Configure email verification method (Optional). Enable this to send OTP via email.
-
-!!! abstract ""
-
-        curl -X 'PATCH' \
-        'https://api.asgardeo.io/t/<org_name>/api/server/v1/identity-governance/VXNlciBPbmJvYXJkaW5n/connectors/dXNlci1lbWFpbC12ZXJpZmljYXRpb24' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "operation": "UPDATE",
-            "properties": [
-                {
-                    "name": "EmailVerification.OTP",
-                    "value": true
-                }
-            ]
-        }'
-
-3: Create user with email verification required
-
-!!! abstract ""
-
-    === "Request format"
-
-        ```curl
-        curl -X 'POST' \
-        'https://api.asgardeo.io/t/<org_name>/scim2/Users' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "userName": "<USERNAME>",
-            "emails": [
-                {
-                    "primary": true,
-                    "value": "<EMAIL>"
-                }
-            ],
-            "password": "<PASSWORD>",
-            "urn:scim:wso2:schema": {
-                "verifyEmail": "true"
-            }
-        }'
-        ```
-    === "Sample request"
-
-        ```
-        curl -X 'POST' \
-        'https://api.asgardeo.io/t/<org_name>/scim2/Users' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "userName": "DEFAULT/bob",
-            "emails": [
-                {
-                    "primary": true,
-                    "value": "[email protected]"
-                }
-            ],
-            "password": "P@ssw0rd",
-            "urn:scim:wso2:schema": {
-                "verifyEmail": "true"
-            }
-        }'
-        ```
-
-    ---
-    **Response**
-    ```
-    "HTTP/1.1 201 Created"
-    ```
-
-4: Resend email verification code (Optional)
-
-!!! abstract ""
-
-    === "Request format"
-
-        ```curl
-        curl -X 'POST' \
-        'https://api.asgardeo.io/t/<org_name>/api/identity/user/v1.0/resend-code' \
-        -H 'accept: application/json' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "user": {
-                "username": "<username>",
-                "realm": "DEFAULT"
-            },
-            "properties": [
-                {
-                    "key": "RecoveryScenario",
-                    "value": "EMAIL_VERIFICATION_OTP"
-                }
-            ]
-        }'
-        ```
-    === "Sample request"
-
-        ```
-        curl -X 'POST' \
-        'https://api.asgardeo.io/t/<org_name>/api/identity/user/v1.0/resend-code' \
-        -H 'accept: application/json' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "user": {
-                "username": "[email protected]",
-                "realm": "DEFAULT"
-            },
-            "properties": [
-                {
-                    "key": "RecoveryScenario",
-                    "value": "EMAIL_VERIFICATION_OTP"
-                }
-            ]
-        }'
-        ```
-
-    ---
-    **Response**
-    ```
-    "HTTP/1.1 201 Created"
-    ```
-
-5: Confirm email or validate OTP (One-Time Password)
-
-You can verify the email using the confirmation link, or enter the OTP using the following API.
-
-!!! abstract ""
-
-    === "Request format"
-
-        ```curl
-        curl -X 'POST' \
-        'https://api.asgardeo.io/t/<org_name>/api/identity/user/v1.0/validate-code' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "code": "<CODE>"
-        }'
-        ```
-    === "Sample request"
-
-        ```
-        curl -X 'POST' \
-        'https://api.asgardeo.io/t/<org_name>/api/identity/user/v1.0/validate-code' \
-        -H 'Authorization: Bearer <access_token>' \
-        -H 'Content-Type: application/json' \
-        -d '{
-            "code": "c1KLdm"
-        }'
-        ```
-    
-    ---
-    **Response**
-    ```
-    "HTTP/1.1 202 Accepted"
-    ```
+        ![Filter users by account status]({{base_path}}/assets/img/guides/users/filter-users-by-account-status.png){: width="600" style="display: block; margin: 0; border: 0.3px solid lightgrey;"}

en/asgardeo/docs/guides/users/onboard-users.md

@@ -0,0 +1,3 @@
+{% set base_url = "https://api.asgardeo.io/t/<org_name>" %}
+
+{% include "../../../../includes/guides/users/onboard-users.md" %}

en/asgardeo/mkdocs.yml

@@ -167,6 +167,7 @@ plugins:
         'guides/applications/register-mcp-client-app.md': 'guides/agentic-ai/mcp/register-mcp-client-app.md'
         'guides/authorization/mcp-server-authorization.md': 'guides/agentic-ai/mcp/mcp-server-authorization.md'
         'quick-starts/mcp-server.md': 'sdks/asgardeo-mcp-server.md'
+
 exclude_docs: |
   /get-started/hello-world.md
 
@@ -368,7 +369,9 @@ nav:
       - User management:
         - User management: guides/users/index.md
         - Manage administrators: guides/users/manage-administrators.md
-        - Manage users: guides/users/manage-users.md
+        - Users: 
+          - Onboard users: guides/users/onboard-users.md
+          - Manage users: guides/users/manage-users.md
         - Manage groups: guides/users/manage-groups.md
         - Manage roles: guides/users/manage-roles.md
         - Manage active sessions: guides/users/manage-sessions.md