describeDataCategoryGroupStructures() | SOAP API Developer Guide

Syntax

1describeDataCategoryGroupStructures()[] = connection.
2                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 “Data Categories in Salesforce.com” and “Data Category 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.

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

Sample Code—C#

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.

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

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 Data Category 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

describeDataCategoryGroupStructures()[]

Faults

InvalidSObjectFault

UnexpectedErrorFault