MicroStrategy ONE

Using Extended Properties

Extended properties are a series of properties stored in property sets, which can be saved as part of an object in the metadata. These properties act as placeholders that allow you to store values on different objects.

A common use for extended properties is to store additional custom information that can be used to achieve new functionality. For example, assume that a report can be displayed as a grid, a graph, or a map. You want reports that can be displayed as maps to be identified with a distinctive icon when you view the contents of a folder. In addition, when a report is executed, if the extended property is set for map display and this feature is available for the user, you want a map icon to display on the toolbar and a new map menu item to be available. To accomplish this, you create a new property set with an extended property for displaying a report as a map and save it as part of the Report object. You use the value stored in this property to determine whether to apply the functionality associated with map display— a special image on the Folder Browsing page and a new toolbar icon and menu item on the Report page.

It is important to note that the extended property simply provides a way to save custom information; you must add the logic to support the functionality associated with the property. For example, you must create a custom event definition for each functionality you want to add and a custom event handler with the logic to handle each custom event. Depending on the functionality associated with the extended property, it can be necessary to create a custom transform and/or layout definition file and a new style that uses this transform and/or layout definition file.

In a Windows environment, you create new property sets and properties for MicroStrategy objects with the Extended Property Editor. To access this editor, you download the MicroStrategy SDK from the MicroStrategy Developer Zone (MSDZ) and then run the ExtPropEdt application located in the SDK/tools/ExtPropEdt folder.

The Extended Properties Editor is available only in a Windows environment.

To create property sets and properties, you must first connect to MicroStrategy by choosing File -> New Connection and specifying a data source, the authentication method, and a set of administrative credentials. Once you have successfully logged on to a data source, the Property Set menu becomes active.

From the Property Set menu on the Extended Properties Editor, you have menu options to Add, Edit, and Remove property sets and properties. Once you have added property sets and properties, you can retrieve and modify the value of these properties using the MicroStrategy SDK. The sections below provide sample code for performing the following actions:

Accessing a Property Set to Retrieve, Modify and Save a Property

Properties can be retrieved from different objects in the metadata, such as Projects, Reports, and Documents. All of these objects have public methods to access properties and property sets. The following code sample shows how to retrieve such properties from an object, modify them, and save them back into the object:

Copy 
//A property set object
WebPropertySet propSet = null;
 
//A property object
WebProperty property = null;
 
//A string to hold the value of the property
String propertyValue = “”;
 
//Fetch property set from object by passing the object type (report, project, etc) and the name of the property
propSet = myObject.getPropertySet(objectType, propertySetName);
 
//Fetch the property that we want to get access to by passing its name
property = propSet.getItemByName(propertyName);
 
//Fetch the value of the property and save it to a string variable
propertyValue = property.getValue();
 
//Add logic that uses the value of the property
…
 
//Set a new value for the property
property.setValue(“newValue”);
 
//Save the property set back into the object
propSet.save();

Retrieving Properties from a Report Object

The following code sample illustrates how to fetch properties from a Report object.

Copy 
/***
Get a report property value. <BR>
* It can retrieve any property in any property set. Thus it may trigger a Iserver call. <BR>
* @param rb the ReportBean object
* @param reportObjectType the object type (EnumDSSXMLReportObjects) for which the propertywill be
* @param propertySetName the property name
* @param propertyName the property name
* @return the property value
*/
private static String getReportInstancePropertyValue(ReportBean rb, int reportObjectType,String propertySetName, String propertyName) {
  String __result = "";
  try {
    WebPropertySet ps = null;
    ps = rb.getReportInstance().getPropertySet(reportObjectType, propertySetName);
    __result = ps.getItemByName(propertyName).getValue();       
    ps.getItemByName(propertyName).setValue(__result);
  } catch (WebBeanException ex) {
           // Couldn't retrieve report instance from report bean (rb)
     } catch (WebObjectsException ex) {
           // Couldn't retrieve property sets from report instance for report bean (rb)
     }
    return __result;
}
/**
* Set a report property and saves it <BR>
* It can set any property in any property set. <BR>
* @param rb the ReportBean object
* @param reportObjectType the object type (EnumDSSXMLReportObjects) for which the property will be
* @param propertySetName the property name
* @param propertyName the property name
* @param propertyValue the value to set on the specified property
*/private static void setReportInstancePropertyValue(ReportBean rb, int reportObjectType, String propertySetName, String propertyName, String propertyValue) {
    try {
           WebPropertySet ps = null;
 
           ps = rb.getReportInstance().getPropertySet(reportObjectType, propertySetName);
 
           ps.getItemByName(propertyName).setValue(propertyValue);
           ps.save();
         } catch (WebBeanException ex) {
         //Couldn't retrieve report instance from report bean (rb)
         } catch (WebObjectsException ex) {
         //Couldn't retrieve property sets from report instance for report bean (rb)
         }
    }

Retrieving Properties from a Project Object

The following code sample illustrates how to fetch properties from a Project object.

Copy 
try {
     propertySet = session.getFactory().getProjectSource()   .getProjectProperties("DefaultProjectProperties");
     if (propertySet != null) {
            WebProperty property = null;
 
            property = propertySet.getItemByName("ReportSaveAs8iWarning");
            if (property != null) {
                   property.setValue(value);
                   property.save();
            }
     }
} catch (WebObjectsException woe) {
  //Error in retrieving and saving PropertySet:DefaultProjectProperties, Property: ReportSaveAs8iWarning
}

See also