BrandMaker MediaPool WebHook Consumer Example
Motivation
In order to synchronize contents and assets, which are stored in BrandMakers DAM Solution "Media Pool", a powerfull WebHook integration is offered.
To register and retrieve events from this integration, integrators need to implement a REST endpoint to capture the POST data and pull the according information from the MediaPool API.
Scope
This repository contains a blue print for a webhook, which is capable of the following:
- ✔️ register for events like "PUBLISHED" or "DEPUBLISHED"
- ✔️ retrieve the POST message for the events
- ✔️ validate POST data
- ✔️ Add a job to an internal processing queue
- ✔️ Within the queue listener
- ✔️ pull asset metadata from Media Pool via REST API
- ✔️ pull binary of requested version and rendition from REST API
- ✔️ store binary to local file system
- ✔️ store metadata as JSON to local file system
Prerequisits
Environment
- Java >= 9
- Spring https://spring.io/
- ActivMQ https://activemq.apache.org/
- Eclipse / IntelliJ
- Maven
- Github
BrandMaker Media Pool
Please make yousrself familiar with the basic principles of Webhooks. There are two comprehensive and recommended introductions available here:
Furthermore, to understand how BrandMaker Media Pool is making use of this kind of loosely coupled integrations, read the tutorial available here https://github.com/brandmaker/MediaPoolWebHookConsumer/blob/master/Media-Pool_WebHook-Push-API-Description_6-6_EN_20200203.pdf
Authentication
BrandMaker releases prior to 7.0 need Basic Authentication. Please provide a user id and a password within the application.yaml file for these versions.
With LTS release 7.0 and newer, please use CAS in order to authenticate via oAuth2 access tokens. In order to retrieve those tokens, follow the guideline available on https://developers.brandmaker.com/guides/auth/ and the following steps:
- Register your client in the administration (Fusion / Registered Apps)
- Authenticate a user via usual oAuth2 web flow, i.e. with "postman"
- Store the tokens etc. into a JSON file in the working directory of the running application
- Configure the file in the application.yaml and uncomment userid and password
Example of a credentials JSON file:
{
"server" : "https://cas.brandmaker.com/api/v1.1/token",
"clientId" : "9d4 ... ca",
"clientSecret" : "1 ... Eo",
"accessToken" : {
"token" : "__--CAS--__uXWiXloK6Y3fA j.. .y6durAClyKMmlyclfDgb19Od6M8s8",
"expires" : "2022-08-04T08:43:52Z"
},
"refreshToken" : {
"token" : "__--CAS--__UlrLUt_yPjqtY. .. .MeUDhocmE9DN6wUVnmX6XNPvkepQTXsCk",
"expires" : "2023-08-04T07:43:52Z"
}
}
General Concept
According to the recommendations to not to process the events immediately within the hook itself, the structure of a basic consumer looks like
The processing queue in the above flow chart will be implemented with the use of Spring JMS and ActiveMQ. In order to make this example as stand alone as possible,
we will use the embedded broker of ActiveMQ. Any available broker can be configured through the application.yaml
file. The internally used broker wille be configured persistant.
The queue topic can be configured within the application.yaml
as well.
On https://codenotfound.com/spring-jms-activemq-example.html you will find further information on how to integrate Spring JMS and ActiveMQ.
The effective processing of the event (i.e. picking up meta data and binary from Media Pool via REST API etc.) takes place in the queue listener.
Usage
Build
Within the root directory of your project, run mvnw clean package
and mvnw javadoc:javadoc
Test
In order to test your Media Pool Webhook, open a CLI in the root directory of your project and start springboot with
java -Dserver.address=0.0.0.0 -jar target\webhook.consumer-0.0.1-SNAPSHOT.jar
Access to the Webhook: POST to http://localhost:8080/hook
Api Documentation and test client generated with open-api and swagger-ui: http://localhost:8080/api-docs.html
Project state
Further Information
Reference Documentation
For further reference, please consider the following sections: