Sophora Metadata Supplier for ARD Mediathek/Audiothek Operation

Triggering the Sophora Metadata Supplier with Sophora

If connected to Sophora the Metadata Supplier synchronises and listens to Sophora document changed events and determines whether to send content to the ARD Mediathek/Audiothek. For this purpose, it must be configured which document state change(s) of documents of which document type(s) should trigger the Metadata Supplier.

Sophora Event to Metadata Supplier Configuration

The following fragment of the application.yml shows an example event handler configuration:

• On a publish event for a Sophora document of type audio, video, image, broadcast or broadcast series the document should be sent to the ARD Mediathek/Audiothek.
• If an audio or video document is "published at", set offline or deleted in Sophora it should be sent to the ARD Mediathek/Audiothek.
• Broadcasts and broadcast series should be sent in the ARD Mediathek/Audiothek if they were set offline or deleted in Sophora.

# Sophora feature settings
metadata-supplier-sophora:
  event-handler:
    configurations:
      -
        on-state-change:
          - 'PUBLISH'
        on-documents-of-types:
          - 'sophora-content-nt:audio'
          - 'sophora-content-nt:video'
          - 'sophora-extension-nt:image'
          - 'sophora-content-nt:broadcast'
          - 'sophora-content-nt:broadcastSeries'
      -
        on-state-change:
          - 'PUBLISH_AT'
          - 'OFFLINE'
          - 'DELETE'
        on-documents-of-types:
          - 'sophora-content-nt:audio'
          - 'sophora-content-nt:video'
      -
        on-state-change:
          - 'OFFLINE'
          - 'DELETE'
        on-documents-of-types:
          - 'sophora-content-nt:broadcast'
          - 'sophora-content-nt:broadcastSeries'

Possible values:

• on-state-change: COMPLETELY_DELETED, DELETE, DISABLE, ENABLE, NONE, OFFLINE, PRE_PUBLISH, PUBLISH, PUBLISH_AT, PUBLISH_AT_CANCELED RELEASE, VERSIONED
• on-documents-of-types: <Any document type name>

The values for on-state-change are the names of StateChange form the Sophora API (which is also provided in DocumentChangedEvents) plus additionally "PUBLISH_AT_CANCELED". The "PUBLISH_AT_CANCELED" configuration is used if a document was in the state PUBLISH_AT and was not published but changed to another state (normally a save of the document). This pseudo-state is only recognized during normal operation and is not handled during synchronizing at startup (see below).

Synchronisation at Startup

When started, the Metadata Supplier synchronises all changes made to Sophora documents from a certain date to the ARD Mediathek/Audiothek. The reference date is stored in the file data/lastHandledEventDate.txt. If no reference date is specified, no content is resynchronised and only new document state changes are transferred. This behavior can be disabled by setting:

# Sophora feature settings
metadata-supplier-sophora:
  sync-at-startup: false

Client Script to manually trigger the Sophora Metadata Supplier

In addition to the trigger option mentioned above, content can be sent from the Sophora DeskClient to the ARD Mediathek/Audiothek without having to explicitly change it (e.g. without re-publishing it in Sophora). For this purpose you can use the client script "Zur ARD Mediathek/Audiothek senden" which is available in the metadata-supplier-scripts-client project.

Before the first use, make sure that the REST API of the Sophora Metadata Supplier (see next section) is reachable by the Sophora Server and that its URL (http://<host>:<port>/<context-path>/) is stored in the Sophora configuration document under the key sophora.metadata-supplier.url.

Depending on the desired use cases, the script can be configured for different document types and document sources (the document currently open in the editor, the currently selected document(s) or the entire search result).

REST API

Independent of the Sophora connection the Metadata Supplier provides a REST API. The documentation can be reached at http://<host>:<port>/<context-path>/swagger-ui.html (see the log file of the Metadata Supplier at startup and Web Server Configuration).

The default Swagger UI path can be changed in the application.yml, e.g. to use http://<host>:<port>/<context-path>/sms-swagger-ui.html:

# Swagger UI
springdoc:
  swagger-ui:
    path: '/sms-swagger-ui.html'

Note that we provide a metadata-supplier-rest-example-client project which contains call examples for the REST interface.

Monitoring

The Sophora Metadata Supplier provides a web server that offers some endpoints for monitoring. The base URL for accessing data is http://<host>:<port>/<context-path>/actuator/ (see Web Server Configuration).

Health Checks

The health page indicates if the Sophora Metadata Supplier is running: /actuator/health. It provides JSON with a "status".

The Sophora component also provides information about the connection to a Sophora Server. This information can be accessed at /actuator/sophora.

Metrics

The Sophora Metadata Supplier offers some data for performance monitoring. The available metrics can be accessed at /actuator/metrics. To access the value of a specific metric add it to the path as follows: /actuator/metrics/name.of.metric.

The metrics are also available in Prometheus format at /actuator/prometheus. To use it see the example scrape_config in the Spring Boot Actuator Documentation for Production-ready Features.

JMX MBeans

Java Management Extensions (JMX) provide managed beans (MBeans) for management and monitoring applications. Jolokia is a JMX-HTTP bridge to provide those MBeans via HTTP. In the Sophora Metadata Supplier they can be accessed under the path /actuator/jolokia. For details of the API see Jolokia documentation.

Examples:

• list all available MBeans: /actuator/jolokia/search/*:*
• list attributes and operations of MBean "java.lang:type=Runtime": /actuator/jolokia/list/java.lang/type%3DRuntime
• show attribute "ThreadCount": /actuator/jolokia/read/java.lang:type=Threading/ThreadCount

Logging

Structured logging can be enabled by activating the json-logs profile.

In the application.yml:

---
# Application settings
spring:
  profiles:
    active: 'json-logs'

Or via VM argument:

-Dspring.profiles.active=json-logs

Web Server Configuration

The default port of the web server for the REST-API and monitoring is 8080 and the default context-path is empty. Both can be changed in the application.yml:

# Web Server
server:
  port: 8049
  servlet:
    context-path: '/sms'