The Sophora Media Finder (for ARD Core) is intended to allow users at ARD to search for and choose media items from ARD Mediathek/Audiothek to use in their regional applications.
Users need to develop their own plugins to add custom functionality to it.
The function of the plugin is to work with the received items from the ARD API's, for example to create Sophora Documents or to perform additional lookups.
When the Media Finder application is run, the plugin is called whenever a mapping is requested.
Create a custom mapper plugin
To create a custom mapper plugin, a Java project with the following Maven dependency to the artifact media-finder has to be created. Note that we provide a media-finder-example-plugin project, which can be used as a starting point for your own custom mapper (GroupId: com.subshell, ArtifactId: media-finder-example-plugin).
<dependencyManagement>
<dependencies>
<!-- Media Finder -->
<dependency>
<groupId>com.subshell.sophora.mediafinder</groupId>
<artifactId>mediafinder-parent</artifactId>
<version>${sophora.mediafinder.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<!-- Sophora Media Finder -->
<dependency>
<groupId>com.subshell.sophora.mediafinder</groupId>
<artifactId>media-finder-mapper</artifactId>
<scope>provided</scope>
</dependency>
<!-- Optional Sophora Dependencies -->
<dependency>
<groupId>com.subshell.sophora</groupId>
<artifactId>com.subshell.sophora.client</artifactId>
</dependency>
<dependency>
<groupId>com.subshell.sophora</groupId>
<artifactId>spring-boot-sophora-commons</artifactId>
</dependency>
</dependencies>
In addition, in the sophora-media-finder-examples-parent directory of each release there is a zip file with a complete example project. This can be extracted and used as a first step to create your own plugin.
Create a launcher project
To start the Media Finder with your custom mapper plugin for development reasons from your IDE you have to use a launcher project. Note that we provide a media-finder-example-plugin-launcher project, which can be used as a starting point (GroupId: com.subshell.sophora.mediafinder ArtifactId: media-finder-example-plugin-launcher).
1. Create a new Maven project that is used as launcher project (e.g. media-finder-with-custom-plugin-launcher) with a dependency to metadata-supplier-application and your custom plugin project created above:
...
<artifactId>media-finder-with-custom-plugin-launcher</artifactId>
...
<dependencies>
<!-- Media Finder Application -->
<dependency>
<groupId>com.subshell.sophora.mediafinder</groupId>
<artifactId>media-finder-mapper</artifactId>
<version>${sophora.mediafinder.version}</version>
</dependency>
<!-- Your custom Media Finder plugin -->
<dependency>
<groupId>com.mycompany.mediafinder</groupId>
<artifactId>my-custom-media-finder-plugin</artifactId>
<!-- The development version of your plugin -->
<version>5.x.y-SNAPSHOT</version>
</dependency>
</dependencies>
...
2. Create (or copy) an application.yml to the root of your launcher project (next to the pom.xml) and configure it with your settings.
3. In IntelliJ IDEA (Eclipse IDE should be similar) create a launch configuration for the launcher project with the following settings:
- Name:
Sophora Media Finder with custom plugin(or similar) - Project:
media-finder-example-plugin-launcher(your launcher project) - Main class:
com.subshell.sophora.media.finder.application.MediaFinderApplication - Working Directory:
${workspace_loc:media-finder-example-plugin-launcher}(the launcher project root)
4. Finally run the launch configuration. The Media Finder should start with your settings and your plugin.
Create custom mappers
The Media Finder recognizes a mapper class by looking for two criteria. It needs to be a Spring component (with the @Component annotation) and it has to extend the IMediaFinderMapper interface. This generic interface can be used to create Sophora Documents. We provide an ExampleMediaFinderMapper in the sources JAR file of the media-finder-example-plugin project.
@Component
@Slf4j
public class ExampleMediaFinderMapper implements IMediaFinderMapper {
@Override MappingResponse mapItem(ItemResearchResource item) {
// To be implemented
}
}
MappingResponse, ItemResearchResource
The interface expects its users to return a MappingResponse. This datatype contains a list of SophoraDocuments represented in SophoraJSON and an error message that can be set if the mapping was not successful.
It takes in an ItemResearchResource, which contains various information about the context and comes from the ARD Asset Research Service.
From there, the plugin can generate arbitrary Sophora Documents. Those are passed as a List of maps in the field "sophoraDocuments" in the MappingResponse.
# Example MappingResponse JSON
{
"sophoraDocuments": [
{
"sophora:externalId": "myExternalId",
"jcr:primaryType": "sophora-content-nt:video",
"sophora-content:title", "My Title"
}],
"errorMessage": "An error occurred during mapping of additional documents."
}
Mapping Images
To map images to Sophora documents via the plugin, the IMediaFinderImageDataRetriever interface can be used. This has two methods, getImageCollectionById and getBinaryDataOfImage. Using getImageCollectionById, you can get the ImageCollection from the ARD image service. With getBinaryDataOfImage, on the other hand, you get the base64 encoded image data for a specific image width. This data can then be used to create image documents in Sophora.
Sophora Connection
Most likely you will want to connect to a Sophora instance, e.g. to perform lookups. To do that, use SBOC and the client in your plugin.
Add both dependencies to your pom.xml, as shown in the optional part above. Also, add an additional component scan to your application.yml that contains the SBOC package name (com.subshell.sophora.springbootsophoracommons).
The Sophora client connection also needs to be configured via the application.yml:
# Scan for the SBOC Package
spring:
application:
spring-additional-base-packages: 'com.subshell.sophora.springbootsophoracommons'
# Sophora connection settings
sophora:
client:
server-connection:
urls: ['http://localhost:1196']
username: 'user'
password: 'password'
Install a custom mapper plugin
The Administration overview contains a more detailed guide on installation.
When the Java project with the custom mapper(s) is built, the result has to be a JAR that includes all its dependencies (jar-with-dependencies). Then place your built plugin JAR in the plugins folder which is located next to the Media Finder Application JAR file.
If you created your mapper implementation in another package other than com.subshell.sophora.media.finder, you have to configure that in your application.yml.
---
# Application settings
spring:
application:
spring-additional-base-packages: 'my.custom.package.name'
Create a docker image
The Media Finder Docker Image can be used to create your own custom docker image. The working directory of the base image is the /sophora folder, where the application.yml file must be copied to. The subdirectory plugins must be filled with your custom mapper plugin from the previous step. That's all and your Dockerfile should look like this:
ARG SMF_TAG
FROM docker.subshell.com/media-finder/media-finder:$SMF_TAG
COPY application.yml .
COPY your-custom-mapper-plugin-jar-with-dependencies.jar ./plugins/
Now, run your own Media Finder Docker Container with this image and enjoy the working Media Finder Application wherever you want.
