Tree entity roles
A tree entity is a space, a folder or a document: the items of the sidebar tree, which can sit inside one another. This resource gives a user or a user group one or more roles on a space, a folder or a document. The roles are listed in role_refs: reader, writer and admin are the built-in roles, and your own roles come from roles. The access also applies to everything inside the space, folder or document. Write one record per space, folder or document and member. When the member is a group, every member of the group gets the roles of the group, and the import creates the access for the group as a whole, not for each user. Users who are not yet in the target company are added to it without an invitation email. A group that already exists in the target keeps its own members (see user_groups). A package with groups or roles of your own can be imported only by a user with the Members management permission, and only if the tariff includes groups. For example, {"external_id": "m-liam", "tree_entity_ref": {"resource": "spaces", "external_id": "s-sales"}, "member_ref": {"resource": "users", "external_id": "u-liam"}, "role_refs": ["writer", "r-editor"]} gives the user u-liam the built-in writer role and the role r-editor in the space s-sales, and {"external_id": "m-analytics", "tree_entity_ref": {"resource": "folders", "external_id": "f-handbook"}, "member_ref": {"resource": "user_groups", "external_id": "g-analytics"}, "role_refs": ["reader"]} gives the group g-analytics the reader role in the folder f-handbook.
A record of this entity needs records of other entities in the package: Documents or Folders or Spaces; User groups or Users.
Files in the package
List every file of this entity in resource_files of the manifest, with "resource": "tree_entity_roles". An entity can have any number of files. See Bundle format.
[
{
"resource": "tree_entity_roles",
"path": "resources/tree_entity_roles.json"
}
]Fields
| Field | Type | Required | Description |
|---|---|---|---|
external_id | string (ExternalId) | Yes | Your own identifier of the record, for example k-mrr, unique within the resource across all of its files and case sensitive. Other records refer to this one by it.Constraints: 1–512 characters. |
member_ref | PolymorphicRef refers to User groups or Users | Yes | Who gets access: an object with resource (users or user_groups) and the external_id of that user or group.Constraints: resource is one of users, user_groups. |
role_refs | BuiltInOrRef<roles>[] refers to Roles | Yes | The roles the member has in that space, folder or document: at least one, each once. The built-in roles reader, writer and admin (Commentator, Writer and Administrator in the app) are levels of access, so give at most one of them. Next to it, give as many of your own roles from roles as the member has in the source system, for example ["writer", "r-developer", "r-reviewer"]. The permissions of all the roles are added up; the member card in the app shows one of them.Constraints: items are unique; at least 1 item; at most one of reader, writer and admin; each item is one of reader, writer, admin (the built-in roles), or the external_id of a roles record. |
tree_entity_ref | PolymorphicRef | Yes | The tree entity (a space, a folder or a document): an object with resource (spaces, folders or documents) and the external_id of that record.Constraints: resource is one of spaces, folders, documents. |
access_mod | enum | No | all to see everything in the space, folder or document, related_only to see only the items related to the member. The default is all. related_only works only with the built-in reader or writer role and no role of your own in the record; a role of your own decides what its holders see through its own permissions; admin always sees everything.Constraints: one of all, related_only. Default: |
References
Show on the entity map
Example
A record of this entity:
{
"external_id": "eam-reports-omar",
"tree_entity_ref": {
"resource": "spaces",
"external_id": "s-reports"
},
"member_ref": {
"resource": "users",
"external_id": "u-omar"
},
"role_refs": [
"ter-analyst"
]
}Rules
- access_mod related_only only with the built-in reader or writer role and no role of your own.
- The combination of tree_entity_ref, member_ref must be unique.
Related entities
Documents, Folders, Roles, Spaces, User groups, Users
Check after the import
After the import, the records of this entity can be checked on Space users › Get list of users and Group Entities › Get list of group entities.
JSON Schema
tree_entity_roles.json
