Sophora Metadata Supplier for ARD Mediathek/Audiothek Administration

System Requirements

The Sophora Metadata Supplier for ARD Mediathek/Audiothek requires a current version of Java 11.

Configuration

The Sophora Metadata Supplier for ARD Mediathek/Audiothek uses the following configuration files:

• application.yml: This is the main configuration file.
• metadata-supplier-application-executable.conf (optional): Used to set the JVM properties (JAVA_OPTS) such as heap size and proxy settings.
• loader.properties (optional): Used for changing the folder of the mapping plugins.
• logback-spring.xml: Logging configuration.

The Sophora Metadata Supplier needs to be restarted for changes in any of these configuration files to take effect.

The main configuration of the Sophora Metadata Supplier is done in the file application.yml. Here you can see the default application.yml you may copy and adapt. See also section "Running with(out) Sophora" and "Triggering the Sophora Metadata Supplier" for examples.

# Default configuration to use the Metadata Supplier with Sophora as source system
---
# Application settings
spring:
  application:
    name: 'Sophora Metadata Supplier for ARD Mediathek/Audiothek'
    # Specifies the package of the spring-boot-sophora-commons for component scan.
    # Default is 'com.subshell.sophora.springbootsophoracommons'.
    # Set to empty if Sophora should not be used.
    spring-boot-sophora-commons-package: 'com.subshell.sophora.springbootsophoracommons'
    # Specifies additional base packages for component scan. Default is empty.
    spring-additional-base-packages: ''

# Sophora feature settings
# Note: Property 'spring.application.spring-boot-sophora-commons-package' must be set
# if any of these properties is set to true.
metadata-supplier-sophora:
  listen-to-document-changes: true
  enable-sticky-note-feedback: true
  attach-used-sources-to-sticky-notes: true
  sync-at-startup: true

# Sophora connection settings
sophora:
  client:
    server-connection:
      urls:
        - 'http://localhost:1196'
      username: 'admin'
      password: 'admin'
      retries: 60
      retryInterval: 20
    cache:
      publishedDocumentCacheElementsInMemory: 2000
      documentCacheElementsInMemory: 2000
    misc:
      dataDir: data
      jmxName: 'Sophora Metadata Supplier for ARD Mediathek/Audiothek'
    toolInfo:
      enabled: true
      name: 'Sophora Metadata Supplier for ARD Mediathek/Audiothek'

# ARD Mediathek/Audiothek connection settings
ardmedialibrary:
  credentials:
    username: 'username'
    password: 'password'
  imageService:
    url: 'https://deliver-test.ard.de/delivery-api'
  assetApi:
    url: 'https://deliver-test.ard.de/delivery-api'
  playerApi:
    url: 'https://deliver-test.ard.de/delivery-api'
  retry:
    # Number of max attempts to create/update a resource in the ARD Mediathek/Audiothek
    # in the case of a "Resource does not exist" error (must be at least 1)
    maxAttempts: 1
    # Delay between the retry attempts (in milliseconds)
    delayInMillis: 1000

Installation

The Sophora Metadata Supplier for ARD Mediathek/Audiothek is a Spring Boot application. It expects to find the configuration files next to the JAR file. So we recommend to put the executable application JAR and the configuration files into the same directory.

Recommended directory structure:

/cms
    /sophora-metadata-supplier
        /data
        /i18n
        /logs
        /plugins
        application.yml
        loader.properties
        logback-spring.xml
        metadata-supplier-application-executable.conf
        metadata-supplier-application-executable.jar

Starting and Stopping

The executable Metadata Supplier Application JAR file is a Spring Boot executable JAR. On Linux and MacOS, the Metadata Supplier can be started by running the executable JAR as follows:

./metadata-supplier-application-executable.jar

For running the Metadata Supplier as a background daemon, we suggest to create a systemd service as /etc/systemd/system/metadata-supplier-application.service. You may need to adapt the user (line 6) and path to the installation (line 7-8) according to your setup.

[Unit]
Description=Sophora Metadata Supplier for ARD Mediathek/Audiothek
After=syslog.target

[Service]
User=sophora
WorkingDirectory=/cms/sophora-metadata-supplier
ExecStart=/cms/sophora-metadata-supplier/metadata-supplier-application-executable.jar
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

More options are documented in the Spring Boot documentation.

JAVA_OPTS

Options for the Java VM, such as heap size and proxy settings, can be set using the environment variable JAVA_OPTS or using an entry in the metadata-supplier-application-executable.conf file. For example:

JAVA_OPTS="-Xmx1G -Dhttps.proxyHost=<...> -Dhttps.proxyPort=<...> -Dhttps.proxyUser=<...> -Dhttps.proxyPassword=<...> -Dhttp.nonProxyHosts=<...>"

To specify the default locale for i18n of messages, you also have to specify the user.language and user.country variables, e.g.:

-Duser.language=de -Duser.country=DE

Running with(out) Sophora

By default, the Metadata Supplier wants to connect to a Sophora Server as source system. You have to specify the connection data like the Sophora Server URL, user name and password as well as the connection data to the ARD Mediathek/Audiothek in your application.yml:

---
# Sophora connection settings
sophora:
  client:
    server-connection:
      urls: 'https://my-sophora-server:1195'
      username: '<sophora-username>'
      password: '<sophora-password>'

# ARD Mediathek/Audiothek connection settings
ardmedialibrary:
  credentials:
    username: '<ARD Mediathek/Audiothek username>'
    password: '<ARD Mediathek/Audiothek password>'
  imageService:
    url: 'https://server.ard.de/delivery-api'
  assetApi:
    url: 'https://server.ard.de/delivery-api'
  playerApi:
    url: 'https://server.ard.de/delivery-api'

If you do not use Sophora as source system, you have to disable loading Sophora components at startup. Just activate the no-sophora profile in your application.yml and provide the ARD Mediathek/Audiothek connection data:

---
# Application settings
spring:
  profiles:
    active: 'no-sophora'

# ARD Mediathek/Audiothek connection settings
ardmedialibrary:
  credentials:
    username: '<ARD Mediathek/Audiothek username>'
    password: '<ARD Mediathek/Audiothek password>'
  imageService:
    url: 'https://server.ard.de/delivery-api'
  assetApi:
    url: 'https://server.ard.de/delivery-api'
  playerApi:
    url: 'https://server.ard.de/delivery-api'

See the Operation Guide for further informations how to setup the workflow with Sophora.

Enable automatic retries

Behind the scenes, the ARD Mediathek/Audiothek consists of various services. For example, the images are managed by a different service than the shows. Unfortunately, it sometimes happens that when a resource is created in one service, it is not yet known that the resources needed for it have already been created in the other service. This case results in an error like this and the resource has not been created or updated:

ValidationException: Invalid imageCollectionId provided: 'urn:ard:image-collection:c98a5df133699de2'. Resource does not exist.

To avoid this problem, you can define in the application.yml that in such a case, after a few milliseconds, the Sophora Metadata Supplier should automatically try again to create or update the resource in the ARD Mediathek/Audiothek. This gives the different services the opportunity to synchronise.

# ARD Mediathek/Audiothek connection settings
ardmedialibrary:
  retry:
    # Number of max attempts to create/update a resource in the ARD Mediathek/Audiothek
    # in the case of a "Resource does not exist" error (must be at least 1)
    maxAttempts: 1
    # Delay between the retry attempts (in milliseconds)
    delayInMillis: 1000

Of course, the operation will continue to fail if all attempts are exhausted and the problem still remains.

Backup and Recovery

At start-up, the Metadata Supplier creates a "data" directory in which the last handled event date, usages and mapped resources are located. A backup of this directory should be made regularly in order to be able to restore the Metadata Supplier with this data if necessary.