chore(entirety): documentation update

* chore: update docs

* chore: add docs for modules

* docs: adapted license information

* docs: slightly adapted CONTRIBUTING.md --> conventional commits are mandatory

* Add files via upload

* Add files via upload

* Add files via upload

* Add files via upload

* Update DEVICES.md

* Update ENTITIES.md

* Update NOTIFICATIONS.md

* chore: use relative links for docs of modules

* Chore: Add Subsections

* Chore :  Add Subsections

* Chore: Add Subsections

* chore: move the images

* chore: revise the tutorials

* chore: further move images

* fix: links

* fix: links for going back

* chore: use relative links

* chore: adapt contribution guidelines (wip)

* Fix spelling

* fix spelling, improve clarity of descriptions

* fix spelling, clarify descriptions in devices module

* docs: revise the descriotion for notification module

* chore: remove todo

* chore(entirety): keep media folder in repo

* chore(entirety): give python version information

* chore(entirety): revision based on review feedbacks

* chore(entirety): remove quotation marks in .env.example

* docs: draft for contribution guidelines and individual cla

* docs: intermediate commit before checking GUI tutorial

* chore: revert merge with 106

* Merge branch 'development' into '149'

* docs: re-did images for user guide overview (projects)

* docs: new images for entities module

* docs: adaptions for Devices module tutorial

* [entirety]docs: fix typo

* [entirety]docs: add contact email

* [entirety]docs: typo

* docs[entirety]: update image for subscription module

* docs[entirety]: fix typo

* docs[entirety]: add information about custom notification

* docs[entirety]: fix typo

* docs[entirety]: improve user guide

* docs(entirety): create docs for data model module

* docs[entirety]: upload screen shots

* docs(entirety): revise datamodels documentation

---------

Co-authored-by: JunsongDu <[email protected]>
Co-authored-by: Ganesh-eon <[email protected]>
Co-authored-by: JunsongDu <[email protected]>
Co-authored-by: iripiri <[email protected]>

Author: 4 people

README.md

@@ -1,20 +1,59 @@
 # n5geh.tools.entirety
 
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
 [![semantic-release](https://github.com/N5GEH/n5geh.tools.entirety/actions/workflows/semantic-release.yml/badge.svg)](https://github.com/N5GEH/n5geh.tools.entirety/actions/workflows/semantic-release.yml)
 
+Entirety is a web-based graphical user interface (GUI) meant to provide easy access to some of FIWARE's Generic Enablers (GE) without requiring deeper knowledge on their APIs: Context Brokers like [Orion](https://fiware-orion.readthedocs.io/en/master/) and the [IoT Agent JSON](https://github.com/telefonicaid/iotagent-json/tree/master). 
+Entirety is python-based and relies on the [FIWARE Library for Python (FiLiP)](https://github.com/RWTH-EBC/FiLiP) for the communication with the GE APIs. 
+
+Entirety holds modules (as displayed on the left hand side of the GUI) providing features to perform CRUD (create, read, update, delete) operations to entities in the Context Broker, devices in the IoT Agent, and subscriptions / notifications to QuantumLeap or other applications. Furthermore, Entirety provides a graphical overview of the semantic relationships between entities in the Semantics module as well as a store for standardized data models that can be either created or imported from external sources, like the [Smart Data Models Program](https://smartdatamodels.org//) in the Data Models module.
+
+This project is currently in the process of contribution to FIWARE by the [Institute for Energy Efficient Buildings and Indoor Climate of RWTH Aachen University](https://www.ebc.eonerc.rwth-aachen.de/cms/~dmzz/e-on-erc-ebc/?lidx=1). You can find more GEs in the [FIWARE catalogue](https://github.com/Fiware/catalogue/).
+
+## Table of Contents
+
+- [n5geh.tools.entirety](#n5gehtoolsentirety)
+  - [Table of Contents](#table-of-contents)
+  - [Built With](#built-with)
+  - [Roadmap](#roadmap)
+  - [User Guide](#user-guide)
+  - [Deployment Guide](#deployment-guide)
+  - [Contributing](#contributing)
+  - [Development](#development)
+    - [Prerequisites](#prerequisites)
+      - [Installing dependencies](#installing-dependencies)
+      - [create .env File](#create-env-file)
+    - [Get started](#get-started)
+    - [Required](#required)
+    - [Optional](#optional)
+    - [OIDC](#oidc)
+  - [User and permissions model](#user-and-permissions-model)
+  - [Changelog](#changelog)
+  - [Contact](#contact)
+  - [License](#license)
+  - [Further project information](#further-project-information)
+  - [Acknowledgments](#acknowledgments)
+
 ## Built With
 
 - Django 4.1
 - Bootstrap 5.2
 - htmx 1.8.2
+- Python 3.8/3.9
 
 ## Roadmap
 Have a look at our [roadmap](./docs/ROADMAP.md) to see what features we plan to work on in the short and long run. We kindly invite you to participate in [discussions](https://github.com/N5GEH/n5geh.tools.entirety/discussions) about possible features as well.
-## Deployment
 
-To deploy the application please refer to
-our [deployment guide](https://github.com/N5GEH/n5geh.tutorials.entirety_step_by_step)
+## User Guide
+
+The [user guide](./docs/USERGUIDE.md) describes how the GUI works and guides you through the functionalities of Entirety.
+
+## Deployment Guide
+
+To deploy Entirety via docker, please, refer to our [deployment guide](https://github.com/N5GEH/n5geh.tutorials.entirety_step_by_step), that also gives an overview of the used environment variables.
+If you wish to deploy Entirety for development purposes on your local machine, you can follow the [development](#deployment) and [get started](#get-started) paragraphs.
+
 
 ## Contributing
 
@@ -49,7 +88,7 @@ pre-commit
   cp .env.EXAMPLE .env
 ```
 
-## Usage
+### Get started
 
 Migrate Database
 
@@ -118,7 +157,10 @@ See [changelog](./docs/CHANGELOG.md) for detailed overview of changes.
 
 ## License
 
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
+Entirety is licensed under the GPLv3 license [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE).
+
+Furthermore, the authors want to make the following statement:
+>Please note that software derived as a result of modifying the source code of the software in order to fix a bug or incorporate enhancements IS considered a derivative work of the product. Software that merely uses or aggregates (i.e. links to) an otherwise unmodified version of existing software IS NOT considered a derivative work.
 
 ## Further project information
 

app/Entirety/.env.EXAMPLE

@@ -50,8 +50,8 @@ OIDC_TOKEN_ROLE_PATH="$.entirety.roles"
 
 # FIWARE
 CB_URL=http://localhost:1026
-IOTA_URL="http://localhost:4041"
-QL_URL="http://localhost:8668"
+IOTA_URL=http://localhost:4041
+QL_URL=http://localhost:8668
 
 # CSRF
 CSRF_TRUSTED_ORIGINS=[]

app/Entirety/src/jsonschemaparser

@@ -0,0 +1 @@
+Subproject commit 102c79003703c2b89e1ee08d138b3b16e7748bf0

app/Entirety/subscriptions/views/update.py

@@ -268,7 +268,6 @@ def post(self, request, *args, **kwargs):
                 )
                 messages.error(request, e)
                 return self.form_invalid(form)
-
             with ContextBrokerClient(
                 url=settings.CB_URL,
                 fiware_header=FiwareHeader(

docs/CONTRIBUTING.md

@@ -3,6 +3,29 @@
 Thank you for investing your time in contributing to our project!
 Please read our contribution guideline carefully.
 
+## Ground rules & expectations
+
+Before we get started, here are a few things we expect from you (and that you should expect from others):
+
+- Be kind and thoughtful in your conversations around this project. We all come from different backgrounds and projects, which means we likely have different perspectives on "how open source is done." Try to listen to others rather than convince them that your way is correct.
+- If you open a pull request, you must sign the [Individual Contributor License Agreement](Entirety%20Individual%20Contributor%20License%20Agreement_DRAFT.pdf) by stating in a comment "I have read the CLA Document and I hereby sign the CLA"
+- Please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution.
+- When adding content, please consider if it is widely valuable. Please don't add references or links to things you or your employer have created as others will do so if they appreciate it.
+- When reporting a vulnerability on the software, please, get in contact with the Entirety repository maintainers ([[email protected]](mailto:[email protected])) in order to discuss it in a private way.
+
+## How to contribute 
+
+If you like to contribute, start by searching through the [issues](https://github.com/N5GEH/n5geh.tools.entirety/issues), [discussions](https://github.com/N5GEH/n5geh.tools.entirety/discussions), and [pull requests](https://github.com/N5GEH/n5geh.tools.entirety/pulls) of this project to see whether someone else has raised a similar idea or question.
+
+1. Open a new [issue](https://github.com/N5GEH/n5geh.tools.entirety/issues) for feature requirement or bug resolution.
+2. Assign a user to that issue.
+3. Create a new branch for the corresponding issue (you can use the button/link on issue page to create the new branch).
+4. Make changes to that branch. Follow the [conventional commits convention](#conventional-commits).
+5. Open a [pull request](https://github.com/N5GEH/n5geh.tools.entirety/pulls) **from the new branch to development branch**.
+6. Assign reviewer from the list of reviewers.
+7. Once the pull request is approved by at least one reviewer, merge the branch to development, test if development branch is working as expected, and delete the old branch.
+8. An updated docker image of the development branch will be automatically pushed to the package registry when development branch is updated.
+
 ## Conventional commits
 
 We are using [conventional commits](https://www.conventionalcommits.org/)
@@ -43,15 +66,3 @@ If the commit is not bound to specific modules, for example some changes to the
 * **div:** _d\_\<name\>_
 * **dropdown:** _dd\_\<name\>_
 * **modal**: _m\_\<name\>_
-
-## GitHub Workflow for development
-
-1. Open a new issue for feature requirement or bug resolution.
-2. Assign a user to that issue.
-3. Create new branch for the corresponding issue (you can use the button/link on issue page to create the new branch).
-4. Make changes to that branch.
-5. Open a Pull Request from the new branch to development branch.
-6. Assign reviewer from the list of Reviewers.
-7. Once the Pull Request is approved by at least one reviewer, merge the branch to development, test if development
-branch is working as expected and delete the old branch.
-8. Updated development docker image will be automatically pushed to package registry when development branch will be updated.

docs/Entirety Individual Contributor License Agreement_DRAFT.pdf

@@ -0,0 +1,53 @@
+# *DATA MODELS MODULE*
+
+Data models define the structure and vocabularies of data in FIWARE platforms.
+It helps to improve the reusability and interoperability of data.
+In Entirety, the Data Models module allows users to create, manage, and use data models in other related modules such as `Entities` and `Devices`.
+
+- [Data Models Module](#data-models-module)
+  - [Create Data Models](#create-data-models)
+  - [Manage Data Models](#manage-data-models)
+  - [Use Data Models](#use-data-models)
+
+On the landing page of the *Data Models* module, you can see a list of all data models that belong to the project.
+![Alt text](images/data_model_overview.png)
+
+
+## Create Data Models
+To create a "new" data model, click on the *+* button in the top left.
+By "new" we mean that you can either create a completely new data model from scratch or you can import an existing data model from a URL or copy the source code directly from another source.
+We recommend to always use import function if possible, as it will ensure that the data model is findable and reusable in the future.
+
+![Alt text](images/create_data_model.png)
+
+For example, in the creation dialog, you can specify a URL (``Scheme link``) to access the data model, such as a data model that we host via GitHub pages: https://n5geh.github.io/n5geh.data_models/example_building_automation/deploy/schemas/RadiatorThermostatFiware.json.
+And then, by clicking on the *Load* button, the data model will be loaded into the text fields.
+
+> **Note:** Here you can find more example data models: https://github.com/N5GEH/n5geh.data_models/tree/main/example_building_automation
+
+If your data model is not publicly accessible, you can also copy the source code directly into the text fields.
+The same applies if you want to create a new data model from scratch.
+The *Beautify JSON* button will format the JSON code for better readability.
+
+Finally, you can click on the *Save* button to save the data model.
+
+## Manage Data Models
+
+As can be seen in the landing page, all data models are listed.
+You can update (click on the *Inspect* button) or delete (click on the *Delete* button) a data model.
+
+## Use Data Models
+Data models can be used in the `Entities Module` and `Devices Module` to pre-fill the fields of entities or devices/service groups.
+When creating a new entity or device/service groups, you can select a data model from the dropdown menu.
+
+**In Entities Module:**
+
+![Alt text](images/create_entity_from_data_model.png)
+Here you can pre-fill the *Entity Type* and the attributes of the entity.
+An ID is automatically generated, but can be changed.
+
+**Device/Service Group**:
+
+![Alt text](images/create_service_group_from_data_model.png)
+Here it is recommended to use data models to create service groups for a specific device type.
+With the ``Auto Provision`` option, you can enable the automatic creation of entities (following the data model) when a new device starts sending data to the IoT Agent.

docs/GUI_TUTORIALS/DATAMODELS.md

@@ -0,0 +1,66 @@
+# DEVICES MODULE
+
+The "Devices" module is developed to interact with the FIWARE Generic Enabler known as IoT Agent-JSON, which manages `devices` and `service group` and their interactions within the FIWARE platform. The basic functionalities include creation, update, and removal of devices. Furthermore, the IoT Agent-JSON offers the use service groups to group certain devices and enable bi-directional communication, e.g. for the use of commands.
+
+A detailed description of the terminology can be found in the docoumentation of the [IoT Agent Node Lib](https://iotagent-node-lib.readthedocs.io/en/latest/api.html) and the [IoT Agent JSON](https://fiware-iotagent-json.readthedocs.io/en/latest/usermanual.html).
+
+- [DEVICES MODULE](#devices-module)
+  - [Devices](#devices)
+    - [Create New Device](#create-new-device)
+    - [Create Multiple Devices](#create-multiple-devices)
+    - [Delete Device](#delete-device)
+  - [Service Groups](#service-groups)
+
+On the landing page of the "Devices" module, the [*Devices*](#devices) tab is selected. You can also switch to the [*Service Groups*](#service-groups) tab.
+
+## Devices
+
+Upon load of the devices tab, a list of all devices that belong to the project are displayed. The handling is very similar to the [entities module](ENTITIES.md).
+By clicking on the *+* , you can add new devices. By clicking on the *bin*, you can delete a specific device. And by clicking on the *eye*, you can edit an already existing device.
+Furthermore, you can create Batch Devices by clicking on the batch devices option.
+You can choose which device to perform actions on by selecting the white selection box in the left column.
+
+![Alt text](images/image-11.png)
+
+### Create New Device
+By clicking the blue *+* , you can create a new device by filling in the *Device ID, Device Name* and the *Device Type*.
+
+![Alt text](images/image-12.png)
+
+Either create a device from scratch or pre-load information from a data model.
+
+- The new device will be linked to an Entity by specifying the *Entity Name* and *Entity Type*.
+- Multiple device attributes can be added by filling in the *Attribute Name*, *Attribute Type* and *Object ID* (optional).
+- You can also add multiple device commands for a specific device by adding the *Command Name* and *Command Type*.
+
+![Alt text](images/image-13.png)
+
+### Create Multiple Devices
+If you are familiar with the syntax of the IoT Agent JSON, you can use this option to fill in a valid JSON and create multiple devices. 
+
+![Alt text](images/image-14.png)
+
+### Delete Device
+- To delete a device, you can select the desired device and click on the *bin*, this will open a dialog box which gives you options for deleting the device.
+
+![Alt text](images/image-15.png)
+
+- You can choose to delete the entity related to this device by clicking the select box before deleting.
+- Additionally, you can click the *Advanced* button to delete further entity-related information like subscriptions and relationships which are associated to the connected entity.
+
+![Alt text](images/image-16.png)
+
+## Service Groups
+
+Upon load of the service groups tab, all available service groups are listed. The handling of the service groups tab is the same as for the devices tab.
+
+![Alt text](images/image-17.png)
+
+For each service group, the fields *Resource* and *API Key* are mandatory. The *Resource* "/iot/json" is pre-filled but can be changed. Furthermore, an *Entity Type* can be linked to the service group, only explicit attributes can be accepted or auto provisioning can be enabled.
+
+![Alt text](images/image-18.png)
+
+
+Back: [Entirety GUI](../USERGUIDE.md#modules)
+
+Further: [Subscriptions](Subscriptions.md)

docs/GUI_TUTORIALS/DEVICES.md

@@ -0,0 +1,55 @@
+# Entities Module
+
+The Entities module is developed to interact with the Orion Context Broker (CB).
+It allows users to manage entities within the CB.
+In the FIWARE context, entities hold information in a smart solution, typically corresponding to real-world objects or abstract entities.
+
+![Alt text](images/image-5.png)
+
+Users are able to create, update, retrieve, and delete entities via the "Entities" module. By clicking on the *+* , you can add new entities, by clicking on the *bin* you can delete all selected entities and by clicking on the *eye* you can inspect and edit the selected entity. You can choose which entity to perform actions on by checking one or many of the check boxes on the left hand side of each entity row.
+
+You can use the search bar at the top to filter for entities by either ID or type. Currently, the search is case sensitive!
+
+- [Entities Module](#entities-module)
+  - [Create Entity](#create-entity)
+  - [Create Multiple Entities:](#create-multiple-entities)
+  - [Delete an Entity](#delete-an-entity)
+
+
+## Create Entity
+
+By clicking the *+*, you can either create a single entity or have the possibility to batch create one or more entities. Click on *Create Entity*.
+-	Create Entity: By clicking the *+* , you can create a new entity in two ways:
+    - Raw: By filling in the *Entity ID* and the *Entity Type*. Attributes can be added but are not mandatory. If you add an attribute, *Attribute Name* and *Attribute Type* are mandatory while *Attribute Value* and *Metadata* are optional.
+    - From data model: You can also load *Entity Type* and pre-defined attributes by loading from a data model. Choose an existing data model and click on the *Load* button.
+
+By checking an entity and clicking on the *eye* button, you can inspect an entity.
+The dialog is the same as for creating an entity but the fields ID and type cannot be changed. A click on the red bin below each attribute will delete the attribute. *Note:* You have to click the *Update* button at the bottom in order to make the changes effective.
+
+![Alt text](images/image-6.png)
+
+![Alt text](images/image-7.png)
+
+## Create Multiple Entities: 
+    
+If you are familiar with the syntax of the context brokers, you can use this option to fill in a valid JSON and create multiple entities and their attributes. 
+
+![Alt text](images/image-6-multiple.png)
+
+## Delete an Entity
+
+To delete an entity, select the desired entity and click on the *bin*. This will open a dialog box with different options as described below.
+ 
+![Alt text](images/image-8.png)
+
+- Close: Deletion will be aborted.
+-	Force Delete: Delete an entity without deleting their possible associations.
+-	Advanced selection: This option will open another dialog box which offers three options for deleting the associations of the entity which are: *1. Subscriptions 2. Relationships 3.Devices*
+
+![Alt text](images/image-10.png)
+
+The advanced selection for deleting an entity allows you to delete the subscriptions, relationships and devices that this particular entity is linked with.
+
+Back: [Entirety GUI](../USERGUIDE.md#modules)
+
+Further: [Devices](DEVICES.md)

docs/GUI_TUTORIALS/ENTITIES.md

@@ -0,0 +1 @@
+# *SEMANTICS MODULE*