System

Administration Guide

Version: 10.10
10.10, June 2018
Copyright © 2018 by MicroStrategy Incorporated. All rights reserved.
Trademark Information
The following are either trademarks or registered trademarks of MicroStrategy Incorporated or its affiliates in the United States and certain other countries:
MicroStrategy, MicroStrategy 10, MicroStrategy 10 Secure Enterprise, MicroStrategy 9, MicroStrategy 9s, MicroStrategy Analytics, MicroStrategy Analytics Platform, MicroStrategy
Desktop, MicroStrategy Library, MicroStrategy Operations Manager, MicroStrategy Analytics Enterprise, MicroStrategy Evaluation Edition, MicroStrategy Secure Enterprise,
MicroStrategy Web, MicroStrategy Mobile, MicroStrategy Server, MicroStrategy Parallel Relational In-Memory Engine (MicroStrategy PRIME), MicroStrategy MultiSource,
MicroStrategy OLAP Services, MicroStrategy Intelligence Server, MicroStrategy Intelligence Server Universal, MicroStrategy Distribution Services, MicroStrategy Report Services,
MicroStrategy Transaction Services, MicroStrategy Visual Insight, MicroStrategy Web Reporter, MicroStrategy Web Analyst, MicroStrategy Office, MicroStrategy Data Mining Services,
MicroStrategy Narrowcast Server, MicroStrategy Health Center, MicroStrategy Analyst, MicroStrategy Developer, MicroStrategy Web Professional, MicroStrategy Architect,
MicroStrategy SDK, MicroStrategy Command Manager, MicroStrategy Enterprise Manager, MicroStrategy Object Manager, MicroStrategy Integrity Manager, MicroStrategy System
Manager, MicroStrategy Analytics App, MicroStrategy Mobile App, MicroStrategy Tech Support App, MicroStrategy Mobile App Platform, MicroStrategy Cloud, MicroStrategy R
Integration, Dossier, Usher, MicroStrategy Usher, Usher Badge, Usher Security, Usher Security Server, Usher Mobile, Usher Analytics, Usher Network Manager, Usher Professional,
MicroStrategy Services, MicroStrategy Professional Services, MicroStrategy Consulting, MicroStrategy Customer Services, MicroStrategy Education, MicroStrategy University,
MicroStrategy Managed Services, BI QuickStrike, Mobile QuickStrike, Transaction Services QuickStrike Perennial Education Pass, MicroStrategy Web Based Training (WBT),
MicroStrategy World, Best in Business Intelligence, Pixel Perfect, Global Delivery Center, Direct Connect, Enterprise Grade Security For Every Business, Build Your Own Business
Apps, Code-Free, Welcome to Ideal, The World’s Most Comprehensive Analytics Platform, The World’s Most Comprehensive Analytics Platform. Period.
Other product and company names mentioned herein may be the trademarks of their respective owners.
Specifications subject to change without notice. MicroStrategy is not responsible for errors or omissions. MicroStrategy makes no warranties or commitments concerning the availability
of future products or versions that may be planned or under development.
Patent Information
This product is patented. One or more of the following patents may apply to the product sold herein: U.S. Patent Nos. 6,154,766, 6,173,310, 6,260,050, 6,263,051, 6,269,393, 6,279,033,
6,567,796, 6,587,547, 6,606,596, 6,658,093, 6,658,432, 6,662,195, 6,671,715, 6,691,100, 6,694,316, 6,697,808, 6,704,723, 6,741,980, 6,765,997, 6,768,788, 6,772,137, 6,788,768, 6,798,867,
6,801,910, 6,820,073, 6,829,334, 6,836,537, 6,850,603, 6,859,798, 6,873,693, 6,885,734, 6,940,953, 6,964,012, 6,977,992, 6,996,568, 6,996,569, 7,003,512, 7,010,518, 7,016,480, 7,020,251,
7,039,165, 7,082,422, 7,113,993, 7,127,403, 7,174,349, 7,181,417, 7,194,457, 7,197,461, 7,228,303, 7,260,577, 7,266,181, 7,272,212, 7,302,639, 7,324,942, 7,330,847, 7,340,040, 7,356,758,
7,356,840, 7,415,438, 7,428,302, 7,430,562, 7,440,898, 7,486,780, 7,509,671, 7,516,181, 7,559,048, 7,574,376, 7,617,201, 7,725,811, 7,801,967, 7,836,178, 7,861,161, 7,861,253, 7,881,443,
7,925,616, 7,945,584, 7,970,782, 8,005,870, 8,051,168, 8,051,369, 8,094,788, 8,130,918, 8,296,287, 8,321,411, 8,452,755, 8,521,733, 8,522,192, 8,577,902, 8,606,813, 8,607,138, 8,645,313,
8,761,659, 8,775,807, 8,782,083, 8,812,490, 8,832,588, 8,943,044, 8,943,187. 8,958,537, 8,966,597, 8,983,440, 8,984,274, 8,984,288, 8,995,628, 9,027,099, 9,027,105, 9,037, 577, 9,038,152,
9,076,006, 9,086,837, 9,116,954, 9,124,630, 9,154,303, 9,154,486, 9,160,727, 9,166,986, 9,171,073, 9,172,699, 9,173,101, 9,183, 317, 9,195,814, 9,208,213, 9,208,444, 9,262,481, 9,264,415,
9,264,480, 9,269,358, 9,275,127, 9,292,571, 9,300,646, 9,311,683 9,313,206, 9,330,174, 9,338,157, 9,361,392, 9,378,386, 9,386,416, 9,391,782, 9,397,838, 9,397,980, 9,405,804, 9,413,710,
9,413,794, 9,430,629, 9,432,808, 9,438,597, 9,444,805, 9,450,942, 9,450,958, 9,454,594, 9,507,755, 9,513,770, 9,516,018, 9,529,850, 9,563,761, 9,565,175, 9,608,970, 9,640,001, 9,646,165,
9,680,908, 9,697,146, 9,697,350, 9,742,764, 9,742,781, 9,743,235, 9,762,564, 9,794,245, 9,801,053, and 9,807,074. Other patent applications are pending.
 1
CONTENTS
Overview and Additional Resources 5
Introduction to MicroStrategy System Administration 19
Setting Up User Security 67
Identifying Users: Authentication 111
Create a Service Principal Name for your Libraryapplication server 181
Configure the krb5.keytab file for the application server 181
Configure the krb5.conf file for the Libraryapplication server 183
Configure the jaas.conf file for the application server 184
Configure the JVM startup parameters 185
Enable the SPNEGO mechanism 185
Configure the configOverride.properties File 186
To configure IIS to enable integrated authentication to the MicroStrategy virtual
directory 187
Creating a Service Principal Name for IIS 187
Enabling session keys for Kerberos security 188
Configuring the krb5.ini file 188
Secure Communication in MicroStrategy 226
Managing Your Licenses 241
Managing Your Projects 260
Monitoring System Usage 316
Tuning Your System for Best Performance 333
Clustering Multiple MicroStrategy Servers 399
Improving Report and Document Response Time: Caching 438
Managing Intelligent Cubes 490
Scheduling Jobs and Administrative Tasks 507
Administering MicroStrategy Web and Mobile 556

© 2018, MicroStrategy Inc. iii

System Administration Guide

Combining Administrative Tasks with System Manager 571

Automating Administrative Tasks with Command Manager 670
Verifying Reports and Documents with Integrity Manager 683
Maintaining Your MicroStrategy System with Health Center 717
SQL Generation and Data Processing: VLDB Properties 743
Creating a Multilingual Environment: Internationalization 950
Multi-Tenant Environments: Object Name Personalization 1000
List of Privileges 1023
Intelligence Server Statistics Data Dictionary 1050
Enterprise Manager Data Dictionary 1128
Command Manager Runtime 1569
MicroStrategy Web Cookies 1572
Troubleshooting 1583
Index 1636

iv © 2018, MicroStrategy Inc.

 1
OVERVIEW AND ADDITIONAL
RESOURCES
This guide is the primary resource that system administrators use to learn about the
concepts and high-level steps for implementing, deploying, maintaining, tuning, and
troubleshooting the MicroStrategy business intelligence system. It offers a full discussion of
the concepts that a system administrator should consider before the system is made widely
available to users in the enterprise.
The sections provide the following information:
• Introduction to MicroStrategy System Administration
This section provides an overview of the architecture and how the MicroStrategy system
interacts with the various external components/systems. It describes how Intelligence
Server connects to and uses the data warehouse. It also describes what Intelligence
Server is, what happens when it is started and stopped, and what MicroStrategy
metadata is and what purposes it serves, as well as what a MicroStrategy project is and
what MicroStrategy objects are. It describes all aspects of connecting to databases
including database instances, database connections, and what a MicroStrategy server
definition is and what it controls. It also describes general job processing flows with the
MicroStrategy system including report execution, object and element browsing, and
HTML document execution.
• Chapter , Setting Up User Security
This section covers what users and groups are, what the different modes are for
authentication and how to implement them, how to control access to data at both the
application and database levels, and how to control access to the application
functionality. The examples section shows how combinations of security features in both
the MicroStrategy system and in the database management systems can be used
together.
This section describes how to manage MicroStrategy Web and MicroStrategy Web
Universal, what the Web-related privileges are for the product, how to use the
Administrator page including how to set project defaults. It also describes additional
security requirements or options you can use with MicroStrategy Web products,
including using digital certificates or firewalls, secure sockets layers, and so on.
• Chapter , Identifying Users: Authentication

© 2018, MicroStrategy Inc. 5

System Administration Guide

Authentication is the process through which the system identifies the user. This section
describes the modes of authentication that MicroStrategy supports, and how to
configure them so that they support your user community.
• Enabling Secure Communication
This section describes the steps to enable secure, encrypted communications between
MicroStrategy components using SSL.
• Chapter , Managing Your Licenses
This section covers making the system available to users. This includes some best
practices are for deploying the system, and how to implement easy ways to install
systems using SMS systems and silent installs; what License Manager is and how to use
it; and setting up security in the MicroStrategy environment.
• Chapter , Managing Your Projects
In a MicroStrategy system, a project is the environment in which reporting is done. This
section provides information on how to manage a project’s life cycle, how to duplicate a
project, update or copy project objects, merge projects, compare and track projects, and
manage schema objects.
• Chapter , Monitoring System Usage
This section explains how you can use the monitors available in the system to see the
state of the system at any time (past or present). It describes how Enterprise Manager
can help do this by monitoring statistics that can be logged.
• Chapter , Tuning Your System for Best Performance
This section provides information for you to find the balance that maximizes the use of
your system’s capacity to provide the best performance possible for the required number
of users.
• Chapter , Clustering Multiple MicroStrategy Servers
A clustered set of machines provides a related set of functionality or services to a
common set of users. MicroStrategy recommends clustering Intelligence Servers in
environments where access to the data warehouse is mission-critical and system
performance is of utmost importance. This section describes how to cluster Intelligence
Servers, how to manage clustered projects, and how to connect MicroStrategy Web to a
cluster.
• Chapter , Improving Report and Document Response Time: Caching
This section explains how you can make the system efficient and remove load from
Intelligence Server by using the caching and History List features. It describes how
caches work in the system, where they are stored, what the matching requirements are
for using a cache, how to create pre-calculated data using aggregate tables, how to
administer caches including how to invalidate them. It also describes what the History
List is, how it is used in both MicroStrategy Web and Developer, and how to administer
it.
• Chapter , Managing Intelligent Cubes

6 © 2018, MicroStrategy Inc.

 System Administration Guide

You can return data from your data warehouse and save it to Intelligence Server
memory, rather than directly displaying the results in a report. This data can then be
shared as a single in-memory copy, among many different reports created by multiple
users. The reports created from the shared sets of data are executed against the in-
memory copy, also known as an Intelligent Cube. This section provides details to
understand and to create Intelligent Cubes your users can access when the execute
reports and documents.
• Chapter , Scheduling Jobs and Administrative Tasks
This section describes how you can automate certain MicroStrategy jobs and
administrative tasks. Methods of automation include scheduling reports, documents, and
administrative tasks, and using MicroStrategy Distribution Services to distribute reports
and documents via email, file, and printer subscriptions.
• Chapter , Administering MicroStrategy Web and Mobile
This section provides a high-level overview for some of the administrative tasks that are
unique to administering MicroStrategy Web, Web Universal, and Mobile Server.
• Chapter , Combining Administrative Tasks with System Manager
System Manager lets you define multiple configurations for your MicroStrategy
environment, that can then be executed in a single workflow. This provides the ability to
deploy the various configurations to as many systems as required. The deployment of
these configurations can be done using a standard interface, an interactive command
line process, or a completely silent configuration process.
• Chapter , Automating Administrative Tasks with Command Manager
Command Manager lets you automate various administrative and application
development tasks by using text commands that can be saved as scripts. This section
describes how to create and execute these scripts.
• Chapter , Verifying Reports and Documents with Integrity Manager
Integrity Manager is an automated comparison tool designed to streamline the testing of
MicroStrategy reports and documents. It can verify that changes to the environment
have not caused changes to the report results, and can also test the performance of an
Intelligence Server. This section describes how to configure Integrity Manager and how
to create and execute an integrity test, and provides best practices for using Integrity
Manager.
• Chapter , Maintaining Your MicroStrategy System with Health Center
MicroStrategy Health Center can help you diagnose and fix problems in your
MicroStrategy system. It detects known problems and provides an immediate solution to
many of them. This section describes how to configure your Health Center network and
how to schedule system checks for MicroStrategy components.
• SQL Generation and Data Processing: VLDB Properties
This section shows you how to set the VLDB properties for your system, and provides a
complete listing of all MicroStrategy VLDB properties.
• Chapter , Creating a Multilingual Environment: Internationalization

© 2018, MicroStrategy Inc. 7

System Administration Guide

This section shows you how to use MicroStrategy to internationalize a project in your
MicroStrategy environment, to make it available to a multi-lingual audience. This
includes internationalizing data in your data warehouse and metadata objects in the
MicroStrategy metadata repository.
• Chapter , Multi-Tenant Environments: Object Name Personalization
This section shows you how to use MicroStrategy to personalize object names in a
project in your MicroStrategy environment, to support a multi-tenant setup.
• Chapter , List of Privileges
This section provides a complete list of the privileges assigned to each predefined user
group and security role. It also provides a complete list of all privileges available in
MicroStrategy.
• Chapter , Command Manager Runtime
This section provides a complete list of the commands available in Command Manager
Runtime, a lightweight version of Command Manager designed to be bundled with OEM
applications.
• Chapter , Intelligence Server Statistics Data Dictionary
This section provides a complete list of all the database tables used in the Intelligence
Server statistics.
• Chapter , Enterprise Manager Data Dictionary
This section provides a complete list of all the database tables and object definitions
used in the Enterprise Manager project.
• Chapter , MicroStrategy Web Cookies
This section provides a complete list of all the cookies used by MicroStrategy Web.

The sample documents and images in this guide, as well as some example steps, were
created with dates that may no longer be available in the MicroStrategy Tutorial project. If you
are re-creating an example, replace the year(s) shown in this guide with the most recent year
(s) available in the software.

• Chapter , Troubleshooting
This section provides a high-level methodology for finding trouble spots in the system
and fixing them. It describes how to use the Diagnostics and Performance Logging tool
to help diagnose bottlenecks in the system, memory depletions, exceptions, or
authentication problems.

About This Guide

The following sections provide the location of additional examples and describe the user
roles for which the information in this book was designed.

The sample documents and images in this guide, as well as some example steps, were
created with dates that may no longer be available in the MicroStrategy Tutorial project. If you

8 © 2018, MicroStrategy Inc.

 System Administration Guide

are re-creating an example, replace the year(s) shown in this guide with the most recent year
(s) available in the software.

How to find business scenarios and examples

Within this guide, many of the concepts discussed are accompanied by business scenarios
or other descriptive examples.
For examples of reporting functionality, see the MicroStrategy Tutorial, which is
MicroStrategy’s sample warehouse and project. Information about the MicroStrategy
Tutorial and the Human Resources Analytics Module can be found in the Basic Reporting
Guide.
Detailed examples of advanced reporting functionality can be found in the Advanced
Reporting Guide.
Other examples in this book use the Analytics Module project, which includes a set of
precreated sample reports. Sample reports present data for analysis in the human resources
business area.

What’s new in this guide

MicroStrategy 10.9
l You can now control MicroStrategy PDF Exporter and MicroStrategy Collaboration
Service via Service Manager. For more information, see the Service Manager section of
Running Intelligence Server as an application or a service
l File size limits can now be placed on the log files collected by Kafka Consumer. For more
information, see Limiting the Size of Messages Logged to Kafka .
l Report Pre and Post SQL statements can now be executed against Connect Live
Intelligent Cubes that run against primary and/or secondary database instances. For more
information, see Multi-source Report Pre and Post Statements.

MicroStrategy 10.8
l Change Journaling is now enabled by default for all projects in your production
environment. There is no longer an option to disable change journaling in the project
configuration. For more information, see Monitoring system activity: Change journaling
l To enable persistent quick search functionality in projects, the Change Journal
functionality is now enabled by default.
l For MDX metric values, you can now select whether to format per column or cell. For
more informatoin, see MDX Cell Formatting.

© 2018, MicroStrategy Inc. 9

System Administration Guide

MicroStrategy 10.7
l When performing In-Memory calculations - such as derived metrics, subtotals, and
dynamic aggregation - on simple and aggregation functions, we would ignore nulls during
the calculation of aggregation functions while still treating them as 0 for scalar operations.
The new calculation behavior is applied by default but can be reverted by through the
Advanced VLDB Properties Editor. For more information, see NULL checking for
Analytical Engine
l When running a multi-source report in 10.7, you can execute multiple report pre- and post-
SQL statements in an expected order for both primary and all secondary databases. This
can be helpful to database administrators who want to collect database statistics. The
SQL statements are also executed when the report is used in a document or dashboard.
To apply pre- and post-SQL statements, use the Pre/Post Statements VLDB setting. For
more information on these SQL statements, see Multi-source Report Pre and Post
Statements.

MicroStrategy 10.6
l MicroStrategy Web (JSP version) and Mobile can now use SAML to authenticate users by
integrating with third-party IdPs, such as Usher, without writing code. For more
information, see Enabling single sign-on with SAML authentication for JSP Web and
Mobile.
l Pre/Post Statements now support using !f to insert the full path to the report. For more
information, see Customizing SQL statements: Pre/Post Statements.

MicroStrategy 10.5
l On Linux environments, 10.5 includes Messaging Services. This offers a fast and scalable
message broker for distributed deployments. For new installations, the Messaging
Services is enabled out-of-the-box by default. For upgrades to the 10.5 Feature Release,
Messaging Services needs to be configured in conjunction with the existing Intelligence
Server(s). For more information, see MicroStrategy Messaging Services.

MicroStrategy 10.4
l You can reserve nodes in a cluster for specific users with user fences or for subscriptions
with workload fences. For more information, see Reserving nodes with Work Fences,
page 420.
l When using Usher as a method of authentication for MicroStrategy Web and Mobile, you
can leverage the connection between LDAP and your Usher server, eliminating the need
for manual configuration. For Steps, see Enabling Usher authentication for Web and
Mobile.

10 © 2018, MicroStrategy Inc.

 System Administration Guide

MicroStrategy 10
l You can allow users of MicroStrategy Mobile to use integrated authentication to log into
MicroStrategy. For steps to configure integrated authentication, see Enabling integrated
authentication.
l System Manager:
l Encrypt or decrypt specified text or a file (see Performing system processes, page 631).
l Determine the state of Amazon Cloud image (see Administering cloud-based
environments, page 647).
l Documentation on new or modified VLDB properties:
l Modifying third-party cube sources in MicroStrategy: MDX, page 810
l Limiting report rows, SQL size, and SQL time-out: Governing, page 775
l Modifying third-party cube sources in MicroStrategy: MDX, page 810
l Modifying third-party cube sources in MicroStrategy: MDX, page 810
l Calculating data: Metrics, page 821
l Calculating data: Metrics, page 821
l Selecting and inserting data with SQL: Select/Insert, page 908
l Selecting and inserting data with SQL: Select/Insert, page 908
l Parallel SQL Execution Intermediate Table Type, page 946

Who should use this guide

This document is designed for:
• System administrators responsible for configuring and maintaining the MicroStrategy
business intelligence system
• Database administrators who may need to understand how databases (such as the data
warehouse and metadata) work with the MicroStrategy system
• Network administrators who may need to configure network connections between the
system’s components

Education
MicroStrategy Education Services provides a comprehensive curriculum and highly skilled
education consultants. Many customers and partners from over 800 different organizations
have benefited from MicroStrategy instruction.
Courses that can help you prepare for using this manual or that address some of the
information in this manual include:
• Implementing MicroStrategy: Development and Deployment

© 2018, MicroStrategy Inc. 11

System Administration Guide

• MicroStrategy Administration
For the most up-to-date and detailed description of education offerings and course curricula,
visit http://www.microstrategy.com/Education.

Documentation
MicroStrategy provides both manuals and online help; these two information sources
provide different types of information, as described below:
• Manuals: In general, MicroStrategy manuals provide:
▫ Introductory information and concepts
▫ Examples and images
▫ Checklists and high-level procedures to get started
To access documentation resources from any location, click here.
Most of these manuals are also available printed in a bound, soft cover format. To
purchase printed manuals, contact your MicroStrategy Account Executive with a
purchase order number.
• Help: In general, MicroStrategy help provides:
▫ Detailed steps to perform procedures
▫ Descriptions of each option on every software screen

Translations
Due to translation time, manuals in languages other than English may contain information
that is one or more releases behind. You can see the version number on the title page of
each manual.

Finding information
You can search all MicroStrategy books and Help for a word or phrase, with a simple
Google™ search at http://www.google.com. For example, type “MicroStrategy derived
metric” or “MicroStrategy logical table” into a Google search. As described above, books
typically describe general concepts and examples; Help typically provides detailed steps and
screen options. To limit your search to MicroStrategy books, on Google’s main page you can
click More, then select Books.

Additional formats
MicroStrategy manuals are available as electronic publications, downloadable on the Apple
iBookstore or Google Play, and can be read on your iOS or Android device respectively. To
download a book, search for the book’s title in the iBookstore or Google Play respectively. To
view a list of manuals that are currently available, scan the following QR codes using your
device’s camera:

12 © 2018, MicroStrategy Inc.

 System Administration Guide

For iOS devices, scan the following QR code:

For Android devices, scan the following QR code:

For new MicroStrategy releases, it may take several days for the latest manuals to be
available on the iBookstore or Google Play.

Guides for MicroStrategy overview and evaluation

• Introduction to MicroStrategy
Instructions for installing, configuring, and using the MicroStrategy Evaluation Edition of
the software. This guide also includes a detailed, step-by-step evaluation process of
MicroStrategy features, where you perform reporting with the MicroStrategy Tutorial
project and its sample business data.
• MicroStrategy Evaluation Edition Quick Start Guide
Overview of the installation and evaluation process, and additional resources.

Resources for Security

• Usher Help
Steps to setup your Usher Security network, and control access to logical and physical
resources.

Manuals for query, reporting, and analysis

• MicroStrategy Installation and Configuration Guide

© 2018, MicroStrategy Inc. 13

System Administration Guide

Information to install and configure MicroStrategy products on Windows, UNIX, Linux,

and HP platforms, as well as basic maintenance guidelines.
• MicroStrategy Upgrade Guide
Instructions to upgrade existing MicroStrategy products.
• MicroStrategy Project Design Guide
Information to create and modify MicroStrategy projects, and understand facts,
attributes, hierarchies, transformations, advanced schemas, and project optimization.
• MicroStrategy Basic Reporting Guide
Instructions to get started with MicroStrategy Developer and MicroStrategy Web, and
how to analyze data in a report. Includes the basics for creating reports, metrics, filters,
and prompts.
• MicroStrategy Advanced Reporting Guide
• MicroStrategy Report Services Document Creation Guide
Instructions to design and create Report Services documents, building on information in
the Document and Dashboard Analysis Guide. It is organized to help guide you through
creating a new document, from creating the document itself, to adding objects to the new
document, and formatting the document and its objects.
• MicroStrategy Dashboards and Widgets Creation Guide
Instructions for designing and creating MicroStrategy Report Services dashboards, a
type of document that is optimized for viewing online and for user interactivity. It builds on
the basic concepts about documents presented in the MicroStrategy Report Services
Document Creation Guide.
• MicroStrategy In-memory Analytics Guide
Information to use MicroStrategy OLAP Services features, including Intelligent Cubes,
derived metrics, derived elements, dynamic aggregation, view filters, and dynamic
sourcing.
• MicroStrategy Office User Guide
Instructions for using MicroStrategy Office to work with MicroStrategy reports and
documents in Microsoft® Excel, PowerPoint, and Word, to analyze, format, and
distribute business data.
• MicroStrategy Mobile Analysis Guide
Information and instructions for using MicroStrategy Mobile to view and analyze data,
and perform other business tasks with MicroStrategy reports and documents on a
mobile device.
• MicroStrategy Mobile Design and Administration Guide
Information and instructions to install and configure MicroStrategy Mobile, as well as
instructions for a designer working in MicroStrategy Developer or MicroStrategy Web to
create effective reports and documents for use with MicroStrategy Mobile.

14 © 2018, MicroStrategy Inc.

 System Administration Guide

• MicroStrategy System Administration Guide

Concepts and high-level steps to implement, deploy, maintain, tune, and troubleshoot a
MicroStrategy business intelligence system.
• MicroStrategy Supplemental Reference for System Administration
Information and instructions for MicroStrategy administrative tasks such as configuring
VLDB properties and defining data and metadata internationalization, and reference
material for other administrative tasks.
• MicroStrategy Functions Reference
Function syntax and formula components; instructions to use functions in metrics, filters,
attribute forms; examples of functions in business scenarios.
• MicroStrategy MDX Cube Reporting Guide
Information to integrate MicroStrategy with MDX cube sources. You can integrate data
from MDX cube sources into your MicroStrategy projects and applications.

Manuals for Analytics Modules

• Manual for the Human Resources Analytics Module
• Human Resources Analytics Module Reference

Software Development Kits

• MicroStrategy Developer Library (MSDL)
Information to understand the MicroStrategy SDK, including details about architecture,
object models, customization scenarios, code samples, and so on.
• MicroStrategy Web SDK

The Web SDK is available in the MicroStrategy Developer Library, which is part of the
MicroStrategy SDK

Documentation for MicroStrategy Portlets

• Enterprise Portal Integration Help
Information to help you implement and deploy MicroStrategy BI within your enterprise
portal, including instructions for installing and configuring out-of-the-box MicroStrategy
Portlets for several major enterprise portal servers.

© 2018, MicroStrategy Inc. 15

System Administration Guide

Help
Each MicroStrategy product includes an integrated help system to complement the various
interfaces of the product as well as the tasks that can be accomplished using the product.
Some of the MicroStrategy help systems require a web browser to be viewed. For supported
web browsers, see the MicroStrategy Readme.
MicroStrategy provides several ways to access help:
• Help button: Use the Help button or ? (question mark) icon on most software windows to
see help for that window.
• Help menu: From the Help menu or link at the top of any screen, select MicroStrategy
Help to see the table of contents, the Search field, and the index for the help system.
• F1 key: Press F1 to see context-sensitive help that describes each option in the software
window you are currently viewing.

For MicroStrategy Web, MicroStrategy Web Administrator, and MicroStrategy Mobile Server,
pressing the F1 key opens the context-sensitive help for the web browser you are using to
access these MicroStrategy interfaces. Use the Help menu or ? (question mark) icon to
access help for these MicroStrategy interfaces.

Accessing manuals and other documentation sources

The manuals are available here as well as from the machine where MicroStrategy was
installed.

Adobe Acrobat Reader is required to view these manuals. If you do not have Acrobat Reader
installed on your computer, you can download it here.

The best place for all users to begin is with the MicroStrategy Basic Reporting Guide.

To access documentation resources on Windows

1 In Windows, choose Start > Programs (or All Programs) > MicroStrategy
Documentation > Product Manuals.
2 Click the link for the desired manual or other documentation source.
3 If you click the link for the Narrowcast Services SDK Guide, a File Download dialog box
opens. This documentation resource must be downloaded. Select Open this file
from its current location, and click OK.

If bookmarks are not visible on the left side of an Acrobat (PDF) manual, from the View
menu click Bookmarks and Page. This step varies slightly depending on your version of
Adobe Acrobat Reader.

16 © 2018, MicroStrategy Inc.

 System Administration Guide

To access documentation resources on UNIX and Linux

1 Within your UNIX or Linux machine, navigate to the directory where you installed
MicroStrategy. The default location is /opt/MicroStrategy, or
$HOME/MicroStrategy/install if you do not have write access to
/opt/MicroStrategy.
2 From the MicroStrategy installation directory, open the Help folder.
3 Open the Product_Manuals.htm file in a web browser. A page opens in your
browser showing a list of available manuals in PDF format and other documentation
sources.
4 Click the link for the desired manual or other documentation source.
5 If you click the link for the Narrowcast Services SDK Guide, a File Download dialog box
opens. This documentation resource must be downloaded. Select Open this file
from its current location, and click OK.

If bookmarks are not visible on the left side of an Acrobat (PDF) manual, from the View
menu click Bookmarks and Page. This step varies slightly depending on your version of
Adobe Acrobat Reader.

Documentation standards
MicroStrategy online help and PDF manuals (available both online and in printed format) use
standards to help you identify certain types of content. The following table lists these
standards.

These standards may differ depending on the language of this manual; some languages have
rules that supersede the table below.

Type Indicates

bold • Button names, check boxes, options, lists, and menus that are the focus of actions
or part of a list of such GUI elements and their definitions
Example: Click Select Warehouse .
italic • Names of other product manuals and documentation resources
• When part of a command syntax, indicates variable information to be replaced by
the user
Example: The aggregation level is the level of calculation for the metric.
Example: Type copy c:\filename d:\foldername\filename

Courier • Calculations
font • Code samples

© 2018, MicroStrategy Inc. 17

System Administration Guide

Type Indicates

• Registry keys
• Path and file names
• URLs
• Messages displayed in the screen
• Text to be entered by the user
Example: Sum(revenue)/number of months.

Example: Type cmdmgr -f scriptfile.scp and press Enter.

+ A keyboard command that calls for the use of more than one key (for example,
SHIFT+F1).
A note icon indicates helpful information for specific situations.

A warning icon alerts you to important information such as potential security risks;
these should be read before continuing.

18 © 2018, MicroStrategy Inc.

 1
Introduction to MicroStrategy System
Administration
This section summarizes the major components in the MicroStrategy system architecture
and provides a brief overview of some of the basic concepts you need to understand to
administer a MicroStrategy system.
The following are discussed:

Best practices for MicroStrategy system administration

MicroStrategy recommends the following best practices to keep your system running
smoothly and efficiently:
l Use the project life cycle of development, testing, production to fully test your reports,
metrics, and other objects before releasing them to users.
l If you need to delegate administrative responsibilities among several people, you can
create separate security roles for each type of administrator and assign those roles to the
appropriate users. MicroStrategy comes with a number of predefined administrative
security roles for this purpose. For more information about these security roles, see
Defining sets of privileges: Security roles, page 84. For an introduction to the
MicroStrategy security model, including users and privileges, see Chapter , Setting Up
User Security.
l Once Intelligence Server is up and running, you can adjust its governing settings to better
suit your environment. For detailed information about these settings, see Chapter , Tuning
Your System for Best Performance.

You can use Enterprise Manager to monitor various aspects of Intelligence Server’s
performance. Enterprise Manager is a MicroStrategy project that uses the Intelligence
Server statistics database as its data warehouse. For information , see the Enterprise
Manager Guide.

l If you have multiple machines available to run Intelligence Server, you can cluster those
machines to improve performance and reliability. See Chapter , Clustering Multiple
MicroStrategy Servers.
l Create caches for commonly used reports and documents to reduce the database load

© 2018, MicroStrategy Inc. 19

System Administration Guide

and improve the system response time. See Chapter , Improving Report and Document
Response Time: Caching.

Creating reports based on Intelligent Cubes can also greatly speed up the processing time
for reports. Intelligent Cubes are part of the OLAP Services features in Intelligence Server.
See Chapter , Managing Intelligent Cubes.

l Schedule administrative tasks and reports to run during off-peak hours, so that they do not
adversely affect system performance. See Chapter , Scheduling Jobs and Administrative
Tasks

You can automate the delivery of reports and documents to users with the Distribution
Services add-on to Intelligence Server. See Overview of Distribution Services, page 529.

Understanding the MicroStrategy architecture

A MicroStrategy system is built around a three-tier or four-tier structure. The diagram below
illustrates a four-tier system.

l The first tier, at the bottom, consists of two databases: the data warehouse, which
contains the information that your users analyze; and the MicroStrategy metadata, which
contains information about your MicroStrategy projects. For an introduction to these
databases, see Storing information: the data warehouse and Indexing your data:
MicroStrategy metadata.
l The second tier consists of MicroStrategy Intelligence Server, which executes your
reports against the data warehouse. For an introduction to Intelligence Server, see
Processing your data: Intelligence Server.

If MicroStrategy Developer users connect via a two-tier project source (also called a direct
connection), they can access the data warehouse without Intelligence Server. For more

20 © 2018, MicroStrategy Inc.

 System Administration Guide

information on two-tier project sources, see Tying it all together: projects and project
sources.

l The third tier in this system is MicroStrategy Web or Mobile Server, which delivers the
reports to a client. For an introduction to MicroStrategy Web, see Chapter , Administering
MicroStrategy Web and Mobile.
l The last tier is the MicroStrategy Web client or MicroStrategy Mobile app, which provides
documents and reports to the users.

In a three-tier system, Developer is the last tier.

Storing information: the data warehouse

The data warehouse is the foundation that your MicroStrategy system is built on. It stores all
the information you and your users analyze with the MicroStrategy system. This information
is usually placed or loaded in the data warehouse using some sort of extraction,
transformation, and loading (ETL) process. Your online transaction processing (OLTP)
system is usually the main source of original data used by the ETL process.
As a system administrator, you need to know which relational database management
system (RDBMS) manages your data warehouse, how the MicroStrategy system accesses
it (which machine it is on and which ODBC driver and Data Source Name it uses to connect
to it), and what should happen when the data warehouse is loaded (such as running scripts
to invalidate certain caches in Intelligence Server, and so on). These are all discussed later in
this guide.

Indexing your data: MicroStrategy metadata

MicroStrategy metadata is like a road map or an index to the information that is stored in your
data warehouse. The MicroStrategy system uses the metadata to know where in the data
warehouse it should look for information. It also stores other types of objects that allow you to
access that information. These are discussed below.
The metadata resides in a database, the metadata repository, that is separate from your
data warehouse. This can be initially created when you run through the MicroStrategy
Configuration Wizard. All the metadata information is encrypted and stored in database
tables defined by MicroStrategy.

For more information about running the MicroStrategy Configuration Wizard, see the
Installation and Configuration Guide.

To help explain how the MicroStrategy system uses the metadata to do its work, imagine that
a user runs a report with a total of revenue for a certain region in a quarter of the year. The
metadata stores information about how the revenue metric is to be calculated, information
about which rows and tables in the data warehouse to use for the region, and the most
efficient way to retrieve the information.
The physical warehouse schema is a type of conceptual tool that is crucial for you to visualize
information’s location in the data warehouse. This includes table and column information

© 2018, MicroStrategy Inc. 21

System Administration Guide

about where things are actually stored as well as maps, such as lookup and relate tables,
that help the system efficiently access that information. Persons who create the schema
objects in the MicroStrategy metadata must reference the physical warehouse schema.
Therefore, it is not actually stored in a location in the metadata, but it is implicitly present in
the definition of the schema objects in the metadata.

The role of the physical warehouse schema is further explained in the Basic Reporting Guide.

In addition to the physical warehouse schema’s implicit presence in the metadata, the
following types of objects are stored in the metadata:
l Schema objects are objects created, usually by a project designer or architect, based on
the logical and physical models. Facts, attributes, and hierarchies are examples of
schema objects. These objects are developed in MicroStrategy Architect, which can be
accessed from MicroStrategy Developer. The Project Design Guide is devoted to
explaining schema objects.
l Application objects are the objects that are necessary to run reports. These objects are
generally created by a report designer and can include reports, report templates, filters,
metrics, prompts, and so on. These objects are built in Developer or Command Manager.
The Basic Reporting Guide and Advanced Reporting Guide are devoted to explaining
application objects.
l Configuration objects are administrative and connectivity-related objects. They are
managed in Developer (or Command Manager) by an administrator changing the
Intelligence Server configuration or project configuration. Examples of configuration
objects include users, groups, server definitions and so on.

Processing your data: Intelligence Server

Intelligence Server is the second tier in the MicroStrategy system. Intelligence Server must
be running for users to get information from the data warehouse using MicroStrategy clients,
such as MicroStrategy Web or Developer.
Intelligence Server is the heart of the MicroStrategy system. It executes reports stored in the
metadata against the data warehouse and passes the results of the reports to users. For
detailed information about Intelligence Server, including how to start and stop it, see
Managing Intelligence Server, page 29.
A server definition is an instance of Intelligence Server and its configuration settings. Multiple
server definitions can be stored in the metadata, but only one can be run at a time on a
machine. If you want multiple machines to point to the same metadata, you should cluster
them. For more information about clustering, including instructions on how to cluster
Intelligence Servers, see Chapter , Clustering Multiple MicroStrategy Servers.

Pointing multiple Intelligence Servers to the same metadata without clustering may cause
metadata inconsistencies. This configuration is not supported, and MicroStrategy strongly
recommends that users not configure their systems in this way.

The server definition information includes the following:

22 © 2018, MicroStrategy Inc.

 System Administration Guide

l Metadata connectivity information, such as:

l Metadata DSN
l Metadata ID and encrypted password
l MicroStrategy administrator user name
l Intelligence Server configuration settings—set in Developer

Tying it all together: projects and project sources

A MicroStrategy project is an object in which you define all the schema and application
objects, which together provide for a flexible reporting environment. A project’s metadata
repository is established by the project source in which you construct the project. The
project’s data warehouse is specified by associating the project with the appropriate
database instance. For detailed information about projects, including instructions on how to
create a project, see the Project Design Guide.
You can manage your projects using the System Administration Monitor. For details, see
Managing and monitoring projects, page 41.
A project source is a container stored in Developer that defines how Developer accesses the
metadata repository. Think of a project source as a pointer to one or more projects that are
stored in a metadata repository.
Two types of project sources can be created, defined by the type of connection they
represent:
l Server connection, or three-tier, which specifies the Intelligence Server to connect to.
l Direct connection, or two-tier, which bypasses Intelligence Server and allows Developer
to connect directly to the MicroStrategy metadata and data warehouse. Note that this is
primarily for project design and testing. Because this type of connection bypasses
Intelligence Server, important benefits such as caching and governing, which help protect
the system from being overloaded, are not available.

In older systems you may encounter a 6.x Project connection (also two-tier) that
connects directly to a MicroStrategy version 6 project in read-only mode.

For more information on project sources, see the Installation and Configuration Guide.

Communicating with databases

To successfully configure your system, you must establish connections to the MicroStrategy
metadata and to the data warehouse that contains the business information on which you
will report. These procedures are explained in the Installation and Configuration Guide.
While the MicroStrategy Configuration Wizard sets up some of these connections for you
automatically when you first install and configure your MicroStrategy software, you may
need to further fine-tune them. For instructions on how to manage your database
connections, see Monitoring database instance connections, page 26.

© 2018, MicroStrategy Inc. 23

System Administration Guide

Connecting to the MicroStrategy metadata

MicroStrategy users need connectivity to the metadata so that they can access projects,
create objects, and execute reports. Intelligence Server connects to the metadata by reading
the server definition registry when it starts. However, this connection is only one segment of
the connectivity picture.
Consider these questions:
l How does a Developer user access the metadata?
l How does a user connect to Intelligence Server?
l Where is the connection information stored?
The diagram below illustrates three-tier metadata connectivity between the MicroStrategy
metadata database (tier one), Intelligence Server (tier two), and Developer (tier three).

In a server (three-tier) environment, Developer metadata connectivity is established through

the project source. For steps to create a project source, see the Installation and
Configuration Guide.

24 © 2018, MicroStrategy Inc.

 System Administration Guide

You can also create and edit a project source using the Project Source Manager in
Developer. When you use the Project Source Manager, you must specify the Intelligence
Server machine to which to connect. It is through this connection that Developer users
retrieve metadata information.

The Developer connection information is stored in the Developer machine registry.

Connecting to the data warehouse

Once you establish a connection to the metadata, you must create a connection to the data
warehouse. This is generally performed during initial software installation and configuration,
but it can also be established with the following procedures in Developer:
l Creating a database instance: A MicroStrategy object created in Developer that
represents a connection to the data warehouse. A database instance specifies
warehouse connection information such as the data warehouse DSN, Login ID and
password, and other data warehouse-specific information.
l Creating a database connection: Specifies the DSN and database login used to access
the data warehouse. A database instance designates one database connection as the
default connection for MicroStrategy users.
l Creating a database login: Specifies the user ID and password used to access the data
warehouse. The database login overwrites any login information stored in the DSN.

© 2018, MicroStrategy Inc. 25

System Administration Guide

l User connection mapping: The process of mapping MicroStrategy users to database

connections and database logins. To execute reports, MicroStrategy users must be
mapped to a database connection and login.
For procedures to connect to the data warehouse, see the Installation and Configuration
Guide.

Caching database connections

Connecting to and disconnecting from databases incurs a small amount of overhead that
may cause a small yet noticeable decrease in performance in high-concurrency systems.
With connection caching, Intelligence Server is able to reuse database connections. This
minimizes the overhead associated with repeatedly connecting to and disconnecting from
databases.
Connections can exist in one of two states:
l Busy: connections that are actively submitting a query to a database
l Cached: connections that are still connected to a database but not actively submitting a
query to a database
A cached connection is used for a job if the following criteria are satisfied:
l The connection string for the cached connection matches the connection string that will be
used for the job.
l The driver mode (multiprocess versus multithreaded) for the cached connection matches
the driver mode that will be used for the job.

Intelligence Server does not cache any connections that have pre- or post-SQL statements
associated with them because these options may drastically alter the state of the connection.

Monitoring database instance connections

A warehouse database connection is initiated any time a user executes an uncached report
or browses uncached elements. The Database Connection Monitor enables you to view the
number of busy and cached connections to the data warehouse. You can also view the
name of the database instance, the user who is using the connection, and the database login
being used to connect to the database.
If a database connection is cached, the ODBC connection from Intelligence Server to the
data warehouse remains open. However, if the data warehouse connection surpasses the
connection time-out or lifetime governors (set in the Database Connections dialog box, on
the Advanced tab), the ODBC connection closes, and it no longer displays in the Database
Connection Monitor.

26 © 2018, MicroStrategy Inc.

 System Administration Guide

To view the current database connections

1. In Developer, log in to a project source. You must log in as a user with the Monitor
Database Connections privilege.
2. Expand Administration, then expand System Monitors, and then select
Database Connections. The database connection information displays on the
right-hand side.

To delete a database connection

In the Database Connection Monitor, right-click the connection and select Disconnect.

Benefiting from centralized database access control

All database connectivity is handled by Intelligence Server, which provides centralized
control of database access. The advantages of centralized control include:
l Connectionless client—All connections to databases in the system are made through
Intelligence Server. This means that only the Intelligence Server machine needs to have
database connectivity. It also eliminates the need to rely on identically configured
connections on client and server computers. This makes it easy to set up, deploy, and
manage large systems.
l Connection caching—Connecting to and disconnecting from databases incurs a small
amount of overhead that may cause a small, yet noticeable, decrease in performance in
high-concurrency systems. With connection caching, Intelligence Server is able to reuse
database connections. This minimizes the overhead associated with repeated connecting
to and disconnecting from databases.
l Workload governing—Because only Intelligence Server connects to databases, it can
make sure that no one database becomes overloaded with user requests. This is
especially important for the data warehouse.
l User connection mapping—Intelligence Server can map MicroStrategy users and user
groups to data warehouse login IDs. This allows multiple users to access the database
using a single database login.
l Ease of administration/monitoring—Because all database connectivity is handled by
Intelligence Server, keeping track of all connections to all databases in the system is easy.
l Prioritized access to databases—You can set access priority by user, project, estimated
job cost, or any combination of these.
l Multiprocess execution—The ability to run in multiprocess mode means that if one
process fails, such as a lost or hung database access thread, the others are not affected.
l Database optimizations—Using VLDB properties, Intelligence Server is able to take
advantage of the unique performance optimizations that different database servers offer.

© 2018, MicroStrategy Inc. 27

System Administration Guide

Updating VLDB properties for ODBC connections

VLDB properties allow Intelligence Server to take advantage of the unique optimizations that
different databases offer. Depending on the database type, these properties can affect how
Intelligence Server handles things like:
l Join options, such as the star join and full outer join
l Metric calculation options, such as when to check for NULLs and zeros
l Pre- and post-SQL statements
l Query optimizations, such as sub-queries and driving tables
l Table types, such as temporary tables or derived tables
For more information about all the VLDB properties, see SQL Generation and Data
Processing: VLDB Properties.

Upgrading your database type properties

Default VLDB properties are set according to the database type specified in the database
instance. MicroStrategy periodically updates the default settings as database vendors add
new functionality.
When you create the metadata for a MicroStrategy project, the database-specific
information is loaded from a file supplied by MicroStrategy (called Database.pds). If you
get a new release from MicroStrategy, the metadata is automatically upgraded using the
Database.pds file with the metadata update process. The Administrator is the only user
who can upgrade the metadata. Do this by clicking Yes when prompted for updating the
metadata. This happens when you connect to an existing project after installing a new
MicroStrategy release.

The MicroStrategy system cannot detect when you upgrade or change the database used to
store the MicroStrategy metadata or your data warehouse. If you upgrade or change the
database that is used to store the metadata or data warehouse, you can manually update the
database type to apply the default properties for the new database type.

When the you update the database type information, this process:
l Loads newly supported database types. For example, properties for the newest database
servers that were recently added.
l Loads updated properties for existing database types that are still supported.
l Keeps properties for existing database types that are no longer supported. If there were
no updates for an existing database type, but the properties for it have been removed from
the Database.pds file, the process does not remove them from your metadata.

In some cases, MicroStrategy no longer updates certain DBMS objects as newer versions
are released. These are not normally removed. However, in the case of Oracle 8i R2 and
Oracle 8i R3, the DBMS objects were merged into “Oracle 8i R2/R3” for both Standard and
Enterprise editions because Oracle 8i R3 is no longer being updated. You may need to select
the merged version as part of your database instance if you are using a version of Oracle 8i.

28 © 2018, MicroStrategy Inc.

 System Administration Guide

This will become apparent if date/time functions stop working, particularly in Enterprise
Manager.

For more information about VLDB properties, see SQL Generation and Data Processing:
VLDB Properties.
You may need to manually upgrade the database types if you chose not to run the update
metadata process after installing a new release.

To manually upgrade the database type properties

1. In the Database Instance editor, click the General tab.

2. Select Upgrade.
For more detailed information about manually upgrading VLDB properties, functions, and
SQL syntax for your database server, see the MicroStrategy Developer Help.

The Readme lists all DBMSs that are supported or certified for use with MicroStrategy.

Managing Intelligence Server

This section introduces you to basic Intelligence Server operation, including starting and
stopping Intelligence Server and running it as a service or as an application.
You can improve your system and database performance by adjusting various Intelligence
Server governing settings to fit your system parameters and your reporting needs. For
detailed information about these settings, see Chapter , Tuning Your System for Best
Performance.

What happens when Intelligence Server starts?

Once a server definition is defined and selected for Intelligence Server using the
Configuration Wizard, the metadata connection information specified in the server definition
is saved in the machine’s registry. When Intelligence Server starts, it reads this information to
identify the metadata to which it will connect.
The portion of server definition information that is stored in the machine’s registry includes
the server definition name, the DSN pointing to the metadata, and the metadata ID and
encrypted password. For more information on server definitions, see the Installation and
Configuration Guide.
When Intelligence Server starts, it does the following:
l Initializes internal processing units
l Reads from the machine registry which server definition it is supposed to use and
connects to the specified metadata database
l Loads configuration and schema information for each loaded project

© 2018, MicroStrategy Inc. 29

System Administration Guide

l Loads existing report cache files from automatic backup files into memory for each loaded
project (up to the specified maximum RAM setting)

This occurs only if report caching is enabled and the Load caches on startup feature is
enabled.

l Loads schedules
l Loads MDX cube schemas

You can set Intelligence Server to load MDX cube schemas when it starts, rather than
loading MDX cube schemas upon running an MDX cube report. For more details on this
and steps to load MDX cube schemas when Intelligence Server starts, see the Configuring
and Connecting Intelligence Server section of the Installation and Configuration Guide.

If a system or power failure occurs, Intelligence Server cannot capture its current state. The
next time the server is started, it loads the state information, caches, and History Lists that
were saved in the last automatic backup. (The automatic backup frequency is set using the
Intelligence Server Configuration Editor.) The server does not re-execute any job that was
running until the person requesting the job logs in again.

What happens when Intelligence Server stops?

When you initiate an Intelligence Server shutdown, it:
l Writes cache and History List information to backup files
l Cancels currently executing jobs

The user who submitted a canceled job sees a message in the History List indicating that
there was an error. The user must resubmit the job.

l Closes database connections

l Logs out connected users from the system
l Removes itself from the cluster (if it was in a cluster)

It does not rejoin the cluster automatically when restarted.

As noted earlier, if a system or power failure occurs, these actions cannot be done. Instead,
Intelligence Server recovers its state from the latest automatic backup.

Running Intelligence Server as an application or a service

Intelligence Server can be started as a Windows service or as an application. If you run
Intelligence Server as a service, you can start and stop it from a remote machine with
Developer or by logging into the Intelligence Server machine remotely. In addition, you can
configure the service to start automatically when the machine on which it is installed starts.
For more information about running Intelligence Server as a service, see Starting and
stopping Intelligence Server as a service, page 31.

30 © 2018, MicroStrategy Inc.

 System Administration Guide

On rare occasions you may need to run Intelligence Server as an application. This includes
occasions when you need precise control over when Intelligence Server stops and starts or
when you need to change certain advanced tuning settings that are not available when
Intelligence Server is running as a service. For more information about running Intelligence
Server as an application, see Starting Intelligence Server as an application, page 36.

Registering and unregistering Intelligence Server as a UNIX service

In UNIX, when you configure Intelligence Server you must specify that it starts as an
application or a service. If you want to start Intelligence Server as a service, you must
register it as a service with the system. In addition, in UNIX, if you want to start Intelligence
Server as a service after having started it as an application, you must register it as a service.

To register or unregister Intelligence Server as a service in UNIX, you must be logged in to

the Intelligence Server machine with root privileges.

You can register Intelligence Server as a service in two ways:

l From the Configuration Wizard: on the Specify a Port Number page, ensure that the
Register Intelligence Server as a Service check box is selected.
l From the command line: in ~/MicroStrategy/bin enter:
mstrctl -s IntelligenceServer rs
If you want to start Intelligence Server as an application after having registered it as a
service, you need to unregister it. Unregistering the service can be done only from the
command line, in ~/MicroStrategy/bin. The syntax to unregister the service is:
mstrctl -s IntelligenceServer us

Starting and stopping Intelligence Server as a service

Once the service is started, it is designed to run constantly, even after the user who started it
logs off the system. However, you may need to stop and restart it for these reasons:
l Routine maintenance on the Intelligence Server machine
l Changes to Intelligence Server configuration options that cannot be changed while
Intelligence Server is running
l Potential power outages due to storms or planned building maintenance
You can start and stop Intelligence Server manually as a service using any of the following
methods:
l MicroStrategy Service Manager is a management application that can run in the
background on the Intelligence Server machine. It is often the most convenient way to
start and stop Intelligence Server. For instructions, see Service Manager, page 32.
l If you are already using Developer, you may need to start and stop Intelligence Server
from within Developer. For instructions, see Developer, page 34.

© 2018, MicroStrategy Inc. 31

System Administration Guide

l You can start and stop Intelligence Server as part of a Command Manager script. For
details, see Command Manager, page 34.
l Finally, you can start and stop Intelligence Server from the command line using
MicroStrategy Server Control Utility. For instructions, see Command line, page 35.

Prerequisites for starting and stopping Intelligence Server

l You must have the Configuration access permission for the server definition object. For
information about object permissions in MicroStrategy, see Controlling access to objects:
Permissions, page 73. For a list of the permission groupings for server definition objects,
see Controlling access to objects: Permissions, page 73.
l To remotely start and stop the Intelligence Server service in Windows, you must be logged
in to the remote machine as a Windows user with administrative privileges.

Service Manager
Service Manager is a management tool installed with Intelligence Server that enables you to
start and stop Intelligence Server and choose a startup option. Service Manager allows you
to start, stop, and manage the following services:
l MicroStrategy Intelligence Server
l MicroStrategy Listener
l MicroStrategy Distribution Manager
l MicroStrategy Execution Engine
l MicroStrategy Enterprise Manager Data Loader
l MicroStrategy Collaboration Service
l MicroStrategy PDF Exporter
For instructions on how to use Service Manager, click Help from within Service Manager.

Service Manager requires that port 8888 be open. If this port is not open, contact your network
administrator.

To open MicroStrategy Service Manager in Windows

1. In the system tray of the Windows task bar, double-click the MicroStrategy Service
Manager icon, or .

2. If the icon is not present in the system tray, then from the Windows Start menu, point
to All Programs, then MicroStrategy Tools, then select Service Manager.

32 © 2018, MicroStrategy Inc.

 System Administration Guide

To open MicroStrategy Service Manager in UNIX

In UNIX, Service Manager requires an X-Windows environment.

1. Browse to the folder specified as the home directory during MicroStrategy installation
(the default is ~/MicroStrategy), then browse to /bin.
2. Type ./mstrsvcmgr and press ENTER.

Using the Listener/Restarter to start Intelligence Server

You can configure Intelligence Server to start automatically when the Intelligence Server
machine starts. You can also configure the Restarter to restart the Intelligence Server
service automatically if it fails, but the machine on which it is installed is still running. To do
this, you must have the MicroStrategy Listener service running.

To start a MicroStrategy service automatically when the machine

restarts

1. From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, then select Service Manager.

© 2018, MicroStrategy Inc. 33

System Administration Guide

2. In the Server drop-down list, select the name of the machine on which the service is
installed.
3. In the Service drop-down list, select the service.
4. Click Options.
5. Select Automatic as the Startup Type option.
6. Click OK.

You can also set this using the Services option in the Microsoft Window’s Control
Panel.

To start Intelligence Server service automatically when it fails

unexpectedly

The MicroStrategy Listener service must be running for the Re-starter feature to work.

1. From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, then select Service Manager.
2. In the Server drop-down list, select the machine on which the Intelligence Server
service is installed.
3. In the Service drop-down list, select MicroStrategy Intelligence Server.
4. Click Options.
5. On the Intelligence Server Options tab, select the Enabled check box for the Re-
starter Option.

Developer
You can start and stop a local Intelligence Server from Developer. You cannot start or stop a
remote Intelligence Server from Developer; you must use one of the other methods to start
or stop a remote Intelligence Server.

To start or stop Intelligence Server using Developer

1. In Developer, in the Folder List, right-click the Administration icon.

2. Choose Start Server to start it or Stop Server to stop it.

Command Manager
Command Manager is a script-based tool that enables you to perform various administrative
and maintenance tasks with reusable scripts. You can start and stop Intelligence Server
using Command Manager.

34 © 2018, MicroStrategy Inc.

 System Administration Guide

For the Command Manager syntax for starting and stopping Intelligence Server, see the
Command Manager Help (press F1 from within Command Manager). For a more general
introduction to MicroStrategy Command Manager, see Chapter , Automating Administrative
Tasks with Command Manager.

Command line
You can start and stop Intelligence Server from a command prompt, using the MicroStrategy
Server Control Utility. This utility is invoked by the command mstrctl. By default the utility
is in C:\Program Files (x86)\Common Files\MicroStrategy\ in Windows,
and in ~/MicroStrategy/bin in UNIX.
The syntax to start the service is:
mstrctl -s IntelligenceServer start --service
The syntax to stop the service is:
mstrctl -s IntelligenceServer stop
For detailed instructions on how to use the Server Control Utility, see Managing
MicroStrategy services from the command line, page 37.

Windows Services window

You can start and stop Intelligence Server and choose a startup option using the Windows
Services window.

To start and stop Intelligence Server using the Windows Services

window

1. On the Windows Start menu, point to Settings, then choose Control Panel.
2. Double-click Administrative Tools, and then double-click Services.
3. From the Services list, select MicroStrategy Intelligence Server.
4. You can do any of the following:
l To start the service, click Start.
l To stop the service, click Stop.
l To change the startup type, select a startup option from the drop-down list.
l Automatic means that the service starts when the computer starts.
l Manual means that you must start the service manually.
l Disabled means that you cannot start the service until you change the startup
type to one of the other types.
5. Click OK.

© 2018, MicroStrategy Inc. 35

System Administration Guide

Starting Intelligence Server as an application

While the need to do so is rare, you can start Intelligence Server as an application. This may
be necessary if you must administer Intelligence Server on the machine on which it is
installed, if Developer is not installed on that machine.
Some advanced tuning settings are only available when starting Intelligence Server as a
service. If you change these settings, they are applied the next time Intelligence Server is
started as a service.

MicroStrategy recommends that you not change these settings unless requested to do so by
a MicroStrategy Technical Support associate.

There are some limitations to running Intelligence Server as an application:

l The user who starts Intelligence Server as an application must remain logged on to the
machine for Intelligence Server to keep running. When the user logs off, Intelligence
Server stops.
l If Intelligence Server is started as an application, you cannot administer it remotely. You
can administer it only by logging in to the Intelligence Server machine.
l The application does not automatically restart if it fails.

In UNIX, if Intelligence Server has previously been configured to run as a service, you
must unregister it as a service before you can run it as an application. For instructions on
unregistering Intelligence Server as a service, see Registering and unregistering
Intelligence Server as a UNIX service, page 31.

The default path for the Intelligence Server application executable is C:\Program Files
(x86)\MicroStrategy\Intelligence Server\MSTRSvr.exe in Windows, and
~/MicroStrategy/bin in UNIX.
Executing this file from the command line displays the following administration menu in
Windows, and a similar menu in UNIX.

36 © 2018, MicroStrategy Inc.

 System Administration Guide

To use these options, type the corresponding letter on the command line and press Enter.
For example, to monitor users, type U and press Enter. The information is displayed.

Managing MicroStrategy services from the command line

MicroStrategy Server Control Utility enables you to create and manage Intelligence Server
server instances from the command line. A server instance is an Intelligence Server that is
using a particular server definition. For more information about server definitions, see
Processing your data: Intelligence Server.
Server Control Utility can also be used to start, stop, and restart other MicroStrategy
services—such as the Listener, Distribution Manager, Execution Engine, or Enterprise
Manager Data Loader services—and to view and set configuration information for those
services.
The following table lists the commands that you can perform with the Server Control Utility.
The syntax for using the Server Control Utility commands is:
mstrctl -m machinename [-l login] -s servicename
command [instancename]
[(> | <) filename.xml]
where:
l machinename is the name of the machine hosting the server instance or service. If this
parameter is omitted, the service is assumed to be hosted on the local machine.
l login is the login for the machine hosting the server instance or service, and is required if
you are not logged into that machine. You are prompted for a password.
l servicename is the name of the service, such as IntelligenceServer or EMService.

To retrieve a list of services on a machine, use the command mstrctl -m

machinename ls.

l command is one of the commands from the list below.

l instancename is the name of a server instance, where required. If a name is not
specified, the command uses the default instance name.
l filename is the name of the file to read from or write to.

If you want to. . . Then use this command.

..

Get information about the Server Control Utility

List all commands for the Server Control Utility. -h

This command does not require a machine name, login, or service name. --help

Display the version number of the Server Control Utility. -V

© 2018, MicroStrategy Inc. 37

System Administration Guide

If you want to. . . Then use this command.

..

--version
This command does not require a machine name, login, or service name.

Get information about the MicroStrategy network

List machines that the Server Control Utility can see and affect. lm

This command does not require a machine name, login, or service name.
list-machines

List the MicroStrategy services available on a machine. ls

This command does not require a service name. list-servers

List the ODBC DSNs available on a machine. lod

This command does not require a service name. list-odbc-dsn

Configure a service

Display the configuration information for a service, in XML format. For more gsvc
information, see Using files to store output and provide input, page 27. instancename [>
filename.xml]
You can optionally specify a file to save the configuration properties to.
get-service-
configuration
instancename [>
filename.xml]

Specify the configuration information for a service, in XML format. For more ssvc
information, see Using files to store output and provide input, page 27. instancename [<
filename.xml]
You can optionally specify a file to read the configuration properties from.
set-service-
configuration
instancename [<
filename.xml]
Configure a server

Display the configuration properties of a server, in XML format. For more gsc [>
information, see Using files to store output and provide input, page 27. filename.xml]

You can optionally specify a file to save the configuration properties to. get-server-
configuration
[>
filename.xml]

Specify the configuration properties of a server, in XML format. For more ssc [<
information, see Using files to store output and provide input, page 27.

38 © 2018, MicroStrategy Inc.

 System Administration Guide

If you want to. . . Then use this command.

..

filename.xml]
You can optionally specify a file to read the configuration properties from.
set-server-
configuration
[<
filename.xml]
Configure a server instance

Display the configuration information for a server instance, in XML format. gsic
For more information, see Using files to store output and provide input, instancename [>
page 27.
filename.xml]
You can optionally specify a file to save the configuration properties to. get-server-
instance-
configuration
instancename [>
filename.xml]

Specify the configuration information for a server instance, in XML format. ssic
For more information, see Using files to store output and provide input, instancename
page 27.
set-server-
You can optionally specify a file to read the configuration properties from. instance-
configuration
instancename [<
filename.xml]
Manage server instances

Display the default instance for a service. gdi

get-default-
instance

Set an instance of a service as the default instance. sdi

instancename

set-default-
instance
instancename

Create a new server instance. ci instancename

create-instance
instancename

Create a copy of a server instance. Specify the name for the new instance as cpi
newinstancename. instancename
newinstancename

© 2018, MicroStrategy Inc. 39

System Administration Guide

If you want to. . . Then use this command.

..

copy-instance
instancename
newinstancename

Delete a server instance. di instancename

delete-instance
instancename

Register a server instance as a service. rs instancename

register-
service
instancename

Unregister a registered server instance as a service. us instancename

unregister-
service
instancename

Display the license information for a service instance. gl instancename

get-license
instancename

Display the status information for a server instance gs instancename

get-status
instancename
Start or stop a server instance

Start a server instance as a service. start --service

instancename

Start a server instance as an application. For more information, see Running start --
Intelligence Server as an application or a service, page 30. interactive
instancename

Stop a server instance that has been started as a service. stop

instancename

Pause a server instance that has been started as a. service pause

instancename

Resume a server instance that has been started as a service and paused. resume
instancename

Terminate a server instance that has been started as a service. term

40 © 2018, MicroStrategy Inc.

 System Administration Guide

If you want to. . . Then use this command.

..

instancename

terminate
instancename

Using files to store output and provide input

Certain Server Control Utility commands involve XML definitions. The commands to display
a server configuration, a service configuration, and a server instance configuration all output
an XML definition. The commands to modify a server configuration, a service configuration,
and a server instance configuration all require an XML definition as input.
It is difficult and time consuming to type a complete server, service, or server instance
configuration from the command line. An easier way to configure them is to output the
current configuration to a file, modify the file with a text editor, and then use the file as input to
a command to modify the configuration.

Configuring Intelligence Server with XML files requires extensive knowledge of the various
parameters and values used to define Intelligence Server configurations. Providing an
incorrect XML definition to configure Intelligence Server can cause errors and unexpected
functionality.

For example, the following command saves the default server instance configuration to an
XML file:
mstrctl -s IntelligenceServer
gsic > filename.xml
The server instance configuration is saved in the file filename.xml, in the current
directory.
The following command modifies the default server instance configuration by reading input
from an XML file:
mstrctl -s IntelligenceServer
ssic < filename.xml
The XML definition in ServerInstance.xml is used to define the server instance
configuration.

Managing and monitoring projects

The System Administration Monitor lists all the projects on an Intelligence Server and all the
machines in the cluster that Intelligence Server is using. You can monitor the status of the
projects on a project source, and load, unload, idle, and resume projects for the entire project
source or for a single node of the cluster. You can also schedule various system
maintenance tasks from the Scheduled Maintenance view.
The System Administration group contains the following views:

© 2018, MicroStrategy Inc. 41

System Administration Guide

l Project, which helps you keep track of the status of all the projects contained in the
selected project source. For detailed information, see Managing project status,
configuration, or security: Project view, page 42.
l Cluster, which helps you manage how projects are distributed across the servers in a
cluster. For detailed information, see Managing clustered Intelligence Servers: Cluster
view, page 43.
l The Scheduled Maintenance monitor, which lists all the scheduled maintenance tasks.
For detailed information, see Scheduling administrative tasks, page 514.

Managing project status, configuration, or security: Project view

The Project view helps you keep track of the status of all the projects contained in the
selected project source. It also enables access to a number of project maintenance
interfaces in one place. This makes it faster and easier to perform maintenance tasks such
as purging caches, managing security filters, or loading or unloading projects from
Intelligence Server.

To access the Project view

1. Expand Administration in the project source’s folder list.

2. Expand the System Administration group, and then select Project. The projects
and their statuses display on the right-hand side.

Using the Project view

The Project view lists all the projects in the project source. If your system is set up as a cluster
of servers, the Project Monitor displays all projects in the cluster, including the projects that
are not running on the node from which you are accessing the Project Monitor. For details on
projects in a clustered environment, see Distributing projects across nodes in a cluster, page
419.
To view the status of a project, select the List or Details view, and click the + sign next to
the project’s name. A list of all the servers in the cluster expands below the project’s name.
The status of the project on each server is shown next to the server’s name. If your system is
not clustered, there is only one server in this list.

For projects distributed asymmetrically across nodes of a cluster, a primary server is

assigned to each project. A project’s primary server handles the time-based scheduling for
that project. The primary server is displayed in bold, and Primary Server appears after the
server name.

From the Project view, you can access a number of administrative and maintenance
functions. You can:

42 © 2018, MicroStrategy Inc.

 System Administration Guide

l Manage the users and security filters for a project

l View the change journal for a project (for details, see Monitoring system activity: Change
journaling, page 317)
l Export and print the project’s schema or other project documentation
l Load or unload projects from Intelligence Server, or idle or resume projects for
maintenance (for details, see Setting the status of a project, page 44)

To load a project on a specific server in a cluster, you use the Cluster Monitor. For details
on this procedure, see Managing clustered Intelligence Servers: Cluster view, page 43.

l Purge report, element, or object caches for projects

These tasks are all available by right-clicking a project in the Project Monitor. For more
detailed information about any of these options, see the Help or related sections in this
guide.

You can perform an action on multiple projects at the same time. To do this, select several
projects (CTRL+click), then right-click and select one of the options.

You can also schedule any of these maintenance functions from the Schedule
Administration Tasks dialog box. To access this dialog box, right-click a project in the Project
view and select Schedule Administration Tasks. For more information, including
detailed instructions on scheduling a task, see Scheduling administrative tasks, page 514.

Managing clustered Intelligence Servers: Cluster view

The Cluster view helps you keep track of the status of your clustered Intelligence Servers.
Through the Cluster view, you can view the status of each node, add or remove nodes in the
cluster, and view how projects are distributed across the nodes.

To access the Cluster view

1. Expand Administration in the project source’s folder list.

2. Expand the System Administration group, and then select Cluster. The
projects and their statuses display on the right-hand side.
3. To see a list of all the projects on a node, click the + sign next to that node. The status
of the project on the selected server is shown next to the project’s name.

Using the Cluster view

From the Cluster view, you can access a number of administrative and maintenance
functions. You can:
l Manage the security policy settings for the project source
l Join or leave a cluster

© 2018, MicroStrategy Inc. 43

System Administration Guide

l Manage the change journaling for projects on a cluster

l Purge the object cache for a server
These tasks are all available by right-clicking a server in the Cluster view.
You can also load or unload projects from a machine, or idle or resume projects on a
machine for maintenance (for details, see Setting the status of a project, page 44) by right-
clicking a project on a server. For more detailed information about any of these options, see
the MicroStrategy Developer Help, or see Managing your projects across nodes of a cluster,
page 422.

Setting the status of a project

Each project in Intelligence Server can operate in one of several modes. Project modes
allow for various system administration tasks to occur without interrupting Intelligence Server
operation for other projects. The tasks that are allowed to occur depend on the job or jobs
that are required for that task.
A project’s status can be one of the following:
l Loaded, page 44
l Unloaded, page 44
l Request Idle, page 45
l Execution Idle, page 45
l Warehouse Execution Idle, page 46
l Full Idle, page 46
l Partial Idle, page 46
For instructions on changing a project’s status, see Changing the status of a project, page
47.
For example scenarios where the different project idle modes can help to support project and
data warehouse maintenance tasks, see Project and data warehouse maintenance example
scenarios, page 48.

Loaded
A project in Loaded mode appears as an available project in Developer and MicroStrategy
Web products. In this mode, user requests are accepted and processed as normal.

Unloaded
Unloaded projects are still registered on Intelligence Server, but they do not appear as
available projects in Developer or MicroStrategy Web products, even for administrators.
Nothing can be done in the project until it is loaded again.

44 © 2018, MicroStrategy Inc.

 System Administration Guide

Unloading a project can be helpful when an administrator has changed some project
configuration settings that do not affect run-time execution and are to be applied to the
project at a later time. The administrator can unload the project, and then reload the project
when it is time to apply the project configuration settings.

A project unload request is fully processed only when all executing jobs for the project are
complete.

Request Idle
Request Idle mode helps to achieve a graceful shutdown of the project rather than modifying
a project from Loaded mode directly to Full Idle mode. In this mode, Intelligence Server:
l Stops accepting new user requests from the clients for the project.
l Completes jobs that are already being processed. If a user requested that results be sent
to her History List, the results are available in her History List after the project is resumed.
Setting a project to Request Idle can be helpful to manage server load for projects on
different clusters. For example, in a cluster with two nodes named Node1 and Node2, the
administrator wants to redirect load temporarily to the project on Node2. The administrator
must first set the project on Node1 to Request Idle. This allows existing requests to finish
execution for the project on Node1, and then all new load is handled by the project on
Node2.

Execution Idle
A project in Execution Idle mode is ideal for Intelligence Server maintenance because this
mode restricts users in the project from running any job in Intelligence Server. In this mode,
Intelligence Server:
l Stops executing all new and currently executing jobs and, in most cases, places them in
the job queue. This includes jobs that require SQL to be submitted to the data warehouse
and jobs that are executed in Intelligence Server, such as answering prompts.

If a project is idled while Intelligence Server is in the process of fetching query results from
the data warehouse for a job, that job is canceled instead of being placed in the job queue.
When the project is resumed, if the job was sent to the user’s History List, an error
message is placed in the History List. The user can click the message to resubmit the job
request.

l Allows users to continue to request jobs, but execution is not allowed and the jobs are
placed in the job queue. Jobs in the job queue are displayed as “Waiting for project” in the
Job Monitor. When the project is resumed, Intelligence Server resumes executing the jobs
in the job queue.
This mode allows you to perform maintenance tasks for the project. For example, you can
still view the different project administration monitors, create reports, create attributes,
and so on. However, tasks such as element browsing, exporting, and running reports that
are not cached are not allowed.

© 2018, MicroStrategy Inc. 45

System Administration Guide

Warehouse Execution Idle

A project in Warehouse Execution Idle mode is ideal for data warehouse maintenance
because this mode restricts users in the project from running any SQL against the data
warehouse. In this mode, Intelligence Server:
l Accepts new user requests from clients for the project, but it does not submit any SQL to
the data warehouse.
l Stops any new or currently executing jobs that require SQL to be executed against the
data warehouse and, in most cases, places them in the job queue. These jobs display as
“Waiting for project” in the Job Monitor. When the project is resumed, Intelligence Server
resumes executing the jobs in the job queue.

If a project is idled while Intelligence Server is in the process of fetching query results from
the data warehouse for a job, that job is canceled instead of being placed in the job queue.
When the project is resumed, if the job was sent to the user’s History List, an error
message is placed in the History List. The user can click the message to resubmit the job
request.

l Completes any jobs that do not require SQL to be executed against the data warehouse.
This mode allows you to perform maintenance tasks on the data warehouse while users
continue to access non-database-dependent functionality. For example, users can run
cached reports, but they cannot drill if that drilling requires additional SQL to be submitted
to the data warehouse. Users can also export reports and documents in the project.

Full Idle
Full Idle is a combination of Request Idle and Execution Idle. In this mode, Intelligence
Server does not accept any new user requests and active requests are canceled. When the
project is resumed, Intelligence Server does not resubmit the canceled jobs and it places an
error message in the user’s History List. The user can click the message to resubmit the
request.
This mode allows you to stop all Intelligence Server and data warehouse processing for a
project. However, the project still remains in Intelligence Server memory.

Partial Idle
Partial Idle is a combination of Request Idle and Warehouse Execution Idle. In this mode,
Intelligence Server does not accept any new user requests. Any active requests that require
SQL to be submitted to the data warehouse are queued until the project is resumed. All other
active requests are completed.
This mode allows you to stop all Intelligence Server and data warehouse processing for a
project, while not canceling jobs that do not require any warehouse processing. The project
still remains in Intelligence Server memory.

46 © 2018, MicroStrategy Inc.

 System Administration Guide

Changing the status of a project

To load or unload a project

If the project is running on multiple clustered Intelligence Servers, the project is loaded or
unloaded from all nodes. To load or unload the project from specific nodes, use the Cluster
view instead of the Project view. For detailed instructions, see Using the Cluster view, page
43.

1. In Developer, log in to the project source containing the project.

2. Under that project source, expand Administration, then expand System
Administration, and select Project.
3. Right-click the project, point to Administer Project, and select Load or Unload.
The project is loaded or unloaded. If you are using clustered Intelligence Servers, the
project is loaded or unloaded for all nodes in the cluster.

To idle or resume a project

If the project is running on multiple clustered Intelligence Servers, the project status changes
for all nodes. To idle or resume the project on specific nodes, use the Cluster view instead
of the Project view. For detailed instructions, see Using the Cluster view, page 43.

1. In Developer, log in to the project source containing the project.

2. Under that project source, expand Administration, then expand System
Administration, and then select Project.
3. Right-click the project, point to Administer Project, and select Idle/Resume.

4. Select the options for the idle mode that you want to set the project to:

© 2018, MicroStrategy Inc. 47

System Administration Guide

l Request Idle (Request Idle): all executing and queued jobs finish executing, and
any newly submitted jobs are rejected.
l Execution Idle (Execution Idle for All Jobs): all executing, queued, and newly
submitted jobs are placed in the queue, to be executed when the project resumes.
l Warehouse Execution Idle (Execution Idle for Warehouse jobs): all
executing, queued, and newly submitted jobs that require SQL to be submitted to
the data warehouse are placed in the queue, to be executed when the project
resumes. Any jobs that do not require SQL to be executed against the data
warehouse are executed.
l Full Idle (Request Idle and Execution Idle for All jobs): all executing and
queued jobs are canceled, and any newly submitted jobs are rejected.
l Partial Idle (Request Idle and Execution Idle for Warehouse jobs): all
executing and queued jobs that do not submit SQL against the data warehouse are
canceled, and any newly submitted jobs are rejected. Any currently executing and
queued jobs that do not require SQL to be executed against the data warehouse
are executed.

To resume the project from a previously idled state, clear the Request Idle and
Execution Idle check boxes.

5. Click OK. The Idle/Resume dialog box closes and the project goes into the selected
mode. If you are using clustered Intelligence Servers, the project mode is changed for
all nodes in the cluster.

Project and data warehouse maintenance example scenarios

In addition to the example scenarios provided with the different project idle modes, the list
below describes some other maintenance scenarios that can be achieved using various
project idle modes:
l Database maintenance for a data warehouse is scheduled to run at midnight, during
which time the data warehouse must not be accessible to users. At 11:00 P.M., the
administrator sets the project mode to Request Idle. All currently executing jobs will finish
normally. At 11:30 P.M., the administrator sets the project mode to Warehouse Execution
Idle, disallowing any execution against the data warehouse while maintenance tasks are
performed. After maintenance is complete, the administrator sets the project to Loaded to
allow normal execution and functionality to resume for the project.
l Two projects, named Project1 and Project 2, use the same data warehouse. Project1
needs dedicated access to the data warehouse for a specific length of time. The
administrator first sets Project2 to Request Idle. After existing activity against the data
warehouse is complete, Project2 is restricted against executing on the data warehouse.
Then, the administrator sets Project2 to Warehouse Execution Idle mode to allow data
warehouse-independent activity to execute. Project1 now has dedicated access to the
data warehouse until Project2 is reset to Loaded.
l When the administrator schedules a project maintenance activity, the impact on users of
the project during this time can be reduced. The administrator can set a project’s idle
mode to Request Idle, followed by Partial Idle, and finally to Full Idle. This process can

48 © 2018, MicroStrategy Inc.

 System Administration Guide

reduce user access to a project and data warehouse gradually, rather than changing
directly to Full Idle and thus immediately stopping all user activity.

Processing jobs
Any request submitted to Intelligence Server from any part of the MicroStrategy system is
known as a job. Jobs may originate from servers such as Narrowcast Server or Intelligence
Server’s internal scheduler, or from client applications such as Developer, MicroStrategy
Web, Mobile, Integrity Manager, or another custom-coded application.
The main types of requests include report execution requests, object browsing requests,
element browsing requests, Report Services document requests, and HTML document
requests.
The Job Monitor shows you which jobs are currently executing and lets you cancel jobs as
necessary. For information about the job monitor, see Monitoring currently executing jobs,
page 63.
By default, jobs are processed on a first-in first-out basis. However, your system probably
has some jobs that need to be processed before other jobs. You can assign a priority level to
each job according to factors such as the type of request, the user or user group requesting
the job, the source of the job (such as Developer, Mobile, or MicroStrategy Web), the
resource cost of the job, or the project containing the job. Jobs with a higher priority have
precedence over jobs with a lower priority, and they are processed first if there is a limit on
the resources available. For detailed information on job priority, including instructions on how
to prioritize jobs, see Prioritizing jobs, page 369.

Intelligence Server job processing (common to all jobs)

Regardless of the type of request, Intelligence Server uses some common functionality to
satisfy them. The following is a high-level overview of the processing that takes place.
1 A user makes a request from a client application such as MicroStrategy Web, which
sends the request to Intelligence Server.
2 Intelligence Server determines what type of request it is and performs a variety of
functions to prepare for processing.
Depending on the request type, a task list is composed that determines what tasks must
be accomplished to complete the job, that is, what components the job has to use within
the server that handle things like asking the user to respond to a prompt, retrieving
information from the metadata repository, executing SQL against a database, and so on.
Each type of request has a different set of tasks in the task list.
3 The components in Intelligence Server perform different tasks in the task list, such as
querying the data warehouse, until a final result is achieved.
Those components are the stops the job makes in what is called a pipeline, a path that
the job takes as Intelligence Server works on it.
4 The result is sent back to the client application, which presents the result to the user.
Most of the actual processing that takes place is done in steps 2 and 3 internally in
Intelligence Server. Although the user request must be received and the final results must be

© 2018, MicroStrategy Inc. 49

System Administration Guide

delivered (steps 1 and 4), those are relatively simple tasks. It is more useful to explain how
Intelligence Server works. Therefore, the rest of this section discusses Intelligence Server
activity as it processes jobs. This includes:
• Processing report execution, page 50
• Processing object browsing, page 53
• Processing element browsing, page 55
• Processing Report Services document execution, page 57
• Processing HTML document execution, page 59
• Client-specific job processing, page 60
Being familiar with this material should help you to understand and interpret statistics,
Enterprise Manager reports, and other log files available in the system. This may help you to
know where to look for bottlenecks in the system and how you can tune the system to
minimize their effects.

Processing report execution

Reports are perhaps the most common requests made of Intelligence Server. All report
requests have the following pieces:
• A report instance is a container for all objects and information needed and produced
during report execution including templates, filters, prompt answers, generated SQL,
report results, and so on.
• A task list is a list of tasks that must be accomplished to complete a job. All jobs have a
task list associated with them. Intelligence Server coordinates the report instance being
passed from one internal Intelligence Server component to another as a report is
executed.
The most prominent Intelligence Server components related to report job processing are
listed here.

Component Function

Analytical Performs complex calculations on a result set returned from the data warehouse, such
Engine as statistical and financial functions. Also, sorts raw results returned from the Query
Server Engine into a cross-tabbed grid suitable for display to the user. In addition, it performs
subtotal calculations on the result set. Depending on the metric definitions, the
Analytical Engine will also perform metric calculations that were not or could not be
performed using SQL, such as complex functions.
Metadata Controls all access to the metadata for the entire project.
Server
Object Creates, modifies, saves, loads and deletes objects from metadata. Also maintains a
Server server cache of recently used objects. The Object Server does not manipulate metadata
directly. The Metadata Server does all reading/writing from/to the metadata; the Object
Server uses the Metadata Server to make any changes to the metadata.

50 © 2018, MicroStrategy Inc.

 System Administration Guide

Component Function

Query Sends the SQL generated by the SQL Engine to the data warehouse for execution.
Engine
Report Creates and manages all server reporting instance objects. Maintains a cache of
Server executed reports.
Resolution Resolves prompts for report requests. Works in conjunction with Object Server and
Server Element Server to retrieve necessary objects and elements for a given request.
SQL Generates the SQL needed for the report.
Engine
Server

Below is a typical scenario of a report’s execution within Intelligence Server. The diagram
shows the report processing steps. An explanation of each step follows the diagram.

1 Intelligence Server receives the request.

2 The Resolution Server checks for prompts. If the report has one or more prompts, the
user must answer them. For information about these extra steps, see Processing
reports with prompts.
3 The Report Server checks the internal cache, if the caching feature is turned on, to see
whether the report results already exist. If the report exists in the cache, Intelligence
Server skips directly to the last step and delivers the report to the client. If no valid cache

© 2018, MicroStrategy Inc. 51

System Administration Guide

exists for the report, Intelligence Server creates the task list necessary to execute the
report. For more information on caching, see Result caches, page 439.

Prompts are resolved before the Server checks for caches. Users may be able to retrieve
results from cache even if they have personalized the report with their own prompt answers.

4 The Resolution Server obtains the report definition and any other required application
objects from the Object Server. The Object Server retrieves these objects from the
object cache, if possible, or reads them from the metadata via the Metadata Server.
Objects retrieved from metadata are stored in the object cache.
5 The SQL Generation Engine creates the optimized SQL specific to the RDBMS being
used in the data warehouse. The SQL is generated according to the definition of the
report and associated application objects retrieved in the previous step.
6 The Query Engine runs the SQL against the data warehouse. The report results are
returned to Intelligence Server.
7 The Analytical Engine performs additional calculations as necessary. For most reports,
this includes cross-tabbing the raw data and calculating subtotals. Some reports may
require additional calculations that cannot be performed in the database via SQL.
8 Depending on the analytical complexity of the report, the results might be passed back to
the Query Engine for further processing by the database until the final report is ready (in
this case, steps 5–7 are repeated).
9 Intelligence Server’s Report Server saves or updates the report in the cache, if the
caching feature is turned on, and passes the formatted report back to the client, which
displays the results to the user.

Processing reports with prompts

If the report has prompts, these steps are inserted in the regular report execution steps
presented above (see Processing report execution):
1 Intelligence Server sends the job to the Resolution Server component. The Resolution
Server discovers that the report definition contains a prompt and tells Intelligence Server
to prompt the user for the necessary information.
2 Intelligence Server puts the job in a sleep mode and tells the Result Sender component
to send a message to the client application prompting the user for the information.
3 The user completes the prompt, and the client application sends the user’s prompt
selections back to Intelligence Server.
4 Intelligence Server performs the security and governing checks and updates the
statistics. It then wakes up the sleeping job, adds the user’s prompt reply to the job’s
report instance, and passes the job to the Resolution Server again.
5 This cycle repeats until all prompts in the report are resolved.

A sleeping job times out after a certain period or if the connection to the client is lost. If the
prompt reply comes back after the job has timed out, the user sees an error message.

52 © 2018, MicroStrategy Inc.

 System Administration Guide

All regular report processing resumes from the point at which Intelligence Server checks for
a report cache, if the caching feature is turned on.

Processing personal Intelligent Cube reports

Personal Intelligent Cube reports are initially processed the same as a regular report, and
the report instance is held in Intelligence Server’s memory. If the user manipulates the report
and that manipulation does not cause the base report’s SQL to change, the Analytical
Engine component services the request and sends the results to the client. No additional
processing from the data warehouse is required.
Reports can also connect to Intelligent Cubes that can be shared by multiple reports. These
Intelligent Cubes also allow the Analytical Engine to perform additional analysis without
requiring any processing on the data warehouse.
For information on personal Intelligent Cubes and Intelligent Cubes, see the In-memory
Analytics Guide.

Processing graph reports

When processing graph reports, Intelligence Server performs the regular report processing
(see Processing report execution). Depending on the connection, the following happens:
• In a three-tier connection, Intelligence Server sends the report to Developer, which
creates the graph image.
• In a four-tier connection, Intelligence Server uses the graph generation component to
create the graph image and sends it to the client.

Processing object browsing

The definitions for all objects displayed in the folder list, such as folders, metrics, attributes,
and reports, are stored in the metadata. Whenever you expand or select a folder in
Developer or MicroStrategy Web, Intelligence Server must retrieve the objects from the
metadata before it can display them in the folder list and the object viewer.
This process is called object browsing and it creates what are called object requests. It can
cause a slight delay that you may notice the first time you expand or select a folder. The
retrieved object definitions are then placed in Intelligence Server’s memory (cache) so that
the information is displayed immediately the next time you browse the same folder. This is
called object caching. For more information on this, see Object caches, page 486.
The most prominent Intelligence Server components related to object browsing are listed
here.

Component Function

Metadata Controls all access to the metadata for the entire project.
Server

© 2018, MicroStrategy Inc. 53

System Administration Guide

Component Function

Object Creates, modifies, saves, loads and deletes objects from metadata. Also maintains a
Server server cache of recently used objects.
Source Net Receives, de-serializes, and passes metadata object requests to the object server.
Server

The diagram below shows the object request execution steps. An explanation of each step
follows the diagram.

1 Intelligence Server receives the request.

2 The Object Server checks for an object cache that can service the request. If an object
cache exists, it is returned to the client and Intelligence Server skips to the last step in this
process. If no object cache exists, the request is sent to the Metadata Server.
3 The Metadata Server reads the object definition from the metadata repository.
4 The requested objects are received by the Object Server where are they deposited into
memory object cache.
5 Intelligence Server returns the objects to the client.

54 © 2018, MicroStrategy Inc.

 System Administration Guide

Processing element browsing

Attribute elements are typically stored in lookup tables in the data warehouse. This includes
data that is unique to your business intelligence system, such as Northeast, Northwest,
Central, and Asia in the Region attribute.

For a more thorough discussion of attribute elements, see the section in the Basic Reporting
Guide about the logical data model.

When users request attribute elements from the system, they are said to be element
browsing and create what are called element requests. More specifically, this happens when
users:
• Answer prompts when executing a report
• Browse attribute elements in Developer using the Data Explorer (either in the Folder List
or the Report Editor)
• Use Developer’s Filter Editor, Custom Group Editor, or Security Filter Editor
• Use the Design Mode on MicroStrategy Web to edit the report filter
When Intelligence Server receives an element request from the user, it sends a SQL
statement to the data warehouse requesting attribute elements. When it receives the results
from the data warehouse, it then passes the results back to the user. Also, if the element
caching feature is turned on, it stores the results in memory so that additional requests are
retrieved from memory instead of querying the data warehouse again. For more information
on this, see Element caches, page 475.
The most prominent Intelligence Server components related to element browsing are listed
here.

Component Function

DB Element Transforms element requests into report requests and then sends report requests
Server to the warehouse.
Element Net Receives, de-serializes, and passes element request messages to the Element
Server Server.
Element Server Creates and stores server element caches in memory. Manages all element
requests in the project.
Query Engine Sends the SQL generated by the SQL Engine to the data warehouse for execution.
Report Server Creates and manages all server reporting instance objects. Maintains a cache of
executed reports.
Resolution Resolves prompts for report requests. Works in conjunction with Object Server
Server and Element Server to retrieve necessary objects and elements for a given
request.
SQL Engine Generates the SQL needed for the report.
Server

© 2018, MicroStrategy Inc. 55

System Administration Guide

The diagram below shows the element request execution steps. An explanation of each step
follows the diagram.

1 Intelligence Server receives the request.

2 The Element Server checks for a server element cache that can service the request. If a
server element cache exists, the element cache is returned to the client. Skip to the last
step in this process.
3 If no server element cache exists, the database Element Server receives the request
and transforms it into a report request.

The element request at this point is processed like a report request: Intelligence Server
creates a report that has only the attributes and possibly some filtering criteria, and SQL is
generated and executed like any other report.

4 The Report Server receives the request and creates a report instance.

56 © 2018, MicroStrategy Inc.

 System Administration Guide

5 The Resolution Server receives the request and determines what elements are needed
to satisfy the request, and then passes the request to the SQL Engine Server.
6 The SQL Engine Server generates the necessary SQL to satisfy the request and passes
it to the Query Engine Server.
7 The Query Engine Server sends the SQL to the data warehouse.
8 The elements are returned from the data warehouse to Intelligence Server and
deposited in the server memory element cache by the Element Server.
9 Intelligence Server returns the elements to the client.

Processing Report Services document execution

A MicroStrategy Report Services document contains objects representing data coming from
one or more reports. The document also holds positioning and formatting information. A
document is used to combine data from multiple reports into a single display of presentation
quality. When you create a document, you can specify the data that appears and can also
control the layout, formatting, grouping, and subtotaling of that data. In addition, you can
insert pictures into the document and draw borders on it. All these capabilities allow you to
create documents that are suitable to present to management.
Most of the data on a document is from an underlying dataset. A dataset is a MicroStrategy
report that defines the information that Intelligence Server retrieves from the data
warehouse or cache. Other data that does not originate from the dataset is stored in the
document’s definition.
Document execution is slightly different from the execution of a single report, since
documents can contain multiple reports.
The following diagram shows the document processing execution steps. An explanation of
each step follows the diagram.

© 2018, MicroStrategy Inc. 57

System Administration Guide

1 Intelligence Server receives a document execution request and creates a document

instance in Intelligence Server. This instance holds the results of the request.
A document instance facilitates the processing of the document through Intelligence
Server, similar to a report instance that is used to process reports. It contains the report
instances for all the dataset reports and therefore has access to all the information that
may be included in the dataset reports. This information includes prompts, formats, and
so on.
2 The Document Server inspects all dataset reports and prepares for execution. It
consolidates all prompts from from datasets into a single prompt to be answered. All
identical prompts are merged so that the resulting prompt contains only one copy of each
prompt question.
3 The Document Server, with the assistance of the Resolution Server, asks the user to
answer the consolidated prompt. The user’s answers are stored in the Document
Server.
4 The Document Server creates an individual report execution job for each dataset report.
Each job is processed by Intelligence Server, using the report execution flow described

58 © 2018, MicroStrategy Inc.

 System Administration Guide

in Processing report execution, page 50. Prompt answers are provided by the
Document Server to avoid further prompt resolution.
5 After Intelligence Server has completed all the report execution jobs, the Analytical
Engine receives the corresponding report instances to begin the data preparation step.
Document elements are mapped to the corresponding report instance to construct
internal data views for each element.

Document elements include grouping, data fields, Grid/Graphs, and so on.

6 The Analytical Engine evaluates each data view and performs the calculations that are
required to prepare a consolidated dataset for the entire document instance. These
calculations include calculated expressions, derived metrics, and conditional formatting.
The consolidated dataset determines the number of elements for each group and the
number of detail sections.
7 The Document Server receives the final document instance to finalize the document
format:
• Additional formatting steps are required if the document is exported to PDF or Excel
format. The export generation takes place on the client side in three-tier and on the
server side in four-tier, although the component in charge is the same in both cases.
• If the document is executed in HTML, the MicroStrategy Web client requests an
XML representation of the document to process it and render the final output.
8 The completed document is returned to the client.

Processing HTML document execution

An HTML document is a container for formatting, displaying, and distributing multiple reports
from a single request. HTML Documents are based on an HTML template, which allows
them to contain any combination of text, images, hyperlinks, tables, grid reports, and graph
reports. Any reports included in an HTML document are called the child reports of the HTML
document.
Because HTML documents are collections of multiple reports, their execution process is
slightly different from single reports. The most notable differences are shown in the
procedure below.
The diagram below shows the HTML document processing execution steps. An explanation
of each step follows the diagram.

© 2018, MicroStrategy Inc. 59

System Administration Guide

1 Intelligence Server receives an HTML document execution request and creates an

HTML document instance to go through Intelligence Server and hold the results.
An HTML document instance facilitates the processing of the HTML document through
Intelligence Server like a report instance is used for processing reports. It contains the
report instances for all the child reports, the XML results for the child reports, and any
prompt information that may be included in the child reports.
2 The HTML Document Server consolidates all prompts from child reports into a single
prompt to be answered. Any identical prompts are merged so that the resulting single
prompt contains only one copy of each prompt question.
3 Resolution Server asks the user to answer the consolidated prompt. (The user only
needs to answer a single set of questions.)
4 The HTML Document Server splits the HTML document request into separate individual
jobs for the constituent reports. Each report goes through the report execution flow as
described above.

Prompts have already been resolved for the child reports.

5 The completed request is returned to the client.

Client-specific job processing

This section explains the job processing steps that certain client applications perform as they
deliver user requests to Intelligence Server. It also covers how those clients receive results,
and how the results are displayed them to the user.

60 © 2018, MicroStrategy Inc.

 System Administration Guide

For information about the processing steps performed by Intelligence Server for all jobs, see
Intelligence Server job processing (common to all jobs), page 49.

Processing jobs from MicroStrategy Web products

This section provides a high-level overview of processing flow for requests originating in
MicroStrategy Web or Web Universal. It also includes the job process for exporting reports in
various formats.

Job requests from MicroStrategy Web products

1. The user makes a request from a web browser. The request is sent to the web server
via HTTP or HTTPS.
2. An ASP.Net page or a servlet receives the request and calls the MicroStrategy Web
API.
3. The MicroStrategy Web API sends the request to Intelligence Server, which
processes the job as usual (see Processing report execution, page 50).
4. Intelligence Server sends the results back to the MicroStrategy Web API via XML.
5. MicroStrategy Web converts the XML to HTML within the application code:
l In MicroStrategy Web, the conversion is primarily performed in ASP code.
l In some customizations, the conversion may occur within custom XSL classes. By
default, the product does not use XSL for rendering output, except in document
objects.
6. MicroStrategy Web sends the HTML to the client’s browser, which displays the
results.

What happens when I export a report from MicroStrategy Web?

Exporting a report from MicroStrategy Web products lets users save the report in another
format that may provide additional capabilities for sharing, printing, or further manipulation.
This section explains the additional processing the system must do when exporting a report
in one of several formats. This may help you to understand when certain parts of the
MicroStrategy platform are stressed when exporting.
Exporting a report from MicroStrategy Web products causes Intelligence Server to retrieve
the entire result set (no incremental fetch) into memory and send it to MicroStrategy Web.
This increases the memory use on the Intelligence Server machine and it increases network
traffic.

For information about governing report size limits for exporting, see Limiting the information
displayed at one time, page 377 and the following sections.

© 2018, MicroStrategy Inc. 61

System Administration Guide

Export to Comma Separated File (CSV) or Excel with Plain Text

Export to Comma Separated File (CSV) and Export to Excel with Plain Text is done
completely on Intelligence Server. These formats contain only report data and no formatting
information. The only difference between these two formats is the internal “container” that is
used.
The MicroStrategy system performs these steps when exporting to CSV or to Excel with
plain text:
1. MicroStrategy Web product receives the request for the export and passes the
request to Intelligence Server. Intelligence Server takes the XML containing the report
data and parses it for separators, headers and metric values.
2. Intelligence Server then outputs the titles of the units in the Row axis. All these units
end up in the same row of the result text.
3. Intelligence Server then outputs the title and header of one unit in the Column axis.
4. Step 3 is repeated until all units in the Column axis are completed.
5. Intelligence Server outputs all the headers of the Row axis and all metric values one
row at a time.
6. The finished result is then passed to be output as a CSV or an Excel file, which is then
passed to the client browser.

Export to Excel with Formatting

Exporting to Excel with formatting allows for reports to be exported to an Excel file and
contain the same formatting as shown in the browser window. The report retains all cell
coloring, font sizes, styles, and other formatting aspects.

• To export to Excel with formatting, the client machine must have Excel 2000
SR-1 or later.
• To export to Excel, users must first set their Export preferences by clicking
Preferences, then User preferences, then Export, and select the
Excel version they want to export to.

The MicroStrategy system performs these steps when exporting to Excel with formatting:
1. MicroStrategy Web product receives the request for the export to Excel and passes
the request to Intelligence Server. Intelligence Server produces an HTML document
by combining the XML containing the report data with the XSL containing formatting
information.
2. Intelligence Server passes the HTML document to MicroStrategy Web, which creates
an Excel file and sends it to the browser.
3. Users can then choose to view the Excel file or save it depending on the client
machine operating system’s setting for viewing Excel files.

62 © 2018, MicroStrategy Inc.

 System Administration Guide

Export to PDF
Exporting to PDF uses Intelligence Server’s export engine to create a PDF (Portable
Document Format) file. PDF files are viewed with Adobe’s Acrobat reader and provide
greater printing functionality than simply printing the report from the browser.

To view the PDF files, the client machine must have Adobe Acrobat Reader 5.0 version or
greater.

Processing jobs from Narrowcast Server

MicroStrategy Narrowcast Server performs the following steps to deliver reports to users.

For detailed information about Narrowcast Server, see the Narrowcast Server Getting Started
Guide.

Job requests from MicroStrategy Narrowcast Server

1. A Narrowcast service execution is triggered by a schedule or external API call.
2. Narrowcast Server determines the service recipients and allocates work to Execution
Engine (EE) machines.
3. EE machines determine personalized reports to be created for each recipient by using
recipient preferences.
4. Narrowcast Server submits one report per user or one multipage report for multiple
users, depending on service definition.
5. Intelligence Server processes the report job request as usual. (See Processing report
execution, page 50.) It then sends the result back to Narrowcast Server.
6. Narrowcast Server creates formatted documents using the personalized report data.
7. Narrowcast Server packages documents as appropriate for the service’s delivery
method, such as e-mail, wireless, and so on.
8. Narrowcast Server delivers the information to recipients by the chosen delivery
method.

Monitoring currently executing jobs

The Job Monitor informs you of what is happening with system tasks. However, it does not
display detailed sub-steps that a job is performing. You can see jobs that are:
l Executing
l Waiting in the queue
l Waiting for a user to reply to a prompt

© 2018, MicroStrategy Inc. 63

System Administration Guide

l Canceling
l Not completing because of an error
The Job Monitor displays which tasks are running on an Intelligence Server. When a job has
completed it no longer appears in the monitor. You can view a job’s identification number; the
user who submitted it; the job’s status; a description of the status and the name of the report,
document, or query; and the project executing it.

To view the currently executing jobs

1. In Developer, log in to a project source. You must log in as a user with the Monitor
Jobs privilege.
2. Expand Administration, then expand System Monitors, and then select Jobs.
The job information displays on the right-hand side.
3. Because the Job Monitor does not refresh itself, you must periodically refresh it to see
the latest status of jobs. To do this, press F5.
4. To view a job’s details including its SQL, double-click it.
5. To view more details for all jobs displayed, right-click in the Job Monitor and select
View options. Select the additional columns to display and click OK.

At times, you may see “Temp client” in the Network Address column. This may happen when
Intelligence Server is under a heavy load and a user accesses the list of available projects.
Intelligence Server creates a temporary session that submits a job request for the available
projects and then sends the list to the MicroStrategy Web client for display. This temporary
session, which remains open until the request is fulfilled, is displayed as Temp client.

To cancel a job

1. Select the job in the Job Monitor.

2. Press DELETE, and then confirm whether you want to cancel the job.

Using automated installation techniques

You can make installing the MicroStrategy system across your enterprise easier in several
ways. They are mentioned here but more fully explained in theInstallation and Configuration
Guide.

Using a Response file to install the product

The response file installation allows you to automate certain aspects of the installation by
configuring a Windows INI-like response file, called response.ini. This option is typically
implemented by Original Equipment Manufacturer (OEM) applications that embed
MicroStrategy installations in other products. It can also be implemented by IT departments
that want to have more control over desktop installations. For more information on how to set
up and use a response file, see the Installation and Configuration Guide.

64 © 2018, MicroStrategy Inc.

 System Administration Guide

Using a Response file to configure the product

You can also use a response file to automate certain aspects of the MicroStrategy
configuration. This response file supplies parameters to the Configuration Wizard to set up a
metadata repository and statistics tables, Intelligence Server, and multiple project sources.
For steps on setting up and using a response file for the Configuration Wizard, see the
Installation and Configuration Guide.

Running a silent installation

Silent installations do not present any graphical user interface (GUI). They are typically
implemented by IT departments that perform software distribution and installation across the
network, for example, by using Microsoft’s System Management Server software. This
involves configuring a setup.iss file that the MicroStrategy Installation Wizard uses. For
steps on setting up and using a setup.iss file for a silent MicroStrategy installation, see
the Installation and Configuration Guide.

OEMs may use silent installations; however, it is more common for OEMs to use a response
file installation.

Security checklist before deploying the system

Use the checklist below to make sure you have implemented the appropriate security
services or features for your system before it is deployed. All the security implementations
listed below are described in detail in the preceding sections of this section.

Security implementation Completed

Ensure that the Administrator password has been changed. When you install Intelligence
Server, the Administrator account comes with a blank password that must be changed.
Set up access controls for the database (see Controlling access to data, page 88).
Depending on your security requirements you may need to:
• Set up security views to restrict access to specific tables, rows, or columns in the
database
• Split tables in the database to control user access to data by separating a logical data
set into multiple physical tables, which require separate permissions for access
• Implement connection mapping to control individual access to the database
• Configure passthrough execution to control individual access to the database from
each project, and to track which users are accessing the RDBMS
• Assign security filters to users or groups to control access to specific data (these
operate similarly to security views but at the application level)
Understand the MicroStrategy user model (see The MicroStrategy user model, page 67).
Use this model to:
• Select and implement a system authentication mode to identify users

© 2018, MicroStrategy Inc. 65

System Administration Guide

Security implementation Completed

• Set up security roles for users and groups to assign basic privileges and permissions
• Understand ACLs (access control lists), which allow users access permissions to
individual objects
• Check and, if necessary, modify privileges and permissions for anonymous
authentication for guest users. (By default, anonymous access is disabled at both the
server and the project levels.) Do not assign delete privileges to the guest user
account.
Assign privileges and permissions to control user access to application functionary. You
may need to:
• Assign the Denied All permission to a special user or group so that, even if permission
is granted at another level, permission is still denied
• Make sure guest users (anonymous authentication) have access to the Log folder in
C:\Program Files (x86)\Common Files\MicroStrategy. This ensures that any
application errors that occur while a guest user is logged in can be written to the log
files.
Use your web application server security features to:
• Implement file-level security requirements
• Create security roles for the application server
Make use of standard Internet security technologies such as firewalls, digital certificates,
and encryption. For example:
• Enable encryption for MicroStrategy Web products. By default most encryption
technologies are not used unless you enable them.
• If you are working with sensitive or confidential data, enable the setting to encrypt all
communication between MicroStrategy Web server and Intelligence Server.

There may be a noticeable performance degradation because the system must encrypt
and decrypt all network traffic.

Locate the physical machine hosting the MicroStrategy Web application in a physically
secure location.
Restrict access to files stored on the machine hosting the MicroStrategy Web application
by implementing standard file-level security offered by your operating system. Specifically,
apply this type of security to protect access to the MicroStrategy administrator pages, to
prevent someone from typing specific URLs into a browser to access these pages. (The
default location of the Admin page file is C:\Program Files
(x86)\MicroStrategy\Web ASPx\asp\Admin.aspx.) Be sure to restrict access
to:
• The asp directory
• Admin.aspx

66 © 2018, MicroStrategy Inc.

 2
Setting Up User Security
Security is a concern in any organization. The data warehouse may contain sensitive
information that should not be viewed by all users. It is your responsibility as administrator to
make the right data available to the right users.
MicroStrategy has a robust security model that enables you to create users and groups, and
control what data they can see and what objects they can use. The security model is covered
in the following sections:
• The MicroStrategy user model, page 67
• Controlling access to application functionality, page 73
• Controlling access to data, page 88
• Merging users or groups, page 107
Authentication, the process by which the system identifies the user, is an integral part of any
security model. Authenticating users is addressed in Chapter , Identifying Users:
Authentication.

The MicroStrategy user model

This section provides an overview of what users and groups are in the system and how they
can be imported or created.

About MicroStrategy users

Like most security architectures, the MicroStrategy security model is built around the concept
of a user. To do anything useful with MicroStrategy, a user must log in to the system using a
login ID and password. The user can then perform tasks such as creating objects or
executing reports and documents, and can generally take advantage of all the other features
of the MicroStrategy system.

MicroStrategy supports a single sign-on for users in an enterprise environment that consists
of multiple applications, data sources, and systems. Users can log in to the system once and

© 2018, MicroStrategy Inc. 67

System Administration Guide

access all the resources of the enterprise seamlessly. For more details about implementing
single sign-on in MicroStrategy, see Enabling single sign-on authentication, page 142.

Users are defined in the MicroStrategy metadata and exist across projects. You do not have
to define users for every project you create in a single metadata repository.
Each user has a unique profile folder in each project. This profile folder appears to the user
as the “My Personal Objects” folder. By default other users’ profile folders are hidden. They
can be viewed by, in the Developer Preferences dialog box, in the Developer: Browsing
category, selecting the Display Hidden Objects check box.
Administrator is a built-in default user created with a new MicroStrategy metadata
repository. The Administrator user has all privileges and permissions for all projects and all
objects.

One of the first things you should do in your MicroStrategy installation is to change the
password for the Administrator user.

About MicroStrategy user groups

A user group (or “group” for short) is a collection of users. Groups provide a convenient way
to manage a large number of users.
Instead of assigning privileges, such as the ability to create reports, to hundreds of users
individually, you may assign privileges to a group. Groups may also be assigned permissions
to objects, such as the ability to add reports to a folder.

In addition to having privileges of their own, subgroups always inherit the privileges from their
parent groups.

For a list of the privileges assigned to each group, see the List of Privileges section.

Do not modify the privileges for an out-of-the-box user group. During upgrades to newer
versions of MicroStrategy, the privileges for the out-of-the-box user groups are overwritten
with the default privileges. Instead, you should copy the user group you need to modify and
make changes to the copied version.

The Everyone group

All users except for guest users are automatically members of the Everyone group. The
Everyone group is provided to make it easy for you to assign privileges, security role
memberships, and permissions to all users.

When a project is upgraded from MicroStrategy version 7.5.x or earlier to version 9.x, the Use
Developer privilege is automatically granted to the Everyone group. This ensures that all
users who were able to access Developer in previous versions can continue to do so.

68 © 2018, MicroStrategy Inc.

 System Administration Guide

Authentication-related groups
These groups are provided to assist you in managing the different ways in which users can
log into the MicroStrategy system. For details on the different authentication methods, see
Chapter , Identifying Users: Authentication.
l Public/Guest: The Public group provides the capability for anonymous logins and is
used to manage the access rights of guest users. If you choose to allow anonymous
authentication, each guest user assumes the profile defined by the Public group. When a
user logs in as a guest, a new user is created dynamically and becomes a member of the
Public group. For more information about anonymous authentication and the Public/Guest
group, see Implementing anonymous authentication, page 115.
l 3rd Party Users: Users who access MicroStrategy projects through third-party (OEM)
software.
l LDAP Users: The group into which users that are imported from an LDAP server are
added.
l LDAP Public/Guest: The group that is used when a user is linked to an LDAP account
but not imported.

For information on integrating LDAP with MicroStrategy, see Implementing LDAP

authentication, page 116.

l Warehouse Users: Users who access a project through a warehouse connection.

Groups corresponding to product offerings

These groups are built-in groups that correspond to the licenses you have purchased. Using
these groups gives you a convenient way to assign product-specific privileges.
l Architect: Architects function as project designers and can create attributes, facts,
hierarchies, projects, and so on.
l Analyst: Analysts have the privileges to execute simple reports, answer prompts, drill on
reports, format reports, create reports by manipulating Report Objects, create derived
metrics, modify view filter, pivot reports, create page by, and sort using advanced options.
l Developer: Developers can design new reports from scratch, and create report
components such as consolidations, custom groups, data marts, documents, drill maps,
filters, metrics, prompts, and templates.
l Web Reporter: Web Reporters can view scheduled reports and interactively slice and
dice them. They can also use the printing, exporting, and e-mail subscription features.
l Web Analyst: Web Analysts can create new reports with basic report functionality, and
use ad hoc analysis from Intelligent Cubes with interactive, slice and dice OLAP.
l Web Professional: Web Professional users have the maximum access to
MicroStrategy Web functionality. They can create Intelligent Cubes and reports for users,
with full reporting, ad hoc, and OLAP capabilities with seamless ROLAP analysis.

© 2018, MicroStrategy Inc. 69

System Administration Guide

Administrator groups
l System Monitors: The System Monitors groups provide an easy way to give users
basic administrative privileges for all projects in the system. Users in the System Monitors
groups have access to the various monitoring and administrative monitoring tools
System Administrators: The System Administrators group is a group within the
System Monitors group. It provides all the capabilities of the System Monitors group plus
the ability to modify configuration objects such as database instances, and so on.

Privileges
Privileges allow users to access and work with various functionality within the software. All
users created in the MicroStrategy system are assigned a set of privileges by default.
For detailed information about privileges, including how to assign privileges to a user or
group, see Controlling access to functionality: Privileges, page 81. For a list of all user and
group privileges in MicroStrategy, see the List of Privileges section.
To see which users are using certain privileges, use the License Manager. See Using
License Manager, page 244.

To view a user’s privileges

1. In Developer, log in to a project source. You must log in as a user with the Create And
Edit Users And Groups privilege.
2. Expand Administration, then User Manager, and then the group containing the
user.
3. Right-click the user and select Grant access to projects. The User Editor opens
to the Project Access dialog box. The privileges that the user has for each project are
listed, as well as the source of those privileges (inherent to user, inherited from a
group, or inherited from a security role).

Permissions
Permissions allow users to interact with various objects in the MicroStrategy system. All
users created in the MicroStrategy system have certain access rights to certain objects by
default.

Permissions differ from privileges in that permissions restrict or allow actions related to a
single object, while privileges restrict or allow actions across all objects in a project.

For detailed information about permissions, including how to assign permissions for an
object to a user or group, see Controlling access to objects: Permissions, page 73.

70 © 2018, MicroStrategy Inc.

 System Administration Guide

To view the permissions for an object

1. From within Developer, right-click the object and select Properties.

2. Expand the Security category.

Creating, importing, and deleting users and groups

It is possible to create users individually using the User Manager interface in Developer, or
using Command Manager (for a detailed explanation of how to use Command Manager,
including examples, see Chapter , Automating Administrative Tasks with Command
Manager). You can also import users and groups from a text file, from a Windows user
directory, or from an LDAP directory.

To create a new user with the User Editor in Developer

1. In Developer, log in to a project source. You must log in as a user with the Create And
Edit Users And Groups privilege.
2. Expand Administration, then User Manager, and then a group that you want
the new user to be a member of. If you do not want the user to be a member of a
group, select Everyone.
3. Go to File > New > User.
4. Specify the user information for each category in the editor. For details about each
field, see the MicroStrategy Developer Help.

The user login ID is limited to 50 characters.

For detailed information about other methods for creating or importing users or groups, see
the MicroStrategy Developer Help.

To delete a user

If a Narrowcast user exists that inherits authentication from the user that you are deleting,
you must also remove the authentication definition from that Narrowcast user. For
instructions, see the MicroStrategy Narrowcast Server Administration Guide.

1. In Developer, log in to a project source. You must log in as a user with the Create And
Edit Users And Groups privilege.
2. Expand Administration, then User Manager, and then browse to the group
containing the user.
3. Select the user and press DELETE.
4. A dialog box opens, asking you to confirm the action. Click OK.

© 2018, MicroStrategy Inc. 71

System Administration Guide

5. If the user owns a profile folder, a dialog box opens asking if you want to delete the
user’s profile folder:
l If you click No, the folder and its contents remain on the system and ownership is
assigned to Administrator. You may later assign ownership and access control lists
for the folder and its contents to other users.
l If you click Yes, the folder and all of its contents are deleted.

Monitoring users’ connections to projects

When a user connects to a project, a user connection is established. You may want to see a
list of all users connected to projects within a project source. The User Connection Monitor
displays a list of all connections and allows you to disconnect a user.

To view the active user connections

1 In Developer, log in to a project source. You must log in as a user with the Monitor User
Connections privilege.
2 Expand Administration, then expand System Monitors, and then select User
Connections. The user connection information displays on the right-hand side. For
each user, there is one connection for each project the user is logged in to, plus one
connection for <Server> indicating that the user is logged in to the project source.

— Scheduler: Connections made by Intelligence Server to process

scheduled reports or documents appear as <Scheduler> in the
Network Address column. Scheduler sessions cannot be manually
disconnected as described above. However, these sessions will be
removed automatically by Intelligence Server when the user session idle
time out value is reached.
— Temp client: At times, you may see “Temp client” in the Network
Address column. This may happen when Intelligence Server is under a
heavy load and a user accesses the Projects or Home page in
MicroStrategy Web (the pages that display the list of available projects).
Intelligence Server creates a temporary session that submits a job
request for the available projects and then sends the list to the
MicroStrategy Web client for display. This temporary session, which
remains open until the request is fulfilled, is displayed as “Temp client.”

3 To view a connection’s details, double-click it.

To disconnect a user

If you disconnect users from the project source (the <Configuration> entry in the User
Connection Monitor), they are also disconnected from any projects they were connected to.

1 In the User Connection Monitor, select the connection.

72 © 2018, MicroStrategy Inc.

 System Administration Guide

2 Press DELETE.

Controlling access to application functionality

Access control governs the resources that an authenticated user can read, modify, or write.
In addition to controlling access to data (see Controlling access to data, page 88), you must
also control access to application functionality, such as the ability to create reports or which
reports are viewable. The MicroStrategy system provides a rich set of functionality for access
control within Intelligence Server:

Controlling access to objects: Permissions

Permissions define the degree of control users have over individual objects in the system.
For example, in the case of a report, a user may have permission to view the report definition
and execute the report, but not to modify the report definition or delete the report.
While privileges are assigned to users (either individually, through groups, or with security
roles), permissions are assigned to objects. More precisely, each object has an Access
Control List (ACL) that specifies which permissions different sets of users have on that
object.

Intelligence Server includes special privileges called Bypass All Object Security Access
Checks and Bypass Schema Object Security Access Checks. Users with these privileges
are not restricted by access control permissions and are considered to have full control over
all objects and schema objects, respectively. For information about privileges, see
Controlling access to functionality: Privileges, page 81.

To modify permissions for an object in Developer

1. In Developer, right-click the object and select Properties.

To modify an object's ACL, you must access the Properties dialog box directly from
Developer. If you access the Properties dialog box from within an editor, you can view
the object's ACL but cannot make any changes.

2. Select the Security category.

3. For the User or Group (click Add to select a new user or group), from the Object
drop-down list, select the predefined set of permissions, or select Custom to define a
custom set of permissions. If the object is a folder, you can also assign permissions to
objects contained in that folder using the Children drop-down list.
4. Click OK.

To modify permissions for an object in MicroStrategy Web

1 In MicroStrategy Web, right-click an object and select Share.

© 2018, MicroStrategy Inc. 73

System Administration Guide

2 To modify permissions for a user or group, from the Permission Level drop-down list
for that user or group, select the predefined set of permissions, or select Custom to
define a custom set of permissions.
3 To add new users or groups to the object’s access control list (ACL):
a Click Choose Users/Groups.
b Select the users or groups that you want to add to the object’s ACL.
c From the Choose a Permission Level drop-down list, select the predefined set
of permissions, or select Custom to define a custom set of permissions.
d Click Add.
4 To remove a user or group from the object’s ACL, click the X next to the user or group’s
name.
5 When you are finished modifying the object’s permissions, click OK.

Access control list (ACL)

The Access Control List (ACL) of an object is a list of users and groups, and the access
permissions that each has for the object.
For example, for the Northeast Region Sales report you can specify the following
permissions:
l The Managers and Executive user groups have View access to the report.
l The Developers user group (people who create and modify your applications) has Modify
access.
l The Administrators user group has Full Control of the report.
l The Everyone user group (any user not in one of the other groups) should have no access
to the report at all, so you assign the Denied All permission grouping.
The default ACL of a newly created object has the following characteristics:
l The owner (the user who created the object) has Full Control permission.
l Permissions for all other users are set according to the Children ACL of the parent
folder.

Newly created folders inherit the standard ACLs of the parent folder. They do not inherit the
Children ACL.

74 © 2018, MicroStrategy Inc.

 System Administration Guide

• When creating new schema objects, if the Everyone user group is not defined
in the ACL of the parent folder, Developer will add the Everyone user group to
the ACL of the new schema object, and set the permissions to Custom. If the
Everyone user group has permissions already assigned in the parent folder
ACL, they will be inherited properly.
For example, if the Children setting of the parent folder’s ACL includes Full
Control permission for the Administrator and View permission for the
Everyone group, then the newly created object inside that folder will have Full
Control permission for the owner, Full Control for the Administrator, and View
permission for Everyone.
• Modifying the ACL of a shortcut object does not modify the ACL of that
shortcut’s parent object.
• When you move an object to a different folder, the moved object retains its
original ACLs until you close and reopen the project in Developer. Using Save
As to move an object to a new folder will update the ACLs for all objects
except metrics. When editing or moving a metric, you should copy the object
and place the copy in a new folder so the copied object inherits its ACL from
the Children ACL of the folder into which it is copied.

What permissions can be granted for an object?

When you edit an object’s ACL using the object’s Properties dialog box, you can assign a
predefined grouping of permissions or you can create a custom grouping. The table below
lists the predefined groupings and the specific permissions each one grants.

Grouping Description Permissions

granted

View Grants permission to access the object for viewing only, and to provide • Browse
translations for an object’s name and description.
• Read
• Use
• Execute
Modify Grants permission to view and/or modify the object. • Browse
• Read
• Write
• Delete
• Use
• Execute
Full Control Grants all permissions for the object and also allows to modify the ACL Control and
for the object. all other
permissions
are granted

© 2018, MicroStrategy Inc. 75

System Administration Guide

Grouping Description Permissions

granted

Denied All Explicitly denies all permissions for the object. None of the none; all
permissions are assigned. are denied
Default Neither grants nor denies permissions. All permissions are inherited none
from the groups to which the user or group belongs.
Custom Allows the user or group to have a custom combination of permissions custom
that you can define. choice
Consume (Intelligent Cube only) Grants permission to create and execute • Browse
reports based on this Intelligent Cube.
(Only • Read
available in
MicroStrategy • Use
Web)
Add (Intelligent Cube only) Grants permission to create and execute • Browse
reports based on this Intelligent Cube, and republish/re-execute the
(Only Intelligent Cube to update the data. • Read
available in
MicroStrategy • Use
Web) • Execute
Collaborate (Intelligent Cube only) Grants permission to create and execute • Browse
reports based on this Intelligent Cube, republish/re-execute the
(Only Intelligent Cube to update the data, and modify the Intelligent Cube. • Read
available in
MicroStrategy • Write
Web) • Delete
• Use
• Execute

The permissions actually assigned to the user or group when you select a permission
grouping are explained in the table below.

Permission Definition

Browse View the object in Developer and MicroStrategy Web

Read View the object’s definition in the appropriate editor, and view the object’s access control
list. When applied to a language object, allows users to see the language in the
Translation Editor but not edit strings for this language.
Write Modify the object’s definition in the appropriate editor and create new objects in the
parent object. For example, add a new metric in a report or add a new report to a
document.
Delete Delete the object
Control Modify the object’s access control list

76 © 2018, MicroStrategy Inc.

 System Administration Guide

Permission Definition

Use Use the object when creating or modifying other objects. For example, the Use permission
on a metric allows a user to create a report containing that metric. For more information,
see Permissions and report/document execution, page 80. When applied to a language
object, allows users to edit and save translations, and to select the language for display in
their Developer or MicroStrategy Web language preferences. This permission is checked
at design time, and when executing reports against an Intelligent Cube.

A user with Use but not Execute permission for an Intelligent Cube can create and
execute reports that use that Intelligent Cube, but cannot publish the Intelligent Cube.

Execute Execute reports or documents that reference the object. To execute a report or
document, a user must have Execute access to all objects on the report/document. For
more information, see Permissions and report/document execution, page 80. This
permission is checked at run time.

The user must have Use permission on an Intelligent Cube to execute reports against
that Intelligent Cube.

When you give users only Browse access to a folder, using the Custom permissions, they
can see that folder displayed, but cannot see a list of objects within the folder. However, if
they perform a search, and objects within that folder match the search criteria, they can see
those objects. To deny a user the ability to see objects within a folder, you must deny all
access directly to the objects in the folder.

For example, grant the Browse permission to a folder, but assign Denied All for the
folder’s children objects, then select the Apply changes in permissions to all
children objects check box. This allows a user to see the folder, but nothing
inside it. Alternatively, if you assign Denied All to the folder and to its children, the
user cannot see the folder or any of its contents.

Permissions for server governing and configuration

A server object is a configuration-level object in the metadata called Server Definition. It
contains governing settings that apply at the server level, a list of projects registered on the
server, connection information to the metadata repository, and so on. It is created or
modified when a user goes through the Configuration Wizard. Server definition objects are
not displayed in the interface in the same way other objects are (reports, metrics, and so on).
As with other objects in the system, you can create an ACL for a server object that
determines what system administration permissions are assigned to which users. These
permissions are different from the ones for other objects (see table below) and determine
what capabilities a user has for a specific server. For example, you can configure a user to
act as an administrator on one server, but as an ordinary user on another. To do this, you
must modify the ACL for each server definition object by right-clicking the Administration
icon, selecting Properties, and then selecting the Security tab.
The table below lists the groupings available for server objects, the permissions each one
grants, and the tasks each allows you to perform on the server.

© 2018, MicroStrategy Inc. 77

System Administration Guide

Grouping Permissions Granted Allows you to...

Connect • Browse Connect to the server

Monitoring • Browse • View server definition properties
• Read • View statistics settings
• Use the system monitors
Administration • Browse • Start/stop the server
• Read • Apply runtime settings
• Use • Update diagnostics at runtime
• Execute • Cancel jobs
• Idle/resume a project
• Disconnect user
• Schedule reports
• Delete schedules
• Trigger events
• Perform cache administration
• Create security filters
• Use Security Filter Manager
Configuration • Browse • Change server definition properties
• Read • Change statistics settings
• Write • Delete server definition
• Delete • Grant server rights to other users
• Control
Default All permissions that are assigned to Perform any task on that server.
"Default"
Custom... custom choice Perform the tasks your custom selections
allow.

How permissions are determined

A user can have permissions for a given object from the following sources:
• User identity: The user identity is what determines an object’s owner when an object is
created. The user identity also determines whether the user has been granted the right
to access a given object.
• Group membership: A user is granted access to an object if he or she belongs to a group
with access to the object.
• Special privileges: A user may possess a special privilege that causes the normal access
checks to be bypassed:

78 © 2018, MicroStrategy Inc.

 System Administration Guide

▫ Bypass Schema Object Security Access Checks allows the user to ignore the
access checks for schema objects.
▫ Bypass All Object Security Access Checks allows the user to ignore the access
checks for all objects.

Permission levels
A user can have permissions directly assigned to an object, and be a member of one or more
groups that have a different permission grouping assigned to the object. In this case, user-
level permissions override group-level permissions, and permissions that are denied at the
user or group level override permissions that are granted at that level. The list below
indicates what permissions are granted when permissions from multiple sources conflict.
1. Permissions that are directly denied to the user are always denied.
2. Permissions that are directly granted to the user, and not directly denied, are always
granted.
3. Permissions that are denied by a group, and not directly granted to the user, are
denied.
4. Permissions that are granted by a group, and not denied by another group or directly
denied, are granted.
5. Any permissions that are not granted, either directly or by a group, are denied.
For example, user Jane does not have any permissions directly assigned for a report.
However, Jane is a member of the Designers group, which has Full Control permissions for
that report, and is also a member of the Managers group, which has Denied All permissions
for that report. In this case, Jane is denied all permissions for the report. If Jane is later
directly granted View permissions for the report, she would have View permissions only.

Default permissions for folders in a new project

By default, in a new MicroStrategy project, users are only allowed to save objects within their
personal folders. Only administrative users can save objects within the Public Folder
directory in a MicroStrategy project. Folders in a new project are created with these default
ACLs:
• Public Objects folder, Schema Objects folder
▫ Administrator: Full Control
▫ Everyone: Browse
▫ Public/Guest: Browse
• Inherited ACL
▫ Administrator: Default
▫ Everyone: View
▫ Public/Guest: View

© 2018, MicroStrategy Inc. 79

System Administration Guide

This means that new users, as part of the Everyone group, are able to browse the objects in
the Public Objects folder, view their definitions and use them in definitions of other objects
(for example, create a report with a public metric), and execute them (execute reports).
However, new users cannot delete these objects, or create or save new objects to these
folders.

• Personal folders
▫ Owner: Full Control

This means that new users can create objects in these folders and have full control over
those objects.

Permissions and report/document execution

Two permissions relate to report and document execution: the Use and Execute
permissions. These have the following effects:
• The Use permission allows the user to reference or use the object when they are
modifying another object. This permission is checked at object design time, and when
executing reports against an Intelligent Cube.
• The Execute permission allows the user to execute reports or documents that use the
object. This permission is checked only at report/document execution time.
A user may have four different levels of access to an object using these two new
permissions:
• Both Use and Execute permissions: The user can use the object to create new reports,
and can execute reports containing the object.
• Execute permission only: The user can execute previously created reports containing
the object, but cannot create new reports that use the object. If the object is an Intelligent
Cube, the user cannot execute reports against that Intelligent Cube.
• Use permission only: The user can create reports using the object, but cannot execute
those reports.

A user with Browse, Read, and Use (but not Execute) permissions for an Intelligent Cube can
create and execute reports that use that Intelligent Cube, but cannot publish the Intelligent
Cube.

• Neither Use nor Execute permission: The user cannot create reports containing the
object, nor can the user execute such reports, even if the user has Execute rights on the
report.

Interpreting access rights during report/document execution

The ability to execute a report or document is determined by whether the user has Execute
permission on the report and Execute permission on the objects used to define that report.
More specifically, Execute permission is required on all attributes, custom groups,
consolidations, prompts, metrics, facts, filters, templates, and hierarchies used to define the

80 © 2018, MicroStrategy Inc.

 System Administration Guide

report or document. Permissions are not checked on transformations and functions used to
define the report.
If the user does not have access to an attribute, custom group, consolidation, prompt, fact,
filter, template, or hierarchy used to define a report, the report execution fails.
If the user does not have access to a metric used to define a report, the report execution
continues, but the metric is not displayed in the report for that user.
This enhancement allows a finer level of access control when executing reports. The same
report can be deployed to many users who experience different results depending on their
respective permissions on metrics.

ACLs and personalized drill paths in MicroStrategy Web

You can control what attribute drill paths users see on reports. You can determine whether
users can see all drill paths for an attribute, or only those to which they have access. You
determine this access using the Enable Web personalized drill paths check box in
the Project Configuration Editor, Project Definition: Drilling category. (In Developer,
right-click a project and select Project Configuration.)
With the Enable Web personalized drill paths check box cleared (and thus, XML
caching enabled), the attributes to which all users in MicroStrategy Web can drill are stored
in a report’s XML cache. In this case, users see all attribute drill paths whether they have
access to them or not. When a user selects an attribute drill path, Intelligence Server then
checks whether the user has access to the attribute. If the user does not have access (for
example, because of Access Control Lists), the drill is not performed and the user sees an
error message.
Alternatively, if you select the Enable Web personalized drill paths check box, at the
time the report results are created (not at drill time), Intelligence Server checks which
attributes the user may access and creates the report XML with only the allowed attributes.
This way, the users only see their available drill paths, and they cannot attempt a drill action
that is not allowed. With this option enabled, you may see performance degradation on
Intelligence Server. This is because it must create XML for each report/user combination
rather than using XML that was cached.
For more information about XML caching, see Types of result caches, page 441.

Controlling access to functionality: Privileges

As discussed earlier in this section, there are different types of users and groups in the user
community. It is your responsibility as a system administrator to assign privileges to users
and groups. They give you full control over the user experience.
Privileges give users access to specific MicroStrategy functionality. For example, the Create
Metric privilege allows the user to use the Metric Editor to create a new metric, and the
Monitor Caches privilege allows the user to view cache information in the Cache Monitor.

There is a special privilege called Bypass All Object Security Access Checks. Users with
this privilege can ignore the access control permissions and are considered to have full

© 2018, MicroStrategy Inc. 81

System Administration Guide

control over all objects. For information about permissions, see Controlling access to objects:
Permissions, page 73.

Based on their different privileges, the users and user groups can perform different types of
operations in the MicroStrategy system. If a user does not have a certain privilege, that user
does not have access to that privilege’s functionality. You can see which users are using
certain privileges by using License Manager (see Using License Manager, page 244).
Most privileges may be granted within a specific project or across all projects. Certain
administrative privileges, such as Configure Group Membership, do not apply to specific
projects and can only be granted at the project source level.
For a complete list of privileges and what they control in the system, see the List of Privileges
section.

Assigning privileges to users and groups

Privileges can be assigned to users and user groups directly or through security roles. The
difference is that the former grants functionality across all projects while the latter only apply
within a specified project (see Defining sets of privileges: Security roles, page 84).

To assign privileges to users or groups

1. From Developer User Manager, edit the user with the User Editor or edit the group
with the Group Editor.
2. Expand User Definition or Group Definition, and then select Project
Access.
3. Select the check boxes to grant privileges to the user or group.
Rather than assigning individual users and groups these privileges, it may be easier for you
to create Security Roles (collections of privileges) and assign them to users and groups.
Then you can assign additional privileges individually when there are exceptions. For more
information about security roles, see Defining sets of privileges: Security roles, page 84.

Assigning privileges to multiple users at once

You can grant, revoke, and replace the existing privileges of users, user groups, or security
roles with the Find and Replace Privileges dialog box. This dialog box allows you to search
for the user, user group, or security role and change their privileges, depending on the tasks
required for their work.
For example, your organization is upgrading Flash on all users’ machines. Until the time the
Flash update is completed, the users will not be able to export reports to Flash. You can use
Find and Replace Privileges to revoke the Export to Flash privilege assigned to users, and
when the upgrade is complete you can grant the privilege to the users again.
To access the Find and Replace Privileges dialog box, in Developer, right-click the User
Manager and select Find and Replace Privileges. For detailed instructions on how to
find and replace privileges, see the MicroStrategy Developer Help.

82 © 2018, MicroStrategy Inc.

 System Administration Guide

How are privileges inherited?

A user’s privileges within a given project include the following:
l Privileges assigned directly to the user (see Assigning privileges to users and groups,
page 82)
l Privileges assigned to any groups of which the user is a member (see About
MicroStrategy user groups, page 68)

Groups also inherit privileges from their parent groups.

l Privileges assigned to any security roles that are assigned to the user within the project
(see Defining sets of privileges: Security roles, page 84)
l Privileges assigned to any security roles that are assigned to a group of which the user is a
member

Predefined user groups and privileges

MicroStrategy comes with several predefined user groups. For a complete list and
explanation of these groups, see About MicroStrategy user groups, page 68. These groups
possess the following privileges:
l Everyone, Public/Guest, Third Party Users, LDAP Public/Guest, and LDAP Users, have
no predefined privileges.
l The predefined product-based user groups possess all the privileges associated with their
corresponding products. For a list of these groups, see About MicroStrategy user groups,
page 68.

International Users is a member of the following product-based groups: Analyst, Mobile

User, Web Reporter, and Web Analyst. It has the privileges associated with these groups.

l System Monitors and its member groups have privileges based on their expected roles in
the company. To see the privileges assigned to each group, right-click the group and
select Grant Access to Projects.

How predefined user groups inherit privileges

Several of the predefined user groups form hierarchies, which allow groups to inherit
privileges from any groups at a higher level within the hierarchy. These hierarchies are as
follows:
• Web Reporter
▫ Web Analyst
- Web Professional
In the case of the MicroStrategy Web user groups, the Web Analyst inherits the
privileges of the Web Reporter. The Web Professional inherits the privileges of both the

© 2018, MicroStrategy Inc. 83

System Administration Guide

Web Analyst and Web Reporter. The Web Professional user group has the complete set
of MicroStrategy Web privileges.
• Analyst
▫ Developer
In the case of the MicroStrategy Developer user groups, the Developer inherits the
privileges of the Analyst and therefore has more privileges than the Analysts.
• System Monitors
▫ various System Monitors groups
The various System Monitors user groups inherit the privileges of the System Monitors
user group and therefore have more privileges than the System Monitors. Each has its
own specific set of privileges in addition, that are not shared by the other System
Monitors groups.
• International Users
This group inherits the privileges of the Analyst, Mobile User, Web Reporter, and Web
Analyst groups.

Defining sets of privileges: Security roles

A security role is a collection of project-level privileges that are assigned to users and groups.
For example, you might have two types of users with different functionality needs: the
Executive Users who need to run, sort, and print reports, and the Business Analysts who
need additional capabilities to drill and change subtotal definitions. In this case, you can
create two security roles to suit these two different types of users.
Security roles exist at the project source level, and can be used in any project registered with
Intelligence Server. A user can have different security roles in each project. For example, an
administrator for the development project may have a Project Administrator security role in
that project, but the Normal User security role in all other projects on that server.
A security role is fundamentally different from a user group in the following ways:
l A group is a collection of users that can be assigned privileges (or security roles) all at
once, for the project source and all projects in it.
l A security role is a collection of privileges in a project. Those privileges are assigned as a
set to various users or groups, on a project-by-project basis.
For information about how privileges are inherited from security roles and groups, see
Controlling access to functionality: Privileges, page 81.

Managing security roles

The Security Role Manager lists all the security roles available in a project source. From this
manager you can assign or revoke security roles for users in projects, or create or delete
security roles. For additional methods of managing security roles, see Other ways of
managing security roles, page 86.

84 © 2018, MicroStrategy Inc.

 System Administration Guide

To assign a security role to users or groups in a project

1 In Developer, log in to the project source containing the security role. You must have the
Grant/Revoke Privileges privilege.
2 Expand Administration, then Configuration Managers, and then select
Security Roles. A list of security roles in the project source opens in the main
Developer pane.
3 Double-click the security role you want to assign to the user or group.
4 Select the Members tab.
5 From the Select a Project drop-down list, select the project for which to assign the
security role.
6 From the drop-down list of groups, select the group containing a user or group you want
to assign the security role to. The users or groups that are members of that group are
shown in the list box below the drop-down list.

— By default, users are not shown in this list box. To view the users as well
as the groups, select the Show users check box.
— To assign a top-level group to a security role, from the drop-down list
select All Groups.

7 Select a desired user or group.

8 Click the > icon. The user or group moves to the Selected members list. You can
assign multiple users or groups to the security role by selecting them and clicking the >
icon.
9 When you are finished assigning the security role, click OK.

To create a security role

1 In Developer, log in to the project source you want to create the security role in.
2 Expand Administration, then Configuration Managers, and then select
Security Roles.
3 From the File menu, point to New, and select Security Role. The Security Role
Editor opens at the General tab.
4 Enter a name and description for the new security role.
5 Select the Privileges tab.
6 Select the privileges to add to this security role. For an explanation of each privilege, see
the List of Privileges section.

To select all privileges in a privilege group, select the group.

© 2018, MicroStrategy Inc. 85

System Administration Guide

7 To assign the role to users, select the Members tab and follow the instructions in To
assign a security role to users or groups in a project, page 85.
8 Click OK.

To delete a security role

1 In Developer, log in the project source you want to remove the security role from.
2 Expand Administration, then Configuration Managers, and then select
Security Roles. A list of security roles in the project source opens in the main
Developer pane.
3 Click the security role that you want to remove.
4 From the File menu select Delete.
5 Click Yes to confirm that you want to delete the security role.

Other ways of managing security roles

You can also assign security roles to a user or group in the User Editor or Group Editor.
From the Project Access category of the editor, you can specify what security roles that
user or group has for each project.
You can assign roles to multiple users and groups in a project through the Project
Configuration dialog box. The Project Access - General category displays which users
and groups have which security roles in the project, and allows you to re-assign the security
roles.
For detailed instructions on using these editors to manage security roles, see the
MicroStrategy Developer Help.
You can also use Command Manager to manage security roles. Command Manager is a
script-based administrative tool that helps you perform complex administrative actions
quickly. For specific syntax for security role management statements in Command Manager,
see Security Role Management in the Command Manager on-line help (from Command
Manager, press F1, or select the Help menu). For general information about Command
Manager, see Chapter , Automating Administrative Tasks with Command Manager.

If you are using UNIX, you must use Command Manager to manage your system’s security
roles.

Controlling access to a project

You can deny user or group access to a specific MicroStrategy project by using a security
role.

86 © 2018, MicroStrategy Inc.

 System Administration Guide

To deny user or group access to a project

1 In Developer, right-click on the project you want to deny access to. Select Project
Configuration.
2 Expand the Project Access category.
3 In the Select a security role drop-down list, select the security role that contains the
user or group who you want to deny project access.
4 On the right-hand side of the Project access - General dialog, select the user or group
who you want to deny project access. Then click the left arrow to remove that user or
group from the security role.
5 Using the right arrow, add any users to the security role for whom you want to grant
project access. To see the users contained in each group, highlight the group and check
the Show users check box.
6 Make sure the user or group whose access you want deny does not appear in the
Selected members pane on the right-hand side of the dialog. Then click OK.
7 In Developer, under the project source that contains the project you are restricting
access to, expand Administration, then expand User Manager.
8 Click on the group to which the user belongs who you want to deny project access for.
Then double-click on the user in the right-hand side of Developer.
9 Expand User Definition, then select Project Access.
10 In the Security Role Selection row, under the project you want to restrict access to,
review the Security Role Selection drop-down list. Make sure that no security role is
associated with this project for this user.
11 Click OK.
When the user attempts to log in to the project, he receives the message “No projects were
returned by this project source.”

The role-based administration model

Beginning with version 9.0, the MicroStrategy product suite comes with a number of
predefined security roles for administrators. These roles makes it easy to delegate
administrative tasks.
For example, your company security policy may require you to keep the user security
administrator for your projects separate from the project resource administrator. Rather than
specifying the privileges for each administrator individually, you can assign the Project
Security Administrator role to one administrator, and the Project Resource Administrator to
another. Because users can have different security roles for each project, you can use the
same security role for different users in different projects to further delegate project
administration duties.
The predefined project administration roles cover every project-level administrative privilege
except for Bypass All Object Security Access Checks. None of the roles have any privileges

© 2018, MicroStrategy Inc. 87

System Administration Guide

in common. For a list of the privileges included with each predefined security role, see the
List of Privileges section.
The predefined administration security roles are:
l Power Users, which have the largest subset of privileges of any security role.
l Project Bulk Administrators, who can perform administrative functions on multiple
objects with Object Manager (see Copying objects between projects: Object Manager,
page 272), Command Manager (see Chapter , Automating Administrative Tasks with
Command Manager), and the Bulk Repository Translation Tool.
l Project Operations Administrators, who can perform maintenance on various
aspects of a project.
l Project Operations Monitors, who can view the various Intelligence Server
monitors but cannot make any changes to the monitored systems.
l Project Resource Settings Administrators, who can configure project-level
settings.
l Project Security Administrators, who create users and manage user and object
security.
For instructions on how to assign these security roles to users or groups, see Managing
security roles, page 84.

Do not modify the privileges for an out-of-the-box security role. During upgrades to newer
versions of MicroStrategy, the privileges for the out-of-the-box security roles are overwritten
with the default privileges. Instead, you should copy the security role you need to modify and
make changes to the copied version.

Controlling access to data

Access control governs the resources that an authenticated user is able to read, modify, or
write. Data is a major resource of interest in any security scheme that determines what
source data a user is allowed to access. You may be more familiar with the terms
authentication (making sure the user is who he says he is) and authorization (making sure he
can access the data he is entitled to see now that I know who he is).
The ways by which data access can be controlled are discussed below:

Controlling access to the database: Connection mappings

Connection mappings allow you to assign a user or group in the MicroStrategy system to a
login ID on the data warehouse RDBMS. The mappings are typically used to take advantage
of one of several RDBMS data security techniques (security views, split fact tables by rows,
split fact tables by columns) that you may have already created. For details on these
techniques, see Controlling access to data at the database (RDBMS) level, page 105.

88 © 2018, MicroStrategy Inc.

 System Administration Guide

Why use connection mappings?

Use a connection mapping if you need to differentiate MicroStrategy users from each other
at the data warehouse level or if you need to direct them to separate data warehouses. This
is explained in more detail below.
First it is important to know that, as a default, all users in a MicroStrategy project use the
same database connection/DSN and database login when connecting to the database. This
means that all users have the same security level at the data warehouse and therefore,
security views cannot be assigned to a specific MicroStrategy user. In this default
configuration, when the database administrator (DBA) uses an RDBMS feature to view a list
of users connected to the data warehouse, all MicroStrategy users would all appear with the
same name. For example, if forty users are signed on to the MicroStrategy system and
running jobs, the DBA sees a list of forty users called “MSTR users” (or whatever name is
specified in the default database login). This is shown in the diagram below in which all jobs
running against the data warehouse use the “MSTR users” database login.

Creating a connection mapping

You define connection mappings with the Project Configuration Editor in Developer. To
create a connection mapping, you assign a user or group either a database connection or
database login that is different from the default. For information on this, see Connecting to
the data warehouse, page 25.

To create a connection mapping

1. In Developer, log into your project. You must log in as a user with administrative
privileges.
2. Go to Administration > Projects > Project Configuration.
3. Expand the Database Instances category, and then select Connection
Mapping.
4. Right-click in the grid and select New to create a new connection mapping.

© 2018, MicroStrategy Inc. 89

System Administration Guide

5. Double-click the new connection mapping in each column to select the database
instance, database connection, database login, and language.
6. Double-click the new connection mapping in the Users column. Click ... (the browse
button).
7. Select the desired user or group and click OK. That user or group is now associated
with the connection mapping.
8. Click OK.

Connection mapping example

One case in which you may want to use connection mappings is if you have existing security
views defined in the data warehouse and you want to allow MicroStrategy users’ jobs to
execute on the data warehouse using those specific login IDs. For example,
l The CEO can access all data (warehouse login ID = “CEO”)
l All other users have limited access (warehouse login ID = “MSTR users”)
In this case, you would need to create a user connection mapping within MicroStrategy for
the CEO. To do this:
l Create a new database login definition for the CEO in MicroStrategy so it matches his or
her existing login ID on the data warehouse
l Create the new connection mapping in MicroStrategy to specify that the CEO user uses
the new database login
This is shown in the diagram below in which the CEO connects as CEO (using the new
database login called “CEO”) and all other users use the default database login “MSTR
users.”

Both the CEO and all the other users use the same project, database instance, database
connection (and DSN), but the database login is different for the CEO.

90 © 2018, MicroStrategy Inc.

 System Administration Guide

If we were to create a connection mapping in the MicroStrategy Tutorial project according to

this example, it would look like the diagram below.

For information on creating a new database connection, see Connecting to the data
warehouse, page 25. For information on creating a new database login, see Connecting to
the data warehouse, page 25.
Connection mappings can also be made for user groups and are not limited to individual
users. Continuing the example above, if you have a Managers group within the
MicroStrategy system that can access most data in the data warehouse (warehouse login ID
= “Managers”), you could create another database login and then create another connection
mapping to assign it to the Managers user group.
Another case in which you may want to use connection mappings is if you need to have
users connect to two data warehouses using the same project. In this case, both data
warehouses must have the same structure so that the project works with both. This may be
applicable if you have a data warehouse with domestic data and another with foreign data
and you want users to be directed to one or the other based on the user group to which they
belong when they log in to the MicroStrategy system.
For example, if you have two user groups such that:
l “US users” connect to the U.S. data warehouse (data warehouse login ID “MSTR users”)
l “Europe users” connect to the London data warehouse (data warehouse login ID “MSTR
users”)
In this case, you would need to create a user connection mapping within MicroStrategy for
both user groups. To do this, you would:
l Create two database connections in MicroStrategy—one to each data warehouse (this
assumes that DSNs already exist for each data warehouse)
l Create two connection mappings in the MicroStrategy project that link the groups to the
different data warehouses via the two new database connection definitions
This is shown in the diagram below.

© 2018, MicroStrategy Inc. 91

System Administration Guide

The project, database instance, and database login can be the same, but the connection
mapping specifies different database connections (and therefore, different DSNs) for the two
groups.

Linking database users and MicroStrategy users: Passthrough

execution
You can link a MicroStrategy user to an RDBMS login ID using the User Editor (on the
Authentication tab, specify the Warehouse Login and Password) or using Command
Manager. This link is required for database warehouse authentication (see Implementing
database warehouse authentication, page 221) but works for other authentication modes as
well.
You can configure each project to use either connection mappings or the linked warehouse
login ID when users execute reports, documents, or browse attribute elements. If
passthrough execution is enabled, the project uses the linked warehouse login ID and
password as defined in the User Editor (Authentication tab). If no warehouse login ID is
linked to a user, Intelligence Server uses the default connection and login ID for the project’s
database instance.
By default, warehouse passthrough execution is turned off, and the system uses connection
mappings. If no connection mapping is defined for the user, Intelligence Server uses the
default connection and login ID for the project's database instance.

92 © 2018, MicroStrategy Inc.

 System Administration Guide

Why use passthrough execution?

You may want to use passthrough execution for these reasons:
l RDBMS auditing: If you want to be able to track which users are accessing the RDBMS
system down to the individual database query. Mapping multiple users to the same
RDBMS account blurs the ability to track which users have issued which RDBMS queries.
l Teradata spool space: If you use the Teradata RDBMS, note that it has a limit for spool
space set per account. If multiple users share the same RDBMS account, they are
collectively limited by this setting.
l RDBMS security views: If you use security views, each user needs to log in to the RDBMS
with a unique database login ID so that a database security view is enforced.

Enabling linked warehouse logins

You can configure linked warehouse logins with the Project Configuration Editor in
Developer. To create a connection mapping, you assign a user or group either a database
connection or database login that is different from the default. For information on this, see
Connecting to the data warehouse, page 25.

To enable linked warehouse logins

1. In Developer, log into your project. You must log in as a user with administrative
privileges.
2. From the Administration menu, point to Projects, and select Project
Configuration.
3. Expand the Database Instances category, expand Authentication, and then
select Warehouse.
4. Select the Use warehouse pass-through credentials check box.
5. To use warehouse credentials for all database instances, select the For all
database instances option.
6. To use warehouse credentials for specific database instances, select the For
selected database instances option. Then select those database instances from
the list below.
7. Click OK.

Restricting access to data: Security filters

Security filters enable you to control what warehouse data users can see when that data is
accessed through MicroStrategy. A security filter can be assigned to a user or group to
narrow the result set when they execute reports or browse elements. The security filter
applies to all reports and documents, and all attribute element requests, submitted by a user.

© 2018, MicroStrategy Inc. 93

System Administration Guide

For example, two regional managers can have two different security filters assigned to them
for their regions: one has a security filter assigned to her that only shows the data from the
Northeast region, and the other has a security filter that only shows data from the Southwest
region. If these two regional managers run the same report, they may see different report
results.
Security filters serve a similar function to database-level techniques such as database views
and row level security. For information about controlling data security at the data warehouse
level, see Controlling access to data at the database (RDBMS) level, page 105.
For more information about security filters, see the following:
• Security filter example, page 94
• How security filters work, page 95
• Creating and applying a security filter, page 95
• Security filters and metric levels, page 96
• Using a single security filter for multiple users: System prompts, page 103
• Merging security filters, page 100

Security filter example

A user in the MicroStrategy Tutorial project has a security filter defined as Subcategory=TV.
When this user browses the Product hierarchy beginning with the Category attribute, she
only sees the Electronics category. Within the Electronics category, she sees only the TV
subcategory. Within the TV subcategory, she sees all Items within that subcategory.
When this user executes a simple report with Category, Subcategory, and Item in the rows,
and Revenue in the columns, only the Items from the TV Subcategory are returned, as
shown in the example below.

94 © 2018, MicroStrategy Inc.

 System Administration Guide

If this user executes another report with Category in the rows and Revenue in the columns,
only the Revenue from the TV Subcategory is returned, as shown in the example below. The
user cannot see any data from attribute elements that are outside the security filter.

How security filters work

Security filters are the same as regular filters except that they can contain only attribute
qualifications, custom expressions, and joint element lists. Relationship filters and metric
qualifications are not allowed in a security filter. A security filter can include as many
expressions as you need, joined together by logical operators. For more information on
creating filters, see the Filters section in the Basic Reporting Guide.
A security filter comes into play when a user is executing reports and browsing elements.
The qualification defined by the security filter is used in the WHERE clause for any report that
is related to the security filter’s attribute. By default, this is also true for element browsing:
when a user browses through a hierarchy to answer a prompt, she only sees the attribute
elements that the security filter allows her to see. For instructions on how to disable security
filters for element browsing, see To disable security filters for element browsing, page 96.
Security filters are used as part of the cache key for report caching and element caching.
This means that users with different security filters cannot access the same cached results,
preserving data security. For more information about caching, see Chapter , Improving
Report and Document Response Time: Caching.
Each user or group can be directly assigned only one security filter for a project. Users and
groups can be assigned different security filters for different projects. In cases where a user
inherits one or more security filters from any groups that she belongs to, the security filters
may need to be merged. For information about how security filters are merged, see Merging
security filters, page 100.

Creating and applying a security filter

You create and apply security filters in the Security Filter Manager. Make sure you inform
your users of any security filters assigned to them or their group. If you do not inform them of
their security filters, they may not know that the data they see in their reports has been
filtered, which may cause misinterpretation of report results.

To create security filters, you must have the following privileges:

l Create Application Objects (under the Common Privileges privilege group)
l Use Report Filter Editor (under the Developer privilege group)
l Use Security Filter Manager (under the Administration privilege group)

© 2018, MicroStrategy Inc. 95

System Administration Guide

1. To create and apply a security filter for a user or group

2. In Developer, from the Administration menu, point to Projects and then select
Security Filter Manager.
3. From the Choose a project drop-down list, select the project that you want to
create a security filter for.
4. Select the Security Filters tab.
5. Select one:
l To create a new security filter, click New. The Security Filter Editor opens. For
instructions on how to use this editor to create a filter, see the MicroStrategy
Developer Help.
l OR, to convert an existing filter into a security filter, click Import. Browse to the
filter you want to convert and click Open. Specify a name and location for the new
security filter and click Save.
6. In the left side of the Security Filter Manager, in the Security Filters tab, browse to
the security filter that you want to apply, and select that security filter.
7. In the right side of the Security Filter Manager, select Security Filters.
8. Browse to the user or group that you want to apply the security filter to, and select that
user or group.
9. Click > to apply the selected security filter to the selected user or group.
10. Click OK.

To disable security filters for element browsing

1. In Developer, log into a project. You must log in with a user account that has
administrative privileges.
2. From the Administration menu, point to Projects, and then select Project
Configuration.
3. Expand the Project Definition category, and then select Advanced.
4. Under Attribute element browsing, clear the Apply security filters to
element browsing check box.
5. Click OK.
6. Restart Intelligence Server for your changes to take effect.

Security filters and metric levels

In certain situations involving level metrics, users may be able to see a limited amount of data
from outside their security filter. Specifically, if a metric is defined with absolute filtering on a
level above that used in the security filter’s expression, the filter expression is raised to the
metric’s level. For information about metric levels and filtering in metrics, see the Metrics
section in the Advanced Reporting Guide.

96 © 2018, MicroStrategy Inc.

 System Administration Guide

For example, consider a metric called Category Revenue that is defined to return the
revenue across all items in each category. Its level expression is Target=Category,
Filtering=Absolute. When a user with a security filter Subcategory=TV executes a report
with the Category Revenue metric, the Category Revenue metric displays the total revenue
for the category. The user’s security filter is effectively changed to show the entire Category
in which TV is a Subcategory.
This behavior can be modified by using the top range attribute and bottom range attribute
properties.
l A top range attribute specifies the highest level of detail in a given hierarchy that the
security filter allows the user to view. If a top range attribute is specified, the security filter
expression is not raised to any level above the top range.
l A bottom range attribute specifies the lowest level of detail in a given hierarchy that
the security filter allows the user to view. If this is not specified, the security filter can view
every level lower than the specified top range attribute, as long as it is within the
qualification defined by the filter expression.

The top and bottom range attributes can be set to the same level.

For instructions on how to assign range attributes to security filters, see Assigning a top or
bottom range attribute to a security filter, page 99.
The examples below use a report with Category, Subcategory, and Item on the rows, and
three metrics in the columns:
l Revenue
l Subcategory Revenue, which is defined with absolute filtering to the Subcategory level
l Category Revenue, which is defined with absolute filtering to the Category level
The user executing this report has a security filter that restricts the Subcategory to the TV
element.

No top or bottom range attribute

If no top or bottom range attribute is specified, then at the level of the security filter
(Subcategory) and below, the user cannot see data outside his or her security filter. Above
the level of the security filter, the user can see data outside the security filter if it is in a metric
with absolute filtering for that level. Even in this case, the user sees only data for the
Category in which his or her security filter is defined.
In the example report below, the user’s security filter does not specify a top or bottom range
attribute. Item-level detail is displayed for only the items within the TV category. The
Subcategory Revenue is displayed for all items within the TV subcategory. The Category
Revenue is displayed for all items in the Category, including items that are not part of the TV
subcategory. However, only the Electronics category is displayed. This illustrates how the
security filter Subcategory=TV is raised to the category level such that Category=Electronics
is the filter used with Category Revenue.

© 2018, MicroStrategy Inc. 97

System Administration Guide

Top range attribute: Subcategory

If a top range attribute is specified, then the user cannot see any data outside of her security
filter. This is true even at levels above the top level, regardless of whether metrics with
absolute filtering are used.
In the example report below, the user’s security filter specifies a top range attribute of
Subcategory. Here, the Category Revenue is displayed for only the items within the TV
subcategory. The security filter Subcategory=TV is not raised to the Category level, because
Category is above the specified top level of Subcategory.

98 © 2018, MicroStrategy Inc.

 System Administration Guide

Bottom range attribute: Subcategory

If a bottom range attribute is specified, the user cannot see data aggregated at a lower level
than the bottom level.
In the example report below, the user’s security filter specifies a bottom range attribute of
Subcategory. Item-level detail is not displayed, because Item is a level below the bottom
level of Subcategory. Instead, data for the entire Subcategory is shown for each item. Data
at the Subcategory level is essentially the lowest level of granularity the user is allowed to
see.

Assigning a top or bottom range attribute to a security filter

You assign top and bottom range attributes to security filters in the Security Filter Manager.
You can assign range attributes to a security filter for all users, or to the security filters per
user.
You can assign the same attribute to a security filter as a top and bottom range attribute. A
security filter can have multiple top or bottom range attributes as long as they are from
different hierarchies. You cannot assign multiple attributes from the same hierarchy to either
a top or bottom range. However, you can assign attributes from the same hierarchy if one is
a top range attribute and one is a bottom range attribute. For example, you can assign
Quarter (from the Time hierarchy) and Subcategory (from the Products hierarchy) as top
range attributes, and Month (from the Time hierarchy) and Subcategory as bottom range
attributes.

To modify security filters, you must have the Use Security Filter Manager privilege.

© 2018, MicroStrategy Inc. 99

System Administration Guide

To assign a top or bottom range attribute to a security filter

1 In Developer, from the Administration menu, point to Projects and then select
Security Filter Manager.
2 From the Choose a project drop-down list, select the project that you want to modify
security filters for.
3 Select the Attributes tab.
4 Browse to the attribute that you want to set as a top or bottom range attribute, and select
that attribute.
5 To apply a top or bottom range attribute to a security filter for all users:
a In the right side of the Security Filter Manager, select Security Filters.
b Browse to the security filter that you want to apply the range attribute to.
c Expand that security filter, and select either the Top range attributes or
Bottom range attributes folder.
d Click > to apply the selected attribute to the selected security filter.
6 To apply a top or bottom range attribute to a security filter for a single user or group:
a In the right side of the Security Filter Manager, select Groups/Users.
b Browse to the user or group that you want to apply the range attribute to.
c Expand that user or group and select the security filter that you want to apply the
range attribute to.
d Expand that security filter, and select either the Top range attributes or
Bottom range attributes folder.
e Click > to apply the selected attribute to the selected security filter for the selected
user or group.
7 Click OK.

Merging security filters

A user can be assigned a security filter directly, and can inherit a security filter from any
groups that she belongs to. Because of this, multiple security filters may need to be merged
when executing reports or browsing elements.
MicroStrategy supports the following methods of merging security filters:
l Merging related security filters with OR and unrelated security filters with AND, page 101
(This is the default method for merging security filters)
l Merging all security filters with AND, page 102

100 © 2018, MicroStrategy Inc.

 System Administration Guide

For the examples in these sections, consider a project with the following user groups and
associated security filters:

Group Security Filter Hierarchy

Electronics Category = Electronics Product

Drama Subcategory = Drama Product
Movies Category = Movies Product
Northeast Region = Northeast Geography

You control how security filters are merged at the project level. You can change the merge
settings in the Project Configuration Editor for the selected project, in the Security Filter
category. After making any changes to the security filter settings, you must restart
Intelligence Server for those changes to take effect.

Changing how security filters are merged does not automatically invalidate any result caches
created for users who have multiple security filters. MicroStrategy recommends that you
invalidate all result caches in a project after changing how security filters are merged for that
project. For instructions on how to invalidate all result caches in a project, see Managing
result caches, page 450.

Merging related security filters with OR and unrelated security filters with AND
By default, security filters are merged with an OR if they are related, and with an AND if they
are not related. That is, if two security filters are related, the user can see all data available
from either security filter. However, if the security filters are not related, the user can see only
the data available in both security filters.
Two security filters are considered related if the attributes that they derive from belong in the
same hierarchy, such as Country and Region, or Year and Month. In the example security
filters given above, the Electronics, TV, and Movies security filters are all related, and the
Northeast security filter is not related to any of the others.
Using this merge method, a user who is a member of both the Electronics and Drama groups
can see data from the Electronics category and the Drama subcategory, as shown below:

A user who is a member of both the Movies and Drama groups can see data from all
subcategories in the Movies category, not just the Drama subcategory. A user who is a
member of both the Electronics and Drama categories can see data from both categories.

© 2018, MicroStrategy Inc. 101

System Administration Guide

If a user who is a member of the Movies and Northeast groups executes a report with
Region, Category, and Subcategory in the rows, only data from the Movies category in the
Northeast region is shown, as seen below:

Data for the Movies category from outside the Northeast region is not available to this user,
nor is data for the Northeast region for other categories.

Merging all security filters with AND

You can also configure Intelligence Server to always merge security filters with an AND,
regardless of whether they are related.
As in the first method, a user who is a member of both the Movies and Northeast groups
would see only information about the Movies category in the Northeast region.
A user who is a member of both the Movies and Drama groups would see only data from the
Drama subcategory of Movies, as shown below:

Data for the other subcategories of Drama is not available to this user.
This setting may cause problems if a user is a member of two mutually exclusive groups. For
example, a user who is a member of both the Movies and Electronics groups cannot see any
data from the Product hierarchy, because that hierarchy does not contain any data that
belongs to both the Movies and Electronics categories.

To configure how security filters are merged, you must have the Configure Project Basic
privilege.

To configure how Intelligence Server merges multiple security filters

for a user or group

1 In Developer, log into a project. You must log in as a user with administrative privileges.
2 From the Administration menu, point to Projects, and then select Project
Configuration.
3 Expand the Security Filter category, and then select General.

102 © 2018, MicroStrategy Inc.

 System Administration Guide

4 Under Security Filter Merge Options, select one of the options:

• Union (OR) Security Filters on related attributes, intersect (AND)
Security Filters on unrelated attributes (see Merging related security filters
with OR and unrelated security filters with AND, page 101)
• Intersect (AND) all Security Filters (see Merging all security filters with
AND, page 102)
5 Click OK.
6 Restart Intelligence Server for your changes to take effect.

Using a single security filter for multiple users: System prompts

A system prompt is a special type of prompt that does not require an answer from the user.
Instead, it is answered automatically by Intelligence Server. System prompts are in the
Public Objects/Prompts/System Prompts folder in Developer.

• Like other prompt objects, answers to system prompts are used to match
caches. Therefore, users do not share caches for reports that contain
different answers to system prompts.
• The system prompts Token 1, Token 2, Token 3, and Token 4 are provided
to support using an XQuery source to authenticate users for a MicroStrategy
project. For steps to report on and authenticate using XQuery sources, see
the Advanced Reporting Guide.

The User Login prompt is a system prompt that is automatically answered with the login
name of the user who executes the object containing the prompt. It can provide flexibility
when implementing security mechanisms in MicroStrategy. You can use this prompt to insert
the user’s login name into any security filter, or any other object that can use a prompt.
If you are using LDAP authentication in your MicroStrategy system, you can import LDAP
attributes into your system as system prompts. You can then use these system prompts in
security filters, in the same way that you use the User Login system prompt, as described
above. For instructions on how to import LDAP attributes as system prompts, see Managing
LDAP authentication, page 136.
For examples of how to use system prompts in security filters, see:
l Simplifying the security filter definition process, page 104
l Implementing a report-level security filter, page 104
l Using database tables that contain security information, page 104

To create a security filter using a system prompt

1. In Developer, from the Administration menu, point to Projects and then select
Security Filter Manager.

© 2018, MicroStrategy Inc. 103

System Administration Guide

2. From the Choose a project drop-down list, select the project that you want to
create a security filter for.
3. Select the Security Filters tab.
4. Click New.
5. Double-click on the text Double-click here to add a qualification.
6. Select Add an advanced qualification and click OK.
7. From the Option drop-down list, select Custom Expression.
8. Type your custom expression in the Custom Expression area. You can drag and
drop a system prompt or other object to include it in the custom expression. For
detailed instructions on creating custom expressions in filters, see the Filters section of
the Advanced Reporting Guide.
9. When you have finished typing your custom expression, click Validate to make sure
that its syntax is correct.
10. Click Save and close. Type a name for the security filter and click Save.

Simplifying the security filter definition process

You can use a system prompt to apply a single security filter to all users in a group. For
example, you can create a security filter using the formula User@ID=?[User Login] that
displays information only for the element of the User attribute that matches the user’s login.
For a more complex example, you can restrict Managers so that they can only view data on
the employees that they supervise. Add the User Login prompt to a security filter in the form
Manager=?[User Login]. Then assign the security filter to the Managers group. When
a manager named John Smith executes a report, the security filter generates SQL for the
condition Manager='John Smith' and only John Smith’s employees’ data is returned.

Implementing a report-level security filter

You can also use the User Login system prompt to implement security filter functionality at
the report level, by defining a report filter with a system prompt. For example, you can define
a report filter with the User Login prompt in the form Manager=?[User Login]. Any
reports that use this filter return data only to those users who are listed as Managers in the
system.

Using database tables that contain security information

If your organization maintains security information in database tables, you can use a system
prompt to build MicroStrategy security mechanisms using the database security tables. For
example, you can restrict the data returned based on a user’s login by creating a report filter
that accesses columns in your security tables and includes the User Login system prompt.
You can also restrict data access based on two or more unrelated attributes by using logical
views (database views) and the User Login system prompt in a security filter. For more
information, including detailed instructions, on how to implement these examples, see
MicroStrategy Tech Note TN11351.

104 © 2018, MicroStrategy Inc.

 System Administration Guide

Controlling access to data at the database (RDBMS) level

Database servers have their own security architectures that provide authentication, access
control, and auditing. As mentioned above, you may choose to use these RDBMS
techniques to manage access to data, or you may choose to use mechanisms in the
MicroStrategy application layer to manage access to data, or you may use a combination of
the two. They are not mutually exclusive. One advantage of using the database-level security
mechanisms to secure data is that all applications accessing the database benefit from those
security measures. If only MicroStrategy mechanisms are used, then only those users
accessing the MicroStrategy application benefit from those security measures. If other
applications access the database without going through the MicroStrategy system, the
security mechanisms are not in place.

Security views
Most databases provide a way to restrict access to data. For example, a user may be able to
access only certain tables, or he may be restricted to certain rows and columns within a
table. The subset of data available to a user is called the user’s security view.
Security views are often used when splitting fact tables by columns and splitting fact tables
by rows (discussed below) cannot be used. The rules that determine which rows each user
is allowed to see typically vary so much that users cannot be separated into a manageable
number of groups. In the extreme, each user is allowed to see a different set of rows.
Note that restrictions on tables, or rows and columns within tables, may not be directly
evident to a user. However, they do affect the values displayed in a report. You need to
inform users as to which data they can access so that they do not inadvertently run a report
that yields misleading final results. For example, if a user has access to only half of the sales
information in the data warehouse but runs a summary report on all sales, the summary
reflects only half of the sales. Reports do not indicate the database security view used to
generate the report.
Consult your database vendor’s product documentation to learn how to create security views
for your database.

Splitting fact tables by rows

You can split fact tables by rows to separate a logical data set into multiple physical tables
based on values in the rows (this is also known as table partitioning). The resultant tables are
physically distinct tables in the data warehouse, and security administration is simple
because permissions are granted to entire tables rather than to rows and columns.
If the data to be secured can be separated by rows, then this may be a useful technique. For
example, suppose a fact table contains the key Customer ID, Address, Member Bank and
two fact columns, as shown below:

Customer Customer Member Bank Transaction Amount Current Balance

ID Address ($) ($)

123456 12 Elm St. 1st National 400.80 40,450.00

© 2018, MicroStrategy Inc. 105

System Administration Guide

Customer Customer Member Bank Transaction Amount Current Balance

ID Address ($) ($)

945940 888 Oak St. Eastern 150.00 60,010.70

Credit
908974 45 Crest Dr. People’s 3,000.00 100,009.00
Bank
886580 907 Grove Rd. 1st National 76.35 10,333.45
562055 1 Ocean Blvd. Eastern 888.50 1,000.00
Credit

You can split the table into separate tables (based on the value in Member Bank), one for
each bank: 1st National, Eastern Credit, and so on. In this example, the table for 1st National
bank would look like this:

Customer Customer Member Bank Transaction Amount Current Balance

ID Address ($) ($)

123456 12 Elm St. 1st 400.80 40,450.00

National
886580 907 Grove Rd. 1st 76.35 10,333.45
National

The table for Eastern Credit would look like this:

Customer Customer Member Bank Transaction Amount Current Balance

ID Address ($) ($)

945940 888 Oak St. Eastern 150.00 60,010.70

Credit
562055 1 Ocean Blvd. Eastern 888.50 1,000.00
Credit

This makes it simple to grant permissions by table to managers or account executives who
should only be looking at customers for a certain bank.
In most RDBMSs, split fact tables by rows are invisible to system users. Although there are
many physical tables, the system “sees” one logical fact table.
Support for Split fact tables by rows for security reasons should not be confused with the
support that Intelligence Server provides for split fact tables by rows for performance
benefits. For more information about partitioning, see the Advanced Reporting Guide.

106 © 2018, MicroStrategy Inc.

 System Administration Guide

Splitting fact tables by columns

You can split fact tables by columns to separate a logical data set into multiple physical tables
by columns. If the data to be secured can be separated by columns, then this may be a useful
technique.
Each new table has the same primary key, but contains only a subset of the fact columns in
the original fact table. Splitting fact tables by columns allows fact columns to be grouped
based on user community. This makes security administration simple because permissions
are granted to entire tables rather than to columns. For example, suppose a fact table
contains the key labeled Customer ID and fact columns as follows:

Customer Customer Member Transaction Amount Current Balance

ID Address Bank ($) ($)

You can split the table into two tables, one for the marketing department and one for the
finance department. The marketing fact table would contain everything except the financial
fact columns as follows:

Customer Customer Member

ID Address Bank

The second table used by the financial department would contain only the financial fact
columns but not the marketing-related information as follows:

Customer Transaction Current Balance

ID Amount ($) ($)

Merging users or groups

Within a given project source, you may need to combine multiple users into one user
definition or combine a user group into another user group. For example, if UserA is taking
over the duties of UserB, you may want to combine the users by merging UserB’s properties
into UserA. The MicroStrategy User Merge Wizard merges multiple users or groups and
their profiles into a single user or group, with a single profile.
Topics covered in this section include:

© 2018, MicroStrategy Inc. 107

System Administration Guide

How users and groups are merged

The User Merge Wizard combines users and their related objects, from a single project
source. These objects include profile folders, group memberships, user privileges, security
roles, and security filters, among others. Information from the user or group that is being
merged is copied to the destination user or group. Then the user or group that is being
merged is removed from the metadata and only the destination user or group remains.
For example, you want to merge UserB into UserA. In this case UserA is referred to as the
destination user. In the wizard, this is shown in the image below:

When you open the User Merge Wizard and select a project source, the wizard locks that
project configuration. Other users cannot change any configuration objects until you close the
wizard. For more information about locking and unlocking projects, see Locking projects,
page 271.

You can also merge users in batches if you have a large number of users to merge. Merging
in batches can significantly speed up the merge process. Batch-merging is an option in the
User Merge Wizard. Click Help for details on setting this option.
The User Merge Wizard automatically merges the following properties: privileges, group
memberships, profile folders, and object ownership (access control lists). You may optionally
choose to merge properties such as a user’s or group’s security roles, security filters, and
database connection maps. Details about how the wizard merges each of these properties
are discussed below.

Merging user privileges

The User Merge Wizard automatically merges all of a user’s or group’s privileges. To
continue with the example above, before the users are merged, each user has a distinct set
of global user privileges. After the merge, all privileges that had been assigned to UserB are
combined with those of the destination user, UserA. This combination is performed as a
union. That is, privileges are not removed from either user.
For example, if UserA has the Web user privilege and UserB has the Web user and Web
Administration privileges, after the merge, UserA has both Web user and Web
Administration privileges.

Merging user group memberships

The User Merge Wizard automatically merges all of a user’s or group’s group memberships.
Before the merge, each user has a distinct set of group memberships. After the merge, all
group memberships that were assigned to UserB are combined with those of the destination
user, UserA. This combination is performed as a union. That is, group memberships are not
removed for either user.

108 © 2018, MicroStrategy Inc.

 System Administration Guide

Merging user profile folders

The User Merge Wizard automatically merges all of a user’s or group’s profile folders. Before
the merge, UserA and UserB have separate and distinct user profile folders. After UserB is
merged into UserA, only UserA exists; her profile contains the profile folder information from
both UserA and UserB.

Merging object ownership and access control lists

The User Merge Wizard automatically merges all of a user’s or group’s object ownerships
and access control lists (ACLs). Before the merge, the user to be merged, UserB, owns the
user objects in her profile folder and also has full control over the objects in the access control
list. After the merge, ownership and access to the merged user’s objects are granted to the
destination user, UserA. The merged user is removed from the object’s ACL. Any other
users that existed in the ACL remain in the ACL. For example, before the merge, UserB
owns an object that a third user, UserC has access to. After the merge, UserA owns the
object, and UserC still has access to it.

Merging project security roles

The User Merge Wizard does not automatically merge a user’s or group’s security roles. To
merge them, you must select the Security Roles check box on the Merge Options page in
the wizard. Before the merge, both users have unique security roles for a given project. After
the merge, the destination user profile is changed based on the following rules:
• If neither user has a security role for a project, the destination user does not have a
security role on that project.
• If the destination user has no security role for a project, the user inherits the role
from the user to be merged.
• If the destination user and the user to be merged have different security roles, then
the existing security role of the destination user is kept.
• If you are merging multiple users into a single destination user and each of the users
to be merged has a security role, then the destination user takes the security role of
the first user to be merged. If the destination user also has a security role, the
existing security role of the destination user is kept.

Merging project security filters

The User Merge Wizard does not automatically merge a user’s or group’s security filters. To
merge them, you must select the Security Filters check box on the Merge Options page
in the wizard. When merging security filters, the wizard follows the same rules as for security
roles, described above.

Merging database connection mapping

The User Merge Wizard does not automatically merge a user’s or group’s database
connection maps. To merge them, you must select the Connection Mapping check box

© 2018, MicroStrategy Inc. 109

System Administration Guide

on the Merge Options page in the wizard. When merging database connection mappings,
the wizard follows the same rules as for security roles and security filters, described above.

Running the User Merge Wizard

The following high-level procedure provides an overview of what the User Merge Wizard
does. For an explanation of the information required at any given page in the wizard, click
Help, or press F1.

To merge users or groups

1. From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select User Merge Wizard.
2. Specify the project source containing the users/groups you want to merge.
3. Select whether you want to merge optional user properties such as security roles,
security filters, and database connection maps. For a description of how the User
Merge Wizard merges these optional properties, see each individual property’s
section in How users and groups are merged, page 108.
4. Specify whether you want to have the wizard select the users/groups to merge
automatically (you can verify and correct the merge candidates), or if you want to
manually select them.
5. In the User Merge Candidates page, select the destination users or groups and click >
to move them to the right-hand side.
6. Select the users or groups to be merged and click > to move them to the right-hand
side.
7. Click Finish.

110 © 2018, MicroStrategy Inc.

 3
Identifying Users: Authentication
Authentication is the process by which the system identifies the user. In most cases, a user
provides a login ID and password which the system compares to a list of authorized logins
and passwords. If they match, the user is able to access certain aspects of the system,
according to the access rights and application privileges associated with the user.

Workflow: changing authentication modes

The following is a list of high-level tasks that you perform when you change the default
authentication mode in your MicroStrategy installation.
• Choose an authentication mode, and set up the infrastructure necessary to support it.
For example, if you want to use LDAP Authentication, you must set up your LDAP
directory and server. For the modes of authentication available, see Modes of
authentication, page 112.
• Import your user database into the MicroStrategy metadata, or link your users’ accounts
in your user database with their accounts in MicroStrategy. For example, you can import
users in your LDAP directory into the MicroStrategy metadata, and ensure that their
LDAP credentials are linked to the corresponding MicroStrategy users. Depending on
the authentication mode you choose, the following options are available:
▫ If your organization’s users do not exist in the MicroStrategy metadata:
— You can import their accounts from an LDAP directory, or from a text file. For
the steps to import users, refer to the System Administration Help in Developer.
— You can configure Intelligence Server to automatically import users into the
metadata when they log in.
▫ If your organization’s users already exist in the MicroStrategy metadata:
— You can use a Command Manager script to edit the user information in the
metadata, and link the users’ MicroStrategy accounts to their accounts in your
user directory.
• Enable your chosen authentication mode for MicroStrategy applications at the following
levels:
▫ Your web server, for example, IIS or Apache.
▫ Your application server, for example, IIS or WebSphere.

© 2018, MicroStrategy Inc. 111

System Administration Guide

▫ In Web Administrator, on the Default Server Properties page.

▫ In Mobile Administrator, on the Default Server Properties page.
▫ For all project sources that the above applications connect to.
The specific steps to implement an authentication mode depend on the mode you
choose, and are described in the sections that follow.

Modes of authentication
Several authentication modes are supported in the MicroStrategy environment. The main
difference between the modes is the authentication authority used by each mode. The
authentication authority is the system that verifies and accepts the login/password
credentials provided by the user.
The available authentication modes for MicroStrategy Library are:
l Standard: Intelligence Server is the authentication authority. This is the default
authentication mode. For more information, see Implementing standard authentication,
page 114. the System Administration Guide.
l Anonymous: Users log in as “Guest” and do not need to provide a password. This
authentication mode may be required to enable other authentication modes, such as
database warehouse or LDAP. For more information, see Implementing anonymous
authentication, page 115. the System Administration Guide.
l Database warehouse: The data warehouse database is the authentication authority.
For more information, see Implementing database warehouse authentication, page 221.
l LDAP (lightweight directory access protocol): An LDAP server is the
authentication authority. For more information, see Implementing LDAP authentication,
page 116.Setting up LDAP authentication in MicroStrategy Web, Library, and Mobile
l Single sign-on: Single sign-on encompasses several different third-party authentication
methods, including:
l SAML authentication: A two way authentication set up between your MicroStrategy
server and a SAML Identity Provider. For more information, see Enabling Single Sign-
on with SAML Authentication.
l Integrated authentication: A domain controller using Kerberos authentication is
the authentication authority. For more information, see Enabling integrated
authentication.
l Windows authentication: Windows is the authentication authority. For more
information, see Implementing Windows NT authentication, page 196.
l Third-party authentication: A third-party single sign-on tool, such as IBM®
Tivoli® Access Manager, CA SiteMinder®, or Oracle® Access Manager, is the
authentication authority. For more information, see Enabling Single Sign-on to Web,
Mobile, and Office with third-party authentication, page 202.
l Usher Security: Users log into Web and Mobile using Usher Security. Usher enables
users to electronically validate their identity using the Usher app and mobile badge on their

112 © 2018, MicroStrategy Inc.

 System Administration Guide

smartphone, instead of entering a password. For steps, see Enabling Usher

authentication for Web and Mobile, page 218.
For examples of situations where you might want to implement specific authentication
modes, and the steps to do so, see Authentication examples, page 223.

Configuring the authentication mode for a project source

You can configure a project source to use a specific authentication mode using the Project
Source Manager. By default, project sources use standard authentication (see Implementing
standard authentication, page 114).

To configure the authentication mode for a project source

1. In Developer, from the Tools menu, select Project Source Manager.

2. Select the appropriate project source and click Modify.
3. On the Advanced tab, select the appropriate option for the default authentication
mode that you want to use.
4. Click OK twice.
5. If the project source is accessed via MicroStrategy Web or MicroStrategy Office, there
are additional steps that must be followed to configure the authentication mode, as
follows:
l To set the authentication mode in MicroStrategy Web, use the MicroStrategy Web
Administrator’s Default Server Properties page. For detailed instructions, see the
MicroStrategy Web Help. (Click Help from the MicroStrategy Web Administrator
page.)
l To set the authentication mode in MicroStrategy Office, use the
projectsources.xml file. For detailed instructions, see the MicroStrategy
Office User Guide.

Importing users from different authentication systems

You can import users from multiple different authentication systems, such as from a
database warehouse and from an LDAP Server, into a single MicroStrategy metadata.
Each user that is imported into MicroStrategy from a single authentication mechanism is
created as a separate user object in the MicroStrategy metadata. For example, if User A is
imported from your LDAP Server into MicroStrategy, the User A object is created in the
MicroStrategy metadata. If User A is also imported from your NT system, a separate User A
object (we can call it User A-NT) is created in the metadata. Every time a user is imported
into the MicroStrategy metadata, a separate user object is created.
As an alternative, you can import User A from a single authentication system (LDAP, for
example), and then link the User A object that is created to the same user in your NT system,
and to the same user in your database warehouse, and so on. Using linking, you can

© 2018, MicroStrategy Inc. 113

System Administration Guide

“connect” or map multiple authentication systems to a single user object in the MicroStrategy
metadata.

Sharing user accounts between users

MicroStrategy does not recommend sharing user accounts.

You may decide to map several users to the same MicroStrategy user account. These users
would essentially share a common login to the system. Consider doing this only if you have
users who do not need to create their own individual objects, and if you do not need to
monitor and identify each individual user uniquely.

Implementing standard authentication

Standard authentication is the default authentication mode and the simplest to set up. Each
user has a unique login and password and can be identified in the MicroStrategy application
uniquely.
By default, all users connect to the data warehouse using one RDBMS login ID, although
you can change this using Connection Mapping. For more information, see Connecting to
the data warehouse, page 25. In addition, standard authentication is the only authentication
mode that allows a user or system administrator to change or expire MicroStrategy
passwords.
When using standard authentication, Intelligence Server is the authentication authority.
Intelligence Server verifies and accepts the login and password provided by the user. This
information is stored in the metadata repository.
When a project source is configured to use standard authentication, users must enter a valid
login ID and password combination before they can access the project source.

Password policy
A valid password is a password that conforms to any specifications you may have set. You
can define the following characteristics of passwords:
• Whether a user must change his password when he first logs into MicroStrategy
• How often the password expires
• The number of past passwords that the system remembers, so that users cannot use the
same password
• Rules for password complexity, including:
▫ The minimum number of characters that the password must contain
▫ The minimum number of upper-case characters that the password must contain
▫ The minimum number of lower-case characters that the password must contain

114 © 2018, MicroStrategy Inc.

 System Administration Guide

▫ The minimum number of numeric characters, that is, numbers from 0 to 9, that the
password must contain
▫ The minimum number of special characters, that is, symbols, that the password
must contain
The expiration settings are made in the User Editor and can be set for each individual user.
The complexity and remembered password settings are made in the Security Policy Settings
dialog box, and affect all users. For detailed information about configuring these settings, see
the MicroStrategy Developer Help.

Steps to implement standard authentication

The procedure below gives the high-level steps for configuring your Intelligence Server for
standard authentication. For additional information about any of these steps, see the
MicroStrategy Developer Help.

High-level steps to configuration standard authentication

1 In Developer, open the Project Source Manager and click Modify.

2 On the Advanced tab, select Use login ID and password entered by the user
(standard authentication). (This is the default setting.)
3 In MicroStrategy Web, log in as an administrator. On the Preferences page, select
Project Defaults, select Security, and then enable Standard (user name &
password) as the login mode.
4 In Developer, create a database instance for the data warehouse and assign it a default
database login. This is the RDBMS account that will be used to execute reports from all
users.

Implementing anonymous authentication

When using anonymous authentication, users log in as guests and do not need to provide a
password. Each guest user assumes the profile defined by the Public group. When a user
logs in as a guest, a new user is created dynamically and becomes a member of the Public
group.

This dynamically created guest user is not the same as the “Guest” user which is visible in
the User Manager.

Guest users inherit security settings, including privileges and permissions, project access,
security filter, and connection map information, from the Public/Guest group; they are not
part of the Everyone group.
By default, guest users have no privileges; you must assign this group any privileges that you
want the guest users to have. Privileges that are grayed out in the User Editor are not
available by default to a guest user. Other than the unavailable privileges, you can determine
what the guest user can and cannot do by modifying the privileges of the Public/Guest user
group and by granting or denying it access to objects. For more information, see Controlling

© 2018, MicroStrategy Inc. 115

System Administration Guide

access to functionality: Privileges, page 81 and Controlling access to objects: Permissions,

page 73.
All objects created by guest users must be saved to public folders and are available to all
guest users. Guest users may use the History List, but their messages in the History List are
not saved and are purged when the guest users log out.

To enable anonymous access to a project source

By default, anonymous access is disabled at both the server and the project levels.

1. In Developer, log into the project source with a user that has administrative privileges.
2. From the folder List, select Administration.
3. From the File menu, select Properties.
4. In the Security tab, click Add.
5. Select the Public/Guest group.
6. In the Access Permission list, select Connect.
7. Click OK.
8. Click OK.
9. Follow the procedure in Configuring the authentication mode for a project source,
page 113 and select Anonymous authentication. When users log into this
project source, they are now automatically logged in as guest users and not prompted
for a login or password.

Implementing LDAP authentication

Lightweight Directory Access Protocol (LDAP) is an open standard Internet protocol running
over TCP/IP that is designed to maintain and work with large user directory services. It
provides a standard way for applications to request and manage user and group directory
information. LDAP performs simple Select operations against large directories, in which
the goal is to retrieve a collection of attributes with simple qualifications, for example,
Select all the employees’ phone numbers in the support division.
An LDAP authentication system consists of two components: an LDAP server and an LDAP
directory. An LDAP server is a program that implements the LDAP protocol and controls
access to an LDAP directory of user and group accounts. An LDAP directory is the storage
location and structure of user and group accounts on an LDAP server. Before information
from an LDAP directory can be searched and retrieved, a connection to the LDAP server
must be established.
If you use an LDAP directory to centrally manage users in your environment, you can
implement LDAP authentication in MicroStrategy. Group membership can be maintained in
the LDAP directory without having to also be defined in Intelligence Server. LDAP
authentication identifies users in an LDAP directory which MicroStrategy can connect to
through an LDAP server. Supported LDAP servers include Novell Directory Services,

116 © 2018, MicroStrategy Inc.

 System Administration Guide

Microsoft Directory Services, and Sun ONE 5.1/iPlanet. For the latest set of certified and
supported LDAP servers, refer to the Readme.
The high-level steps to implement LDAP authentication are as follows:
1. Review the LDAP information flow, described in LDAP information flow, page 117.
2. Depending on your requirements, collect information and make decisions regarding
the information in Checklist: Information required for connecting your LDAP server to
MicroStrategy, page 118.
3. Run the LDAP Connectivity Wizard to connect your LDAP server to MicroStrategy, as
described in Setting up LDAP authentication in MicroStrategy Web, Library, and
Mobile, page 133.
4. To make changes in your LDAP configuration, use the procedures described in
Managing LDAP authentication, page 136.
You can also set up MicroStrategy Office to use LDAP authentication. For information, see
the MicroStrategy Office User Guide.

LDAP information flow

The following scenario presents a high-level overview of the general flow of information
between Intelligence Server and an LDAP server when an LDAP user logs into Developer
or MicroStrategy Web:
1 When an LDAP user logs in to MicroStrategy Web or Developer, Intelligence Server
connects to the LDAP server using the credentials for the LDAP administrative user,
called an authentication user.
2 The authentication user is bound to LDAP using a Distinguished Name (DN) and
password set up in the user’s configuration.
3 The authentication user searches the LDAP directory for the user who is logging in via
Developer or MicroStrategy Web, based on the DN of the user logging in.
4 If this search successfully locates the user who is logging in, the user’s LDAP group
information is retrieved.
5 Intelligence Server then searches the MicroStrategy metadata to determine whether the
DN of the user logging in is linked to an existing MicroStrategy user or not.
6 If a linked user is not found in the metadata, Intelligence Server refers to the import and
synchronization options that are configured. If importing is enabled, Intelligence Server
updates the metadata with the user and group information it accessed in the LDAP
directory.
7 If a linked user is not found and importing is disabled, but the LDAP server is configured
to accept anonymous authentication, Intelligence Server creates a new user session
with an anonymous Guest user. If the LDAP server is not configured to accept
anonymous authentication, Intelligence Server does not allow the user to log in.
8 The user who is logging in is given access to MicroStrategy, with appropriate privileges
and permissions.

© 2018, MicroStrategy Inc. 117

System Administration Guide

Checklist: Information required for connecting your LDAP server to

MicroStrategy
You can connect your LDAP server to your Intelligence Server using the LDAP Connectivity
Wizard. Before beginning the process, ensure that you have the following information:
• The connection details for your LDAP server. The information required is as follows:
▫ The machine name or IP address of the LDAP server.
▫ The network port that the LDAP server uses.
▫ Whether the LDAP server is accessed using clear text, or over an encrypted SSL
connection. If you are using an SSL connection, you need to do the following before
you begin to set up LDAP:
a Obtain a valid certificate from your LDAP server and save it on the machine
where Intelligence Server is installed.
b Follow the procedure recommended by your operating system to install the
certificate.
▫ The user name and password of an LDAP user who can search the LDAP directory.
This user is called the authentication user, and is used by the Intelligence Server to
connect to the LDAP server. Typically, this user has administrative privileges for
your LDAP server.
• Details of your LDAP SDK. The LDAP SDK is a set of connectivity file libraries (DLLs)
that MicroStrategy uses to communicate with the LDAP server. For information on the
requirements for your LDAP SDK, and for steps to set up the SDK, see Setting up
LDAP SDK connectivity.
• Your LDAP search settings, which allow Intelligence Server to effectively search
through your LDAP directory to authenticate and import users. For information on
defining LDAP search settings, see Defining LDAP search filters to verify and import
users and groups at login, page 123.
Additionally, depending on your organization’s requirements, it is recommended that you
make decisions and gather information about the following:
• Determine whether you want to use connection pooling with your LDAP server. With
connection pooling, you can reuse an open connection to the LDAP server for
subsequent operations. The connection to the LDAP server remains open even when
the connection is not processing any operations (also known as pooling). This setting
can improve performance by removing the processing time required to open and close a
connection to the LDAP server for each operation.
For background information on connection pooling, see Determining whether to use
connection pooling, page 126.
• Determine the method that Intelligence Server uses to authenticate users in the LDAP
server. The possible options are described below:
▫ Binding: If you choose this method, the Intelligence Server attempts to log in to the
LDAP server with the user’s credentials. Intelligence Server also checks the LDAP

118 © 2018, MicroStrategy Inc.

 System Administration Guide

server for user’s restrictions, such as whether the user’s account has been locked,
or the user’s password has expired.
▫ Password comparison: If you choose this method, the Intelligence Server verifies
the user’s user name and password with the LDAP server, without attempting to log
in to the LDAP server.
For a comparison of the two methods of authentication, see Determining whether to use
authentication binding or password comparison, page 127.
• Determine whether you need to use database passthrough authentication. In
MicroStrategy, a single user name and password combination is frequently used to
connect to and execute jobs against a database. However, you can choose to pass to
the database a user’s LDAP user name and password used to log in to MicroStrategy.
The database is then accessed and jobs are executed using the LDAP user name and
password. This allows each user logged in to MicroStrategy to execute jobs against the
database using their unique user name and password which can be given a different set
of privileges than other users.
For additional information on database passthrough authentication, see Determining
whether to enable database passthrough authentication with LDAP, page 128.
• Determine whether you want to import LDAP user and group information into the
MicroStrategy metadata. The following options are available:
▫ Import users and groups into MicroStrategy: If you choose this option, a
MicroStrategy user is created for each user in your LDAP directory. Users can then
be assigned additional privileges and permissions in MicroStrategy.
▫ Link users and groups to MicroStrategy, without importing them: If you choose this
option, a link is created between MicroStrategy users and users in your LDAP
directory, without creating new LDAP users in your metadata. If you have an LDAP
directory with a large number of users, this option avoids filling your metadata with
new users.
For information on the benefits and considerations for importing LDAP user and group
information into MicroStrategy, see Determining whether to import LDAP users into
MicroStrategy, page 128.
• Determine whether you want to automatically synchronize user and group information
with the LDAP server. This ensures that if there are changes in the group membership
for the users you have imported into MicroStrategy, or users who are linked to existing
MicroStrategy accounts, the changes in the LDAP directory are applied in MicroStrategy
when users log in, or on a schedule that you determine.
For the benefits and considerations of synchronizing user and group information, see
Determining whether to automatically synchronize LDAP user and group information,
page 131.
• If you choose to import LDAP user and group information into the MicroStrategy
metadata, determine the following:
▫ Determine whether you want to import LDAP user and group information into the
MicroStrategy metadata when users log in, and whether the information is
synchronized every time users log in.

© 2018, MicroStrategy Inc. 119

System Administration Guide

▫ Determine whether you want to import LDAP user and group information into the
MicroStrategy metadata in batches, and whether you want the information to be
synchronized according to a schedule.
If you want to import LDAP user and group information in batches, you must provide
search filters to import the users. For example, if your organization has 1,000 users
in the LDAP directory, of whom 150 need to use MicroStrategy, you must provide a
search filter that imports the 150 users into the MicroStrategy metadata. For
information on defining search filters, see Defining LDAP search filters to verify and
import users and groups at login, page 123.
▫ If your LDAP organizational structure includes groups contained within groups,
determine how many recursive groups to import when you import a user or group
into MicroStrategy.
To understand how this setting effects the way the users and groups are imported
into MicroStrategy, see the following diagram:

If you choose to import two nested groups when MicroStrategy imports LDAP
groups, the groups associated with each user are imported, up to two levels above
the user. In this case, for User 1, the groups Domestic and Marketing would be
imported. For User 3, Developers and Employees would be imported.
▫ If you use a single sign-on (SSO) authentication system, such as Windows
authentication or integrated authentication, determine whether you want to import
the LDAP user and group information for users of your single sign-on system.
▫ Determine whether the following additional information is imported:
— The users’ email addresses. If you have a license for MicroStrategy Distribution
Services, then when you import LDAP users, you can import these email
addresses as contacts associated with those users.
— The format that the users’ login IDs and group names are imported in. For
example, you can determine whether users log in to MicroStrategy using their
LDAP login ID, or their LDAP distinguished name.
— Additional LDAP attributes to import. For example, your LDAP directory may
include an attribute called accountExpires, which contains information

120 © 2018, MicroStrategy Inc.

 System Administration Guide

about when the users’ accounts expire. The attributes in your LDAP directory
depend on the LDAP server that you use, and your LDAP configuration.
You can create security filters based on the LDAP attributes that you import.
For example, you import the LDAP attribute countryName, create a security
filter based on that LDAP attribute, and then you assign that security filter to all
LDAP users. Now, when a user from Brazil views a report that breaks down
sales revenue by country, she only sees the sales data for Brazil.
For information on setting up security filters based on LDAP attributes, see
Managing LDAP authentication, page 136.
Once you have collected the above information, you can use the LDAP Connectivity Wizard
to set up your LDAP connection. The steps are described in Setting up LDAP authentication
in MicroStrategy Web, Library, and Mobile, page 133.

Setting up LDAP SDK connectivity

From the perspective of your LDAP server, Intelligence Server is an LDAP client that uses
clear text or encrypted SSL to connect to your LDAP server through the LDAP SDK.
The LDAP SDK is a set of connectivity file libraries (DLLs) that MicroStrategy uses to
communicate with the LDAP server. For the latest set of certified and supported LDAP SDK
files, refer to the Readme.
Intelligence Server requires that the version of the LDAP SDK you are using supports the
following:
• LDAP v. 3
• SSL connections
• 64-bit architecture on Linux platforms

For LDAP to work properly with Intelligence Server, the 64-bit LDAP libraries must be used.

The following image shows how behavior of the various elements in an LDAP configuration
affects other elements in the configuration.

© 2018, MicroStrategy Inc. 121

System Administration Guide

1 The behavior between Intelligence Server and the LDAP SDK varies slightly depending
on the LDAP SDK used. The Readme provides an overview of these behaviors.
2 The behavior between the LDAP SDK and the LDAP server is identical, no matter which
LDAP SDK is used.
MicroStrategy recommends that you use the LDAP SDK vendor that corresponds to the
operating system vendor on which Intelligence Server is running in your environment.
Specific recommendations are listed in the Readme, with the latest set of certified and
supported LDAP SDKs, references to MicroStrategy Tech Notes with version-specific
details, and SDK download location information.
To configure Intelligence Server to use specific DLLs, see the Intelligence Server
Configuration Editor: LDAP category, Platform section in the MicroStrategy Developer Help.

High-level steps to install the LDAP SDK DLLs

1. Download the LDAP SDK DLLs onto the machine where Intelligence Server is
installed.
2. Install the LDAP SDK.
3. Register the location of the LDAP SDK files as follows:
l Windows environment: Add the path of the LDAP SDK libraries as a system
environment variable so that Intelligence Server can locate them.
l Linux environment: Modify the LDAP.sh file located in the env folder of your
MicroStrategy installation to point to the location of the LDAP SDK libraries. The
detailed procedure is described in the procedure To add the LDAP SDK path to the
environment variable in UNIX, page 122 below.
4. Restart Intelligence Server.

To add the LDAP SDK path to the environment variable in UNIX

This procedure assumes you have installed an LDAP SDK. For high-level steps to install an
LDAP SDK, see High-level steps to install the LDAP SDK DLLs, page 122.

1 In a Linux console window, browse to HOME_PATH where HOME_PATH is the specified

home directory during installation. Browse to the folder /env in this path.
2 Add Write privileges to the LDAP.sh file by typing the command chmod u+w
LDAP.sh and then pressing ENTER.
3 Open the LDAP.sh file in a text editor and add the library path to the MSTR_LDAP_
LIBRARY_PATH environment variable. For example: MSTR_LDAP_LIBRARY_
PATH='/path/LDAP/library'

It is recommended that you store all libraries in the same path. If you have several paths, you
can add all paths to the MSTR_LDAP_LIBRARY_PATH environment variable and separate

122 © 2018, MicroStrategy Inc.

 System Administration Guide

them by a colon (:). For example: MSTR_LDAP_LIBRARY_

PATH='/path/LDAP/library:/path/LDAP/library2'

4 Remove Write privileges from the LDAP.sh file by typing the command chmod a-w
LDAP.sh and then pressing ENTER.
5 Restart Intelligence Server for your changes to take effect.

Defining LDAP search filters to verify and import users and groups at login
You must provide Intelligence Server with some specific parameters so it can search
effectively through your LDAP directory for user information.
When users attempt to log in to MicroStrategy, the Intelligence Server authenticates users
by searching the LDAP directory for the user’s Distinguished Name, which is a unique way to
identify users within the LDAP directory structure.
To search effectively, Intelligence Server must know where to start its search. When setting
up LDAP authentication, it is recommended that you indicate a search root Distinguished
Name to establish the directory location from which Intelligence Server starts all user and
group searches. If this search root is not set, Intelligence Server searches the entire LDAP
directory.
Additionally, you can specify search filters, which help narrow down the users and groups to
search.
The following sections describe the search settings that you can configure:
l Highest level to start an LDAP search: Search root, page 123 provides examples of these
parameters as well as additional details of each parameter and some LDAP server-
specific notes.
l Finding users: user search filters, page 125 provides an overview of LDAP user search
filters.
l Finding groups: group search filters, page 125 provides an overview of LDAP group
search filters.

Highest level to start an LDAP search: Search root

The following diagram and table present several examples of possible search roots based on
how users might be organized within a company and within an LDAP directory. The diagram
shows a typical company’s departmental structure. The table describes several user import
scenarios based on the diagram.

© 2018, MicroStrategy Inc. 123

System Administration Guide

The following table, based on the diagram above, provides common search scenarios for
users to be imported into MicroStrategy. The search root is the root to be defined in
MicroStrategy for the LDAP directory.

Scenario Search Root

Include all users and groups from Operations

Operations
Include all users and groups from Sales
Operations, Consultants, and Sales
Include all users and groups from Departments (with an exclusion clause in the User/Group
Operations, Consultants, and search filter to exclude users who belong to Marketing and
Technology Administration)

Include all users and groups from Departments (with an exclusion clause in the User/Group
Technology and Operations but not search filter to exclude users who belong to Consultants.)
Consultants.

For some LDAP vendors, the search root cannot be the LDAP tree’s root. For example, both
Microsoft Active Directory and Sun ONE require a search to begin from the domain
controller RDN (dc). The image below shows an example of this type of RDN, where
“dc=sales, dc=microstrategy, dc=com”:

124 © 2018, MicroStrategy Inc.

 System Administration Guide

If your LDAP directory has multiple domains for different departments, see MicroStrategy
Tech Note TN18229.

Finding users: user search filters

User search filters allow MicroStrategy to efficiently search an LDAP directory to
authenticate or import a user at login.
Once Intelligence Server locates the user in the LDAP directory, the search returns the
user’s Distinguished Name, and the password entered at user login is verified against the
LDAP directory. Intelligence Server uses the authentication user to access, search in, and
retrieve the information from the LDAP directory.
Using the user’s Distinguished Name, Intelligence Server searches for the LDAP groups
that the user is a member of. You must enter the group search filter parameters separately
from the user search filter parameters (see Finding groups: group search filters, page 125).
User search filters are generally in the form (&(objectclass=LDAP_USER_OBJECT_
CLASS)(LDAP_LOGIN_ATTR=#LDAP_LOGIN#)) where:
l LDAP_USER_OBJECT_CLASS indicates the object class of the LDAP users. For
example, you can enter (&(objectclass=person)(cn=#LDAP_LOGIN#)).
l LDAP_LOGIN_ATTR indicates which LDAP attribute to use to store LDAP logins. For
example, you can enter (&(objectclass=person)(cn=#LDAP_LOGIN#)).
l #LDAP_LOGIN# can be used in this filter to represent the LDAP user login.
Depending on your LDAP server vendor and your LDAP tree structure, you may need to try
different attributes within the search filter syntax above. For example, (&
(objectclass=person) (uniqueID=#LDAP_LOGIN#)), where uniqueID is the
LDAP attribute name your company uses for authentication.

Finding groups: group search filters

Group search filters allow MicroStrategy to efficiently search an LDAP directory for the
groups to which a user belongs. These filters can be configured in the Intelligence Server
Configuration Editor, under the LDAP subject.
The group search filter is generally in one of the following forms (or the following forms may
be combined, using a pipe | symbol to separate the forms):
l (&(objectclass=LDAP_GROUP_OBJECT_CLASS) (LDAP_MEMBER_
LOGIN_ATTR=#LDAP_LOGIN#))
l (&(objectclass=LDAP_GROUP_OBJECT_CLASS) (LDAP_MEMBER_DN_
ATTR=#LDAP_DN#))
l (&(objectclass=LDAP_GROUP_OBJECT_CLASS)
(gidNumber=#LDAP_GIDNUMBER#))
The group search filter forms listed above have the following placeholders:

© 2018, MicroStrategy Inc. 125

System Administration Guide

l LDAP_GROUP_OBJECT_CLASS indicates the object class of the LDAP groups. For

example, you can enter (&(objectclass=groupOfNames)(member=#LDAP_
DN#)).
l LDAP_MEMBER_[LOGIN or DN]_ATTR indicates which LDAP attribute of an LDAP
group is used to store LDAP logins/DNs of the LDAP users. For example, you can enter
(&(objectclass=groupOfNames)(member=#LDAP_DN#)).
l #LDAP_DN# can be used in this filter to represent the distinguished name of an LDAP
user.
l #LDAP_LOGIN# can be used in this filter to represent an LDAP user’s login.
l #LDAP_GIDNUMBER# can be used in this filter to represent the UNIX or Linux group ID
number; this corresponds to the LDAP attribute gidNumber.
You can implement specific search patterns by adding additional criteria. For example, you
may have 20 different groups of users, of which only five groups will be accessing and
working in MicroStrategy. You can add additional criteria to the group search filter to import
only those five groups.

Determining whether to use connection pooling

With connection pooling, you can reuse an open connection to the LDAP server for
subsequent operations. The connection to the LDAP server remains open even when the
connection is not processing any operations (also known as pooling). This setting can
improve performance by removing the processing time required to open and close a
connection to the LDAP server for each operation.
If you do not use connection pooling, the connection to an LDAP server is closed after each
request. If requests are sent to the LDAP server infrequently, this can help reduce the use of
network resources.

Connection pooling with clustered LDAP servers

You may have multiple LDAP servers which work together as a cluster of LDAP servers.
If connection pooling is disabled, when a request to open an LDAP connection is made, the
LDAP server with the lightest load at the time of the request is accessed. The operation
against the LDAP directory can then be completed, and in an environment without
connection pooling, the connection to the LDAP server is closed. When the next request to
open an LDAP connection is made, the LDAP server with the least amount of load is
determined again and chosen.
If you enable connection pooling for a clustered LDAP environment, the behavior is different
than described above. On the first request to open an LDAP connection, the LDAP server
with the least amount of load at the time of the request is accessed. However, the connection
to the LDAP server is not closed because connection pooling is enabled. Therefore, instead
of determining the LDAP server with the least amount of load during the next request to open
an LDAP connection, the currently open connection is reused.
The diagrams shown below illustrate how subsequent connections to a clustered LDAP
server environment are handled, depending on whether connection pooling is enabled or
disabled.

126 © 2018, MicroStrategy Inc.

 System Administration Guide

Determining whether to use authentication binding or password comparison

When MicroStrategy attempts to authenticate an LDAP user logging in to MicroStrategy, you
can choose to perform an LDAP bind to authenticate the user or simply authenticate on user
name and password.
By implementing authentication binding, MicroStrategy authenticates the user by logging in
to the LDAP server with the user’s credentials, and assessing the following user restrictions:
l Whether the LDAP password is incorrect, has been locked out, or has expired
l Whether the LDAP user account has been disabled, or has been identified as an intruder
and is locked out

© 2018, MicroStrategy Inc. 127

System Administration Guide

If MicroStrategy can verify that none of these restrictions are in effect for this user account,
MicroStrategy performs an LDAP bind, and successfully authenticates the user logging in.
This is the default behavior for users and groups that have been imported into MicroStrategy.
You can choose to have MicroStrategy verify only the accuracy of the user’s password with
which the user logged in, and not check for additional restrictions on the password or user
account. To support password comparison authentication, your LDAP server must also be
configured to allow password comparison only.

Determining whether to enable database passthrough authentication with

LDAP
In MicroStrategy, a single user name and password combination is frequently used to
connect to and execute jobs against a database. However, you can choose to pass a user’s
LDAP user name and password used to log in to MicroStrategy to the database. The
database is then accessed and jobs are executed using the LDAP user name and password.
This allows each user logged in to MicroStrategy to execute jobs against the database using
their unique user name and password, which can be given a different set of privileges than
other users.
Database passthrough authentication is selected for each user individually. For general
information on selecting user authentication, see About MicroStrategy users, page 67.
If a user’s password is changed during a session in MicroStrategy, scheduled tasks may fail
to run when using database passthrough authentication. Consider the following scenario.
A user with user login UserA and password PassA logs in to MicroStrategy at 9:00 A.M. and
creates a new report. The user schedules the report to run at 3:00 P.M. later that day. Since
there is no report cache, the report will be executed against the database. At noon, an
administrator changes UserA’s password to PassB. UserA does not log back into
MicroStrategy, and at 3:00 P.M. the scheduled report is run with the credentials UserA and
PassA, which are passed to the database. Since these credentials are now invalid, the
scheduled report execution fails.
To prevent this problem, schedule password changes for a time when users are unlikely to
run scheduled reports. In the case of users using database passthrough authentication who
regularly run scheduled reports, inform them to reschedule all reports if their passwords
have been changed.

Determining whether to import LDAP users into MicroStrategy

To connect your LDAP users and groups to users and groups in MicroStrategy, you can
either import the LDAP users and groups into the MicroStrategy metadata or you can simply
create a link between users and groups in the LDAP directory and in MicroStrategy.
Importing a user creates a new user in MicroStrategy based on an existing user in the LDAP
directory. Linking a user connects an LDAP user’s information to an existing user in
MicroStrategy. You can also allow LDAP users to log in to the MicroStrategy system
anonymously, without an associated MicroStrategy user. The benefits and considerations of
each method are described in the table below.

128 © 2018, MicroStrategy Inc.

 System Administration Guide

Connection Benefits Considerations

Type

Import LDAP • Users and groups are created in the • In environments that have many LDAP
users and metadata. users, importing can quickly fill the
groups metadata with these users and their
• Users and groups can be assigned related information.
additional privileges and
permissions in MicroStrategy. • Users and groups may not have the
correct permissions and privileges
• Users have their own inboxes and when they are initially imported into
personal folders in MicroStrategy. MicroStrategy.
Link users • For environments that have many • Users to be linked to must already
and groups LDAP users, linking avoids filling the exist in the MicroStrategy metadata.
without metadata with users and their
importing related information.
• You can use Command Manager to
automate the linking process using
scripts. See the Command Manager
Help for details.
Allow • Users can log in immediately without • Privileges are limited to those for the
anonymous having to create a new MicroStrategy Public/Guest group.
or guest user.
users • Users’ personal folders and Inboxes
are deleted from the system after they
log out.

The options for importing users into MicroStrategy are described in detail in the following
sections:
l Importing LDAP users and groups into MicroStrategy, page 129
l Linking users and groups without importing, page 130
l Allowing anonymous/guest users with LDAP authentication, page 131
You can modify your import settings at any time, for example, if you choose not to import
users initially, but want to import them at some point in the future. The steps to modify your
LDAP settings are de