Release notes

2022r10

Extra custom attribute types in content, MAM and trailer API

Previously, the content, MAM and trailer API already supported the following custom attribute types:

  • Boolean

  • Date

  • Drop-down

  • Integer

  • Reference

  • String

  • Text

  • Web

From this version, the following types have been added:

  • Duration:
    With default format HH:MM:SS:iii

  • Decimal number:
    A period should be used as decimal and maximum two digits after the decimal will be returned.

  • Drop-down list for multiselection

They have been added to the calls that already supported custom attributes. A new version of the YAMLs can be retrieved to use these attributes.

In the GET calls, the following suffixes can be added to the call to either get only specified attributes in the response or all custom attributes of the supported types:

  • ?customAttributes=attributeName,attributeName

  • ?customAttributes=allCustomAttributes

For each custom attribute, the attribute name, value and type will be given. The new types will be included in the response as follows:

    "customAttributes": [
        {
            "attributeName": "customMultiMA",
            "value": [
                "Value1",
                "Value2"
            ],
            "type": "Drop-down list for multiselection"
        },
        {
            "attributeName": "cADecimal",
            "value": 2.64,
            "type": "Decimal number field"
        },
        {
            "attributeName": "cADuration",
            "value": "02:03:04.000",
            "type": "Duration field"
        }
    ]

In POST or PUT calls, an array of custom attributes needs to be provided with their attribute name and value. If the value is left empty by using null or "" for some types, the custom attribute is emptied. The new types should be specified as follows:

    "customAttributes": {
        "cADecimal": 1.23,
        "cADuration": "01:32:20.000",
        "customMultiMA": ["TestWOnDynamicDomain23"]
    }

GET /products call in content API

Previously, in the content API, a GET call needed to be used per type of content:

  • GET /programs

  • GET /episodes

  • GET /seasons

  • GET /series

From this version, a new call, GET /products/{contentId}, was added. It allows you to search for content regardless of the type. It will use the provided content ID to identify the content type and return the relevant attributes. These attributes are the same as in the existing GET calls.

It is also possible to add the custom attributes parameter or debug parameters (RN-4469) to the call URL.

Content running orders in content API

In a previous version, content running orders were introduced for more flexible planning. (RN-3641) However, they were not yet part of the content API.

From this version, the following was added or changed to include them in the content API:

New calls

GET, POST and PUT /contentRunningOrders

Content running orders can only be created, edited and retrieved in full with the these specific calls, not using the product calls. It is also possible to create content structures using the type. (RN-4496)

GET, POST, PUT and DELETE /contentRunningOrderElements

Products can only be added to or removed from content running orders using these calls, not using the product calls.

POST /contentRunningOrderElementsForSeries

This call can be used to add all episodes of a series at once to a content running order.

GET, POST, PUT and DELETE /pressSheetsCRO

Press sheets on content running orders can only be created or edited with these specific calls, not the content press sheet calls.

More information on how to configure them can be found in the YAML.

Existing calls

GET /programs and /episodes

The following attributes were added:

"displayType": "program"
 "defaultStructureSeries": "12345678"
 "defaultContentStructure": "12345678"
 "contentRunningOrderElements": [
        {
            "contentRunningOrderElementId": "7445097000",
            "contentRunningOrderId": "7445093000",
            "contentId": "143048527",
            "orderNo": 2,
            "displayType": "programType",
            "displayNumber": null,
            "displaySeason": null,
            "version": "Default",
            "isDefault": false,
            "seasonId": "7445043527",
            "displayTypeCRO": null,
            "displaySeasonCRO": null
        }
    ]

This represents a list of content running order elements linked to the product and its properties in the content running order.

PUT, POST /programs, /episodes, /seasons and versions

The following attributes were added:

"displayType": "string"
 "defaultContentStructure": "string"

GET /season 

"displayType": "series",
 "defaultStructureSeries": null,
 "defaultContentStructure": null, 
 "contentRunningOrders": [
        {
            "contentRunningOrderId": "7445093000",
            "type": null,
            "isStructure": false
        }
    ]

This represents a list of content running orders created on the series.

Additional drop-down list calls

  • /productDisplayTypes:
    For the PSIProductDisplayType drop-down list

  • /contentRunningOrderDisplayTypes:
    For the PSIContentRunningOrderDisplayType drop-down list

  • /contentRunningOrderTypes:
    For the PSIContentRunningOrderType drop-down list

  • /contentRunningOrderElementTypes:
    For the PSIContentRunningOrderElementType drop-down list

  • /psiContents:
    For the PSIContents drop-down list

  • /targetGroups:
    For the TargetGroup drop-down list

  • /croExternalDisplayInstructions:
    For the CROExternalDisplayInstruction drop-down list

Fix for inheritance from series to episodes in content API

Previously, when updating a series using a PUT or POST /seasons call, then no changes were propagated to its episodes.

This issue has been fixed. The episodes that had the same values for the updated properties will inherit the changes, as if the inheritance method was set to Only if values are equal.

For example, a series and most episodes had a duration of 00:40:00 while one episode had a duration of 00:43:00. When the POST call changes the duration of the series to 00:47:00, then the series and the episodes that had 00:40:00 as duration will be updated.

2022r8

Contact person added to GET, POST and PUT calls of content API

The contactPerson attribute has been added to the

  • response of the GET

    • /program

    • /seasons

    • /series

    • /episodes calls,

  • body of the PUT and POST

    • /program

    • /seasons

    • /series

    • /episodes calls

of the content API.

A new version of the YAML should be retrieved to use this attribute.

The attribute corresponds to the external reference of the person linked as contact person. When no persons with the defined reference can be found or when multiple persons exist with the reference, the appropriate error messages are returned.

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2022-11-30T15:29:33Z",
    "concept": "Program",
    "id": "1401698527",
    "errors": [
        {
            "errorCode": "CONTENT-00035",
            "description": "No person found with id BAPI",
            "data": [
                "BAPI"
            ]
        }
    ]
}

2022r7

Fix for clearing parental ratings in PUT and POST calls of content and MAM API

Parental ratings on content and media assets are defined per regulator. This means they are represented as an array in API calls:

    "ratings": [
        {
            "regulator": "localRegulator",
            "rating": "12",
            "reason": null
        },
        {
            "regulator": "Ofcom",
            "rating": "allAges",
            "reason": null
        }
    ]

Previously, when trying to clear the ratings while updating a product or media asset by leaving the "rating": null in the PUT or POST calls of the APIs, an error message would appear saying the rating was invalid.

This issue has been fixed. When specifying null as value for the rating attributes, then the specific rating will be cleared. When sending null for the ratings array, all ratings per regulator will be deleted.

2021r2.000

API version: v1.3.1

More custom attribute types

See release notes of version 2021r2.001.

Since version 2020r2.002, a number of types of custom attributes were already supported by the content API:

  • Check boxes
  • Drop-down lists
  • String fields

They could be included in the body of the PUT and POST calls and included as parameters in the GET call.

From this version, support for the following types has been added:

  • Date fields
  • Number fields
  • Reference fields
  • Text fields
  • Web fields

In the GET calls, the following suffixes can be added to the call to either get only specified attributes in the response or all custom attributes of the supported types:

  • ?customAttributes=attributeName,attributeName
  • ?customAttributes=allCustomAttributes

For each custom attribute on the product, the attribute name, value and type will be given. For the reference custom attributes, the referenced concept is also included:

{    "customAttributes": [
        {
            "attributeName": "cADate",
            "value": "2021-10-04",
            "type": "Date field"
        },
        {
            "attributeName": "cAMediaAsset",
            "value": "6111521000",
            "type": "Reference field",
            "concept": "Media asset"
        },
        {
            "attributeName": "cANumber",
            "value": 1,
            "type": "Number field"
        },
        {
            "attributeName": "cAText",
            "value": "Shaken, not stirred",
            "type": "Text field"
        },
        {
            "attributeName": "cAWeb",
            "value": "https://www.geekster.be/",
            "type": "Web field"
        }
    ]
}

In the POST and PUT calls, an array of custom attributes needs to be provided with their attribute name and value. If the value is left empty by using null or "" for some types, the custom attribute on the product is emptied.

{
    "contentId": "PGM001",
    "customAttributes": {
        "cADate": "2021-10-01",
        "cAMediaAsset": "3350456000",
        "cANumber": "10",
        "cAText": "I am inevitable",
        "cAWeb": "https://www.geekster.be"
    }
}

Debug parameters

See release notes of version 2021r2.001.

Using the GET calls in the content API, you can retrieve the metadata properties of products in WHATS'ON. However, it was not possible to retrieve more technical information such as the date the product was created or last modified.

From now on, a debug parameter can be added to the GET calls (but not search calls) for all product types in the content API.

It is possible to mention the specific parameters and separate them using commas or to include all:

  • :contentId?debug=dateCreatedUTC,dateModifiedUTC
  • :contentId?debug=all

An example:

basepath/content/v1/programs/6629341527?debug=dateCreatedUTC

The response of the GET call will then include these parameters in a separate attribute converted to UTC time.

The format will be [YYYY-MM-DD]T[HH:MM:SS.MSMSMS][+HH:00] where the final part represents the time difference to UTC time.

For example:

{
    "contentId": "6629341527",
    "contentType": "program",
    "title": "SHANG-CHI AND THE LEGEND OF THE TEN RINGS",
    "duration": "02:00:00",
    "debugInfo": {
        "dateCreatedUTC": "2021-10-01T11:45:27.900+02:00",
        "dateModifiedUTC": "2021-10-01T11:45:42.032+02:00"
    }
}

When the debug parameter is not in the call, it is not visible in the response. When it is in the call but it is not included correctly, the following response will be returned:


{
    "statusCode": "400",
    "message": "Bad Request",
    "timestamp": "2021-10-01T12:13:10Z",
    "concept": "Program",
    "id": "6629341527",
    "errors": [
        {
            "errorCode": "CORE-00007",
            "description": "Invalid debug attributes",
            "data": [
                "dateCreatedUT"
            ]
        }
    ]
}

2021r2.000

API version: v1.1.0

Custom attributes

From this version on, it is possible to include custom attributes in the calls of the content API.

  • Check boxes
  • Drop-down lists
  • String fields

They could be included in the body of the PUT and POST calls and included as parameters in the GET call.

2021r1.000

Press sheets in content API

From this version, it is possible to create, update and delete press sheets via the content API.

New calls are added:

  • POST pressSheets
  • PUT pressSheets/{pressSheetId)
  • GET pressSheets/{pressSheetId)
  • DELETE pressSheets/{pressSheetId)
  • GET pressTargets
  • GET pressStatus
  • GET parentalRatings

Some existing calls got an extra section in their response detailing the existing press sheets:

  • GET programs/{contentId}
  • GET series/{contentId}
  • GET season/{contentId}
  • GET episodes/{contentId}

2020r2.002

Improvements to content API

As from this version, the Description field of the Descriptions tab of the product navigator is also added to the content API. It is available for all POST, PUT and GET calls for content (programs, episodes, series, seasons). Also the Distributor number for episodes is added to POST, PUT and GET calls. Extra drop down fields have been added to the content schema as well:

  • originalLanguage

  • contentTargetGroup

  • content

  • form

  • broadcastMedium

This makes them available for product, series, season & episode calls. Furthermore, support for TitleTypes, for custom attributes on the concept Program and for the cast list has been added to the content API.

2020r1.002

API version: v1.0.1

External reference cannot be cleared by BAPI

Within any POST and PUT call, if a an attribute is sent empty, WHATS'ON will clear that field. Previously, this was also possible with the external reference of content.

Now, this is fixed. When no external reference is provided but the attribute is sent empty or Null, we will ignore that tag and proceed as if there was no ID field (external reference) provided. This means that it should remain as is in a PUT call or return a new one in a POST call.

2017r1.005

API version: v1.0.0

Addition of Content API

From this version on, it is possible to manage content using the Content API.