Project wildlifenl is the backend API for the WildlifeNL system.
A specific instance of an animal. For example: that one horse. Usually this implies that the animal in question carries an animal-borne sensor for unique identifaction.
A possible answer for a question (choice).
A record associating Borne-Sensor-Reading records with an Animal, having a start and end timestamp to match records of type Borne-Sensor-Reading with the correct Borne-Sensor-Deployment.
A timestamped reading from an animal borne sensor including its location (latitude/longitude), type and values. Note that Borne-Sensor-Reading is weakly linked (using a corresponding sensorID) to Borne-Sensor-Deployment because it resides in another database.
The record of a message being sent to a user. A Conveyance is the result of an Encounter or a given Response.
A timestamped record of the location of a member of a specified animal species.
A collection of Questionnaires and Messages with a start date and end date, that together make up a research experiment.
The report from a user about having had a human-wildlife interaction.
The type of the interaction, for example a sighting, damage report or an animal-vehicle collision.
A question that was asked the user upon registering an interaction.
A predefined group of questions that a user should answer upon registering an interaction of a certain Interaction-Type. As soon as any of its questions has an associated Response record, the questionnaire can no longer be changed. A Questionnaire can be deactivated when it is no longer needed to deploy it, and a new questionnaire can be created for the new situation.
A place in the world designated as a nature area.
A piece of information to send to the user upon certain conditions. As soon as a message has an associated Conveyance record, it can no longer be changed. A Message can be deactivated when it is no longer needed to send it, and a new Message can be created for the new situation.
The answer the user gave to the question. If the Question has associated possible Answer records, the response must refer to one of the Answer records of the question.
An authorization record for a set of functionalities. A user having a certain role is authorized to call the functionalities assigned to that role.
A record associating Sensor-Reading records with a LivingLab, including the most recent data. Only readings that have a timestamp between StartTimestamp and EndTimestamp are considered valid readings for this installation, and EndTimestamp can be empty. Note that SensorID is weakly linked to the SensorID of Sensor-Reading.
A timestamped reading from a sensor including its location (latitude/longitude), type and value. Note that SensorID is weakly linked to the SensorID of Sensor-Installation.
The definition for a group of animals (for example: horses), having a field that defines the encounter distance in meters and encounter time in minutes.
A timestamped record of the location a user. Note that Tracking-Reading is weakly linked (using a corresponding userID) to User because it resides in another database.
A human user of any role. The Role records associated with the user authorize him/her to more functionality. A user can also have no associated Role records, which referes to the most prohibited user types (Recreationist, Inhabitant). User also optionally includes the most recent tracked location.
A circular area in the world with a central postion (latitude/longitude) and radius in meters1, that is of interest to a user, for example including agriculture fields or a gardens.
The blue entities are stored in a relational database, whereas the green entities are stored in a timeseries database. As a result the relationships between blue and green entities are "by convention" of having the same IDs rather than them being enforced by any rules. For Sensor-Reading and Borne-Sensor-Reading this brings an advantage in the cases where data is ingested from external automated systems as it is therefore possible to accept and store these data, regardless of there being a way to use and retreive them in a meaningful context (even if there are no Sensor-Installation or Borne-Sensor-Deployment with the referenced ID), subsequently allowing that the installation or deployment that adds meaning be added later, rather than rejecting these data for the reason of there being no meaningful context, and perhaps make external automated systems fail. Note that this advantage is not needed for Tracking-Reading as it is highly unlikely for a new reading to refer to a userID that is unknown.
Blue entities with a red border are created internally as a result of logic (see below) and are therefore de facto read-only.
Some end-points have interal logic that does more than just serve the end-point result.
Upon a new Interaction being posted, it should be checked whether a Questionnaire exists that is accociated with the InteractionType of the newly posted Interaction, that is associated with a non-ended Experiment, and if that Experiment is bound to a specific LivingLab the newly posted Interaction should be within that LivingLab. If so, this Questionnaire should be in the response body of the post request. If multiple Questionnaires qualify, a random single one is chosen as to not overload the end-user.
Upon a new Interaction being posted, including lat/long, it should be checked whether its type is 'Sighting'. If so, it should be checked whether a Zone exits that is associated with the Species of this interaction, and that has a spatiotemperal overlap2 with this Interaction. If so, a new Alarm must be created being associated with the Zone in question and linked to this Interaction.
Upon a new Detection being posted, including lat/long, it should be checked whether a Zone exits that is associated with the Species of this detection and that has a spatiotemperal overlap2 with this Detection. If so, a new Alarm must be created being associated with the Zone in question and linked to this Detection.
Upon a new Borne-Sensor-Reading being posted, including lat/long, it should be checked whether a Borne-Sensor-Deployment exists for this reading, if so the location of the associated Animal should be updated. Then, it should be checked whether a Zone exits that is associated with the Species of this animal, and that has a spatiotemperal overlap2 with this Animal. If so, a new Alarm must be created being associated with the Zone in question and linked to the Animal that the Borne-Sensor-Deployment refers to.
Upon a new Response being posted, it should be checked whether this response refers to an Answer. If so, it should be checked whether a Message exists, in non-ended Experiment, that is associated with the same Answer. If the Experiment has an association with a LivingLab, the Interaction that is associated with the Response must have a spatiotemperal overlap2 with this LivingLab. If so, a new Conveyance must be created referring to that Message and associated with the Response and NOT with an Animal and NOT with an Alarms. The Conveyance and its Message should be in the response body of the post request. If multiple Messages qualify, a random single one is chosen as to not overload the end-user.
Upon a new Tracking-Reading being posted, including lat/long, it should be checked whether there is an Animal, having a Species for which there a Message exists, in a non-ended Experiment, that has spatiotemperal overlap2, within the margins as specified by this Message, with this Tracking-Reading. If the Experiment has an association with a LivingLab, the Tracking-Reading must have a spatiotemperal overlap2 with this LivingLab. Then, a new Conveyance must be created referring to that Message and associated with Animal and NOT with a Response and NOT with Alarm. The Conveyance and its Message should be in the response body of the post request. If multiple Messages qualify, a random single one is chosen as to not overload the end-user.
Whenever a new Alarm is created it should be checked whether a Message exists with trigger type alarm that is for the same Species as the animal that triggered the alarm. If the Message is associated with an Experiment that is bound by a LivingLab there should be a spetiotemperal overlap2 between the Zone that the alarm is for and this LivingLab. If so, a new Conveyance must be created that referring to that Message and is associated with the Alarm and NOT with an Animal, and NOT with a Response. Any Conveyance instances that are created this way and their Message should be in the response body of the post request.
Footnotes
-
To calculate distances in meters between two points as given in latitude and longitude the conversion 1 meter = 0.00001 degree (either latitude or longitude) is used. This produces a small difference with reality as 1 degree latitude in reality is about 110 km and 1 degree longitude in reality is about 111 km on the equator and reaches zero at the poles, but this simplified conversion greatly increases calculation speeds as the problem can then be expressed in euclidean distance. ↩
-
A spatiotemporal overlap means that both the distance as well as the timestamps of the location measurements of two different entities are below a predefined threshold. In other words: They were close to eachother at roughly the same moment in time. ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7