Re-Using Objects Via Shortcuts and Object Templates

Re-using objects can make distributing reports to users much easier. For example, you may have 50 reports that are all based on the same filter. If each report uses its own embedded filter, then that change must be performed in each of the 50 reports. However, if the filter is built as a stand-alone object and added as a shortcut to the reports, the filter can be changed once, and the change is automatically applied to all of the reports in which the filter is used. By creating the filter as a stand-alone object and including the filter as a shortcut in reports, you avoid having to manually change each of the reports that the filter is used in.

When planning to update objects, you can search for the objects that contain them or other objects they contain. This type of search can identify which reports, documents, and so on will be affected by changes to the object. You can, for example, search for all templates that contain the Profit metric by right-clicking the Profit metric and selecting Search for Dependents. The Search dialog box is displayed with a list of the Profit metric's dependents. As another example, you can search for all metrics that are used by the Store Sales template by right-clicking the Store Sales template and selecting Search for Components.

Objects that can be reused include filters, report templates, custom groups, and consolidations. For information on how to take advantage of re-usable objects and steps to create them, see the following links:

Shortcut to a Template
Shortcut to a Filter
Object Templates

Shortcut to a Template

A template specifies the information to retrieve from the data warehouse and how it is displayed in the report grid. Information on the report template includes metric default values, banding options, join type setting, and data sorting options. A template does not include filter information. You can create a stand-alone template in the Template Editor.

When you add a new template to a report, you can replace the default report template with a shortcut to the new template. Creating a shortcut to a template allows you to use a stand-alone template with any number of reports. Any changes made to the stand-alone template are then propagated to all reports that use that template.

You can determine whether a report's template is a shortcut to a template by looking at the template's name in the Grid definition. If a shortcut icon appears in the title bar, the report's template is a stand-alone template.

For steps to add a stand-alone template to a report, see Adding a Stand-Alone Template to a Report.

When you modify a shortcut template in a report, you can either choose to save those changes to this report only, or save them to all reports that share the same template.

If you save the changes to this report only, changes made to the template in this report do not impact other reports. If you save the changes to all reports that use this template, changes made to the template data definition in this report are propagated to all other reports that contain a shortcut to the same template. For example, if you add a metric to a report with a shortcut template, and then save the changes to the shortcut instead of only to the local copy of the report, all other reports that contain the same shortcut template display the new metric in Report Objects. For steps to save the report, see Saving a Report with a Shortcut to a Stand-Alone Template.

To avoid unexpected impacts on reports when making template changes, conduct a quick impact analysis: see Modifying a Template and Validating Changes.

Adding a Stand-Alone Template to a Report

The following procedure describes how to apply a previously created, stand-alone template to a report during report creation.

This procedure assumes that you have already created a stand-alone template. For steps, see the MicroStrategy Developer help.

To Add a Template to a Report

In Web or Developer, open the report in Design Mode.
Use the Object Browser to search for and locate the template that you want to add to the report.

If the Object Browser is not displayed, choose View > Object Browser.

Right-click the template and select one of the following:

To connect a stand-alone template to this report, select Replace with shortcut to template. Going forward, changes to the stand-alone template are propagated to the report, and vice versa.
To embed the template in the report, select Replace with copy of template. Going forward, changes to the stand-alone template are not propagated to the report, and vice versa.
The template's components appear in the report's Report View pane. If the template is a shortcut, the template's name is also displayed. If the report does not use a shortcut template, the template is named Local Template.

Save the report.
If you added the template as a shortcut, you must save the report with the shortcut to retain that functionality. For steps, see To Save a Report with a Shortcut to a Stand-Alone Template.

Saving a Report with a Shortcut to a Stand-Alone Template

When you save changes to a report that contains a stand-alone template, you can choose to either save the changes to that report only (called a local copy), or save the changes to all reports that use the same template (called a template shortcut). Steps are below to save a report's change to a template shortcut so that those changes are automatically propagated to all reports that also use the stand-alone template they are all connected to.

Reports with shortcuts to stand-alone templates and filters allow you to share report caches. For an introduction to report caches, see the Caching chapter in the System Administration Help.

To Save a Report with a Shortcut to a Stand-Alone Template

Save the report with a shortcut to a stand-alone template:

Click Save and Close on the toolbar of the Report Editor or Report Viewer.
Select the folder in which to save the report, then enter the name of the new report.
Click Save.

If the report contains prompts, the Save Options dialog box opens after you have named the report. Click Advanced on the Save Options dialog box. For a prompted report, see the MicroStrategy Developer help.

Select one of the following options for saving the report:

Create a local copy of the template. Changes that you make to the template are not propagated to the original object, and vice versa. This is also called a local or embedded template.
Retain the shortcuts to the template. Creating shortcuts allows you to take advantage of the benefits of object reuse. Changes that you make to the template are propagated to the original object, and vice versa. Use this option to share report caches.

Select the Remember answers the next time I am prompted check box to use the selections that you made above as the defaults for saving reports in future.
Click OK.

Modifying a Template and Validating Changes

Changing a template may cause unexpected issues with some of the reports that depend on the template. For example, a report has a shortcut to a template, which contains Country, Region, Metric 1, and Metric 2. The view filter is set to "Metric 1 > 20." Metric 1 is then removed from the stand-alone template but not from the report view. When that report is executed, an error occurs because the view filter can no longer be evaluated (Metric 1 no longer exists).

You can check for issues like the example above by validating your template changes. You validate template changes by conducting a quick impact analysis with the Template Dependency Validator, before saving any changes to a template. When a template is modified and saved in MicroStrategy Developer, the Template Dependency Validator lists:

Reports that depend on the template
Reports that will not run if the change is completed

To resolve any issues, you can do the following in the Template Dependency Validator:

Cancel the change and re-evaluate.
Open each dependent report and remove the dependencies, then make your changes to the template.

For the previous example, you might remove the view filter from the view definition of the dependent report.

Shortcut to a Filter

When you add a filter to a report, you have the option of adding it as an embedded filter which applies to that report only, or you can add a shortcut to an existing filter.

An embedded filter is generated when a copy of an existing filter is added to a report or when the filter is created on the fly from within the report. Changes made to an embedded filter affect only the report in which it is contained because the filter exists only within that report.

In contrast, a shortcut to a filter stands alone as a filter and can be used in multiple reports. When the stand-alone filter is changed, the changes are propagated to all other reports that contain a shortcut to the same filter. For more information and steps on how to create an embedded filter or a shortcut to a filter, see Shortcut vs. Embedded Filters.

Object Templates

An object template is a predefined structure you can use to create a new object. An object template provides a foundation you can use to create reports, metrics, filters, or other objects. For example, you may want to create many filters that contain the current month as part of the filter's definition. You can create a filter object template that contains the current month and use the filter object template to automatically include the current month condition in every new filter you create. Using an object template, you only have to define that filtering condition once.

Another example is a need to build multiple reports containing the attribute Day and the metrics Revenue, Cost, and Profit. To reduce the time spent creating these similar reports, define a report with these objects and save it in the Object Templates folder, thus creating a report object template. Multiple reports can now be based on the new report object template, thus incorporating the template's attributes and metrics quickly and easily.

You can create empty object templates that define default formatting on a project level for new reports, templates, metrics, and documents. For a list of settings you can define for each type of empty object template, see Empty Object Templates.

You can create object templates for the following objects:

Consolidations
Custom groups
Documents
Filters
Metrics
Reports
Templates (A template is the part of a report that specifies the information to retrieve from the data warehouse and how it is displayed in the report grid. It does not include filter information. For more information on what a template includes, see Shortcut to a Template.)

You can determine whether users can choose from a list of available object templates when creating a new object, or if they must use a default object template that you define. For steps, see Making Object Templates Available to Users.

If an object template is altered, the change is not propagated to previously defined objects.

To be used as an object template, the object must be saved in the Object Templates folder. This is the only difference between an object (such as a report) and an object template (such as a report object template).

Empty Object Templates

Empty object templates define default formatting and other default settings on a project level for new reports, templates, metrics, and documents. They do not contain a definition.

Your project has a series of reports that must be exported in Excel format to a particular location. A specific Excel macro must be run after the report is exported. You can create a user-defined empty report object template, called Excel Export Settings, with these specifications. When the Excel Export Settings report object template is used to create a new report, the new report contains the correct Excel information.

As another example, a project requires all currency values to include cents for precision and to distinguish negative values in red font. To meet these conditions, create an empty metric object template named Currency Formatting and set these formats. When a user creates a new metric that returns currency values, he selects Currency Formatting in the New Metric dialog box. The formatting for red negative values and cents is included in the new metric.

There are two kinds of empty object templates:

Empty object templates provided by MicroStrategy. These are displayed in the New Object dialog box as Empty Document, Empty Metric, Empty Report, and Empty Template.
You can choose whether to display the empty object template for a particular object type. For steps, see Making Object Templates Available to Users.
User-defined empty object templates. These help you control new objects created in your project, by specifying a default set of formatting options that should be applied to each new object.
You can create an empty metric template with specific currency formatting or an empty report object template set to display data by default in outline mode. The user-defined empty object template contains only formatting options. User-defined empty metric templates do not have formulas and user-defined empty report templates do not include attributes, metrics, or other grid items in the report objects.
Empty object templates are saved in the Object Templates folder.
The settings available in a user-defined empty object template vary with the type of object, as described below:
- An empty metric object template does not contain a formula but can contain the following settings:
- An empty report object template does not contain any grid units, such as attributes, metrics, consolidations, and so on. An empty report contains:
- An empty template object template is similar to an empty report object template.

Making Object Templates Available to Users

You can determine whether users can choose from a list of available object templates when creating a new object. By default, the New Object dialog box displays when users create a new object and contains a list of available object templates users can use to define the new object.

If you choose to hide the New Object dialog box for a type of object, each new object of that type will be created using the default object template. If you have not defined a default object template, the object will be created using MicroStrategy's empty object template. Default object templates include Documents, Metrics, Reports, and Templates.

If you choose to display the New Object dialog box, you can choose to hide MicroStrategy's empty object template. The empty object template is displayed in the New Object dialog box as Empty Document, Empty Metric, Empty Report, or Empty Template. If you hide the empty object template, users cannot create new objects with the empty object template.

If you disable the empty object template for a particular object type, and the only object template is the project-level default object template, all new objects must use the formatting and other settings defined on the default object template. You can use this feature to ensure that all reports in a project adhere to specific formatting standards.

You create a report object template with specific formatting and save the report object template as Default Format. The project does not have any other report object templates. You set Default Format as the default object template for reports and do not show the Empty Report object template. If a user has enabled object templates for reports, when he creates a new report, his only choice in the New Grid dialog box is Default Format. If object templates for reports have been disabled, the New Grid dialog box is not displayed and Default Format is automatically used.