MicroStrategy ONE

WebDrillMap - WebDrillPath

A report and each template unit on the report have default drill paths associated with them. A drill path describes a path that is followed while drilling. These drill paths have the corresponding drill actions embedded within their definition. The WebDrillPath interface represents a drill path. It holds a collection of WebDrillPaths. Thus, a report has its own drill map (report-level drill map), and each template unit on the report has its own drill map (template unit drill maps).

WebDrillPath

  • Each drill path has a drillPath ID associated with it. This ID is unique over the template unit or report-level drill map to which it belongs. The drillPath ID can be read using the getID() method.  

  • Each drill path has a name and a description. They can be read using the  getName() and getDescription() methods respectively. It also has a SetName() method, which specifies the name of the set to which the drill path belongs. The SetName() method can be queried using getSetName().  

  • The drill actions for a drill path can be obtained and traversed using getDrillActions().  

  • A drill path can have a path object (generally, drill paths for metrics have path objects). On a drill path, getPathObject() returns the corresponding path object if it exists. If the path object is absent, it returns a null value.  

  • A drill path also has an enumeration for its importance. This constant is used to designate the paths that are deemed important by the designer of the drill map. MicroStrategy Intelligence Server uses this importance criterion when it is searching for a drill map to determine which paths to offer to the user as possible drill actions.

The following values are available for the importance property of a drill path (defined in com.microstrategy.webapi.EnumDSSXMLDrillImportance):

Importance Meaning

DssXmlDrillImportanceHigh

The server includes this path for all types of path searches.

DssXmlDrillImportanceMedium

The server includes this path only when it is searching for multiple paths, but not when it is searching for a single path.

DssXmlDrillImportanceLow

The report server only includes this path when searching for multiple paths.

WebDrillMap

  • The WebDrillMap interface has support for browsing through its WebDrillPath objects using methods such as elements(), size(), isEmpty(), get(int index), itemByID(int drillPathID), and getDrillPathWithHighImportance(). getDrillPathWithHighImportance() is used to get the drill path with High Importance from the Report Server. Only one such drill path should exist for a given report or template unit on Intelligence Server. If there are more than one drill paths, this call returns the first one encountered. 

  • Drill paths of a report instance can be browsed by calling getDrillMap() on its WebDrillInstance object. The call returns the drill paths as a collection within a WebDrillMap object. 

  • To get the default drill paths for a template unit of a report instance, the getDrillMap() method is used on the corresponding WebTemplateUnit object. 

  • From a drill map, filterBySetName(String setName) is used to get a filtered drill map with only those drill paths that belong to the set name that is passed as an argument. 

  • The WebDrillMap object is Read-Only. Thus it does not support adding drill paths. Similarly the WebDrillPath objects are Read-Only. 

  • getUniqueDrillPaths() can be used to get a list of unique drill paths from the drill map. Drill paths are compared by name. If similar drill paths exist along different importance levels, the one with highest importance is included in the returned drill map. 

  • getSetNames() returns an ordered array of set names contained in the drill map.

Once, an application has obtained a drill path (as a WebDrillPath object) from a WebDrillMap, it can ask the WebDrillInstance object to generate and populate the corresponding WebDrillAction objects using loadActionsFromDrillPath(WebDrillPath drillPath.). If the WebDrillPath has been obtained from a WebTemplateUnit, the WebTemplateUnit would be set automatically as the template unit (drill source) for the WebDrillInstance within this call.

loadActionsFromDrillPath(int drillPathID) uses the drillPathID to search the corresponding drill path object and load its drill actions. If no drill template unit is specified, it searches for the corresponding drill path object only within the report level drill map, otherwise it searches within the drill map of the specified template unit.