Page History: MetaService 1.0 : Home
Compare Page Revisions
Page Revision: 2009/05/16 00:53
Welcome to Company Webcast's Meta Service
The Cwc MetaService is a
Soap 1.1 secure webservice that allows clients to find webcasts and retrieve their metadata, binaries and mediastreams.
Essentially the metadata describes in as much detail as available the "events" as they occured in real time,
at the time of the live webcast.
So for example, the metadata for any given webcast might contain a list of Speakers that were active during the webcast.
For every Speaker the metadata will then contain a list of "Events", where the Event's Start and End time describe when the Speaker was active.
The metadata also contains links to relevant binaries like media streams, mp3's and PowerPoint slides, and we provide mechanisms for downloading them, or publishing them directly within the context of your own application.
Example usage scenario's
- Include a list of upcoming webcasts in your website
- Add a list of video fragments to speaker's homepages
- Build a front end for WebcastSearch and let users search through your webcasts
- Retrieve metadata and binaries for your archive or integration with existing data/indexing/search solutions
- Create your own playback experience with full synchronization of slides, speakers, annotations and topics
- Dynamically create compilations of fragments based on topics or speakers
Getting started
The MetaService is a
Soap 1.1 web service that uses "Transport" security.
In Soap, clients and services communicate with each other using XML messages, and Transport security means they can only do it over SSL.
Soap services, like the MetaService, often use the
Web Services Definition Language (WSDL) standard to explain to the world what input they require, and what data the client can expect in return.
The WSDL file for the MetaService is available at this Url:
https://services.companywebcast.com/meta/metaservice.svc?wsdlA WSDL file is not necessarily formatted to be easy to read by people, you would normally use it with tools in your IDE or platform that do know how to read such a file, and these can then help you (a lot) with a client implementation.
The MetaService exposes 2 basic methods:
Typically a client would call WebcastSearch to retrieve WebcastSummaries, which give some basic info about the webcasts that match the search parameters. A client would then use elements from a WebcastSummary as input parameters for a call to WebcastGet. WebcastGet returns a Webcast object, which contains detailed information about a single webcast, in a single language.
A client has to authenticate against the MetaService by providing a username and password in every call.
If you have an account that gives you access to the CWC Webcast Management System, you can use that. However, we recommend you request an account specifically for consuming the MetaService. Requests for accounts can be sent to
Lars.Jilesen@companywebcast.com.
For testing purposes you can use the user "testusername" with password "testpassword".
Creating a client
In essence a Soap service, such as the Cwc MetaService, is a web service to which a client has to POST a specifically formatted HTTP Header and XML message, to in turn retrieve XML containing the data a client is after.
To implement a client that consumes the MetaService, it would therefore suffice to manually craft the request message, post it to the service and deserialize the XML response.
However, it's often much more convenient to use code generating tools that are built into IDE's, part of your platform, or exist as standalone applications. We have tested various platforms and IDEs against the MetaService, and all make implementing a client trivial.
Check the links below for sample code and some discussion about ways to consume the MetaService with different platfoms. Please note that in most cases these were created without deep knowledge of the actual platform, so better solutions may exist. In all cases sample code is provided for demo purposes only, they are not production ready.
Important note:
Do not create a browser based client (Flash, Silverlight, Java Applet) that contains your Webcast Management System username and password. If you are looking to implement something like this, please request a new account specifically for the MetaService from
Lars.Jilesen@companywebcast.com, and consider these new account details, and all metadata, binaries and streams that this account has access to, as being in the public domain.
Using WebcastSearch and WebcastGet
The MetaService exposes 2 methods that you can use to find webcasts and retrieve their metadata.
Typically a client would call WebcastSearch to retrieve WebcastSummaries, which give some basic info about the webcasts that match the search parameters. A client would then use elements from a WebcastSummary as input parameters for a call to WebcastGet. WebcastGet returns a Webcast object, which contains detailed information about a single webcast, in a single language.
Input parameters:
Username
Required, a string. The user name provided to you by Companywebcast that allows access to the Webcast Management System, or was specifically created for consuming the MetaService.
Password
Required, a string. The password provided to you by Companywebcast that allows access to the Webcast Management System, or was specifically created for consuming the MetaService.
OwnerName
Optional, a string. The (partial) name of the person or organization that commissioned the Webcast. Do not set OwnerName to search in all Webcasts your MetaService account has access to.
TopicTitle
Optional, a string. The (partial) title of a topic that was discussed during a Webcast.
SpeakerLastName
Optional, a string. The (partial) last name of a speaker who was present during a Webcast.
WebcastTitle
Optional, a string. The (partial) title of a Webcast.
PeriodFrom
Optional, a DateTime/Calendar. The date at which to start WebcastSearch. Older webcasts will not be returned. Note that all dates and times used throughout the MetaService are UTC. You will have to compensate for your timezone when working with any DateTime in the MetaService.
PeriodTo
Optional, a DateTime/Calendar. The date at which to end WebcastSearch. Newer webcasts will not be returned. Note that all dates and times used throughout the MetaService are UTC. You will have to compensate for your timezone when working with any DateTime in the MetaService.
Status
Optional, an enumeration of type WebcastStatus. Multiple values can be set.
PageSize
Optional, an integer. The maximum amount of results returned by WebcastSearch. Note that WebcastSearch can not return more than 100 results per call, and attempting to do so will result in an error.
PageNumber
Optional, an integer. The amount of results returned by WebcastSearch is less or equal to the value of PageSize, with a maximum of 100. If more results are available they are spread out across Pages, which you can navigate with PageNumber. The first page is 0.
returns:
WebcastSearchResult
An integer that indicates the success or failure of your WebcastSearch request.
It can have one of the following values:
0 = success
Positive (= client error):
2 = Page size exceeds 100
3 = Not authorized
Negative (= server error):
-1 = Server error
-2 = Service temporarily offline
WebcastSummaries
A list of WebcastSummary objects. A WebcastSummary object contains basic information about a Webcast, and elements you need for WebcastGet.
Input parameters:
Username
Required, a string. The username provided to you by Companywebcast that allows access to the Webcast Management System, or was specifically created for consuming the MetaService.
Password
Required, a string. The password provided to you by Companywebcast that allows access to the Webcast Management System, or was specifically created for consuming the MetaService.
Id
Required, a string. Uniquely identifies the Webcast for which you want to retrieve metadata. To find out what the Id of a Webcast is, call WebcastSearch to retrieve a WebcastSummary and use its Id property.
Language
Optional, a string. The language for which you want to retrieve metadata. To find out which languages are available for a Webcast, call WebcastSearch to retrieve a WebcastSummary and use its Languages property. If you don't set a language, the default language will be returned.
returns:
WebcastGetResult
An integer that indicates the success or failure of your WebcastGet request.
It can have one of the following values:
0 = success
Positive (= client error):
1 = Invalid Webcast Id
3 = Not authorized
Negative (= server error):
-1 = Server error
-2 = Service temporarily offline
Webcast
A Webcast object. The Webcast object contains detailed information about a Webcast.
Understanding the Webcast security model
Many Webcasts are configured to limit access in some way, and these limitations apply to the MetaService's data and underlying binaries like pdf files and media streams as well.
The Webcast object you retrieve when you call WebcastGet contains Urls to binaries and mediastreams. You can download the files at those Urls, or link to them directly from within your own application, as long as each request for a Url includes a valid authorization cookie.
MetaService clients and users receive this authorization cookie by visiting the Url in Webcast.RegisterUrl.
The application at Webcast.RegisterUrl is our gatekeeper, and it provides access with 3 seperate scenario's in mind:
- Publish a link to the Company Webcast Player
When a webcast has access limitations configured:
When a user clicks on RegisterUrl he is presented with an authentication form. Once the form is completed the user is redirected to the Companywebcast Player.
When a webcast has no access limitations:
When a user clicks on RegisterUrl, he is redirected to the Companywebcast Player.
- Publish a link directly to a binary or media stream
When a webcast has access limitations configured:
You can build completely custom end user experiences by using the Urls to streams and binaries directly in your own application. However, the user interface of the authorization process is always hosted by Companywebcast. Depending on the type of access limitations applied to a Webcast, you may have to implement some kind of overlay that displays the form at Webcast.RegisterUrl.
The default behaviour of Webcast.RegisterUrl is to display a form, and after successfull completion, redirect the user to a Companywebcast Player. You can override where the user is redirected after successfull completion, and in stead redirect the user to a page within your own application.
You do this by formatting your call to RegisterUrl like this : Webcast.RegisterUrl?ref=http://yoursite/yourfile
When a webcast has no access limitations:
Use the Urls to streams and binaries directly in your application.
- Retrieve binaries to local storage
Your MetaService client can use the Urls to binaries and mediastreams to retrieve and store files locally. For this to work your client will have to send a valid authorization cookie along with every request for a binary or mediastream. Because webcasts may have access limitations in place that require interactive input from the user, we've provided to "known" users a way of retrieving an authorization cookie directly.
You can retrieve a valid cookie per Webcast by POSTing your MetaService account details to Webcast.RegisterUrl.
Your account details have to be formatted like this : Username=YourUsername&Password=YourPassword
This is an example of a valid request to Webcast.RegisterUrl:
POST /rotterdam/20090409_1/nl/authenticate/register HTTP/1.1
Accept: */*
Content-Length: 32
UA-CPU: x86
Accept-Encoding: gzip, deflate
User-Agent: Jakarta Commons-HttpClient/3.1
Host: player.companywebcast.com
Connection: Keep-Alive
Cache-Control: no-cache
Username=testusername&Password=testpassword