Release notes

2024r2

Custom attributes in on-demand schedule API

Custom attributes were already supported in the content, MAM, trailer API and person API.

From this version, the on-demand schedule API also supports custom attributes of the following types:

  • Boolean

  • Date

  • Decimal number

  • Drop-down list

  • Drop-down list for multiselection

  • Duration

  • Integer

  • Reference

  • String

  • Text

  • Web

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

  • ?customAttributes=attributeName,attributeName

  • ?customAttributes=allCustomAttributes

For example: GET /onDemandTransmissions/9296208812?customAttributes=letterboxdAverage

For each custom attribute, the attribute name, value and type will be given. For example:

    "customAttributes": [
        {
            "attributeName": "letterboxdAverage",
            "value": "9",
            "type": "String field"
        }
    ]

For custom attributes of the type Drop-down list or Drop-down list for multiselection, a GET /dropdown/customAttribute/{attributeName} call has been added to the API to retrieve the possible values. The {attributeName} should be replaced with the actual attribute name of the custom attribute.

For example, GET /onDemandTransmissions/v1/dropdown/customAttribute/ageGroup.

To update one or more custom attributes on an on-demand transmission using the POST or PUT /onDemandTransmissions calls, an array needs to be provided with the attribute name and value of the custom attributes that should be updated:

    "customAttributes": {
            "letterboxAverage": "9",
            "ageGroup": "18-35"
        }

If the value is left empty by using null or "" for some types, the custom attribute is emptied.

The YAML has been updated for this change. It can be retrieved by using the GET /api call.

For API developers, the following parts of the YAML were updated.

30: get
The addition of parameters for custom attributes at line 34
254:  new drop-down call for custom attributes
395: schema for custom attributes
419: OnDemandTransmissionforGET schema
868: change to reference to new GET schema 
 - $ref: '#/components/schemas/OnDemandTransmissionForGet'

For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml

Changes to deleting and updating transmissions in on-demand schedule API

Previously, it was not possible to

  • update an on-demand transmission using the POST or PUT /onDemandTransmissions calls,

  • delete an on-demand transmission using the DELETE /onDemandTransmissions/{onDemandTransmissionId} call

of the on-demand schedule API when

  • a format template had already been applied;

  • an encoding media asset sequence was linked;

  • publication transmissions had been created;

  • publication records had been created;

In this case, a 422 error would be returned with the specific scenario:

Could not update/delete transmission:

  • the on demand transmission has a format template applied

  • the on demand transmission has encoding media asset linked

  • the on demand transmission has publication transmissions

  • the on demand transmission has publication records

For example:

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2024-03-05T08:18:03Z",
    "concept": "OnDemandTransmission",
    "id": "8521812812",
    "errors": [
        {
            "errorCode": "ONDEMANDSCHEDULE-00017",
            "description": "Could not update/delete transmission: the on demand transmission has publication transmissions",
            "data": [
                "the on demand transmission has publication transmissions"
            ]
        }
    ]
}

However, updating or deleting an on-demand transmission is allowed when doing it in WHATS'ON Base, even if there are already publication transmissions or publication records.

Therefore, from this version, it will be allowed to update or delete an on-demand transmission with publication transmissions and records in the on-demand schedule API.

When updating, such as changing the start or end date of the on-demand transmission using the POST or PUT calls, the linked publication transmissions and publication records will also be updated. So instead of the error message, a 200 message is returned:

{
    "statusCode": "200",
    "message": "OnDemandTransmission has been modified",
    "timestamp": "2024-03-05T08:20:32Z",
    "concept": "OnDemandTransmission",
    "id": "8521812812"
}

When deleting an on-demand transmission using the DELETE call, the linked publication transmissions will also be deleted and the status of the publication records will be changed to either Deleted or Deleted after publication, depending on whether the record has previously been published.

Note that the constraints for the linked format template and encoding media asset are still applied.

Nothing has changed in the YAML for this new behaviour.

2022r3

Additional fields in GET transmission calls of on-demand schedule API

From this version, in the response of the

  • GET call to search for a specific on-demand transmission ((GET /onDemandTransmissions/:onDemandTransmissionId:)

  • GET call to search for on-demand transmissions (GET /onDemandTransmissions),

of the on-demand schedule API, additional fields have been added:

  • mediaAssetId: the external reference of the media asset linked to the transmission

  • contentType: the description of the type of content, for example program, episode etc.

  • exploitationRightId: the external reference of the right linked to the transmission

This caused changes to the YAML so it is recommended to execute the call to get the newest version of the YAML.

2020r1.002.000

API version: v1.0.0

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 a transmission.

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.

2019r1.000.000

API version: v1.0.0

Addition of On-demand schedule API

From this version on, it is possible to manage on-demand transmissions using the On-demand schedule API.