Administrative settings¶

The project administration interface provides tools for configuring an OpenBioMaps project, managing its users and data structures, and monitoring project-related services. The pages available to an administrator depend on the administrator’s permissions, the project configuration, the installed modules, and the server environment.

This page provides an overview of the administrative settings and tools. Some settings affect access to project data or modify the underlying database. Administrators should therefore review changes carefully and test them before applying them to a production project.

For an overview of the project administration documentation, see Project administration.

Administrative access¶

The Administrative access section allows project administrators to delegate individual administrative functions to user groups. Each function available through the project administration interface can be assigned to one or more groups.

This provides fine-grained control over who can perform administrative tasks. For example, a project could define the following groups:

User managers, with access to user and group management;
Data curators, with access to species names, attachments, and data management tools; and
Upload form editors, with access to upload form management.

Grant only the permissions required for each administrative role. Functions that change database structures, execute SQL, manage access rules, or edit executable code should be restricted to trusted administrators.

Database tables and columns¶

The Database tables and columns section is used to create and manage the SQL tables, views, and columns associated with a project. Objects registered through this interface are added to the OpenBioMaps metadata and can therefore be made available to upload forms, queries, modules, and other OpenBioMaps interfaces.

Tables and columns created directly through a standard SQL client are not registered automatically. They must also be added to the relevant OpenBioMaps metadata before they can be used through the web application.

Naming tables and columns¶

Use lowercase letters, numbers, and underscores for table and column names. Avoid spaces, accented characters, quoted identifiers, and other special characters. Names should be descriptive and should remain stable after forms, queries, or modules begin using them.

A description should be provided whenever a table or column is created. These descriptions form part of the project’s metadata and help users understand the meaning and intended use of the data.

Registering available columns¶

Administrators can select which columns are available when creating upload forms and query interfaces. A column that exists in PostgreSQL but is not registered as available will not automatically appear in these interfaces.

Columns can also be assigned semantic roles. These roles allow OpenBioMaps and its modules to identify important fields without relying on a project-specific column name. Depending on the project and installed modules, roles may identify fields containing:

a scientific name;
an alternative taxon name;
an observation date;
a data collector;
a location or geometry;
a count of individuals;
latitude and longitude values;
a citation; or
an attachment.

Column types¶

The administrative interface provides the following documented column types or semantic roles:

Data: A general-purpose data column.
Spatial Geometry: A geometry column used for maps and spatial operations.
Scientific Species Name: A scientific-name column used by taxon-management functions.
Alternative Names: An alternative-name column used by taxon-management functions.
Date: A date or date-time column used by date filters.
Number of Individuals: A numeric column used by summary functions.
Latitude/Longitude: A coordinate column used to create spatial geometry.
Citing: A citation-related column used by summary functions.
Attachment: A column that refers to uploaded file attachments.
UTM Zone: A UTM-zone column used when spatial geometry is created from coordinates.

Column descriptions and commands¶

The Comment field contains a description of the column’s contents. Adding a meaningful description is recommended because it contributes to the project’s metadata.

The Command field can be used to perform specific operations or assign settings to a column. The documented commands include:

SET srid:4326: Assign SRID 4326 to the obm_geometry column. Replace 4326 with the spatial reference identifier required by the project.
SET use_rules:1: Enable access-rule handling for the obm_id column.
RENAME:new_name: Rename a column to new_name.
DROP: Delete the column.

Renaming or deleting a column can invalidate upload forms, query templates, modules, views, triggers, and external applications that refer to it. Update all dependent configuration before performing either operation, and create a database backup when appropriate.

SQL console¶

An SQL console is also available to system administrators. The SQL console can be used to modify or delete project data and database structures. For this reason, access (to the database tables interface) should only be granted to trusted users who have sufficient experience with PostgreSQL and OpenBioMaps system administration tasks.

Queries executed in the SQL console can be saved and re-run.

The console displays the query results in a dynamic table. The results of the query table can be exported as a CSV file. If the query results contain more than 1,000 rows, the table is no longer displayed; instead, a CSV export is automatically generated.

Managing views¶

A data table can be replaced by a view to provide a customised representation of its data or to improve a specific workflow. The documented process creates a schema with the same name as the original table, moves the original table into that schema, and creates a view in its previous location. Corresponding INSERT, UPDATE, and DELETE rules provide write operations where configured.

This approach may be useful for large tables affected by expensive workflows or triggers. It changes the database structure substantially and can affect forms, queries, modules, foreign keys, triggers, backups, and external clients.

Data access¶

The Data access section summarises the project’s access configuration and the current state of row-level access rules. Administrators can inspect the read and modification levels applied to the project and its managed data tables.

The interface includes:

the configured levels for reading and modifying data;
the status of access restrictions for individual data tables;
controls for enabling or disabling configured restrictions;
the status of triggers used to maintain access rules; and
links to related documentation.

The documented access levels are:

everybody: Access is not restricted to authenticated users.
logged-in users: Access requires authentication.
specified group members: Access is controlled through project groups and more specific rules.

The effective access to a record may be affected by project-level, row-level, and column-level rules. For a detailed overview, see Data access.

The interface is available through Profile > Project administration > Data access. Some underlying defaults may also be defined in the project’s local_vars.php.inc configuration file.

Groups¶

The Groups section allows administrators to create and manage groups of project users. Groups are used to assign access to data, upload forms, modules, and administrative functions.

Administrators can:

create a group;
add users to or remove users from a group;
add groups to other groups where nested groups are supported; and
use the resulting groups in other access-management interfaces.

Nested groups can provide a reusable and scalable permission structure. They should nevertheless be kept simple enough that administrators can determine the effective permissions of an individual user.

Upload forms¶

Upload forms determine how data can be entered or imported into project tables. They define the available fields, input controls, validation rules, and access settings for a data-collection workflow.

For detailed instructions, see Upload form management.

Functions¶

The Functions section provides tools for reviewing SQL rules and triggers associated with project tables and views. It includes separate lists of the rules and triggers registered for each table and provides templates for selected trigger functions.

The interface can create, edit, enable, or disable the following documented trigger types:

taxon-list triggers;
history triggers; and
access-rules triggers.

Furthermore, custom triggers and rules can also be created and configured here.

Database triggers execute automatically when data change. An incorrect trigger can reject valid changes, modify data unexpectedly, or weaken access control. Test customised trigger functions before enabling them in a production project.

Taxon-list trigger¶

The taxon-list trigger inserts previously unknown scientific names from a configured species-name field into the project’s taxon table. This can help maintain a project whose species list expands as observations are added.

The species names added to the taxon table can now be maintained via the taxon name management interface.

Administrative settings: species names

History trigger¶

The history trigger records changes made to records in the target table. The resulting history can be displayed through the record’s data-history interface.

Access-rules trigger¶

The access-rules trigger maintains row-level access rules for records in a project table. It can derive restrictions from a configured sensitivity field and can transfer read and write permissions from the upload form used to create a record.

For example, if an upload form grants read access to groups A and B and write access to group C, the trigger can add those assignments to the rules-table entry associated with each record created through that form.

This trigger is relevant to projects that use group-level or row-level access restrictions. Its configuration must be consistent with the project’s general access settings and rules-table schema.

For more information, see Data access.

Species names¶

The Species names section manages the project’s taxon table. Species names can be assigned to the following documented categories:

accepted name;
synonym;
common name; and
misspelled name.

Names stored in the taxon table are used by taxon-related search interfaces and by background jobs that detect or repair taxon names.

Translations¶

OpenBioMaps uses global and project-specific translations.

Global translations¶

Global translations can be added and improved through the OpenBioMaps translation platform. The platform contains translations for the web application, mobile applications, and other OpenBioMaps components. Contributors can also propose a new language.

Local translations¶

Local translations allow a project to define project-specific interface text. Translation keys use the str_ prefix followed by a descriptive English identifier. For example, a project could define str_observations and provide its translation in each active language.

A public example is available at:

https://openbiomaps.org/projects/checkitout/upload/?form=426&type=web

Modules¶

Modules extend the functionality available in an OpenBioMaps project. Their configuration and access requirements depend on the individual module.

Modules extend the functionality available in an OpenBioMaps project. Their configuration and access requirements depend on the individual module. Modules often provide basic functions, such as text search interfaces on the map page; in other cases, they provide tools specific to certain tasks. The behaviour of modules can often be customised.

For more information, see Modules.

Interrupted uploads¶

The Interrupted uploads section lists saved or unfinished file uploads and web-form data-entry sessions. Depending on their state, an interrupted upload can be restored or discarded.

Administrators should verify that an upload is no longer required before deleting it. An interrupted upload may contain work that its owner intends to resume.

File manager¶

The File manager section provides tools for managing attachments uploaded to the project. It can be used to browse attachments, review their associations with database records, and create exports.

The documented functions include:

listing uploaded attachments;
filtering and sorting attachments;
editing file comments;
linking attachments to data records;
managing existing file associations; and
exporting the attachments associated with a data table.

A bulk export is processed as a background job. When processing has finished, the system provides a link for downloading the resulting archive.

Access to attachment management and export functions should be limited to authorised users. Exported files remain subject to the project’s data-access and privacy requirements.

SQL query settings¶

The SQL query settings section defines the templates used to assemble queries for MapServer layers and for textual query results in the web application. These templates resemble SQL but include OpenBioMaps placeholders that are replaced dynamically by the query interpreter.

Each query template should be connected to a web-map layer. In a MapServer mapfile, a WMS layer that uses a dynamically generated query must contain a DATA definition with the %query% placeholder.

Query templates can contain placeholders delimited by percent signs. Core functions and installed modules may replace these placeholders with SQL fragments at runtime.

Basic query template¶

A query template may use placeholders such as %qstr% for query conditions and %morefilter% for additional filters:

SELECT obm_id, %grid_geometry% AS obm_geometry
    %selected%
FROM %F%checkitout c%F%
    %uploading_join%
    %rules_join%
    %taxon_join%
    %grid_join%
    %search_join%
    %morefilter%
WHERE %geometry_type% %envelope% %qstr%

The %F% markers identify the primary FROM relation and its alias so that the interpreter can split and extend the template.

Adding joins¶

Additional joins can be enclosed in %J% markers:

SELECT
    n.obm_geometry,
    n.obm_id,
    -2 AS date_part,
    nestbox_type,
    project_id,
    beinaction
    %selected%
FROM %F%public_nestbox_data n%F%
    %J%LEFT JOIN public_nestbox_data_observations o
        ON o.nestbox_id = n.obm_id%J%
    %taxon_join%
    %morefilter%
WHERE %envelope% %qstr%

Complex query templates¶

Templates can also use common table expressions and other SQL constructs:

WITH aall AS (
    SELECT
        o.obm_id,
        n.obm_geometry,
        nestbox_type,
        project_id,
        beinaction,
        COALESCE(
            EXTRACT(DAY FROM (CURRENT_DATE - datum)::interval),
            '-1'
        ) AS date_part
        %selected%
    FROM %F%public_nestbox_data_observations o%F%
        %J%LEFT JOIN public_nestbox_data n
            ON nestbox_id = n.obm_id%J%
        %taxon_join%
        %morefilter%
    WHERE 1 = 1 %envelope% %qstr%
)
SELECT *
FROM aall
ORDER BY date_part DESC

A typical simple template has the following form:

SELECT obm_id, obm_geometry %selected%
FROM %F%checkitout c%F%
    %uploading_join%
    %rules_join%
    %taxon_join%
    %morefilter%
WHERE %geometry_type% %envelope% %qstr%

Query templates affect both correctness and data access. An incorrect join or missing access-rule placeholder may expose records or fields that should be restricted. Test each query as public, authenticated, and group-specific users before making it available.

Map settings¶

The Map settings section configures spatial layers in the web map and their corresponding MapServer definitions. The web-map and MapServer settings must remain consistent so that layers use the intended data source, projection, extent, and style.

Web-map layers¶

The web-map settings configure the OpenLayers-based map interface. Administrators can define settings such as:

the initial map centre and zoom level;
the available base maps and overlay layers;
which layers are visible by default;
the association between layers, project tables, and query templates; and
selected aspects of layer appearance and behaviour.

MapServer settings¶

Advanced administrators can edit the project’s raw MapServer mapfile. The mapfile defines layer data sources, spatial reference systems, extents, styles, and rendering options.

Changes to a mapfile can make project layers unavailable or expose an unintended data source. Preserve a working version and validate the edited mapfile before deploying changes.

Spatial reference systems¶

Map layers must use correctly defined spatial reference systems. The configured SRID determines how coordinates are interpreted and transformed when data from different sources are displayed together.

The map extent and projection settings control the area and coordinate system displayed by the web map. They must be compatible with the layer data, MapServer configuration, and OpenLayers settings.

Members¶

The Members section lists the users registered in the project. Administrators can manage project membership, status, and group assignments.

The documented member statuses are:

Normal: The user receives the project’s standard upload and query permissions. More specific group assignments and access rules may modify these permissions.
Operator: The user has access to all project functions and data.
Suspended: The user cannot access project functions or data. Suspending a user is similar to disabling their project membership but does not delete their profile.

The project founder has full project access and does not need to be assigned the operator status. Group assignments can be changed on this page, although the Groups interface may be more convenient for managing several users.

For related settings, see Groups and Administrative access.

Viewing another user’s profile¶

A member’s name links to their profile page. Administrators with the required permission may see a user-secret icon in the upper-right area of the page. This function opens another user’s profile while the administrator remains authenticated with their own account.

The icon used by the interface is documented by Fork Awesome.

This feature can expose personal information and user-specific content. Access should be restricted and its use should follow the project’s privacy and auditing policies.

Message templates¶

The message template editor is currently unavailable.

Messages sent automatically by the system or a project are generated from templates. OpenBioMaps provides global templates for implemented message types, and a project can create local versions that override them.

To customise a global template, select it, edit its contents, and save it as a local version. Templates may contain variables that are replaced when the message is sent. The variables supported by an individual template are defined by the function, module, or background job that sends it.

New templates can also be created for custom modules and background jobs.

Variables and included templates¶

Variables are written between percent signs, for example %USER_NAME%. The following global variables are documented:

%PROJECT_TABLE%: The project’s database identifier or table name.
%PROJECT_TITLE%: The project’s short description.
%PROJECT_DESCRIPTION%: The project’s long description.
%USER_NAME%: The name of the recipient or relevant user.
%URL%: A URL associated with the message.
%OB_DOMAIN%: The OpenBioMaps domain associated with the message.
%DOMAIN%: The domain name defined in the projects table.
%PROTOCOL%: The protocol defined in the projects table.

One template can include another template. For example, appending @footer@ includes the template named footer.

Predefined templates¶

The documented user-related templates are:

welcome_to: Welcomes a user to the project.
change_email_address: Sends a confirmation link for changing a user’s email address.
dropmyaccount: Confirms a request to delete an account.
create_new_project: Confirms the creation of a project.
invitation: Sends an invitation to join a project.
invitation_accomplished: Reports that an invitation has been accepted.
invitation_request: Notifies administrators about a request for an invitation.
lostpw: Supports password recovery.

The documented general-purpose templates are:

new_gitlab_issue: Contains a copy of a submitted bug report.
new_shared_polygon: Announces a newly shared polygon.
new_upload_news: Announces a new upload in the project news.
new_upload_report: Notifies administrators about a new upload.
footer: Provides a general message footer.
interconnect_request: Supports an interconnection request.

The documented evaluation-notification templates are:

data_evaluation_commenters: Notifies previous commenters when a record receives a new comment.
data_evaluation_owner: Notifies the owner when a record they uploaded receives a comment.
upload_evaluation_commenters: Notifies previous commenters when an upload receives a new comment.
upload_evaluation_owner: Notifies the owner when their upload receives a comment.
user_evaluation_commenters: Notifies previous commenters when a user receives a new comment.
user_evaluation_owner: Notifies a user when they receive a comment.

The documented module-related templates are:

dlr_new_request: Notifies project administrators about a new download request. The documented variables are username, requestid, and request_message.
dlr_request_registered: Confirms to a user that their download request has been registered.
incomplete_list_processed: Reports that an incomplete list has been processed.
incomplete_list_unprocessed: Reports that an incomplete list could not be processed.

Server info¶

The Server info section displays selected information about the OpenBioMaps server and the resources used by the project. Depending on the server configuration, it may include:

the installed OpenBioMaps application version;
disk usage by project files, attachments, and uploads;
load averages for the previous 1, 5, and 15 minutes;
server load normalised by the number of CPU cores;
available memory; and
a link to the Supervisor administration interface.

These values can help administrators identify resource constraints and provide diagnostic information to server operators. Access to detailed server information should be restricted because version and infrastructure details may be security-sensitive.

Server logs¶

The Server logs section provides access to logs made available by the server configuration. The documented sources include:

application or system logs;
MapServer logs;
background-job events; and
background-job errors.

The interface may provide filtering, searching. Logs can contain usernames, record identifiers, query details, file paths, request parameters, or other sensitive information. Access and retention should follow the server’s security and privacy policies.

Background job settings¶

Background jobs allow a project to execute scheduled or manually initiated tasks without continuous user interaction. They can be used for operations such as:

maintaining species-name data;
validating records;
importing or exporting data;
cleaning temporary tables;
running analyses; and
refreshing materialised views.

A background job is a standalone program. OpenBioMaps jobs are commonly written in PHP, but the server may also support programs written in Python, R, Bash, or another installed language.

The administration interface can be used to:

install predefined jobs from a central Git repository;
upload a project-specific job;
review installed jobs;
configure job parameters and schedules;
enable or disable jobs;
start a job manually;
inspect recent output and execution status; and
edit job source code where this function is enabled.

Detailed logs are available through the Server logs section.

Editing or uploading a job is equivalent to installing executable code on the server. These functions must be restricted to trusted administrators, and custom jobs should be reviewed for command injection, unsafe file access, credential exposure, and excessive resource use.

For more information, see Jobs.

Scheduling jobs¶

The server’s system-level scheduler must first be configured. In a Docker installation, this is typically a cron process on the host. It periodically invokes the scheduler for the project, which starts any jobs that are due.

Before scheduling a newly installed or modified job:

review its configuration and source;
use Run to execute it manually;
wait for the execution to finish;
inspect its result and logs; and
configure the recurring schedule only after the test succeeds.

The project scheduler uses cron-like minute, hour, and day fields. An asterisk means every valid value in the corresponding field.

System-level Docker example¶

The following example invokes a project’s scheduler from the host:

*/5 * * * * /usr/local/bin/docker-compose -f /srv/docker/openbiomaps/docker-compose.yml exec -u www-data -T app php /var/www/html/biomaps/root-site/projects/myproject/jobs.php

Replace the Compose file, service, project path, and execution user with values appropriate for the installation.

Project description¶

The Project description section defines the project name displayed in the page header and the longer project description. Separate values can be provided for each active language.

The short and long descriptions may also be used in project metadata, message templates, and summary pages. They should therefore identify the project clearly and provide current contact or contextual information where appropriate.

Data management¶

The Data management section provides summaries of uploads and observation lists. It can help administrators review recent submissions, identify contributors, and navigate between related records, uploads, and tracklogs.

The documented functions include:

listing observation lists by uploader, date, or tracklog;
summarising the number of records uploaded by each user and to each table;
displaying observation lists submitted during the previous 90 days; and
displaying tracklogs submitted during the previous 30 days.

Interactive tables provide filtering and sorting where supported.