We'll walk you through creating and editing custom fields for your clips, playlists or programs, setting them as required or optional and an explanation of how the API behaves when dealing custom fields as well.
Setting custom fields
1) Go to Organization, Network or Program settings - depending on the scope 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 at either the clip, playlist or program level.
3) Give the field a display name, which will be added to the clip, program or playlist details page UI and an API name, which is how this field will be labeled in the management and (optionally) the consumer API or RSS feed.
NOTE: Please be aware that if a custom field is viewable in the Consumer API or RSS feed, treat the field name and contents as public.
4) 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.
5) Choose if this Field is required in order for a clip, playlist or program to be saved.
NOTE: If required, the custom field value will need to be added to any clip, playlist or program (depending on the scope of your custom field) within the organization, network or program before it is published (i.e. made unlisted or public) and saved. Private clips and playlists do not require the required fields to be input before saving. A value will need to be entered before saving a new program since those visibility options don't apply at a program-level.
5a) Optional, add a description for this custom field to help your account users utilise this custom field.
6) Save changes.
Using Custom Fields
When Custom fields are active, there will be a new addition to the clip, playlist or program details page.
Required fields are marked with (required) and if no selection or data is entered into a required field, this will prevent a user from publishing or saving.
Retrieving Custom fields
Clips with custom fields will be included in Omny's webhooks service, or the Omny APIs, both Management and (optionally) the Consumer API.
You can also optionally add your custom fields to your RSS feeds. If you opt into this option, the custom fields will be shown in this format:
<omny:clipCustomField key="my-test-clip-field" value="test"/>
<omny:playlistCustomField key="my-test-playlist-custom-field" value="test"/>
<omny:programCustomField key="my-test-program-custom-field" value="test"/>
Management API
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:
POST /v0/clips/{clipId}
{
"Id" : "Guid",
...
"CustomFieldData" :
{
"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:
POST /v0/clips/{clipId}
{
"Id" : "Guid",
...
"CustomFieldData" :
{
"my-custom-field" : ""
}
}
The same approach should be taken for playlist-level and program-level custom fields.
Create endpoint validation
When creating a new clip, playlist or program - all fields marked as required are required if the creation also publishes the clip or playlist. A program will validate when saved.
Update endpoint validation
When updating a clip or playlist 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 or playlist via the publish endpoint.
For any questions please contact Omny Support.