Release notes

2024r12

Custom attributes in copyright API

Custom attributes were already supported in the content, MAM, on-demand schedule, person and trailer API.

From this version, the copyright API also supports custom attributes of the following types for the concept of copyright sheets only:

  • Boolean

  • Date

  • Decimal number

  • Drop-down list

  • Drop-down list for multiselection

  • Duration

  • Integer

  • Reference

  • String

  • Text

  • Web

In the GET /copyrightSheets/{copyrightSheetId} call, 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 /copyrightSheets/9296208812?customAttributes=exclusive

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

    "customAttributes": [
        {
            "attributeName": "exclusive",
            "value": true,
            "type": "Check box"
        }
    ]

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 /copyrightSheets/v1/dropdown/customAttribute/department.

To update one or more custom attributes on a copyright sheet using the POST or PUT /copyrightSheets calls, an array needs to be provided with the attribute name and value of the custom attributes that should be updated:

"customAttributes": {
            "exclusive": "false"
            "department": "film"
        }

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

The YAML will be updated in an upcoming version. Until then, the changes above can already be entered manually.

2023r3

Introduction of copyright API

From this version, the copyright API has been introduced. It allows to create, update and delete copyright sheets, copyright materials and material uses. It can also be used to link copyright sheets to content.

The full API definition can be consulted in the API explorer.

In a high-level overview, the API contains the following calls.

Copyright sheets

POST /copyrightSheets

  • The version and status attributes are mandatory. The available values can be retrieved using the GET /copyrightVersions and GET /copyrightVersions/{versionId}/statuses calls.

  • It is possible to define a list of material uses with the materialUseList attribute. The materials already have to exist. For each material use in the array, the materialId and durationInUse are mandatory. When this materialUseList attribute is specified, all existing material uses will be replaced by the list specified in the call.

  • By specifying the contentId, it is possible to link a copyright sheet to content. If this is not provided, the created copyright sheet will be present in the copyright import assistant.

PUT /copyrightSheets/{copyrightSheetId}

  • The copyrightSheetId attribute is mandatory.

  • For the materialUseList, the same conditions apply as in the POST call.

DELETE /copyrightSheets/{copyrightSheetId}
GET /copyrightSheet/{copyrightSheetId}

When a user is logged in and authenticated, the permission needed for these calls is Copyright Management (browser for the GET call and editor).

Copyright materials

  • POST, PUT /simpleMaterials

  • POST, PUT /musicMaterials

  • POST, PUT /textMaterials

  • POST, PUT /artMaterials

  • POST, PUT /filmMaterials

  • POST, PUT /photoMaterials

  • POST, PUT /otherMaterials

  • DELETE /materials

  • GET /materials

When a user is logged in and authenticated, the permission needed for these calls is Material Management (browser for the GET call and editor).

POST calls

No mandatory fields. When created, the type of the material will automatically be the same as that of the call.

For example, if you use the POST /musicMaterial call, you will automatically create a music material.

If the materialId is provided in the call and matches the external reference of an existing copyright material of the same type as the call, this material will be updated. If a material exists with that same reference but with a different type, an error is returned.

PUT calls

The materialId is mandatory and should belong to a material with the same type as the call. If not, an error is returned.

Material uses

It is already possible to create material uses with the copyright sheet calls but the materialUseList attribute in those calls always replaces all existing material uses. To manage individual material uses, the following calls can be used.

POST /materialUses

The following attributes are mandatory:

  • copyrightId: the external reference of the copyright sheet on which the use should be created

  • materialId: the external reference of the material that will be used

  • durationInUse: the duration of the material use on the copyright sheet in format HH:MM:SS.

PUT /materialUses/{materialUseId}

The materialUseId attribute is mandatory.

DELETE /materialUses/{materialUseId}
GET /materialUses/{materialUseId}

GET calls for drop-down lists

  • GET /copyrightVersions: Maps to WOnCopyRightSheetVersion drop-down list

  • GET /copyrightVersions/{versionId}/statuses: Maps to WOnCopyRightSheetStatus

  • GET /materialUseSubTypes/{materialType}: Maps to PSIMaterialType

  • GET /castFunctions: Maps to Function

  • GET /castTypes: Maps to PSICastType

  • GET /licences: Maps to PSICastParticipantLicenseType

  • GET /carriers: Maps to PSIAudioCarrier

  • GET /soundvalues: Maps to Sound

  • GET /languages: Maps to PSILanguage

  • GET /countries: Maps to PSICountry

  • GET /materialUseSubTypes: Maps to WOnCopyRightMaterialUseSubType