694 lines
23 KiB
Plaintext
694 lines
23 KiB
Plaintext
namespace team
|
|
|
|
import async
|
|
import users
|
|
import common
|
|
import team_common
|
|
|
|
union_closed AdminTier
|
|
"Describes which team-related admin permissions a user has."
|
|
|
|
team_admin
|
|
"User is an administrator of the team - has all permissions."
|
|
user_management_admin
|
|
"User can do most user provisioning, de-provisioning and management."
|
|
support_admin
|
|
"User can do a limited set of common support tasks for existing users."
|
|
member_only
|
|
"User is not an admin of the team."
|
|
|
|
example default
|
|
member_only = null
|
|
|
|
#
|
|
# Common structs
|
|
#
|
|
|
|
struct TeamMemberProfile extends MemberProfile
|
|
"Profile of a user as a member of a team."
|
|
|
|
groups List(team_common.GroupId)
|
|
"List of group IDs of groups that the user belongs to."
|
|
member_folder_id common.NamespaceId
|
|
"The namespace id of the user's root folder."
|
|
|
|
example default
|
|
team_member_id = "dbmid:FDFSVF-DFSDF"
|
|
account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
|
|
external_id = "244423"
|
|
email = "tami@seagull.com"
|
|
email_verified = false
|
|
status = active
|
|
name = default
|
|
groups = ["g:e2db7665347abcd600000000001a2b3c"]
|
|
membership_type = full
|
|
joined_on = "2015-05-12T15:50:38Z"
|
|
member_folder_id = "20"
|
|
|
|
union_closed MemberSelectorError extends UserSelectorError
|
|
user_not_in_team
|
|
"The user is not a member of the team."
|
|
|
|
|
|
########################
|
|
# Member info routes
|
|
########################
|
|
|
|
#
|
|
# Route: members/list
|
|
#
|
|
|
|
struct MembersListArg
|
|
limit UInt32(min_value=1, max_value=1000) = 1000
|
|
"Number of results to return per call."
|
|
include_removed Boolean = false
|
|
"Whether to return removed members."
|
|
|
|
example default
|
|
limit = 100
|
|
include_removed = false
|
|
|
|
|
|
struct TeamMemberInfo
|
|
"Information about a team member."
|
|
|
|
profile TeamMemberProfile
|
|
"Profile of a user as a member of a team."
|
|
role AdminTier
|
|
"The user's role in the team."
|
|
|
|
example default
|
|
profile = default
|
|
role = member_only
|
|
|
|
|
|
struct MembersListResult
|
|
members List(TeamMemberInfo)
|
|
"List of team members."
|
|
cursor String
|
|
"Pass the cursor into :route:`members/list/continue` to obtain the additional members."
|
|
has_more Boolean
|
|
"Is true if there are additional team members that have not been returned
|
|
yet. An additional call to :route:`members/list/continue` can retrieve them."
|
|
|
|
example default
|
|
members = [default]
|
|
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
|
|
has_more = true
|
|
|
|
|
|
union MembersListError
|
|
""
|
|
|
|
route members/list(MembersListArg, MembersListResult, MembersListError)
|
|
"Lists members of a team.
|
|
|
|
Permission : Team information."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
|
|
#
|
|
# Route: members/list/continue
|
|
#
|
|
|
|
struct MembersListContinueArg
|
|
cursor String
|
|
"Indicates from what point to get the next set of members."
|
|
|
|
example default
|
|
cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
|
|
|
|
union MembersListContinueError
|
|
invalid_cursor
|
|
"The cursor is invalid."
|
|
|
|
route members/list/continue(MembersListContinueArg, MembersListResult, MembersListContinueError)
|
|
"Once a cursor has been retrieved from :route:`members/list`, use this to paginate
|
|
through all team members.
|
|
|
|
Permission : Team information."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
|
|
#
|
|
# Route: members/get_info
|
|
#
|
|
|
|
struct MembersGetInfoArgs
|
|
members List(UserSelectorArg)
|
|
"List of team members."
|
|
|
|
example default
|
|
members = [default]
|
|
|
|
union_closed MembersGetInfoItem
|
|
"Describes a result obtained for a single user whose id was specified in the
|
|
parameter of :route:`members/get_info`."
|
|
|
|
id_not_found String
|
|
"An ID that was provided as a parameter to :route:`members/get_info`,
|
|
and did not match a corresponding user. This might be a team_member_id, an
|
|
email, or an external ID, depending on how the method was called."
|
|
member_info TeamMemberInfo
|
|
"Info about a team member."
|
|
|
|
example default
|
|
member_info = default
|
|
|
|
|
|
# Information returned by :route:`members/get_info`.
|
|
# describing multiple team members."
|
|
alias MembersGetInfoResult = List(MembersGetInfoItem)
|
|
|
|
|
|
union MembersGetInfoError
|
|
""
|
|
|
|
|
|
route members/get_info(MembersGetInfoArgs, MembersGetInfoResult, MembersGetInfoError)
|
|
"Returns information about multiple team members.
|
|
|
|
Permission : Team information
|
|
|
|
This endpoint will return :field:`MembersGetInfoItem.id_not_found`,
|
|
for IDs (or emails) that cannot be matched to a valid team member."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
|
|
##########################
|
|
# Member management routes
|
|
##########################
|
|
|
|
|
|
#
|
|
# Route members/add
|
|
#
|
|
|
|
struct MemberAddArg
|
|
member_email common.EmailAddress
|
|
member_given_name common.OptionalNamePart?
|
|
"Member's first name."
|
|
member_surname common.OptionalNamePart?
|
|
"Member's last name."
|
|
member_external_id team_common.MemberExternalId?
|
|
"External ID for member."
|
|
member_persistent_id String?
|
|
"Persistent ID for member. This field is only available to teams using persistent ID SAML configuration."
|
|
send_welcome_email Boolean = true
|
|
"Whether to send a welcome email to the member.
|
|
If send_welcome_email is false, no email invitation will be sent to the user.
|
|
This may be useful for apps using single sign-on (SSO) flows for onboarding that
|
|
want to handle announcements themselves."
|
|
role AdminTier = member_only
|
|
is_directory_restricted Boolean?
|
|
"Whether a user is directory restricted."
|
|
|
|
example default
|
|
member_email = "tom.s@company.com"
|
|
member_given_name = "Tom"
|
|
member_surname = "Silverstone"
|
|
member_external_id = "company_id:342432"
|
|
role = default
|
|
|
|
struct MembersAddArg
|
|
new_members List(MemberAddArg)
|
|
"Details of new members to be added to the team."
|
|
force_async Boolean = false
|
|
"Whether to force the add to happen asynchronously."
|
|
|
|
example default
|
|
new_members = [default]
|
|
|
|
|
|
union_closed MemberAddResult
|
|
"Describes the result of attempting to add a single user to the team.
|
|
'success' is the only value indicating that a user was indeed added to the team -
|
|
the other values explain the type of failure that occurred, and include the email
|
|
of the user for which the operation has failed."
|
|
|
|
success TeamMemberInfo
|
|
"Describes a user that was successfully added to the team."
|
|
team_license_limit common.EmailAddress
|
|
"Team is already full. The organization has no available licenses."
|
|
free_team_member_limit_reached common.EmailAddress
|
|
"Team is already full. The free team member limit has been reached."
|
|
user_already_on_team common.EmailAddress
|
|
"User is already on this team. The provided email address is associated
|
|
with a user who is already a member of (including in recoverable state) or invited to the team."
|
|
user_on_another_team common.EmailAddress
|
|
"User is already on another team. The provided email address is associated
|
|
with a user that is already a member or invited to another team."
|
|
user_already_paired common.EmailAddress
|
|
"User is already paired."
|
|
user_migration_failed common.EmailAddress
|
|
"User migration has failed."
|
|
duplicate_external_member_id common.EmailAddress
|
|
"A user with the given external member ID already exists on the team (including in recoverable state)."
|
|
duplicate_member_persistent_id common.EmailAddress
|
|
"A user with the given persistent ID already exists on the team (including in recoverable state)."
|
|
persistent_id_disabled common.EmailAddress
|
|
"Persistent ID is only available to teams with persistent ID SAML configuration. Please contact Dropbox for more information."
|
|
user_creation_failed common.EmailAddress
|
|
"User creation has failed."
|
|
|
|
example default
|
|
success = default
|
|
|
|
union_closed MembersAddLaunch extends async.LaunchResultBase
|
|
complete List(MemberAddResult)
|
|
|
|
example default
|
|
complete = [default]
|
|
|
|
route members/add(MembersAddArg, MembersAddLaunch, Void)
|
|
"Adds members to a team.
|
|
|
|
Permission : Team member management
|
|
|
|
A maximum of 20 members can be specified in a single call.
|
|
|
|
If no Dropbox account exists with the email address specified, a new Dropbox account will
|
|
be created with the given email address, and that account will be invited to the team.
|
|
|
|
If a personal Dropbox account exists with the email address specified in the call,
|
|
this call will create a placeholder Dropbox account for the user on the team and send an
|
|
email inviting the user to migrate their existing personal account onto the team.
|
|
|
|
Team member management apps are required to set an initial given_name and surname for a
|
|
user to use in the team invitation and for 'Perform as team member' actions taken on
|
|
the user before they become 'active'."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
#
|
|
# Route members/add/job_status/get
|
|
#
|
|
|
|
union_closed MembersAddJobStatus extends async.PollResultBase
|
|
complete List(MemberAddResult)
|
|
"The asynchronous job has finished. For each member that was specified in the
|
|
parameter :type:`MembersAddArg` that was provided to :route:`members/add`, a
|
|
corresponding item is returned in this list."
|
|
failed String
|
|
"The asynchronous job returned an error. The string contains an error message."
|
|
|
|
example default
|
|
complete = [default]
|
|
|
|
route members/add/job_status/get(async.PollArg, MembersAddJobStatus, async.PollError)
|
|
"Once an async_job_id is returned from :route:`members/add` ,
|
|
use this to poll the status of the asynchronous request.
|
|
|
|
Permission : Team member management."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
#
|
|
# Route members/set_profile
|
|
#
|
|
|
|
# Note that we do not allow changing 'familiar_name' and 'display_name from users.Name, since they
|
|
# are derived from the given_name, surname and locale.
|
|
struct MembersSetProfileArg
|
|
"Exactly one of team_member_id, email, or external_id must be provided to identify the user account.
|
|
|
|
At least one of new_email, new_external_id, new_given_name, and/or new_surname must be provided."
|
|
|
|
user UserSelectorArg
|
|
"Identity of user whose profile will be set."
|
|
new_email common.EmailAddress?
|
|
"New email for member."
|
|
new_external_id team_common.MemberExternalId?
|
|
"New external ID for member."
|
|
new_given_name common.OptionalNamePart?
|
|
"New given name for member."
|
|
new_surname common.OptionalNamePart?
|
|
"New surname for member."
|
|
new_persistent_id String?
|
|
"New persistent ID. This field only available to teams using persistent ID SAML configuration."
|
|
new_is_directory_restricted Boolean?
|
|
"New value for whether the user is a directory restricted user."
|
|
|
|
example default
|
|
user = default
|
|
new_email = "t.smith@domain.com"
|
|
new_surname = "Smith"
|
|
|
|
union MembersSetProfileError extends MemberSelectorError
|
|
external_id_and_new_external_id_unsafe
|
|
"It is unsafe to use both external_id and new_external_id."
|
|
no_new_data_specified
|
|
"None of new_email, new_given_name, new_surname, or new_external_id are specified."
|
|
email_reserved_for_other_user
|
|
"Email is already reserved for another user."
|
|
external_id_used_by_other_user
|
|
"The external ID is already in use by another team member."
|
|
set_profile_disallowed
|
|
"Modifying deleted users is not allowed."
|
|
param_cannot_be_empty
|
|
"Parameter new_email cannot be empty."
|
|
persistent_id_disabled
|
|
"Persistent ID is only available to teams with persistent ID SAML configuration. Please contact Dropbox for more information."
|
|
persistent_id_used_by_other_user
|
|
"The persistent ID is already in use by another team member."
|
|
directory_restricted_off
|
|
"Directory Restrictions option is not available."
|
|
|
|
|
|
route members/set_profile(MembersSetProfileArg, TeamMemberInfo, MembersSetProfileError)
|
|
"Updates a team member's profile.
|
|
|
|
Permission : Team member management."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "identity"
|
|
|
|
#
|
|
# Route members/set_admin_permissions
|
|
#
|
|
|
|
struct MembersSetPermissionsArg
|
|
"Exactly one of team_member_id, email, or external_id must be provided to identify the user account."
|
|
|
|
user UserSelectorArg
|
|
"Identity of user whose role will be set."
|
|
new_role AdminTier
|
|
"The new role of the member."
|
|
|
|
example default
|
|
user = default
|
|
new_role = default
|
|
|
|
|
|
struct MembersSetPermissionsResult
|
|
team_member_id team_common.TeamMemberId
|
|
"The member ID of the user to which the change was applied."
|
|
role AdminTier
|
|
"The role after the change."
|
|
|
|
example default
|
|
team_member_id = "dbmid:9978889"
|
|
role = default
|
|
|
|
|
|
union MembersSetPermissionsError extends UserSelectorError
|
|
last_admin
|
|
"Cannot remove the admin setting of the last admin."
|
|
user_not_in_team
|
|
"The user is not a member of the team."
|
|
cannot_set_permissions
|
|
"Cannot remove/grant permissions."
|
|
team_license_limit
|
|
"Team is full. The organization has no available licenses."
|
|
|
|
route members/set_admin_permissions(MembersSetPermissionsArg, MembersSetPermissionsResult, MembersSetPermissionsError)
|
|
"Updates a team member's permissions.
|
|
|
|
Permission : Team member management."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
|
|
#
|
|
# Route members/send_welcome_email
|
|
#
|
|
|
|
union MembersSendWelcomeError extends MemberSelectorError
|
|
""
|
|
|
|
route members/send_welcome_email(UserSelectorArg, Void, MembersSendWelcomeError)
|
|
"Sends welcome email to pending team member.
|
|
|
|
Permission : Team member management
|
|
|
|
Exactly one of team_member_id, email, or external_id must be provided to identify the user account.
|
|
|
|
No-op if team member is not pending."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "try-commit-platform"
|
|
|
|
|
|
#
|
|
# Route members/remove
|
|
#
|
|
|
|
struct MembersDeactivateBaseArg
|
|
"Exactly one of team_member_id, email, or external_id must be provided to identify the user account."
|
|
|
|
user UserSelectorArg
|
|
"Identity of user to remove/suspend/have their files moved."
|
|
|
|
struct MembersDeactivateArg extends MembersDeactivateBaseArg
|
|
wipe_data Boolean = true
|
|
"If provided, controls if the user's data will be deleted on their linked devices."
|
|
|
|
example default
|
|
user = default
|
|
wipe_data = false
|
|
|
|
struct MembersRemoveArg extends MembersDeactivateArg
|
|
transfer_dest_id UserSelectorArg?
|
|
"If provided, files from the deleted member account will be
|
|
transferred to this user."
|
|
transfer_admin_id UserSelectorArg?
|
|
"If provided, errors during the transfer process will be sent via
|
|
email to this user. If the transfer_dest_id argument was provided,
|
|
then this argument must be provided as well."
|
|
|
|
keep_account Boolean = false
|
|
"Downgrade the member to a Basic account. The user will retain the email address associated with their Dropbox
|
|
account and data in their account that is not restricted to team members. In order to keep the account the argument wipe_data should be set to False."
|
|
|
|
example default
|
|
user = default
|
|
wipe_data = true
|
|
transfer_dest_id = default
|
|
transfer_admin_id = default
|
|
keep_account = false
|
|
|
|
union MembersDeactivateError extends UserSelectorError
|
|
user_not_in_team
|
|
"The user is not a member of the team."
|
|
|
|
union MembersTransferFilesError extends MembersDeactivateError
|
|
removed_and_transfer_dest_should_differ
|
|
"Expected removed user and transfer_dest user to be different."
|
|
removed_and_transfer_admin_should_differ
|
|
"Expected removed user and transfer_admin user to be different."
|
|
transfer_dest_user_not_found
|
|
"No matching user found for the argument transfer_dest_id."
|
|
transfer_dest_user_not_in_team
|
|
"The provided transfer_dest_id does not exist on this team."
|
|
transfer_admin_user_not_in_team
|
|
"The provided transfer_admin_id does not exist on this team."
|
|
transfer_admin_user_not_found
|
|
"No matching user found for the argument transfer_admin_id."
|
|
unspecified_transfer_admin_id
|
|
"The transfer_admin_id argument must be provided when file transfer is requested."
|
|
transfer_admin_is_not_admin
|
|
"Specified transfer_admin user is not a team admin."
|
|
recipient_not_verified
|
|
"The recipient user's email is not verified."
|
|
|
|
union MembersRemoveError extends MembersTransferFilesError
|
|
remove_last_admin
|
|
"The user is the last admin of the team, so it cannot be removed from it."
|
|
cannot_keep_account_and_transfer
|
|
"Cannot keep account and transfer the data to another user at the same time."
|
|
cannot_keep_account_and_delete_data
|
|
"Cannot keep account and delete the data at the same time. To keep the account the argument wipe_data should be set to False."
|
|
email_address_too_long_to_be_disabled
|
|
# Added value in order to handle task T82902.
|
|
"The email address of the user is too long to be disabled."
|
|
cannot_keep_invited_user_account
|
|
"Cannot keep account of an invited user."
|
|
|
|
route members/remove(MembersRemoveArg, async.LaunchEmptyResult, MembersRemoveError)
|
|
"Removes a member from a team.
|
|
|
|
Permission : Team member management
|
|
|
|
Exactly one of team_member_id, email, or external_id must be provided to identify the user account.
|
|
|
|
Accounts can be recovered via :route:`members/recover` for a 7 day period
|
|
or until the account has been permanently deleted or transferred to another account
|
|
(whichever comes first). Calling :route:`members/add` while a user is still recoverable
|
|
on your team will return with :field:`MemberAddResult.user_already_on_team`.
|
|
|
|
Accounts can have their files transferred via the admin console for a limited time, based on the version history
|
|
length associated with the team (120 days for most teams).
|
|
|
|
This endpoint may initiate an asynchronous job. To obtain the final result
|
|
of the job, the client should periodically poll :route:`members/remove/job_status/get`."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
#
|
|
# Route members/remove/job_status/get
|
|
#
|
|
|
|
route members/remove/job_status/get(async.PollArg, async.PollEmptyResult, async.PollError)
|
|
"Once an async_job_id is returned from :route:`members/remove` ,
|
|
use this to poll the status of the asynchronous request.
|
|
|
|
Permission : Team member management."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
#
|
|
# Route members/suspend
|
|
#
|
|
|
|
union MembersSuspendError extends MembersDeactivateError
|
|
suspend_inactive_user
|
|
"The user is not active, so it cannot be suspended."
|
|
suspend_last_admin
|
|
"The user is the last admin of the team, so it cannot be suspended."
|
|
team_license_limit
|
|
"Team is full. The organization has no available licenses."
|
|
|
|
route members/suspend(MembersDeactivateArg, Void, MembersSuspendError)
|
|
"Suspend a member from a team.
|
|
|
|
Permission : Team member management
|
|
|
|
Exactly one of team_member_id, email, or external_id must be provided to identify the user account."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
#
|
|
# Route members/unsuspend
|
|
#
|
|
|
|
struct MembersUnsuspendArg
|
|
"Exactly one of team_member_id, email, or external_id must be provided to identify the user account."
|
|
|
|
user UserSelectorArg
|
|
"Identity of user to unsuspend."
|
|
|
|
example default
|
|
user = default
|
|
|
|
|
|
union MembersUnsuspendError extends MembersDeactivateError
|
|
unsuspend_non_suspended_member
|
|
"The user is unsuspended, so it cannot be unsuspended again."
|
|
team_license_limit
|
|
"Team is full. The organization has no available licenses."
|
|
|
|
route members/unsuspend(MembersUnsuspendArg, Void, MembersUnsuspendError)
|
|
"Unsuspend a member from a team.
|
|
|
|
Permission : Team member management
|
|
|
|
Exactly one of team_member_id, email, or external_id must be provided to identify the user account."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
#
|
|
# Route members/recover
|
|
#
|
|
|
|
struct MembersRecoverArg
|
|
"Exactly one of team_member_id, email, or external_id must be provided to identify the user account."
|
|
|
|
user UserSelectorArg
|
|
"Identity of user to recover."
|
|
|
|
example default
|
|
user = default
|
|
|
|
|
|
union MembersRecoverError extends UserSelectorError
|
|
user_unrecoverable
|
|
"The user is not recoverable."
|
|
user_not_in_team
|
|
"The user is not a member of the team."
|
|
team_license_limit
|
|
"Team is full. The organization has no available licenses."
|
|
|
|
route members/recover(MembersRecoverArg, Void, MembersRecoverError)
|
|
"Recover a deleted member.
|
|
|
|
Permission : Team member management
|
|
|
|
Exactly one of team_member_id, email, or external_id must be provided to identify the user account."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "super-admin-and-deployment"
|
|
|
|
# manage_former_member_files
|
|
|
|
union MembersTransferFormerMembersFilesError extends MembersTransferFilesError
|
|
user_data_is_being_transferred
|
|
"The user's data is being transferred. Please wait some time before retrying."
|
|
user_not_removed
|
|
"No matching removed user found for the argument user."
|
|
user_data_cannot_be_transferred
|
|
"User files aren't transferable anymore."
|
|
user_data_already_transferred
|
|
"User's data has already been transferred to another user."
|
|
|
|
struct MembersDataTransferArg extends MembersDeactivateBaseArg
|
|
transfer_dest_id UserSelectorArg
|
|
"Files from the deleted member account will be transferred to this user."
|
|
transfer_admin_id UserSelectorArg
|
|
"Errors during the transfer process will be sent via
|
|
email to this user."
|
|
|
|
example default
|
|
user = default
|
|
transfer_dest_id = default
|
|
transfer_admin_id = default
|
|
|
|
# Routes - moving removed user's files
|
|
|
|
route members/move_former_member_files(MembersDataTransferArg, async.LaunchEmptyResult, MembersTransferFormerMembersFilesError)
|
|
"Moves removed member's files to a different member. This endpoint initiates an asynchronous job. To obtain the final result
|
|
of the job, the client should periodically poll :route:`members/move_former_member_files/job_status/check`.
|
|
|
|
Permission : Team member management."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|
|
|
|
# This is a duplicate of route members/remove/job_status/get
|
|
|
|
route members/move_former_member_files/job_status/check(async.PollArg, async.PollEmptyResult, async.PollError)
|
|
"Once an async_job_id is returned from :route:`members/move_former_member_files` ,
|
|
use this to poll the status of the asynchronous request.
|
|
|
|
Permission : Team member management."
|
|
|
|
attrs
|
|
auth = "team"
|
|
owner = "team-lifecycle"
|