Digital Marketing: Leveraging the HP MediaBin APIs: Part 2 – API Overview

In my last post, we saw a quick introduction to VMB Web services and looked at a few simple operations.  In this post, we’ll go through an overview of the VMB Web service API to give you a good understanding of how the API is organized, so you’ll have a better idea of the API calls used to accomplish some basic tasks.

 

Autonomy_MediaBin_616x254.jpgThe VMB Web service API is very extensive and covers nearly all the functionality available in the VMB Server.  In fact, the VMB Client uses this API exclusively; so if there’s something the Client does, you can be sure there’s an underlying set of API calls it’s using to perform that operation. 

 

There are over 200 available methods and they are organized into groups based on the type of object to which they apply.  If you’re familiar with the VMB Client, you already know about the many types of objects VMB manages: folders, collections, assets, tasks, etc.  The organization of the API follows this model very closely.  For example, there’s a set of API calls to manipulate VMB folders (“containers”), another set that applies to collections, still more that apply to searches and so on.  Below is a table summarizing the major categories of API calls:

 

Method Prefix

For

MBSession_...

Methods to manage the user’s context (login, logout, lightbox, etc)

MBContainer_...

Methods for manipulating a container (aka folder)

MBCollection_...

Methods for manipulating a collection

MBAsset_...

Methods for manipulating an asset

MBAsset_Revision_...

Methods for manipulating an asset revision

MBAction_...

Methods for manipulating an action

MBMetadata_...

Methods for manipulating a metadata definition (see MB_Object calls to manipulate an asset’s metadata)

MBTask_...

Methods for manipulating a task

MBTask_Revision_...

Methods for manipulating a task revision

MBObject_...

Methods applicable to multiple object types (e.g. both folders and assets)

 

In addition to these basic methods, the API also includes special streamer URLs used to retrieve asset previews and various other special-purpose items.

 

Working with Folders and Collections

As we discussed in the last post, Pagers provide the means to walk through the contents of VMB collections, folders, lists of tasks, metadata definitions, and so on.  They are a great way to enumerate the contents of a VMB object, and you’ll find specialized pagers for each object having contents. (Note that there’s no “Delete” call for a Pager; they are very lightweight and are automatically deleted when you log out.) The most common of the Pager calls are listed below. Of these, the most often used are the “Create” calls and “GetPageByIndex”.  The GetAllObjects call can be useful too, but only when you are certain the number of returns will be manageable (typically in the 100- 300 item range):

 

Method Category

Used for

MBPagerCache_Create…Pager

Create a pager to enumerate a list of assets, containers, collections, associations, tasks, metadata definitions, …

MBPagerCache_GetPage

Call this with the pager id to get a single page of objects (25 at a time)

MBPagerCache_GetPageByIndex

Call this with the pager id to get a single page of objects (variable page size)

MBPagerCache_GetAllObjects

Get all the objects from the pager at once. Use with caution.

MBPager_GetPage…

Less commonly used; Useful for getting a small, finite set of objects all in one call (e.g. associations, an enumerated list of assets). Use with caution.

 

MBSession calls

Apart from the login call, one of the most useful MBSession calls is “MBSession_GetMBObjectByPath”.  This call allows you to retrieve the internal GUID for a particular object from the MediaBin Server.  As you’ll find, virtually all of the web service calls require you to identify the object you wish to act on using this identifier.  For example, to enumerate the contents of a folder, you’ll need to provide the GUID of the folder.  The GetMBObject by path call is your means for recovering this GUID so you can use it in subsequent calls.  However, be cautious about how you use this call—use Pagers whenever possible rather than multiple calls to GetMBObjectByPath.

 

MBContainer calls

First, you might be a little confused that there’s no MBContainer call to return the assets in a container.  That’s because this function is served by the Pager calls.  Since a folder can contain thousands, or tens of thousands of assets, returning them in one call can be problematic.  So follow the example supplied in the last post by creating a Pager and retrieving the assets one page at a time.  The MBContainer calls are mainly used when you’d like to insert a new asset into VMB.  Since assets live in containers, the call to perform this operation is a container call. So simply retrieve the GUID of the container to which you would like to add the asset, then use the InsertFile (or InsertFileEx) call to accomplish the insertion.  Note that in each case the server requires a UNC path to the asset you’d like to insert, and this path must be visible to the VMB server.  When we discuss uploading assets, well cover the primary ways to move your files to the server and position them for ingestion.

 

MBCollection calls

The collection calls perform two basic functions: First, they manage content and security on collections.  Since collections are of two types (Static and Dynamic), they also manage the dynamic properties of a collection; namely they are utilized for searches, both ad-hoc and templated.  Search criteria are highly configurable and the search API in VMB is quite extensive – so much so that we’ll be covering this topic as a separate post.

 

MBAsset calls

The MBAsset calls manage all the properties of an asset in MediaBin; the exception being the asset’s metadata.  Metadata is managed by the MBObject series of calls. Because folders and assets can both have metadata; this allows one set of calls to handle both cases.  The remaining asset properties are managed by the MBAsset set of calls which include asset retrieval, revisions, associations, annotations, and previews.

 

Asset retrieval requires a little explanation as the return from the RetrieveFile calls is a MediaBin Job GUID.  This GUID identifies the retrieval job created by the RetrieveFile call, which must be monitored using the MBJob calls to check for completion.  Retrievals run asynchronously through the API, as a result the return of the RetrieveFile call only indicates that the request to retrieve the file has been processed, not that the retrieved file is available.

 

MBObject calls

This class of calls manages the common properties of assets, containers (folders) and other VMB objects.  These are the calls used to delete, copy, rename and move assets and folders from one part of the repository to another.   Another major use of this set of calls is to retrieve and set the metadata on both assets and folders.  The basic calls are MBObject_GetMetadataValue,  MBObject_GetMetadataValues and MBObject_ReviseMetadataValues, all of which process metadata in an internal structure.  While we will explore these calls in depth as part of a later post, I just wanted to point this out since new users tend to have a difficult time locating these calls.

 

MBMetadata calls

These calls are used to create new metadata definitions for subsequent use.   They are only rarely used in the context of custom development as in most installations the metadata can most simply be defined using the MediaBin Client’s UI.  Much more typical is the population of an asset’s metadata from a script, using the MBObject calls.

 

MBJob calls

Used to monitor VMB jobs to ensure their completion and verify their completion status (success or failure).  These calls are most commonly used after a request to download an asset has been submitted (via MBAsset_RetrieveFile) to monitor the progress of the associated download job until it completes.

 

MBAction calls

Used to create, monitor and manage a VMB workflow action.  These calls are also seldom used in the context of custom development as most VMB workflow actions are instantiated by users working from within the VMB Client.

 

Finally, a number of special purpose calls are present to manage revisions of tasks (MBTaskRevision) and assets (MBAssetRevision).

 

In our next several postings, we will do a deep dive into the most commonly used MediaBin APIs, including Search, Metadata and Download.   I will also be providing some example code to help you get started on your own projects.

 

If you've just joined us in this series, catch up and then follow along! 

Digital Marketing: Leveraging the HP MediaBin APIs: Part 1 - Getting Started

Digital Marketing: Leveraging the HP MediaBin APIs: Part 3 – Searching

 

#HPDMB

Comments
Peter Garcia | ‎04-01-2014 05:58 AM

Hi David, very nicely developed walkthrough of the API. Really liked that you went over the login and session concepts.

Can't wait for the next installment!

NickLeo | ‎04-01-2014 09:08 AM

This is a great explanation of the API calls. Very useful!

Todd Richardson | ‎04-02-2014 08:50 AM

Thanks for the overview. VMB web service API covers all core rich media management functions and then some. Example code would be helpful.    

 

Thanks!

Leave a Comment

We encourage you to share your comments on this post. Comments are moderated and will be reviewed
and posted as promptly as possible during regular business hours

To ensure your comment is published, be sure to follow the Community Guidelines.

Be sure to enter a unique name. You can't reuse a name that's already in use.
Be sure to enter a unique email address. You can't reuse an email address that's already in use.
Type the characters you see in the picture above.Type the words you hear.
Search
Showing results for 
Search instead for 
Do you mean 
About the Author
David Roy has over 27 years of experience in Software Engineering, with expertise in the areas of Digital Asset Management, Image Science an...
Featured


Follow Us
The opinions expressed above are the personal opinions of the authors, not of HP. By using this site, you accept the Terms of Use and Rules of Participation.