Discover Objects and Members in Business Concepts (v3)
Resolves natural-language user text to Business Concepts, then returns direct semantic evidence and grouped, capped related objects and members.
REST Resource
POST
/HyperionPlanning/rest/v3/applications/{application}/businessconcepts/action/discoverRequired Roles
Service Administrator
Requests
Supported Media Types: application/json
The following table summarizes the client request parameters:
Table 3-92 Discover Objects and Members - Request Parameters
| Name | Description | Type | Required |
|---|---|---|---|
application |
Application name. | string | Yes |
text |
Natural-language text to resolve and discover related artifacts for. | string | Yes |
locale |
Locale hint for matching text; defaults to the request locale. | string | No |
planType |
Optional plan type used to narrow plan-type-bound cubes, forms, dashboards with resolvable backing forms, and members. When omitted, discovery uses application-level resolution across all plan types. | string | No |
conceptLimit |
Maximum number of resolved Business Concept matches to use for discovery. | integer | No |
limitPerType |
Maximum number of items returned in each object or member bucket. | integer | No |
artifactCandidateLimit |
Maximum number of scored Form or Dashboard candidates returned in explorationPlan.artifactCandidates. Candidate visibility is independent of recommendation eligibility. Minimum: 1. Maximum: 10. | integer | No |
artifactMinMatchPercent |
Minimum artifact concept score as a percentage of the strongest resolved concept score required for an artifact to drive a curated recommendation. Candidates below this threshold remain visible in explorationPlan.artifactCandidates. | integer | No |
processExcludes |
When true, discovery matches only positive Business Concept associations and honors EXCLUDES relationships by omitting them from positive matches. When false, discovery matches raw relationship-aware associations, including EXCLUDES. | boolean | No |
suggestions |
Controls lower-confidence weak-direct and description-only suggestions. AUTO includes only suggestions that add uncovered request terms; INCLUDE returns all eligible suggestions up to the remaining concept limit; NONE suppresses suggestions. | string | No |
objectTypes |
Logical object buckets to include. Supported values include Cube, Form, Folder, and Dashboard. If omitted, all object buckets with associations to resolved concepts are returned. Accepts null. | array of strings | No |
dimensions |
Dimension names to include for member discovery. If omitted, dimensions with member associations to resolved concepts are discovered. | array of strings | No |
objectFields |
Fields to return for each object item. Defaults to name, objectType, path, businessConcepts, and businessConceptAssociations. Type-specific fields are returned only from compatible buckets; cubeName applies to Form, and dashboardFormIds applies to Dashboard. They are omitted from incompatible buckets rather than rejecting a mixed-type request. Accepts null. | array of strings | No |
memberFields |
Fields to return for each member item. Defaults to name, path, businessConcepts, and businessConceptAssociations. | array of strings | No |
includeNavigation |
When true, returns routes in the caller's applicable navigation flows for Forms and Dashboards directly associated with resolved Business Concepts. | boolean | No |
navigationScope |
Controls selected-flow ranking among applicable navigation flows. selectedThenAll places the caller's selected flow first without excluding other applicable flows; all does not boost the selected flow. Allowed values: selectedThenAll, all. | string | No |
includeNavigationAncestors |
When true, each navigation route includes its Card, Cluster, and Tab ancestors in display order. When false, the route contains only its target node. | boolean | No |
navigationLimit |
Maximum primary or suggested navigation routes returned. A value of zero uses the default of 10. Minimum: 0. | integer | No |
Sample Request Payload:
{
"text": "What are the revenue, expenses, and variances for my department?",
"locale": "en",
"planType": "Plan1",
"conceptLimit": 5,
"limitPerType": 10,
"artifactCandidateLimit": 5,
"artifactMinMatchPercent": 60,
"processExcludes": true,
"suggestions": "AUTO",
"objectTypes": [
"Cube",
"Form",
"Dashboard"
],
"dimensions": [
"Account",
"Entity"
],
"objectFields": [
"name",
"objectType",
"path",
"businessConcepts",
"businessConceptAssociations"
],
"memberFields": [
"name",
"path",
"businessConcepts",
"businessConceptAssociations"
],
"includeNavigation": true,
"navigationScope": "selectedThenAll",
"includeNavigationAncestors": true,
"navigationLimit": 10
}
Response
Success schema: BusinessConceptDiscoveryResponse. Nested schemas are
documented in Shared schemas.
The following table lists the Response parameters:
Table 3-93 Discover Objects and Members - Response Parameters
| Name | Description | Type |
|---|---|---|
resolvedConcepts |
High-confidence direct semantic evidence used to retrieve primary objects and members. For multi-term requests, primary results require at least two matched terms and a score at least 40 percent of the strongest direct match. | BusinessConceptMatchCollection |
suggestedConcepts |
Lower-confidence weak-direct or description-only matches returned separately from primary routing evidence. | BusinessConceptMatchCollection |
objects |
Object result buckets keyed by logical object type, such as Cube, Form, Folder, or Dashboard. | BusinessConceptDiscoveryObjectCollection |
suggestedObjects |
Object result buckets associated only with suggested concepts. | BusinessConceptDiscoveryObjectCollection |
members |
Member result buckets keyed by dimension name, such as Account or Entity. | BusinessConceptDiscoveryMemberCollection |
suggestedMembers |
Member result buckets associated only with suggested concepts. | BusinessConceptDiscoveryMemberCollection |
navigationRoutes |
Primary routes in caller-applicable navigation flows supported by direct Business Concept associations. Returned only when includeNavigation is true. See BusinessConceptNavigationRouteCollection in Shared schemas. | BusinessConceptNavigationRouteCollection |
suggestedNavigationRoutes |
Lower-confidence routes supported by suggested concepts, excluding artifacts already present in navigationRoutes. Returned only when includeNavigation is true. | BusinessConceptNavigationRouteCollection |
explorationPlan |
Advisory, evidence-backed next-step guidance. This plan does not retrieve live data or select a complete point of view. | BusinessConceptExplorationPlan |
semanticPov |
Conservative POV proposal derived from the same parsed request and live application context. Clients must validate each semantic value against the selected form or cube. | BusinessConceptSemanticPovResolution |
Sample Response:
{
"resolvedConcepts": {
"items": [],
"totalResults": 0,
"hasMore": false
},
"suggestedConcepts": {
"items": [],
"totalResults": 0,
"hasMore": false
},
"objects": {},
"suggestedObjects": {},
"members": {},
"suggestedMembers": {},
"explorationPlan": {
"status": "NO_RELEVANT_CONCEPTS",
"sourceStrategy": "DIRECT_DISCOVERY",
"recommendedAction": "DIRECT_ARTIFACT_DISCOVERY",
"recommendationStrength": "LOW",
"reason": "No relevant concepts were resolved.",
"recommendations": [],
"artifactCandidates": [],
"caveats": [
"Validate a complete point of view before retrieving data."
]
}
}