Every media item on AdmiralCloud is a mediaContainer. All collections (private or group collection) as well as publicareas (press area, mediahub) are mediaContainers as well.
Availability of mediacontainers for external publishing
There are a lot of parameters that define it a mediacontainer is available for external pages (such as weblinks, projects/public areas, mediahubs etc).
- Flag -> only mediacontainers with flag 0 are available for external links
- start and end date -> if start and/or end date are set, they determine the available time range
- settings for embedLinkNotAllowed, publicAreaNotAllowed, downloadNotAllowed, downloadOriginalNotAllowed
Deleting mediacontainers
MediaContainers are usually put in trash when a user deletes it. Exceptions are dropsites, downloadlinks, pinboard, collections and miscellaneous media type like avatar, watermark, contactPictures or welcomeBackgrounds.
MediaContainers with media content
If a mediaContainer of type video, audio, image or document is put into trash all connection to publicareas and other mediacontainers are immediately removed. All other data related to the mediacontainer (e.g. chapters, subtitles, etc) remain intact and can be restored.
Embedlinks remain also intact but are deactivated. They are automatically restored if a mediaContainer is restored from trash.
modelCounts for this mediaContainer will reflect the changes, so embedlinks will be shown as 0. modelCounts for tags the mediaContainer uses will also reflect the change, although the relation itself remains intact.
MediaContainers of type publicarea
For mediaContainers which are publicareas the deletion will update all related mediacontainer documents, but the relation itself (between publicarea and mediacontainer) remains intact. This way, restoring a mediaContainer of type publicarea will also bring back all mediacontainer relations.
Reference
Find MediaContainer
Find a specific mediacontainer (by id). The mediacontainer is returned including additional fields like controlGroups, tags, etc. If a public area is requested formats and mediacontainers are additionally returned in the result
Create MediaContainer
Creates a new mediacontainer (a new video, image, public area). The mediacontainer is related to all controlgroups of the user that are sent with the request.
Important notes:
- If no controlgroups are sent, then first user.individualConfiguration.preferredControlGroup is checked. If there’s no setting, the user’s first group is used.
- The user can have a individual configuration to prevent linking the new mediacontainer to all controlgroups. For example someone from the admin group does not want to have his
- uploaded videos added to the admin group, as they will spread into every child group, making the video globally available!
If you want to create additionalMedia (like logos or watermarks) make sure to set the appropriate flag. See below for details.
| Field | Type | Required | Description |
|---|---|---|---|
| audioLanguage | array | ✗ | One or more audioLanguage(s) of the new mediacontainer. Relevant for video and audio. |
| contacts | array | ✗ | Ids of contacts to assign to the new mediacontainer. |
| controlGroups | array | ✗ | ControlGroups for this mediacontainer. The session user must have access to the controlGroups. |
| copy | object | ✗ | Create a new mediacontainer based on a existing mediacontainer (copy/duplicate). |
| └ from | integer | ✗ | Id of the mediacontainer you want to copy |
| └ models | array | ✗ | Models your want to copy |
| └ container_name | object | ✗ | Setting for container_name of mediacontainer you want to copy |
| └ suffix | string | ✗ | Suffix that will be appended to container_name of the new mediacontainer |
| copyFrom | integer | ✗ | Id of mediacontainer to copy – for pressarea only! |
| createPublicarea | object | ✗ | Set of properties used when creating a publicarea |
| └ templateId | integer | ✗ | Id of template for publicarea. Only used, if you create a publicarea |
| └ start | integer | ✗ | Start date of publicarea as unix timestamp |
| └ end | integer | ✗ | End date of publicarea as unix timestamp |
| └ publish | boolean | ✗ | If true, the publicarea will be published. |
| └ withChannels | array | ✗ | Create a mediahub with the given channels |
| └ downloadLinkMediaContainer | integer | ✗ | Id of downloadlink mediacontainer. |
| downloadLinkMediaContainer | integer | ✗ | Id of downloadlink mediacontainer. |
| end | integer | ✗ | End date of publicarea as unix timestamp |
| flag | integer | ✗ | Flag for the this mediacontainer. Please see list above for details. Please note that the value will be checked against mediacontainer type. |
| formatIds | array | ✗ | Ids of formats to create, when creating a publicarea. |
| formats | array | ✗ | Ids of formats to create, when creating a publicarea. |
| notes | string | ✗ | Notes for this mediacontainer. Will never be public, but are visible to all users with access to this mediacontainer. |
| origin | string | ✗ | A string to identify the origin of a mediacontainer, e.g. an ID of a system you are migrating data from. |
| settings | object | ✗ | Optional settings for this mediacontainer. |
| └ externalAllowed | boolean | ✗ | TBA |
| └ internalOnly | boolean | ✗ | TBA |
| └ downloadNotAllowed | boolean | ✗ | TBA |
| └ downloadOriginalNotAllowed | boolean | ✗ | TBA |
| └ publicAreaNotAllowed | boolean | ✗ | TBA |
| └ embedLinkNotAllowed | boolean | ✗ | TBA |
| └ lock | boolean | ✗ | TBA |
| └ lockUser | integer | ✗ | TBA |
| └ deletionProtection | boolean | ✗ | TBA |
| └ startDate | integer | ✗ | TBA |
| └ startDateSetBy | object | ✗ | TBA |
| └ type | string | ✗ | TBA |
| └ id | integer | ✗ | TBA |
| └ endDate | integer | ✗ | TBA |
| └ endDateSetBy | object | ✗ | TBA |
| └ type | string | ✗ | TBA |
| └ id | integer | ✗ | TBA |
| └ allowedViewers | array | ✗ | TBA |
| └ fourEyesPrinciple | boolean | ✗ | TBA |
| start | integer | ✗ | Start date of publicarea as unix timestamp |
| subtype | string | ✗ | Subtype of the new mediacontainer |
| tags | array | ✗ | Optional settings for this mediacontainer. |
| templateId | integer | ✗ | Id of template for publicarea. Only used, if you create a publicarea |
| type | string | ✓ | Type of the new mediacontainer |
| uploader | string | ✗ | A string to identify the uploader of a mediacontainer, if this is not a registered user. |
| withChannels | array | ✗ | Create a mediahub with the given channels |
| Field | Type | Description |
|---|---|---|
| audioLanguage | array | One or more audioLanguage(s) of the new mediacontainer. Relevant for video and audio. |
| contacts | array | Ids of contacts to assign to the new mediacontainer. |
| controlGroups | array | ControlGroups for this mediacontainer. The session user must have access to the controlGroups. |
| copy | object | Create a new mediacontainer based on a existing mediacontainer (copy/duplicate). |
| └ from | integer | Id of the mediacontainer you want to copy |
| └ models | array | Models your want to copy |
| └ container_name | object | Setting for container_name of mediacontainer you want to copy |
| └ suffix | string | Suffix that will be appended to container_name of the new mediacontainer |
| flag | integer | Flag for the this mediacontainer. Please see list above for details. Please note that the value will be checked against mediacontainer type. |
| formatIds | array | Ids of formats to create, when creating a publicarea. |
| formats | array | Ids of formats to create, when creating a publicarea. |
| origin | string | A string to identify the origin of a mediacontainer, e.g. an ID of a system you are migrating data from. |
| settings | object | Optional settings for this mediacontainer. |
| └ externalAllowed | boolean | TBA |
| └ internalOnly | boolean | TBA |
| └ downloadNotAllowed | boolean | TBA |
| └ downloadOriginalNotAllowed | boolean | TBA |
| └ publicAreaNotAllowed | boolean | TBA |
| └ embedLinkNotAllowed | boolean | TBA |
| └ lock | boolean | TBA |
| └ lockUser | integer | TBA |
| └ deletionProtection | boolean | TBA |
| └ startDate | integer | TBA |
| └ startDateSetBy | object | TBA |
| └ type | string | TBA |
| └ id | integer | TBA |
| └ endDate | integer | TBA |
| └ endDateSetBy | object | TBA |
| └ type | string | TBA |
| └ id | integer | TBA |
| └ allowedViewers | array | TBA |
| └ fourEyesPrinciple | boolean | TBA |
| subtype | string | Subtype of the new mediacontainer |
| tags | array | Optional settings for this mediacontainer. |
| └ tagId | integer | Id of tag you want to assign |
| └ flag | integer | Flag of tag you want to assign. See TagController for flag description. |
| └ settings | object | Settings of tag you want to assign. |
| └ origin | string | Set the origin of the tag, e.g. during migration |
| type | string | Type of the new mediacontainer |
| uploader | string | A string to identify the uploader of a mediacontainer, if this is not a registered user. |
Update MediaContainer
Updates an existing mediacontainer with formats (for public areas), tags and controlgroups.
Destroy MediaContainer
Puts a mediacontainer into trash bin. With that, all related models (e.g. licenses) are deleted. Only exception is embedlinks – they are also put in trash. Also metadata of the mediaContainer remains intact.
All mediacontainers in trash bin can be displayed using Search Controller with flag 1. Items in trash can be recovered including embedlinks.
All relations with embedlinks, downloadlinks, publicareas or channels will stop deleting the mediacontainer unless you send “forceDelete”.
Items can be finally delete from trash if you send “forceDeleteMediaContainer”. Keep in mind that EVERYTHING (including all media files) is immediately deleted (without retention). In order to send forceDeleteMediaContainer the user requires a specific permission. See User Controller for details.
If a mediacontainer gets deleted during an upload (before the media is probed) it will be immediately deleted
Notes
- Customer can set an securityConfiguration parameter to require a reason for deleting (deleteMediaContainerDescription = true)
| Field | Type | Required | Description |
|---|---|---|---|
| forceDelete | boolean | ✗ | Marks the mediacontainer deleted even if there are relations. |
| forceDeleteMediaContainer | boolean | ✗ | all related medias and all relations will be permanently deleted. Requires user.settings and only works for items already in trash (flag 1) |
| id | integer | ✓ | Id of the mediaContainer you want to delete. |
| infoOnly | boolean | ✗ | TBA |
| notes | string | ✗ | Optional reason why this mediacontainer is deleted. Is required if customer.securityConfiguration.deleteMediaContainerDescription is set to true |
| Field | Type | Description |
|---|---|---|
| id | integer | Id of the mediaContainer you want to delete. |
| infoOnly | boolean | TBA |
BatchUpdate MediaContainer
Batch updates existing mediacontainers with tags, controlgroupIds, audioLanguage etc. You can also use batchUpdate to update flag (move to trash, restore from trash) of mediacontainers, make the favorite and many more operation.
- If you sent parameter delete then the mediacontainers are marked deleted if they are not related with players, etc. Send “forceDelete” to ignore those warnings.
- Returns a jobId which can be used to fetch the result after activity’s progress is 100%.
- You can either send a list of ids or a search query (search term or query) which selects the ids in the background.
- If there are multiple batch updates for the same mediaContainerId, then this MC will be job result’s conflict array.
- Not all batchOperations are available for all mediaContainer types.
- Make sure to put all update parameters into an enclosing object named “updatedParams”!
| Field | Allowed types | Max Ids | Notes |
|---|---|---|---|
| audioLanguage | video | unlimited | |
| channel | video, audio, image, document | unlimited | |
| contacts | all | unlimited | |
| controlGroupIds | all | unlimited | |
| favorites | all | unlimited | |
| flag | video, audio, image, document | unlimited | |
| license | video, audio, image, document | unlimited | |
| publicArea | video, audio, image, document | 250 | |
| relation | video, audio, image, document | 250 | |
| settings | all | unlimited | |
| tags | all | unlimited | |
| sync | all | 250 | BETA |
Batch Job Result
The Batch Job Result provides comprehensive information about the outcome of batch operations in AdmiralCloud. This response allows you to get the status of multiple media container operations performed in a single batch request, helping you identify which items were successfully processed and which encountered issues.
Structure
A Batch Job Result contains four distinct arrays, each categorizing media containers based on their processing outcome:
- processed: Media containers that were successfully processed
- ignored: Media containers that were intentionally skipped
- conflict: Media containers that couldn’t be processed due to rule violations
- error: Media containers that encountered technical errors during processing
Examples for the different types:
Media containers might be ignored if they are in the trash bin, have already been processed or don’t meet prerequisite conditions.
Conflicts typically occur when deletion protection is active for the media container or the operation would violate business rules.
Technical errors can include functional issues – we log these errors and investigate them.
Properties
Each item within these arrays contains the following properties:
- id: The unique identifier of the media container (mediaContainerId)
- message: An explanatory message describing the reason for the outcome
- Optional for items in the “processed” array
- Required for items in the “ignored”, “conflict”, and “error” arrays
FindBatch MediaContainer
DEPREECATED
We recommend to use search instead.
Returns an array of mediacontainer objects including controlGroups. If you send ids then all filters are ignored!
Make sure to send a maximum of 250 ids per request. Use skip and limit for longer lists. If you send more than 250 ids, they will be truncated and and a warning is sent in the X-AdmiralCloud-Warning Header.
FindRelations for MediaContainer
DEPREECATED
We recommend to use search instead.
Find all relations for a given mediacontainer – press areas and mediahubs (incl channels).
PROTIP: If you want to know if this mediacontainer is related to a dropsite (aka uploaded via Dropsite) use the origin information from the mediacontainer itself.
FindContacts for MediaContainer
DEPREECATED
We recommend to use search instead.
Find all contacts for a given mediacontainer
Merge MediaContainers
Merges two mediacontainers (e.g. JPEG and RAW) and all their data to one mediacontainer. This mediacontainer then contains both original files.
Validate MediaContainers
Validates a mediaContainer against given requirements
Check MediaContainers
EXPERIMENTAL
No documentation is yet available.
Data Model
| Field | Type | Description |
|---|---|---|
| id | Integer | Id of the mediaContainer |
| type | String | Type of the mediaContainer |
| subtype | String | Sub type of the mediaContainer |
| origin | String | A string representing the origin of this mediaContainer |
| audioLanguage Deprecated | String | ATTN: DEPRECATED – contact AC Team[badge] |
| flag | Integer | Status flag of the mediaContainer |
| settings | Object | Object with misc settings |
| eventHistory | String | A string/text with information on important changes of this mediaContainer |
| notes | String | A string with custom notes |
| deletedBy | Integer | Id of the user who deleted this mediaContainer |
| deletedAt | Integer | Unix timestamp of the deletion date |
| markedForDeletion | Integer | Unix timestamp of a planned deletion |
| markedForDeletionBy | Integer | Id of the user who planned the deletion |
| uploader Experimental | String | Name of a dropsite uploader. |
| released | Integer | Unix timestamp of the release date |
| releasedFlag | Integer | Status flag of the release |
| releasedBy | Integer | Id of the user who released the mediaContainer |
| lastEditorId | Integer | Id of the user who did the latest update |
| lastEditedModel | String | A list of models that were affected during the lat update process |
| lastEditedFields | JSON | A json object that contains the fields from the latest update. |
| customerId | Integer | The id of the customer this mediaContainer belongs to |
| creatorId | Integer | Id of the user who created this mediaContainer. |
| migrated | String | Identifier for migration |