UGC | Version 4

Multimedia service

As a separate application, the UGC multimedia service handles the task to manage multimedia data like audio or video


You can start the ugc multimedia service by executing ugc-multimedia.jar either directly or by calling java -jar ugc-multimedia.jar which is an executable. JVMARGS can be provided either as JAVA_OPTS in an ugc-multimedia.conf file next to the ugc-multimedia.jar or as part of the command when using java -jar ugc-multimedia.jar. The content of an ugc-multimedia.conf file might be:

JAVA_OPTS='-Xmx1g -Dlogging.config=/cms/ugc-multimedia/config/logback.xml -Dspring.config.location=/cms/ugc-multimedia/config/application.yml'

Starting the ugc multimedia service with java would look like this for the same properties:

java -Xmx1g -Dlogging.config=/cms/ugc-multimedia/config/logback.xml -Dspring.config.location=/cms/ugc-multimedia/config/application.yml -jar ugc-multimedia.jar

It is necessary to use a reverse proxy as described below and on the "Reverse Proxy" documentation page.


The configuration of the service is done with a file called application.yml. It's written in the commonly used YAML format. In this example all values are the default values.

      ddl-auto: <mode> # database intitialization mode, e.g. update (see Spring documentation for details)
    database-platform: <org.hibernate.dialect> # org.hibernate.dialect.MySQL5InnoDBDialect or org.hibernate.dialect.Oracle12cDialect
    database: <database-type> # type of database, either mysql or oracle 
    url: <url-to-database>
      # url to database which depends on the type of database, could be either jdbc:mysql://<host>:<port>/<db>?serverTimezone=UTC or jdbc:oracle:thin:@//<host>:<port>/<SID>
    username: <user> # user to access the database
    password: <pwd> # password of that user
    driver-class-name: <driver-class> # driver class to access the database, depends on type of database and may be either com.mysql.cj.jdbc.Driver or oracle.jdbc.OracleDriver 
      max-file-size: <file-size> # maximum size of a single file to upload, e.g. 20MB
      max-request-size: <request-size> # maximum size of all files uploaded in a single request, e.g. 20 MB
        include: 'Prometheus' # exposes the specified endpoint. Default: 'Prometheus'
      enabled: true # enables the Prometheus endpoint. Default: true

server : 
  port : <port> # port where the endpoints of the ugc multimedia service can be accessed
      urls: http://<host>:<port> # url to sophora servers the service should connect to, may be several to overcome a unreachable sophora server instance
      username: <sophora-user> # the user the service uses to login to sophora
      password: <sophora-pwd> # the password of the user
  type: fs # type of storage to use for the multimedia files. fs for filesystem and s3 for an s3 compatible storage is supported. One of the storage options has to be configured.
    fs: # configuration for fs storage type
    baseDir: <path> # path to the location where to store files, e.g. /binaries/
#  type: s3 # example configuration for s3 storage  
#  s3:
#    accessKeyId: <accessKeyId>
#    secretAccessKey: <secretAccessKey>
#    bucketName: <bucketName>
#    host: <host>

  allowedMimeTypes: # MIME types that might be uploaded. May be either a type or a type with a subtype (e.g. 'audio', 'audio/mpeg') and may also contain a suffix (e.g. 'image/svg+xml'). Default: 'audio', 'video'
    - <mimeType1>
    - <mimeType2>
  headlineProperty: <title-property> # the title that is displayed in the document overview  (sophora-content:title)
  # definition of the markers with which entries can be marked and filtered in the editorial-ui. The list can contain any number of entries
    - key: <key1> # unique key
      label: <label1> # the label
      colorValue: <color-value1> # a valid css color ("Red", "Blue", "#F0F8FF", ...) 
    - key: <key2>
      label: <label2> 
      colorValue: <color-value1>
auth: # when the following two properties are set, the requests of all endpoints starting with '/secure' will be protected with HTTP basic authentication
  username: <username>
  password: <password>
  clamdHost: <clamd host> # host of the clamd service to scan multimedia uploads for viruses
  clamdPort: <clamd port> # port of the clamd service to scan multimedia uploads for viruses
  timeoutInMS: <milliseconds> # timeout in MS of the connection to the clamd service
  clamdFileStorageDir: <path> # path of the location where the file to be tested should be stored, e.g. clamdTest/ After the scan the file will be deleted.
  httpStatusCodeForVirus: <HTTP code> # HTTP response code in case a virus is detected by the clamd service. Default is 200

    enabled: false # enables the clean up job. Default is false.
    cronSchedule: "0 59 * * * *" # the time at which the cron job is triggered. Default is 1 minute before the hour
    regexForBinaries: "[a-z0-9-]{36,}" # the regex to filter binaries to be deleted by the cleanup job. Default is the regex for UUIDs. 
    binaryWasAtLeastNotModifiedSinceHours: 72 # the hours since a binary file was last modified. Only binaries that have at least not been changed up to this configured point in time are deleted. Default is 72 hours.
    enabled: false # enables the clean up job for missing binaries. Default is false 
    cronSchedule: "0 59 * * * *" # the time at which the cron job is triggered. Default is 1 minute before the hour 
    minimumAgeInHours: 72 # the hours since metadata have been created. Only metadata that have been created at least the number of hours ago are deleted. Default is 72 hours.

  crossOriginUrl: "http://localhost:8080" # a url from which cross-origin requests are allowed. Default is "http://localhost:8080"

  allowedOrigin: http://host:port # an allowed origin of the websocket, which is used to check for new multimedia content of a UGC instance. Required only when running the ugc editorial UI with a reverse proxy. 

Clamd can be configured to scan uploads for viruses. If no configuration is made, there is no virus check and all files are uploaded to your storage.


The endpoints of the UGC multimedia service are documented by the interactive Swagger UI and are specified by the OpenAPI standard. It can be accessed at the URL http://<hostname>:<port>/swagger-ui.html. (With UGC versions before 4.3.0 it can be accessed at the URL http://<hostname>:<port>/api-ui/)

It is necessary to use a reverse proxy to distribute requests to the UGC multimedia service and the UGC Webapp. We provide example configurations for Nginx and the Apache HTTP Server on the "Reverse Proxy" documentation page. Ensure that requests to the following paths and all subpaths are forwarded to the multimedia service. See Swagger UI for a complete list of endpoints.

  • /public/binary
  • /public/multimedia
  • /secure/binary
  • /secure/multimedia
  • /websocket/multimedia

Additionally, HTTP basic authentication can be enabled for the /secure/ endpoints, as shown in the configuration section above.


The submission of multimedia is done via the endpoint "/public/binary/saveBinaryAndCreateMultimedia". In the body of the request, two request parts are used: the file, which can be an audio or video file, and a multimediaDto. The content type of the multimediaDto must be 'application/json' and accepts an object in the following format:

    "description": "string", 
    "externalId": "string", 
    "headline": "string", 
    "userId": "string", 
    "username": "string"

Below is an example of how to send a request to this endpoint from the frontend using JavaScript:

const multimediaFormData = new FormData();

multimediaFormData.append('multimediaDto', new Blob([
		], {
			type: "application/json"

multimediaFormData.append("file", $("#multimediaData")[0].files[0]);

				url: saveMultimediaObjectUrl,
				type: 'POST',
				data: multimediaFormData,
				dataType: 'json',
				processData: false,
				enctype: 'multipart/mixed',
				contentType: false

The multimedia entries submitted in this way can be managed via the editorial ui, which has a new tab in the "multimedia" navigation if the addon has been activated.


There are two storage options available. With type: fs multimedia files can be saved in the filesystem. type: s3 allows them to be uploaded to an s3 compatible cloud storage. One of both storage options has to be configured. You have to configure bucketName, accessKeyId, secretAccessKey and the host.

Last modified on 7/18/22

The content of this page is licensed under the CC BY 4.0 License. Code samples are licensed under the MIT License.