System-to-Person Automation API

Media Shuttle’s System-to-Person API allows you to generate single use links that allow specified users to upload or download content using a Media Shuttle portal. Signiant Jet, Signiant Flight Deck, media asset managers (MAMs), digital asset managers (DAMs), or other third-party applications can integrate with Media Shuttle using the System-to-Person API.

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 allow access to transfer files to or from storage for a specific user:
    • 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

API Call Limit

The System-to-Person API has a maximum payload size of 100 kB, and can transfer a maximum of 100 files per package.

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

When generating an upload or download link, you must provide the recipient’s email address to ensure that only the recipient can send or receive content.

Once a link is generated, the recipient will be added to the associated portal as a Portal Member without direct access to the Media Shuttle portal, to ensure System-to-Person transactions provide reporting data and portal security.

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

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:

{
  "user": {
    "email": "user@example.com"
  },
  "grants": ["download"],
  "expiresOn": "2019-01-21T11:00:45.046Z",
  "notifications": [
    {
      "type": "webhook",
      "url": "http://example.com/path/to/webhook"
    }
  ]
}

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

Submit Portal Metadata

You can use the Media Shuttle API to retrieve metadata form information submitted in Submit portals.

To retrieve metadata:

  1. Authorize your account.
  2. In the Portals section, expand GET /portals.
  3. Click Try it out and fill in the url field with the relevant Submit portal URL.
  4. Click Execute.
  5. In the Response Body, copy the portal ID.
  6. In the System-to-Person section, expand POST /portals/{portalId}/subscriptions.
  7. Click Try it out and fill in the portalId field with the copied portal ID.
  8. Edit the Request body and replace the URL with a webhook URL.
  9. Click Execute to subscribe to the webhook.
  10. Submit a file and fill out a metadata form in the relevant Submit portal.
  11. Copy the package ID from the webhook response.
  12. In the System-to-Person section, expand GET /portals/{portalId}/packages/{packageId}.
  13. Click Try it out and fill in the portalId and packageId fields.
  14. Click Execute and see the Response body to view the metadata.

A successful response will return the submitted metadata in the Response body.

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

Download links in a distribution workflow are single use by default. To allow for multiple use, set the isReusable to true in a request body:

{
  "user": {
    "email": "user@example.com"
  },
  "grants": ["download"],
  "expiresOn": "2019-01-21T11:00:45.046Z",
  "isReusable": true
}

Note: Upload links can only be used once.

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 SwaggerUI Documentation to provide a functional API reference that can be used with your account to create upload or download tokens for acquisition or distribution workflows.

Note: Tokens are single use, and a separate token is required for each recipient.

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

Note: The SwaggerUI authorization is handled by SwaggerHub. 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.

Generating and Redeeming Tokens

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

Distribution Workflow

Distribution workflows allow users to download content from portals using a link. A distribution workflow, uses the PUT /portals/{portalId}/packages/{packageId}/files API 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 API 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 API 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 API 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 API 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: \ / [ : ? * < > "|