feat(organizations): create endpoints to handle organization invitations #5395

rajpatel24 · 2024-12-20T15:00:43Z

🗒️ Checklist

run linter locally
update all related docs (API, README, inline, etc.), if any
draft PR with a title <type>(<scope>)<!>: <title> TASK-1234
tag PR: at least frontend or backend unless it's global
fill in the template below and delete template comments
review thyself: read the diff and repro the preview as written
open PR & confirm that CI passes
request reviewers, if needed
delete this section before merging

📣 Summary

Implemented endpoints for organization invitations, allowing organization owners to invite existing users or unregistered users to join their organization. The invitee can either accept or decline the invitation. If the invitee accepts, their assets will be transferred to the organization.

📖 Description

Organization owners can send invitations to users (both registered and unregistered) via email or username.
The invitee can accept or decline the invitation. If accepted, the invitee's assets will be transferred to the organization owner.

POST https://[kpi]/api/v2/organizations/org_12345/invites/

Create organization invites for registered and unregistered users.
Set the role for which the user is being invited - (Choices: member, admin). Default is member.

Payload:

{
    "invitees": ["demo14", "[email protected]", "[email protected]"],
    "role": "admin"
}

Response:

[
    {
        "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/",
        "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
        "status": "pending",
        "invitee_role": "admin",
        "created": "2025-01-06T13:01:40Z",
        "modified": "2025-01-06T13:01:40Z",
        "invitee": "demo14"
    },
    {
        "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/6746121a-7a87-4c2d-9994-85e38d8cff65/",
        "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
        "status": "pending",
        "invitee_role": "admin",
        "created": "2025-01-06T13:01:40Z",
        "modified": "2025-01-06T13:01:40Z",
        "invitee": "demo13"
    },
    {
        "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/2af706a9-4f67-4145-a0d3-8d66fbc77a19/",
        "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
        "status": "pending",
        "invitee_role": "admin",
        "created": "2025-01-06T13:01:40Z",
        "modified": "2025-01-06T13:01:40Z",
        "invitee": "[email protected]"
    }
]

GET https://[kpi]/api/v2/organizations/org_12345/invites/

Response:

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/6746121a-7a87-4c2d-9994-85e38d8cff65/",
            "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
            "status": "pending",
            "invitee_role": "admin",
            "created": "2025-01-06T13:01:40Z",
            "modified": "2025-01-06T13:01:40Z",
            "invitee": "demo13"
        },
        {
            "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/",
            "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
            "status": "pending",
            "invitee_role": "admin",
            "created": "2025-01-06T13:01:40Z",
            "modified": "2025-01-06T13:01:40Z",
            "invitee": "demo14"
        },
        {
            "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/2af706a9-4f67-4145-a0d3-8d66fbc77a19/",
            "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
            "status": "pending",
            "invitee_role": "admin",
            "created": "2025-01-06T13:01:40Z",
            "modified": "2025-01-06T13:01:40Z",
            "invitee": "[email protected]"
        }
    ]
}

PATCH https://[kpi]/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/

Update an organization invite to accept, decline, cancel, expire, or resend.

Payload:

{
    "status": "accepted"
}

Response:

{
    "url": "http://kf.kobo.local/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/",
    "invited_by": "http://kf.kobo.local/api/v2/users/gtl_raj/",
    "status": "accepted",
    "invitee_role": "admin",
    "created": "2025-01-06T13:01:40Z",
    "modified": "2025-01-06T13:01:40Z",
    "invitee": "demo14"
}

DELETE https://[kpi]/api/v2/organizations/org_12345/invites/7a4f9a3b-9112-43cc-a6ae-bb4a6583b4b2/

Organization owner or admin can delete an organization invite.

Response: 204

notion-workspace · 2024-12-31T20:36:14Z

Create endpoints to handle org invitations

notion-workspace · 2024-12-31T20:37:06Z

Invitation response validation

notion-workspace · 2024-12-31T20:37:20Z

Invitation e-mail templates

magicznyleszek · 2025-01-04T10:45:17Z

@rajpatel24 Wuld that whole invite object be present in /api/v2/organizations/:organization_id/members/ in the invite property? And I see you have pending status in there, and is this the same as sent?

magicznyleszek · 2025-01-04T10:53:38Z

kobo/apps/organizations/models.py

+    FAILED = 'failed'
+    IN_PROGRESS = 'in_progress'
+    PENDING = 'pending'
+    RESENT = 'resent'


@rajpatel24 What's the difference between in_progress and pending?

Edit: looking more at this list, I think it would be very useful if you'd describe each of these statuses - like what action triggers them

@magicznyleszek As of now, we're not using in_progress as a status for organization invitations. I included it as a possible choice, along with completed and failed, in case the need arises in the future. Once @noliveleger is back (probably today), I'll discuss this with him. Currently, when the organization owner sends an invitation, the status is set to pending. When the invitee accepts the invitation, the status changes to accepted in the OrganizationInvitation table.

Additionally, when a user accepts an invitation, we trigger an async task to transfer their projects to the organization. This is part of the existing functionality we're reusing for project transfers along with organization invitations. It uses its own project-ownership/Invite table with different statuses, which you might already be familiar with.

So, my question for @noliveleger would be: when the project transfer is completed and the status in the project-ownership/Invite table is set to completed, do we also need to set the status to completed in the OrganizationInvitation table, or is the accepted state sufficient?

To summarize, the /api/v2/organizations/:organization_id/invites/ API will currently have the following statuses: pending, accepted, declined, cancelled, expired, and resent.

If any changes occur regarding this, I'll make sure to update you right away.

@rajpatel24 , accepted would be enough for OrganizationInvitation.

…tations

rajpatel24 · 2025-01-06T06:20:07Z

@rajpatel24 Wuld that whole invite object be present in /api/v2/organizations/:organization_id/members/ in the invite property? And I see you have pending status in there, and is this the same as sent?

@magicznyleszek No, the invite object would not be present there. I don't think it's necessary since /api/v2/organizations/:organization_id/members/ is designed to list the members who are already part of the organization - those who have accepted the invitations and are now part of it.

The pending status is the same as sent. When the organization owner sends an invitation, the status of the invite will be set to pending.

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 092d932 to 64a2b55 Compare December 30, 2024 15:46

rajpatel24 added the Back end label Dec 30, 2024

rajpatel24 changed the title ~~Create endpoints to handle organization invitations~~ feat(organizations): create endpoints to handle organization invitations Dec 30, 2024

rajpatel24 marked this pull request as ready for review December 30, 2024 16:14

rajpatel24 requested review from jnm and noliveleger as code owners December 30, 2024 16:14

rajpatel24 removed the request for review from jnm December 30, 2024 16:14

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 64a2b55 to 1139076 Compare January 1, 2025 15:45

rajpatel24 self-assigned this Jan 1, 2025

Create endpoints to handle organization invitations

c28ad37

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 1139076 to c28ad37 Compare January 2, 2025 14:20

magicznyleszek reviewed Jan 4, 2025

View reviewed changes

magicznyleszek mentioned this pull request Jan 4, 2025

feat(invites): query file for handling API TASK-1092 TASK-991 (wrong base branch) #5407

Closed

9 tasks

Merge branch 'main' into task-969-create-endpoints-to-handle-org-invi…

af29b03

…tations

Update organization invitation tests and email templates

ea9a6bd

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 31ac077 to ea9a6bd Compare January 6, 2025 13:15

magicznyleszek mentioned this pull request Jan 7, 2025

feat(invites): query file for handling API TASK-1092 TASK-991 #5409

Open

Include invite object in the organization members endpoint

5394358

rajpatel24 force-pushed the task-969-create-endpoints-to-handle-org-invitations branch from 32b1431 to 5394358 Compare January 7, 2025 15:37

Add unit test to validate invite object in organization members list

93eb306

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(organizations): create endpoints to handle organization invitations #5395

feat(organizations): create endpoints to handle organization invitations #5395

rajpatel24 commented Dec 20, 2024 •

edited

Loading

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

magicznyleszek commented Jan 4, 2025 •

edited

Loading

magicznyleszek Jan 4, 2025 •

edited

Loading

rajpatel24 Jan 6, 2025

noliveleger Jan 6, 2025

rajpatel24 commented Jan 6, 2025

feat(organizations): create endpoints to handle organization invitations #5395

Are you sure you want to change the base?

feat(organizations): create endpoints to handle organization invitations #5395

Conversation

rajpatel24 commented Dec 20, 2024 • edited Loading

🗒️ Checklist

📣 Summary

📖 Description

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

notion-workspace bot commented Dec 31, 2024

magicznyleszek commented Jan 4, 2025 • edited Loading

magicznyleszek Jan 4, 2025 • edited Loading

Choose a reason for hiding this comment

rajpatel24 Jan 6, 2025

Choose a reason for hiding this comment

noliveleger Jan 6, 2025

Choose a reason for hiding this comment

rajpatel24 commented Jan 6, 2025

rajpatel24 commented Dec 20, 2024 •

edited

Loading

magicznyleszek commented Jan 4, 2025 •

edited

Loading

magicznyleszek Jan 4, 2025 •

edited

Loading