diff --git a/.vscode/settings.json b/.vscode/settings.json index ab3eb0a..56c2d44 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,3 +1,5 @@ { - "restructuredtext.confPath": "${workspaceFolder}\\source" + "restructuredtext.confPath": "${workspaceFolder}\\source", + "iis.configDir": "", + "esbonio.sphinx.confDir": "${workspaceFolder}\\source" } \ No newline at end of file diff --git a/source/f_geoblocks.rst b/source/a_geoblocks.rst similarity index 99% rename from source/f_geoblocks.rst rename to source/a_geoblocks.rst index 64518aa..56bc77b 100644 --- a/source/f_geoblocks.rst +++ b/source/a_geoblocks.rst @@ -307,7 +307,7 @@ Geometry example: classify build year of buildings. Geometry output --------------- -Geometry outputs are stored in :doc:`labels`. +Geometry outputs are stored in `labels `_. Labels are always linked to your Vectors stored in the Vector Server, for instance flood risk for parcels or buildings. Labels are grouped in Labeltypes. The graph can be found via the labeltypes endpoint: diff --git a/source/a_homepage.rst b/source/a_homepage.rst deleted file mode 100644 index 5e42a95..0000000 --- a/source/a_homepage.rst +++ /dev/null @@ -1,28 +0,0 @@ -========== -Homepage -========== - -The Homepage ensures easy access to functionalities for all users. -You can access the Lizard Homepage via the following url “www.{your_organisation}.lizard.net”. -This base url will also be referred to as 'Portal'. -Lizard works best in Chrome. No additional software is needed. - -for example: -https://demo.lizard.net/ - - -.. image:: /images/a_homepage.jpg - -From the Homepage, you can link to the Lizard functionality you are interested in. - - -* **Catalogue**: Search for your data. -* **Viewer**: Explore your data. -* **Management**: Manage your data, users, alarms and GeoBlocks. -* **API**: Query your data. - - -From the homepage you have easy access to the support team and the documentation. - - - diff --git a/source/a_lizard.rst b/source/a_lizard.rst deleted file mode 100644 index a7dcf52..0000000 --- a/source/a_lizard.rst +++ /dev/null @@ -1,17 +0,0 @@ -============ -Introduction -============ - -Lizard is a data and analytics platform, optimised for the physical environment. -We enable you to unlock the potential of your data and allow you to integrate and combine data from different sources and domains. -Explore your data with plug-and-play applications. -Or connect your favourite data science tools with our API. - -The documentation has detailed descriptions of individual components of every aspect of Lizard. -Feel free to move through every section in sequence by using the next functionality at the bottom of every page, or dive straight to the item of interest with the use of the left pane. - -To get familiar with the Catalogue or Viewer, use one of the following tutorials: -1. `Catalogue Tutorial ` -2. `Viewer Tutorial ` - -Tutorials in regards to the Lizard API usage can be found in the `API Tutorials section ` \ No newline at end of file diff --git a/source/d_apitutorials.rst b/source/a_tutorials.rst similarity index 93% rename from source/d_apitutorials.rst rename to source/a_tutorials.rst index cc3d3ed..7e8baf0 100644 --- a/source/d_apitutorials.rst +++ b/source/a_tutorials.rst @@ -1,11 +1,11 @@ -============================== +============= API tutorials -============================== +============= We created interactive manuals for data scientists to use the Lizard API. At the moment we have the following: -0. Virtual Environment +1. Virtual Environment ---------------------- | `Virtual Environment Requirements `_ diff --git a/source/a_user_interfaces.rst b/source/a_user_interfaces.rst new file mode 100644 index 0000000..c69c9c8 --- /dev/null +++ b/source/a_user_interfaces.rst @@ -0,0 +1,51 @@ +=============== +User interfaces +=============== + +Introduction +============ + +Lizard is a data and analytics platform, optimised for the physical environment. +We enable you to unlock the potential of your data and allow you to integrate and combine data from different sources and domains. +Explore your data with plug-and-play applications. +Or connect your favourite data science tools with our API. + +The documentation has detailed descriptions of individual components of every aspect of Lizard. +Feel free to move through every section in sequence by using the next functionality at the bottom of every page, or dive straight to the item of interest with the use of the left pane. + +Tutorials in regards to the Lizard API usage can be found in the `API Tutorials section ` + +Homepage +=============== + +The homepage ensures easy access to functionalities for all users. +You can access the Lizard homepage via the following url “www.{your_organisation}.lizard.net”. +This base url will also be referred to as 'Portal'. +Lizard works best in Chrome. No additional software is needed. + +for example: +https://demo.lizard.net/ + + +.. image:: /images/a_homepage.jpg + +From the Homepage, you can link to the Lizard functionality you are interested in. + +* `**Catalogue** `_: Search for your data. +* `**Viewer** `_: Explore your data. +* `**Management** `_: Manage your data, users, alarms and GeoBlocks. +* `**API** `_: Query your data. + +From the homepage you have easy access to the support team and the documentation. + + +Catalogue +============= + + +Viewer +========== + + +Management +========== \ No newline at end of file diff --git a/source/e_dashboard.rst b/source/b_apps.rst similarity index 94% rename from source/e_dashboard.rst rename to source/b_apps.rst index d2b3acb..7edde98 100644 --- a/source/e_dashboard.rst +++ b/source/b_apps.rst @@ -1,6 +1,11 @@ -========= -Dashboard -========= +==== +Apps +==== + +This page contains an explanation of availibity of apps in Lizard! + +Dashboards +========== Manage, control and keep track with Lizard Dashboards. Lizard Dashboards can offer key insights that help decision makers make data driven decisions. diff --git a/source/e_catalog.rst b/source/b_catalogue.rst similarity index 93% rename from source/e_catalog.rst rename to source/b_catalogue.rst index e84454b..a17c948 100644 --- a/source/e_catalog.rst +++ b/source/b_catalogue.rst @@ -76,7 +76,7 @@ The following information is visible in this overview. * **Access modifier** Divided into Public, Common and Private. .. note:: - Information about the different Access modifiers can be found under :ref:`OrganisationsAnchor`. + Information about the different access modifiers can be found under `organisation modifiers `_. .. note:: Not included are rasters from 3Di scenarios @@ -138,7 +138,7 @@ The following information is visible in this overview. * **Access modifier** Divided into Public, Common and Private. .. note:: - Information about the different Access modifiers can be found under :ref:`OrganisationsAnchor`. + Information about the different access modifiers can be found under `organisation modifiers `_. Details -------- @@ -158,7 +158,7 @@ Action menu You can download the wms directly, open it in the Viewer or in the API or analyse the wms layer in another application linking to Lizard. You can use this link to visualise the raster in external applications such as QGIS or ESRI applications. -For more infomation, please consult the :doc:`WMS Services`. +For more infomation, please consult the `WMS Services `_. Time series and monitoring networks ==================================== @@ -175,7 +175,7 @@ The following information is visible in this overview. * **Access modifier** Divided into Public, Common and Private. .. note:: - Information about the different Access modifiers can be found under :ref:`OrganisationsAnchor`. + Information about the different access modifiers can be found under `organisation modifiers `_. In monitoring networks, you can group timeseries. This can be done for example by grouping them by observation type or by source. @@ -231,7 +231,7 @@ The following information is visible in this overview. * **Access modifier** Divided into Public, Common and Private. .. note:: - Information about the different Access modifiers can be found under :ref:`OrganisationsAnchor`. + Information about the different access modifiers can be found under `organisation modifiers `_. Details diff --git a/source/d_qgisplugin.rst b/source/b_lizardplugin.rst similarity index 100% rename from source/d_qgisplugin.rst rename to source/b_lizardplugin.rst diff --git a/source/b_management.rst b/source/b_management.rst new file mode 100644 index 0000000..0e47556 --- /dev/null +++ b/source/b_management.rst @@ -0,0 +1,555 @@ +========== +Management +========== + +In the management interface there is a variety of options. + +`Usermanagement `_ will be discussed later. + +Rasters +============= + +The data management interface for rasters can be used to upload, edit or remove rasters. +Raster Sources are the data containers, Raster Layers are the configuration of how the data is visualised. + +.. image:: /images/c_manage_rasters_01.png +.. image:: /images/c_manage_rasters_02.png +.. image:: /images/c_manage_rasters_03.png + +Creating and editing Raster Sources and Layers +---------------------------------------------- + +The first step in uploading your raster datasets is to create a Raster Source. + +The Data Management interface is available at: “www.{your_organisation}.lizard.net/management/”. + +After landing on this page, click on ‘Data’ -> ‘Rasters’ -> 'Raster Sources'. +Click on “New Item” |NewItem| to open the form or choose an existing raster to edit. + +.. |NewItem| image:: /images/c_manage_newitem.png + +After filling in the form you can choose to directly upload your data by selecting your GeoTIFF's in the 'DATA' section. +In case of a temporal raster source you need to specify which file belongs to which timestep. +This is recognised automatically if the filename is composed according to the specified format. +When you save a new Source you will have the option to go straight to the Raster Layer form to publish your data. + +.. image:: /images/c_datatypes_01.png + +Interested in the possibilities for your organisation? Please contact us via info@lizard.net. + +GeoBlocks management +==================== + +The GeoBlocks management page provides you a powerful tool to build your GeoBlocks Rasters. +It helps you configure complex GeoBlocks models and enables you to validate your work along the way. + +The Visual editor shows your model as a flow diagram, consisting of block objects representing the input Raster Sources and GeoBlocks operations. +The right sidebar shows the available blocks. Click on the blocks for a description and the expected inputs. Drag a block into the canvas to include it in your model. +Connect blocks to use one as input for the other. + +When the model is valid it can also be shown in the Text editor. This shows the JSON graph as it would be sent to the API when you save the item. +Here you can also make edits and validate the result. + +Example 1 shows a simple model which subtracts one Raster Source from another (difference in surface elevation between two versions of a dataset). + +.. image:: /images/c_manage_geoblocks_01.png + +Example 2 shows a more complex model with multiple Raster Sources and a series of operations. + +.. image:: /images/c_manage_geoblocks_02.png + +For more information about the possibilities of GeoBlocks see: :ref:`GeoBlocksAnchor` + + +WMS Layers +=========== + +WMS stands for Web Mapping Service. +It is a standard method of sharing georeferenced maps. +The WMS layers management allows the user to configure layers in Lizard even if they are hosted on another platform. +In the management screen you can add new WMS layers or edit existing layers. + +.. image:: /images/c_manage_wms_01.png + +New WMS Layer +------------- + +.. image:: /images/c_manage_newitem.png + +After clicking the 'NEW ITEM' icon, you can configure a new WMS layer. + +.. image:: /images/c_manage_wms_02.png + +The configuration has some mandatory items while others are optional, an extensive list with descriptions follows: + +1. GENERAL +------------ + +* Name (required): Choose a name that is findable and not too difficult +* Description (optional): Give a description of the information that is displayed by the WMS layer. +* Tags / Datasets (optional): You can connect the layer to an existing dataset. + +2. DATA +------------ + +* WMS URL (required): Specify which base URL is used to retrieve the image data. It usually ends on '/wms' +* Slug (required): can be seen as layer name used in the external platform +* Download URL (optional): Specify which URL is used to download the data. This will enable the download button in the Lizard Catalogue. +* Legend URL (optional): Specify which URL is used to show the legend of this layer. +* Get Feature URL (optional) : Optional URL to retrieve feature info data. +* Tiled (enabled by default) : Specifies whether the layer is tiled (for better performance) +* Min and max zoom (required): Closest and furthest point of view in this WMS layer. 0 is visible at world scale, 31 is zoomed in at a house. You can check the zoom level in the url in the Viewer (after the coordinates). +* Spatial bounds (optional): Specify the extent of this layer on the map. This information can also be automatically obtained by clicking "Get from source". +* Options (JSON): Extra options of this layer, specfied in JSON. + +3. RIGHTS +------------ + +* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. +* Shared with (optional): Specify if this object should be accessible by other organisations, and if so, which ones. +* Organisation (required, pre-filled): The organisation this object belongs to. +* Supplier (optional): The supplier of this object. If you are not an administrator, this field is always pre-filled with your username. + +If you are satisfied, click "SAVE" + + +Edit WMS Layer +--------------- + +By clicking on the name of a WMS layer, the configuration of the corresponding layer is opened. +In the configuration page you can edit any of the settings previously given to the WMS layer. +To quickly find a WMS layer: use the search bar. +If the layer you are looking for seems unavailable you might have to switch organisations, feel free to contact the servicedesk for any problems (servicedesk@nelen-schuurmans.nl). + +.. image:: /images/c_manage_wms_03.png + +.. tip:: + Advanced: Is your WMS layer not visible in the Viewer? Check via the network tab (press F12) how Lizard requests the WMS and if that WMS url makes sense. + + +WMS Services +============= + +Lizard provides a Web Map Service (WMS) that you can use to visualise rasters and 3Di scenarios stored in Lizard Raster Server as tiled images. +The Lizard WMS Service follows the `OGC WMS guidelines `_. + +Rasters +--------- + +To visualise and request the GetCapabilities of a specific raster you can use the following URL: + +``https://{yourportal}.lizard.net/wms/raster_{UUID of raster}/?request=GetCapabilities`` + +for example: +https://demo.lizard.net/wms/raster_eae92c48-cd68-4820-9d82-f86f763b4186/?request=GetCapabilities + +You can easily find the UUID of the raster in the `Lizard Catalogue `_ or `API `_. +The Lizard Catalogue also provides the Lizard WMS GetCapabilities link for each raster. +With the GetCapabilities query parameter you retrieve the metadata of the service, including supported operations, parameters and a list of available layers. + +3Di Scenarios +-------------- + +To visualise and request the GetCapabilities of a 3Di scenario (list of rasters) you can use the following URL: + +``https://{yourportal}.lizard.net/wms/scenario_{UUID of scenario}/?request=getcapabilities`` + +For example: +https://demo.lizard.net/wms/scenario_c30ef7f2-c871-4d70-a087-8f078f9ebafd/?request=GetCapabilities + +You can look up the UUID of the scenario using the `Scenarios endpoint in the Lizard API `_. +All available filters are listed on the endpoints’ page. E.g. you can look up a scenario and it’s uuid by filtering on your own username. +With the GetCapabilities query parameter you retrieve the metadata of the service, including supported operations, parameters and a list of available layers. + +Layer collections +------------------- + +To visualise and request the GetCapabilities of layer collections (list of rasters, previously called 'datasets') you can use the following URL: + +``https://{yourportal}.lizard.net/wms/{slug of layer collection}?request=GetCapabilities`` + +For example: +https://demo.lizard.net/wms/basiskaarten/?request=GetCapabilities + +You can search for layer collections in the Lizard Catalogue by using the Layer collection filter in the left panel. +You will find the Lizard WMS GetCapabilities URL of the layer collection in the metadata panel of a specific layer. + + +.. _WMSauthAnchor: + +Authorisation +-------------- + +The Lizard WMS Service follows the authorisation system mentioned under `organisation modifiers `_. +If layers are private you need privileges in the organisation that owns the data. + +Use a Personal API Key to authenticate with the Lizard WMS Service, as described in `API authentication <_APIAuthenticationAnchor>`_. + +In QGIS the authentication is filled in as follows: + +- username = __key__ +- password = Personal API Key + + +How to load WMS in GIS +======================= + +You can connect directly to Lizard in a GIS application like QGIS. + + +* 1 + +Open QGIS and load a new WMS connection. + +.. image:: /images/e_qgis_wms1.png + + +* 2 + +Give the connection a name and copy the wms link from 'https' to 'GetCapabilities', e.g. "https://maps1.klimaatatlas.net/geoserver/twn_klimaatatlas/wms/?request=GetCapabilities". + +.. image:: /images/e_qgis_wms2.png + + +* 3 + +If the wms layer is not public, you have to enter your :ref:`Credentials`. in the Authentication - Basic tab. + + +.. image:: /images/e_qgis_wmslogin.jpg + + +* 4 + +Click OK and double click on the connection. If multiple layers appear, double click on the one you are interested in. + +.. image:: /images/e_qgis_wms3.png + + +.. image:: /images/e_qgis_wms4.png + +The styling will automatically be taken from Lizard. +If the layer is temporal, you can also navigate through time. + +Layer collections +==================== + +.. warning:: + This section will be extended in the near future. + + + +Time series +============== + + +The data management interface for timeseries can be used to upload, edit or remove timeseries, monitoring networks and locations. + +.. image:: /images/c_manage_timeseries_menu.png + + + +Locations +---------- + +.. image:: /images/c_manage_locations_01.png + + +Search or sort your locations here. +Check out possible actions by clicking the three dots icon. +Create a new object with the New Item button on the top right corner. + + +.. image:: /images/c_manage_newitem.png + +.. image:: /images/c_manage_locations_02.png + +1. **GENERAL** + + +* Location name (required): Choose a name that is findable and not too difficult +* Code (required): Choose a code that represents the object within your organisation. + + +2. **DATA** + + +.. warning:: + Locations must be connected to an existing asset to be visualised in the Viewer. The asset will have a symbol and zoom level depending on the type. Also, the metadata differs per type. For now, only measuringstations can be added via the API. If you have any questions about this, please contact the service desk. + +* Asset type (optional): Specify a type of asset. +* Asset location: after specifying the asset type, you can search by code or name. +* Extra metadata (JSON) (optional): Free JSON field to add information to this object. + +3. **RIGHTS** + +* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. + + +If you are satisfied, click "SAVE" + +Timeseries +------------ + +.. image:: /images/c_manage_timeseries_01.png + +Search or sort your time series here. +Check out possible actions by clicking the three dots icon next to a time series. You can add timeseries to a monitoring network (MN), edit, or delete hem. +Create a new object with the New Item button on the top right corner. + +.. image:: /images/c_manage_newitem.png + +.. image:: /images/c_manage_timeseries_02.png + +1. **GENERAL** + +* Name (required): Choose a name that is findable and not too difficult +* Code (required): Choose a code that represents the object within your organisation. + + +2. **DATA** + +* Observation type (required): Choose the way the data is measured, and the units. New observation types can be added via the `observation types api `_ or requested via the servicedesk. +* Location (required): Choose to which location you want to add this timeseries. New locations can be added via the api or via data management --> timeseries --> locations. +* Value type (required): Specify what kind of data you will be supplying. See `Level of measurement `_. +* Datasource (optional): Specify a data source if it is available. Otherwise, you can leave it empty or create a new one via the API. +* Interval (optional): Specify a time range between each time series step. + +.. note:: + if you leave the interval at 0, it will mean it is irregular ('nonequidistant') data. This is also necessary if you have timesteps smaller than seconds. + +* CSV Files (optional): You can add new data via a csv file or via the API. If you want to supply a csv file, see the instructions below: + +.. note:: + The first line of the file should describe the column names, for example: + + | time, value + | 2020-03-20T01:00:00Z, 3.14 + | 2020-03-20T01:05:00Z, 2.72 + + The next lines are the timestemp and value for that timestep. Make sure you do not list the same timestep twice. + All uploads in Lizard are expected to be in UTC time. + + | time: ISO 8601 date and time representation. This is a required field. + | value: A number, string, or boolean, depending on the value_type of the corresponding time series. + + +* Extra metadata (JSON) (optional): Free JSON field to add information to this object. + + +3. **RIGHTS** + +* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. +* Username of supplier (optional): The supplier of this object. If you are not an administrator, this field is always pre-filled with your username. +* Supplier code (optional): The FTP or Supplier code is used as reference to your own system. + +.. note:: + Timeseries are not linked to an organisation directly. They are linked to organisations via the locations. + +If you are satisfied, click "SAVE" + + + +Monitoring networks +--------------------- + +Monitoring networks are used to group and give insights on time series. +Check out possible actions by clicking the three dots icon next to existing networks. + +Create a new object with the New Item button on the top right corner. + +.. image:: /images/c_manage_newitem.png + +.. image:: /images/c_manage_monitoringnetworks_01.png + +1. **GENERAL** + +* Name (required): Choose a name that is findable and not too difficult +* Description (optional) + + +2. **DATA** + +.. warning:: + The button "MANAGE" will only work if there are already timseries connected to the monitoring network. If there are, you can remove the the connection here. New connections can be added via the timeseries management app. + +3. **RIGHTS** + +* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. +* Organisation (required, pre-filled): The organisation this object belongs to. + +If you are satisfied, click "SAVE" + + + +Scenarios +============== + +The data management interface for scenarios can be used to manage scenarios. + + +.. image:: /images/c_manage_scenarios_01.png + + +Search for a scenario +------------------------ + +You can search for a scenario by either typing (part of) the scenario name, the UUID, username of the supplier or model name. + +.. image:: /images/c_manage_scenarios_search.png + +You can also specify that you only want to show your own scenarios by ticking the box in the top right corner. + + +Used storage and deletion of scenarios +----------------------------------------- + +.. image:: /images/c_manage_scenarios_storage.png + +In the left side, you can see the used storage for your organisation. This may have influence on your subscription. + +.. image:: /images/c_manage_scenarios_delete1.png + +If you want to remove a complete scenario, you simply check the box of the relevant scenario(s) and choose 'delete'. +If you choose 'delete raw', it will only remove the raw data and not the timeseries and rasters. You can also remove a specific raster of a scenario by double-clicking on a scenario and clicking on the 'trash' icon next to the layer. + +.. image:: /images/c_manage_scenarios_delete2.png + +.. warning:: + If you delete a scenario, it is really gone! We might be able to retrieve the rasters if you contact support within 14 days. + +Add a scenario +-------------------- + +Scenarios can be automatically exported to Lizard, for example via 3Di. +You can also add a new scenario with the New Item button on the top right corner. + +.. image:: /images/c_manage_newitem.png + +Edit a scenario +---------------- + +Right now you can only edit the accessability of a scenario. +Scenarios are private by default (only visible for logged in users of the same organisation). +You can choose to make them visible for all logged in users or even public so no login is necessary. + +.. image:: /images/c_manage_scenarios_public.png + + +.. tip:: + Make scenarios public if you want to use them in other GIS applications via a `wms link `_. + + +You can add a scenario to an existing project via the threedot icon. + +.. image:: /images/c_manage_scenarios_project.png + +Group scenarios in a project +----------------------------- + +Projects are used to group and give insights on scenarios. + +.. image:: /images/c_manage_projects_01.png + +Create a new project with the New Item button on the top right corner. + +.. image:: /images/c_manage_newitem.png + + +Labels +============ + +.. warning:: + This section is to be extended. + +.. image:: /images/c_manage_labeltypes.png + + + +Alarms +====== + +Lizard provides an alarm feature that sends notifications via sms or email when newly processed values of timeseries or temporal rasters exceed a threshold. +It is used to notify people of events that may require action, for instance an upcoming rain event or flood. + +The alarm management screens are found at https://demo.lizard.net/management/#/alarms. + +.. image:: /images/f_alarms_01.jpg + +The configuration has a variety of options to generate relevant notifications with messages that include the specifics of the event. + +Notifications +============= + +Behind the Notifications tile you find the overviews of existing raster and timeseries alarms for your organisation and their status (active/inactive). +The 'NEW ITEM' button leads you to the form to register a new alarm. +We go through some of the options that the system provides, to explain them in detail. + +Selecting a raster +------------------ + +Raster alarms are set on temporal rasters. These can be part of a scenario, a single source raster or a Geoblock. +An alarm is set for one point location intersecting this temporal raster. + +You can type in the field to search in the names of available rasters. Next, select the type of intersection (Point, Line or Polygon). +Draw the geometry on the map or insert a geometry in the JSON field below the map. + +For Line and Polygon intersections a spatial aggregation is needed to derive a timeseries that can be compared to the alarm thresholds. +The options are: + +* Sum +* Mean +* Min +* Max +* Median +* Count + +Selecting a timeseries +---------------------- + +Timeseries often do not have a clear name or code by themselves. +That is why we start with looking up the asset it relates to. +Once the asset is selected it should be easy to select the timeseries from the list of related objects. + +Relative start and end +---------------------- + +The user doesn't always want to receive alarms for the whole period of newly processed data. +For instance, for operational flood models which might have records of prior theshold exceedances, you may only be interested in receiving alarms for forecasted threaths. + +To only analyse the relevant part of your data you can set relative start and end. +They are set relative to The figure below gives a schematic overview of how this method works. + +.. image:: /images/f_alarms_02.jpg + +If these fields are left empty the trigger check is done on the complete data frame of newly processed data. + +Snoozing option +--------------- + +It can be considered undesirable for alarms to be triggered during brief spikes. +The snoozing option allows the user to determine the timeperiod a threshold should be exceeded before the alarm is triggered and a notification is sent. +This option is available for both the raising of the alarm and its withdrawal. Default is 1 (trigger at first occurrence). + +Contacts and Groups +=================== + +The recipients of alarm notifications are configured in the Contacts screen, with their phone number and/or email address. +Each contact can be part of multiple Groups, which in turn can be used in multiple alarms. +So no need to do a whole lot of data duplications of contact info. + +Templates +========= + +The notification messages are configured with Templates. +There is a difference in setting up Email and SMS Templates: + +* Email: Supports both plain text and HTML and are not limited in length +* SMS: Plain text with maximum length of 160 characters (after substitution of variables) + +You can use a number of variables to enrich the content of the notifications and make them applicable to different alarms. +The variables contain options for including the name of the receiver and details about the alarm at hand. + +The option "No further impact" determines that a message is used specifically to notify when an alarm is fully withdrawn. +This type of message can be set in addition to a standard message to let receivers know that the situation has settled down. +This often requires a different text and therefore a different Template. diff --git a/source/b_usermanagement.rst b/source/b_usermanagement.rst deleted file mode 100644 index 737389c..0000000 --- a/source/b_usermanagement.rst +++ /dev/null @@ -1,140 +0,0 @@ -.. _AuthenticationAnchor: - -========== -Signing in -========== - -Users that already have a Lizard account can click the "Log in" -button on the top right of the screen. - -First-time users require an invitation to create a Lizard account. Users with -a "manager" role are able to send invitations to new users. -If you do not know whom to contact, please contact our support office -(servicedesk@nelen-schuurmans.nl). - -After clicking "Log in" or after following the invitation link, you will arrive -at the login screen. - -.. note:: - Please ensure that "https://auth.lizard.net/" domain is indeed displayed - in your browser's address bar and that your browser displays the lock - symbol indicating that the connection is secure. - -On the login page you have four different options to sign in: - -1. through a company account, -2. through a social account, -3. with username and password, -4. by creating a new account (Sign up). - -First-time users may choose any of these options. If your company is listed as -one of the possible companies to sign in with, that is the preferred choice. - -Existing users should use the same method as they used when signing in for -the first time. If your Lizard username/password existed before Januari 2021, -use method 3. - -.. tip:: - Do you want to add your company to the list to centralise the user accounts - of your organisation? Please contact our support office - (servicedesk@nelen-schuurmans.nl) for the options. - - -.. _OrganisationsAnchor: - -============= -Organisations -============= - -All data in Lizard is linked to an organisation. -Organisations are the backbone of our authorisation model. -When an organisation uploads data, they are able to determine the level of authorisation required for access. -There are three types of authorisation options that can be applied to your data: - -* **Public**: everyone is able to access your data -* **Common**: everyone with login credentials to Lizard is able to access your data -* **Private**: everyone with login credentials to Lizard AND user rights to your organisation is able to access your data - - - -Whitelisting -============ - -The users of a certain portal may not be interested in a lot of the public/common datasets that are made available by others. -Every Lizard portal has its own whitelist. -Whitelisting allows the organisations to determine which data should be visible. -This can remove some of the clutter. -The whitelist affects both the Lizard Viewer aswell as the Catalogue. - -The effect is that for the same user the available data can differ between [your_organisation].lizard.net and demo.lizard.net (for which all organisations are whitelisted). -The whitelisting mechanism is overruled if a user has specific authorisation for an organisation. - -.. tip:: - Do you want to see or change the whitelist settings of a portal? Please contact our support office - (servicedesk@nelen-schuurmans.nl). - -===== -Roles -===== - -We have 4 roles and 3 different types of privileges. - -* A **user**, who can only *read* data -* A **supplier**, who can *read* data and change (*'write'*) his or her own data -* An **administator**, who can *read* data and change (*'write'*) all organisation's data. -* A **manager**, who can *manage* other roles in the organisation. A manager can not read or write data by default. This role should be appointed separately. - - -=============== -User management -=============== - -Users can be managed in the User Management interface. -This interface can be reached via the {your_organisation}.lizard.net/management/users/ (or `demo.lizard.net/management/users `_). - -.. note:: - You require a “manager” role to access the User Management interface. - Haven’t got a “manager” role but you would like to add the User Management interface? - Please contact the application manager within your organisation or our support office (servicedesk@nelen-schuurmans.nl) - -.. image:: /images/b_usermanagement_03.png - -In the example above, you see the current rights for 7 users under the organisation Nelen & Schuurmans. - -Manage existing users -===================== - -The User Management interface gives you an overview of all users that have roles for your organisation. -If you are Manager for multiple organisations you can switch organisation using the button in the dark green bar. You can change the role of a user by clicking the “three dots" next to the user and choose the roles you want to assign. Then click “Save” to make the changes. - -Adding a new user -================= - -You can add a new user by clicking the “NEW ITEM” icon in the upper right corner. - -.. image:: /images/c_manage_newitem.png - -This will lead you to the screen where a new user can be added. - -.. image:: /images/b_usermanagement_04.png - -By default the new user is granted a “User” role. At least one role is required when a new user is invited. -Do not forget to click ‘Save’! When saved, an invitation email will be sent to the new user. -This user can follow the invitation link to (if necessary) create an account and receive the new roles. -The user will appear in the user management overview once they accepted the invite and created the account. - -.. note:: - Sometimes this invitation mail will end up in the spam folder. - -.. note:: - The invited user is required to sign in with the email address that is supplied by the manager. This email address can't be changed later on. - -.. note:: - Deselecting all roles will remove the user from the organisation, but will not delete the user's account. - -.. note:: - You cannot remove your own manager role. - -.. tip:: - Click on 'Pending Users', to see who have not completed the activation process yet. - diff --git a/source/e_viewer.rst b/source/b_viewer.rst similarity index 100% rename from source/e_viewer.rst rename to source/b_viewer.rst diff --git a/source/c_apifunctional.rst b/source/c_apifunctional.rst deleted file mode 100644 index 1633bbb..0000000 --- a/source/c_apifunctional.rst +++ /dev/null @@ -1,73 +0,0 @@ -============================== -API functional documentation -============================== - -You can access the Lizard API via “{your_organisation}.lizard.net/api/v4/”. - -.. image:: /images/c_apifunctional_01.jpg - -What is an API? -=============== - -API stands for Application Programming Interface. -The API, looking like the picture above, gives back timeseries, rasters, or other data or information. -This is depending on the request you do to the API. -This request comes from the URL you type in the browser. -You can also access the API via another program, and make automatic requests. - -Basic use API -============= - -Below we discuss a basic request to the API. -More examples and possibilities will be discussed further down - -The basic url is www.{your_organisation}.lizard.net/api/v4, for example: - www.demo.lizard.net/api/v4 - -If you type this in your browser, for example Google Chrome, you will get a list of parameters. -These parameters are so called *endpoints*. -If you paste this endpoint after your basic url, you will initiate a query. -An example is ``locations``. -If you click on the url www.demo.lizard.net/api/v4/locations , you will send a query to Lizard to search all locations that you have access to. -As a response, you will get indeed the locations back, as well as some metadata. - -.. image:: /images/c_apifunctional_02.jpg - -Above each page, you will see some additional parameters, with which you can specify your query more. -Most endpoints have examples of this. - -.. image:: /images/c_apifunctional_03.jpg - -If we are looking for a specific location, with a name that starts with 'Inlaat', we can use this query: - -https://demo.lizard.net/api/v4/locations/?name__startswith=Inlaat - -If you are an administrator or supplier of the data, you can also edit or delete the data via the API. - -Versions -======== - -We support two versions of our API: - -* API v3: deprecated (sunset date: 4 July 2023) -* API v4: stable - - -API V3 will be taken offline by 4 July 2023. Any use in scripts or applications should be reimplemented in API V4. -API V4 is the stable version. We can make changes to this version, but they should always be backwards compatible and therefore not break any existing use. - -Digitale Delta API ------------------- - -De Nederlandse watersector staat voor de opgave om in een snel veranderende omgeving haar informatievoorziening te transformeren en klaar te maken voor de toekomst. -De Digitale Delta is het open platform voor het aanbieden en vinden van relevante data voor het waterbeheer in Nederland. -Lizard spreekt Digitale Delta en is een van de dataleveranciers binnen de Digitale Delta. -De Digitale Delta API Root is te vinden op https://demo.lizard.net/dd/api/v2 - -De documentatie van de Digitale Delta API is te vinden op: -https://github.com/DigitaleDeltaOrg/dd-api-spec/blob/master/README.md - -Contact -======= - -If you have additional questions about the use of the API contact our servicedesk (servicedesk@nelen-schuurmans.nl) \ No newline at end of file diff --git a/source/d_datatypes.rst b/source/c_endpoints.rst similarity index 76% rename from source/d_datatypes.rst rename to source/c_endpoints.rst index 7c77963..673bccd 100644 --- a/source/d_datatypes.rst +++ b/source/c_endpoints.rst @@ -1,5 +1,263 @@ - ========= +Endpoints +========= + +This page goes into the technical documentation of our API. + +The Lizard REST API is used to interact with Lizard data and objects. +The API enables to collect, export and manage data. +With the API, objects and data can be listed, created, (partially) updated and retrieved. +Objects and data have different endpoints, to allow specific interactions. + +The endpoints are browseable through the API root view: + +- API V3 https://demo.lizard.net/api/v3/ (deprecated) + +- API V4 https://demo.lizard.net/api/v4/ (stable) + +Resources are addressable via an URL and can be interacted with via HTTP verbs. The +most commonly used and supported verbs are: + +* GET : retrieve data +* PATCH/PUT : change data +* DELETE : delete data +* POST : add data + +We also have HEAD and OPTIONS. + +.. _APIAuthenticationAnchor: + +Authentication +============== + +When you login via your browser, your browser receives a session cookie. +All subsequent requests to the API are authenticated with that session cookie. + +Authenticating to the REST API outside of a browser is done by attaching a +Personal API Key to *every* request. You can attach a Personal API Key to +a request by using HTTP Basic Authentication with password = {your api key}. +The username needs to be fixed to ``__key__`` (with double underscores on both +sides of the word "key"). + +Almost all applications or script languages support HTTP Basic Authentication. +See below for some examples. + +Generate a Personal API key at https://demo.lizard.net/management/. +It is considered best practise to generate one Personal API Key per application +or script, so that you can selectively revoke keys in case they are compromised. + +Examples +-------- + +Python requests +~~~~~~~~~~~~~~~ + +With Python, we recommend using the ``requests`` package. Supply your API Key +in the ``auth`` parameter, as follows: + +.. code-block:: python + + import requests + + url = "demo.lizard.net/api/v4/locations" + my_secret_key = "abcdefg.01234567890" # Example + + response = requests.get(url, auth=("__key__", my_secret_key)) + + +Postman +~~~~~~~ + +In Postman you can set up HTTP Basic Authentication as shown in the image below. +Be sure to choose "Basic Auth" as Type, and not "API Key". + +.. image:: /images/c_apitechnical_03.png + + +Applications: OAuth2 +-------------------- + +Applications (such as dashboards) that use the Lizard API should authenticate +using OAuth2. For this, you will need a registration. Contact our servicedesk to +request one. + + +Legacy: username / password +--------------------------- + +Lizard supports authenticating by attaching ``username`` and ``password`` to +every request, either directly in Username and Password headers, or using +HTTP Basic Authentication. This legacy authentication does generate a session. + +.. warning:: + This form of authentication has been deprecated on *June 1st, 2021*. Ensure + that your applications and scripts use new API Keys after that date. + +In the period until June 1st, 2021, correct username / password combinations +will be migrated automatically to a Personal API Key, in such a way that +you may keep using the same username / password combination. Password changes +will however not be reflected anymore in the migrated API Key. + + +Authorisation +============= + +For all endpoints, users have to be ``admin`` in the organisation that owns the +data to create or update resources. +See `user management `_ for more information about roles and permissions. + +Supported data formats +====================== + +The data formats supported depend on the endpoint, although +JSON is generally available. See documentation on the individual endpoints +for specifics. + +The format of responses can be controlled by specifying an ``Accept`` header +in requests, e.g. Accept: application/json. When posting data, the +format of the payload must be specified via a ``Content-Type`` header, e.g. +Content-Type: text/csv. + +When interacting with the API via a browser, the ``format`` query parameter +may also be used for controlling the format of the response, for example: + +https://demo.lizard.net/api/v4/timeseries/?format=json + +Common variables +================ + +In this section, query parameters and response fields applicable to all +endpoints are described. + +Query parameters +---------------- + +The API supports the following common query parameters on :http:method:`GET` list requests: + +.. http:get:: //?page=(int:offset)&page_size=(int:size) + + :query page: offset number; default is 0. + :query page_size: limit number of entries returned; default is 10. + +Response fields +--------------- + +All list responses share the following fields. + + * **count:** number of results for this page + * **next:** url to next page, `null` if last page + * **previous:** url previous page, `null` if first page + * **results:** array with actual results + +These fields are not specifically mentioned in the response description of each endpoint. + +Timeseries +========== + +This section describes timeseries-related endpoints. + +.. _timeseries_endpoint: + +.. _timeseries_base_parameters: + + **Example request:** + + GET https://demo.lizard.net/api/v4/timeseries/1bcba36e-781d-4339-9632-00d5398c3b15/ + + **Example response:** + + .. image:: /images/c_apitechnical_01.jpg + +Locations +========== + +This section describes location-related endpoints. + +.. _locations_endpoint: + + **Example request:** + + GET https://demo.lizard.net/api/v4/locations/faa84a55-cb8d-460c-a8b8-18d2b59da28c/ + + **Example response:** + + .. image:: /images/c_apitechnical_02.jpg + +Changes in v4 compared to v3 +============================ + +Some major changes have been made in the setup of API v4 in comparison to v3. We have worked on consistency in parameterisation and response formats per endpoint. + +To help users convert their scripts and applications we list the most important changes here. For more details please inspect the documentation within the API. + +Timeseries +---------- + + * Timeseries events, aggregates and percentiles can be retrieved from separate sub-endpoints under the timeseries instance, instead being combined in the detail page of the timeseries instance. + * Timestamps are in ISO8601 format, instead of UNIX milliseconds. + +Rasters +------- + +- Raster aggregates have been split out in separate sub-endpoints under ``/api/v4/rasters/{uuid}/``: + + - counts + + - curve + + - line + + - point + + - rrc + + - zonal + +- Raster WMS is no longer available within the versioned Lizard API (``/api/v3/wms/`` isn't being replaced by ``/api/v4/wms/``). Instead use https://demo.lizard.net/wms/. + +- Timestamps are in ISO8601 format, instead of UNIX milliseconds. + +Scenarios +--------- + +- scenario-results has become a sub-endpoint under scenario instances, i.e. ``/api/v4/scenarios/{uuid}/results/`` + +Labels +------ + +- All label related endpoints have been grouped under the labeltypes endpoint. + +Events +------ + +- The events endpoint has been placed under eventseries. + +Miscellaneous +------------- + +- /regions has become /boundaries in v4 + +- The following endpoints will not return in v4: + + - annotations + + - domains + + - nodes + + - leveereferencepoints + + - leveerings + + - leveesections + + - leveezones + + - opticalfibers + + - timeseriestypes + + Datatypes ========= diff --git a/source/c_general.rst b/source/c_general.rst deleted file mode 100644 index 27f1fdd..0000000 --- a/source/c_general.rst +++ /dev/null @@ -1,14 +0,0 @@ -================ -General -================ - - -In the data management interface you manage rasters, geoblocks, wms layers, layer collections, time series, scenarios and labels. - - -.. image:: /images/c_datatypes_01.png - -The Data Management interface is available at: “{your_organisation}.lizard.net/management/”. - -.. note:: - This functionality is available only to users with an admin, manager or supplier role. \ No newline at end of file diff --git a/source/d_general.rst b/source/c_introduction.rst similarity index 77% rename from source/d_general.rst rename to source/c_introduction.rst index 864e6fe..c5fd425 100644 --- a/source/d_general.rst +++ b/source/c_introduction.rst @@ -1,4 +1,75 @@ -================ +============ +Introduction +============ + +API functional documentation +============================== + +You can access the Lizard API via “{your_organisation}.lizard.net/api/v4/”. + +.. image:: /images/c_apifunctional_01.jpg + +What is an API? +=============== + +API stands for Application Programming Interface. +The API, looking like the picture above, gives back timeseries, rasters, or other data or information. +This is depending on the request you do to the API. +This request comes from the URL you type in the browser. +You can also access the API via another program, and make automatic requests. + +Basic use API +============= + +Below we discuss a basic request to the API. +More examples and possibilities will be discussed further down + +The basic url is www.{your_organisation}.lizard.net/api/v4, for example: + www.demo.lizard.net/api/v4 + +If you type this in your browser, for example Google Chrome, you will get a list of parameters. +These parameters are so called *endpoints*. +If you paste this endpoint after your basic url, you will initiate a query. +An example is ``locations``. +If you click on the url www.demo.lizard.net/api/v4/locations , you will send a query to Lizard to search all locations that you have access to. +As a response, you will get indeed the locations back, as well as some metadata. + +.. image:: /images/c_apifunctional_02.jpg + +Above each page, you will see some additional parameters, with which you can specify your query more. +Most endpoints have examples of this. + +.. image:: /images/c_apifunctional_03.jpg + +If we are looking for a specific location, with a name that starts with 'Inlaat', we can use this query: + +https://demo.lizard.net/api/v4/locations/?name__startswith=Inlaat + +If you are an administrator or supplier of the data, you can also edit or delete the data via the API. + +Versions +======== + +We support two versions of our API: + +* API v3: deprecated (sunset date: 4 July 2023) +* API v4: stable + + +API V3 will be taken offline by 4 July 2023. Any use in scripts or applications should be reimplemented in API V4. +API V4 is the stable version. We can make changes to this version, but they should always be backwards compatible and therefore not break any existing use. + +Digitale Delta API +------------------ + +De Nederlandse watersector staat voor de opgave om in een snel veranderende omgeving haar informatievoorziening te transformeren en klaar te maken voor de toekomst. +De Digitale Delta is het open platform voor het aanbieden en vinden van relevante data voor het waterbeheer in Nederland. +Lizard spreekt Digitale Delta en is een van de dataleveranciers binnen de Digitale Delta. +De Digitale Delta API Root is te vinden op https://demo.lizard.net/dd/api/v2 + +De documentatie van de Digitale Delta API is te vinden op: +https://github.com/DigitaleDeltaOrg/dd-api-spec/blob/master/README.md + Data uploads ================ @@ -285,4 +356,7 @@ This example .ini creates (a) new nested asset(s) from each record of the shapef You can copy paste this code in your own .ini file and zip it together with the shapefile. +Contact +======= +If you have additional questions about the use of the API contact our servicedesk (servicedesk@nelen-schuurmans.nl) diff --git a/source/c_labels.rst b/source/c_labels.rst deleted file mode 100644 index 835868c..0000000 --- a/source/c_labels.rst +++ /dev/null @@ -1,8 +0,0 @@ -============ -Labels -============ - -.. warning:: - This section is to be extended. - -.. image:: /images/c_manage_labeltypes.png diff --git a/source/c_layercollections.rst b/source/c_layercollections.rst deleted file mode 100644 index 7b31ed5..0000000 --- a/source/c_layercollections.rst +++ /dev/null @@ -1,6 +0,0 @@ -==================== -Layer collections -==================== - -.. warning:: - This section will be extended in the near future. \ No newline at end of file diff --git a/source/c_rasters.rst b/source/c_rasters.rst deleted file mode 100644 index 5d30ac7..0000000 --- a/source/c_rasters.rst +++ /dev/null @@ -1,54 +0,0 @@ -============= -Rasters -============= - -The data management interface for rasters can be used to upload, edit or remove rasters. -Raster Sources are the data containers, Raster Layers are the configuration of how the data is visualised. - -.. image:: /images/c_manage_rasters_01.png -.. image:: /images/c_manage_rasters_02.png -.. image:: /images/c_manage_rasters_03.png - -Creating and editing Raster Sources and Layers ----------------------------------------------- - -The first step in uploading your raster datasets is to create a Raster Source. - -The Data Management interface is available at: “www.{your_organisation}.lizard.net/management/”. - -After landing on this page, click on ‘Data’ -> ‘Rasters’ -> 'Raster Sources'. -Click on “New Item” |NewItem| to open the form or choose an existing raster to edit. - -.. |NewItem| image:: /images/c_manage_newitem.png - -After filling in the form you can choose to directly upload your data by selecting your GeoTIFF's in the 'DATA' section. -In case of a temporal raster source you need to specify which file belongs to which timestep. -This is recognised automatically if the filename is composed according to the specified format. -When you save a new Source you will have the option to go straight to the Raster Layer form to publish your data. - -.. image:: /images/c_datatypes_01.png - -Interested in the possibilities for your organisation? Please contact us via info@lizard.net. - -GeoBlocks management --------------------- - -The GeoBlocks management page provides you a powerful tool to build your GeoBlocks Rasters. -It helps you configure complex GeoBlocks models and enables you to validate your work along the way. - -The Visual editor shows your model as a flow diagram, consisting of block objects representing the input Raster Sources and GeoBlocks operations. -The right sidebar shows the available blocks. Click on the blocks for a description and the expected inputs. Drag a block into the canvas to include it in your model. -Connect blocks to use one as input for the other. - -When the model is valid it can also be shown in the Text editor. This shows the JSON graph as it would be sent to the API when you save the item. -Here you can also make edits and validate the result. - -Example 1 shows a simple model which subtracts one Raster Source from another (difference in surface elevation between two versions of a dataset). - -.. image:: /images/c_manage_geoblocks_01.png - -Example 2 shows a more complex model with multiple Raster Sources and a series of operations. - -.. image:: /images/c_manage_geoblocks_02.png - -For more information about the possibilities of GeoBlocks see: :ref:`GeoBlocksAnchor` diff --git a/source/c_scenarios.rst b/source/c_scenarios.rst deleted file mode 100644 index 48a7f40..0000000 --- a/source/c_scenarios.rst +++ /dev/null @@ -1,75 +0,0 @@ -============== -Scenarios -============== - -The data management interface for scenarios can be used to manage scenarios. - - -.. image:: /images/c_manage_scenarios_01.png - - -Search for a scenario ------------------------- - -You can search for a scenario by either typing (part of) the scenario name, the UUID, username of the supplier or model name. - -.. image:: /images/c_manage_scenarios_search.png - -You can also specify that you only want to show your own scenarios by ticking the box in the top right corner. - - -Used storage and deletion of scenarios ------------------------------------------ - -.. image:: /images/c_manage_scenarios_storage.png - -In the left side, you can see the used storage for your organisation. This may have influence on your subscription. - -.. image:: /images/c_manage_scenarios_delete1.png - -If you want to remove a complete scenario, you simply check the box of the relevant scenario(s) and choose 'delete'. -If you choose 'delete raw', it will only remove the raw data and not the timeseries and rasters. You can also remove a specific raster of a scenario by double-clicking on a scenario and clicking on the 'trash' icon next to the layer. - -.. image:: /images/c_manage_scenarios_delete2.png - -.. warning:: - If you delete a scenario, it is really gone! We might be able to retrieve the rasters if you contact support within 14 days. - -Add a scenario --------------------- - -Scenarios can be automatically exported to Lizard, for example via 3Di. -You can also add a new scenario with the New Item button on the top right corner. - -.. image:: /images/c_manage_newitem.png - -Edit a scenario ----------------- - -Right now you can only edit the accessability of a scenario. -Scenarios are private by default (only visible for logged in users of the same organisation). -You can choose to make them visible for all logged in users or even public so no login is necessary. - -.. image:: /images/c_manage_scenarios_public.png - - -.. tip:: - Make scenarios public if you want to use them in other GIS applications via a `wms link `_. - - -You can add a scenario to an existing project via the threedot icon. - -.. image:: /images/c_manage_scenarios_project.png - -Group scenarios in a project ------------------------------ - -Projects are used to group and give insights on scenarios. - -.. image:: /images/c_manage_projects_01.png - -Create a new project with the New Item button on the top right corner. - -.. image:: /images/c_manage_newitem.png - - \ No newline at end of file diff --git a/source/c_timeseries.rst b/source/c_timeseries.rst deleted file mode 100644 index 5ca33c3..0000000 --- a/source/c_timeseries.rst +++ /dev/null @@ -1,160 +0,0 @@ -============== -Time series -============== - - -The data management interface for timeseries can be used to upload, edit or remove timeseries, monitoring networks and locations. - -.. image:: /images/c_manage_timeseries_menu.png - - ----------- -Locations ----------- - -.. image:: /images/c_manage_locations_01.png - - -Search or sort your locations here. -Check out possible actions by clicking the three dots icon. -Create a new object with the New Item button on the top right corner. - - -.. image:: /images/c_manage_newitem.png - -.. image:: /images/c_manage_locations_02.png - -1. GENERAL ------------- - -* Location name (required): Choose a name that is findable and not too difficult -* Code (required): Choose a code that represents the object within your organisation. - - -2. DATA ------------- - -.. warning:: - Locations must be connected to an existing asset to be visualised in the Viewer. The asset will have a symbol and zoom level depending on the type. Also, the metadata differs per type. For now, only measuringstations can be added via the API. If you have any questions about this, please contact the service desk. - -* Asset type (optional): Specify a type of asset. -* Asset location: after specifying the asset type, you can search by code or name. -* Extra metadata (JSON) (optional): Free JSON field to add information to this object. - -3. RIGHTS ------------- - -* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. - - -If you are satisfied, click "SAVE" - ------------- -Timeseries ------------- - -.. image:: /images/c_manage_timeseries_01.png - -Search or sort your time series here. -Check out possible actions by clicking the three dots icon next to a time series. You can add timeseries to a monitoring network (MN), edit, or delete hem. -Create a new object with the New Item button on the top right corner. - -.. image:: /images/c_manage_newitem.png - -.. image:: /images/c_manage_timeseries_02.png - -1. GENERAL ------------- - -* Name (required): Choose a name that is findable and not too difficult -* Code (required): Choose a code that represents the object within your organisation. - - -2. DATA ------------- - -* Observation type (required): Choose the way the data is measured, and the units. New observation types can be added via the `api `_ or requested via the servicedesk. -* Location (required): Choose to which location you want to add this timeseries. New locations can be added via the api or via data management --> timeseries --> locations. -* Value type (required): Specify what kind of data you will be supplying. See `Level of measurement `_. -* Datasource (optional): Specify a data source if it is available. Otherwise, you can leave it empty or create a new one via the API. -* Interval (optional): Specify a time range between each time series step. - -.. note:: - if you leave the interval at 0, it will mean it is irregular ('nonequidistant') data. This is also necessary if you have timesteps smaller than seconds. - -* CSV Files (optional): You can add new data via a csv file or via the API. If you want to supply a csv file, see the instructions below: - -.. note:: - The first line of the file should describe the column names, for example: - - | time, value - | 2020-03-20T01:00:00Z, 3.14 - | 2020-03-20T01:05:00Z, 2.72 - - The next lines are the timestemp and value for that timestep. Make sure you do not list the same timestep twice. - All uploads in Lizard are expected to be in UTC time. - - | time: ISO 8601 date and time representation. This is a required field. - | value: A number, string, or boolean, depending on the value_type of the corresponding time series. - - -* Extra metadata (JSON) (optional): Free JSON field to add information to this object. - - -3. RIGHTS ------------- - -* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. -* Username of supplier (optional): The supplier of this object. If you are not an administrator, this field is always pre-filled with your username. -* Supplier code (optional): The FTP or Supplier code is used as reference to your own system. - -.. note:: - Timeseries are not linked to an organisation directly. They are linked to organisations via the locations. - -If you are satisfied, click "SAVE" - - - ---------------------- -Monitoring networks ---------------------- - -Monitoring networks are used to group and give insights on time series. -Check out possible actions by clicking the three dots icon next to existing networks. - -Create a new object with the New Item button on the top right corner. - -.. image:: /images/c_manage_newitem.png - -.. image:: /images/c_manage_monitoringnetworks_01.png - -1. GENERAL ------------- - -* Name (required): Choose a name that is findable and not too difficult -* Description (optional) - - -2. DATA ------------- - -.. warning:: - The button "MANAGE" will only work if there are already timseries connected to the monitoring network. If there are, you can remove the the connection here. New connections can be added via the timeseries management app. - -3. RIGHTS ------------- - -* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. -* Organisation (required, pre-filled): The organisation this object belongs to. - -If you are satisfied, click "SAVE" - - - - - - - - - - diff --git a/source/c_wms.rst b/source/c_wms.rst deleted file mode 100644 index 93455e5..0000000 --- a/source/c_wms.rst +++ /dev/null @@ -1,66 +0,0 @@ -=========== -WMS Layers -=========== - -WMS stands for Web Mapping Service. -It is a standard method of sharing georeferenced maps. -The WMS layers management allows the user to configure layers in Lizard even if they are hosted on another platform. -In the management screen you can add new WMS layers or edit existing layers. - -.. image:: /images/c_manage_wms_01.png - -New WMS Layer -============== - - -.. image:: /images/c_manage_newitem.png - -After clicking the 'NEW ITEM' icon, you can configure a new WMS layer. - -.. image:: /images/c_manage_wms_02.png - -The configuration has some mandatory items while others are optional, an extensive list with descriptions follows: - -1. GENERAL ------------- - -* Name (required): Choose a name that is findable and not too difficult -* Description (optional): Give a description of the information that is displayed by the WMS layer. -* Tags / Datasets (optional): You can connect the layer to an existing dataset. - -2. DATA ------------- - -* WMS URL (required): Specify which base URL is used to retrieve the image data. It usually ends on '/wms' -* Slug (required): can be seen as layer name used in the external platform -* Download URL (optional): Specify which URL is used to download the data. This will enable the download button in the Lizard Catalogue. -* Legend URL (optional): Specify which URL is used to show the legend of this layer. -* Get Feature URL (optional) : Optional URL to retrieve feature info data. -* Tiled (enabled by default) : Specifies whether the layer is tiled (for better performance) -* Min and max zoom (required): Closest and furthest point of view in this WMS layer. 0 is visible at world scale, 31 is zoomed in at a house. You can check the zoom level in the url in the Viewer (after the coordinates). -* Spatial bounds (optional): Specify the extent of this layer on the map. This information can also be automatically obtained by clicking "Get from source". -* Options (JSON): Extra options of this layer, specfied in JSON. - -3. RIGHTS ------------- - -* Accessibility (required, private by default): Choose an access modifier to decide who has access to this object. -* Shared with (optional): Specify if this object should be accessible by other organisations, and if so, which ones. -* Organisation (required, pre-filled): The organisation this object belongs to. -* Supplier (optional): The supplier of this object. If you are not an administrator, this field is always pre-filled with your username. - -If you are satisfied, click "SAVE" - - -Edit WMS Layer -=============== - -By clicking on the name of a WMS layer, the configuration of the corresponding layer is opened. -In the configuration page you can edit any of the settings previously given to the WMS layer. -To quickly find a WMS layer: use the search bar. -If the layer you are looking for seems unavailable you might have to switch organisations, feel free to contact the servicedesk for any problems (servicedesk@nelen-schuurmans.nl). - -.. image:: /images/c_manage_wms_03.png - -.. tip:: - Advanced: Is your WMS layer not visible in the Viewer? Check via the network tab (press F12) how Lizard requests the WMS and if that WMS url makes sense. diff --git a/source/d_apitechnical.rst b/source/d_apitechnical.rst deleted file mode 100644 index 53f4dad..0000000 --- a/source/d_apitechnical.rst +++ /dev/null @@ -1,258 +0,0 @@ -============================= -API technical documentation -============================= - -This page goes into the technical documentation of our API. - -The Lizard REST API is used to interact with Lizard data and objects. -The API enables to collect, export and manage data. -With the API, objects and data can be listed, created, (partially) updated and retrieved. -Objects and data have different endpoints, to allow specific interactions. - -The endpoints are browseable through the API root view: - -- API V3 https://demo.lizard.net/api/v3/ (deprecated) - -- API V4 https://demo.lizard.net/api/v4/ (stable) - -Resources are addressable via an URL and can be interacted with via HTTP verbs. The -most commonly used and supported verbs are: - -* GET : retrieve data -* PATCH/PUT : change data -* DELETE : delete data -* POST : add data - -We also have HEAD and OPTIONS. - -.. _APIAuthenticationAnchor: - -Authentication -============== - -When you login via your browser, your browser receives a session cookie. -All subsequent requests to the API are authenticated with that session cookie. - -Authenticating to the REST API outside of a browser is done by attaching a -Personal API Key to *every* request. You can attach a Personal API Key to -a request by using HTTP Basic Authentication with password = {your api key}. -The username needs to be fixed to ``__key__`` (with double underscores on both -sides of the word "key"). - -Almost all applications or script languages support HTTP Basic Authentication. -See below for some examples. - -Generate a Personal API key at https://demo.lizard.net/management/. -It is considered best practise to generate one Personal API Key per application -or script, so that you can selectively revoke keys in case they are compromised. - -Examples --------- - -Python requests -~~~~~~~~~~~~~~~ - -With Python, we recommend using the ``requests`` package. Supply your API Key -in the ``auth`` parameter, as follows: - -.. code-block:: python - - import requests - - url = "demo.lizard.net/api/v4/locations" - my_secret_key = "abcdefg.01234567890" # Example - - response = requests.get(url, auth=("__key__", my_secret_key)) - - -Postman -~~~~~~~ - -In Postman you can set up HTTP Basic Authentication as shown in the image below. -Be sure to choose "Basic Auth" as Type, and not "API Key". - -.. image:: /images/c_apitechnical_03.png - - -Applications: OAuth2 --------------------- - -Applications (such as dashboards) that use the Lizard API should authenticate -using OAuth2. For this, you will need a registration. Contact our servicedesk to -request one. - - -Legacy: username / password ---------------------------- - -Lizard supports authenticating by attaching ``username`` and ``password`` to -every request, either directly in Username and Password headers, or using -HTTP Basic Authentication. This legacy authentication does generate a session. - -.. warning:: - This form of authentication has been deprecated on *June 1st, 2021*. Ensure - that your applications and scripts use new API Keys after that date. - -In the period until June 1st, 2021, correct username / password combinations -will be migrated automatically to a Personal API Key, in such a way that -you may keep using the same username / password combination. Password changes -will however not be reflected anymore in the migrated API Key. - - -Authorisation -============= - -For all endpoints, users have to be ``admin`` in the organisation that owns the -data to create or update resources. -See :doc:`b_usermanagement` for more information about roles and permissions. - -Supported data formats -====================== - -The data formats supported depend on the endpoint, although -JSON is generally available. See documentation on the individual endpoints -for specifics. - -The format of responses can be controlled by specifying an ``Accept`` header -in requests, e.g. Accept: application/json. When posting data, the -format of the payload must be specified via a ``Content-Type`` header, e.g. -Content-Type: text/csv. - -When interacting with the API via a browser, the ``format`` query parameter -may also be used for controlling the format of the response, for example: - -https://demo.lizard.net/api/v4/timeseries/?format=json - -Common variables -================ - -In this section, query parameters and response fields applicable to all -endpoints are described. - -Query parameters ----------------- - -The API supports the following common query parameters on :http:method:`GET` list requests: - -.. http:get:: //?page=(int:offset)&page_size=(int:size) - - :query page: offset number; default is 0. - :query page_size: limit number of entries returned; default is 10. - -Response fields ---------------- - -All list responses share the following fields. - - * **count:** number of results for this page - * **next:** url to next page, `null` if last page - * **previous:** url previous page, `null` if first page - * **results:** array with actual results - -These fields are not specifically mentioned in the response description of each endpoint. - -Timeseries -========== - -This section describes timeseries-related endpoints. - -.. _timeseries_endpoint: - -.. _timeseries_base_parameters: - - **Example request:** - - GET https://demo.lizard.net/api/v4/timeseries/1bcba36e-781d-4339-9632-00d5398c3b15/ - - **Example response:** - - .. image:: /images/c_apitechnical_01.jpg - -Locations -========== - -This section describes location-related endpoints. - -.. _locations_endpoint: - - **Example request:** - - GET https://demo.lizard.net/api/v4/locations/faa84a55-cb8d-460c-a8b8-18d2b59da28c/ - - **Example response:** - - .. image:: /images/c_apitechnical_02.jpg - -Changes in v4 compared to v3 -============================ - -Some major changes have been made in the setup of API v4 in comparison to v3. We have worked on consistency in parameterisation and response formats per endpoint. - -To help users convert their scripts and applications we list the most important changes here. For more details please inspect the documentation within the API. - -Timeseries ----------- - - * Timeseries events, aggregates and percentiles can be retrieved from separate sub-endpoints under the timeseries instance, instead being combined in the detail page of the timeseries instance. - * Timestamps are in ISO8601 format, instead of UNIX milliseconds. - -Rasters -------- - -- Raster aggregates have been split out in separate sub-endpoints under ``/api/v4/rasters/{uuid}/``: - - - counts - - - curve - - - line - - - point - - - rrc - - - zonal - -- Raster WMS is no longer available within the versioned Lizard API (``/api/v3/wms/`` isn't being replaced by ``/api/v4/wms/``). Instead use https://demo.lizard.net/wms/. - -- Timestamps are in ISO8601 format, instead of UNIX milliseconds. - -Scenarios ---------- - -- scenario-results has become a sub-endpoint under scenario instances, i.e. ``/api/v4/scenarios/{uuid}/results/`` - -Labels ------- - -- All label related endpoints have been grouped under the labeltypes endpoint. - -Events ------- - -- The events endpoint has been placed under eventseries. - -Miscellaneous -------------- - -- /regions has become /boundaries in v4 - -- The following endpoints will not return in v4: - - - annotations - - - domains - - - nodes - - - leveereferencepoints - - - leveerings - - - leveesections - - - leveezones - - - opticalfibers - - - timeseriestypes diff --git a/source/d_authentication_user_management.rst b/source/d_authentication_user_management.rst new file mode 100644 index 0000000..e2b9da3 --- /dev/null +++ b/source/d_authentication_user_management.rst @@ -0,0 +1,199 @@ +================================== +Authentication and User Management +================================== + + +Signing in +========== + +Users that already have a Lizard account can click the "Log in" +button on the top right of the screen. + +First-time users require an invitation to create a Lizard account. Users with +a "manager" role are able to send invitations to new users. +If you do not know whom to contact, please contact our support office +(servicedesk@nelen-schuurmans.nl). + +After clicking "Log in" or after following the invitation link, you will arrive +at the login screen. + +.. note:: + Please ensure that "https://auth.lizard.net/" domain is indeed displayed + in your browser's address bar and that your browser displays the lock + symbol indicating that the connection is secure. + +On the login page you have four different options to sign in: + +1. through a company account, +2. through a social account, +3. with username and password, +4. by creating a new account (Sign up). + +First-time users may choose any of these options. If your company is listed as +one of the possible companies to sign in with, that is the preferred choice. + +Existing users should use the same method as they used when signing in for +the first time. If your Lizard username/password existed before Januari 2021, +use method 3. + +.. tip:: + Do you want to add your company to the list to centralise the user accounts + of your organisation? Please contact our support office + (servicedesk@nelen-schuurmans.nl) for the options. + + +Organisations +============= + +All data in Lizard is linked to an organisation. +Organisations are the backbone of our authorisation model. +When an organisation uploads data, they are able to determine the level of authorisation required for access. +There are three types of authorisation options that can be applied to your data: + +* **Public**: everyone is able to access your data +* **Common**: everyone with login credentials to Lizard is able to access your data +* **Private**: everyone with login credentials to Lizard AND user rights to your organisation is able to access your data + + + +Whitelisting +------------ + +The users of a certain portal may not be interested in a lot of the public/common datasets that are made available by others. +Every Lizard portal has its own whitelist. +Whitelisting allows the organisations to determine which data should be visible. +This can remove some of the clutter. +The whitelist affects both the Lizard Viewer aswell as the Catalogue. + +The effect is that for the same user the available data can differ between [your_organisation].lizard.net and demo.lizard.net (for which all organisations are whitelisted). +The whitelisting mechanism is overruled if a user has specific authorisation for an organisation. + +.. tip:: + Do you want to see or change the whitelist settings of a portal? Please contact our support office + (servicedesk@nelen-schuurmans.nl). + + +Roles +----- + +We have 4 roles and 3 different types of privileges. + +* A **user**, who can only *read* data +* A **supplier**, who can *read* data and change (*'write'*) his or her own data +* An **administator**, who can *read* data and change (*'write'*) all organisation's data. +* A **manager**, who can *manage* other roles in the organisation. A manager can not read or write data by default. This role should be appointed separately. + + +User management +=============== + +Users can be managed in the User Management interface. +This interface can be reached via the {your_organisation}.lizard.net/management/users/ (or `demo.lizard.net/management/users `_). + +.. note:: + You require a “manager” role to access the User Management interface. + Haven’t got a “manager” role but you would like to add the User Management interface? + Please contact the application manager within your organisation or our support office (servicedesk@nelen-schuurmans.nl) + +.. image:: /images/b_usermanagement_03.png + +In the example above, you see the current rights for 7 users under the organisation Nelen & Schuurmans. + + +The management screen offers the opportunity to manage various aspects of your organization. +This includes managing your data: rasters, scenarios, time series, and more. +For complete use of this page, refer to the `lizard documentation `_. +The most important thing in this case is "User Management". +Only managers have access to the "Users" screen. +In this screen, you can: + +1. Invite new users. +2. Manage invitations. +3. Adjust existing rights. + + +Inviting New Users +---------------------------- + +If a new user needs access to Lizard from the organization, this can be granted by the Manager. +This is done as follows: + +1. Log in to the organization's portal ({organization}.lizard.net). +2. Go to the user section in the management screen ({organization}.lizard.net/management/users). +3. Click on `+ NEW USER` at the top right of the screen (Image 1, in red). +4. Type the user's email in the 'email' field (Image 2). +5. Select the roles the user will have. For the rights associated with the roles, refer to `Roles`_. +6. Click `SAVE`. +7. Success! The invitation has been sent and will be in the new user's mailbox within 5 minutes. + +.. tip:: Clicking on a role when inviting someone will also display the rights of each role on the left side of your screen. + +.. tip:: If the email does not appear in the inbox after 5 minutes, first check your spam folder. If the invitation is not there either, you can always contact the `servicedesk `_. + +.. figure:: /images/h_gebruiker_uitnodigen_1.png + :scale: 50% + :alt: Overview of the Lizard management page with multiple users. + + Image 1: An overview of the user section in the management screen of Lizard. + Here you can view existing rights and invite new users (red) or manage pending invitations (yellow). + +.. figure:: /images/h_gebruiker_uitnodigen_2.png + :scale: 50% + :alt: Invitation screen for new users of Lizard. Enter an email and select the roles for the new user. + + Image 2: The invitation screen for new users. You select the roles by clicking on them. + + + +Managing Invitations +--------------------- + +In the `Pending Invitations` screen, you can see which invitations you have sent that have not yet been accepted or expired. +Invitations expire by default within 15 days, but you can cancel them earlier by clicking on the 3 dots next to an email (Image 3). +If an email has not reached a user, you can also verify the email here. + +.. figure:: /images/h_pending_uitnodiging_1.png + :scale: 50% + :alt: Invitation screen for new users of Lizard. Enter an email and select the roles for the new user. + + Image 3: An overview of pending invitations. + + +Adjusting Existing Rights +--------------------------- + +In the user rights overview screen, you can manage the rights of existing users. +Here you see the following information of users who have rights for your organization: + +1. Username +2. Email +3. Roles + +.. figure:: /images/h_rechten_beheren_1.png + :scale: 50% + :alt: Overview of the Lizard management page with multiple users. + + Image 4: An overview of pending invitations. + +By clicking on the username of the respective user, you will be taken to this user's specific page. +Here, you can click on the roles you want to remove or add. +If a role is clearly colored, the user has these rights. + +.. figure:: /images/h_rechten_beheren_2.png + :scale: 50% + :alt: Roles of an individual user. + + Image 5: In this case, the user has 'User' and 'Manager' rights. + + +Tips +============= + +.. tip:: Ensure that rights are discussed and granted at the beginning of a project. + This prevents delays later due to someone waiting for their rights. + +.. tip:: Don't forget to remove users' rights after a project is completed. + This way, you actively maintain the user database and keep your data under control. + However, be sure to check if any scripts are running on an API KEY of any of these users. + +.. tip:: If you want to deactivate accounts, contact the `servicedesk `_. \ No newline at end of file diff --git a/source/d_faq.rst b/source/d_faq.rst new file mode 100644 index 0000000..c964d24 --- /dev/null +++ b/source/d_faq.rst @@ -0,0 +1,14 @@ +========================== +Frequently Asked Questions +========================== + +This section will be extended in the near future. + +.. |date| date:: + + +.. Note:: + This document will be revised periodically to reflect changes in the products and solutions being supported and the processes, + procedures and technologies being used to deliver support services. + The latest version of this document was created on |date|. + \ No newline at end of file diff --git a/source/g_servicesupport.rst b/source/d_self_service_portal.rst similarity index 81% rename from source/g_servicesupport.rst rename to source/d_self_service_portal.rst index ec286cb..22efb83 100644 --- a/source/g_servicesupport.rst +++ b/source/d_self_service_portal.rst @@ -2,6 +2,9 @@ Self Service Portal =================== +Self Service Portal +=================== + Nelen & Schuurmans provide a Service Desk function via https://nelen-schuurmans.topdesk.net/, The Nelen & Schuurmans Self Service Portal shall be available 24/7. The Service Desk giving support on all Lizard products for Lizard customers. Customers can reach telephonic support (Prio 1) on working days from 09:00 - 17:00 (CEST) excluding the days declared as dutch public holiday close days. @@ -18,7 +21,6 @@ This access should be used for, but not limited to: All incidents relating to the Lizard software with the exception of enhancement/feature requests are recorded and followed up at no additional cost. -================== Priority incidents ================== @@ -33,27 +35,9 @@ The levels are: * **Prio 2 (medium):** The work and/or control processes are hindered or the Client's importance is large, but a workaround is possible. * **Prio 3 (low):** Not urgent. Lizard is impaired, a single function is impacted but key business processes are not interrupted. The problem causes minimal operational or business impact, a general technical question or enhancement request. -================ + Feature requests ================ Beyond the scope are enhancement/feature requests or questions about the use of Lizard in the organisation, for which the customer can purchase an additional service. -For more info the customer can contact the local Lizard consultant or email to info@nelen-schuurmans.nl. - - - - -============================== -Frequently Asked Questions -============================== - -This section will be extended in the near future. - -.. |date| date:: - - -.. Note:: - This document will be revised periodically to reflect changes in the products and solutions being supported and the processes, - procedures and technologies being used to deliver support services. - The latest version of this document was created on |date|. - \ No newline at end of file +For more info the customer can contact the local Lizard consultant or email to info@nelen-schuurmans.nl. \ No newline at end of file diff --git a/source/e_lizardwms.rst b/source/e_lizardwms.rst deleted file mode 100644 index e4c2b61..0000000 --- a/source/e_lizardwms.rst +++ /dev/null @@ -1,104 +0,0 @@ -============ -WMS Services -============ - -Lizard provides a Web Map Service (WMS) that you can use to visualise rasters and 3Di scenarios stored in Lizard Raster Server as tiled images. -The Lizard WMS Service follows the `OGC WMS guidelines `_. - -Rasters -======= - -To visualise and request the GetCapabilities of a specific raster you can use the following URL: - -``https://{yourportal}.lizard.net/wms/raster_{UUID of raster}/?request=GetCapabilities`` - -for example: -https://demo.lizard.net/wms/raster_eae92c48-cd68-4820-9d82-f86f763b4186/?request=GetCapabilities - -You can easily find the UUID of the raster in the `Lizard Catalogue `_ or `API `_. -The Lizard Catalogue also provides the Lizard WMS GetCapabilities link for each raster. -With the GetCapabilities query parameter you retrieve the metadata of the service, including supported operations, parameters and a list of available layers. - -3Di Scenarios -============== - -To visualise and request the GetCapabilities of a 3Di scenario (list of rasters) you can use the following URL: - -``https://{yourportal}.lizard.net/wms/scenario_{UUID of scenario}/?request=getcapabilities`` - -For example: -https://demo.lizard.net/wms/scenario_c30ef7f2-c871-4d70-a087-8f078f9ebafd/?request=GetCapabilities - -You can look up the UUID of the scenario using the `Scenarios endpoint in the Lizard API `_. -All available filters are listed on the endpoints’ page. E.g. you can look up a scenario and it’s uuid by filtering on your own username. -With the GetCapabilities query parameter you retrieve the metadata of the service, including supported operations, parameters and a list of available layers. - -Layer collections -====================== - -To visualise and request the GetCapabilities of layer collections (list of rasters, previously called 'datasets') you can use the following URL: - -``https://{yourportal}.lizard.net/wms/{slug of layer collection}?request=GetCapabilities`` - -For example: -https://demo.lizard.net/wms/basiskaarten/?request=GetCapabilities - -You can search for layer collections in the Lizard Catalogue by using the Layer collection filter in the left panel. -You will find the Lizard WMS GetCapabilities URL of the layer collection in the metadata panel of a specific layer. - - -.. _WMSauthAnchor: - -Authorisation -============= - -The Lizard WMS Service follows the authorisation system mentioned under :ref:`Authorisation`. -If layers are private you need privileges in the organisation that owns the data. - -Use a Personal API Key to authenticate with the Lizard WMS Service, as described in :ref:`API Authentication`. - -In QGIS the authentication is filled in as follows: - -- username = __key__ -- password = Personal API Key - - -How to load WMS in GIS -======================= - -You can connect directly to Lizard in a GIS application like QGIS. - - -* 1 - -Open QGIS and load a new WMS connection. - -.. image:: /images/e_qgis_wms1.png - - -* 2 - -Give the connection a name and copy the wms link from 'https' to 'GetCapabilities', e.g. "https://maps1.klimaatatlas.net/geoserver/twn_klimaatatlas/wms/?request=GetCapabilities". - -.. image:: /images/e_qgis_wms2.png - - -* 3 - -If the wms layer is not public, you have to enter your :ref:`Credentials`. in the Authentication - Basic tab. - - -.. image:: /images/e_qgis_wmslogin.jpg - - -* 4 - -Click OK and double click on the connection. If multiple layers appear, double click on the one you are interested in. - -.. image:: /images/e_qgis_wms3.png - - -.. image:: /images/e_qgis_wms4.png - -The styling will automatically be taken from Lizard. -If the layer is temporal, you can also navigate through time. diff --git a/source/a_releasenotes.rst b/source/e_release_notes.rst similarity index 99% rename from source/a_releasenotes.rst rename to source/e_release_notes.rst index 99e453c..93ecedb 100644 --- a/source/a_releasenotes.rst +++ b/source/e_release_notes.rst @@ -30,7 +30,7 @@ October 10th 2023 ================= New viewer released: -* Documentation for the new viewer: :doc:`e_viewer` +* Documentation for the new viewer: :doc:`b_viewer` May 2nd 2023 diff --git a/source/f_alarms.rst b/source/f_alarms.rst deleted file mode 100644 index f0a67fc..0000000 --- a/source/f_alarms.rst +++ /dev/null @@ -1,88 +0,0 @@ -====== -Alarms -====== - -Lizard provides an alarm feature that sends notifications via sms or email when newly processed values of timeseries or temporal rasters exceed a threshold. -It is used to notify people of events that may require action, for instance an upcoming rain event or flood. - -The alarm management screens are found at https://demo.lizard.net/management/#/alarms. - -.. image:: /images/f_alarms_01.jpg - -The configuration has a variety of options to generate relevant notifications with messages that include the specifics of the event. - -Notifications -============= - -Behind the Notifications tile you find the overviews of existing raster and timeseries alarms for your organisation and their status (active/inactive). -The 'NEW ITEM' button leads you to the form to register a new alarm. -We go through some of the options that the system provides, to explain them in detail. - -Selecting a raster ------------------- - -Raster alarms are set on temporal rasters. These can be part of a scenario, a single source raster or a Geoblock. -An alarm is set for one point location intersecting this temporal raster. - -You can type in the field to search in the names of available rasters. Next, select the type of intersection (Point, Line or Polygon). -Draw the geometry on the map or insert a geometry in the JSON field below the map. - -For Line and Polygon intersections a spatial aggregation is needed to derive a timeseries that can be compared to the alarm thresholds. -The options are: - -* Sum -* Mean -* Min -* Max -* Median -* Count - -Selecting a timeseries ----------------------- - -Timeseries often do not have a clear name or code by themselves. -That is why we start with looking up the asset it relates to. -Once the asset is selected it should be easy to select the timeseries from the list of related objects. - -Relative start and end ----------------------- - -The user doesn't always want to receive alarms for the whole period of newly processed data. -For instance, for operational flood models which might have records of prior theshold exceedances, you may only be interested in receiving alarms for forecasted threaths. - -To only analyse the relevant part of your data you can set relative start and end. -They are set relative to The figure below gives a schematic overview of how this method works. - -.. image:: /images/f_alarms_02.jpg - -If these fields are left empty the trigger check is done on the complete data frame of newly processed data. - -Snoozing option ---------------- - -It can be considered undesirable for alarms to be triggered during brief spikes. -The snoozing option allows the user to determine the timeperiod a threshold should be exceeded before the alarm is triggered and a notification is sent. -This option is available for both the raising of the alarm and its withdrawal. Default is 1 (trigger at first occurrence). - -Contacts and Groups -=================== - -The recipients of alarm notifications are configured in the Contacts screen, with their phone number and/or email address. -Each contact can be part of multiple Groups, which in turn can be used in multiple alarms. -So no need to do a whole lot of data duplications of contact info. - -Templates -========= - -The notification messages are configured with Templates. -There is a difference in setting up Email and SMS Templates: - -* Email: Supports both plain text and HTML and are not limited in length -* SMS: Plain text with maximum length of 160 characters (after substitution of variables) - -You can use a number of variables to enrich the content of the notifications and make them applicable to different alarms. -The variables contain options for including the name of the receiver and details about the alarm at hand. - -The option "No further impact" determines that a message is used specifically to notify when an alarm is fully withdrawn. -This type of message can be set in addition to a standard message to let receivers know that the situation has settled down. -This often requires a different text and therefore a different Template. diff --git a/source/h_managers_lizard.rst b/source/h_managers_lizard.rst index 9bee2df..236b3fe 100644 --- a/source/h_managers_lizard.rst +++ b/source/h_managers_lizard.rst @@ -1,165 +1,165 @@ -:orphan: - -======== -Managers -======== - -What are the tasks of a Manager in an organization -================================================== - -The role of a manager is important for managing the data of an organization. -As a manager, you grant or revoke rights for your organization. -A manager mainly has two tasks: - -1. Maintaining the rights of existing users -2. Granting rights to new employees or external parties - -**Maintaining rights of existing users** - -The rights of users under your organization do not expire automatically. -So, it is important that you regularly check whether users still need their rights. -This can include employees leaving the organization or projects coming to an end. -Sometimes, not all rights need to be revoked, this is also possible. -It is up to you to determine how often you want to perform this check. - -**Granting rights to new users** - -If a user needs rights for your organization, you are responsible for granting them. -For the smooth progress of a project, it is useful to handle such requests promptly. -Granting rights also doesn't have to be a lengthy task; rights can be granted in a minute. -You can learn exactly how this works in `Inviting New Users`_ and `Adjusting Existing Rights`_. - -.. tip:: Use a bookmark to go directly to the Management page. This way, you can give a user rights in no time. - - -Roles and rights -================= - -**User** - -For every project collaborator, internal or external, who needs access to the organization's private data. -These are only "read" rights, meaning this user cannot modify or add data. - -**Supplier** - -Project collaborators who need to modify or deliver data require "write" rights. -This falls under this role. -As a supplier, it is only possible to deliver and modify your own data, not that of other users (within the organization). -However, a user with only supplier rights can still view publicly available data. - -**Administrator** - -An administrator has both "read" and "write" rights. -This means the rights of User and Supplier come together in this role. -Additionally, with these rights, there is the ability to modify the delivered data of others. - -**Manager** - -The manager gives and takes rights from others. -A manager can also revoke the rights of another manager. -So, make sure to only give manager rights to trusted parties. - -.. tip:: In some situations, organizations arise for specific projects. - If the data within this project falls under your organization and you want to appoint a manager for this, - please contact the `servicedesk `_. - -The management screen -===================== - -The management screen offers the opportunity to manage various aspects of your organization. -This includes managing your data: rasters, scenarios, time series, and more. -For complete use of this page, refer to the `lizard documentation `_. -The most important thing in this case is "User Management". -Only managers have access to the "Users" screen. -In this screen, you can: - -1. Invite new users. -2. Manage invitations. -3. Adjust existing rights. - - -Inviting New Users ----------------------------- - -If a new user needs access to Lizard from the organization, this can be granted by the Manager. -This is done as follows: - -1. Log in to the organization's portal ({organization}.lizard.net). -2. Go to the user section in the management screen ({organization}.lizard.net/management/users). -3. Click on `+ NEW USER` at the top right of the screen (Image 1, in red). -4. Type the user's email in the 'email' field (Image 2). -5. Select the roles the user will have. For the rights associated with the roles, refer to `Roles and rights`_. -6. Click `SAVE`. -7. Success! The invitation has been sent and will be in the new user's mailbox within 5 minutes. - -.. tip:: Clicking on a role when inviting someone will also display the rights of each role on the left side of your screen. - -.. tip:: If the email does not appear in the inbox after 5 minutes, first check your spam folder. If the invitation is not there either, you can always contact the `servicedesk `_. - -.. figure:: /images/h_gebruiker_uitnodigen_1.png - :scale: 50% - :alt: Overview of the Lizard management page with multiple users. - - Image 1: An overview of the user section in the management screen of Lizard. - Here you can view existing rights and invite new users (red) or manage pending invitations (yellow). - -.. figure:: /images/h_gebruiker_uitnodigen_2.png - :scale: 50% - :alt: Invitation screen for new users of Lizard. Enter an email and select the roles for the new user. - - Image 2: The invitation screen for new users. You select the roles by clicking on them. - - - -Managing Invitations ---------------------- - -In the `Pending Invitations` screen, you can see which invitations you have sent that have not yet been accepted or expired. -Invitations expire by default within 15 days, but you can cancel them earlier by clicking on the 3 dots next to an email (Image 3). -If an email has not reached a user, you can also verify the email here. - -.. figure:: /images/h_pending_uitnodiging_1.png - :scale: 50% - :alt: Invitation screen for new users of Lizard. Enter an email and select the roles for the new user. - - Image 3: An overview of pending invitations. - - -Adjusting Existing Rights ---------------------------- - -In the user rights overview screen, you can manage the rights of existing users. -Here you see the following information of users who have rights for your organization: - -1. Username -2. Email -3. Roles - -.. figure:: /images/h_rechten_beheren_1.png - :scale: 50% - :alt: Overview of the Lizard management page with multiple users. - - Image 4: An overview of pending invitations. - -By clicking on the username of the respective user, you will be taken to this user's specific page. -Here, you can click on the roles you want to remove or add. -If a role is clearly colored, the user has these rights. - -.. figure:: /images/h_rechten_beheren_2.png - :scale: 50% - :alt: Roles of an individual user. - - Image 5: In this case, the user has 'User' and 'Manager' rights. - - -Tips -============= - -.. tip:: Ensure that rights are discussed and granted at the beginning of a project. - This prevents delays later due to someone waiting for their rights. - -.. tip:: Don't forget to remove users' rights after a project is completed. - This way, you actively maintain the user database and keep your data under control. - However, be sure to check if any scripts are running on an API KEY of any of these users. - -.. tip:: If you want to deactivate accounts, contact the `servicedesk `_. +:orphan: + +======== +Managers +======== + +What are the tasks of a Manager in an organization +================================================== + +The role of a manager is important for managing the data of an organization. +As a manager, you grant or revoke rights for your organization. +A manager mainly has two tasks: + +1. Maintaining the rights of existing users +2. Granting rights to new employees or external parties + +**Maintaining rights of existing users** + +The rights of users under your organization do not expire automatically. +So, it is important that you regularly check whether users still need their rights. +This can include employees leaving the organization or projects coming to an end. +Sometimes, not all rights need to be revoked, this is also possible. +It is up to you to determine how often you want to perform this check. + +**Granting rights to new users** + +If a user needs rights for your organization, you are responsible for granting them. +For the smooth progress of a project, it is useful to handle such requests promptly. +Granting rights also doesn't have to be a lengthy task; rights can be granted in a minute. +You can learn exactly how this works in `Inviting New Users`_ and `Adjusting Existing Rights`_. + +.. tip:: Use a bookmark to go directly to the Management page. This way, you can give a user rights in no time. + + +Roles and rights +================= + +**User** + +For every project collaborator, internal or external, who needs access to the organization's private data. +These are only "read" rights, meaning this user cannot modify or add data. + +**Supplier** + +Project collaborators who need to modify or deliver data require "write" rights. +This falls under this role. +As a supplier, it is only possible to deliver and modify your own data, not that of other users (within the organization). +However, a user with only supplier rights can still view publicly available data. + +**Administrator** + +An administrator has both "read" and "write" rights. +This means the rights of User and Supplier come together in this role. +Additionally, with these rights, there is the ability to modify the delivered data of others. + +**Manager** + +The manager gives and takes rights from others. +A manager can also revoke the rights of another manager. +So, make sure to only give manager rights to trusted parties. + +.. tip:: In some situations, organizations arise for specific projects. + If the data within this project falls under your organization and you want to appoint a manager for this, + please contact the `servicedesk `_. + +The management screen +===================== + +The management screen offers the opportunity to manage various aspects of your organization. +This includes managing your data: rasters, scenarios, time series, and more. +For complete use of this page, refer to the `lizard documentation `_. +The most important thing in this case is "User Management". +Only managers have access to the "Users" screen. +In this screen, you can: + +1. Invite new users. +2. Manage invitations. +3. Adjust existing rights. + + +Inviting New Users +---------------------------- + +If a new user needs access to Lizard from the organization, this can be granted by the Manager. +This is done as follows: + +1. Log in to the organization's portal ({organization}.lizard.net). +2. Go to the user section in the management screen ({organization}.lizard.net/management/users). +3. Click on `+ NEW USER` at the top right of the screen (Image 1, in red). +4. Type the user's email in the 'email' field (Image 2). +5. Select the roles the user will have. For the rights associated with the roles, refer to `Roles and rights`_. +6. Click `SAVE`. +7. Success! The invitation has been sent and will be in the new user's mailbox within 5 minutes. + +.. tip:: Clicking on a role when inviting someone will also display the rights of each role on the left side of your screen. + +.. tip:: If the email does not appear in the inbox after 5 minutes, first check your spam folder. If the invitation is not there either, you can always contact the `servicedesk `_. + +.. figure:: /images/h_gebruiker_uitnodigen_1.png + :scale: 50% + :alt: Overview of the Lizard management page with multiple users. + + Image 1: An overview of the user section in the management screen of Lizard. + Here you can view existing rights and invite new users (red) or manage pending invitations (yellow). + +.. figure:: /images/h_gebruiker_uitnodigen_2.png + :scale: 50% + :alt: Invitation screen for new users of Lizard. Enter an email and select the roles for the new user. + + Image 2: The invitation screen for new users. You select the roles by clicking on them. + + + +Managing Invitations +--------------------- + +In the `Pending Invitations` screen, you can see which invitations you have sent that have not yet been accepted or expired. +Invitations expire by default within 15 days, but you can cancel them earlier by clicking on the 3 dots next to an email (Image 3). +If an email has not reached a user, you can also verify the email here. + +.. figure:: /images/h_pending_uitnodiging_1.png + :scale: 50% + :alt: Invitation screen for new users of Lizard. Enter an email and select the roles for the new user. + + Image 3: An overview of pending invitations. + + +Adjusting Existing Rights +--------------------------- + +In the user rights overview screen, you can manage the rights of existing users. +Here you see the following information of users who have rights for your organization: + +1. Username +2. Email +3. Roles + +.. figure:: /images/h_rechten_beheren_1.png + :scale: 50% + :alt: Overview of the Lizard management page with multiple users. + + Image 4: An overview of pending invitations. + +By clicking on the username of the respective user, you will be taken to this user's specific page. +Here, you can click on the roles you want to remove or add. +If a role is clearly colored, the user has these rights. + +.. figure:: /images/h_rechten_beheren_2.png + :scale: 50% + :alt: Roles of an individual user. + + Image 5: In this case, the user has 'User' and 'Manager' rights. + + +Tips +============= + +.. tip:: Ensure that rights are discussed and granted at the beginning of a project. + This prevents delays later due to someone waiting for their rights. + +.. tip:: Don't forget to remove users' rights after a project is completed. + This way, you actively maintain the user database and keep your data under control. + However, be sure to check if any scripts are running on an API KEY of any of these users. + +.. tip:: If you want to deactivate accounts, contact the `servicedesk `_. diff --git a/source/index.rst b/source/index.rst index 00e03a5..9afaae4 100644 --- a/source/index.rst +++ b/source/index.rst @@ -7,70 +7,46 @@ Welcome to the Lizard documentation! .. toctree:: :maxdepth: 1 - :caption: Introduction - :name: Introduction + :caption: Getting Started + :name: Getting Started with Lizard - a_lizard - a_homepage - a_releasenotes + a_user_interfaces + a_tutorials + a_geoblocks .. toctree:: - :maxdepth: 2 - :caption: Authorisation and Authentication - :name: Authentication, Authorisation and User Management + :maxdepth: 1 + :caption: User Manuals + :name: User Manuals - b_usermanagement + b_catalogue + b_viewer + b_management + b_apps + b_lizardplugin .. toctree:: - :maxdepth: 2 - :caption: Data Management - :name: Data Management + :maxdepth: 1 + :caption: API + :name: Lizard API - c_general - c_rasters - c_wms - c_layercollections - c_timeseries - c_scenarios - c_labels + c_introduction + c_endpoints .. toctree:: - :maxdepth: 2 - :caption: Data Exchange - :name: Data Exchange + :maxdepth: 1 + :caption: Support + :name: Support - d_datatypes - d_general - c_apifunctional - d_apitechnical - d_apitutorials - d_qgisplugin + d_authentication_user_management + d_faq + d_self_service_portal .. toctree:: - :maxdepth: 2 - :caption: Visualisation - :name: Visualisation - - e_viewer - e_dashboard - e_catalog - e_lizardwms - -.. toctree:: - :maxdepth: 2 - :caption: Advanced Analysis - :name: Advanced Analysis - - f_geoblocks - f_alarms - - - -.. toctree:: - :maxdepth: 2 - :caption: Service and Support - :name: Service and Support + :maxdepth: 1 + :caption: Release Notes + :name: Release Notes - g_servicesupport + e_release_notes \ No newline at end of file