Custom Actions Beta

Frame.io Actions provide quick access to common media operations like downloading, renaming, and duplicating items – and also allow for integrations with 3rd party tools and services to be surfaced directly within the user interface of Frame.io.

About Actions

With the introduction of custom Actions (beta), developers can configure and manage their own Actions in Frame.io V4. Leveraging the same underlying Event system as Webhooks, custom Actions are an alternative mechanism for developers to connect their assets to the tools that matter most to the users in their Frame.io Account.

Actions can be executed by any user that is a Member of the Frame.io Workspace the Action is enabled in. When executing an Action, Frame.io sends a payload to a URL you provide. The receiving application responds with an HTTP status code to acknowledge receipt, or with a custom callback to render additional form fields in the Frame.io UI. The receiving application can be your own hosted program, service, or even low-code/no-code IPaaS tool like Workfront Fusion or Zapier.

Use the Custom Actions beta to build integrations directly into Frame.io as programmable UI components. This enables workflows that can be triggered by users within the app, leveraging the same underlying events routing as webhooks. You can create user-triggered single or multi-step forms that come back to Frame.io as another form or a basic response. And when a user clicks a Custom Action on an Asset, Frame.io sends a payload to a URL you provide. The receiving application responds with an HTTP status code to acknowledge receipt, or responds with a custom callback that can render additional UI in Frame.io.

Actions Improvements in V4

Leveraging learnings from users of our Legacy version, we’ve included a number of enhancements to the Actions feature set in Frame.io V4:

Migrated Actions

There are a few things to keep in mind when migrating to a Frame.io V4 Account containing custom Actions previously created in the legacy version of Frame.io.

Action Status

Upon Account migration to Frame.io V4, all custom Actions created in earlier versions will have a status of ‘null’ and will be automatically disabled. This provides users the opportunity to first update your Actions to use the V4 API before enabling as any Actions not updated will fail. To identify Actions in this state visit the Actions Settings page and reference the column “Status” or, if using the API, by checking the is_active field.

Actionable Resources: Files, Folders & Version Stacks

Given the separation of asset types as separate resources in the Frame.io V4 API, there may be behavior to consider when interpreting the resource ID received in your Action’s payload. The behavior for individual Files is straight-forward, as the ID will reflect the specific File the Action was executed on. Likewise for Folders, you’ll be receiving the ID for the Folder the Action was executed on; however, depending on your use-case you have multiple options when defining your Action’s behavior. Use the Folder ID to make subsequent calls to the Frame.io API if you want interact with the Folder resource itself. Alternatively, you may want to get the children of that Folder in order to perform further processing on the assets within. When an action is Executed on a Version Stack, your payload will contain the ID for the ‘Head Asset’, which is the top most File in the Stack and is what is shown in the Frame.io UI.

You can read more about the differences between the Frame.io Legacy API and V4 in our Migration Guide.

A Custom Action requires:

Configure Your Custom Action

When a user selects a Custom Action on an Asset, Frame.io sends a payload to a URL you provide. The receiving application can respond with an HTTP status code to acknowledge receipt, or respond with a custom callback that renders additional UI in Frame.io.

Payload From Frame.io

When the user clicks your Custom Action, a payload is sent to the URL you set in the URL field. Use this payload to identify:

POST /your/url
{
    "account_id": "9a44f696-ae69-4e0c-9731-806d27ea46f1",
    "action_id": "ecd40785-4485-4f07-9d26-a006ea84efdf",
    "interaction_id": "e0a1c945-a8da-480d-92fb-e895cb640a01",
    "project":
    {
        "id": "3dda6833-ec3b-46bd-a7d9-1a77c03a165b"
    },
    "resource":
    {
        "id": "f9d5728c-ac1a-4f48-92bb-ea2f9be3c58b",
        "type": "file"
    },
    "type": "two.event",
    "user":
    {
        "id": "50d976e6-27d2-47cb-9388-45b38d55f4f0"
    },
    "workspace":
    {
        "id": "382a1fe6-67cf-481e-9b65-79cfd9e9727f"
    }
}

Interactions, Retries and Timeouts

The interaction_id is a unique identifier to track of the interaction as it evolves over time. If you do not need to respond to the user, return a 200 status code, and you’re done. While optional, we recommend including information about the result of the action, like a success message or error alert. Custom actions support message callbacks.

Create a Message Callback

In your HTTP response to the webhook event, you can return a JSON object describing a message that will be returned to the initiating user in the Frame.io UI.

{
  "title": "Success!",
  "description": "The thing worked! Nice."
}

Messages close the action loop providing variable context to the user, without asking them to switch contexts. When the initial payload and subsequent calls to the Frame.io API don’t provide enough context for the receiving application, use Form Callbacks.

Create a Form Callback

Let’s say that you need more info before you start your process. For example, you may be uploading content to a system that requires additional details and settings. You can describe a Form in your response, which the user sees snd fills out, and is then sent right back to you! Here’s an example form that renders a Form in the Frame.io UI that the acting user can fill out and submit:

{
  "title": "Need some more info!",
  "description": "Getting ready to submit this file!",
  "fields": [
    {
      "type": "text",
      "label": "Title",
      "name": "title",
      "value": "MyVideo.mp4"
    },
    {
      "type": "select",
      "label": "Captions",
      "name": "captions",
      "options": [
        {
          "name": "Off",
          "value": "off"
        },
        {
          "name": "On",
          "value": "on"
        }
      ]
    }
  ]
}

When the user submits the form, you’ll receive an event on the same URL as the initial POST:

POST /your/url
{
  "type": "your-specified-event-name",
  "interaction_id": "the-same-id-as-before",
  "action_id": "unique-id-for-this-custom-action",
  "data":{
    "title": "MyVideo.mp4",
    "captions": "off"
  }
}

All custom fields added on a form appear in the data section of the JSON payload sent by Frame.io. Use the interaction_id to map the initial request and this new form data. And again, you can respond with a message (or even another form!). By chaining Actions, Forms, and Messages, you can effectively program entire Asset workflows in Frame.io with business logic from an external system.

Form Details

Like messages, Forms support title and description attributes that render at the top of the Form. Beyond that, each form field accepts the following base attributes:

Supported Field Types

Text field

A simple text field with no additional parameters.

{  
  "type": "text",
  "label": "Title",
  "name": "title",
  "value": "MyVideo.mp4"
}

Text area

A simple text area with no additional parameters.

{  
  "type": "textarea",
  "label": "Description",
  "name": "description",
  "value": "This video is really, really popular."
}

Select list

Defines a picklist that the user can choose from. Must include an options list, each member of which should include a human-readable name, and a machine-parseable value.

{
  "type": "select",
  "label": "Captions",
  "name": "captions",
  "value": "off",
  "options": [
       {
         "name": "Off",
         "value": "off"
       },
       {
         "name": "On",
         "value": "on"
      }
   ]
}

Checkbox

A simple checkbox with no additional parameters.

{ 
   "type": "boolean", 
   "name": "enabled", 
   "label": "Enabled", 
   "value": "false"
}

Link

A simple link with no additional parameters.

{
  "type": "link",
  "name": "videoLink",
  "label": "Video Link",
  "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc"
}

The Frame.io Permissions Model

Custom Actions have a special permissions model: they belong to a Workspace, not to any specific user who exists on an Account. That means:

Security and Verification

By default, all Custom Actions have a signing key generated during their creation. This is not configurable. This key can be used to verify that the request originates from Frame.io. Included in the POST request are the following:

Verifying the Signature

import hmac
import hashlib
def verify_signature(curr_time, req_time, signature, body, secret):
    """
    Verify webhook/custom action signature
    :Args:
        curr_time (float): Current epoch time
        req_time (float): Request epoch time
        signature (str): Signature provided by the frame.io API for the given request
        body (str): Custom Action body from the received POST
        secret (str): The secret for this Custom Action that you saved when you first created it
    """
    if int(curr_time) - int(req_time) < 500:
        message = 'v0:{}:{}'.format(req_time, body)
        calculated_signature = 'v0={}'.format(hmac.new(
            bytes(secret, 'latin-1'),
            msg=bytes(message, 'latin-1'),
            digestmod=hashlib.sha256).hexdigest())
        if calculated_signature == signature:
            return True
    return False

Beta Feedback

We’d love to hear from developers and end-users about the ways you’d like to use Actions in Frame.io V4. Be sure to reach out to us with your questions, ideas, and use-cases to help inform our prioritization.