describeDataCategoryGroupStructures()

Retrieves available category groups along with their data category structure for objects specified in the request.

Syntax

1DescribeDataCategoryGroupStructureResult[] = connection.
2describeDataCategoryGroupStructures()(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 sample shows how to use sObject and data category group pairs to retrieve data categories for each pair. It calls describeDataCategoryGroupStructures() with two pairs, KnowledgeArticleVersion/Regions and Question/Regions, and iterates through the results of this call. It gets the top categories for each result, which is “All”, and then gets the first-level child categories. The sample requires that you set up a data category group called Regions with some child categories and associate it with a knowledge article and questions. Alternatively, you can replace the data category group name in the sample if you want to use an existing data category group in your org that has a different name.

1swfobject.registerObject("clippy.codeblock-1", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17public void describeDataCateogryGroupStructuresSample() {
18    try {
19        // Create the data category pairs
20        DataCategoryGroupSobjectTypePair pair1 = 
21            new DataCategoryGroupSobjectTypePair();
22        DataCategoryGroupSobjectTypePair pair2 = 
23            new DataCategoryGroupSobjectTypePair();
24        pair1.setSobject("KnowledgeArticleVersion");
25        pair1.setDataCategoryGroupName("Regions");
26        pair2.setSobject("Question");
27        pair2.setDataCategoryGroupName("Regions");
28        
29        DataCategoryGroupSobjectTypePair[] pairs = 
30            new DataCategoryGroupSobjectTypePair[] {
31                pair1, 
32                pair2
33            };
34
35        // Get the list of top level categories using the describe call
36        DescribeDataCategoryGroupStructureResult[] results =
37            connection.describeDataCategoryGroupStructures(
38                pairs,
39                false
40        );
41        
42        // Iterate through each result and get some properties
43        // including top categories and child categories
44        for (int i = 0; i < results.length; i++) {
45          DescribeDataCategoryGroupStructureResult result = 
46              results[i];
47          String sObject = result.getSobject();
48          System.out.println("sObject: " + sObject);
49          System.out.println("Group name: " + result.getName());
50          System.out.println("Group label: " + result.getLabel());
51          System.out.println("Group description: " + 
52              result.getDescription());
53          
54          // Get the top-level categories
55          DataCategory[] topCategories = result.getTopCategories();
56          
57          // Iterate through the top level categories and retrieve 
58          // some information
59          for (int j = 0; j < topCategories.length; j++) {
60            DataCategory topCategory = topCategories[j];
61            System.out.println("Category name: " + 
62                topCategory.getName());
63            System.out.println("Category label: " + 
64                topCategory.getLabel());
65            DataCategory [] childCategories =
66                topCategory.getChildCategories();
67            System.out.println("Child categories: ");
68            for (int k = 0; k < childCategories.length; k++) {
69              System.out.println("\t" + k + ". Category name: " +
70                  childCategories[k].getName());
71              System.out.println("\t" + k + ". Category label: " +
72                  childCategories[k].getLabel());
73            }
74          }
75        }
76      } catch (ConnectionException ce) {
77        ce.printStackTrace();
78    }
79}

Sample Code—C#

1swfobject.registerObject("clippy.codeblock-2", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17public void describeDataCateogryGroupStructuresSample() {
18    try {
19        // Create the data category pairs
20        DataCategoryGroupSobjectTypePair pair1 = 
21            new DataCategoryGroupSobjectTypePair();
22        DataCategoryGroupSobjectTypePair pair2 = 
23            new DataCategoryGroupSobjectTypePair();
24        pair1.sobject = "KnowledgeArticleVersion";
25        //pair1.setDataCategoryGroupName("Regions");
26        pair1.dataCategoryGroupName = "KBArticleCategories";
27        pair2.sobject = "Question";
28        //pair2.setDataCategoryGroupName("Regions");
29        pair2.dataCategoryGroupName = "KBArticleCategories";
30            
31        DataCategoryGroupSobjectTypePair[] pairs = 
32            new DataCategoryGroupSobjectTypePair[] {
33                pair1, 
34                pair2
35            };
36
37        // Get the list of top level categories using the describe call
38        DescribeDataCategoryGroupStructureResult[] results =
39            binding.describeDataCategoryGroupStructures(
40                pairs,
41                false
42        );
43            
44        // Iterate through each result and get some properties
45        // including top categories and child categories
46        for (int i = 0; i < results.Length; i++) {
47            DescribeDataCategoryGroupStructureResult result = 
48                results[i];
49            String sObject = result.sobject;
50            Console.WriteLine("sObject: " + sObject);
51            Console.WriteLine("Group name: " + result.name);
52            Console.WriteLine("Group label: " + result.label);
53            Console.WriteLine("Group description: " + 
54                result.description);
55              
56            // Get the top-level categories
57            DataCategory[] topCategories = result.topCategories;
58              
59            // Iterate through the top level categories and retrieve 
60            // some information
61            for (int j = 0; j < topCategories.Length; j++) {
62            DataCategory topCategory = topCategories[j];
63            Console.WriteLine("Category name: " + 
64                topCategory.name);
65            Console.WriteLine("Category label: " + 
66                topCategory.label);
67            DataCategory [] childCategories =
68                topCategory.childCategories;
69            Console.WriteLine("Child categories: ");
70            for (int k = 0; k < childCategories.Length; k++) {
71                Console.WriteLine("\t" + k + ". Category name: " +
72                    childCategories[k].name);
73                Console.WriteLine("\t" + k + ". Category label: " +
74                    childCategories[k].label);
75            }
76            }
77        }
78    } 
79    catch (SoapException e) 
80    {
81        Console.WriteLine("An unexpected error has occurred: " +
82            e.Message + "\n" + e.StackTrace);
83    }
84}

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 data category group visibility settings. For more information on data 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

SOAP API Developer's Guide