System-to-Person Automation API Guide

This guide is intended for developers who want to automate the creation of Media Shuttle upload and download links from within other systems, such as Media Asset Managers (MAMs), Digital Asset Managers (DAMs), and other third-party applications. These links let users upload or download content to and from Media Shuttle Share Portals.

Understanding System-to-Person API

The following diagram displays Media Shuttle’s key concepts.

Media Shuttle Relationship Diagram

Media Shuttle Terminology

Portal​: A URL that provides access to storage

Access Control:

  • People - Defined by roles
  • Links - Created by people or created programmatically as endpoints, e.g. tokens

Role: A grouping of permissions used to simplify task authorization

  • Portal Member - Performs transfers
  • Operations Administrator (or account admin?) - Manages portal members
  • IT Administrator (or portal admin?) - Manages infrastructure and security associated with portals

Link: A URL that points to a specific storage location

  • Download URL - Provides access to content via a package
  • Upload URL - Directs an upload to an empty package that has been created as a placeholder

Account: Represents a billing entity. Each account requires an API key.

Package​: Groups files, folders and metadata. In this context, a package is a pointer to content that can be found within a portal.

Completing Pre-requisites

Before you begin integrating Media Shuttle with your MAMs, DAMs, or other third-party applications, make sure you have these requirements in place:

For more information, see Getting Started with Media Shuttle API.

Establishing an Integrated Workflow

Integrating Media Shuttle distribution or acquisition workflows into your MAM, DAM or third-party application requires a maximum of four REST calls.

The following diagram shows the required commands and their sequence for a typical integration workflow:

A diagram explaining the system to person workflow

You can do a walk-through of these workflows by following the distribution/acquisition exercises.

Distribution Workflow

Media Shuttle can be used to assist distribution or ‘fulfillment’ workflows from MAM/DAM systems.

Diagram of Distribution Workflow

In this sample workflow:

  1. Files are made available within the Media Shuttle portal’s storage path.
  2. A Media Shuttle package is created and populated with files or objects, and a download token is generated.
    Note:​ Download tokens serve as pointers to content on disk. Generating a download token does not copy any content.
  3. A URL is sent to the downloader via a third-party email or another contact mechanism.
    Note: A separate URL is required for each intended recipient or download.
  4. The end user downloads via the URL. The token handles all authentication and authorization.
  5. Media Shuttle invokes a callback URL (optional).
  6. The system queries Media Shuttle for events associated with the package (optional).

Acquisition Workflow

Media Shuttle can be used to assist acquisition or ‘ingest’ workflows to MAM/DAM systems.

Diagram of Acquisition Workflow

In this sample workflow:

  1. A file landing place is chosen in Media Shuttle’s accessible storage.
  2. A placeholder Media Shuttle package is created within the portal’s storage. This step generates a URL.
  3. The system sends the URL to the uploader via third-party email or another mechanism.
  4. The end user uploads using the URL. The token handles all authentication and authorization.
  5. Media Shuttle invokes a callback URL (optional).
  6. The system queries Media Shuttle for events associated with the package (optional).

Adding Callbacks/Webhooks

Each time that you call the token endpoint, you have the option to provide a callback URL. This URL will be called upon successful upload or download.

To provide a callback URL, insert the following in the body of the token request:

"notifications":
[
{
"type": "webhook",
"url": "http://my.callback.url/..."
}
]

Currently, the only event that is enabled for callbacks/webhooks is the redemption event. This event is only triggered when there is a successful upload or download. If the upload or download fails, it is not considered redeemed.

For more information on callbacks, see Working With Webhooks.

Testing the API for a Distribution or Acquisition Workflow

You can test the System-to-Person Automation API for either a distribution or an acquisition workflow without writing any code. Before starting, make sure that you’ve completed the pre-requisite steps.

To test a distribution/acquisition workflow:

  1. Log into your Media Shuttle account.
  2. Obtain your API key by selecting the Developer menu option and copying your API key.
  3. Navigate to SwaggerHub.
  4. Click Authorize and enter your API key to authorize SwaggerHub to use your Media Shuttle credentials.
  5. In the Portals section, expand GET /portals to obtain the portal ID for the Share portal to which you have access.
  6. Click Try it out, followed by Execute.
  7. In the System-to-Person section, expand POST /portals/{portalID}/packages and create a new package. Your package will be part of the response body.
  8. For a distribution workflow, add content to the package.
    Note: Make sure you specify the destinationPath relative to the portal’s storage root. You can determine the portal’s root in Media Shuttle by examining the path setting.
  9. Expand POST /portals/{portalId}/packages/{packageId}/tokens and generate an upload/download URL for the package. The email address will be used for auditing purposes, regardless of who performs the upload or download that redeems the token.
  10. Test the upload/download URL by copying the URL from the response body into a browser.
  11. Query the activities associated with the package using GET /portals/{portalId}/packages/{packageId}/events (optional). The response from the query will allow you to build an audit trail of activity or create proof of delivery, if necessary.

Troubleshooting a Distribution Workflow

A Transfer failed error can occur within a distribution workflow when an incorrect path is specified. This error can also occur when content is deleted from the storage location.

To prevent this error, ensure that the content specified in the package remain in the storage location until the download token is redeemed.