Currently, the Komf notification context for Velocity templates only exposes the explicit series metadata from the media server ($series.metadata). This means fields such as summary are only filled if the series-level metadata is set.
However, Komga provides an aggregated booksMetadata block in its API, which includes useful fallback data – such as the summary from the first book with a summary, and aggregated authors/tags/releaseDate. This is especially valuable because it's common for many series to rely on that aggregated information rather than a manually set series-level summary or authors.
Current limitations
- Komf templates cannot access
booksMetadata.summary, booksMetadata.authors, etc., as those are not mapped into the Velocity context (only $series.metadata and $books are available).
- As a result, end users cannot:
- Use the aggregated summary (which is what Komga itself shows when series summary is not set)
- Access all series-level authors/tags in notifications (unless every book is painstakingly parsed individually)
- There are TODO comments in the KomgaMediaServerClientAdapter (e.g., for
authors) highlighting the current limitation and intention to pull those fields from the aggregation, but this isn't implemented.
|
authors = emptyList(), //TODO take authors from book metadata?, |
|
releaseYear = null, //TODO take from book metadata?, |
Requested solutions
I would like to request one of the following.
-
Direct Access: Provide access in Velocity templates to the full Komga booksMetadata aggregation block as a top-level property (e.g., $series.booksMetadata). This would mirror the structure seen in the Komga API response and be consistent for fields like authors, tags, releaseDate, summary, and summaryNumber.
-
Automatic Fallback: For fields like summary, authors, etc., if the series-level metadata is empty, automatically fallback to use the aggregated value from the booksMetadata aggregation (as Komga does in its UI/api consumers). This would ensure message completeness and consistent information for notifications.
I think the second solution would be better. Especially for cross-compatibility with Kavita. Moreover, it would make the user not responsible for checking if the summary is empty which would be kinda verbose – see the example below.
…
#if(${series.summary} == "")${series.booksMetadata.summary}#{else}${series.summary}#end
…Current workarounds
As I wrote earlier, we can technically access the metadata by aggregating metadata from books manually. This is not a good solution though. It would make the template unreadable. Templates shouldn't contain such advanced logic – they were not invented for that.
Other Considerations
Please consider if there are more aggregated values that would be valuable to surface or fallback to.
Currently, the Komf notification context for Velocity templates only exposes the explicit series metadata from the media server (
$series.metadata). This means fields such assummaryare only filled if the series-level metadata is set.However, Komga provides an aggregated
booksMetadatablock in its API, which includes useful fallback data – such as the summary from the first book with a summary, and aggregated authors/tags/releaseDate. This is especially valuable because it's common for many series to rely on that aggregated information rather than a manually set series-level summary or authors.Current limitations
booksMetadata.summary,booksMetadata.authors, etc., as those are not mapped into the Velocity context (only$series.metadataand$booksare available).authors) highlighting the current limitation and intention to pull those fields from the aggregation, but this isn't implemented.komf/komf-mediaserver/src/commonMain/kotlin/snd/komf/mediaserver/komga/KomgaMediaServerClientAdapter.kt
Lines 260 to 261 in 5d0f689
Requested solutions
I would like to request one of the following.
Direct Access: Provide access in Velocity templates to the full Komga
booksMetadataaggregation block as a top-level property (e.g.,$series.booksMetadata). This would mirror the structure seen in the Komga API response and be consistent for fields likeauthors,tags,releaseDate,summary, andsummaryNumber.Automatic Fallback: For fields like
summary,authors, etc., if the series-level metadata is empty, automatically fallback to use the aggregated value from the booksMetadata aggregation (as Komga does in its UI/api consumers). This would ensure message completeness and consistent information for notifications.I think the second solution would be better. Especially for cross-compatibility with Kavita. Moreover, it would make the user not responsible for checking if the summary is empty which would be kinda verbose – see the example below.
Current workarounds
As I wrote earlier, we can technically access the metadata by aggregating metadata from
booksmanually. This is not a good solution though. It would make the template unreadable. Templates shouldn't contain such advanced logic – they were not invented for that.Other Considerations
Please consider if there are more aggregated values that would be valuable to surface or fallback to.