Collecting Metadata

Metadata entry allows end users to populate predefined fields with information describing the file they are about to share.

This feature can be used to provide details about transfers to increase interoperability with Media and Digital Asset Managers. Metadata allows you to use business logic to process files through your organization's established workflows.

Metadata validation is included in Enterprise subscriptions. To enable metadata validation on your account, contact Signiant Customer Care.

The Metadata feature provides:

• Improved file tracking: Query Media Shuttle for the metadata associated with any historical delivery by providing the unique tracking code.
• Quicker time to production: Integrate workflows associated with your existing web forms.
• Lower Development Costs: Re-use your own web infrastructure and link it to Media Shuttle.

Pre-requisites

• A Media Shuttle Submit portal configured for metadata.
• A web server that has a valid SSL certificate.
• A web server that can host a web form application, serve form requests, and respond to form submissions from Media Shuttle via https.
• The ability to generate security signatures to exchange with Media Shuttle.

Note: Self-signed certificates are not accepted by Media Shuttle.

Interaction Between Media Shuttle and Your Web Server

Creating a Metadata-Enabled Portal

To create a metadata-enabled portal you must build and deploy a customized web form that collects metadata for Media Shuttle portal submissions. The form is rendered in an iframe, hosted on a web server or platform, and accessed securely by Media Shuttle using https.

Note: It is recommended to collect metadata using an AWS Lambda, Azure Function, or other serverless computing platform to collect submissions.

Media Shuttle provides a sample web form for each portal that allows you to see how the metadata feature will appear to the end user. You can view the sample web form at https://<portalUrlPrefix>.mediashuttle.com/metadata/sample/form.

Registering your web form in your Media Shuttle Operations Administration Console assigns a registration key that you is used to secure communications between your Media Shuttle portal and your web server.

To register your form in a Submit portal:

1. Log into your Operations Administration Console at <yourURL>.mediashuttle.com/admin.
2. Select the Metadata tab.
3. Select Enable metadata collection.
4. In Metadata provider URL, enter the secure URL for the web server that hosts your form.
5. Take note of the Registration key generated by Media Shuttle when you register a URL. The registration key is required to sign requests made using the web form.
6. Click Save Changes.

Note: Ensure that your registration key is kept secure. Do not include it in JavaScript client-side code or embed it in a mobile client. When required, you can reset your registration key on the Metadata tab in your Operations Administration Console.

Handling Form Requests

Each time a user uploads files to your Submit portal, Media Shuttle will request your web form, using the URL you registered, by posting a request to your web server with specific parameters:

• packageId: The package identifier for the set of files being submitted to Media Shuttle. This ID can be used to make REST API calls.
• redirectUrl: The URL endpoint provided by Media Shuttle to which your form redirects.
• metadataId: Tracks individual form requests by passing a metadataId parameter in request links to your portal. (optional)

For example, when portal members use the link https://my-submit-portal.mediashuttle.com?metadataId=123, Media Shuttle passes the key-value pair metadataId=123 back to you in the web form POST request. You must generate this metadataId and your web form application must perform any validation checks that you require.

Sample Form Request

POST https://your-web-form-uri
content-type: application/x-www-form-urlencoded

metadataId=123&packageId=X30G1zUlIThVdyGRbb&
redirectUrl=https%3A%2F%2Fmy-submit-portal.mediashuttle.com
2Fmetadata%2Fv3.0%2Fmy-submit-portal
%2Fpackage%2FX30G1zUlIThVdyGRbb%2Fmetadata

After receiving a form request from Media Shuttle, your application responds by displaying the form inside a sandboxed iframe within the portal browser window. This iframe has privileges to submit forms and execute JavaScript.

<iframe sandbox="allow-forms allow-scripts">
    your HTML document
</iframe>

Note: Sending an X-Frame-Options response header value of DENY or SAMEORIGIN in form request responses causes your form to be displayed incorrectly in Media Shuttle. You can optionally send a value of ALLOW_FROM URI where the URI is the Media Shuttle portal URI or omit this header in your response.

Handling Form Submissions

Your web form must handle valid and invalid form submissions. Any invalid submission should return the appropriate HTML document response. The validation error, for example, should redisplay the form with invalid field markers.

Upon successfully processing a web form submission, your server must respond with an HTTP 307 (Temporary Redirect) status. Your server response must specify a redirect target URL in the Location response header. Your application may store the metadata itself. Media Shuttle also stores the metadata and continues with the transfer.

Success Response

HTTP/1.1 307 Temporary Redirect
Location: https://my-submit-portal.mediashuttle.com/metadata/v3.0/my-submit-
portal/package/X30G1zUlIThVdyGRbb/metadata?X-Sig-Algorithm=SIG1-HMAC-SHA256
&X-Sig-Date=<RequestDate>&X-Sig-Signature=<Signature>

Signing Requests

To ensure secure communications, all metadata-related web requests sent to Media Shuttle must be signed. Requests are signed using the registration key that was generated when you enabled metadata collection in your portal.

The signing process secures requests by:

• Verifying that the requester has the required access to the registration key.
• Protecting data in transit by using key request elements in the calculation of the signature hash.
• Protecting against replay attacks by including a timestamp component in the calculation of the signature hash. Requests are valid for 24 hours.

Note: You can use the Media Shuttle Metadata Signature Generator to generate signed request URLs for Media Shuttle metadata requests.

Building the Canonical Request

Creating the request in canonical format before signing ensures that the same signature can be calculated for verification purposes on the receiving end.

The canonical request is defined as follows:

CanonicalRequest =
   CanonicalURL + '\n' +
   CanonicalQueryString + '\n' +
   HexEncode(Hash(RequestPayLoad))

To build the canonical request:

1. Construct the CanonicalURL. Include the redirectURL passed by Media Shuttle when the form was requested up to, but not including, the question mark character (?) that begins the query string parameters, if any.

2. Construct the CanonicalQueryString.

   • URL-encode each parameter name and value according to the following rules:
     • Use only valid URL characters: A-Z, a-z, 0- 9, hyphen (-), underscore (_), period (.) and tilde (~).
     • Percent-encode all other characters with %XY, where X and Y are hexadecimal characters (0-9 and uppercase A-F).
   • Sort the encoded parameter names by character code, in strict ASCII order.
   • Build the CanonicalQueryString starting with the first parameter name in the sort list.
   • For each parameter, append the URL-encoded parameter name, followed by the = character, followed by the URL-encoded parameter value. Use an empty string for parameters that have no value.
   • Append the & character after each parameter value, except for the last value in the list.
   • In the CanonicalQueryString include parameters for the request and the two following query string parameters:
     • X-Sig-Algorithm=SIG1-HMAC-SHA256: Specifies the version of the signing algorithm used. This examples defines the algorithm as SIG1-HMAC-SHA256.
     • X-Sig-Date=<ISO8601 timestamp>: Specifies the ISO8601 formatted timestamp of the request. Requests older than one day are rejected by Media Shuttle.

3. Build the HexEncode. This function returns the base-16 encoding of the supplied parameter in lowercase characters. Hash returns a SHA256 message digest. RequestPayload is the request body represented as an array of bytes in UTF-8 format.

Creating the String to Sign

The string to sign includes the RequestDate plus the CanonicalRequest.

The RequestDate is the ISO8601 timestamp of the request. It must match the timestamp specified by the X-Sig-Date query string.

StringToSign =
   RequestDate + '\n' +
   CanonicalRequest

Calculating the Signature

You can calculate your signature by deriving your signing key from your private registration key. After you calculate the signature as a digest, the value is converted to its hexadecimal representation.

To calculate your signature:

1. Derive your signing key from your registration key.

DerivedSigningKey = HMAC_SHA256(RegistrationKey, RequestDate)

HMAC_SHA256(key, data) represents an HMAC-SHA256 function that returns output in binary format.

2. Create your signature using the DerivedSigningKey.

Signature = HexEncode(HMAC_SHA256(DerivedSigningKey, StringToSign))

Adding the Signature to the Request

To add the signature to the request, append the hexadecimal representation of the signature to the request URL query string.

RequestURL = RequestURL + &X-Sig-Algorithm=SIG1-HMAC-SHA256&X-Sig-
Date=<RequestDate>&X-Sig-Signature=<Signature>

Querying Package Details Using the REST API

You can make a GET request from a REST API endpoint to query portal package details including the list of files/folders, package size, status, sender and any associated metadata. Packages can be queried from the REST API immediately after form submission, without having to wait for file upload to complete.

GET /metadata/v3.0/portal/{portalUrlPrefix}/package/{packageId}

portalUrlPrefix: The URL prefix of the portal's URL. For example, for submit-portal.mediashuttle.com, the URL prefix is submit-portal.
packageId: The unique Media Shuttle package identifier. The packageId is posted to your web server in the web form request body.

REST API Endpoint Query String

https://{portalUrlPrefix}.mediashuttle.com/metadata/v3.0/portal/{portalUrlPrefix}/package/{packageId}?X-
Sig-Algorithm=SIG1-HMAC-SHA256&X-Sig-Date={RequestDate}&X-Sig-Signature={Signature}

• X-Sig-Algorithm: Identifies the signature algorithm used to sign the request URL. The parameter value should be set to SIG1-HMAC-SHA256.
• X-Sig-Date: The ISO8601 formatted request timestamp
• X-Sig-Signature: The request signature

Response

Success Response

{
    "result": "SUCCESS",
    "packageDetails":
    {
        "portalId": "578e1f3a-bccd-4ac3-b780-6f064003d6b0",
        "packageId": "3TnjFY7eUQa8MzfoTSDlGK",
        "creationDate": "2014-12-12T00:03:38.404+0000",
        "fileSize": 896403,
        "fileCount": 1,
        "status": "AVAILABLE",
        "sender": "sender@company.com",
        "deleted": false,
        "metadata":
        {
            "title": "title",
            "description": "description"
        },
        "files": [{
            "rangeKey": "3TnjFY7eUQa8MzfoTSDlGK:a263cafd-950c-4b4c-882c-e52b458cb7e9",
            "portalId": "578e1f3a-bccd-4ac3-b780-6f064003d6b0",
            "packageId": "3TnjFY7eUQa8MzfoTSDlGK",
            "fileId": "a263cafd-950c-4b4c-882c-e52b458cb7e9",
            "isDirectory": false,
            "fileName": "file1",
            "fileSize": 896403,
            "uploadTime": "2014-12-12T00:03:38.584+0000"
}] }
}

Error Response

{
    "result": "FAILURE",
    "resultCode": "<result code>"
}

Possible Error Codes

• portal.package.not.found
• portal.package.deleted
• exception.getting.portal.package