---
schema_version: "1"
id: e838d102b5ecf95abed3033ba23c182a970cc35fde5af3a42efb19c659f1153e
title: DataCategoryGroup
collection: legacydeveloper
version: current
locale: en-us
portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/api_meta/meta_datacategorygroup.md
canonical_url: https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_datacategorygroup.htm
source_site: developer.salesforce.com
content_type: documentation
content_hash: 641a3019c2866d4de8c862de6870bb5021889e09a319cc076f73c43cc9e2f313
description: Represents a data category group.
---
# DataCategoryGroup

Represents a data category group.

This type extends the Metadata metadata type and inherits its fullName field.

![Warning](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note_warning.png)

#### Warning

Using Metadata API to deploy category changes from one organization to another permanently removes categories and record categorizations that are not specified in your XML file. Salesforce recommends that you manually create data categories and record associations in an organization from Setup by entering Data Categories in the Quick Find box, then selecting **Data Categories** rather than deploying changes from a sandbox to a production organization. For more information, see Usage.

Data category groups are provided to:

- Classify and filter data.
- Share data among users.

Every data category group contains items or data categories that can be organized hierarchically.

The example below shows the Geography data category group and its data categories.

Geography
    Worldwide
        North America
            United States of America
            Canada
            Mexico
        Europe
        Asia

![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png)

#### Note

See "Work with Data Categories" in the Salesforce online help for more information on data category groups, data categories, parent and sub categories.

## File Suffix and Directory Location

The file suffix is .datacategorygroup. There is one file for each data category group stored in the datacategorygroups folder in the corresponding package directory.

## Version

Data category groups are available in API version 18.0 and later.

## Fields

This metadata type contains the following fields:

| Field Name | Field Type | Description |
| --- | --- | --- |
| active | boolean | Required. The status of the category group. Indicates whether this category group is active, (true), or not active (false). |
| dataCategory | DataCategory | Required. The top-level category within the data category group. |
| description | string | The description of the data category group. |
| fullName | string | Required. The unique name of the data category group. When creating a data category group, the fullName field and the file name (without its suffix) must match.The fullName can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. This field is inherited from the Metadata component. |
| label | string | Required. Label that represents the object in Salesforce. |
| objectUsage | ObjectUsage | The objects that are associated with the data category group. |

## DataCategory

Represents an item (or data category) in the data category group. A data category can recursively contain a list of other data categories.

<table class="featureTable sort_table" summary="">



          <thead class="thead sorted" align="left">
            <tr>
              <th class="featureTableHeader  " id="d336830e254">Field Name</th>

              <th class="featureTableHeader  " id="d336830e257">Field Type</th>

              <th class="featureTableHeader  " id="d336830e260">Description</th>

            </tr>

          </thead>

          <tbody class="tbody">
            <tr>
              <td class="entry" headers="d336830e254" data-title="Field Name"><span class="keyword parmname">dataCategory</span></td>

              <td class="entry" headers="d336830e257" data-title="Field Type">DataCategory[]</td>

              <td class="entry" headers="d336830e260" data-title="Description">A recursive list of sub data categories. For example, a list of countries within a
                continent. You can create up to 100 categories in a data category group and have up to 5
                levels in a data category group hierarchy.</td>

            </tr>

            <tr>
              <td class="entry" headers="d336830e254" data-title="Field Name"><span class="keyword parmname">label</span></td>

              <td class="entry" headers="d336830e257" data-title="Field Type">string</td>

              <td class="entry" headers="d336830e260" data-title="Description">Required. Label for the data category throughout the Salesforce user
                interface.</td>

            </tr>

            <tr>
              <td class="entry" headers="d336830e254" data-title="Field Name"><span class="keyword parmname">name</span></td>

              <td class="entry" headers="d336830e257" data-title="Field Type">string</td>

              <td class="entry" headers="d336830e260" data-title="Description">Required. The developer name of the data category used as a unique identifier for API
                access. The name can only contain characters, letters, and the underscore (_) character,
                must start with a letter, and cannot end with an underscore or contain two consecutive
                underscore characters.<div class="box message confirm">
                  <div class="inner">
                    <div class="bd">
                      <div class="media">
                        <img class="img mtm" src="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note_important.png" alt="Important">
                        <div class="mediaBd">
                          <h4 class="mbs">Important</h4>
                          <p><span class="ph" id="devname_cant_change"><a name="devname_cant_change"><!-- --></a>The value for this
                              field is defined once and cannot be changed later.</span></p>
                        </div>
                      </div>
                    </div>
                  </div>
                </div>
                <div class="box message warn">
                  <div class="inner">
                    <div class="bd">
                      <div class="media">
                        <img class="img mtm" src="https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note_warning.png" alt="Warning">
                        <div class="mediaBd">
                          <h4 class="mbs">Warning</h4>
                          <p>If you
                            deploy a category group that already exists in an organization, any category that is not
                            defined in the XML file is permanently removed from your organization. For more information
                            see Usage.</p>
                        </div>
                      </div>
                    </div>
                  </div>
                </div>
              </td>

            </tr>

          </tbody>

        </table>

## ObjectUsage

Represents the objects that can be associated with the data category group. This association allows the object to be classified and filtered using the data categories.

<table class="featureTable sort_table" summary="">



          <thead class="thead sorted" align="left">
            <tr>
              <th class="featureTableHeader  " id="d336830e338">Field Name</th>

              <th class="featureTableHeader  " id="d336830e341">Field Type</th>

              <th class="featureTableHeader  " id="d336830e344">Description</th>

            </tr>

          </thead>

          <tbody class="tbody">
            <tr>
              <td class="entry" headers="d336830e338" data-title="Field Name"><span class="keyword parmname">object</span></td>

              <td class="entry" headers="d336830e341" data-title="Field Type">string[]</td>

              <td class="entry" headers="d336830e344" data-title="Description">A list of the object names that can be associated with the data category group. Valid
                values are:<ul class="ul bulletList">
                  <li class="li">
                    <samp class="codeph java" id="objectType_article"><a name="objectType_article"><!-- --></a>KnowledgeArticleVersion</samp>—to
                    associate articles. See "Modify Default Category Group Assignments for Articles" in the
                    Salesforce online help for more information on data category groups association to
                    articles.
                  </li>

                  <li class="li">
                    <samp class="codeph java" id="objectType_question"><a name="objectType_question"><!-- --></a>Question</samp>—to associate
                    questions. You can associate the <samp class="codeph java">Question</samp> object with
                    at most one category group.
                  </li>

                </ul>
                <p class="p">If you deploy a category group that already exists in an organization, any object
                  association that is not defined in the XML file is permanently removed from your
                  organization. Ensure that your XML file specifies all the records associated with your
                  category group in the organization. For more information see Usage.</p>
              </td>

            </tr>

          </tbody>

        </table>

## Declarative Metadata Sample Definition

This sample is the definition of the Geography data category group and its data categories:

<?xml version="1.0" encoding="UTF-8"?>
<DataCategoryGroup xmlns="http://soap.sforce.com/2006/04/metadata">
   <label\>Geography</label\>
   <description\>Geography structure of service center locations</description\>
   <fullName\>geo</fullName\>

   <dataCategory\> <name\>WW</name\> <label\>Worldwide</label\>
      <dataCategory\> <name\>AMER</name\> <label\>North America</label\>
         <dataCategory\>
             <name\>USA</name\>
             <label\>United States of America</label\>
         </dataCategory\> 
         <dataCategory\>
             <name\>CAN</name\>
             <label\>Canada</label\>
         </dataCategory\>
         <dataCategory\>
             <name\>MEX</name\>
             <label\>Mexico</label\>
         </dataCategory\>
      </dataCategory\> 
      <dataCategory\> <name\>EMEA</name\> <label\>Europe, Middle East, Africa</label\> 
         <dataCategory\>
             <name\>FR</name\>
             <label\>France</label\>
         </dataCategory\> 
         <dataCategory\>
             <name\>SP</name\>
             <label\>Spain</label\>
        </dataCategory\>
         <dataCategory\>
            <name\>UK</name\>
            <label\>United-Kingdom</label\>
         </dataCategory\>
      </dataCategory\>
      <dataCategory\>
          <name\>APAC</name\>
          <label\>Asia</label\>
      </dataCategory\>
   </dataCategory\>

   <objectUsage\>
      <object\>KnowledgeArticleVersion </object\>
   <objectUsage\>
</DataCategoryGroup\>

## Usage

When you deploy a category group XML file, Metadata API checks whether the category group exists in the target organization. If the category group does not exist, it is created. If the category group already exists, then Metadata API:

- Adds any new category or object defined in the XML file.
- Deletes any category that is not defined in the XML file. Records associated with the deleted categories are re-associated with the parent category.
- Deletes any object association that is not defined in the XML file.
- Moves any category if its hierarchical position differs from the position specified in the XML file.
    
    ![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png)
    
    #### Note
    
    When a category moves to a new parent category, users that have no visibility on the new parent category lose their visibility to the repositioned category.

![Note](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/images/icon_note.png)

#### Note

For more information about category deletion, category repositioning and its impact on record categorization and visibility see "Delete a Data Category" and "Modify and Arrange Data Categories" in the Salesforce online help.

Using Metadata API to deploy category changes from one organization to another permanently removes categories and record categorizations that are not specified in your XML file. Salesforce recommends that you manually create data categories and record associations in an organization from Setup by entering Data Categories in the Quick Find box, then selecting **Data Categories** rather than deploying changes from a sandbox to a production organization.

The following example illustrates what happens if you deploy an XML representation of a Geography data category group hierarchy to an organization that already has this data category group defined. Note that the organization contains a US category, while the XML file includes a USA category in the same hierarchical position. The Metadata API deployment process deletes the US category from the organization and moves associations for any records from US to the parent AMER category. It also adds the USA category under AMER. Note that all records that were previously categorized with US are now associated with the AMER category.

![The Geography category group with the category US in the organization and the category USA in the XML file](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/dev_guides/api_meta/images/category_remove.png)

The next example illustrates what can happen when you delete or move a category in a data category group and deploy its XML representation from a sandbox to a production organization that already has this data category group defined. Hierarchy 1 shows the initial data category group in the sandbox organization. In hierarchy 2, we add an EU category under EMEA and move FR, SP and UK below EU. In hierarchy 3, we delete FR and associate its records with its new parent, EU. Finally, we deploy the changes from the sandbox to the production organization.

![Moving and deleting "FR" in the Geography category group](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/dev_guides/api_meta/images/category_miscategorization.png)

Metadata API has no concept of the order of the changes made to the sandbox organization. It just deploys the changes from one organization to another. During the deployment, it first notices the deletion of the FR category and removes it from the production organization. Consequently, it moves associations for any records from FR to its parent on the production organization, EMEA. Metadata API then adds the EU category and moves SP and UK below it. Although the category group hierarchy looks the same in both organizations, record categorization in production is different from the sandbox organization. The records that were originally associated with FR in hierarchy 1 are associated with EU in the sandbox organization, but are associated with EMEA in the production organization.

## Wildcard Support in the Manifest File

This metadata type supports the wildcard character \* (asterisk) in the package.xml manifest file. For information about using the manifest file, see [Deploying and Retrieving Metadata with the Zip File](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based_zip_file.htm "The deploy() and retrieve() calls are used to deploy and retrieve a .zip file. Within the .zip file is a project manifest (package.xml) that lists what to retrieve or deploy, and one or more XML components that are organized into folders.").