allow strings and multiple fylr fields in datacite fields

Author: Manuel Erdoes

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-05-11
+
+### Added
+- Expression syntax for `fylr Field Path`: combine multiple fields and static strings using `+` (e.g. `"Label: " + objecttype.field1 + "\n" + objecttype.field2`)
+- String literals with escape sequences (`\n` newline, `\t` tab) in field path expressions
+- Conditional groups `(...)`: if any field inside a group is empty, the entire group — including its static labels — is omitted from the output
+- `|decimal2` format specifier for fixed-point integer fields stored as ×100 (e.g. `2030` → `20.30`)
+- Support for nested table fields in dot-path resolution: paths now traverse through fylr's `_nested:<objecttype>__<fieldname>` array keys automatically
+
 ## [1.0.1] - 2026-05-06
 
 ### Added

README.md

@@ -51,8 +51,45 @@ Each row maps a DataCite metadata field to a field path in the fylr object. The
 |---|---|
 | Profile ID | Must match the `ID` of a profile in the Profiles table |
 | DataCite Field | Target field name. Supported: `title`, `creator`, `publisher`, `date`, `description`, `contributor`, `subjects`, `resourceTypeGeneral`, `publicationYear` |
-| fylr Field Path | Dot-separated path to the field in the fylr object, e.g. `haustieranatomie.titel` |
-| Default Value | Fallback value if the field path resolves to nothing |
+| fylr Field Path | A field path or expression (see below) |
+| Default Value | Fallback value if the expression resolves to an empty string |
+
+#### fylr Field Path expressions
+
+The **fylr Field Path** column accepts either a plain dot-path or a concatenation expression built from field references, string literals, and optional conditional groups.
+
+**Plain path** (single field, existing behaviour):
+
+```
+haustieranatomie.titel
+```
+
+**Concatenation** — join multiple values with `+`:
+
+```
+haustieranatomie.field1 + haustieranatomie.field2
+```
+
+**String literals** — use `"..."` or `'...'` for static text. `\n` inserts a newline, `\t` a tab:
+
+```
+haustieranatomie.titel + "\n" + haustieranatomie.beschreibung
+"Title: " + haustieranatomie.titel
+```
+
+**Conditional groups** — wrap part of an expression in `(...)`. The group is omitted entirely if any field inside it is empty. Use this to avoid orphan labels when optional fields are missing:
+
+```
+haustieranatomie.titel + ("\nHeight: " + haustieranatomie.hoehe) + ("\nWidth: " + haustieranatomie.breite)
+```
+
+If `hoehe` is empty the whole `("\nHeight: " + haustieranatomie.hoehe)` group is dropped — no stray label appears.
+
+**Decimal format specifier** — append `|decimal2` to a field reference to divide the stored integer by 100 and format it with two decimal places. Useful for fields stored as fixed-point integers (e.g. a value of `2030` is displayed as `20.30`):
+
+```
+"Height: " + haustieranatomie.hoehe|decimal2 + " cm"
+```
 
 ## Webhook URL
 

documentation.md

@@ -24,6 +24,9 @@ This document explains how the `fylr-plugin-datacite` plugin is implemented. It
 9. [The Main Script (`server/webhook/register-doi.js`)](#the-main-script-serverwebhookregister-doijs)
    - [Top-level structure](#top-level-structure)
    - [`main()`](#main)
+   - [`resolveExpressionAsync()`](#resolveexpressionasync)
+   - [`tokenizeExpression()`](#tokenizeexpression)
+   - [`formatDecimal2()`](#formatdecimal2)
    - [`resolveFieldPathAsync()`](#resolvefieldpathasync)
    - [`getNestedValue()`](#getnestedvalue)
    - [`httpRequest()`](#httprequest)
@@ -290,14 +293,17 @@ If the admin forgets the query parameter, the script fails fast with `datacite.c
 
 ### Top-level structure
 
-The file is ~480 lines with this shape:
+The file is ~560 lines with this shape:
 
 - Lines 1-13: require `http`/`https`, parse `info.json` from `argv[2]`.
 - Lines 15-41: buffer stdin, invoke `main()` when stdin ends, catch unhandled errors.
 - Lines 43-334: `main()` — the whole orchestration.
-- Lines 341-419: `resolveFieldPathAsync()` — dot-path resolution with fylr-specific fallbacks.
-- Lines 424-437: `getNestedValue()` — simple dot-path getter.
-- Lines 443-476: `httpRequest()` — Node stdlib HTTP wrapper returning a Promise.
+- `resolveExpressionAsync()` — evaluates a field-path expression (single path or concatenation); calls `resolveFieldPathAsync()` per path token.
+- `tokenizeExpression()` — parses an expression string into typed tokens.
+- `formatDecimal2()` — divides an integer by 100 and formats to two decimal places.
+- `resolveFieldPathAsync()` — dot-path resolution with fylr-specific fallbacks (linked objects, nested tables).
+- `getNestedValue()` — simple dot-path getter for reading from `info.json`.
+- `httpRequest()` — Node stdlib HTTP wrapper returning a Promise.
 
 There are commented-out `console.error` debug lines throughout. They are intentionally preserved for quick re-enablement during future debugging; do not delete them without a reason.
 
@@ -318,7 +324,7 @@ Orchestrates everything in a single async function:
 9. **Compute the DataCite Basic Auth header** ([L128](server/webhook/register-doi.js#L128)).
 10. **Loop over objects** ([L143-323](server/webhook/register-doi.js#L143-L323)):
     - Read `_system_object_id` and `_objecttype`.
-    - For each field mapping: strip an optional `<objecttype>.` prefix from the dot-path (the UI sometimes includes it, sometimes not), pick `_current[objecttype]` as the root if it exists (richer data, closer to what a full object fetch would return), and resolve the path.
+    - For each field mapping: call `resolveExpressionAsync()` with the raw `fylr_field_path` value. This handles both plain dot-paths and concatenation expressions transparently.
     - Construct the DOI as `<doi_prefix><system_object_id>`.
     - Construct the landing URL by substituting `%system_object_id%` in the template.
     - Build the DataCite payload (see [JSON:API payload format](#jsonapi-payload-format)). Note the defensive `:unkn` fallbacks — DataCite requires certain fields and rejects empty ones.
@@ -328,15 +334,44 @@ Orchestrates everything in a single async function:
 
 **Why `exit(0)` on config errors?** A non-zero exit causes fylr to treat the whole webhook invocation as failed and may hide the emitted JSON body. Emitting a structured error on stdout plus `exit(0)` gives cleaner admin-visible diagnostics.
 
-### `resolveFieldPathAsync()`
+### `resolveExpressionAsync()`
+
+The entry point for all field-path resolution. It accepts either a plain dot-path (backwards compatible) or a concatenation expression and returns a string.
+
+The expression syntax:
+
+| Token | Example | Behaviour |
+|---|---|---|
+| Plain path | `haustieranatomie.titel` | resolves via `resolveFieldPathAsync` |
+| Concatenation | `field1 + field2` | results joined without separator |
+| String literal | `"Label: "` or `"\n"` | used verbatim (`\n` → newline, `\t` → tab) |
+| Conditional group | `("Label: " + field)` | entire group omitted if any field inside is empty |
+| Format specifier | `field\|decimal2` | integer ÷ 100, two decimal places (e.g. `2030` → `20.30`) |
+
+An optional `<objecttype>.` prefix on each path token is stripped before resolution, so paths with or without the prefix work identically.
+
+### `tokenizeExpression()`
 
-[register-doi.js:341-419](server/webhook/register-doi.js#L341-L419)
+Parses an expression string into an array of typed tokens used by `resolveExpressionAsync`. Token types:
+
+- `{type: 'literal', value: string}` — a quoted string literal
+- `{type: 'path', value: string, format?: string}` — a dot-path reference, with an optional `format` field when `|decimal2` is appended
+- `{type: 'group', tokens: Token[]}` — a conditional group enclosed in `(...)`, recursively parsed
+
+The parser is recursive-descent, handling nested groups naturally. `+` is the only operator; whitespace around it is ignored.
+
+### `formatDecimal2()`
+
+Divides the raw string value by 100 and formats the result with `Number.toFixed(2)`. Used for field values stored as fixed-point integers (×100). Returns the original value unchanged if it is not a valid number.
+
+### `resolveFieldPathAsync()`
 
-Resolves a dot-separated path (e.g. `haustieranatomie.titel` or `hersteller.hersteller.name`) into a value. The logic has three subtleties that would not be obvious from the signature:
+Resolves a dot-separated path (e.g. `haustieranatomie.titel` or `hersteller.hersteller.name`) into a value. The logic has four subtleties that would not be obvious from the signature:
 
-1. **fylr date fields are wrapped objects** (`{value: "2025-04-05"}`). At the end of the walk, if the result is an object with a `value` key, it is unwrapped ([L417](server/webhook/register-doi.js#L417)).
+1. **fylr date fields are wrapped objects** (`{value: "2025-04-05"}`). At the end of the walk, if the result is an object with a `value` key, it is unwrapped.
 2. **The root is always `obj[objecttype]`** — fylr objects are keyed by objecttype at the top level. Passing in a bare object without that wrapper returns `undefined`.
-3. **Linked objects are shallow in the webhook payload**. When an object links to another object, the webhook payload only carries `{_id, _version}` for the linked object. If a dot-path descends into a linked object (either directly navigating into its typed key or trying to access a missing field on a wrapper), the function fetches the full linked object via `GET /api/v1/db/<objecttype>/_all_fields/<id>?format=long` using the plugin user's Bearer token, then continues the walk.
+3. **Nested table fields use a special key format.** In the fylr API payload, a nested table named `tierart` on objecttype `haustieranatomie` is stored under the key `_nested:haustieranatomie__tierart` (not `tierart`). The traversal loop tries the plain part name first; if not found, it automatically tries the `_nested:<objecttype>__<part>` variant before proceeding. The value is an array; the first element is taken and traversal continues into it.
+4. **Linked objects are shallow in the webhook payload**. When an object links to another object, the webhook payload only carries `{_id, _version}` for the linked object. If a dot-path descends into a linked object (either directly navigating into its typed key or trying to access a missing field on a wrapper), the function fetches the full linked object via `GET /api/v1/db/<objecttype>/_all_fields/<id>?format=long` using the plugin user's Bearer token, then continues the walk.
 
 Both linked-object-fetch branches record failures via the shared `warnings` array so the caller can decide how to surface them. Errors from fetches are never fatal; the path just returns `undefined` and the mapping falls back to its `default_value`.
 
@@ -445,4 +480,5 @@ Using the internal API URL (`info.api_url`) avoids any reverse-proxy interferenc
 | `PublishUnknownCollector: collector ""` | The `_basetype` wrapper got removed, or the `collector` field inside `publish` is empty, or the collector name doesn't match the one configured in fylr |
 | Publish entry returns 401/403 | The plugin user in `datacite_global.api_user` lacks the `system.api.publish.post` right |
 | Linked-object field resolves to `undefined` | Either the plugin user can't read the linked objecttype, or the path is wrong. Uncomment the linked-object `console.error` lines to see the failed fetch URL. |
+| Nested table field (e.g. `tierart`) resolves to `undefined` | The field is stored under `_nested:<objecttype>__<fieldname>` in the payload. Make sure the path continues *into* the nested rows (e.g. `objecttype.nestedField.linkedType.linkedType.textField`). |
 | Admin UI shows raw l10n keys instead of labels | New parameter was added to `manifest.master.yml` but not to `datacite-loca.csv` |

manifest.master.yml

@@ -1,6 +1,6 @@
 plugin:
   name: fylr-plugin-datacite
-  version: "1.0.1"
+  version: "1.1.0"
   url: https://github.com/eth-library/fylr-publish-datacite-plugin
   l10n: l10n/datacite-loca.csv
   displayname:

server/webhook/register-doi.js

@@ -162,15 +162,9 @@ async function main() {
 
             if (!dataciteField) continue;
 
-            // Strip objecttype prefix if present (e.g. "haustieranatomie.titel" -> "titel")
-            let resolvedPath = fylrPath;
-            if (resolvedPath && resolvedPath.startsWith(objecttype + '.')) {
-                resolvedPath = resolvedPath.slice(objecttype.length + 1);
-            }
-
             // Prefer _current which contains the full field data; fall back to top-level obj
             const sourceObj = (obj._current && obj._current[objecttype]) ? obj._current : obj;
-            const resolvedValue = await resolveFieldPathAsync(sourceObj, objecttype, resolvedPath, fylrApiUrl, accessToken, warnings);
+            const resolvedValue = await resolveExpressionAsync(fylrPath, sourceObj, objecttype, fylrApiUrl, accessToken, warnings);
             mappedFields[dataciteField] = resolvedValue || defaultValue || '';
         }
 
@@ -364,6 +358,120 @@ async function main() {
     process.exit(0);
 }
 
+/**
+ * Parses a fylr_field_path value into typed tokens for resolveExpressionAsync.
+ *
+ * Token types:
+ *   literal  – a quoted string ("..." or '...'), with \n and \t escape support
+ *   path     – an unquoted dot-path field reference
+ *   group    – a (...) conditional block; omitted entirely when any path inside is empty
+ *
+ * Examples:
+ *   type.field + " — " + type.other + "\n"
+ *   ("Label: " + type.field + "\n") + ("Other: " + type.other + "\n")
+ */
+function formatDecimal2(value) {
+    if (!value) return '';
+    const num = parseFloat(value) / 100;
+    if (isNaN(num)) return value;
+    // return num.toFixed(2).replace('.', ',');
+    return num.toFixed(2);
+}
+
+function tokenizeExpression(expression) {
+    let i = 0;
+
+    function makePathToken(raw) {
+        const pipeIdx = raw.indexOf('|');
+        if (pipeIdx === -1) return { type: 'path', value: raw };
+        return { type: 'path', value: raw.slice(0, pipeIdx).trim(), format: raw.slice(pipeIdx + 1).trim() };
+    }
+
+    function parseString(q) {
+        i++; // skip opening quote
+        let s = '';
+        while (i < expression.length && expression[i] !== q) {
+            if (expression[i] === '\\' && i + 1 < expression.length) {
+                const n = expression[i + 1];
+                s += n === 'n' ? '\n' : n === 't' ? '\t' : n;
+                i += 2;
+            } else { s += expression[i++]; }
+        }
+        i++; // skip closing quote
+        return s;
+    }
+
+    function parseTokenList(stopChar) {
+        const result = [];
+        let current = '';
+        while (i < expression.length && expression[i] !== stopChar) {
+            const ch = expression[i];
+            if (ch === '"' || ch === "'") {
+                const t = current.trim(); if (t) result.push(makePathToken(t)); current = '';
+                result.push({ type: 'literal', value: parseString(ch) });
+            } else if (ch === '+') {
+                const t = current.trim(); if (t) result.push(makePathToken(t)); current = ''; i++;
+            } else if (ch === '(') {
+                const t = current.trim(); if (t) result.push(makePathToken(t)); current = '';
+                i++; // skip '('
+                const groupTokens = parseTokenList(')');
+                if (i < expression.length) i++; // skip ')'
+                result.push({ type: 'group', tokens: groupTokens });
+            } else { current += ch; i++; }
+        }
+        const t = current.trim(); if (t) result.push(makePathToken(t));
+        return result;
+    }
+
+    return parseTokenList(undefined);
+}
+
+/**
+ * Resolves a fylr_field_path expression to a string value.
+ *
+ * Supports:
+ *   - Single dot-path:  type.field  (existing behaviour)
+ *   - Concatenation:    type.field + " — " + type.other + "\n"
+ *   - Conditional group: ("Label: " + type.field + "\n")
+ *     → the group is omitted entirely when any field path inside resolves to empty,
+ *       so labels/separators never appear without their corresponding value.
+ */
+async function resolveExpressionAsync(expression, sourceObj, objecttype, fylrApiUrl, accessToken, warnings) {
+    if (!expression) return '';
+    const tokens = tokenizeExpression(expression);
+
+    async function resolvePath(token) {
+        let path = token.value;
+        if (path.startsWith(objecttype + '.')) path = path.slice(objecttype.length + 1);
+        const raw = (await resolveFieldPathAsync(sourceObj, objecttype, path, fylrApiUrl, accessToken, warnings)) || '';
+        if (token.format === 'decimal2') return formatDecimal2(raw);
+        return raw;
+    }
+
+    const parts = [];
+    for (const token of tokens) {
+        if (token.type === 'literal') {
+            parts.push(token.value);
+        } else if (token.type === 'path') {
+            parts.push(await resolvePath(token));
+        } else if (token.type === 'group') {
+            const subParts = [];
+            let anyEmpty = false;
+            for (const sub of token.tokens) {
+                if (sub.type === 'literal') {
+                    subParts.push(sub.value);
+                } else {
+                    const val = await resolvePath(sub);
+                    if (!val) anyEmpty = true;
+                    subParts.push(val);
+                }
+            }
+            if (!anyEmpty) parts.push(subParts.join(''));
+        }
+    }
+    return parts.join('');
+}
+
 /**
  * Like resolveFieldPath but handles fylr date objects ({value: "..."})
  * and fetches linked objects from the fylr API when the path goes deeper
@@ -379,6 +487,13 @@ async function resolveFieldPathAsync(obj, objecttype, dotPath, fylrApiUrl, acces
     for (let i = 0; i < parts.length; i++) {
         if (current === null || current === undefined) return undefined;
 
+        // Nested tables (haustieranatomie > tierart etc.) are arrays in the API payload.
+        // Take the first element so dot-path traversal can continue into it.
+        if (Array.isArray(current)) {
+            current = current[0];
+            if (current === null || current === undefined) return undefined;
+        }
+
         const part = parts[i];
 
         if (typeof current !== 'object') return undefined;
@@ -412,6 +527,13 @@ async function resolveFieldPathAsync(obj, objecttype, dotPath, fylrApiUrl, acces
         }
 
         if (!(part in current)) {
+            // fylr stores nested table rows under _nested:<objecttype>__<fieldname>
+            const nestedKey = '_nested:' + objecttype + '__' + part;
+            if (nestedKey in current) {
+                current = current[nestedKey];
+                continue;
+            }
+
             // If current is a linked object wrapper, fetch the full object and retry
             if (current._objecttype && current._system_object_id && fylrApiUrl && accessToken) {
                 const innerId = current[current._objecttype] && current[current._objecttype]._id;