Taxonomies and categories are essential tools for efficiently organizing and categorizing content items, making them easier to search and discover. This document describes the features of Oracle WebCenter Content, offering a detailed overview of how to create, manage, and use taxonomies and categories to enhance content organization and improve discoverability.
Overview
WebCenter Content (on Marketplace) supports Taxonomies feature via a new component called Taxonomies.
Administration of Taxonomies: Users have the “admin” role or Admin-level permissions (RWDA) on the security group (and optionally account) set on the taxonomy can perform CREATE/UPDATE/DELETE operations on a taxonomy and its categories.
Users have the “admin” role or read permissions on the security group (and optionally account) set on the taxonomy or read permisisons on any of the security groups mapped to the taxonomy can perform READ operations on a taxonomy and its categories.
Consumption of Taxonomies: Users can CATEGORIZE a content item to categories in one or multiple taxonomies as long as that content item’s security group is mapped to those taxonomies.
Manage Taxonomies
A taxonomy is a hierarchy of categories, mapped to your business structure, used to organize the content items and to help users find items by drilling down into the area they’re working on.
There are REST APIs to perform the following management operations:
Create a taxonomy and its categories.
- User should not use special characters in the taxonomy name.
- User can provide a three-letter abbreviation for the taxonomy. If not provided, a unique three letter abbreviation would be generated.
- User can provide an optional description describing what the taxonomy should be used for.
- User should assign a security group to the taxonomy and optionally an account (when Accounts feature is enabled in WCC) too.
- User can add top-level categories by providing the taxonomy GUID as the parent GUID during category creation. He can also add categories at the same level (siblings) or under a selected category (children) by specifying the appropriate category GUID as its parent.
- User can provide a unique API name for the category. If not provided, a unique value would be generated.
Read taxonomy information.
Read category information.
Edit a taxonomy and its categories.
- User can update a taxonomy by renaming it, or changing the description, or changing the abbreviation (three-letter and should be unique), or assigning it to a another security group (or another account).
- User can update a category by renaming it or changing the description or changing the hierarchy by updating the position or the parent GUID.
- User can update the API name of a category with a unique value.
Delete a taxonomy or its cateogries.
- User can delete a taxonomy or a category as long as there are no content items categorized with the taxonomy categories or its descendants.
- If user wants to delete a taxonomy or category when there are content items categorized with it, they need to de-categorize all such items and then can go ahead with the delete.
- Deleting a category will delete all its descendants.
- Deleting a taxonomy will delete all of its categories and all the taxonomy and security group mappings.
List taxonomies.
List categories under a taxonomy.
- User can search categogries by their parent GUIDs, or category names, or category API names.
Copy category.
- User can copy a category to another target category within the same taxonomy.
- Copying a category will copy all of its descendants.
Manage Taxonomy and Security Group Mappings
To support content item categorization, we need to map taxonomies to content items’ security groups.
There are REST APIs to perform the mapping:
To add a taxonomy mapping to a security group or remove a taxonomy mapping from a security group, user must have either the “admin” role or Admin-level permissions (RWDA) on the security group and the account (optionally) that are set on the taxonomy and on the security group being mapped or unmapped.
For WCC instances with OracleSearchText or OpenSearch search engines, removing a taxonomy mapping from a security group is blocked if there are content items under that security group that are categorized with categories from the taxonomy. But he can forcefully remove the mapping by passing an optional boolean query parameter ‘forceRemove’.
User can read security groups mapped to a taxonomy. User must have either the “admin” role or R permissions on the security group and the account (optinally) that are set on the taxonomy or R permission on any of the mapped security groups.
User can read the associated taxonomies of a security group. User must have either the “admin” role or R permissions on the security group.
Use Taxonomies for Item Categorization and Item Search
Note: this is only supported for WCC instances configured with OracleTextSearch or OpenSearch search engines.
Item categorization will help organising the items. If a taxonomy has been mapped with security groups that content items belong to, user can add and remove categories of that taxonomy to the content items. User can search content items categorized to a specific category (or categories) or their descendant categories.
There are REST APIs to perform the item categorization operations:
Categorize or De-categorize an item.
The user must have RW permissions on the content item and the content item’s security group should be mapped to the taxonomy.
User can use the check-in and update REST APIs for categorize or de-categorize item by adding or removing category information as metadata in the form data parameters. The taxonomy categories info is stored as the metadata so that users can search items via their assigned categories.
User can use the bulk add categories API and bulk remove categories API to categorize and de-categorize multiple items in one go.
Read item categorization information.
The user must have R permission on the content item.
User can fetch the taxonomy categories information on a content item (by its dDocName).
About Lifecycle of Item Categorization
A mapping between the taxonomy being used for categorization and the content item’s security group should exist for the item categorization to succeed.
Item categorization is supported only on the item level and not at the revision level.
Deleting old revisions should not impact categorization. Categorization info will be cleaned up only when the very last version of the content item is being deleted.
User should be able to retain the item categorization info when items are restored from trash.
In case of permanent delete of the last revision of an item, all the categorization info will be cleaned up and cannot be retained.
Create taxonomy and its categories using WebCenter Content REST API
You need to assign a taxonomy to a security group during creation. Once the taxonomy is successfully created, you can create categories at the top-level (direct children of taxonomy). Multiple categories can be created thereafter either at the top level as siblings or under a specific category (sub-categories) forming a hierarchy.
Examples
Example 1
Create Taxonomy BookGenres with Security Group AudioBooks.
POST https://{host}:{port}/documents/wcc/api/v1.1/taxonomies
Request Body
{
"dTaxonomyName": "BookGenres",
"dDescription": "Book Genres",
"dTaxonomySecurityGroup": "AudioBooks"
}Example 2
Create Category Fiction under the BookGenres Taxonomy (use the taxonomy GUID created in Example 1 in the path parameter and the dParentGUID).
POST https://{host}:{port}/documents/wcc/api/v1.1/taxonomies/B6A08AFFFFE797345C6DD64BC30AEAF9/categories
Request Body
{
"dCategoryName": "Fiction",
"dParentGUID": "B6A08AFFFFE797345C6DD64BC30AEAF9"
}Create child category Fantasy under the Fiction category under the BookGenres Taxonomy (use the taxonomy GUID created in Example 1 in the path parameter and the Fiction category GUID created above as dParentGUID):
POST https://{host}:{port}/documents/wcc/api/v1.1/taxonomies/B6A08AFFFFE797345C6DD64BC30AEAF9/categories
Request Body
{
"dCategoryName": "Fantasy",
"dParentGUID": "F08E631C39EC3839268C6D87A307721D"
}Example 3
Search categories in BookGenres Taxonomy with name having substring Fan and with parent as Fiction and API name as ebo-f-f.
GET https://{host}:{port}/documents/wcc/api/v1.1/taxonomies/B6A08AFFFFE797345C6DD64BC30AEAF9/categories
Query Parameters
QueryText=(dCategoryName <substring> `Fan` <AND> dParentGUID <matches> `F08E631C39EC3839268C6D87A307721D` <AND> dAPIName <matches> `ebo-f-f`)
Categorize items with taxonomy categories Using WebCenter Content REST API
You can categorize or de-categorize items either during check-in or during updates. If a content item belongs to a different security group than the one mapped to the taxonomy, you need to first map the taxonomy to the content item’s security group and then add and remove categories of that taxonomy to the content item.
Examples
Example 1
Content Item Document1 is being uploaded to security group EBooks which is currently not mapped to BookGenres taxonomy.
Map the BookGenres taxonomy to the EBooks security group:
POST https://{host}:{port}/documents/wcc/api/v1.1/taxonomies/B6A08AFFFFE797345C6DD64BC30AEAF9/securityGroups/.add
Request Body
{
"dSecurityGroup": "EBooks"
}Example 2
Upload a file Document1.txt in security group EBooks and categorize it with Fantasy category of the BookGenres taxonomy (use the taxonomy GUID created in Example 1 and the Fantasy category GUID created in Example 2 under the create taxonomies and categories section):
POST https://{host}:{port}/documents/wcc/api/v1.1/files/data`
Request Body
FormData Parameters
primaryFile = path to the local
Document1.txtfilemetadataValues = { “dDocTitle”: “Document1”, “dDocType”: “Document”, “dSecurityGroup”: “EBooks”, “addCategories”: “taxonomyGUID:B6A08AFFFFE797345C6DD64BC30AEAF9,categoryGUIDs:F409A046F4574F7B3269496FD5ED6805” }
Example 3
Update an existing file Document1.txt with dDocName WCCDoc-1318489 in security group EBooks and de-categorize it with Fantasy category of the BookGenres taxonomy (use the taxonomy GUID created in Example 1 and the Fantasy category GUID created in Example 2 under the create taxonomies and categories section):
PUT https://{host}:{port}/documents/wcc/api/v1.1/files/WCCDOC-1318489
Request Body
FormData Parameters
metadataValues = { “dDocTitle”: “Document1”, “dDocType”: “Document”, “dSecurityGroup”: “EBooks”, “removeCategories”:“taxonomyGUID:B6A08AFFFFE797345C6DD64BC30AEAF9,categoryGUIDs:F409A046F4574F7B3269496FD5ED6805” }
Example 4
Read content item (with dDocName WCCDoc-1318489) taxonomy categories information:
GET https://{host}:{port}/documents/wcc/api/v1.1/files/WCCDoc-1318489/taxonomies
Search content items by taxonomy categories Using WebCenter Content REST API
Example 1
Search items that are in EBooks group and categorized with category Fantasy.
GET https://{host}:{port}/documents/wcc/api/v1.1/files/search/items
Query Parameters
fields=dDocName,dID,dDocTitle,dRevLabel,dSecurityGroup,dDocAuthor
q=(dSecurityGroup <matches> `EBooks` <AND> xTaxonomyCategories <matches> `F409A046F4574F7B3269496FD5ED6805`)
Example 2
Search items that are in EBooks group and categorized with category Fiction or any of its descendants.
GET https://{host}:{port}/documents/wcc/api/v1.1/files/search/items
Query Parameters
fields=dDocName,dID,dDocTitle,dRevLabel,dSecurityGroup,dDocAuthor
q=(dSecurityGroup <matches> `EBooks` <AND> xTaxonomyCategories <contains> `F08E631C39EC3839268C6D87A307721D`)
Managing and Using Taxonomies in Oracle WebCenter Content
G29679-02
Last updated: May 2025
Copyright © 2024, Oracle and/or its affiliates.
Primary Author: Oracle Corporation