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", "demo13@demo13.com", "demo25@demo25.com"],
    "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": "demo25@demo25.com"
    }
]

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": "demo25@demo25.com"
        }
    ]
}

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?

kobo/apps/organizations/models.py

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

…tations

noliveleger · 2025-01-13T21:44:51Z

kobo/apps/organizations/serializers.py

+    def create(self, validated_data):
+        """
+        Create multiple invitations for the provided invitees.


move it before underscore prefixed methods.

noliveleger · 2025-01-13T21:49:15Z

kobo/apps/organizations/tasks.py

+    # Get sender's organization without using the cached organization property,
+    # as it may be outdated.
+    sender_organization = Organization.objects.filter(
+        organization_users__user=sender
+    ).first()
+    recipient = sender_organization.owner_user_object


How can it be outdated since the cache only lives during the request?
Can you provide some examples to reproduce the issue?

I'm updating the user's organization during the PATCH request (when the invitee accepts the invitation). However, after updating the user's organization, when I try to fetch the organization using the organization property, it doesn't return the updated value. It's working fine if we remove the @cache_for_request decorator. I've tried several ways to update the cached value but haven't been successful.

I see, can you try to use void_cache_for_request() decorator somewhere, somehow to update sender.organization? Your solution does work but it means somewhere we could still call sender.organization and organization would not the correct one (until the request ends).

kobo/apps/organizations/models.py

noliveleger · 2025-01-15T22:04:52Z

kobo/apps/organizations/templates/emails/accepted_invite.txt

+
+{% trans "All projects, submissions, data storage, transcription and translation usage for their projects will be transferred to you." %}
+
+{% trans "Note: You will continue to have permissions to manage these projects until the user permissions are changed." %}


I don't think this sentence should be here since that's the sender who receives this message.
(Please fix HTML template too)

noliveleger · 2025-01-15T22:12:08Z

kobo/apps/organizations/templates/emails/registered_user_invite.txt

@@ -0,0 +1,18 @@
+{% load i18n %}
+{% trans "Hello," %}


Let's be a little more fancy,
If email has been sent to a username, let's use: Hello <username>
if email has been sent to a valid email with only one account, let's use: Hello <username>
if email has been sent to a valid email with more than one account, let's use: Hello <email> .

Then get rid of (username: {{ recipient_username }}) in block below

What happens if invitation is sent to an email with multiple account? I don't see the template for that? The text is little bit different

Sure, I've updated the template accordingly.

Regarding the template for multiple accounts, it is included in the same template with the has_multiple_accounts condition. I’ve also updated some text for it.

…atuses from the model

noliveleger · 2025-01-16T14:44:13Z

kobo/apps/organizations/constants.py

@@ -1,4 +1,24 @@
+INVITE_OWNER_ERROR = (
+    'This account is already the owner of {organization_name}. '


By convention, we are using ##placeholder## to let the translators know it is a placeholder and it should not be translated.

As per our discussion, @rajpatel24 may create an utility function to replace placeholders (instead of calling .replace().replace().etc)

noliveleger · 2025-01-16T14:49:08Z

kobo/apps/organizations/models.py

+
+        email_message = EmailMessage(
+            to=self.invited_by.email,
+            subject=t('KoboToolbox organization invitation accepted'),


You probably need to call translation.activate(<language>) to be sure the correct language is loaded.

sender_language = self.invited_by.extra_details.data.get('last_ui_language', DEFAULT_LANGUAGE) translation.activate(sender_language)

As per our internal discussion:
last_ui_language was used only for reports.

we should make sure it's clear in the code that we use that attribute for more than just reports

Please add a comment in ExtraUserDetail that it is also used to translate (email) templates in the user's language.

noliveleger · 2025-01-16T14:52:23Z

kobo/apps/organizations/models.py

+        # Get recipient role with an article
+        recipient_role = self.invitee_role
+        if recipient_role and recipient_role[0].lower() in 'aeiou':
+            recipient_role = 'an ' + recipient_role


Should be the whole string to translate it.

recipient_role = t('an admin') if self.invitee_role === 'admin' else t('a member') ```

noliveleger · 2025-01-16T14:54:17Z

kobo/apps/organizations/permissions.py

+class OrgMembershipInvitePermission(
+    ValidationPasswordPermissionMixin, IsAuthenticated
+):


During QA, anybody was able to see all invites from an org.

Admins and owner should be able to see all their org invites

Others should see all the invites related to them

Nobody should be able to see invites of other orgs.

noliveleger · 2025-01-16T14:59:42Z

kobo/apps/organizations/tasks.py

+    # Get sender's organization without using the cached organization property,
+    # as it may be outdated.
+    sender_organization = Organization.objects.filter(
+        organization_users__user=sender
+    ).first()
+    recipient = sender_organization.owner_user_object


I see, can you try to use void_cache_for_request() decorator somewhere, somehow to update sender.organization? Your solution does work but it means somewhere we could still call sender.organization and organization would not the correct one (until the request ends).

noliveleger · 2025-01-16T15:04:11Z

kobo/apps/organizations/tests/test_organization_invitations.py

+        self.client.force_login(user)
+        return self.client.patch(self.detail_url(guid), data={'status': status})
+
+    def test_owner_can_send_invitation(self):


We need to test that owner and admins can send invitations but no one else. (member and anonymous).

noliveleger · 2025-01-16T15:04:34Z

kobo/apps/organizations/tests/test_organization_invitations.py

+        self.assertEqual(response.data['status'], 'resent')
+        self.assertEqual(mail.outbox[0].to[0], invitation.invitee.email)
+
+    def test_owner_can_cancel_invitation(self):


Same comment, we need to test every role just to be sure.

noliveleger · 2025-01-16T15:05:36Z

kobo/apps/organizations/tests/test_organization_invitations.py

+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(response.data['status'], 'cancelled')
+
+    def test_list_invitations(self):


We need also to test someone from OrganizationA cannot list invitations from OrganizationB (if they don't belong to it).

noliveleger · 2025-01-16T15:12:06Z

kobo/apps/organizations/views.py

+    serializer_class = OrgMembershipInviteSerializer
+    permission_classes = [OrgMembershipInvitePermission]
+    http_method_names = ['get', 'post', 'patch', 'delete']
+    lookup_field = 'guid'


Let's see if we can use our KpiUidField (this comment should in the model :-P) instead of this guid to be consistent with other fields. If cannot be replaced, no need to have two different fields which do the same thing.

noliveleger · 2025-01-16T15:12:18Z

kobo/apps/organizations/views.py

+            'invitee', 'invited_by', 'organization'
+        ).filter(organization_id=organization_id)
+
+    def create(self, request, *args, **kwargs):


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

kobo/apps/organizations/models.py Show resolved Hide resolved

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

rajpatel24 and others added 2 commits January 13, 2025 16:43

Add unit test to validate invite object in organization members list

93eb306

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

1674881

…tations

noliveleger requested changes Jan 15, 2025

View reviewed changes

Update organization invitation email templates and remove unwanted st…

c230f54

…atuses from the model

noliveleger requested changes Jan 16, 2025

View reviewed changes

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

rajpatel24 commented Jan 6, 2025

noliveleger Jan 13, 2025

noliveleger Jan 13, 2025

rajpatel24 Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 15, 2025

noliveleger Jan 15, 2025

rajpatel24 Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025

noliveleger Jan 16, 2025


		{% trans "All projects, submissions, data storage, transcription and translation usage for their projects will be transferred to you." %}

		{% trans "Note: You will continue to have permissions to manage these projects until the user permissions are changed." %}

		@@ -1,4 +1,24 @@
		INVITE_OWNER_ERROR = (
		'This account is already the owner of {organization_name}. '

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

rajpatel24 commented Jan 6, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rajpatel24 commented Dec 20, 2024 •

edited

Loading

magicznyleszek commented Jan 4, 2025 •

edited

Loading