describeDataCategoryGroupStructures()

Syntax

DescribeDataCategoryGroupStructureResult[] = connection.
describeDataCategoryGroupStructures()(DataCategoryGroupSObjectTypePair[] pairs, boolean topCategoriesOnly)

Usage

Use this call to return the visible data category structure for the given object category group pairs. First use describeDataCategoryGroups() to find the available category groups for the objects specified. From the returned list, choose the object category group pairs to pass as the input in describeDataCategoryGroupStructures(). This call returns all the visible categories and data category structure as output. For additional information about data categories and data category visibility, see “What are Data Categories?” and “About Category Group Visibility” in the Salesforce online help.

Sample Code—Java

This example shows how to use category group and object pairs to retrieve categories from the Regions category group. Using pair 1 and pair 2 you can check if either Salesforce Knowledge articles or questions are associated with Regions. If any articles or questions are associated with Regions, the call returns its name and the name, label, description of the category group. It also retrieves the top-level categories in Regions and any of its child categories.

public void describeDataCateogryGroupStructures() {
  try {
    DataCategoryGroupSobjectTypePair pair1 = 
        new DataCategoryGroupSobjectTypePair();
    DataCategoryGroupSobjectTypePair pair2 = 
        new DataCategoryGroupSobjectTypePair();
    pair1.setSobject("KnowledgeArticleVersion");
    pair1.setDataCategoryGroupName("Regions");
    pair2.setSobject("Questions");
    pair2.setDataCategoryGroupName("Regions");
    
    DataCategoryGroupSobjectTypePair[] pairs = 
        new DataCategoryGroupSobjectTypePair[] {
            pair1, 
            pair2
        };

    // Get the list of top level categories using the describe call
    DescribeDataCategoryGroupStructureResult[] results =
        connection.describeDataCategoryGroupStructures(
            pairs,
            true
    );
    
    for (int i = 0; i < results.length; i++) {
      DescribeDataCategoryGroupStructureResult result = 
          results[i];
      String sObject = result.getSobject();
      System.out.println("sObject: " + sObject);
      System.out.println("Group name: " + result.getName());
      System.out.println("Group label: " + result.getLabel());
      System.out.println("Group description: " + 
          result.getDescription());
      // Get the top-level categories
      DataCategory[] topCategories = result.getTopCategories();
      // Iterate through the top level categories and retrieve 
      // some information
      for (int j = 0; j < topCategories.length; j++) {
        DataCategory topCategory = topCategories[j];
        System.out.println("Category name: " + 
            topCategory.getName());
        System.out.println("Category label: " + 
            topCategory.getLabel());
        DataCategory [] childCategories =
            topCategory.getChildCategories();
        System.out.println("Child categories: ");
        for (int k = 0; k < childCategories.length; k++) {
          System.out.println("\t" + k + ". Category name: " +
              childCategories[k].getName());
          System.out.println("\t" + k + ". Category label: " +
              childCategories[k].getLabel());
        }
      }
    }
  } catch (ConnectionException ce) {
    ce.printStackTrace();
  }
}

Sample Code—C#

This example shows how to use category group and object pairs to retrieve categories from the Regions category group. Using pair 1 and pair 2 you can check if either Salesforce Knowledge articles or questions are associated with Regions. If any articles or questions are associated with Regions, the call returns its name and the name, label, description of the category group. It also retrieves the top-level categories in Regions and any of its child categories.

private void describeDataCategoryGroupStructuresSample()
{
    try
    {
        // Assuming that you have a category group called 
    
        // Regions. Creating a list of Data Category group 
    
        // pairs to use for the describe call. 
    
        DataCategoryGroupSobjectTypePair pair1 = 
            new DataCategoryGroupSobjectTypePair();
        DataCategoryGroupSobjectTypePair pair2 = 
            new DataCategoryGroupSobjectTypePair();
        pair1.setSobject("KnowledgeArticleVersion");
        pair1.setDataCategoryGroupName("Regions");
        pair2.setSobject("Questions");
        pair2.setDataCategoryGroupName("Regions");
        
        DataCategoryGroupSobjectTypePair[] pairs = 
            new DataCategoryGroupSobjectTypePair[] {
                pair1, pair2
            };
        
        
        // Get the list of top level categories using the describe call 
    
        DescribeDataCategoryGroupStructureResult[] resultsList =
                binding.describeDataCategoryGroupStructures(
                    pairs,
                    true
                );

        for (int x=0;x<resultsList.length;x++)
        {
            DescribeDataCategoryGroupStructureResult singleResult
                = resultsList[x] 
    ;
            // Get the name of the associated SObject 
    
            string sObject = singleResult.getSobject();
            Console.WriteLine("sObject: " + sObject);

            // Get the name of the data category group 
    
            string categoryGroupName = singleResult.getName();
            Console.WriteLine("Group name: " + categoryGroupName);

            // Get the label of the data category group 
    
            string categoryGroupLabel = singleResult.getLabel();
            Console.WriteLine("Group label: " + categoryGroupLabel);

            // Get the description of the data category group 
    
            string categoryGroupDescription
                = singleResult.getDescription();
            Console.WriteLine("Group description: " + categoryGroupDescription);
       
            // Get the top level categories 
    
            DataCategory [] topLevelDataCategoriesList =
                    singleResult.getTopCategories();

            // Iterate through the top level categories and retrieve their 
    
            // information 
    
            for (int j=0;j<topLevelDataCategoriesList.length;j++)
            {
                DataCategory singleCategory
                    = topLevelDataCategoriesList[j] 
    ;

                // Get the name of the category 
    
                string categoryName = singleCategory.getName();
                Console.WriteLine("Category name: " + categoryName);

                // Get the label of the category 
    
                string categoryLabel = singleCategory.getLabel();
                Console.WriteLine("Category label: " + categoryLabel);

                // Get the list of sub categories in the category 
    
                DataCategory [] childCategories
                    = singleCategory.getChildCategories();
            }
        }
    } catch (Exception ex) {
       Console.WriteLine("\nFailed to get data category group structure descriptions.");
        Console.WriteLine(ex.Message);
        Console.WriteLine(ex.StackTrace);
    }
}

Arguments

Name	Type	Description
pairs	DataCategoryGroupSObjectTypePair[]	Specifies a category group and an object to query. Visible data categories are retrieved for that object.
topCategoriesOnly	boolean	Indicates whether the call returns only the top (`true`) or all the categories (`false`) visible depending on the user's role category group visibility settings. For more information on category group visibility, see About Category Group Visibility in the Salesforce online help.

DataCategoryGroupSObjectTypePair contains the following fields:

Name	Type	Description
dataCategoryGroupName	string	The unique name used for API access to the data category group.
sobject	string	The object associated with the data category group

Response

DescribeDataCategoryGroupStructureResult[]

Faults

InvalidSObjectFault

UnexpectedErrorFault