Media Shuttle System-to-Person Automation API Integration Guide

The System-to-Person Automation API allows you to generate links that allow specified users to upload or download content using a Media Shuttle portal. Signiant Jet, Signiant Flight Deck, or other third-party applications can integrate with Media Shuttle using the API.

Contact us today to add the System-to-Person Automation API to your Media Shuttle Account

Account and Portal Requirements

System-to-Person automation requires the following:

Note: The System-to-Person API distribution payloads can contain a maximum of 100 files per package, and the total size of file paths and file names must be less than 100 KB. To reduce file path and name size, files must be renamed or moved to a different directory with a shorter path.

Workflow Model

The following image outlines the general workflow for creating an upload or download token for a Share Portal using the Media Shuttle System-to-Person Automation API.

Media Shuttle Upload Download Token Workflow

System-to-Person API Webhooks

The System-to-Person API allows you to create webhooks that authorize your application to receive information about portal events.

Webhooks send subscription updates to a URL when a transfer finishes.

Learn more about System-to-Person webhooks

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 sends 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:

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

If notifications are enabled at multiple levels, you may receive duplicate notifications for the same transfer event. The optional notifications array at the package level will return a summary of the transfer, and not the package details. To receive transfer notifications with package details, you must subscribe to portal level notifications by using the /portals/{portalId}/subscriptions endpoint in the System-to-Person API.

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:

Copy 
{
  "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 one-time use 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: \ / [ : ? * < > "|

About Signiant

Signiant’s intelligent file movement software helps the world’s top content creators and distributors ensure fast, secure delivery of large files over public and private networks. Built on Signiant’s patented technology, the company’s on-premises software and SaaS solutions move petabytes of high-value data every day between users, applications and systems with proven ease.

Quick Links