Assets
Assets represent the smallest units of managed content in Oracle Content Management. They’re typically used for content modeling, publishing, and delivery.
As such, they differ from "regular" (that is, non-asset) documents, which are mostly used for collaboration, syncing, or backup purposes. Assets will often be media files (images or videos), but they can also be documents or structured content that includes text. In headless development, you’ll mostly be working with assets.
Asset Management
Content contributors manage assets in repositories in the Oracle Content Management web interface.
Depending on their assigned privileges, content contributors can perform a number of asset management tasks, including:
- Manage asset types
- Manage localization policies
- Manage publishing channels
- Manage taxonomies
- Manage repositories
- Manage workflows
- Manage audience attributes
- Use digital assets
- Use structured content
- Use recommendations
- Use collections
See Managing Assets with Oracle Content Management for more information.
Description of the illustration asset-repository.png
Asset Properties
All assets share a number of common properties, while different types of assets also have their own additional sets of properties.
Each of these properties can be programmatically accessed using the REST APIs for content modeling and delivery.
These are some of the basic properties that every asset of any type has:
- id
- type
- typeCategory
- name
- description
- slug
- language
- translatable
- createdDate (value, timezone)
- updatedDate (value, timezone)
In addition to these standard properties, assets of different types also have other sets of properties. For example, some image and video properties include:
- mediaType
- mimeType
- width
- Height
- size
- extension
- formats
- duration (videos only)
Asset Types
Every asset in Oracle Content Management is categorized as a specific asset type. These types determine how an asset can be managed and published.
There are two main types of assets:
- Digital asset types—These define file media types (MIME types) and sets of attributes for assets of that type. There are a number of seeded (out-of-the-box) digital asset types, but you can also define your own custom digital asset types. For example, you could have a "Logo" digital asset type, which consists of a PNG or JPG file along with some associated attributes such as copyright statement and caption. When you create an asset from a digital asset type, it’s called a digital asset (so file plus associated attributes).
- Content item types—These are defined groups of data fields of various data types. For example, you might create a blog article content type, where each asset stores values for title, body, author, photo, date created, and a list of references to related articles. When you create an asset from a content item type, it’s called a content item.
Create Asset Types
If you have the required administrative privileges, you can create asset types in the Oracle Content Management web interface (under Administration > Content).
When creating a new asset type, you choose to create either a content item type or a digital asset type.
Create Assets
Content contributors can create new digital assets by uploading new files from their local computer or adding existing items in their Documents section of Oracle Content Management.
While adding assets, content contributers can assign digital asset types, categories, channels, tags, and collections to support content modeling, routing, and delivery.
Similarly, they can also create new content items based on the content item types made available to them.
Note:
Assets must be published before they're available for use in publishing channels (and also through REST APIs).
Content API for Assets
Assets exist both in a management context and in a delivery context. For an authored asset to be used in an application, it must first be published, so it becomes available in the delivery context.
We’ll mostly focus on the delivery context here as that is of primary interest to developers. See Managing Assets with Oracle Content Management for more information on assets from a management perspective.
Once published, each asset is available as a REST resource. You can see the address to the resource as part of the asset properties, which you can find in the Oracle Content Management web interface.
Description of the illustration asset-api-properties.png
Let's explore what such a REST resource looks like in the delivery context. First, the delivery URL has a specific form.
https://.../content/published/api/v1.1/items/CORE6F39A82DD76F408C8C31F7D8FCB3E8C0?channelToken=1c92cd5b68b245ax87ffb8898ff2fdbd
- The access context identifier
/published
indicates that this is about delivering published content. - The object identifier
/items
indicates that we're working with asset items (and not other object types). - This is followed by the identifier of the asset, which is a series of
letters and numbers (for example,
CORE6F39A82DD76F408C8C31F7D8FCB3E8C0
). Each asset has its own unique identifier. - At the end is a query parameter,
channelToken
, which is an identifier for the channel that this asset has been published to. It's the context in which the asset is being accessed.
You can see the full JSON response data for an asset by clicking the {}
brackets next to the delivery URL. It looks something like this:
Description of the illustration json-response-content-type.png
Or, in text form:
{
"id": "CORE6F39A82DD76F408C8C31F7D8FCB3E8C0",
"type": "Press-Release",
"typeCategory": "ContentType",
"name": "The Power of Coffee",
"description": "Press release 'The Power of Coffee' for marketing kit",
"slug": "1481786546522-the-power-of-coffee",
"language": "en-US",
"translatable": true,
"createdDate": {
"value": "2021-03-29T18:33:13.732Z",
"timezone": "UTC"
},
"updatedDate": {
"value": "2021-03-29T23:55:37.057Z",
"timezone": "UTC"
},
"fields": {
"body_text": "\n\rOur annual \"Power of Coffee\" fundraiser raised over $1 million to help families in need. With your donations last month, and Cafe Supremo's dollar for dollar matching, we hit our highest numbers ever! Thank you for being a part of our community and giving back to our community. Our annual \"Power of Coffee\" fundraiser raised over $1 million to help families in need. With your donations last month, and Cafe Supremo's dollar for dollar matching, we hit our highest numbers ever! Thank you for being a part of our community and giving back to our community. ",
"photo": {
"id": "CONTA37AC23CE5284C46ACF4D3C3B10A9950",
"type": "DigitalAsset",
"typeCategory": "DigitalAssetType",
"name": "Coffee Beans and Ground Coffee.jpg",
"links": [
{
"href": "https://.../content/published/api/v1.1/items/CONTA37AC23CE5284C46ACF4D3C3B10A9950?channelToken=1c92bb5b68b245da87ffb8672ff2fddb",
"rel": "self",
"method": "GET",
"mediaType": "application/json"
}
]
},
"title": "The Power of Coffee!"
},
"links": [
{
"href": "https://.../content/published/api/v1.1/items/CORE6F39A82DD76F408C8C31F7D8FCB3E8C0?channelToken=1c92bb5b68b245da87ffb8672ff2fddb",
"rel": "self",
"method": "GET",
"mediaType": "application/json"
},
{
"href": "https://.../content/published/api/v1.1/items/CORE6F39A82DD76F408C8C31F7D8FCB3E8C0?channelToken=1c92bb5b68b245da87ffb8672ff2fddb",
"rel": "canonical",
"method": "GET",
"mediaType": "application/json"
},
{
"href": "https://.../content/published/api/v1.1/metadata-catalog/items/CORE6F39A82DD76F408C8C31F7D8FCB3E8C0?channelToken=1c92bb5b68b245da87ffb8672ff2fddb",
"rel": "describedby",
"method": "GET",
"mediaType": "application/schema+json"
}
]
}
The JSON data matches the various metadata fields for the asset in Oracle Content Management:
Description of the illustration json-response-diagram.png
Fields in green are all standard fields; they are present in every asset. One such standard field is the unique identifier (id) of the asset. Other standard fields are asset properties such as type, name, description, slug, language, translatability status (translatable), and the creation and update dates (createdDate and updatedDate).
A child "fields" node contains all user-defined field values, such as title, body, photo, or whatever else was specified in the asset type definition.
Looking at the "photo" field in the example above, you may notice that this looks a bit different. That’s because it’s a reference field. These don’t contain the complete data set for the asset, but merely an identifier, a name, a type, and a link to the asset. In fact, any media field (the data type for the "photo" field) is actually a reference field behind the scenes. It’s a reference to an out-of-the-box type called DigitalAsset (which is why "type" under the photo field says “DigitalAsset”).
Now, suppose you have an "Article" content item with an "author" reference field, and you
want to access all of the author field along with the article without having to incur
additional network calls. You can easily do that by simply adding
expand=fields.author
as a query parameter, and the author field
expands inside the Article JSON response.