Merge branch 'release-v0.27.0' into 'master'

Release 0.27.0

See merge request Scientific-IT-Systems/SampleDB!1050

Dockerfile

@@ -1,42 +1,64 @@
-FROM python:3.11-slim-bookworm
-
-LABEL maintainer="[email protected]"
-LABEL org.opencontainers.image.source=https://github.com/sciapp/sampledb
-LABEL org.opencontainers.image.url=https://scientific-it-systems.iffgit.fz-juelich.de/SampleDB/
-LABEL org.opencontainers.image.documentation=https://scientific-it-systems.iffgit.fz-juelich.de/SampleDB/
-LABEL org.opencontainers.image.title="SampleDB"
-LABEL org.opencontainers.image.description="A web-based electronic lab notebook with a focus on sample and measurement metadata"
-LABEL org.opencontainers.image.licenses=MIT
-
+# Dockerfile for sampledb
+FROM python:3.11-slim-bookworm as builder
 
 # Install required system packages
 # GCC is required to build python dependencies on ARM architectures
 # git is required to build python dependencies from git repositories
+ARG DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && \
     apt-get upgrade -y && \
-    apt-get install -y gcc libpangocairo-1.0-0 gettext git
+    apt-get install -y gcc git
 
-# Switch to non-root user
+# It's important to keep the same path in builder image and final image
 RUN useradd -ms /bin/bash sampledb
 USER sampledb
 WORKDIR /home/sampledb
 
+ENV PYTHONDONTWRITEBYTECODE=1
+
 # Set up virtual environment
 ENV VIRTUAL_ENV=/home/sampledb/venv
 RUN python3 -m venv $VIRTUAL_ENV
 ENV PATH="$VIRTUAL_ENV/bin:$PATH"
-RUN  pip install --upgrade pip
+RUN pip install --upgrade pip
 
 # Install required Python packages
 COPY requirements.txt requirements.txt
 RUN pip install --no-cache-dir -r requirements.txt
 
-# Clean up system packages that are no longer required
-USER root
-RUN apt-get remove -y gcc && \
-    apt-get autoremove -y && \
+# Final image
+FROM python:3.11-slim-bookworm
+
+LABEL maintainer="[email protected]"
+LABEL org.opencontainers.image.source=https://github.com/sciapp/sampledb
+LABEL org.opencontainers.image.url=https://scientific-it-systems.iffgit.fz-juelich.de/SampleDB/
+LABEL org.opencontainers.image.documentation=https://scientific-it-systems.iffgit.fz-juelich.de/SampleDB/
+LABEL org.opencontainers.image.title="SampleDB"
+LABEL org.opencontainers.image.description="A web-based electronic lab notebook with a focus on sample and measurement metadata"
+LABEL org.opencontainers.image.licenses=MIT
+
+# Install required system packages
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && \
+    apt-get upgrade -y && \
+    apt-get install -y libpangocairo-1.0-0 gettext && \
     rm -rf /var/lib/apt/lists/*
+
+# Switch to non-root user
+RUN useradd -ms /bin/bash sampledb
 USER sampledb
+WORKDIR /home/sampledb
+
+# Python specific config
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Copy dependencies from builder image
+COPY --from=builder --chown=sampledb:sampledb /home/sampledb/venv /home/sampledb/venv
+
+# Set up virtual environment
+ENV VIRTUAL_ENV=/home/sampledb/venv
+ENV PATH="$VIRTUAL_ENV/bin:$PATH"
 
 # Copy sampledb source code
 COPY --chown=sampledb:sampledb sampledb sampledb

README.md

@@ -22,7 +22,7 @@ If you do not have Docker installed yet, please [install Docker](https://docs.do
 
 ### Using docker-compose
 
-First, get the [docker-compose.yml](https://raw.githubusercontent.com/sciapp/sampledb/develop/docker-compose.yml) configuration file. You can git clone this repo or just get the file:
+First, get the [docker-compose.yml](https://raw.githubusercontent.com/sciapp/sampledb/develop/docker-compose.yml.dist) configuration file. You can git clone this repo or just get the file:
 
 ```bash
 curl https://raw.githubusercontent.com/sciapp/sampledb/develop/docker-compose.yml.dist --output docker-compose.yml
@@ -63,7 +63,7 @@ docker run \
     --restart=always \
     --name sampledb \
     -p 8000:8000 \
-    sciapp/sampledb:0.26.0
+    sciapp/sampledb:0.27.0
 ```
 
 ### Once it's started

docker-compose.yml.dist

@@ -6,7 +6,7 @@ version: '3'
 
 services:
   web:
-    image: sciapp/sampledb:0.26.0
+    image: sciapp/sampledb:0.27.0
     restart: always
     container_name: sampledb
     # Note: this config option works with docker-compose version >1.27

docs/administrator_guide/configuration.rst

@@ -67,6 +67,7 @@ LDAP
 
 If you use LDAP for user management, you can use these variables to configure how SampleDB should connect to your LDAP server.
 
+.. _customization_configuration:
 
 Customization
 -------------
@@ -315,5 +316,9 @@ Miscellaneous
      - The time of inactivity after which users on shared devices will be signed out in minutes (default: 30 minutes).
    * - SAMPLEDB_DISABLE_OUTDATED_USE_AS_TEMPLATE
      - If set, users cannot use objects with outdated schemas as a template (default: False).
+   * - SAMPLEDB_DISABLE_TOPICS
+     - You can set this option to disable the :ref:`Topics <topics>` feature. (default: False, Topics enabled)
+   * - SAMPLEDB_LABEL_PAPER_FORMATS
+     - Specifies label paper formats that can be used for qr code labels. For more information, see :ref:`Label Paper Formats <labels>`. (default: ``[]``)
 
 There are other configuration values related to packages used by SampleDB. For more information on those, see the documentation of the corresponding packages.

docs/administrator_guide/customization.rst

@@ -0,0 +1,57 @@
+.. _customization:
+
+Customization
+=============
+
+SampleDB provides several methods for customizing a specific SampleDB instance.
+
+Configuration
+-------------
+
+There are several :ref:`Configuration Variables <customization_configuration>` which can be used to set the name and description of the SampleDB instance and to set instance-specific links (e.g. to a privacy policy or help page).
+
+Custom Stylesheets
+------------------
+
+The file ``sampledb/static/css/custom.css`` can be used to define custom CSS rules to change the appearance of SampleDB.
+
+To use this while using a Docker container to run SampleDB, you will need to bind mount the file to the path ``/home/sampledb/sampledb/static/css/custom.css``, .e.g using the ``--volume`` parameter for the ``docker run`` command or using a ``volumes`` section in a ``docker-compose.yml`` file.
+
+Custom Templates
+----------------
+
+SampleDB uses `Jinja <https://jinja.palletsprojects.com/en/>`_ templates to render its web frontend. While you can, in theory, overwrite those templates to provide your own, this may lead to issues when upgrading the SampleDB version. However, the following templates are explicitly provided to be overwritten for the purpose of customization:
+
+custom/alerts.html
+``````````````````
+
+This template is included right above system alerts which usually report success or failure on user actions, e.g. having signed in or having created an object. By introducing custom HTML, you can add alerts to be shown on all pages, or by checking the ``request.endpoint`` variable in Jinja, you can ensure these alerts are only shown on specific pages.
+
+.. code-block:: html+jinja
+    :caption: A custom alerts template for alerts on the sign-in page
+
+    {% if request.endpoint == 'frontend.sign_in' %}
+      <div class="alert alert-info">
+        <strong>Note:</strong> Contact an <a href="mailto:[email protected]">administrator</a> to request an account.
+      </div>
+    {% endif %}
+
+custom/head.html
+````````````````
+
+This template is included in the HTML head section and can be used to include custom stylesheets (in addition to the ``custom.css`` file described above), custom scripts and other elements. Note that SampleDB is configured with a fairly restrictive `Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP>`_, which will block inline scripts or stylesheets as well as those from other servers/origins. Place any scripts or stylesheets in the ``sampledb/static/`` folder to make sure they will not be blocked.
+
+.. code-block:: html+jinja
+    :caption: A custom head template including a CSS file from the ``sampledb/static`` directory
+
+    <link rel="stylesheet" href="{{ fingerprinted_static('example.css') }}">
+
+custom/scripts.html
+```````````````````
+
+This template is included at the end of the HTML body section, right after scripts for SampleDB have been included, so that jQuery and other scripts are already available. This can be used to include custom scripts and other elements. As noted above, you will need to use the ``sampledb/static/`` folder to make sure the scripts will not be blocked.
+
+.. code-block:: html+jinja
+    :caption: A custom scripts template including a JavaScript file from the ``sampledb/static`` directory
+
+    <script src="{{ fingerprinted_static('example.js') }}"></script>

docs/administrator_guide/getting_started.rst

@@ -42,7 +42,7 @@ Next, start the SampleDB container:
         --restart=always \
         --name sampledb \
         -p 8000:8000 \
-        sciapp/sampledb:0.26.0
+        sciapp/sampledb:0.27.0
 
 This will start a minimal SampleDB installation at ``http://localhost:8000`` and allow you to sign in with the username ``admin`` and the password ``password``.
 

docs/administrator_guide/labels.rst

@@ -0,0 +1,23 @@
+.. _labels:
+
+Label Paper Formats
+===================
+
+The configuration variable ``SAMPLEDB_LABEL_PAPER_FORMATS`` can be used to set available label paper formats for
+self-adhesive labels, which can be used when generating QR Code labels. The value of this variable must consist of a list
+of JSON objects. Each JSON object represents a label paper format and must contain the following keys:
+ * ``format_name``: Name of the label paper format which is shown during selection (string or dictionary with language keys (e.g. ``{"en": "Example Format"}``))
+ * ``labels_in_row``: Number of labels in a row (positive integer)
+ * ``labels_in_col``: Number of labels in a column (positive integer)
+ * ``qr_code_width``: Width of the QR code in mm (positive integer)
+ * ``label_width``: Width of a single label in mm (positive float)
+ * ``label_height``: Height of a single label in mm (positive float)
+ * ``margin_horizontal``: Distance between two labels in horizontal direction in mm (positive float)
+ * ``margin_vertical``: Distance between two labels in vertical direction in mm (positive float)
+ * ``paper_format``: Paper format that should be used (integer between 0 and 3)
+    * 0: DIN A4 Portrait
+    * 1: DIN A4 Landscape
+    * 2: Letter Portrait
+    * 3: Letter Landscape
+
+By default, no label paper formats are available. (``[]``)

docs/changelog.rst

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+Version 0.27
+------------
+
+Released on March 18th, 2024.
+
+- Added ``choice`` array style for multi selection dropdowns
+- Introduce action topics and allow filtering action lists by topics
+- Added new array index diff syntax for updating data via the HTTP API
+- Added creation of activity log entries during import of objects from other databases
+- Added initial support for custom templates
+
 Version 0.26
 ------------
 

docs/developer_guide/api.rst

@@ -2317,6 +2317,48 @@ The following diff would add a value of 11g to ``mass_list`` and set ``measureme
       ]
     }
 
+A dictionary mapping indices to item diffs is also supported for arrays, though this syntax will not be generated by SampleDB. Indices are strings, with signed string indices (e.g. "+0" or "-1") being relative to the end of the array. This can be useful for writing diffs that change arrays without requiring knowledge about the current array length. As such, the following diff would also add an entry to ``mass_list``, using this alternative array index syntax:
+
+.. code-block:: json
+
+    {
+      "mass_list": {
+        "+0": {
+          "_after": {
+            "_type": "quantity",
+            "magnitude": 12,
+            "magnitude_in_base_units": 0.012,
+            "units": "g",
+            "dimensionality": "[mass]"
+          }
+        }
+      }
+    }
+
+While diffs for timeseries will use the generic ``_before`` and ``_after`` syntax when produced by SampleDB, using the array or array index syntax for timeseries is also supported when providing diffs via the HTTP API. As such, the following two diffs would both append an entry to the timeseries ``temperature``:
+
+.. code-block:: json
+
+    {
+      "temperature": [
+        null,
+        null,
+        {
+          "_after": ["2023-01-02 03:04:05.678900", 20, 293,15]
+        }
+      ]
+    }
+
+.. code-block:: json
+
+    {
+      "temperature": {
+        "+0": {
+          "_after": ["2023-01-02 03:04:05.678900", 20, 293,15]
+        }
+      }
+    }
+
 .. _access_tokens:
 
 Access Tokens
@@ -2399,7 +2441,8 @@ Reading the full accessible object log
                 "object_id": 163,
                 "user_id": 12,
                 "data": {},
-                "utc_datetime": "2023-12-03 01:02:03"
+                "utc_datetime": "2023-12-03 01:02:03",
+                "is_imported": false
             }
         ]
 
@@ -2410,4 +2453,5 @@ Reading the full accessible object log
     :>json string user_id: the ID of the user by whose activity the log entry was created
     :>json string data: the data of the log entry, might be empty (``{}``)
     :>json string utc_datetime: the timestamp of the log entry in UTC in format %Y-%m-%d %H:%M:%S
+    :>json bool is_imported: whether the log entry was imported
     :statuscode 200: no error

docs/index.rst

@@ -20,6 +20,7 @@ User Guide
     user_guide/objects.rst
     user_guide/search.rst
     user_guide/locations.rst
+    user_guide/topics.rst
     user_guide/export.rst
     user_guide/citations.rst
 
@@ -62,7 +63,9 @@ Administrator Guide
     administrator_guide/federation.rst
     administrator_guide/monitoring_dashboard.rst
     administrator_guide/download_service.rst
+    administrator_guide/customization.rst
     administrator_guide/deprecated_features.rst
+    administrator_guide/labels.rst
 
 Developer Guide
 ---------------

docs/user_guide/actions.rst

@@ -17,6 +17,15 @@ Action Types
 The type of an Action describes the general kind of process it represents, such as **Sample Creation**. There are four built-in action types for creating samples, performing a measurement, running a simulation, and for use as schema templates. Administrators can create additional custom action types.
 Schema templates have a special role, as they are usually not used like other actions. Instead, actions marked for use as a schema template can be included in the schemas of other actions.
 
+.. _action_topics:
+
+Topics
+------
+
+Topics allow you to filter the action list by predefined topics.
+When creating or editing an action, you can optionally assign one or more topics to the action.
+See the :ref:`topics section <topics>` for more details.
+
 Custom Actions
 --------------
 

docs/user_guide/schemas.rst

@@ -353,7 +353,7 @@ If the ``default`` attribute is not set, this number can be used to set how many
 style
 ^^^^^
 
-This attribute is a string indicating how the array should be displayed. By default, the items will be shown one after another, but sometimes a different behavior may be desired. If the items are objects, using the ``table`` style may be useful to create a table with the items as rows and their properties in the columns. For top-level tables with many columns, the ``full_width_table`` style can be used to let the table be as wide as the browser window permits. Alternatively, if the items should be in the columns and their properties should be in the rows, the ``horizontal_table`` style can be used. If the items are neither objects nor arrays, the ``list`` style may be useful to create a simple list.
+This attribute is a string indicating how the array should be displayed. By default, the items will be shown one after another, but sometimes a different behavior may be desired. If the items are objects, using the ``table`` style may be useful to create a table with the items as rows and their properties in the columns. For top-level tables with many columns, the ``full_width_table`` style can be used to let the table be as wide as the browser window permits. Alternatively, if the items should be in the columns and their properties should be in the rows, the ``horizontal_table`` style can be used. If the items are neither objects nor arrays, the ``list`` style may be useful to create a simple list. If the items are texts with a list of choices, then the style ``choice`` will result in a dropdown allowing the user to select multiple items.
 
 .. note:: Using a style other than the default may lead to issues when entering or viewing object data. Please test the action and how its objects are displayed. If you encounter issues with a style, you can `report it on GitHub <https://github.com/sciapp/sampledb/issues/new>`_.
 

docs/user_guide/topics.rst

@@ -0,0 +1,15 @@
+.. _topics:
+
+Topics
+======
+
+Actions in |service_name| can be filtered by topics to limit the displayed actions in the action list.
+A topic for example could represent a laboratory, actions used in one workflow, or the actions one research group uses.
+Multiple topics can be assigned to one action.
+Similar to object filters users can save their topic filter selection.
+
+Similar to action types, topics can be displayed in the navbar and on the frontpage.
+Administrators can create new topics.
+
+.. note::
+    An administrator might have disabled this feature (see :ref:`SAMPLEDB_DISABLE_TOPICS <miscellaneous_config>`)

docs/user_guide/users.rst

@@ -96,3 +96,26 @@ If a user does not create an alias for a database, no personal information will
 
 .. note::
     Administrators can enable that the information from user profiles will be shared by default.
+
+
+Federated Identities
+--------------------
+
+If a user has access to two or more different SampleDB instances in a federation, they can be locally linked by a federated identity.
+A federated identity allows the federation users to be recognized (e.g., object creation, comments, etc.) by the name of the local corresponding user in the federated identity.
+
+To create federated identities, there are two different ways:
+- The first way is that users can create federated identities by themselves. For that, the users have to verify their identity by authenticating with the federation partner through the "Sign in to …" button in the federation overview.
+- As an alternative, if the local and federated users share the same email address, a federated identity will be created automatically when updates are imported.
+
+
+.. figure:: ../static/img/generated/federated_identity.png
+    :alt: Federated Identity Overview
+
+    Federated Identity Overview
+
+
+In addition to the federated identities used with federation partners, users can also create federated identities during the process of :ref:`importing an .eln file <eln_import>`.
+
+.. note::
+    When setting up a federated identity for users from ELN files, the importing users can only create a federated identity for themselves.