Integration Strategies

From Wiki
Jump to: navigation, search

Contents

Service Account

A Service Account mechanism can be used to integrate an external platform where users are authenticated, and where user accounts match up precisely with Ensemble Video user accounts. The Service Account is simply an internal Ensemble Video user account that has elevated privileges and can access content on behalf of other user accounts via a "User" filter parameter.


Typically, an administrative interface in the external platform or environment is implemented where three things are specified:

  • Ensemble Video instance - specifies the DNS name of an Ensemble Video instance where API calls will be made (e.g. ensemble.institution.edu). This is used to construct the base uri for API requests.
  • Service Account username and password - these are the credentials for the account used to query the Ensemble Video API, filtering results for the currently authenticated user in the integrating platform.
  • Domain - identifies the Identity Provider for accessing user information for when individual user accounts are based on an LDAP or Shibboleth Identity Provider. This is typically appended to the value sent in the "User" filter parameter.


When an authenticated user in the integratingplatform needs to interact with their Ensemble Video data, the platform willuse the above configuration settings to query the Ensemble Video API on behalfof that user. As mentioned above, the implicationis that the user accounts in both platforms match, although this is usually thecase when both platforms connect to the same user directories (e.g. LDAP,Shibboleth).


Since the Service Account option is most useful for server to server communication, the Service Account in this case is typically an Ensemble Video internal account with Institution Admin or Organization Admin permissions, and Basic Authentication is used to authenticate to the API. The elevated role ensures that the Service Account has access to the same data that each individual user has. User filtering is then used to limit query results in order to access the current user's Organizations, Libraries, Playlists and Media Workflows.


For example:

https://test01.ensemblevideo.com/api/libraries
(returns libraries for the Service Account)


https://test01.ensemblevideo.com/api/libraries?user=jdimaggio
(returns libraries for the Service Account, limited to only those results that the internal Ensemble Account user jdimaggio can access)


https://test01.ensemblevideo.com/api/libraries?user=jdimaggio@institution.edu
(returns libraries for the Service Account, limited to only those results that the user jdimaggio, in the Identify Provider with the “institution.edu” domain, can access)


Use Case

The most common scenario for external integration is to create an interface where a user can navigate the Organization/Library structure of Ensemble Video, enabling access to whatever Organizations and Libraries the user has access to when logged into Ensemble Video.


Once a particular library has been selected, a typical integration then enables display or search and access of content via Playlist, Media Library, or Shared Library. Or it may enable selection of Media Workflow, then build provide a UI upload element to enable the user to upload media.


A completed Javascript module which performs all of these functions can be downloaded and examined or extended, as needed. You can find the module here: https://github.com/ensembleVideo/ev-script


Ensemble Video Javascript module - user interface

Ev-script-screenshot.png


Sample API Calls

There are a variety of variations on the scenario described above, for enabling navigation and access to content via API calls. But the sample API calls and related actions below should give you a good idea for how to enable API-based user navigation and access to media, or Media Workflow access and upload.


  1. Use the "currentuser" API call to get the "home" Organization and Library for the user.
    https://test01.ensemblevideo.com/api/currentuser&User=<user@domain>
  2. Get a list of Organizations for this user.
    https://test01.ensemblevideo.com/api/organizations?pageindex=1&pagesize=9999&User=<user@domain>
  3. Get the Libraries in the user’s home Organization.
    https://test01.ensemblevideo.com/api/libraries?pageindex=1&pagesize=9999&filteron=Organizationid&filtervalue=<OrganizationID>
  4. Display a dropdown menu with access to all available Organizations and Libraries, but with the “home” Organization and Library selected.
  5. Display content from the home library, list of Playlist or Media Workflows. Examples:
    • Get a list of 10 most recently added videos in the user’s home library
      https://test01.ensemblevideo.com/api/content/<LibraryID>?pageindex=1&pagesize=10&User=<user@domain>
    • Get a list of 10 most recently added videos for a given Playlist
      http://test01.ensemblevideo.com/app/simpleapi/video/list.xml/<PlaylistID>?resultsCount=10&User=<user@domain>
    • Search home library and find 1 page worth of search results
      https://test01.ensemblevideo.com/api/content/<LibraryID>?pageindex=1&pagesize=10&FilterValue=<search string>&User=<user@domain>
    • Searching Playlist
      http://test01.ensemblevideo.com/app/simpleapi/video/list.xml/<PlaylistID>?searchString=<searchstring>&resultsCount=10&User=<user@domain>
    • Show available Media Workflows
      https://demo.ensemblevideo.com/api/MediaWorkflows?FilterOn=LibraryID&FilterValue=<LibraryID>&User=<username@domain>


Using the Ensemble Video HTML Plug-in

If your integration enables users to click on individual videos in a listing and view that content, then we always recommend using the Ensemble Video Embed code and HTML Plugin-in to embed that content. The Plugin should also be used for whenever you enable users to embed a Playlist.


The HTML Plugin-in has quite a few parameters and options. All you need to do is add the Playlist ID (for Playlist embeds) or Content ID (for single video embeds) and wrap the embed code around that ID.


Playlist Embed

<iframe id="ensembleFrame_{playlist_id}"
        src="https://test01.ensemblevideo.com/app/plugin/embed.aspx?DestinationID={playlist_id}&isResponsive=true"
        frameborder="0" style="width: 800px; height : 1000px;" height="1000" width="800" allowfullscreen>
</iframe>


Individual Video Embed

<iframe id="ensembleEmbeddedContent_{content_id}"
        src="https://test01.ensemblevideo.com/app/plugin/embed.aspx?ID={content_id}&displayTitle=false&startTime=0&autoPlay=false&hideControls=false&showCaptions=false&width=640&height=360&displaySharing=false"
        frameborder="0" style="width:640px;height:416px;" height="416" width="640" allowfullscreen>
</iframe>


The HTML Plugin-in code is a Javascript module that automatically detects the viewers device and inserts the proper player and calls the correct streaming protocol from the Wowza Media Server. By using the Ensemble Video HTML Plug-in code in your embeds, you can easily deliver content to wide ranging devices with minimal coding.