Introduction of data and concepts: How the different options influence impact of submitted annotation data by different API key accounts (which are identified by Open311_API_ID).
Open311_API_ID (API-ID) indicates which API user account used its active CitobsDB API key for an information submission (observation, annotation of earlier observations, monitoring site or interest definition, control of actions). The API-ID can be assigned different privileges, for example automatically accepted observation curation suggestions. As a certain API key is used only in certain submission form installations, the users having access to these installations are then entitled to these privileged actions.
Privileges are defined as increasing levels of abilities (PRL_#, e. g. PRL_2 for enabling definition of a monitoring site with associated monitoring interest functionalities and chains of action). The main PRL setting for the API key / API-ID can additionally be used as priority level setting: Data submitted with higher priority is prioritized over lower priority data - last entries replace older ones (with same pseudonyme) and identified entries can be ranked above anonymous ones. Lower priority entries are considered merely suggestions before (and correction suggestions after) priority API ID decisions.
Systems which are managing activities at the same levels (e. g. organizing different types of activities at local monitoring sites - for example for different campaigns) can have different rankings of priority. They have same privilege level (e. g. PRL_4 -> 4 (integer) for both services A and B, which both allow users to annotate quality of other observations) but they can have different priority increments, which are positive floating point numbers which are less than 1 (e. g. A:0.1 and B:0.2). In the example case system A would have ranking 4.1 and B 4.2, thus priorized annotated suggestions for curation (e. g. rejection of observation as invalid or confirming it as valid) come from B, if there are suggestions from A and B for the same observation. However, increments will never provide the next level privileges, in this example the system C with PRL_5 (right to decide and select final curation action) will be needed. Automated curation processes (e.g. to change status of an observation) wait for PRL_5 entries: If users of system C confirm a suggestion by system A, or submits an annotation entry of its own with system C PRL_5 priority, this option is executed. Suggested annotations by A and B will never be put to action without the PRL_5 decision, as they are of PRL_4 (even if their inputs are ranked as B first).
Privileges can be defined as a selection too. By default, all privileges at and below the defined priority level are available for the system with this API key account, and the automated processes at platform will perform accordingly as they interpret inputs with different Open311_API_ID. And by default, none of the inputs for processes requiring higher PRL levels should be considered valid suggestions. In fact, if an activity is annotated to require a certain privilege, and submitting API-ID is not allowed to suggest such an input, it can be automatically marked as not valid input - or the submission might even not be allowed by a client service or future versions of the Citobs palatform. The privileges can be defined as a selection, from a multivalue list of PRLs. Such selection can include privileges which are higher than current API priority, and these are considered suggestions. As these suggestions remain in open data, systems, services and even users of datasets can react to them, even if automated actions are not implemented by the Citobs platform.
Privileges and priorities can be grouped for example for certain actions: General (default group) priorities and privileges could be replaced by special submission priorities and privileges. Systems utilizing the platform data can take account of pre-set list of groups (submission of different data types, curation based on annotation submissions for earlier inputs, campaign management, contracting/acknowledging of participants and participation, definition of systems and services) or they can be specially defined. API key account type definition can be used with this grouping to decide if for a certain system TL-API (API keys used in most secure systems) is required or if I-API is sufficient (API keys which are used outside secure server installations) - and what weight or special actions are done on for example Q-API (e. g. demonstration keys and systems under construction) or F-API (systems known to have quality issues on submitted data)
Privileges can be defined by Citobs platform client API key accounts, and this open definition of privileges and priorities should be the only method of such definitions at least in between different organizations and systems (services in systems might have separate subsidiary methods implemented for technical reasons). API key accounts without specially defined priority and privilege have a PRL_0 if they are active, and naturally no privileges except viewing open data if the API-ID is inactive / deactivated. Typical client systems for submitting Earth observation (EO) related information have PRL_1 and client system management has management API key account for their internal and customer actions and controls at PRL_8 to PRL_12. If a client system would contract their individual customers for dedicated actions (e. g. to acquire new or reprocessed EO data, an action which could result in costs or compensations for activities) they are typically assigned PRL_16 or up to PRL_18.
Assigning general privileges to other API key accounts (Open311_API_ID) requires level PRL_18 privileges. Typically PRL_19 is the highest privilege level available for Citobs platform client system API key accounts of an organization. PRL_20 is for limited cases available for coordinators of multiple client organizations, typically privileges over PRL_19 are for Citobs platform maintenance and management only.
This form is for information and introduction only, it is not possible to assign priviledges here.
Detailed instructions will be made available later
Publicly available submission forms will be made available later
This form is generally published in open domain.
SYKE CitobsDB terms of use for annotation data:
api_privileges_general_service_code_en_202206071516241 / CC4.0-BY SYKE, CitobsDB kansalaishavainnot.fi
CSEPIN määrittelyiden ilmoituspalvelu / CSEPIN definitions service description:
https://rajapinnat.ymparisto.fi/api/kansalaishavainnot/1.0/services.json?extension=true&service_code=api_privileges_general_service_code_en_202206071516241
CSEPIN määrittelyiden aineisto / CSEPIN definitions data:
https://rajapinnat.ymparisto.fi/api/kansalaishavainnot/1.0/requests.json?start_date=1999-12-31T00:00:00Z&end_date=2027-06-24T00:00:00Z&status=open&extension=true&service_code=api_privileges_general_service_code_en_202206071516241
Request for managing API key account with higher priority and privilege settings:
havaitsemaan@syke.fi