Send to Frame.io

Go to README

What does this plugin do?

This plugin provides a seamless bridge between Cantemo Portal and Frame.io, enabling users to quickly share media for cloud-based review and collaboration.

How to trigger:

In the Search tab, search for and find the item(s) you want to send to Frame.io, select them and then click on the Gear in the top right of the page, in the filter type frame, and then click on Send to Frame.io.

User Experience:

A new window will pop up called 'Send to Frame.io'. User will need to select which Format to Send, set Frame.io Upload Location information, as well as set Sharing information and then click Send

Once user clicks Send, that will start the Job which can be viewed/monitored in the Job Monitor. Once the job is finished, the user can click on the Frame.io Asset link or the Share Link right from the Job Viewer.

When clicking on the Frame.io Asset button, it opens a new browser tab to the Frame.io page.

---

README

What it adds:

• Item gear + search gear options to send items to Frame.io.
• Frame.io oauth page

Logging

• Individual jobs have logs. All job logs also appear in the cs_api_server log.
• The /var/log/cinesys/cs_send_to_frameio directory is no longer used.

Authentication

• When auto is true and token is the defined, token is used for what is shown in the UI, regardless if oauth is enabled. When the actual upload is triggered, the user's oauth token will be attempted first before falling back on token if they don't have access to the correct project.

Configuration

Example configuration with all options:

{
    "share_url_field_id": "portal_mf396876",
    "url_field_id": "portal_mf414244",
    "token": "fio-u-...",
    "use_oauth": true,
    "oauth_optional": false,
    "account_names": [
        "My Projects",
        "MSG Networks"
    ],
    "shape_tags": [
        "original",
        "lowres"
    ],
    "priority": "MEDIUM",
    "auto": false,
    "auto_team_config": {
        "field_id": "msg_department",
        "map": {
            "Communications": "Network Branded Content",
            "Creative Services": "Network Promotions",
            "Engineering": "Network Engineering",
            "Gardenvision": "Sports Gardenvision",
            "Interactive": "Network Interactive",
            "Marketing": "Network Marketing",
            "Media Assets": "Network Media Assets",
            "On-Air Promotion": "Network Promotions",
            "Production": "Network Branded Content",
            "Programming": "Network Programming",
            "_default": "My Projects"
        }
    },
    "auto_project_config": {
        "field_id": "msg_project",
        "use_label": true
    },
    "auto_folder_config": {
        "path": "<msg_description>/CineSys",
        "use_label": true
    },
    "host": "https://cantemo.cinesys.io",
    "notification_emails": [
        "[e-mail]"
    ],
    "enabled_field_id": "portal_mf164750",
    "enabled_field_value": "sharing"
}

Primary Options

Key	Required	Description
share_url_field_id	optional (but recommended)	Metadata field to store the Frame.io share url in
url_field_id	optional (but recommended)	Metadata field to store the Frame.io asset url in
token	optional	Frame.io app token to use when oauth is disabled, or to fallback on when oauth is not available. When calling Frame.io, every effort will be made to use oauth tokens, but this can be a fallback if no tokens are available. This is highly recommended to be set if auto is enabled. Follow these directions to create a Frame.io app token: https://docs.frame.io/docs/get-a-developer-token
use_oauth	optional	Whether to require users to sign in with oauth to use the plugin. Assets will be uploaded to Frame.io as the authenticated user.
oauth_optional	optional	Whether to allow users to upload via the modal without signing in to oauth.
account_names	optional	A list of account names to restrict this tool to. If this is undefined and a user has access to multiple Frame.io accounts, they can upload to any of them.
shape_tags	required	A list of shape tags that can be uploaded to Frame.io
priority	optional	Vidispine job priority. Defaults to MEDIUM if left out.
auto	optional	Automatically select the team, project, and folder based on metadata.
host	required	Cantemo hostname for linking to items in notification emails
notification_emails	optional	A list of emails to send a notification to whenever an asset is uploaded to Frame.io. Portal must have email settings configured in portal.conf for this to work.
enabled_field_id	optional	Only allow items with the metadata field enabled_field_id set to enabled_field_value to be sent to Frame.io. Administrators can still send any item to Frame.io.

auto_team_config

This plugin does not create teams, so the metadata field chosen must be mapped to existing teams.

Key	Required	Description
field_id	required	Metadata field to use
map	required	A mapping from field values (not labels) to Frame.io team names. The _default key can be used as a fallback if none of the other options match.

auto_project_config

This plugin will create any missing projects for the resolved values.

Key	Required	Description
field_id	required	Metadata field to use. A project will be created with this name.
use_label	optional	Whether to use field labels instead of values.
map	optional (not recommended)	You likely won't need this, as you can automatically create projects for any field value. This allows you to create a mapping from field values to Frame.io project names. The _default key can be used as a fallback if none of the other options match.

auto_folder_config

This plugin will create any folders that don't already exist.

Key	Required	Description
path	required	A formatted path that can contain metadata fields. For example <msg_description>/CineSys will resolve to the path My Description/CineSys.
use_label	optional	Whether to use field labels instead of values.

Scripts

Setting Asset Label

Authentication: This script will use token if set in the Configuration, otherwise it will attempt to use the item owner's oauth token.

Rulesengine script call_cs_api_server.py with arguments /cs_send_to_frameio/script/asset_label/<label>, where <label> is one of approved, needs_review, in_progress or none.

Uploading

Authentication: If useOwner is true, the item owner's oauth token will be tried first. If user is set, that user's oauth token will be tried next. Finally, if token is set in the Configuration, it will be tried last.

Example script for upload:

#!/opt/cantemo/python/bin/python
import json
import subprocess
import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--item_id", default="")
item_id = parser.parse_args().item_id

options = {
    "projectId": "7b5c9190-1546-482b-aa6f-735181b2a312",
    "folderPath": "/",
    "shapeTags": ["original"],  # will upload the first of these that exists on the item
    "shareType": "presentation",  # "review", "presentation", or "none"
    "shareDownload": False,
    "shareExpirationDays": 30,
    # "user": "admin",  # Oauth only option
    "useOwner": True,  # Oauth only option
    "assetLabel": "none",  # "approved", "needs_review", "in_progress", or "none"
    "jobMetadata": {},
}

subprocess.run(
    [
        "/opt/cantemo/python/bin/python",
        "/opt/cantemo/portal/portal/plugins/rulesengine3/shellscripts/call_cs_api_server.py",
        "/cs_send_to_frameio/script/upload",
        *(["--item_id", item_id] if item_id else []),
        "--data",
        json.dumps(options),
    ]
)

Options

Key	Required	Description
projectId	optional (required if auto is false)	Frame.io project ID to upload to. Has no effect if auto is enabled.
folderPath	optional (required if auto is false)	Folder path within the project. Has no effect if auto is enabled.
shapeTags	required	Shape tags order of preference. Will upload the first of these that exists on the item.
shareType	optional	Create a share link of this type. "review", "presentation", or "none"
shareDownload	optional	Whether to allow downloading on the share link
shareExpirationDays	optional	Defaults to 30
user	optional	Which user's oauth token to use for this script. If this user is not signed it, it will fall back onto the token in the config. This option is required if token is not defined in the config.
useOwner	optional	Attempt to upload using the item owner's oauth token, before falling back on user if defined, and finally falling back on token in the config.
assetLabel	optional	Label to give the Frame.io asset. "approved", "needs_review", "in_progress", or "none"
jobMetadata	optional	Additional job metadata to add to the vidispine job

Portal Permissions

• Users must have the 'cinesys_send_to_frameio' permissions flag to use this plugin.