Please click start to get a first introduction per video:
Broadcasters-training-video.mp4Welcome to the comprehensive setup and usage guide for ENAPSO together Free, specifically tailored for broadcasters. This document provides step-by-step instructions to get started with the Docker platform, from installation to managing your data with ENAPSO together free services.
Before you begin, ensure the following requirements are met:
Docker Installed: Docker must be installed and running on your machine to facilitate the deployment of applications within containers. For optimal performance and compatibility, ensure that your Docker installation is version 20.10 or above. To check your Docker version, open your command prompt or terminal and enter:
Internet Connection: Necessary to pull the Docker image from the repository.
Credentials: To request your username and access token for the ENAPSO together free platform powered by Innotrade, send an email to support@innotrade.de with the subject line "Request for Credentials." Optionally, you can include a message similar to the following as inspiration:
Open your command prompt or terminal. Log in to the Docker registry to access the ENAPSO together image using the following command:
docker login registry.innotrade.com -u [username] -p [Personal Access Token]
Replace [username]
and [Personal Access Token]
with your credentials.
Still, in your command prompt or terminal, pull the latest version of ENAPSO together free:
docker pull registry.innotrade.com/innotrade/enapso-together-free
Now, run the Docker container to deploy the platform locally using this command:
docker run -p 80:80 registry.innotrade.com/innotrade/enapso-together-free
This maps the container's port 80 to your local machine's port 80.
 Resolving Port Conflicts
when attempting to run the Docker container for the ENAPSO together Free platform, you have the following option to resolve it and access the service.
If port 80 is already in use on your machine, you can map the container's internal port (80) to a different port on your host. For example, if you choose to use port 8080 on your host, you can modify your Docker run command like this:
docker run -p 8080:80 registry.innotrade.com/innotrade/enapso-together-free
After running the Docker command with the new port setting, you'll need to modify how you access the service through your web browser. Simply add :8080
(or whatever port number you chose) right after localhost
in the URL. For example, to access the service, you would use:
http://localhost:8080/enapso-dev/view-management-service/api-docs/
This tells your browser to connect to the service at the new port you've set up.
 Run Docker Container with Triplestore UI Access
To run the ENAPSO together free platform and enable access to the triplestore UI for enhanced monitoring and management, use the following Docker command:
docker run -p 80:80 -p 3030:3030 registry.innotrade.com/innotrade/enapso-together-free
This command maps the container's port 80 to your local machine's port 80 for the main service, and port 3030 to your local machine's port 3030 for accessing the Triplestore UI. After executing this command, open your web browser and navigate to http://localhost:3030
. This URL will lead you directly to the Triplestore UI, where you can monitor the repositories or perform various administrative operations. This setup ensures comprehensive access to both the platform's services and its user interface.
To confirm that the Docker image is running correctly on your machine, use the following command in your command prompt or terminal:
This command will list all running containers. Please verify that the ENAPSO together free container appears in the list, it is active and running.
Access the Swagger documentation for ENAPSO together free services through your web browser:
To perform the following tasks, you need to clone the repository and run the setup script:
Upload the ontology file, for detailed instructions and a step-by-step process, follow the link: Upload the Ontology File.
Upload the demo data file, for detailed instructions and a step-by-step process, follow the link: Upload the Demo Data.
Create CRUD templates for the EditorialObject
class, for detailed instructions and a step-by-step process, follow the link: Create CRUD Templates.
Set up REST routes for the CRUD operations, for detailed instructions and a step-by-step process, follow the link: Set up REST Routes.
Follow these steps to set up the ENAPSO demo on your local machine.
Open a new terminal and clone the repository to your local machine by running the following command:
git clone https://github.com/innotrade/enapso-demo.git
This will download all the necessary files and scripts to set up the ENAPSO demo.
Navigate to the cloned repository directory
Run the appropriate setup script for your operating system.
For macOS and Linux
cd scripts
chmod +x setup_enapso_media_mac.sh
./setup_enapso_media_mac.sh
For Windows
cd scripts
setup_enapso_media_windows.bat
The setup script will perform the following tasks:
Upload the ontology file (ontologies/ebucoreplus.owl
)
Upload the demo data file (demo-data/editorialObject_demoData.ttl
)
Create CRUD templates for the EditorialObject
class
Set up REST routes for the CRUD operations
This guide outlines the steps to prepare and upload the EBUCorePlus
ontology to your graph database. For details, open the expanders.
 Uploading Your Ontology
Follow these instructions to ensure your graph database is properly set up to manage and utilize ontology data, from downloading the necessary files to configuring the upload through the GraphDB Management Service's endpoint.
Prepare Your Ontology File: Ensure the ebucoreplus
ontology file is saved on your local machine. You can obtain the EBUCorePlus ontology from the EBU GitHub repository. Once you open the link, you will see the content of the ontology file displayed. To download it, locate the Download
icon on the upper right side of the page and click on it. This will automatically save the file to the default download folder on your local machine.
Clone EBUCorePlus Repository: If you want to clone the entire repository, ensure that Git is installed on your computer. You can check this by running git --version
in your terminal. If Git is not installed, you will need to download and install it from the official Git website. Open your command prompt (CMD), and move to the directory where you want the repository to be cloned. You can do this by running the command cd path/to/your/directory
, replacing path/to/your/directory
with the path to the desired directory on your local machine. Once you're in the desired directory, run the following command to clone the repository:
git clone https://github.com/ebu/ebucoreplus.git
This will clone the entire ebucoreplus repository to your local machine.
Ensure Node.js is installed on your machine. If not, install it from the Node.js official website. This installation includes npm (Node Package Manager), which manages Node packages.
After installation, verify that Node.js and npm are successfully installed by doing the following:
Open a command prompt or terminal.
Run the command node -v
and press Enter. This will display the version of Node.js if it is installed.
Run the command npm -v
and press Enter. This will display the version of npm if it is installed.
For using the ENAPSO tools, it's important to have at least Node.js version 10 or higher, as earlier versions might not support some functionalities of the tools.
If you need to update Node.js to the latest version, you can download it from the official Node.js website and install it on your system. It will automatically replace the older version with the new one.
Install the enapso-graphdb-cli tool globally using npm:
npm install -g @innotrade/enapso-graphdb-cli
Open the terminal, and navigate to the directory where the ebucoreplus.owl
file is located, or set the file path in the --sourcefile
variable, and execute the following command to successfully upload the ontology
enapsogdb import --dburl "http://localhost/fuseki" --repository "Test" --sourcefile "ebucoreplus.owl" --format "text/turtle" --baseiri "http://www.ebu.ch/metadata/ontologies/ebucoreplus#" --context "http://www.ebu.ch/metadata/ontologies/ebucoreplus" --triplestore "fuseki"
Open the terminal and run the following curl
command which rebuilds the ENAPSO service cache with the latest data, ensuring efficient query performance and accurate auto CRUD template management by reflecting all recent changes.
curl -X POST http://localhost/enapso-dev/graphdb-management/v1/build-cache
Access Swagger Documentation: Navigate to the GraphDB Management Service in your web browser.
Upload the Ontology: Utilize the
endpoint to upload the ontology to the graph database repository.
Click the Try it out
button.
Fill out the following fields:
: Select and upload your
ontology file.
format: Specify the format as
.
baseIRI (Optional): Enter the base IRI for your ontology such as http://www.ebu.ch/metadata/ontologies/ebucoreplus#
. Using this base IRI helps ensure consistent referencing within your ontology. If you need to use a specific or different IRI, replace the default with your custom IRI. Enter the base IRI for your ontology.
context (Optional): Define the (also known as a named graph) for your ontology . The context is an identifier that organizes data within the graph database, such as http://www.ebu.ch/metadata/ontologies/ebucoreplus
. If the context field is left empty, behavior varies by triplestore:
In Fuseki, data will be added to the default context http://ont.enapso.com/default
.
In GraphDB by Ontotext, data will be added to the graph database's default context, as described in their documentation.
button:
Upon execution, the response will indicate that the ontology has been . You will see a message or a status code in the Swagger interface confirming the successful upload.
If you receive both HTTP 200
and HTTP 201
responses for similar requests, it means:
HTTP 200
is returned when you upload data that already exists in the graph database repository, indicating a successful overwrite.
HTTP 201
is returned when the upload adds new data to the graph database repository.
This guide outlines the steps to upload the demo data for the EditorialObject
to your graph database. For details, open the expanders.
 Upload Demo Data
Follow these instructions to effectively populate your graph databases with instances of the EditorialObject
within the EBUCorePlus
ontology, using either the GraphDB Management Service's provided API endpoints or the enapso-graphdb-cli
tool, which are explained below. Additionally, you can find the necessary TTL demo data here.
Refer to the prerequisite information above and follow the same procedure.
Refer to the installation information above and follow the same procedure.
Open the terminal, and navigate to the directory where the editorialObject_demoData.ttl
file is located, or set the file path in the --sourcefile
variable, and execute the following command to successfully upload the ontology
enapsogdb import --dburl "http://localhost/fuseki" --repository "Test" --sourcefile "editorialObject_demoData.ttl" --format "text/turtle" --baseiri "http://www.ebu.ch/metadata/ontologies/ebucoreplus#" --context "http://www.ebu.ch/metadata/ontologies/ebucoreplus/demodata" --triplestore "fuseki"
Access Swagger Documentation: Navigate to the GraphDB Management Service in your web browser.
Editorial Object Demo Data: The above attached file, named editorialObject_demoData.ttl
, contains the demo data for the Editorial Object.
Upload the Ontology File: Utilize the upload-ontology-from-file
to upload the demo data to the graph database repository.
Click the Try it out
button.
Fill out the :
: Select and upload your editorialObject_demoData.ttl
ontology file.
format: Specify the format as text/turtle
.
baseIRI (Optional): Enter the base IRI for your ontology such as http://www.ebu.ch/metadata/ontologies/ebucoreplus#
.
context (Optional): Define the context (also known as a named graph) for your demo data, such as http://www.ebu.ch/metadata/ontologies/ebucoreplus/demodata
.
Execute the upload by clicking the Execute
button.
Upon execution, the response will indicate that the ontology has been . You will see a message or a status code in the Swagger interface confirming the upload was successful.
If you receive both HTTP 200
and HTTP 201
responses for similar requests, it means:
HTTP 200
is returned when you upload data that already exists in the graph database repository, indicating a successful overwrite.
HTTP 201
is returned when the upload adds new data to the graph database repository.
This setion provides detailed instructions on how to generate CRUD (create
, read
, update
, delete
) templates for specific classes within your ontology using the View Management API. For details, open the expanders.
 CRUD Template Management
By following these steps, you can automate the creation of SPARQL templates that facilitate the management of instances of any specified class, such as the EditorialObject
from the EBUCorePlus
ontology. This process simplifies the implementation of CRUD operations in your graph database.
Access View Management API Docs: Use the link provided in the Swagger Documentation Access section.
Generate CRUD Templates: Find the
. This endpoint is used to automatically generate CRUD (
, read
, update
, delete
) templates for a specific class you specify in the POST body. For instance, if you pass the class http://www.ebu.ch/metadata/ontologies/ebucoreplus#EditorialObject
, the endpoint will create four SPARQL templates: readEditorialObject
, createEditorialObject
, updateEditorialObject
, and deleteEditorialObject
. These templates enable you to manage instances of the class easily, providing a streamlined approach to handle CRUD operations in your graph database.
Click the Try it out
button.
In the displayed POST body, you will find a JSON object with a cls
key. the http://ont.enapso.com/dotnetpro#Person
associated with cls
with the class IRI you intend to manage. For example, to manage the EditorialObject class, input: http://www.ebu.ch/metadata/ontologies/ebucoreplus#EditorialObject
.
After replacing the cls
default in the post body, click the Execute
to send the request.
Once executed, the response will confirm the creation of CRUD templates. You'll see a success message along with the names of the CRUD operations (,
read
, update
, delete
) for your class and their respective status codes.
After generating your CRUD templates, you'll need to use them to manage data. This section explains how to execute the
, create
, update
, and delete
templates for the EditorialObject
class. For details, open the expanders.
 Executing CRUD Operations
To view existing instances of the EditorialObject
class, follow these steps:
Access Template Execution API: Navigate to the API documentation where you can execute templates by name.
Prepare to Execute the Read Template:
Locate the
endpoint.
Click the Try it out
button to enable input.
Against the templateName
key, enter readEditorialObject
, which is the name of the read template for the EditorialObject
class.
Ensure that any existing variables
are cleared out before executing to avoid any unintended filtering.
Click the Execute
button to send the request.
Upon successful execution, the API will return a response displaying all instances of the EditorialObject
class. This verifies that the read operation is functioning correctly.
To create a new instance of the EditorialObject
, you'll need to understand the IRI
(Internationalized Resource Identifier), a unique identifier that ensures each instance is distinct and aligns with global web standards. If an IRI
is not provided, it automatically generates one to guarantee each instance's uniqueness. Alternatively, you can specify your own IRI
to maintain control over the identifier of your instance, adhering to standard HTTP practices.
Set Up Creation Request:
Go back to the execute-template-by-name
endpoint if you aren't already there.
Click Try it out
button again to set up a new request.
Enter createEditorialObject
against the templateName
key, which is the name of the create template for the EditorialObject
class.
Provide necessary variables
for the new instance. Typically, this would be in JSON format in the request's body, for example.
{
"title": "M - A City Hunts a Murderer",
"productionSynopsis": "Directed by Fritz Lang, this thriller is one of the earliest masterpieces of sound cinema, exploring themes of justice, vigilance, and societal response to crime.",
"shotLog": "Iconic scenes using shadows and sound to create suspense, notably the murderers eerie whistling of In the Hall of the Mountain King."
}
When you send a request to create a new instance, a unique IRI (Internationalized Resource Identifier) is involved. This IRI acts like a unique id for your instance that complies with global web standards.
If you do not provide an IRI, it automatically generates one for you, ensuring that each instance is uniquely identified. However, if you have a specific IRI you wish to use, you can include it in your variables
JSON object. This allows you to control the unique identifier of your instance, following the standard HTTP practices.
Click the Execute
button to send the creation request.
The response will confirm that the new instance has been successfully created. Look for a success message and any details provided about the newly created instance.
After creating a new instance of the EditorialObject
class, to if the record has been successfully created, you can follow these steps to verify the addition to the graph database:
Re-execute the Read Template:
Navigate back to the execute-template-by-name
endpoint in the View Management Service documentation.
Click the Try it out
button to enable input for a new request.
Against the templateName
key, enter readEditorialObject
again. This is the same read template you used earlier to view instances.
Click the Execute
button to send the request once more.
The response will now include the list of all current instances of the EditorialObject
class. Look through the list to find the newly created instance. You should see the details you entered for the instance, such as the label or any other identifiers, confirming that it has been successfully persisted in the database.
You can verify the changes made to the graph database r after performing CRUD operations provides an option to transparently.
To update an existing instance within your graph database, you first need to know you're targeting. This is where the IRI
(Internationalized Resource Identifier) comes in - it acts as a unique identifier, much like an id
for each instance. You can find the IRI
by reading the instances of the class you're interested in. Once you have the IRI
, it serves as an identifier to specify which instance to update. Along with the IRI
, you need to pass the properties and their new values that you want to update.
Access Update Template Execution:
Navigate to the execute-template-by-name
endpoint in the View Management Service documentation.
Click the Try it out
button.
Enter the name of the update template (e.g., updateEditorialObject
) against the templateName
key.
In the variables
object, specify the iri
you wish to update, which you can obtain through reading the instance data. Also, include the properties and their values you want to change. For example,
{
"iri": "http://ont.enapso.com/sparql-template#EditorialObject_bf161f6f-4b89-431f-8f83-eb7b51b9a89f",
"contentDescription": "In Berlin during the Weimar Republic, the police and the criminal underworld scramble to capture a child murderer who has caused panic across the city."
}
Click the Execute
button to send the update request.
The response whether the update was successful, including a confirmation message or status code. It's important to note that an HTTP 200
status is returned whether the specific instance whose IRI
was provided exists or not. This status also indicates successful query execution, not necessarily that any update was performed. Even if no update occurs due to specific conditions not being met, you will still receive a 200
OK, signifying that the query itself was processed without errors.
To delete an instance from your ontology, you need to specify to remove by using its IRI (Internationalized Resource Identifier). The IRI serves as a unique identifier for each instance and can be obtained by reading the instance data beforehand. Once you have the IRI, use it to indicate which instance you wish to delete.:
Access Delete Template Execution:
Go to the execute-template-by-name
endpoint in the View Management Service documentation.
Click the Try it out
button.
Enter the name of the delete template (e.g., deleteEditorialObject
) against the templateName
key.
In the variables
object, provide the IRI of the instance you wish to delete. For example,
{
"iri": "http://ont.enapso.com/sparql-template#EditorialObject_bf161f6f-4b89-431f-8f83-eb7b51b9a89f"
}
Click the Execute
button to send the delete request.
The response should confirm that the from the graph database repository. Even if the instance with the specified IRI
doesn't exist or if a delete wasn't performed due to certain conditions, the request will still return a 200
status code. This indicates that the query was executed successfully, even if no actual deletion occurred.
Congratulations on successfully setting up and starting to use the ENAPSO together Free platform for broadcasters. You've learned how to upload an ontology and , which are crucial for effective data handling within the platform.
As you continue to work with ENAPSO, explore further features and functionalities to enhance your data management capabilities. Remember, the documentation and support help you maximize the platform's potential.
Thank you for following this guide, and happy data managing!