Link relation loc:delete-item-in-folder-by-id-bulk-command

New in MC | Cloud UX 2020.9

Overview

Start a long-running command that deletes a list of items from the current folder.

If a requested item doesn’t exist AM and PM behave differently: MediaCentral Production Management will return this item as failed, whereas MediaCentral Asset Management returns success for it.

The link relation is similar to loc:delete-item-by-id-bulk-command with the difference that the link relation is only available in the loc:item resource of a folder and only affects items in that folder. If you try deleting items that are not in this but in a different folder, the call will fail for those items with code 400 Bad Request.

HTTP method	POST
URI template variables	-
Query parameters	mode	The deletion mode. The exact behavior depends on the system, see Information for specific systems for details. The value can be one of: reference: Delete only the items in the folder, but not the assets. media: Delete only the media files of the items. metadata: Delete the items in the folder and the assets, but leave the media files intact. all: Deletes the items in the folder and the assets, including the media files. If the parameter is not given or empty, the default mode depends on the system.
override-reservations	Override the reservation on the asset. Only for MediaCentral Production Management and MediaCentral Asset Management. See below for details.
Request body		An array of item IDs: `[ "/Catalogs/Test/DoesntExist", "/Catalogs/Test/060a2b340101010101010f0013-000000-070812007d070018-060e2b347f7f-d080" ]`
HTTP response	200 OK	The command was started.
400 Bad Request	The request was invalid.
Response body	-	A command:command resource. You should poll the status of the command by calling the "self" link periodically until the value of command.lifecycle is "finished" or "error". When the lifecycle is "finished", the property result contains a bulk response with information about success or failure for the requested items. The order of entries in the result property corresponds to the order of IDs in the request body. Properties per item: success: true if the deletion worked for the item, false if it failed. data: the item ID. httpStatus: HTTP status that a non-bulk call would have returned. errorCode: CTMS error code (only for failed items). errorMessage: Error message (only for failed items). Example with a failed item and a successful item: `{ "command": { "lifecycle": "finished" }, "payload": { "result": [ { "success": false, "data": "/Catalogs/Test/DoesntExist", "httpStatus": 404, "errorCode": "CTMS/ITEM_NOT_FOUND", "errorMessage": "Item /Catalogs/Test/DoesntExist not found" }, { "success": true, "data": "/Catalogs/Test/060a2b340101010101010f0013-000000-070812007d070018-060e2b347f7f-d080" } ] } }`
Available in		loc:item of folders

HTTP method

POST

URI template variables

Query parameters

mode

The deletion mode. The exact behavior depends on the system, see Information for specific systems for details. The value can be one of:

reference: Delete only the items in the folder, but not the assets.
media: Delete only the media files of the items.
metadata: Delete the items in the folder and the assets, but leave the media files intact.
all: Deletes the items in the folder and the assets, including the media files.

If the parameter is not given or empty, the default mode depends on the system.

override-reservations

Override the reservation on the asset. Only for MediaCentral Production Management and MediaCentral Asset Management. See below for details.

Request body

An array of item IDs:

[
  "/Catalogs/Test/DoesntExist",
  "/Catalogs/Test/060a2b340101010101010f0013-000000-070812007d070018-060e2b347f7f-d080"
]

HTTP response

200 OK

The command was started.

400 Bad Request

The request was invalid.

Response body

A command:command resource.

You should poll the status of the command by calling the "self" link periodically until the value of command.lifecycle is "finished" or "error".

When the lifecycle is "finished", the property result contains a bulk response with information about success or failure for the requested items. The order of entries in the result property corresponds to the order of IDs in the request body.

Properties per item:

success: true if the deletion worked for the item, false if it failed.
data: the item ID.
httpStatus: HTTP status that a non-bulk call would have returned.
errorCode: CTMS error code (only for failed items).
errorMessage: Error message (only for failed items).

Example with a failed item and a successful item:

{
  "command": {
    "lifecycle": "finished"
  },
  "payload": {
    "result": [
      {
        "success": false,
        "data": "/Catalogs/Test/DoesntExist",
        "httpStatus": 404,
        "errorCode": "CTMS/ITEM_NOT_FOUND",
        "errorMessage": "Item /Catalogs/Test/DoesntExist not found"
      },
      {
        "success": true,
        "data": "/Catalogs/Test/060a2b340101010101010f0013-000000-070812007d070018-060e2b347f7f-d080"
      }
    ]
  }
}

Available in

loc:item of folders

Information for specific systems

MediaCentral Asset Management

Query parameter	Value	Description
mode	reference	Delete the reference in the folder, but leave the asset in place. This is the only mode that allows deleting sub folders.
metadata	Not supported.
media	Delete all media files of the referenced assets. Media files that are shared with other assets are not deleted.
all	Delete items in the folder and the referenced assets, including the media files. Media files that are shared with other assets are not deleted. Up to MC\|AM 2023.7, the mode was only supported if MAMAssetsCTC was configured to use a BPMN process for deletion.
not given or empty	The default mode is reference.
override-reservations	New in MC \| Cloud UX 2023.12 Defines how to deal with reservations. One of: all: Override all reservations. media: Override reservations when deleting only media files (mode=media). none, not given or empty: Don’t override reservations. Deletion will fail for reserved assets. Up to 2023.7, the query parameter was ignored.

Query parameter

Value

Description

mode

reference

Delete the reference in the folder, but leave the asset in place.

This is the only mode that allows deleting sub folders.

metadata

Not supported.

media

Delete all media files of the referenced assets. Media files that are shared with other assets are not deleted.

all

Delete items in the folder and the referenced assets, including the media files. Media files that are shared with other assets are not deleted.

Up to MC|AM 2023.7, the mode was only supported if MAMAssetsCTC was configured to use a BPMN process for deletion.

not given or empty

The default mode is reference.

override-reservations

New in MC | Cloud UX 2023.12

Defines how to deal with reservations. One of:

all: Override all reservations.
media: Override reservations when deleting only media files (mode=media).
none, not given or empty: Don’t override reservations. Deletion will fail for reserved assets.

Up to 2023.7, the query parameter was ignored.

MediaCentral Production Management

Deleting sub folders is not supported.

Query parameter	Value	Description
mode	reference	Delete the reference in the folder, but leave the asset in place. The call fails for an item if it is the last reference to the asset. In MediaCentral Production Management this is an unusual deletion mode - it is offered for CTMS compatibility reasons (only) and requires more processing time and creates a higher PM Engine load than the other modes. Normally a user should not care if an item is the last reference to an asset. Assets are protected by reservations or because they are still referenced.
metadata	Delete items in a folder and the referenced assets (if the item is the last reference to the asset). Assets are deleted by the so called Scheduled Deletion. An Administrator can configure in the MediaCentral Production Management Delete Behavior settings when the PM Engine performs the asset deletions. If the asset has online media files associated and the Delete Behavior setting "Permanently delete assets and associated online media from the Orphan Clips folder" is selected, the media is deleted together with the asset during the Scheduled Deletion. Otherwise the asset is moved to the Orphan Clips/Kept Media folder.
media	Delete all (online) media files of the referenced assets. Items and referenced assets are not deleted, but will become offline.
all	Delete items in a folder and the referenced assets (if the item is the last reference to the asset), including the media files.
not given or empty	The default mode is metadata.
override-reservations	Defines how to deal with reservations. One of: none: Do not override any reservation. This is the default if the query parameter is not given or empty. media: Override reservations on media files. metadata: Override reservations on assets. all: Override all reservations.

Query parameter

Value

Description

mode

reference

Delete the reference in the folder, but leave the asset in place.

The call fails for an item if it is the last reference to the asset.

In MediaCentral Production Management this is an unusual deletion mode - it is offered for CTMS compatibility reasons (only) and requires more processing time and creates a higher PM Engine load than the other modes.

Normally a user should not care if an item is the last reference to an asset. Assets are protected by reservations or because they are still referenced.

metadata

Delete items in a folder and the referenced assets (if the item is the last reference to the asset).

Assets are deleted by the so called Scheduled Deletion. An Administrator can configure in the MediaCentral Production Management Delete Behavior settings when the PM Engine performs the asset deletions.

If the asset has online media files associated and the Delete Behavior setting "Permanently delete assets and associated online media from the Orphan Clips folder" is selected, the media is deleted together with the asset during the Scheduled Deletion. Otherwise the asset is moved to the Orphan Clips/Kept Media folder.

media

Delete all (online) media files of the referenced assets.

Items and referenced assets are not deleted, but will become offline.

all

Delete items in a folder and the referenced assets (if the item is the last reference to the asset), including the media files.

not given or empty

The default mode is metadata.

override-reservations

Defines how to deal with reservations. One of:

none: Do not override any reservation. This is the default if the query parameter is not given or empty.
media: Override reservations on media files.
metadata: Override reservations on assets.
all: Override all reservations.

If the caller does have the necessary rights in the PM DB to delete one of the supplied items, the command will fail with 403 Forbidden and no item will be deleted.

{
  "command": {
    "error": {
      "text": "User permissions do not allow this operation",
      "code": "CTMS/INSUFFICIENT_PERMISSIONS",
      "httpCode": 403,
      "cause": "runtimeError"
    }
  }
}

When the deletion command finished successfully, the command property payload contains — next to the properties result and command-parameters — an additional property details with a summary of the items, assets, and media files that were deleted or where deletion has failed. See deletion command payload for details.

MediaCentral Newsroom Management

Deleting sub folders is not supported.

Query parameter	Value	Description
mode	reference	Not supported.
metadata	Delete stories from a queue, including file references, but not the physical files on disk.
media	Not supported.
all	Same as metadata: Delete stories from a queue, including file references, but not the physical files on disk.
not given or empty	The default mode is metadata.
override-reservations	is ignored.

Query parameter

Value

Description

mode

reference

Not supported.

metadata

Delete stories from a queue, including file references, but not the physical files on disk.

media

Not supported.

all

Same as metadata: Delete stories from a queue, including file references, but not the physical files on disk.

not given or empty

The default mode is metadata.

override-reservations

is ignored.

Example

Example of the command:command resource after the command is finished. In the example one item succeeded and one failed. Note the result property within the payload sub property.

Example: Finished command.

 
{
  "command": {
    "type": "loc:delete-item-in-folder-by-id-bulk-command",
    "id": "ab1b0976-0025-4211-87fa-fda6c033f4c9",
    "lifecycle": "finished",
    "state": {
      "text": "Deleted 1 of 2 items",
      "code": "avid.mam.assets.access/DELETE_ITEMS_DONE",
      "params": {
        "totalCount": 2,
        "successCount": 1,
        "failureCount": 1
      }
    },
    "progress": 100,
    "serviceName": "MAMAssetsCTC_1",
    "serviceInstance": "MAMAssetsCTC_1",
    "serviceVersion": "7.5.0.91",
    "host": "hostname",
    "created": "2020-08-11T14:25:45.1426858+02:00",
    "modified": "2020-08-11T14:25:45.6270553+02:00",
    "finished": "2020-08-11T14:25:45.6270553+02:00"
  },
  "version": "1.0",
  "payload": {
    "result": [
      {
        "success": true,
        "data": "123330.1444213"
      },
      {
        "success": false,
        "data": "",
        "httpStatus": 400,
        "errorCode": "avid.mam.assets.access/BAD_ARGUMENT",
        "errorMessage": "Invalid item ID"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://host/…"
    }
  }
}