System-to-Person Automation API

The Media Shuttle System-to-Person API integrates Media Shuttle with Signiant Jet, 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 that allow users to upload or download content.

Account and Portal Requirements

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.
  • Access to the IT Administration Console and the Operations Administration Console for the portal.
  • An API key from your Media Shuttle IT Administration Console.
  • A working Media Shuttle portal.

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

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

  • Actor - The person or application using the API to generate an upload or download link. An actor is granted permission to generate a link via the access control layer which is controlled by the specific portal used in the transfer.

  • Access Control - Portal-level permissions that are based on roles or links associated with a portal providing access to stored content, control over storage access, and overall control over the account.

    • Roles: Groups of portal users that allow an increasing level of account access:
      • Portal Member - Uploads and downloads files and folders from storage.
      • Operations Administrator - Manages portal membership and who has access to upload and download content.
      • IT 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 storage:
      • Download URL - Provides access to downloadable content grouped in a package.
      • Upload URL - Provides upload permission to an empty package, created as a placeholder.
  • 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, such as file storage, Amazon S3, or Microsoft Azure.

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

  • Package - A unique identifier that refers to a grouping of files or a placeholder where files can be uploaded.

    • Download packages contain downloadable content from storage.
    • Upload packages act as a placeholder to allow the user to add content to storage.
    • A package can be reused across multiple transfers

Creating a System-to-Person Workflow

Integrated Media Shuttle download or upload workflows require a series of REST calls to create upload and download links that can be used to send or receive files. In addition to providing access to storage, the API allows queries for portal transfer events and send webhooks when transfers complete, fail, or are cancelled by a user.

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

S2p workflow diagram

Acquisition Workflow

Media Shuttle can be used to acquire content for file ingestion workflows:

Diagram of ingest workflow

Distribution Workflow

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

Diagram of fulfillment workflow

Note: Download tokens allow access to specific stored content and do not copy any content when created. Tokens are intended for single use, and a separate URL is required for each intended recipient or download.

Adding Webhooks

API events can also send webhooks, or callbacks, to a URL when transferring files using the system-to-person API.

To set a webhook URL, create a notification array and include the webhook url in a token request body:

"notifications":
[
{
"type": "webhook",
"url": "http://example.com/path/to/webhook"
}
]

For more information on using webhooks, see Working With Webhooks.

Using System-to-Person for an Acquisition or Distribution Workflow

You can use the System-to-Person Automation API to create a workflow without writing any code. Media Shuttle uses SwaggerHub to provide a functional API reference that can be used with your account to create upload or download tokens for acquisition or distribution workflows.

Authorization

To authorize your account:

  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 the Media Shuttle API documentation on SwaggerHub.
  5. Click Authorize and enter your API key to authorize SwaggerHub to use your Media Shuttle credentials.

Note: This does not provide SwaggerHub with access to your content.

Package Creation

To distribute or receive content, you must create a package.

To create a package:

  1. In the Portals section, expand GET /portals to obtain the portal ID for the portal.
  2. Click Try it out and provide a portal URL.
  3. Click Execute.
  4. Copy the id for the relevant portal to your clipboard.
  5. In the System-to-Person section, expand POST /portals/{portalId}/packages.
  6. Click Try it out and paste the portal id in the portalId field.
  7. Click Execute.

A successful response includes a package id and the portalId, which can be used to generate tokens to distribute or acquire content.

Token Generation

Token generation differs depending on the type of workflow being used.

Distribution Workflow

Distribution workflows allow users to download assets from portals through a one-time use link for a specific user. A distribution workflow, uses the PUT /portals/{portalId}/packages/{packageId}/files endpoint to accept request body data.

Note: When using a Send portal, the files must be added to a folder that uses the same name as the packageId.

To create a distribution of files or folders:

  1. Create a Package.
  2. In the System-to-Person section, expand PUT /portals/{portalId}/packages/{packageId}/files.
  3. Click Try it out and fill in the portalId and packageId fields.
  4. In the Request body, edit the path parameter to a file or folder in the portal.
  5. Set the isDirectory parameter as needed.
  6. Enter the total file size of the file or folder contents.
  7. Create additional file objects as required.
  8. Click Execute.

A successful response includes a matching JSON array of file objects containing the files or folders to be downloaded.

Note: A package can only be assigned one set of files. Additional calls to the /files endpoint for the same package will be rejected.

Once files have been added to the packageId folder, generate a download token using POST /portals/{portalId}/packages/{packageId}/tokens endpoint, and setting a download grant for a portal member. The token is a URL that allows a user to download the packaged files or folders.

To create a download token:

  1. In the System-to-Person section, expand PUT /portals/{portalId}/packages/{packageId}/tokens.
  2. Click Try it out and fill in the portalId and packageId fields.
  3. Select a portal example and edit the request body as required.
  4. Click Execute.

Test the download URL workflow by copying the url value from the response body into a browser and using it to download files from the portal. Create tokens as necessary by repeating the call to the endpoint.

Acquisition Workflow

For an acquisition workflow, the token url is used in a browser to allow portal members to upload files to a portal by setting an upload grant in the request body. The /portals/{portalId}/packages/{packageId}/tokens endpoint supports a destinationPath which specifies an upload folder relative to the portal’s storage root.

You can determine the portal’s root in the IT Administration Console by checking the path setting on the portal’s Storage settings.

Submit portals with deliveries organized into unique folders determine transfer destinations automatically and do not support the destinationPath parameter.

To create an upload token:

  1. Create a Package.
  2. In the System-to-Person section, expand PUT /portals/{portalId}/packages/{packageId}/tokens.
  3. Click Try it out and fill in the portalId and packageId fields.
  4. Select a portal example and edit the request body as required.
  5. Click Execute.

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 when a token is created and must be provided to the recipient. The email address used to redeem the token is used for auditing purposes, and is recorded in the portal’s transfer history.

Querying Portal Events

You can 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 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 characters: \ / [ : ? * < > "|