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/discover

Required 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."
    ]
  }
}