System-to-Person Automation API

The Media Shuttle System-to-Person API is used to integrate Media Shuttle with Signiant Manager+Agents, Media Asset Managers (MAMs), Digital Asset Managers (DAMs), and other third-party applications. The API allows applications to generate single-use links allowing users to upload or download content to and from Media Shuttle portals.

Conceptual Overview

In order to use the System-to-Person API, it is important to understand the overall relationship between Media Shuttle concepts and terminology.

Relationship Model

Media Shuttle Relationship Diagram

Media Shuttle Terminology

Actor

The person or application using the API to generate an upload or download link. Actors are granted permission to generate a link via access control which is controlled through the specific portal used in the transfer.

Account

The overall organization associated with all portals. Each account is associated with API keys that provide access to the API.

Portal​

A URL associated with an account that provides access to storage via access control. A single account can be associated with many portals.

Storage

An on-premises or cloud-based location that contains files or objects used in transfers:

  • File storage
  • Amazon S3 storage
  • Microsoft Azure Blob storage

Access Control

Roles and links associated with a portal that provide access to storage, control over access to storage, and control over the account.

  • Roles: A grouping of permissions that organize task authorization
    • Portal Member - Uploads and downloads files and folders from storage
    • Portal Administrator - Manages portal membership and who has access to upload and download content
    • Account Administrator - Manages IT infrastructure, storage, and security associated with all portals associated with the account

  • Links: Single-use URLs that provide access to transfer files to or from a portal’s associated storage
    • 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

Transfer

The upload or download action associated with a link. Once a transfer happens, the link is marked as redeemed and can no longer be used.

Package

A grouping of files, folders and metadata associated with a transfer located within storage. Download packages contain content from storage. Uploads allow the user to add content to storage.

Content

The files, folders, and metadata contained within a package.

Prerequisites

Before you begin integrating the System-to-Person API, make sure you have these requirements in place:

  • An active Media Shuttle subscription with a license for the System-to-Person Automation API
  • An API key ) from your Media Shuttle account
  • A working Media Shuttle portal, with unauthenticated links enabled for Upload and Download
  • Access to the IT Administrator console and the Portal Administrator console for the portal

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

Establishing a Workflow

Integrating Media Shuttle download or upload workflows requires a series of REST calls. In addition to providing access to storage, the API can be used to query the portal for events associated with the transfer and invoke a webhook when the transfer completes.

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



Acquisition Workflow

Media Shuttle can be used to acquire or file ingestion workflows:

Diagram of Acquisition Workflow

In this sample workflow:

  1. The system generates a request to generate a package.
  2. Media Shuttle generates a placeholder package within the portal’s storage, generating a URL.
  3. The system sends the URL to the user, which handles all authentication and authorization.
  4. The user accesses the URL and adds files and folders to the package.

Distribution Workflow

Media Shuttle can be used to distribute files for fulfillment workflows:

Diagram of Distribution Workflow

In this sample workflow:

  1. Files are made available within portal storage.
  2. A Media Shuttle package is created and populated with the available files, generating a URL.
  3. The system sends the URL to the user, which handles all authentication and authorization.
  4. The user downloads files and folders associated with the package via the URL.

Download tokens serve as pointers to content on disk, and do not copy any content. A separate URL is required for each intended recipient or download.

Adding Callbacks/Webhooks

API events can also use callback URLs that can be invoked when transferring files.

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 transfer. If the upload or download fails, it is not considered redeemed.

For more information on callbacks, see Working With Webhooks.

Using the API for an Acquisition or Distribution Workflow

You can use the System-to-Person Automation API for either an acquisition or distribution workflow without writing any code. Before starting, make sure that you meet the prerequisites.

To create a workflow:

  1. Log into your IT Administration console.
  2. Click your user name to open the menu.
  3. Click Developer to view and copy your API key.
  4. Navigate to SwaggerHub.
  5. Click Authorize and enter your API key to authorize SwaggerHub to use your Media Shuttle credentials.
  6. In the Portals section, expand GET /portals to obtain the portal ID for the portal to which you have access.
  7. Click Try it out and provide the required information in the fields.
  8. Click Execute.
  9. 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.

For a distribution workflow:

  1. Add files to the package using PUT /portals/{portalId}/packages/{packageId}/files.
  2. Generate a download token using POST /portals/{portalId}/packages/{packageId}/tokens.
  3. Test the download URL by copying the URL from the response body into a browser.

For an acquisition workflow:

  1. Generate an upload token using POST /portals/{portalId}/packages/{packageId}/tokens.

    • Portals can use the destinationPath relative to the portal’s storage root in the call body to set a target directory. You can determine the portal’s root in Media Shuttle by examining the path setting.
    • Submit portals with deliveries organized into unique folders determine transfer destinations automatically and do not support destinationPath.
  2. Test the upload URL by copying the URL from the response body into a browser.

Note: No notification is sent to the provided email address. The email address used to redeem the token is used for auditing purposes, and is not required to upload or download files. Whoever redeems that token is logged as the user associated with that email address in the portal’s transfer history.

You can now query the activities associated with a package using GET /portals/{portalId}/packages/{packageId}/events. The response from the query will allow you to build an audit trail of activity or create proof of delivery as required.

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, or the file path includes invalid characters.

To prevent this error, ensure that the content specified in the package remains in the storage location until the download token is redeemed, and that the file name does not contain any of the following: \ / [ : ? * < > "|