Templates Syntax Cheat Sheet

Introduction

This is a quick reference guide with the available entities and properties that can be referenced in the Ateliere Connect Metadata Templates, Package Templates, and NTP Job Templates.

Metadata templates

The syntax can be used in the Metadata template code editor, in order to structure technical and descriptive metadata at a Title or Media item level into an appropriate metadata manifest format.

Descriptive metadata

Package templates

The syntax can be used in the Deliverable name format field in order to use technical and descriptive metadata (from the main title or titles in the hierarchy) to name the package deliverables.

Package templates hierarchy

NTP Job templates

The syntax can be used in the Job template editor, at an NTP Transcoding Profile level, in order to enhance the NTP payload with technical and descriptive metadata at a Title or Media item level.

NTP payload

Available entities and properties

To use a property, users can combine the syntax from the Entity and Property tables, as long as the property is available for that entity. For example, a Title entity can not reference an audioTrack property directly, as the value is only available for a media item that has at least one audio track.

Some properties will have sub-properties, which are referenced in separate tables and will need to be included in the syntax construction as well.

How to use this

To build a reference, the Connect base entity must be specified, alongside a property and optionally a sub-property (this can go down to n levels). The construction will look like:

base entity + property + sub-property(level 1) + … + sub-property(level n)

Use the tables below to build your own reference.

Examples

Example #1

If I want to obtain the House ID property of a Title I will look up how each of these objects can be referenced:

Title - entity
House ID - .houseId

The resulting syntax for referencing will be entity + .houseId → entity.houseId

Example #2

If I want to obtain the codec sub-property of the video track of a Media item that is assigned on a Title and has a Tag I will look up how each of these objects can be referenced:

Media item, by Tag - entity.tags['NameOfTag']
Video track - .videoTrack
Codec - .codec

The resulting syntax for referencing will be entity.tags['NameOfTag'] + .videoTrack + .codec → entity.tags['NameOfTag'].videoTrack.codec

Connect base entities

The syntax is able to reference information from Titles and Media items, through multiple constructions, as follows:

Base entity	Syntax
Title	`entity`
Title → Parent (N levels)	`entity.parent.parent.parent[N]`
Media item assigned to Title by Tag	`entity.tags['NameOfTag']`
Media item assigned to Title → Parent by Tag	`entity.parent.tags['NameOfTag']`
Media item assigned to Title by Attribute	`entity.attributes['locale']['NameOfAttribute']`
Media item assigned to Title → Parent by Attribute	`entity.parent.attributes['locale']['NameOfAttribute']`

Properties

Syntax	Applies to	Details
`.attributes['locale']['NameofAttribute']`	Title and Media item	Any descriptive metadata field of a Title or Media Item. A full section regarding the possible references is detailed below
`.updatedById`	Title	The user UUID of the last user who updated the title.
`.updatedAt`	Title	The date of the last update made on the title.
`.slug`	Title	The title slug. Note that it is automatically generated.
`.parentId`	Title	The UUID of the title entity or the parent's parent.
`.organizationId`	Title	The organization UUID of the title entity or parent that it belongs to.
`.name`	Title	The name of the title entity or parent in Connect.
`.id`	Title	The UUID of the title entity or parent.
`.houseId`	Title	The House ID value of the title entity or parent.
`.entityTypeId`	Title	The entity type of the title or parent.
`.createdById`	Title	The user UUID of the creator of the title.
`.createdAt`	Title	The creation date of the title.
`.videoTrack`	Media item	Properties that are related with the Media item’s video track (if one is available).
`.audioTracks['Tag'][0]`	Media item	Properties that are related with the Media item’s audio track (if one is available).
`.timedTextTracks['Tag'][0]`	Media item	Properties that are related with the Media item’s timed text track (if one or more are available).
`.trim`	Media item	Properties that have been set inside the Connect Workbench that are related with trimming the video Media item (trimming at the start and/or at the end of the video).
`.crop`	Media item	Properties that have been set inside the Connect Workbench that are related with cropping the video Media item (cropping or setting a bounding box in the video).
`.locator`	Media item	Properties that are related to the location that the Media item is found at.
`.otherFileProperty`	Media item	Not an actual property, the otherFileProperty text will need to be replaced with an actual property from the following section.

Descriptive metadata properties

For more information about descriptive metadata and how it can be configured, see Configuring Metadata Settings.

Property	Returns	Example
`.attributes['locale']['Number']`	Returns a numeric value metadata field	Metadata field: name: `Season number` global: yes value: `1` Syntax: `entity.attributes['global']['Season number']` Returns: `1`
`.attributes['locale']['String']`	Returns a string value metadata field	Metadata field: name: `Name` global: no, fill in localized `en-us` value value: `Big Buck Bunny` Syntax: `entity.attributes['en-us']['Name']` Returns: `Big Buck Bunny`
`.attributes['locale']['Boolean']`	Returns a boolean value metadata field	Metadata field: name: `DRM` global: no value: `True` Syntax: `entity.attributes['global']['DRM']` Returns: `True`
`.attributes['locale']['Date']`	Returns a date value metadata field	Metadata field: name: `Release date` global: yes value: `31/10/2020` Syntax: `entity.attributes['global']['Release date']` Returns: `31/10/2020`
`.attributes['locale']['Array']`	Returns an array value metadata field	Metadata field: name: `Actor's cast` global: yes value: `John Doe, Jane Doe` Syntax: `entity.attributes['global']['Actor's cast']` Returns: array object: `John Doe, Jane Doe]` can use indexes, example syntax: `entity.attributes['global']['Actor's cast'][0]` returns: `John Doe`
`.attributes['locale']['Tag']`	Returns a Media item that is tagged with the Tag value that is found in the `.attributes['locale']['Tag']` metadata field **	Metadata field: name: `Artwork 16:9` global: yes value: `16:9` Tag, some additional information The `16:9` Tag is used on the target Title on the `example.jpg` source Media item Syntax: `entity.attributes['global']['Artwork 16:9']` Returns: Metadata Template: EMPTY Package Template/NTP Job Template - `example.jpg` looks for value in metadata field → `16:9` Tag → finds the file that is tagged with that value
`.attributes['locale']['File']']`	Returns the Media item that is assigned to a `File` type metadata field on the Title	Metadata field: name: `Video source` global: yes value: `example.mp4` Media item Syntax: `entity.attributes['global']['Video source']` Returns: `example.mp4` Media item
`.attributes['locale']['Reference']`	Returns the Title that is referenced in that field	Metadata field: name: `Trailer` global: yes value: `Big Buck Bunny - Trailer` Title Syntax: `entity.attributes['global']['Trailer']` Returns: `Big Buck Bunny - Trailer` Title The Title’s metadata properties can be further drilled down to return metadata properties from its level entity.attributes['global']['Trailer'].attributes['en_US']['DRM']

Important

The returned file will always be the deliverable inside the current Job when running in a Metadata Template, for NTP and Package Templates it can be both a source or a deliverable.

It is highly recommended to not use the same tags for sources and deliverables if using this construction for Package and NTP Job templates, as the syntax will pick between sources and deliverables at random in this scenario.

Video track properties

Video track property	Details
`.rawIndex`	Index of the track. One way of finding out is by running the GraphQL Query to get the file tracks. Look at index property.
`.typeBasedIndex`	Always 0.
`.codec`	The codec of the video track. Can be seen in the file’s technical details or in the query result.

Audio track properties

Audio track property	Details
`.rawIndex`	Index of the track. One way of finding out is by running the GraphQL Query to get the file tracks. Look at `index` property.
`.typeBasedIndex`	It answers the question: What is the index of this track, when taking only audio tracks in consideration? Formula is: `track.index - firstAudioTrack.index`.
`.codec`	The codec of the audio track. Can be seen in file’s technical metadata.
`.channels`	The channels of the audio track. Can be seen in file’s technical metadata.

Note

.audioTracks['Tag'][0].* is same as .audioTracks.Tag[0].*.
audioTracks['Tag'][0] - means the first audio track that is tagged with Tag. Multiple file tracks can have the same tag.

Timed text track properties

Timed text track property	Details
`.rawIndex`	Index of the track. One way of finding out is by running the GraphQL Query to get the file tracks. Look at `index` property.
`.typeBasedIndex`	It answers the question: What is the index of this track, when taking only timed text tracks in consideration? Formula is: `track.index - firstTimedTextTrack.index`.
`.language`	The language of the file when uploaded, based on the Probe results.
`.preferredLanguage`	The language of the file if it was manually set by an operator in the Connect user interface to overwrite the `language` property.

Note

timedTextTracks['Tag'][0].* is same as timedTextTracks.Tag[0].*.
timedTextTracks['Tag'][0] - means the first timed text track that is tagged with Tag. Multiple file tracks can have the same tag.

Trim properties

Trim property	Details
`.inpoint_asset_tc`	The Input clipping start timecode that is set from the Workbench.
`.outpoint_asset_tc`	The Input clipping end timecode that is set from the Workbench.

Crop properties

Crop property	Details
`.left`	Left crop index as set in the Workbench.
`.right`	Right crop index as set in the Workbench.
`.top`	Top crop index as set in the Workbench.
`.bottom`	Bottom crop index as set in the Workbench.

Locator properties

Locator property	Details
`.dirname`	Directory (folder) path to the media item.
`.basename`	Basename of the media item.
`.extname`	Extension of the media item.
`.url`	URL of the media item.

Example:

Having a file that is the first input of a transcoder profile with the following locator url:

s3://oz-zl-test-files/test-runs/zypline-api/test_524ad8a6-6501-4721-8ca9-7cc8e6b2a5ec/FeatureVideo_640x480_3mb.mov

The syntaxes will render:

{# file1.locator.dirname #} renders s3://oz-zl-test-files/test-runs/zypline-api/test_524ad8a6-6501-4721-8ca9-7cc8e6b2a5ec.
{# file1.locator.extname #} renders .mov.
{# file1.locator.basename #} renders FeatureVideo_640x480_3mb.
{# file1.locator.url #} renders s3://oz-zl-test-files/test-runs/zypline-api/test_524ad8a6-6501-4721-8ca9-7cc8e6b2a5ec/FeatureVideo_640x480_3mb.mov.

Other file properties

There are numerous file properties that result from the Probe process. Below is a list of the most commonly used properties. Note that depending on the Media item, some of the properties will be available, while others might not.

File properties
`.id`	`.autoQcProperties`	`.entityTypeId`
`.filename`	`.fileLocator`	`.generatorWorkflowId`
`.size`	`.mxfIndexLocator`	`.virtualFolderId`
`.info`	`.pHashLocator`	`.titleId`
`.md5`	`.sceneDetectionLocator`	`.parentId`
`.sha1`	`.language`	`.demuxProfileId`
`.etag`	`.languages`	`.transcoderProfileId`
`.duration`	`.type`	`.entityId`
`.frameRate`	`.origin`	`.extension`
`.mimeType`	`.notes`	`.basename`
`.locatorUrl`	`.status`	`.path`
`.properties`	`.statusUpdatedById`	`.definition`
`.tracks`	`.qcNotes`	`.frameRateNumerator`
`.mediainfoProperties`	`.statusUpdatedAt`	`.frameRateDenominator`
`.userProperties`	`.generatedReason`	`.sizeGB`
`.organizationId`	`.imfEssenceType`	`.codec`
`.createdAt`	`.requireDrm`	`.ingested`
`.createdById`	`.errors`	`.startTimecode`
`.updatedAt`	`.readOnly`	`.endTimecode`
`.updatedById`	`.playable`	`.customFields`
`.deletedAt`	`.isIngested`	`.trackingProperties`

The .userProperties contains valuable information defined in Connect at a Media item level, such as ad breaks timecodes, which can be referenced by .userProperties.adBreaks['index'].timecode

A more comprehensive list of properties is found below.

User properties

User property	Details
`.language`	Available for Timed text media items.
`.timeDelta`	Available for Timed text media items.
`.targetTimecodeFormat`	Available for Timed text media items.
`.boundingBox`	Available for video media items. Contains the following sub-properties: `.width` `.height` `.xOffset` `.yOffset`
`.inputClipping`	Available for video media items. Contains the following sub-properties: `.startTimecode` `.endTimecode`
`.adBreaks`	Available for video media items. Contains an array of adBreaks that have been setup in the Connect Workbech. Can reference the timecode by index as a sub-property: `.userProperties.adBreaks['index'].timecode`
`.transcodeHash`	Available for video media items.
`.tracks`	Contains the following sub-properties: `.type` `.index` `.tagId`

Additional functionality

This section covers information that is related to the Template referencing syntax but using alternative methods, such as through operating in the user interface, compared to writing syntax.

Using these methods can offer similar results to using the syntax and as such, they are mentioned in a separate section.

NTP Job Template Inputs

NTP Profiles allow for Inputs to be declared on the right side of the page. This process involves declaring:

the Type of input, either a File or a Composition
the Resolution mode, more specifically how the input will be identified (ie. by Tag)
- based on this choice, an additional field will need to be filled in to further identify the input
a Variable name or how this input will be named in the NTP job template, it can be any name that we want to use in the template

NTP payload

Using Example #2 as a starting point, we referenced the codec value of a media item with the following syntax entity.tags['NameOfTag'].videoTrack.codec

By defining an input as follows:

Type: File
Resolution Mode: Tag
Tag: NameOfTag
Variable Name: file1

We can now reference the value above with the following notation file1.videoTrack.codec.

Syntax best practices

By default, the general LiquidJS documentation will cover a substantial part of the use cases.

Here is a short description:

Notation	Use	Example
`{{ }}`	Output a value from the referencing syntax for Metadata and Package templates (see more info below about NTP Job Templates)	In a Metadata template, we need to output a metadata value from a Title in a tag: `<shortDescription>{{entity.attributes['en-us']['Short Description']}}</shortDescription>`
`{% %}`	Used when assigning values or when creating `for`, `if` blocks etc.	For a NTP Job Template, a series of conditions and `for` loops:
`{# #}`	Used exclusively for NTP Job Templates, in order to not create conflicts with Hybrik’s syntax resolving when outputting values. In this scenario, it should replace the `{{ }}` notation to reference entities and metadata from Connect, as well as any other information that we want to resolve before sending the payload to the transcoding provider.	Same as the example above, note how the `i` increment is referenced in the `for` loop, this means that the syntax will be resolved in Connect before sending the payload over to the transcoding provider:

Important note regarding syntax | `.property` vs `['property']`

The template's syntax allows a property to be referenced with the .property or with the ['property'] notation.

Taking Example #2 into account, let’s add the following details:

NameofTag will have the Trailer value, which is a Tag that has been configured in the Connect Organization
The referencing syntax for the given example will be entity.tags['Trailer'].videoTrack.codec
As mentioned at the beginning of this section, we can alter the syntax to get the same results
- no brackets → entity.tags.Trailer.videoTrack.codec
- all brackets → entity.tags['Trailer']['videoTrack']['codec']

Generally, the bracket notation will always allow properties that have spaces inside them. If we alter the example again to:

Trailer → Feature HD
We can no longer use the non-bracket notation
- Incorrect → entity.tags.Feature HD.videoTrack.codec
We are forced to use the bracket notation, but we are still flexible with the rest of the sub-properties as they contain no spaces
- Correct → entity.tags['Feature HD'].videoTrack.codec
- Correct → entity.tags['Feature HD']['videoTrack']['codec']

As a rule of thumb, it is recommended to use the bracket notation for Metadata fields and Tags, and non-bracket notation for the rest of the properties.

NTP Validations API Documentation

Ateliere Contact us