From 33ab59d74134e61de9ce04053218cfa4e5938e48 Mon Sep 17 00:00:00 2001 From: Johannes Nussbaum <39048939+jnussbaum@users.noreply.github.com> Date: Tue, 20 Dec 2022 10:29:52 +0100 Subject: [PATCH] docs: improve documentation of DSP permission system (DEV-1561) (#270) --- docs/dsp-tools-create.md | 252 +++++++++++++------------- docs/dsp-tools-excel2xml.md | 2 +- docs/dsp-tools-usage.md | 2 +- docs/dsp-tools-xmlupload.md | 181 +++++++----------- testdata/test-project-systematic.json | 2 +- 5 files changed, 197 insertions(+), 242 deletions(-) diff --git a/docs/dsp-tools-create.md b/docs/dsp-tools-create.md index 8fdd91d45..6e53233fc 100644 --- a/docs/dsp-tools-create.md +++ b/docs/dsp-tools-create.md @@ -39,15 +39,15 @@ A complete project definition looks like this: "example", "simple" ], - "lists": [ - ... - ], "groups": [ ... ], "users": [ ... ], + "lists": [ + ... + ], "ontologies": [ ... ] @@ -99,8 +99,7 @@ The `$schema` object refers to the JSON schema for DSP data model definitions an `"project": {"key": "", ...}` -The `project` object contains all resources and properties of the ontology as well as some information about the -project. It requires all the following data fields: +The `project` object contains the basic metadata about the project. The following fields are required: - shortcode - shortname @@ -119,7 +118,7 @@ The following fields are optional (if one or more of these fields are not used, ## "project" object in detail -In the following section all fields of the `project` object are explained in detail. +In the following section, all fields of the `project` object are explained in detail. @@ -129,7 +128,8 @@ In the following section all fields of the `project` object are explained in det `"shortcode": "<4-hex-characters>"` -The shortcode has to be unique and is represented by a 4 digit hexadecimal string. The shortcode has to be provided by the DaSCH. +The shortcode has to be unique and is represented by a 4 digit hexadecimal string. The shortcode has to be provided by +the DaSCH. @@ -139,8 +139,8 @@ The shortcode has to be unique and is represented by a 4 digit hexadecimal strin `"shortname": ""` -The shortname has to be unique. It should be in the form of a [xsd:NCNAME](https://www.w3.org/TR/xmlschema11-2/#NCName). This means a -string without blanks or special characters but `-` and `_` are allowed (although not as first character). +The shortname has to be unique. It should be in the form of a [xsd:NCNAME](https://www.w3.org/TR/xmlschema11-2/#NCName). +This means a string without blanks or special characters but `-` and `_` are allowed (although not as first character). @@ -160,8 +160,8 @@ The longname is a string that provides the full name of the project. `"descriptions": {"": "", ...}` -The description is represented as a collection of strings with language tags (currently "en", "de", "fr", "it", and "rm" are -supported). It is the description of the project. +The description is represented as a collection of strings with language tags (currently, "en", "de", "fr", "it", and +"rm" are supported). @@ -175,6 +175,101 @@ Keywords are represented as an array of strings and are used to describe and/or +### Groups + +(optional) + +`"groups": [, ,...]` + +The `groups` object contains **project specific** group definitions. As opposed to the +[**built-in** groups](./dsp-tools-xmlupload.md#groups), the membership of the users to the project specific groups +can be freely chosen by the `ProjectAdmin`. A project may define several groups such as "student-assistant", +"editors", etc. in order to provide their members specific permissions. +The groups that were created here are then available in the XML file in the +[<permissions> element](dsp-tools-xmlupload.md#defining-permissions-with-the-ltpermissionsgt-element). + +A project specific group definition has the following elements: + +- _name_ (mandatory): name of the group +- _descriptions_ (mandatory): description of the group with language tags in the form `"descriptions": {"": + "", ...}` (currently, "en", "de", "fr", "it", and "rm" are supported) +- _selfjoin_ (optional): true if users are allowed to join the group themselves, false (default) if a `ProjectAdmin` has + to add them +- _status_ (optional): true (default) if the group is active, false if the group is inactive + +Example: + +```json +{ + "groups": [ + { + "name": "biz-editors", + "descriptions": {"en" : "Editors for the BiZ project"}, + "selfjoin": false, + "status": true + } + ] +} +``` + + + +### Users + +(optional) + +`"users": [, ,...]` + +This object contains user definitions. A user has the following elements: + +- _username_: username used for login +- _email_: email that identifies the user, has to be unique within DSP +- _givenName_: first name of the user +- _familyName_: surname of the user +- _password_: password of the user +- _lang_: the default language of the user: "en", "de", "fr", "it", "rm" (optional, default: "en") +- _groups_ (optional): List of groups the user belongs to. The group names must be provided in one of the following forms: + - `other_project_shortname:groupname` + - `:groupname` (for groups defined in the current JSON project file) + - `SystemAdmin` (the most powerful group, built-in into DSP) +- _projects_ (optional): List of projects the user belongs to. The project name has to be followed by a `:` and either + `member` or `admin`. This indicates if the new user has admin rights in the given project or is an ordinary + user. `myproject:admin` would add the user as admin to the project `myproject`. The project defined in the same + JSON project file can be omitted, so only `:admin` or `:member` is enough. Note that in order to give a user `:admin` + rights, he also needs to be a `:member` of the project. + - If _projects_ is omitted, the user won't be part in any project. +- _status_ (optional): true (default) if the user is active, false if the user is deleted/inactive + +Example: + +```json +{ + "users": [ + { + "username": "bizedit", + "email": "bizedit@test.org", + "givenName": "biz-given", + "familyName": "biz-family", + "password": "biz1234", + "lang": "en", + "groups": [ + ":biz-editors", + "SystemAdmin" + ], + "projects": [ + ":admin", + "otherProject:member" + ], + "status": true + } + ] +} +``` + +The `users` element is optional. If not used, it should be omitted. + + + ### Lists (optional) @@ -188,9 +283,9 @@ return objects classified as "Song" and "Opera". But a search for "Song" would o The "lists" section is an array of list definitions. A list definition has one root node whose name is used to identify the list. The children of the root node are the list nodes. If the list is hierarchical, the list nodes can have -children, and these children can again have children etc. +children, and these children can again have children, etc. -When a list is defined for a project, its values can be referenced in resources within a list property, e.g. a property with +When a project defines a list, resources can use the list values by defining a list property, e.g. a property with [object "ListValue"](./dsp-tools-create-ontologies.md#listvalue). A node of a list may have the following elements: @@ -202,16 +297,16 @@ A node of a list may have the following elements: `{"": "", "": "", ... }`. Currently, "de", "en", "fr", "it", and "rm" are supported. - `nodes` (optional): Array of sub-nodes. -Example of a "lists" section: +Example of a "lists" section that contains the two lists "color" and "category": ```json { "lists": [ { - "name": "colors", + "name": "color", "labels": { - "de": "Farben", - "en": "Colors" + "de": "Farbe", + "en": "Color" }, "comments": { "de": "Eine Liste mit einigen Farben", @@ -332,10 +427,10 @@ Example of a "lists" section: ] }, { - "name": "plantes", + "name": "plants", "labels": { "de": "Pflanzen", - "en": "Plantes" + "en": "Plants" } }, { @@ -366,16 +461,16 @@ Example of a "lists" section: Instead of being described in JSON, a list can be imported from one or several Excel files. In this case, the `nodes` element of the root node consists of `{"folder": ""}`. In the above -example, the list "colors" could be imported as follows: +example, the list "color" could be imported as follows: ```json { "lists": [ { - "name": "colors", + "name": "color", "labels": { - "de": "Farben", - "en": "Colors" + "de": "Farbe", + "en": "Color" }, "comments": { "de": "Eine Liste mit einigen Farben", @@ -407,102 +502,9 @@ To do so, it would be necessary to place the following two files into the folder ![Colors_en](./assets/images/img-list-english-colors.png){ width=50% } ![Farben_de](./assets/images/img-list-german-colors.png){ width=50% } -The expected format of the Excel files is documented [here](./dsp-tools-excel2json.md#lists-section). The only difference to -the explanations there is that column A of the Excel worksheet is not interpreted as list name (root node), but as -node name of the first children level below the root node. - - - -### Groups - -(optional) - -`"groups": [, ,...]` - -The `groups` object contains groups definitions. This is used to specify the permissions a user gets. A project may -define several groups such as "project-admins", "editors" etc. in order to provide their members specific permissions. -The groups that were created here are then available in the XML file in the -[<allow> sub-element](dsp-tools-xmlupload.md#the-allow-sub-element). - -A group definition has the following elements: - -- _name_ (mandatory): name of the group -- _descriptions_ (mandatory): description of the group with language tags in the form `"descriptions": {"": - "", ...}` (currently "en", "de", "fr", "it", and "rm" are supported) -- _selfjoin_ (optional): true if users are allowed to join the group themselves, false (default) if an administrator has - to add them -- _status_ (optional): true (default) if the group is active, false if the group is inactive - -Example: - -```json -{ - "groups": [ - { - "name": "biz-editors", - "descriptions": {"en" : "Editors for the BiZ project"}, - "selfjoin": false, - "status": true - } - ] -} -``` - - - -### Users - -(optional) - -`"users": [, ,...]` - -This object contains user definitions. A user has the following elements: - -- _username_: username used for login -- _email_: email that identifies the user, has to be unique within DSP -- _givenName_: firstname of the user -- _familyName_: surname of the user -- _password_: password of the user -- _lang_: the default language of the user: "en", "de", "fr", "it" (optional, default: "en") -- _groups_ (optional): List of groups the user belongs to. The group names must be provided in one of the following forms: - - `other_project_shortname:groupname` - - `:groupname` (for groups defined in the current ontology file) - - `SystemAdmin` (the most powerful group, built-in into DSP) -- _projects_ (optional): List of projects the user belongs to. The project name has to be followed by a `:` and either - `member` or `admin`. This indicates if the new user has admin rights in the given project or is an ordinary - user. `myproject:admin` would add the user as admin to the project `myproject`. The project defined in the same - ontology file can be omitted, so only `:admin` or `:member` is enough. Note that in order to give a user `:admin` rights, - he also needs to be a `:member` of the project. - - If _projects_ is omitted, the user won't be part in any project. -- _status_ (optional): true (default) if the user is active, false if the user is deleted/inactive - -Example: - -```json -{ - "users": [ - { - "username": "bizedit", - "email": "bizedit@test.org", - "givenName": "biz-given", - "familyName": "biz-family", - "password": "biz1234", - "lang": "en", - "groups": [ - ":biz-editors", - "SystemAdmin" - ], - "projects": [ - ":admin", - "otherProject:member" - ], - "status": true - } - ] -} -``` - -The `users` element is optional. If not used, it should be omitted. +The expected format of the Excel files is documented [here](./dsp-tools-excel2json.md#lists-section). The only +difference to the explanations there is that column A of the Excel worksheet is not interpreted as list name (root +node), but as node name of the first children level below the root node. @@ -526,7 +528,13 @@ The `ontologies` section is [documented here](./dsp-tools-create-ontologies.md) ## Fully fleshed out example of a JSON project file -Finally, here is a complete example of an ontology definition: +DaSCH provides you with two example repositories that contain everything which is necessary to create a project and +upload data. Both of them also contain a JSON project definition file. You can find them here: + +- [https://github.com/dasch-swiss/0123-import-scripts](https://github.com/dasch-swiss/0123-import-scripts) +- [https://github.com/dasch-swiss/082E-rosetta-scripts](https://github.com/dasch-swiss/082E-rosetta-scripts) + +In addition, there is another complete example of a JSON project file here: ```json { @@ -636,7 +644,7 @@ Finally, here is a complete example of an ontology definition: "super": [ "hasLinkTo" ], - "object": "teimp:organization", + "object": ":organization", "labels": { "en": "member of", "de": "Mitglied von" @@ -666,7 +674,7 @@ Finally, here is a complete example of an ontology definition: ], "object": "ListValue", "labels": { - "en": "Organizationtype", + "en": "Organization type", "de": "Organisationstyp" }, "comments": { diff --git a/docs/dsp-tools-excel2xml.md b/docs/dsp-tools-excel2xml.md index 7ecafec31..8ae9cd184 100644 --- a/docs/dsp-tools-excel2xml.md +++ b/docs/dsp-tools-excel2xml.md @@ -88,7 +88,7 @@ otherwise, all resources and properties get these permissions. With `excel2xml`, it is not possible to create resources/properties that don't have permissions, because they would be invisible for all users except project admins and system admins. [Read more about permissions -here](./dsp-tools-xmlupload.md#how-to-use-the-permissions-attribute-in-resourcesproperties). +here](./dsp-tools-xmlupload.md#using-permissions-with-the-permissions-attribute). ## 4. Create list mappings diff --git a/docs/dsp-tools-usage.md b/docs/dsp-tools-usage.md index 18a4b6187..872470abc 100644 --- a/docs/dsp-tools-usage.md +++ b/docs/dsp-tools-usage.md @@ -140,7 +140,7 @@ to use this file to replace internal IDs in an existing XML file to reference ex dsp-tools excel2json data_model_files project.json ``` -The expected file and folder structures are described [here](./dsp-tools-excel2json.md#json-project-file-from-excel). +The expected file and folder structures are described [here](./dsp-tools-excel2json.md). diff --git a/docs/dsp-tools-xmlupload.md b/docs/dsp-tools-xmlupload.md index 57eb310b6..ef09cf719 100644 --- a/docs/dsp-tools-xmlupload.md +++ b/docs/dsp-tools-xmlupload.md @@ -46,16 +46,30 @@ The `` element can only contain the following sub-elements: - `` -## Describing permissions with <permissions> elements +## The DSP permissions -The DSP server provides access control for each resource and each field of a resource through permissions. For a -thorough explanation of the permission and access system of DSP, see -[DSP permissions](https://docs.dasch.swiss/latest/DSP-API/02-knora-ontologies/knora-base/#permissions). +The DSP server provides access control for every resource and every property. -It is optional to define permissions in the XML. If not defined, default permissions are applied, so that only project and -system administrators can view and edit resources. All other users have no rights at all, not even view or restricted view permissions. -The following access rights are defined by DSP: +### Groups + +The user doesn't hold the permissions directly, but belongs to an arbitrary number of groups which hold the +permissions. There are **built-in groups** and **project specific groups**: + + - **Built-in groups**: Every user is automatically in at least one of the following built-in groups: + - `UnknownUser`: The user is not known to DSP (not logged in). + - `KnownUser`: The user is logged in, but not a member of the project the data element belongs to. + - `ProjectMember`: The user belongs to the same project as the data element. + - `ProjectAdmin`: The user is project administrator in the project the data element belongs to. + - `Creator`: The user is the owner of the element (created the element). + - `SystemAdmin`: The user is a system administrator. + - **Project specific groups**: + - can be defined in the [JSON project file](./dsp-tools-create.md#groups) + + +### Rights + +A group can have exactly one of these rights: - (no right): If no permission is defined for a certain group of users, these users cannot view any resources/values. - `RV` _restricted view permission_: Same as `V`, but if it is applied to an image, the image is shown with a reduced resolution or with a watermark overlay. @@ -64,33 +78,31 @@ The following access rights are defined by DSP: - `D` _delete permission_: The user is allowed to mark an element as deleted. The original resource or value will be preserved. - `CR` _change right permission_: The user can change the permission of a resource or value. The user is also allowed to permanently delete (erase) a resource. -The user does not hold the permissions directly, but belongs to an arbitrary number of groups which hold the -permissions. By default, the following groups always exist, and each user belongs to at least one of them: +Every right of this row includes all previous rights. -- `UnknownUser`: The user is not known to DSP (not logged in). -- `KnownUser`: The user is known (logged in), but is not a member of the project the data element belongs to. -- `ProjectMember`: The user belongs to the same project as the data element. -- `ProjectAdmin`: The user is project administrator in the project the data element belongs to. -- `Creator`: The user is the owner of the element (created the element). -- `SystemAdmin`: The user is a system administrator. -In addition, more groups with arbitrary names can be created by a project admin. See [here](dsp-tools-create.md#groups) -how to create a group in an ontology JSON file. For referencing a group, the project name has to be prepended to the -group name, separated by a colon, e.g. `dsp-test:MlsEditors`. +### Defining permissions with the <permissions> element -A `` element contains the permissions given to the selected groups and is called a _permission set_. It has -a mandatory attribute `id` and must contain at least one `` element: +The `` element defines a _permission ID_ that can subsequently be used in a +[permissions attribute](#using-permissions-with-the-permissions-attribute) of a `` or `` tag. + +It is optional to define permissions in the XML. If not defined, default permissions are applied, so that only project +and system administrators can view and edit resources. All other users have no rights at all, not even view or +restricted view permissions. + +The `` element defines which rights are given to which groups: ```xml RV V - CR - CR D ``` +In addition to the DSP built-in groups, [project specific groups](./dsp-tools-create.md#groups) are supported as well. +A project specific group name has the form `project-shortname:groupname`. + If you don't want a group to have access at all, leave it out. In the following example, resources or properties with permission `special-permission` can only be viewed by `ProjectAdmin`s: @@ -100,102 +112,31 @@ permission `special-permission` can only be viewed by `ProjectAdmin`s: ``` -Note: The permissions defined in the XML are applied to resources that are created. But only project or system -administrators have the permission to create resources via the XML upload. - -### The <allow> sub-element +### Using permissions with the `permissions` attribute -The `` element is used to define the permission for a specific group. It is of the following form: - -```xml -CR -``` - -The values `CR` etc. are described above. - -The `group` attribute is mandatory. It defines the group which the permission is applied to. In addition to the DSP -system groups, project specific groups are supported as well. A project specific group name has the form -`project-shortname:groupname`. The available system groups are described above. - -There are no sub-elements allowed for the `` element. - - -### Example of a permissions section - -A complete `` section may look as follows: - -```xml - - - - RV - V - CR - CR - - - - V - CR - CR - - - - V - V - CR - CR - - - - RV - CR - CR - - ... - -``` - - -### How to use the `permissions` attribute in resources/properties - -Based on the permissions section of the above example, there are different ways how to grant permissions to a resource -and its properties. It is important to note that a resource doesn't inherit its permissions to its properties. Each -property must have its own permissions. So, in the following example, the bitstreams don't inherit the permissions from their -resource: +Once defined, the permission IDs can be used as `permissions` attribute in the `` and `` tags. It is +important to note that a resource doesn't inherit its permissions to its properties. Each property must have its own +permissions. So, in the following example, the bitstreams don't inherit the permissions from their resource: ``` - - postcards/images/EURUS015a.jpg - + images/EURUS015a.jpg - - postcards/images/EURUS015a.jpg - + images/EURUS015a.jpg - - postcards/images/EURUS015a.jpg - + images/EURUS015a.jpg ``` -To take `KnownUser` as example: +To take as example `KnownUser`, i.e. a logged-in user who is not member of the project: - - With `permissions="prop-default"`, a logged-in user who is not member of the project (`KnownUser`) has `V` rights - on the image: Normal view. - - With `permissions="prop-restricted"`, a logged-in user who is not member of the project (`KnownUser`) has `RV` - rights on the image: Blurred image. - - With a blank `` tag, a logged-in user who is not member of the project (`KnownUser`) has no rights on - the image: No view possible. Only users from `ProjectAdmin` upwards are able to look at the image. + - With `permissions="prop-default"`, he has `V` rights on the image: Normal view. + - With `permissions="prop-restricted"`, he has `RV` rights on the image: Blurred image. + - With a blank `` tag, he has no rights on the image: No view possible. Only users from `ProjectAdmin` + upwards are able to look at the image. ## Describing resources with the <resource> element @@ -207,7 +148,7 @@ A `` element contains all necessary information to create a resource. - `id` (required): a unique, arbitrary string providing a unique ID to the resource in order to be referencable by other resources; the ID is only used during the import process and later replaced by the IRI used internally by DSP - `permissions` (optional, but if omitted, users who are lower than a `ProjectAdmin` have no permissions at all, not - even view rights): a reference to a permission set; the permissions will be applied to the created resource + even view rights): a reference to a permission ID - `iri` (optional): a custom IRI, used when migrating existing resources (DaSCH-internal only) - `ark` (optional): a version 0 ARK, used when migrating existing resources. It is not possible to use `iri` and `ark` in the same resource. When `ark` is used, it overrides `iri` (DaSCH-internal only). @@ -687,10 +628,10 @@ The `` element has the following attributes: For the possible combinations of `encoding` with the `gui_element` [defined in the ontology](dsp-tools-create-ontologies.md#textvalue), see the table: -| `gui_element` (JSON ontology) | `encoding` (XML data) | How DSP-APP renders the whitespaces | -|-------------------------------|-----------------------|------------------------------------------------------------------------------------------------------------------------------| -| `SimpleText` | `utf8` | Pretty-print whitespaces and newlines from the XML are taken into the text field as they are. | -| `Textarea` | `utf8` | Pretty-print whitespaces and newlines from the XML are taken into the text field as they are. | +| `gui_element` (JSON ontology) | `encoding` (XML data) | How DSP-APP renders the whitespaces | +|-------------------------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------| +| `SimpleText` | `utf8` | Pretty-print whitespaces and newlines from the XML are taken into the text field as they are. | +| `Textarea` | `utf8` | Pretty-print whitespaces and newlines from the XML are taken into the text field as they are. | | `Richtext` | `xml` | Pretty-print whitespaces and newlines from the XML are removed. If you want a newline in the text field, use `
` instead. | Example of a public and a hidden text: @@ -904,18 +845,24 @@ file should be kept if data is later added with the `--incremental` option. To do an incremental XML upload, one of the following procedures is recommended. - Incremental XML upload with use of internal IDs: - -1. Initial XML upload with internal IDs. -2. The file `id2iri_mapping_[timestamp].json` is created. -3. Create new XML file(s) with resources referencing other resources by their internal IDs in `` (using the same IDs as in the initial XML upload). -4. Run `dsp-tools id2iri new_data.xml id2iri_mapping_[timestamp].json` to replace the internal IDs in `new_data.xml` with IRIs. Only internal IDs inside the `` tag are replaced. -5. Run `dsp-tools xmlupload --incremental new_data.xml` to upload the data to DSP. - + 1. Initial XML upload with internal IDs. + 2. The file `id2iri_mapping_[timestamp].json` is created. + 3. Create new XML file(s) with resources referencing other resources by their internal IDs in `` (using the same IDs as in the initial XML upload). + 4. Run `dsp-tools id2iri new_data.xml id2iri_mapping_[timestamp].json` to replace the internal IDs in `new_data.xml` with IRIs. Only internal IDs inside the `` tag are replaced. + 5. Run `dsp-tools xmlupload --incremental new_data.xml` to upload the data to DSP. - Incremental XML Upload with the use of IRIs: Use IRIs in the XML to reference existing data on the DSP server. ## Complete example +DaSCH provides you with two example repositories that contain everything which is necessary to create a project and +upload data. Both of them also contain an XML data file. You can find them here: + +- [https://github.com/dasch-swiss/0123-import-scripts](https://github.com/dasch-swiss/0123-import-scripts) +- [https://github.com/dasch-swiss/082E-rosetta-scripts](https://github.com/dasch-swiss/082E-rosetta-scripts) + +In addition, there is another complete example of an XML data file here: + ```xml