[$300] Create "POST /taas-teams/:teamId/members" endpoint

[maxceem]

Each Team in TaaS API is the same as Project in Projects API. In Projects API we already have the ability to invite members. So when users are invited they have to accept invites to become members.
In TaaS App we would like to skip the invitation process and be able to add members directly without invitation. Projects API already has an endpoint POST /projects/{projectId}/members to add members directly but it has several restrictions that don't allow us directly use it:

• it only allows adding members for Topcoder Admins or M2M token
• it only supports adding members by handle
• it only supports adding one member at a time

We have to create an endpoint POST /taas-teams/:teamId/members in TaaS API which would allow us to add members to the team:

• it should allow adding members to the Team to any user who has access to the Team
• it should support adding members by handle and by email
• it should support adding multiple members at a time
• unlike Projects API endpoint, this endpoint should always add members with role=customer - so role cannot be chosen in the request

For the implementation, we can check how POST ​/projects​/{projectId}​/invites is implemented in Projects API it supports most of these requirements, but for invites.

Suggested body request for POST /taas-teams/:teamId/members is same like for invites in Projects API

[
  handles: { "user_hanlde", "user_hanlde_2" }, // invite multiple handles
  emails: { "user_email@test.com", "user_email_4@test.com" }, // invite multiple emails
]

The response can be an object of the next shape same like we do for invites in Projects API. It would return which handles/emails were invited successfully and which failed:

{
   success: [ // this list should containt member objects created
        {
            id: 123123,
            handle: "user_hanlde"
            // ... other fields of created member object
        },
        {
            id: 234235,
            email: "user_email@test.com",
            // ... other fields of created member object            
        }
    ],
   failed: [
       { 
          handle: "user_hanlde_2",
          error: "User doesn't exist",
       },
       { 
          email: "user_email_4@test.com" 
          error: "User doesn't exist",
       },
   ]
}

• NOTE: Projects API POST /projects/{projectId}/members endpoint doesn't always return email and handle when creating members. So you would have to add this into the response manually, to match requested members with created ones. For example, email, firstName and lastName are only returned to admin users. While endpoint in TaaS Api should work for any user (who has access to the team).

• Please, keep error messages without mentioning the user handle/email. This would help us to group errors in UI, so we could show an error in UI like this: user_hanlde_2, user_email_4@test.com: User doesn't exist.

• When calling POST /projects/{projectId}/members also pass ?fields=id,userId,role,createdAt,updatedAt,createdBy,updatedBy,handle,photoURL,workingHourStart,workingHourEnd,timeZone,email so we would get additional details about the created member. We would need them for TaaS API UI: https://marvelapp.com/prototype/921gg0f/screen/75360461/handoff

• NOTE: When inviting by email we would have to find their hadles in the Identity Service. This service sometimes works not good, so we've implemented various workarounds to make it more reliable https://github.com/topcoder-platform/tc-project-service/blob/develop/src/routes/projectMemberInvites/create.js#L111-L118 like:

  • making several attempts to find users in case request fails (as it did sometimes)
  • we are filtering returned data, and remove all the users we didn't ask for, as I guess Identity Service uses some fuzzy searching and might return users we didn't search for
  • please, take these thing into account: implement the same logic in TaaS API or apply another workarounds if you know better ways.

• Update Swagger and Postman

Test Cases:

⚠️ Note, that in all these cases the response would be successful and it would only return failed requests in the failed array. The request itself should only fail if the user doesn't have access to call it, or there is some unexpected error happen, or there is a validation error of the request.

1. Successfully add one member by "handle".
2. Successfully add one member by "email".
3. Successfully add 2+ members by "handles".
4. Successfully add 2+ members by "email".
5. Successfully add 2+ members by combining "handles" and "emails".
6. Failed if we are adding a member by "handle" for an already added user.
7. Failed if we are adding a member by "email" for an already added user.
8. Failed if we are adding a member by "handle" for non-existent user.
9. Failed if we are adding a member by "email" for non-existent user.
10. If we add 6 members:
    • 1 good members by "handle"
    • 1 good member by "email"
    • 1 non-existent member by "handle"
    • 1 non-existent member by "email"
    • 1 already added member by "handle"
    • 1 already added member by "email"
      Then 2 correct ones should be added successfully and 4 should be returned in the failed array with the corresponding errors

[maxceem]

Challenge https://www.topcoder.com/challenges/e4b4a684-67e4-4026-ace6-340a27025f44 has been created for this ticket.

This is an automated message for maxceem via Topcoder X

[maxceem]

Challenge https://www.topcoder.com/challenges/e4b4a684-67e4-4026-ace6-340a27025f44 has been assigned to aaron2017.

This is an automated message for maxceem via Topcoder X

[imcaizheng]

it only supports adding members by handle

1. However, POST /projects/{projectId}/members only supports added members by userId(See https://github.com/topcoder-platform/tc-project-service/blob/develop/src/routes/projectMembers/create.js#L16-L21). I think we can first find the id of a user by its handle/email and then add the user to a team with its id.

making several attempts to find users in case request fails (as it did sometimes)

2. It wasn't implemented by the project service(See https://github.com/topcoder-platform/tc-project-service/blob/develop/src/util.js#L957-L1013, failed requests are simply ignored) Do we still need to implement the logic in taas-apis?

[maxceem]

However, POST /projects/{projectId}/members only supports added members by userId(See https://github.com/topcoder-platform/tc-project-service/blob/develop/src/routes/projectMembers/create.js#L16-L21). I think we can first find the id of a user by its handle/email and then add the user to a team with its id.

Right, so we have to find userId by handle or email and add it after.

It wasn't implemented by the project service(See https://github.com/topcoder-platform/tc-project-service/blob/develop/src/util.js#L957-L1013, failed requests are simply ignored) Do we still need to implement the logic in taas-apis?

I've misunderstood the logic. No need to implement it. We can just use this method to get multiple emails at a time.

[imcaizheng]

I found a function named lookupUserEmails here https://github.com/topcoder-platform/tc-project-service/blob/develop/src/util.js#L916-L947.
@maxceem Could we use the function instead of lookupMultipleUserEmails?

[maxceem]

I think no. That method supposed to be removed. It was replaced with lookupMultipleUserEmails here topcoder-platform/tc-project-service#334 because of the issue of the Idenity Service: it cannot filter by multiple emails properly, see issue topcoder-platform/tc-project-service#246.

[imcaizheng]

PR created #150