diff --git a/concept.md b/concept.md deleted file mode 100644 index 07bd683..0000000 --- a/concept.md +++ /dev/null @@ -1,99 +0,0 @@ -# Background -Due to technical as well as conceptional problems in the past and missing documentation, the konova project follows an underlying concept. This concept has been derived from the results of expert interviews and online surveys regarding the acceptance and usability of KSP as a modern eGovernment web application. - -The results of this study can be requested at ksp-servicestelle@sgdnord.rlp.de - -# Concept - brief overview -The full concept can be requested at ksp-servicestelle@sgdnord.rlp.de - -The following brief overview presents the most important concept ideas, which are used as guideline for the konova project. Due to the task of being the digital representation of the [LKompVzVo](https://mueef.rlp.de/fileadmin/mulewf/Themen/Naturschutz/Eingriff_und_Kompensation/Landeskompensationsverzeichnisverordnung.pdf), there are some constraints which have led to the current form of the concept. - -### Data -In the following chapters we are refering to `data`. This data has been called XY-objects in the past (~"Kompenationsobjekt", "Eingriffsobjekt", ...) which wasn't handy for people being technically uncertain. We simplifiy this by calling it (for this documentation) simply `data`. - -The different data types in konova are -1. `Intervention` - "Eingrff" (~"Eingriffsobjekt") -1. `Compensation` - "Kompensation" (~"Kompensationsobjekt") -1. `EcoAccount` - "Ökokonto" (~"Ökokonto") -1. `Ema` - "EMA" (~"EMA") - -The former `process object` (~"Vorgangsobjekt") does not exist anymore, since it caused irritation among users due to it's unclear relation to intervention. The chapter "Viewing data" clarifies details on the `process state` (~"Vorgangszustand"), which won't exist anymore as well. - -### Creating data -Data must be as easily addable and editable as possible. Therefore it is important to dismiss most of the mandatory form fields of the past. Data adding is a process, which can take up some time, since users need to aggregate their information from different sources. It must be acceptable to start with just a geometry and a title for the data and no further information. The user will come back to continue their work until they are done. - -**Please note:** By `checking` or `recording` (see chapters below) data, automatic tests will check the data on consistency or obvious logic errors. This way we won't have any published data with missing information or other issues. - - -### Sharing data -Sharing data between multiple users must be as easy as possible. Providing access to data using a `share link` is a well established method, oftenly found e.g. in cloud services of all kind. The user, who created the data, can create a `share link` and send it to other people, which shall have access to the data. By clicking the received link, the user needs to log in into the application and has immediately access to the data. The data is now "shared" with the user. - -This eradicates a big problem of the past: Access has been granted by inserting the proper organizations inside of the data, which were linked to users. In case of wrongly selected organizations, there was no way to undo these settings and an admin had to fix this issue for the users. - -### Viewing data -As mentioned, sharing is the new way of providing access to data. In fact, we were talking about **writing access** the whole time. Data can always be seen by every user, but can not be edited directly. A user will have their own index views of shared data. This will be familiar, since KSP did show only data, which hold the user's organization. But in case of wrongly inserted organizations, there was no way to "quickly take a look around for the missing data". It was simply gone for the users. Now, they will always see their (shared) data on the index pages, but can toggle a checkbox for showing unshared data. This way they have reading access to all data in the system and can e.g. remind the user, who created the data in the first place, kindly to share the `share link` with them, so they can have access to the data. - -This eradicates another big problem of the past, extending the one in chapter "Sharing data": Not only did the users had no access to their data - they could not even take a look on the data, to find the problems causing this issue. - -#### Process states -In the past new data had to pass multiple process states (~"Vorgangszustände"). These states were derived from the analogue world and could not be adapted well enough digitally due to users misunderstandings and uncertainty. There **are no process states** in konova. Instead the tasks, defined in the LKompVzVo are realized using the functionalities of `share`, `check` (see below), `recording` (see below) and a flexible user group system. - - -### User groups -User groups define permissions in konova. There are three main groups which a user can be related to. Each group provides the permission for using different functions in konova. A user without any group membership might be able to open konova, but won't be able to do anything. -1. `Default` (~"Datenbereitsteller") - 1. Can create new entries - 1. Can share entries with other users -1. `Registration office` (~"Zulassungsbehörde") - 1. Can perform a `check` on data (more in the related chapter) -1. `Conservation office` (~"Naturschutzbehörde/Eintragungsstelle") - 1. Can perform `recording` on data (~"Verzeichnen") - 1. `Recording` performs the same automatic checks on the data, as `check` and marks the data as `recorded` using a timestamp, if no errors occured - - -### Checking data -Checks are performed by members of the group `Registration office` (let's call them ZB users from now on). Checks are provided to mark data officially as `checked`, so other users can see that some official took a look on the data. This way the LKompVzVo can be fulfilled: ZB users are in charge of the provided data. By `checking` data, they can assure that this data is correct from their point of view. - -Due to problems in the past, the checks are not mandatory. Users of the group `Conservation office` (call them ETS users) can further process the data whether the check has been performed or not. - -`Checks` perform some automatic checks on the data, like all file numbers are provided, no inconsistency detected, and so on. -`Checks` can **not** analyze the content of the data, which means the user still has to take a look on the data. - -**Only interventions** need to be checked. Compensations are checked, if their intervention is checked. - -Past-check editing resets the check mark, so the check needs to be rerun afterwards. - -### Recording data -Recording (~"Verzeichnen") data works just as in KSP: ETS users can record data, which performs the same automatic tests in the background like checks and can be useful to detect flaws inside the data. However, by recording data, it is finally "official". - -Recorded interventions are published if they are recorded and the binding date (~"Datum der Bestandskraft") has been reached. - -Recorded ecoAccounts are published if they are recorded. - -Compensations are published if their intervention is published. - - -### Deleting data -None of the major data types (Intervention, Compensation, EcoAccount, Ema) will be deleted right away, if the user `deletes` them. Instead, they will be marked as deleted, using a timestamp. This way they can be recovered at any time, in case the deletion was a mistake. -If data has not been restored for timespan x, it can be deleted automatically, to keep the database as clean as possible. - - -### Editing data -Each data type consists of different smaller data types. Compensations for example contain geometry, dates, before-states, after-states, documents, actions (~"Maßnahmen") and so on. Instead of providing everything in a single large form, which needs to be loaded on every user edit, the user must be able to add and delete e.g. an action as easily as possible, directly from the detail view of the compensation. Therefore smaller, handy forms for each sub-data type must be provided. - -### User contact -Not being able to contact another user easily was a major problem of KSP. One user needed to clarify some thing about given objects but had no idea how to contact the initial data provider. If data has been shared with a user, it will be possible to see which other users have access as well. By clicking their usernames, a small window will open up, displaying basic contact details about the user: Person name and email. - -### Interfaces -Interfaces are an ongoing topic in KSP: Import from special XML/GML files, providing access via external API packages, and so on. -Konova will provide all import functionalities from KSP, such as the import of GML files and will extend this by the file type [XPlanung](https://xleitstelle.de/xplanung/ueber_xplanung), which becomes mandatory in 2022. - -Furthermore a user must be able to generate an API Token in the own profile settings, which can be used for accessing the konova Json API. Each token must be verified by an admin, before it can be used by a developer. The API will provide basic read/write endpoints for creating and updating data which will be explained in an open documentation. - - -### Interview mode -Despite providing the "classic" forms for creating new data, an interview mode can provide a smart and handy way to add new data to konova. This interview mode will guide the user through the process of data creation by asking questions, one after another, about the intervention/compensation/ecoAccount in a way, the user can easily answer the questions or select the correct answer from a list of given choices. A small text box may add some background information on why this question is important or which effect the answer will have. This way most of the important data can be inserted easily for beginners. - - -### Frontend -The webfrontend must be clean, self explaining and easy to use. Each form field must provide helpful information about the field and what needs to be entered. The frontend must be built using the [bootstrap library](https://getbootstrap.com/). \ No newline at end of file diff --git a/features_en.md b/features_en.md new file mode 100644 index 0000000..b9f7322 --- /dev/null +++ b/features_en.md @@ -0,0 +1,106 @@ + +# Features - brief overview +The full concept can be requested at ksp-servicestelle@sgdnord.rlp.de + +The following brief overview presents the most important features, which are provided by the konova project. Due to the task of being the digital representation of the [LKompVzVo](https://mueef.rlp.de/fileadmin/mulewf/Themen/Naturschutz/Eingriff_und_Kompensation/Landeskompensationsverzeichnisverordnung.pdf), there are some legal constraints which have to be taken into account. + +## Data +In the following chapters we are refering to `data`. This data has been called XY-objects in the past (~"Kompenationsobjekt", "Eingriffsobjekt", ...) which wasn't handy for people being technically uncertain. We simplifiy this by calling it (for this documentation) simply `data`. + +The different data types in konova are +1. `Intervention` - "Eingrff" (~"Eingriffsobjekt") +1. `Compensation` - "Kompensation" (~"Kompensationsobjekt") +1. `EcoAccount` - "Ökokonto" (~"Ökokonto") +1. `Ema` - "EMA" (~"EMA") + +The former `process object` (~"Vorgangsobjekt") does not exist anymore, since it caused irritation among users due to it's unclear relation to intervention. The chapter "Viewing data" clarifies details on the `process state` (~"Vorgangszustand"), which won't exist anymore as well. + +## Creating data +Data must be as easily addable and editable as possible. Therefore it is important to dismiss most of the mandatory form fields of the past. Data adding is a process, which can take up some time, since users need to aggregate their information, worst case from different sources. It must be acceptable to start with just a geometry and a title for the data and no further information. The user will come back to continue their work until they are done. + +On the data's detail view it's getting clear which information is still missing despite the fact they are no mandatory fields on any form. +![Missing data](https://git.naturschutz.rlp.de/attachments/864b1a99-e63b-43c7-bfbd-7bf0c43a21d1) + + +## Sharing data +Sharing data between multiple users must be as easy as possible. Providing access to data is a well established method, oftenly found e.g. in cloud services of all kind. Therefore we adopted these ideas. + +### Sharing data using link +The user who created the data is always the first user having 'shared' access to the data. A `share link` then can be created from the detail view of the data and be send to other people via e-mail which shall have access to the data. By clicking the received link, these users need to login and get immediately access to the data. The data is now 'shared' with this user. +![Share link](https://git.naturschutz.rlp.de/attachments/5a80a8fb-c18c-42e4-87a9-80a9436d1479) + +This eradicates a big problem of the past: Access has been granted by inserting the proper organizations inside of the data, which were linked to users. In case of wrongly selected organizations -which happened a lot-, there was no way to undo this configuration as a user and an admin had to fix this issue by hand. + +### Sharing data using username +Furthermore users can be added directly, if their username is known. This way we can add the same users, we always work with together, directly without having the need to send an e-mail containing a share link. +![Add user directly](https://git.naturschutz.rlp.de/attachments/58193807-6940-41e5-9c5d-cf86134e8a0f) + +## Viewing data +As mentioned, sharing is the new way of providing access to data. In fact, we are talking about **writing access** the whole time. Data can always be seen by every user, but can not be edited directly. Each user will have their own index view of only shared data. This will be familiar for most users, since the successor did show only data, which should have been displayed for the user. +But, as stated priorly, in case of wrongly entered responsible organizations for the data, there was no way to 'quickly take a look around' for the data not showing up in the desired user's index view. It was simply gone for this user. + +Now, they will always see their shared data by default on the index views, but can use the filter section to toggle a checkbox for showing all, even unshared, data. This way they have reading access to all data in the system, if needed. Users then can search for their data and inform the one, who didn't shared it properly with them, to share properly. +![Filter](https://git.naturschutz.rlp.de/attachments/8f1f0b1d-556d-4468-8613-2266ead6cfaf) + + +## Process states +In the past newly entered data had to pass multiple process states (~"Vorgangszustände"). These states were derived from the analogue administration world and could not be adapted digitally well enough due to users misunderstandings and uncertainty. + +**There are no process states in konova.** + +Instead the mandatory tasks, defined in the legal document LKompVzVo, are realized using the functionalities of `share`, `check` (see below), `recording` (see below) and a flexible user group system. + + +## User groups +User groups define permissions in konova. There are three main groups which a user can be related to. Each group provides the permission for using different functions in konova. A user without any group membership might be able to open konova, but won't be able to do anything. +1. `Default` (~"Datenbereitsteller") + 1. Can create new entries + 1. Can share entries with other users +1. `Registration office` (~"Zulassungsbehörde") + 1. Can perform a `check` on data (more in the related chapter) +1. `Conservation office` (~"Naturschutzbehörde/Eintragungsstelle") + 1. Can perform `recording` on data (~"Verzeichnen") + 1. `Recording` performs the same automatic checks on the data, as `check` and marks the data as `recorded` using a timestamp, if no errors occured + + +## Checking data +Checks are performed by members of the group `Registration office` (let's call them ZB users in here - it's shorter). Checks are provided to mark data officially as `checked`, so other users can see that some official took a look on the data. This way the LKompVzVo can be fulfilled: ZB users are generally in charge of the provided data. They need to make sure the data is consistent and correct. By `checking` data, they are supported by some automatism, which checks the data on logical errors and inconsistencies. If the check was successful, the data is marked with a little golden star, so every other user knows that the ZB user did their job on here. + +![Button for run a check on the data](https://git.naturschutz.rlp.de/attachments/78a69b02-9737-4c6f-8efe-7a80cd34c64b) +![Errors on the check form](https://git.naturschutz.rlp.de/attachments/d5fd03f0-35de-4fef-87aa-809a1bad211b) +![Successful check on this data has been run](https://git.naturschutz.rlp.de/attachments/e0df8072-9d1b-4f6e-9001-aa8563fd16fb) +![Check status is shown on the index view](https://git.naturschutz.rlp.de/attachments/12708561-6c49-45cf-8c20-942b5502afd1) + +### Use cases +Due to problems in the past, the checks are **not mandatory**. Users of the group `Conservation office` (call them ETS users) can further process the data whether the check has been performed or not. + +`Checks` perform some automatic checks on the data, like all file numbers are provided, no inconsistency detected, and so on. +`Checks` can **not** analyze the content of the data, which means the user still has to take a look on the data. + +### Checking compensations +**Only interventions** need to be checked. Compensations are checked, if their intervention is checked. + + +### Reset of checked status +Past-check editing resets the check mark, so the check needs to be rerun afterwards. + +## Recording data +Recording (~"Verzeichnen") data works just as in KSP: ETS users can record data, which performs the same automatic tests in the background like checks and can be useful to detect flaws inside the data. However, by recording data, it is finally "official". + +Recorded interventions are published if they are recorded and the binding date (~"Datum der Bestandskraft") has been reached. + +Recorded ecoAccounts are published if they are recorded. + +Compensations are published if their intervention is published. + + +## Deleting data +None of the major data types (Intervention, Compensation, EcoAccount, Ema) will be deleted right away, if the user `deletes` them. Instead, they will be marked as deleted, using a timestamp. This way they can be recovered at any time, in case the deletion was a mistake. +If data has not been restored for timespan x, it can be deleted automatically, to keep the database as clean as possible. + + +## Editing data +Each data type consists of different smaller data types. Compensations for example contain geometry, dates, before-states, after-states, documents, actions (~"Maßnahmen") and so on. Instead of providing everything in a single large form, which needs to be loaded on every user edit, the user must be able to add and delete e.g. an action as easily as possible, directly from the detail view of the compensation. Therefore smaller, handy forms for each sub-data type must be provided. + +## User contact +Not being able to contact another user easily was a major problem of KSP. One user needed to clarify some thing about given objects but had no idea how to contact the initial data provider. If data has been shared with a user, it will be possible to see which other users have access as well. By clicking their usernames, a small window will open up, displaying basic contact details about the user: Person name and email.