# RO invitations design

Document describing API designs for https://github.com/wellcometrust/corporate/issues/10167

## Notes

This is based on the Invitations API.

We considered a couple of different approaches to combining the Research Office invitations with invitations to join an application:
1. Using `/ro-invitation` in URLs and **ROInvitation...** in schema names to differentiate them from inviting users to an application. (See [Previous design](#Previous-design)). We decided we preferred not to have completely separate endpoints for the two sets of invitations.
2. Combining both invitations endpoints as a single `/invitation` endpoint and checking the data format to determine whether an invitation was for a Research Office or an Application. (See [Alternative design](#Alternative-design).) This would allowed easy resuse of code but would have resulted in some slightly messy schemas as they combined information from both invitations, so may have been prone to errors.
3. Using `/api/2/invitation/[application|research-office]` as the endpoints. (See [Suggested Middleware API Design](#Suggested-Middleware-API-design).) This will mean changing the existing application invitation endpoints, but will allow us to reuse code where appropriate but separate code where necessary.

See also these [meeting notes](https://www.notion.so/wellcometrust/RO-permissions-ebbb54dea1bb4802bb937601a1b27717) for discussion of the accept RO invitation process on login.

## Suggested Middleware API Design

Existing endpoints for invitations will be modified to include `application`, e.g.

`GET POST api/2/invitation`

will be moved to

`GET POST api/2/invitation/application`

Some schemas will also be renamed, e.g. `InvitationPostSchema` will become `ApplicationInvitationPostSchema`. Schemas that are common across both types of endpoints will remain the same.

New endpoints are described below.

### `POST api/2/invitation/research-office`

Create a new Research Office invitation and send invitation email if successful

This expects a JSON body conforming to [ResearchOfficeInvitationPostSchema](#ResearchOfficeInvitationPostSchema).

This returns a 201 on success, with the invitation code as the `data` value.

If the organisation id is invalid or the user does not have access to it, an INVALID_ORGANISATION_ID error is returned.

If the user belongs to a different Research Office, an INVALID_USER error is returned.

If the Salesforce call to create a Research Office invitation succeeds but the email sending fails straight away, a `SEND_EMAIL_ERROR`
error will be returned.

--------------------

### `GET api/2/invitation/research-office/<str:invitation_code>`

Returns the details of a Research Office invitation.

If the invitation code is not valid, a NOT_FOUND error will be returned.

Example response:

{
  "data": {
    "invitationCode": "wxyz5678",
    "invitedBy": {
      "email": "[e-mail]",
      "firstName": "Edith",
      "lastName": "Piaf",
      "middleName": "",
      "title": "Ms"
    },
    "organisation": {
      "name": "Oxbridge University",
      "organisationId": "organisation-1"
    },
    "role": "ADMIN"
  },
  "metadata": {},
  "success": true
}

--------------------

### ~~`POST api/2/invitation/research-office/<str:invitation_code>:accept`~~
> [name=Alison Clarke] Accept not needed as per [meeting notes](https://www.notion.so/wellcometrust/RO-permissions-ebbb54dea1bb4802bb937601a1b27717) and [slack conversation](https://wellcome.slack.com/archives/C02KEDRDZUG/p1666607508431559?thread_ts=1666604241.489129&cid=C02KEDRDZUG): invitation code will be passed to the register user endpoint in SF, so once registered they will automatically be added to the RO.

~~Accepts a Research Office invitation.~~

~~This returns a 200 on success.~~

~~If the invitation code is not valid, a NOT_FOUND error will be returned.~~

~~A USER_NOT_ALLOWED error will be returned if the current user is already a member of the organisation, or
the invitation was for a different user.~~

~~This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling is done by another RO member.~~

~~Returns success or failure response.~~

--------------------

### `POST api/2/invitation/research-office/<str:invitation_code>:cancel`

Cancels a Research Office invitation.

This returns a 200 on success.

If the invitation code is not valid, a NOT_FOUND error will be returned.

A USER_NOT_ALLOWED error will be returned if the current user is not an Authorised Approver.

This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling is done by another RO member.

Returns success or failure response.

--------------------

### ~~`POST api/2/invitation/research-office/<str:invitation_code>:decline`~~
> [name=Alison Clarke] Decline not needed as per [meeting notes](https://www.notion.so/wellcometrust/RO-permissions-ebbb54dea1bb4802bb937601a1b27717)

~~Declines a Research Office invitation.~~

~~This returns a 200 on success.~~

~~If the invitation code is not valid, a NOT_FOUND error will be returned.~~

~~A USER_NOT_ALLOWED error will be returned if the invitation was for a different user.~~

~~This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling is done by another RO member.~~

~~Returns success or failure response.~~

--------------------

### `POST api/2/invitation/research-office/<str:invitation_code>:resend`

Resends a Research Office invitation email.

This returns a 200 on success.

If the invitation code is not valid, a NOT_FOUND error will be returned.

A USER_NOT_ALLOWED error will be returned if the invitation was created by a different user.

This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling/resending is done by the lead applicant.

Returns success or failure response.

## Schemas

Schemas are described using <a href="https://json-schema.org/">JSON Schema</a>.

### ResearchOfficeInvitationGetSchema

{
  "definitions": {
    "ResearchOfficeInvitationOrganisationSchema": {
      "description": "Schema used to define the (limited) organisation data returned with an invitation",
      "properties": {
        "organisationId": {
          "title": "Organisationid",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        }
      },
      "required": [
        "organisationId",
        "name"
      ],
      "title": "ResearchOfficeInvitationOrganisationSchema",
      "type": "object"
    },
    "InvitationGetUserSchema": {
      "description": "Schema used to define the user who created an invitation",
      "properties": {
        "email": {
          "format": "email",
          "title": "Email",
          "type": "string"
        },
        "firstName": {
          "title": "Firstname",
          "type": "string"
        },
        "lastName": {
          "title": "Lastname",
          "type": "string"
        },
        "middleName": {
          "title": "Middlename",
          "type": "string"
        },
        "title": {
          "title": "Title",
          "type": "string"
        }
      },
      "required": [
        "title",
        "firstName",
        "middleName",
        "lastName",
        "email"
      ],
      "title": "InvitationGetUserSchema",
      "type": "object"
    }
  },
  "description": "Schema definining the response from a request to get an invitation",
  "properties": {
    "organisation": {
      "$ref": "#/definitions/ResearchOfficeInvitationOrganisationSchema"
    },
    "invitationCode": {
      "title": "Invitationcode",
      "type": "string"
    },
    "invitedBy": {
      "$ref": "#/definitions/InvitationGetUserSchema"
    },
    "permissionSet": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "invitationCode",
    "permissionSet",
    "organisation",
    "invitedBy"
  ],
  "title": "ResearchOfficeInvitationGetSchema",
  "type": "object"
}

### ResearchOfficeInvitationPostSchema

> [name=Alison Clarke] Role will always be "admin" for now but we'll keep it in the middleware schema.

{
  "description": "Schema definining the expected structure of a POST request to get a Research Office invitation",
  "properties": {
    "organisationId": {
      "title": "organisationId",
      "type": "string"
    },
    "customMessage": {
      "title": "Custommessage",
      "type": "string"
    },
    "email": {
      "format": "email",
      "title": "Email",
      "type": "string"
    },
    "role": {
      "type": "string"
    },
  },
  "required": [
    "organisationId",
    "email",
    "role"
  ],
  "title": "ResearchOfficeInvitationPostSchema",
  "type": "object"
}

## Answered Questions

* How is the email for an organisation's first user sent out? (Directly from Salesforce, or does it need to come from the funding platform app via some sort of trigger?) **(This is not in scope at the moment)**
* Is there a page displayed to an invited user before the accept (as with a co-applicant invitation)? - **No, the link goes straight through to accept**
* Who can accept/decline/cancel/resend an invitation?
* Accept/decline: **only invitee**
* Cancel/resend: **any RO authorised approver**
* How will the roles be implemented in Salesforce? Front end has:
* Roles: Authorised approver, Team member
* Additional permission: Allow to submit financial reports (Y/N)
Need to find out how this will be implemented in Salesforce: could be 4 different roles or 2 sets of permissions. Simon suggests tole plus flag for additional permission. Alice is concerned about whether that is a future-proof way of storing permissions.
* Can an RO user be a member of more than one organisation? This affects whether there is the need for a workflow where an RO user signs in to an existing account to accept the invitation. **No, a user can only be a member of one organisation. The API should reject a user who already belongs to a different RO when an admin attempts to invite them.**
* Will SF mandate the RO permissions e.g. ensuring only an admin user can create and cancel invitations? **Presumably no longer needed if we're only having admin users for MVP**
* * Will SF create an equivalent of GET invitation, to enable us to get the organisation ID before calling PATCH invitation, and to get information needed to resend an invitation email? **Have updated the JIRA ticket to request this**
* Where will the validation be done to ensure invitations are restricted to the user for whom they were created? (We can't validate it in the MW unless we have an equivalent of GET invitation, or the `GET roinvite` call validates the invite against the current user.) **We probably don't need to do this unless we implement accept/decline, but if we do then we can use the GET invitation equivalent now to validate**
* Will Salesforce ensure only RO users (admins) are able to use the `roinvite` endpoints? **Yes (but we're still thinking about MW user type validation)**
* If we're only having admins for now, should we specify that role in the H8 call to create an invitation? Or should we just not include any roles for now? **Specify in the call to H8**

# Discarded design suggestions

## Previous design

### `POST api/2/ro-invitation`

Create a new Research Office invitation and send invitation email if successful

This expects a JSON body conforming to [ROInvitationPostSchema](#ROInvitationPostSchema).

This returns a 201 on success, with the invitation code as the `data` value.

If the organisation id is invalid or the user does not have access to it, an INVALID_ORGANISATION_ID error is returned.

If the Salesforce call to create a Research Office invitation succeeds but the email sending fails straight away, a `SEND_EMAIL_ERROR`
error will be returned.

--------------------

### `GET api/2/ro-invitation/<str:invitation_code>`

**FIXME: need to know what info we need to display on accept invitation page - is this needed at all?**

Gets information about a Research Office invitation.

This returns JSON conforming to [ROInvitationGetSchema](#ROInvitationGetSchema).

If the invitation code is not valid, a NOT_FOUND error will be returned.

Example response:

{
    "success": True,
    "data": {
        "invitationCode": "wxyz5678",
        "permissionSet": ["AUTHORISED_APPROVER", "FINANCE"]
        "organisation": {
            "organisationId": "organisation-1",
            "name": "University of Someplace"
        },
        "invitedBy": {
            "title": "Ms",
            "firstName": "Edith",
            "middleName": "",
            "lastName": "Piaf",
            "email": "[e-mail]",
        },
    },
    "metadata": {},
}

--------------------

### `POST api/2/ro-invitation/<str:invitation_code>:accept`

Accepts a Research Office invitation.

This returns a 200 on success.

If the invitation code is not valid, a NOT_FOUND error will be returned.

A USER_NOT_ALLOWED error will be returned if the current user is already a member of the organisation, or
the invitation was for a different user.

This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling is done by another RO member.

Returns success or failure response.

--------------------

### `POST api/2/ro-invitation/<str:invitation_code>:cancel`

Cancels a Research Office invitation.

This returns a 200 on success.

If the invitation code is not valid, a NOT_FOUND error will be returned.

A USER_NOT_ALLOWED error will be returned if the current user is not an Authorised Approver.

This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling is done by another RO member.

Returns success or failure response.

--------------------

### `POST api/2/ro-invitation/<str:invitation_code>:decline`

Declines a Research Office invitation.

This returns a 200 on success.

If the invitation code is not valid, a NOT_FOUND error will be returned.

A USER_NOT_ALLOWED error will be returned if the invitation was for a different user.

This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling is done by another RO member.

Returns success or failure response.

--------------------

### `POST api/2/ro-invitation/<str:invitation_code>:resend`

Resends a Research Office invitation email.

This returns a 200 on success.

If the invitation code is not valid, a NOT_FOUND error will be returned.

A USER_NOT_ALLOWED error will be returned if the invitation was created by a different user.

This is a [custom method](https://cloud.google.com/apis/design/custom_methods) rather than a simple PATCH because
accepting/declining a Research Office invitation is done by the invitee whereas cancelling/resending is done by the lead applicant.

Returns success or failure response.

## Schemas

Schemas are described using <a href="https://json-schema.org/">JSON Schema</a>.

### ROInvitationGetSchema

{
  "definitions": {
    "ROInvitationOrganisationSchema": {
      "description": "Schema used to define the (limited) organisation data returned with an invitation",
      "properties": {
        "organisationId": {
          "title": "Organisationid",
          "type": "string"
        },
        "name": {
          "title": "Name",
          "type": "string"
        }
      },
      "required": [
        "organisationId",
        "name"
      ],
      "title": "ROInvitationOrganisationSchema",
      "type": "object"
    },
    "ROInvitationGetUserSchema": {
      "description": "Schema used to define the user who created an RO invitation",
      "properties": {
        "email": {
          "format": "email",
          "title": "Email",
          "type": "string"
        },
        "firstName": {
          "title": "Firstname",
          "type": "string"
        },
        "lastName": {
          "title": "Lastname",
          "type": "string"
        },
        "middleName": {
          "title": "Middlename",
          "type": "string"
        },
        "title": {
          "title": "Title",
          "type": "string"
        }
      },
      "required": [
        "title",
        "firstName",
        "middleName",
        "lastName",
        "email"
      ],
      "title": "ROInvitationGetUserSchema",
      "type": "object"
    }
  },
  "description": "Schema definining the response from a request to get an invitation",
  "properties": {
    "organisation": {
      "$ref": "#/definitions/ROInvitationOrganisationSchema"
    },
    "invitationCode": {
      "title": "Invitationcode",
      "type": "string"
    },
    "invitedBy": {
      "$ref": "#/definitions/ROInvitationGetUserSchema"
    },
    "permissionSet": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "invitationCode",
    "role",
    "organisation",
    "invitedBy"
  ],
  "title": "ROInvitationGetSchema",
  "type": "object"
}

### ROInvitationPostSchema

{
  "description": "Schema definining the expected structure of a POST request to get a Research Office invitation",
  "properties": {
    "organisationId": {
      "title": "organisationId",
      "type": "string"
    },
    "customMessage": {
      "title": "Custommessage",
      "type": "string"
    },
    "email": {
      "format": "email",
      "title": "Email",
      "type": "string"
    },
    "role": {
      "title": "Role",
      "type": "string"
    },
    "additional_permissions": {
      "title": "Additionalpermissions",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "organisationId",
    "email",
    "role"
  ],
  "title": "ROInvitationPostSchema",
  "type": "object"
}

## Alternative Middleware API design - combining both sets of invitations

### `POST api/2/invitation`

Create a new Research Office invitation and send invitation email if successful

This expects a JSON body conforming to [InvitationPostSchema](InvitationPostSchema) which would be modified to allow both the application and research office invitation types (some fields are common, others would be different).

NB: This is possible in JSON schema using `oneOf`, and in pydantic using `Union`. The resulting JSON schema would look [a bit complex](#Example-combined-PostInvitationSchema) but would work. We could determine the object type after validation to determine which H8 API endpoint to call.

e.g., assuming `ApplicationInvitationPostSchema` and `InvitationPostSchema` are defined:

class InvitationPostSchema(BaseModel):
    __root__: Union[ApplicationInvitationPostSchema, ROInvitationPostSchema] = Field(
        ..., description='Schema validating invitation for application or RO'
    )

[Full code sample](#Example-combined-PostInvitationSchema)

This returns a 201 on success, with the invitation code as the `data` value.

If the organisation id is invalid or the user does not have access to it, an INVALID_ORGANISATION_ID error is returned.

If the Salesforce call to create a Research Office invitation succeeds but the email sending fails straight away, a `SEND_EMAIL_ERROR`
error will be returned.

--------------------

### `GET api/2/invitation/(?P<type>application|ro)/<str:invitation_code>`

The URL will specify whether this is an application or a research office invitation.

As per the POST schema, we could use a `Union` at the root level of the schema to return the relevant properties for a research office vs an application invitation.

--------------------

### `POST api/2/invitation/(?P<type>application|ro)/<str:invitation_code>:accept`

Accepts an invitation.

--------------------

### `POST api/2/invitation/(?P<type>application|ro)/<str:invitation_code>:cancel`

Cancels an invitation.

--------------------

### `POST api/2/invitation/(?P<type>application|ro)/<str:invitation_code>:decline`

Declines an invitation.

--------------------

### `POST api/2/invitation/(?P<type>application|ro)/<str:invitation_code>:resend`

Resends an invitation email.

### Example combined PostInvitationSchema

Pydantic schema:

class InvitationPostBaseSchema(BaseModel):
    email: EmailStr
    customMessage: Optional[str]
    

class ApplicationInvitationPostSchema(InvitationPostBaseSchema):
    """Schema definining the expected structure of a POST request to get an invitation for an application"""
    applicationId: str
    role: str


class ROInvitationPostSchema(InvitationPostBaseSchema):
    """Schema definining the expected structure of a POST request to get an invitation for a research office"""
    organisationId: str
    permissions: List[str]


class InvitationPostSchema(BaseModel):
    __root__: Union[ApplicationInvitationPostSchema, ROInvitationPostSchema] = Field(
        ..., description='schema validating invitation for application or RO'
    )
    

Generated JSON schema:

{
  "anyOf": [
    {
      "$ref": "#/definitions/ApplicationInvitationPostSchema"
    },
    {
      "$ref": "#/definitions/ROInvitationPostSchema"
    }
  ],
  "definitions": {
    "ApplicationInvitationPostSchema": {
      "description": "Schema definining the expected structure of a POST request to get an invitation for an application",
      "properties": {
        "applicationId": {
          "title": "Applicationid",
          "type": "string"
        },
        "customMessage": {
          "title": "Custommessage",
          "type": "string"
        },
        "email": {
          "format": "email",
          "title": "Email",
          "type": "string"
        },
        "role": {
          "title": "Role",
          "type": "string"
        }
      },
      "required": [
        "email",
        "applicationId",
        "role"
      ],
      "title": "ApplicationInvitationPostSchema",
      "type": "object"
    },
    "ROInvitationPostSchema": {
      "description": "Schema definining the expected structure of a POST request to get an invitation for a research office",
      "properties": {
        "customMessage": {
          "title": "Custommessage",
          "type": "string"
        },
        "email": {
          "format": "email",
          "title": "Email",
          "type": "string"
        },
        "organisationId": {
          "title": "Organisationid",
          "type": "string"
        },
        "permissions": {
          "items": {
            "type": "string"
          },
          "title": "Permissions",
          "type": "array"
        }
      },
      "required": [
        "email",
        "organisationId",
        "permissions"
      ],
      "title": "ROInvitationPostSchema",
      "type": "object"
    }
  },
  "description": "Schema definining the expected structure of a POST request to get an invitation",
  "title": "InvitationPostSchema"
}

(Note that pydantic maps `Union` to `anyOf` rather than `oneOf` - see https://github.com/samuelcolvin/pydantic/issues/656 for discussion.)