The events API is Livingdocs’s implementation of the publish/subscribe pattern. This allows you to send messages back and forth between features or to listen for events from the core features. Events are fire and forget thus it is possible that some calls might be lost (e.g. when there is a connection outage). If you need reliable transaction-like hooks, see the hooks feature.
Requiring events from the li-server
Example:
const config = require('../conf')
const liServer = require('@livingdocs/server')(config)
liServer.events.subscribe('document.update', console.log)
Event firing: notify
events.notify(event, message)
- event
<String>
- message
<Object>
The events.notify() methods emits a named event alongside a message object.
Event subscription: subscribe
events.subscribe(event, listener)
- event
<String>
- listener
<Function>
The events.subscribe() method adds a listener that gets called each time the event is fired.
Event unsubscription: unsubscribe
events.unsubscribe(event, listener)
- event
<String>
- listener
<Function>
The events.unsubscribe() method removes the listener that was called each time the event was fired.
Events unsubscription: unsubscribeAll
events.unsubscribeAll()
The events.unsubscribeAll() method removes all listeners.
Event subscribers: subscribers
events.subscribers(event)
- event
<String>
The events.subscribers() method lists all the listeners of an event.
Available Events
The following lists all events, before the comma, the name of the event and behind the comma, the parameters received by a listener.
When a document or media library event is emitted, the Elasticsearch index may not have been updated yet. Hence, when fetching data from a Public API endpoint that internally queries the Elasticsearch index, the response may not immediately reflect the event.
Currently, Livingdocs does not provide a mechanism to circumvent this limitation. Customers impacted by this are recommended to delay fetching data after receiving an event. Depending on the use case, such as when invalidating caches, it may be worth considering an alternative cache invalidation strategy.
User
- user.create,
(eventName, {user})
- user.delete,
(eventName, {user})
- user.password.request,
(eventName, {userId, identityId})
- user.password.redeem,
(eventName, {userId, identityId})
- user.password.change,
(eventName, {id, connectionId, identityId, userId})
- user.email.change,
(eventName, identity)
- user.login.success,
(eventName, {user})
- user.login.fail,
(eventName, {error})
- user.login.new-device,
(eventName, {userId, identityId})
- user.newsletter,
(eventName, {newsletter, userId, email, displayName})
Document
- document.update,
(eventName, {user, documentVersion})
- document.delete,
(eventName, {user, documentVersion})
- document.create,
(eventName, {user, documentVersion})
Note: this event is also triggered by document transforms - document.publish,
(eventName, {user, documentVersion})
- document.unpublish,
(eventName, {user, documentVersion})
- document.copy,
(eventName, {documentVersion, originalDocumentId, isTranslation})
- document.transform,
(eventName, {documentVersion, originalContentType})
- document.build
(eventName, {user, documentVersion, reportId, deliveryHandle})
- document.build.abort
(eventName, {user, documentVersion, reportId, deliveryHandle})
(Added in:release-2024-07
) - document.build.userChoice
(eventName, {user, documentVersion, reportId, deliveryHandle, selectedUserChoice})
(Added in:release-2024-07
) - document.build.draft
(eventName, {user, documentVersion, reportId, deliveryHandle})
- document.build.draft.abort
(eventName, {user, documentVersion, reportId, deliveryHandle})
(Added in:release-2024-07
) - document.build.draft.userChoice
(eventName, {user, documentVersion, reportId, deliveryHandle, selectedUserChoice})
(Added in:release-2024-07
)
Publication
- publication.update,
(eventName, {user, documentVersion})
(Added in:release-2024-03
) - publication.updated,
(eventName, {user, documentVersion})
(Deprecated in:release-2024-03
)
Document List
- document_list.delete,
(eventName, {user, documentList})
- document_list.publish,
(eventName, {user, documentList})
- document_list.update,
(eventName), {user, documentList}
- document_list.create,
(eventName, {user, documentList})
Media Library Entry
- mediaLibraryEntry.create,
(eventName, {userId, projectId, mediaLibraryEntry})
- mediaLibraryEntry.update,
(eventName, {userId, projectId, id, changes})
- mediaLibraryEntry.archive,
(eventName, {userId, projectId, id})
- mediaLibraryEntry.revoke,
(eventName, {userId, projectId, id, mediaLibraryEntry})
- mediaLibraryEntry.active,
(eventName, {userId, projectId, id})
(Added in:release-2024-03
) - mediaLibraryEntry.invalid,
(eventName, {userId, projectId, id})
(Added in:release-2024-03
)
Project
- project.create,
(eventName, {project})
- project.update,
(eventName, {project})
Category
- category.update,
(eventName, {pointer, value, projectId, user})
Migration
Removed in:release-2025-01
- migration.prepare,
(eventName, {migration})
- migration.accept,
(eventName, {migration})
- migration.cancel,
(eventName, {migration})