Dev Webinar

release-2023-11

Overview

• Welcome!
• Q&A after every feature + at the end
• Technical release notes revamp
• Feedback -> meinrad@livingdocs.io

​

Recording of the webinar | Passcode: QbEfU+6t

Features

Document Command API

​

New Public API endpoint to update documents by sending commands:�PATCH api/v1/documents/:id/commands

Commands:

• setMetadataProperty
• setEditableDirective
• publish

Preconditions:

• isPublished (true/false)

More details in the documentation:�https://docs.livingdocs.io/reference/public-api/document-command-api/

Actors

• Actors are all the authorized entities that can perform actions within Livingdocs Editor or Livingdocs Server via the Public API.
• We have separated them into Human users and Machine users (API clients for external applications and Import users). Every API client has an associated ActorId within actors database table.
• This allows tracking of the API Client/Token that performed an action on a document, i.e. via Commands API.

​

​

​

• Import User is no longer a user (migrated from users table to actors table). Therefore, userApi.findById(importUserId) will result in a not found error.

{"operation": "setMetadataProperty", “propertyName”: “title”, …}

Enhanced search syntax

• Syntax allows users to use special operators to improve text based search results. The syntax supports the following operators:
• + : AND operator
• | : OR operator
• - : negates a single token (excludes the token)
• “ : wraps a number of tokens to be included as a phrase into search
• Examples:
• Query 1: quick brown +fox -news will search for documents containing quick and brown and fox and documents that do not contain news, i.e. quick AND brown AND fox AND NOT news.
• Query 2: quick "brown fox" will only match documents that contain the exact phrase brown fox and quick, e.g. The quick fox is brown wouldn’t result in a match, but The brown fox is quick would.
• Query 3: quick | brown | fox will match documents that contain quick OR brown OR fox, any of those words.

Enhanced search syntax

• Users in the Editor can use a new syntax in the Media Library search bar and as opt-in feature per document dashboard within project configuration:

​

​

​

• Score boosting by document update timestamp has been removed
• Boolean AND instead of OR is used when filtering/scoring multiple tokens

Add liServer.register...() methods

We have extended the liServer API to allow to register extensions and custom routes. This simplifies the server initialization and also improves IDE autocomplete support.

https://docs.livingdocs.io/operations/releases/release-2023-11/#add-liserverregister-methods-

Expose IframePlugin register function via liEditor: liEditor.registerIframePlugin({IframePlugin}).

Push Notifications within articles

Exactly one year ago, with November release 2022, we introduced the new push messages feature, but it was limited to Table Dashboard cells.

Now it’s also possible to send a push message from the toolbar in the article editor view.

The toolbar action will be visible on all content types with an li-push-messages metadata property, but the button is disabled if the document has unpublished changes.

​

ParamsSchema & Metadata Plugin config validation

Livingdocs plugins can be used in various contexts:

• Metadata: In Content Types for documents and in Media Types for Media Library Entries
• ParamsSchema: Include Services (Properties Panel), Document Creation Flows and Push Messages

The documentation page for all the metadata plugins describes in which contexts the plugins are supported (except for Creation Flows and Push Messages)

ParamsSchema & Metadata Plugin config validation

Before release-2023-11, we didn’t validate the correct usage of the plugins very strictly. It was done as following:

• Metadata: Validated the metadata property configuration (such as config, ui etc.), but didn’t check if a plugin is actually allowed to be used in Document or Media Metadata.
• Include Services: Only for some of the plugins we validated the configuration and we didn’t check if the plugin is supported in the context either
• Document Creation Flows: No validation at all
• Push Messages: No validation at all

ParamsSchema & Metadata Plugin config validation

With release-2023-11, we are able to validate plugin usage and configuration in all contexts. And with release-2024-01, we will enforce the correct usage.

To opt-in to the validation you can set serverConfig.useStrictSchemas: true. This will allow you to find any invalid usage of plugins and fix them before the next release.

ParamsSchema & Metadata Plugin config validation

Custom downstream plugins will by default work for document and media metadata. You have the option to explicitly enable them for include service params too:

�// In your plugin file:��supportedPluginContexts: [

'documentMetadata',

'mediaLibraryEntryMetadata',

'includeParams'

]

​

Allow tel: and mailto: inline links

Document text content with links can now also contain urls that are prefixed with the tel: and mailto: schema. The same is true for links in the li-tree plugin.

There is no automatic recognition of such link types, users need to explicitly type the tel: and mailto: prefix into the URL input.�

​

Page Management: Real-time Teasers

Teasers can be reloaded automatically on all publish and unpublish events within the current project. This can be enabled by updating the server config:

documents.realtimeUpdates.websocketsEnabled: true

If there is a teaser list in the document then all teasers will be reloaded for every event (with throttling and jitter applied). If there are only document teasers then we only refresh if the document references are published or unpublished.

Note: Setting websocketsEnabled: true will also use the websocket events to update table dashboard rows, or indicate a new result is available.

Breaking Changes: Server

• Metadata plugins: Please replace li-reference with li-document-reference and li-reference-list with li-document-references. No data migration is required, but you will need to remove referenceType from the metadata plugin config.

If you were using ui.config.searchOnlyPublished on li-reference definitions, you should migrate to config.published.

• Project configuration: The label configuration for metadata properties of type li-language does not have an effect anymore. Please remove the li-language label from your metadata configs in contentType configurations.

The language labels are now supported natively in the Livingdocs Editor.

Breaking Changes: Server

• li-includes feature: includesApi.registerService() and includesApi.registerServices() behaviour has changed and are now synchronous methods.

If you rely on its return value to be a Promise (e.g. when accessing .then), you have to update your code. But starting this release it is recommended to use liServer.registerIncludeServices() directly.

Breaking Changes: Server

• DocumentVersion: Remove getter functions which have a replacement on the DocumentVersion class:
• Remove documentVersion.getContentType(), please use documentVersion.contentType
• Remove documentVersion.getDocumentType(), please use documentVersion.documentType
• Remove documentVersion.getProjectId(), please use documentVersion.projectId
• Remove documentVersion.getChannelId(), please use documentVersion.channelId
• Remove documentVersion.getDocumentId(), please use documentVersion.documentId
• Remove documentVersion.getDesignDescriptor(), please use documentVersion.design
• Remove documentVersion.getDesignVersion(), please use documentVersion.design.version
• Remove documentVersion.getTitle(), please use documentVersion.title
• Remove documentVersion.getMetadata(), please use documentVersion.metadata
• Remove documentVersion.getMetadataSource(), please use documentVersion.metadataSource
• Remove documentVersion.getSystemdata(), please use documentVersion.systemdata

Breaking Changes: Editor

• Editor configuration: Editor configuration parameter document.customPublicationDateField support has been removed. With this change metadata based scheduling is no longer supported.

Please migrate to contentType.publishControl.publishSchedule within Publish Control.

Deprecations: Operations

• Operations: Postgres v12 support is deprecated and will be removed in release-2024-03.

Deprecations: Server

• li-documents feature: Document patch API documentApi.patch() has been deprecated, and will be removed in release-2024-01. Please replace it with documentApi.executeDocumentCommands(). No data migration is required, but you will need to swap patches parameter with commands, and user with userId.
• Editing API: This concerns an internal API used by the Livingdocs Editor which has been used in the past by customizations. The Endpoint PATCH /document/:id will be removed in release-2024-01. Please replace it with PATCH /document/:id/commands. No data migration is required, but you will need to replace patches parameter with commands.

Deprecations: Server

• Project configuration: Custom downstream plugins paramSchema validation change. All plugins used in contexts not stated in the docs are affected. Downstream plugins are supported by default in document metadata and media library metadata, but if they are used in include services, creation flows or push messages, the server will throw a validation error on startup.

If a downstream plugin is used in an include service params schema you have to add ‘includeParams’ to supportedPluginContexts[] in the plugin config, as specified in ParamsSchema validation.

Deprecations: Server

• Server configuration: Option serverConfig.documents.realtimeUpdates.enabled is deprecated.

Please use serverConfig.documents.realtimeUpdates.pollingEnabled or serverConfig.documents.realtimeUpdates.websocketsEnabled instead.

This deprecation is part of the Teaser includes reload feature introduced this release.

Q & A

Next Dev Webinar

16.01.24

14:00 - 15:00

Thank you!

Livingdocs ∙ Tellstrasse 31 ∙ 8004 Zürich ∙ www.livingdocs.io