Working with Kaltura Custom Metadata Fields

Working with Kaltura Custom Metadata fields

Custom Metadata is a feature of the Kaltura platform, which allows you to extend the metadata of Entries, Users, Categories, and more.
With Custom Metadata you can define custom fields for almost any object in Kaltura.
For example: The entry object by default has a title, description, tags, and categories.
If you need to add some custom fields such as the director of a film, or the year it was released – you should use Custom Metadata.

Custom Metadata is a natural extension of the Kaltura platform, and is 100% searchable and filterable.
Recently I was asked to explore the process of working with Kaltura Custom Metadata fields.
In this example I added custom metadata while creating media in Kaltura, and performed advanced searches on the data using custom metadata values.

This is not a complex task, but it should be done carefully step-by-step and that’s what I would like to discuss in this post.

Creating a custom metadata schema

First of all, you should add a new custom data profile in your KMC account.
It is done in Settings->Custom Data->Add New Schema.

custom metadata create

Then you should create the required fields and define various field properties such as field type, field description, field searchable properties and etc…
The fields will be accessible via a custom metadata profile id which is displayed at the Custom Data Schema table.

custom metadata details

As you can see, I’ve created a new custom metadata schema with 2 text fields named Test1 and Test2, which are set as searchable. The custom data schema id is 2712991. This is the id I will be using later to access the custom metadata. The id is obtained by calling the metadataProfile service and getting the profile ID.

Connecting to Kaltura

In order to start uploading content and creating entries, you should create a KS (Kaltura Session).

// The partner id and the secret located at
// Settings->Integration Settings at your KMC account
var partnerId = 'your partnet id'; //integer
var secret = 'your secret';
var userId = 'your user id';
var expiry = null;
var privileges = null;
var clientType = KalturaSessionType.ADMIN;

var config = new KalturaConfiguration(partnerId);
config.serviceUrl = 'http://www.kaltura.com';
var client = new KalturaClient(config);

// Start Kaltura session
var result = client.session.start(cbSessionStart, secret, userId, clientType, partnerId, expiry, privileges);

Creating an Entry

In order to add Custom Metadata to the Kaltura entry object, you should first create an entry of-course.
A code example for creating an entry:

//Creates new media entry
 var mediaEntry = new KalturaMediaEntry();
 mediaEntry.name = 'your media entry name';
 mediaEntry.description = 'your media entry description';
 mediaEntry.tags = 'tag1, tag2, tag3';

// this is a required field.
// Should be a proper uploaded media type
// (Can be VIDEO, AUDIO, or IMAGE)
 mediaEntry.mediaType = KalturaMediaType.IMAGE;

var results = client.media.add(cbAddMediaEntry, mediaEntry);

Adding content and metadata to the entry

Adding content and metadata to the newly created entry is done after creating an entry.
I chose to perform this actions at the callback function cbAddMediaEntry (var cbAddMediaEntry = function (success, results))

Adding content:

Adding content to the entry object is done by connecting the KalturaUploadedFileTokenResource and the entry.
First retrieve the uploaded file token id (which is received after uploading file to Kaltura)

Create KalturaUploadedFileTokenResource object and connect it to the entry (results.id stores the created entry id):

var uploadTokenId; // your uploaded file token id
 var fileTokenResource = new KalturaUploadedFileTokenResource();
 fileTokenResource.token = uploadTokenId;
 var result = client.baseEntry.addContent(cbAddContentToEntry, results.id, fileTokenResource);

Adding metadata to the entry is done by creating XML string according to the fields  you created earlier. Here i am adding some data to the Test1 field:

var xmlData = '<metadata><Test1>' + 'some data i want to add the the Test1 field' + '</Test1></metadata>';

var Metadata = new KalturaMetadata();
 var type = KalturaMetadataObjectType.ENTRY;

Metadata.objectId = results.id;
 Metadata.xml = xmlData;
 client.metadata.add(cbAddMetadata, 2712991, type, results.id, xmlData);

Filtering entries by custom metadata value:

// create a regular entry filter here
 var filter = new KalturaMediaEntryFilter();

// create an advanced search object
// here we will filter by custom metadata
 var filterAdvancedSearch = new KalturaMetadataSearchItem();

// assign your custom metadata profile id
 filterAdvancedSearch.metadataProfileId = profileId;

// type of the search (AND or OR)
 //filterAdvancedSearch.type = KalturaSearchOperatorType.SEARCH_AND;
 filterAdvancedSearch.type = KalturaSearchOperatorType.SEARCH_OR;

// object type is essential because of a bug in the Kaltura JS client library
 filterAdvancedSearch.objectType = 'KalturaMetadataSearchItem';

// now we define the search condition
 var filterAdvancedSearchItem = new KalturaSearchCondition();

// define the field we are searching with xpath
// Important note: do not change [local-name()='metadata'].
// The only name you need to change is [local-name()='Test1']
// setting 'Test1' to the name of your customdata field.
 filterAdvancedSearchItem.field = '/*[local-name()='metadata']/*[local-name()='Test1']';
 filterAdvancedSearchItem.value = 'your search value'; // assign value here

 // object type is essential because of a bug in js client library
 filterAdvancedSearchItem.objectType = 'KalturaSearchCondition';

/*
 // in case a second field is needed
 var filterAdvancedSearchItem2 = new KalturaSearchCondition();
 filterAdvancedSearchItem2.field = '/*[local-name()='metadata']/*[local-name()='Test2']';
 filterAdvancedSearchItem2.value = 'your search value'; // assign value
 filterAdvancedSearchItem2.objectType = 'KalturaSearchCondition';
 filterAdvancedSearch.items = [filterAdvancedSearchItem, filterAdvancedSearchItem2];
 */

// add the search items to the advanced search
filterAdvancedSearch.items = [filterAdvancedSearchItem];

// assign advanced search object back to the filter
 filter.advancedSearch = filterAdvancedSearch;
 // add the order by parameter (optional)
 filter.orderBy = '-recent';

// define the pager
var pager = null;
var result = client.media.listAction(cbEntriesList, filter, pager);

To conclude, custom metadata is a powerful tool for extending the basic metadata of the entry.
For more information please contact us at info@panda-os.com