Purpose

This document puts forward a proposed use of annotations in our system. Once we decide on the structure, the requirements document will be updated accordingly.

Revision History

Name	Date	Reason for Change	Version
Annotations Use	November 12th, 2023	Initial ideas for how to use annotations	0.0
Using Annotation Services	November 15th, 2023	Document revised after some feedback by the instructor	0.1
Marked as Obscene	December 19th, 2023	A final design and implementation decision has been made

Comments of essential importance on Version 0.1

• Use of third party annotation services is imposed

• Our database should only store annotation links for our objects, not the annotation data itself

Use of Annotations

We will have annotations produced by

• user entry
• automatic data definition

Annotations by user entry

User functionality perspective

The system will support users to annotate on activities. Any user shall be able to "annotate on" activities (i.e. needs, resources, actions, events, emergencies) Annotations will be of type:

• URLs
• Image/photo uploads
• Text notes

The user interface will provide a pop-up like functionality so that the user will be able to type and enter the values.

From the user perspective annotating any event will be one step (optionally including URL, image end text note) but the system will store 3 annotation records.

Data perspective

Annotations will persist on the system database in records of: Data fields referencing the system records Resulting annotation in json format string.

Annotations will be stored by their URL to the public service entry

The backend will serve URLs in given structure with json structured annotation content. The URL structure will be <root server address>/Annotation/<system-record-id> eg. https://disasterresponse.org/Annotation/6564b3db342a6600d56d3ad2

The backend will serve URLs to the related annotation, with API called by object id

The URL structure will be

<root server address>/Annotation/<activitytype>/<system-record-id>

eg. https://disasterresponse.org/Annotation/needs/6564b3db342a6600d56d3ad2

Backend APIs

API functions will be:

/POST/annotations/need/6564b3db342a6600d56d3ad2

Creates annotations for need for given ID, body providing annotation data. (URL, note, image)

/DELETE/annotations/need/6564b3db342a6600d56d3ad2

Deletes the annotations for the need for given ID.

/DELETE/annotations/b3db342a6600d56d3eb26564

Deletes the annotation record with given ID (ID is the system _id for the annotation). Will only delete the specific annotation other annotations for the related activity will perceive.

/GET/annotations/need/6564b3db342a6600d56d3ad2

Retreives the annotations for need for given ID (annotation URLs on the public service)

/GET/annotations/b3db342a6600d56d3eb26564

Retreives the annotation with given ID (annotation URLs on the public service)

/PATCH/annotations/b3db342a6600d56d3eb26564

Updates the annotation with given ID. Body providing the annotation data (The annotation's type should be same as the provided data)

User details

Users and guests shall be able to annotate

Authorized users shall be able to delete the annotations created by themselves.

Users with specific roles shall be able to delete or update the annotations. (Update will change the username of the annotation to the updating user)

Authorized users shall be able to see the annotations.

To be clear: UI functionalities

On the mobile and frontend, all UI about activities should provide "annotate on" and "see annotations" functions.

Annotations should not be embedded in the activity record screens.

This part is discarded for the sake of having a final product on time.

Automatic annotations

For needs and resources, on creation and update of specific fields the system will create automatic annotations for the activity.

Automatic annotations are discarded in 0.1 version of this document.