Custom metadata fields can be configured as optional, or required, when publishing clips on Omny Studio. This metadata can be retrieved and edited via Omny Studio's Management API or retrieved via the Consumer API for publishing purposes.
We'll walk you through creating and editing custom fields, setting them as required or optional and an explanation of how the API behaves when dealing custom fields.
Setting custom fields
1) Go to Organization, Network or Program settings - depending on the scope of programs you are creating Custom fields for. The structure follows Omny's Settings Inheritance hierachy as explained here.
2) From the Custom fields menu, you can see your existing custom fields, and click 'Create field' to make a new one.
3a) Give the field a display name, which will be added to the Clip Details page UI and an API name, which is how this field will be labelled in the management and (optionally) the consumer API.
NOTE: Please be aware that if a custom field is viewable in the Consumer API, treat the field name and contents as public.
3b) Choose the type of content response this field will accept, Text or Dropdown.
Dropdown options can be listed in the box shown below, each option on a new line.
3c) Choose is this Field is required in order for a clip to be published.
NOTE: If required, the Custom field value will need to be added to any clip within the organization, network or program before it is published (i.e. made unlisted or public) and saved. Private clips do not require the required fields to be input before saving.
3d) Optional, add a description for this custom field to help your account users utilise this Custom field.
4) Save changes.
Using Custom Fields
When Custom fields are active and in the scope of a program, there will be a new addition to the Clip details page, underneath clip description, season and episode numbers, and audio options. If custom fields are available for this program, the dropdown will automatically be expanded.
Required fields are marked with (required). Proceed to create clips and save them as normal, populating Custom fields as necessary.
Retrieving Custom fields
Clips with Custom fields populated can have those clips retrieved through Omny's webhooks, or the Omny APIs, both Management and Consumer. Please be aware that if a Custom Field is viewable in the Consumer API, treat the field name and contents as public.
Custom fields can also be set and updated on clips via the Management API, but the validation rules slightly differ. These are documented below. Note that dropdown values are not validated when being set via the API.
To set custom fields on a clip, include them in the CustomFieldData property as follows:
"Id" : "Guid",
"my-custom-field" : "value1",
"another-custom-field" : "value2"
If any custom fields are omitted from an update, or set to null, their existing value is preserved. Similarly, passing "CustomFieldData" : null will preserve all custom field data.
To clear a custom field, you have to pass an empty string in the API request for that field, as follows:
"Id" : "Guid",
"my-custom-field" : ""
Create endpoint validation
When creating a new clip, all fields marked as required are required if the creation also publishes the clip.
Update endpoint validation
When updating a clip that is already published, you do not need to add values for any new custom fields that are required for publishing. Any required fields that have existing values cannot be cleared, they can only be changed.
Publish endpoint validation
All required custom fields are validated when publishing a clip via the publish endpoint.
For any questions please contact Omny Support.