MicroStrategy Business Intelligence System 10.1 System Administration Guide

System Administration
Guide
Tuning, Monitoring, and
Troubleshooting your
MicroStrategy Business
Intelligence System
10.1
Document Number: 09471010
10.1, August 2015
Document Number: 09471010
Copyright © 2015 by MicroStrategy Incorporated. All rights reserved.
If you have not executed a written or electronic agreement with MicroStrategy or any authorized MicroStrategy distributor (any
such agreement, a "Separate Agreement"), the following terms apply:
This software and documentation are the proprietary and confidential information of MicroStrategy Incorporated and may not be
provided to any other person. Copyright © 2001-2015 by MicroStrategy Incorporated. All rights reserved.
THIS SOFTWARE AND DOCUMENTATION ARE PROVIDED “AS IS” AND WITHOUT EXPRESS OR LIMITED WARRANTY OF
ANY KIND BY EITHER MICROSTRATEGY INCORPORATED OR ANYONE WHO HAS BEEN INVOLVED IN THE CREATION,
PRODUCTION, OR DISTRIBUTION OF THE SOFTWARE OR DOCUMENTATION, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE AND
NONINFRINGMENT, QUALITY OR ACCURACY. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
SOFTWARE AND DOCUMENTATION IS WITH YOU. SHOULD THE SOFTWARE OR DOCUMENTATION PROVE DEFECTIVE,
YOU (AND NOT MICROSTRATEGY, INC. OR ANYONE ELSE WHO HAS BEEN INVOLVED WITH THE CREATION,
PRODUCTION, OR DISTRIBUTION OF THE SOFTWARE OR DOCUMENTATION) ASSUME THE ENTIRE COST OF ALL
NECESSARY SERVICING, REPAIR, OR CORRECTION. SOME STATES DO NOT ALLOW THE EXCLUSION OF IMPLIED
WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.
In no event will MicroStrategy, Incorporated. or any other person involved with the creation, production, or distribution of the
Software be liable to you on account of any claim for damage, including any lost profits, lost savings, or other special, incidental,
consequential, or exemplary damages, including but not limited to any damages assessed against or paid by you to any third party,
arising from the use, inability to use, quality, or performance of such Software and Documentation, even if MicroStrategy, Inc. or any
such other person or entity has been advised of the possibility of such damages, or for the claim by any other party. In addition,
MicroStrategy, Inc. or any other person involved in the creation, production, or distribution of the Software shall not be liable for
any claim by you or any other party for damages arising from the use, inability to use, quality, or performance of such Software and
Documentation, based upon principles of contract warranty, negligence, strict liability for the negligence of indemnity or
contribution, the failure of any remedy to achieve its essential purpose, or otherwise. The entire liability of MicroStrategy, Inc. and
your exclusive remedy, shall not exceed, at the option of MicroStrategy, Inc., either a full refund of the price paid, or replacement of
the Software. No oral or written information given out expands the liability of MicroStrategy, Inc. beyond that specified in the above
limitation of liability. Some states do not allow the limitation or exclusion of liability for incidental or consequential damages, so the
above limitation may not apply to you.
The information contained in this manual (the Documentation) and the Software are copyrighted and all rights are reserved by
MicroStrategy, Inc. MicroStrategy, Inc. reserves the right to make periodic modifications to the Software or the Documentation
without obligation to notify any person or entity of such revision. Copying, duplicating, selling, or otherwise distributing any part of
the Software or Documentation without prior written consent of an authorized representative of MicroStrategy, Inc. are prohibited.
U.S. Government Restricted Rights. It is acknowledged that the Software and Documentation were developed at private expense,
that no part is public domain, and that the Software and Documentation are Commercial Computer Software provided with
RESTRICTED RIGHTS under Federal Acquisition Regulations and agency supplements to them. Use, duplication, or disclosure by
the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFAR 252.227-7013 et. seq. or subparagraphs (c)(1) and (2) of the Commercial Computer Software-Restricted
Rights at FAR 52.227-19, as applicable. Contractor is MicroStrategy, Incorporated., 1850 Towers Crescent Plaza, Tysons Corner, VA
22182. Rights are reserved under copyright laws of the United States with respect to unpublished portions of the Software.
The following terms and notices apply regardless of whether you have executed a Separate Agreement:
Trademark Information
MicroStrategy, MicroStrategy 9, MicroStrategy 9s, MicroStrategy Analytics Platform, MicroStrategy Desktop, MicroStrategy
Analytics Express, MicroStrategy Analytics Enterprise, MicroStrategy Evaluation Edition, MicroStrategy Suite, 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 Web Universal, MicroStrategy Office,
MicroStrategy Data Mining Services, MicroStrategy Narrowcast Server, MicroStrategy Health Center, MicroStrategy Power User,
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 Analytics for
iPad® App, MicroStrategy Analytics Express App, MicroStrategy Tech Support App, MicroStrategy Mobile App Platform,
MicroStrategy Mobile App Developer Academy, MicroStrategy Cloud, MicroStrategy Cloud Platform Services, MicroStrategy Cloud
Data Hosting Services, MicroStrategy Cloud Data Warehouse Services, MicroStrategy Cloud Data Integration Services, MicroStrategy
Virtual Business Intelligence (VBI) Appliance, MicroStrategy Cloud Paid Pilot, MicroStrategy R Integration, MicroStrategy Usher,
Usher Badge, Usher Security, Usher Security Server, Usher Mobile, Usher Analytics, Usher Network Manager, MicroStrategy Trela
for Retail (Alert backwards / used for demonstrations, MicroStrategy Services, MicroStrategy Professional Services, MicroStrategy
Consulting, MicroStrategy Customer Services, MicroStrategy Education, MicroStrategy University, MicroStrategy Managed Services,
MicroStrategy Business Intelligence QuickStrike, BI QuickStrike, Mobile QuickStrike, Transaction Services QuickStrike, Retail
Vendor Portal, Perennial Education Pass, MicroStrategy Web Based Training (WBT), MicroStrategy World, Office Intelligence, Best
in Business Intelligence, Pixel Perfect, Global Delivery Center, MicroStrategy Identity Platform, MicroStrategy Loyalty Platform,
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. 5,321,520,
5,416,602, 5,748,560, 6,154,766, 6,173,310, 6,260,050, 6,263,051, 6,269,393, 6,279,033, 6,501,832, 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,707,889, 6,741,980,
6,765,997, 6,768,788, 6,772,137, 6,788,768, 6,792,086, 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,888,929, 6,895,084, 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,474, 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,457,397, 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,035,382, 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, and 8,943,187. Other patent applications are pending.
Third Party Software
Various MicroStrategy products contain the copyrighted technology or software of third parties ("Third Party Software"). A list of
Third Party Software, as well as links to any terms and conditions associated with such Third Party Software ("Third Party Terms"),
can be found at http://www.microstrategy.com/third-party-notices. Your use of MicroStrategy products is subject to all applicable
Third Party Terms.
CONTENTS
Overview and Additional Resources
About this book
1
4
How to find business scenarios and examples
5
What’s new in this guide
5
Who should use this guide
6
Documentation
7
Manuals for MicroStrategy overview and evaluation
8
Resources for Identity and Loyalty
9
Manuals for query, reporting, and analysis
9
Manuals for Analytics Modules
11
Manuals for Narrowcast Services products
11
Software Development Kits
12
Documentation for MicroStrategy Portlets
12
Documentation for MicroStrategy GIS Connectors
13
Help
13
Accessing manuals and other documentation sources
13
Documentation standards
15
© 2015, MicroStrategy Inc.
i
System Administration Guide
1. Introduction to MicroStrategy System Administration
Best practices for MicroStrategy system administration
2
Understanding the MicroStrategy architecture
3
Storing information: the data warehouse
4
Indexing your data: MicroStrategy metadata
4
Processing your data: Intelligence Server
6
Tying it all together: projects and project sources
6
Communicating with databases
7
Connecting to the MicroStrategy metadata
7
Connecting to the data warehouse
9
Caching database connections
9
Monitoring database instance connections
10
Benefiting from centralized database access control
11
Updating VLDB properties for ODBC connections
11
Managing Intelligence Server
13
What happens when Intelligence Server starts?
13
What happens when Intelligence Server stops?
14
Running Intelligence Server as an application or a service
15
Managing MicroStrategy services from the command line
22
Managing and monitoring projects
26
Managing project status, configuration, or security: Project view
27
Managing clustered Intelligence Servers: Cluster view
28
Setting the status of a project
29
Project and data warehouse maintenance example scenarios
34
Processing jobs
ii
1
35
Intelligence Server job processing (common to all jobs)
35
Processing report execution
36
Processing object browsing
40
Processing element browsing
41
© 2015, MicroStrategy Inc.
System Administration Guide
Processing Report Services document execution
43
Processing HTML document execution
45
Client-specific job processing
47
Monitoring currently executing jobs
50
Using automated installation techniques
51
Using a Response file to install the product
52
Using a Response file to configure the product
52
Running a silent installation
52
Security checklist before deploying the system
2. Setting Up User Security
52
55
The MicroStrategy user model
56
About MicroStrategy users
56
About MicroStrategy user groups
56
Privileges
59
Permissions
59
Creating, importing, and deleting users and groups
60
Monitoring users’ connections to projects
61
Controlling access to application functionality
62
Controlling access to objects: Permissions
63
Controlling access to functionality: Privileges
72
Defining sets of privileges: Security roles
75
Controlling access to data
80
Controlling access to the database: Connection mappings
80
Linking database users and MicroStrategy users: Passthrough execution
84
Restricting access to data: Security filters
86
Controlling access to data at the database (RDBMS) level
98
Merging users or groups
102
How users and groups are merged
102
Running the User Merge Wizard
104
© 2015, MicroStrategy Inc.
iii
System Administration Guide
3. Identifying Users: Authentication
107
Workflow: changing authentication modes
107
Modes of authentication
108
Configuring the authentication mode for a project source
109
Importing users from different authentication systems
110
Sharing user accounts between users
111
Implementing standard authentication
111
Password policy
111
Steps to implement standard authentication
112
Implementing anonymous authentication
112
Implementing database warehouse authentication
114
Database warehouse authentication information flow
114
Steps to implement database warehouse authentication
115
Database warehouse and metadata (6.x) authentication
116
Implementing LDAP authentication
116
LDAP information flow
117
Checklist: Information required for connecting your LDAP server to
MicroStrategy
118
Setting up LDAP authentication in MicroStrategy
136
Managing LDAP authentication
138
Troubleshooting
146
Enabling single sign-on authentication
146
Implementing Windows NT authentication
147
Enabling integrated authentication
155
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
177
Enabling Usher authentication for Web and Mobile
194
Authentication examples
198
Security views: Windows authentication and linked warehouse login
iv
198
© 2015, MicroStrategy Inc.
System Administration Guide
Connection maps: Standard authentication, connection maps, and
partitioned fact tables
4. Enabling Secure Communication
199
201
Overview of SSL and encryption in MicroStrategy
201
Obtaining SSL certificates
202
Prerequisites
203
Generating an SSL Certificate Signing Request
204
Submitting a Certificate Request
205
Installing the SSL certificates
Adding your enterprise CA as a trusted certificate authority
Configuring the MicroStrategy applications to use SSL
206
207
209
Configuring SSL between Intelligence Server and Developer, MicroStrategy
Web, or Mobile Server
210
Configuring Web, Mobile Server, and Web Services to require SSL access 212
Testing SSL access
213
Configuring MicroStrategy client applications to use an HTTPS URL
214
Enabling encryption between Web or Mobile Server and Intelligence Server 215
Self-signed certificates: Creating a Certificate Authority for development
216
Creating the directories and configuration files for your CA
216
Creating the private key and root certificate for the CA
218
Configuring OpenSSL to use your private key and root certificate
219
Signing certificate requests using your CA
220
5. Managing Your Licenses
Managing and verifying your licenses
223
223
Named User licenses
224
CPU licenses
226
Effects of being out of compliance with your licenses
226
Auditing and updating licenses
227
Using License Manager
227
Auditing your system for the proper licenses
229
© 2015, MicroStrategy Inc.
v
System Administration Guide
Updating your license
230
Updating CPU affinity
231
CPU affinity for Intelligence Server on Windows
232
CPU affinity for Intelligence Server on UNIX/Linux
232
CPU affinity for MicroStrategy Web
236
6. Managing Your Projects
239
The project life cycle
Recommended scenario: Development, test, and production
240
Real-life scenario: New version from a project developer
243
Implementing the recommended life cycle
244
Duplicating a project
245
What objects are duplicated with a project?
246
Duplicating projects in multiple languages
247
The Project Duplication Wizard
247
Migrating a project to a new database platform
249
Updating projects with new objects
251
Comparing Project Merge to Object Manager
252
Locking projects
253
Copying objects between projects: Object Manager
254
Prerequisites for copying objects between projects
254
Project locking with Object Manager
255
Copying objects
256
What happens when you copy or move an object
260
Resolving conflicts when copying objects
266
Copying objects in a batch: Update packages
273
Merging projects to synchronize objects
vi
240
290
What happens when you merge projects
292
Merging projects with the Project Merge Wizard
292
Resolving conflicts when merging projects
297
© 2015, MicroStrategy Inc.
System Administration Guide
Comparing and tracking projects
298
Comparing objects between two projects
298
Tracking your projects with the Search Export feature
300
Listing unused objects in a project
301
Deleting unused schema objects: managed objects
302
Deleting managed objects one-by-one
302
Deleting all unused managed objects
303
7. Monitoring System Usage
305
MicroStrategy system monitors
305
Monitoring system activity: Change journaling
307
Enabling change journaling
307
Viewing the change journal entries
309
Increasing the number of change journal entries to view or export
310
Searching the change journal for relevant entries
311
Exporting the change journal
312
Purging the change journal
313
Monitoring system usage: Intelligence Server statistics
314
Overview of Intelligence Server statistics
315
Best practices for recording Intelligence Server statistics
319
Configuring Intelligence Server to log statistics
320
Additional monitoring tools
326
Diagnostics and Performance Logging Tool
327
Integrity Manager
327
Enterprise Manager
327
Health Center
327
Windows Performance Monitor
328
8. Tuning Your System for Best Performance
Tuning overview and best practices
Defining the system requirements
© 2015, MicroStrategy Inc.
329
330
330
vii
System Administration Guide
Configuring the system design
331
Best practices for tuning your system
333
Designing system architecture
334
How the data warehouse can affect performance
335
How the network can affect performance
335
How clustering can affect performance
338
Managing system resources
338
Managing system memory and resources: Windows Performance Monitor 339
Processor type, speed, and number of processors
340
Physical disk
340
Memory
341
Governing Intelligence Server memory use with Memory Contract Manager 345
Governing memory for requests from MicroStrategy Web products
Managing user sessions
355
Governing concurrent users
356
Governing user resources
358
Governing user profiles
361
Governing requests
363
Excluding document datasets from the job limits
364
Limiting the total number of jobs
364
Limiting the number of jobs per project
364
Limiting the number of jobs per user session and per user account
365
Limiting the number of executing jobs per user and project
366
Limiting the maximum report execution time
366
Limiting a report's SQL per pass
367
Managing job execution
viii
354
368
Managing database connection threads
369
Prioritizing jobs
373
Results processing
376
© 2015, MicroStrategy Inc.
System Administration Guide
Governing results delivery
381
Limiting the information displayed at one time
382
Limiting the number of XML cells
383
Limiting export sizes
384
Limiting the memory consumption for file generation
384
Limiting the total number of XML drill paths
385
Tuning your system for in-memory datasets
386
Configuring Intelligence Server for in-memory datasets
386
Configuring your projects for in-memory datasets
387
Designing reports
387
Analytic complexity
388
Subtotals
388
Page-by feature
389
Prompt complexity
389
Report Services documents
389
Intelligent Cubes
390
Configuring Intelligence Server and projects
390
Intelligence Server Configuration Editor
391
Project Configuration Editor
396
Database connection
400
VLDB settings
401
Tuning Narrowcast Server and Intelligence Server
402
Application design considerations
402
How Narrowcast Server connects to Intelligence Server
403
9. Clustering Multiple MicroStrategy Servers
Overview of clustering
405
406
Benefits of clustering
406
The clustered architecture
408
Synchronizing cached information across nodes in a cluster
© 2015, MicroStrategy Inc.
409
ix
System Administration Guide
Prerequisites for clustering Intelligence Servers
414
MicroStrategy prerequisites
414
Server prerequisites
415
Prerequisites for Windows clustering
416
Prerequisites for UNIX/Linux clustering
416
Clustering Intelligence Servers
417
Configuring caches in a cluster
417
Joining the nodes in a cluster
424
Verifying the clustered system is working
424
Distributing projects across nodes in a cluster
425
Managing your clustered system
427
Managing your projects across nodes of a cluster
428
Project failover and latency
430
Shutting down a node
432
Maintaining result caches and History Lists in a clustered environment
433
Connecting MicroStrategy Web to a cluster
435
Clustering and firewalls
436
Exporting to PDF or Excel
436
Node failure
436
10. Improving Report and Document Response Time: Caching
Result caches
x
437
438
Cache management best practices
440
Types of result caches
441
Location of result caches
443
Cache matching algorithm
444
Disabling result caching
446
Monitoring result caches
447
Managing result caches
451
Configuring result cache settings
455
© 2015, MicroStrategy Inc.
System Administration Guide
Saving report results: History List
466
Understanding History Lists
467
Configuring History List data storage
470
Accessing History Lists
473
Archiving History List messages
475
Managing History Lists
476
Element caches
482
Element caching terminology
483
Location of element caches
484
Cache matching algorithm
484
Enabling or disabling element caching
485
Limiting the number of elements displayed and cached at a time
486
Caching algorithm
489
Limiting the amount of memory available for element caches
489
Limiting which attribute elements a user can see
491
Limiting element caches by database connection
492
Limiting element caches by database login
492
Deleting all element caches
493
Summary table of element cache settings
494
Object caches
494
Cache matching algorithm
495
Enabling or disabling object caching
495
Limiting the amount of memory available for object caches
496
Deleting object caches
497
Summary table of object caching settings
498
11. Managing Intelligent Cubes
Managing Intelligent Cubes: Intelligent Cube Monitor
499
500
Viewing Intelligent Cube information and usage statistics
500
Monitoring and modifying Intelligent Cube status
502
© 2015, MicroStrategy Inc.
xi
System Administration Guide
Governing Intelligent Cube memory usage, loading, and storage
Governing Intelligent Cube memory usage
507
Loading Intelligent Cubes when Intelligence Server starts
514
Storing Intelligent Cubes in secondary storage
516
Supporting connection mappings in Intelligent Cubes
517
12. Scheduling Jobs and Administrative Tasks
519
Best practices for scheduling jobs and administrative tasks
520
Creating and managing schedules
522
Time-triggered schedules
522
Event-triggered schedules
522
Creating schedules
523
Managing schedules
524
About events and event-triggered schedules
526
Scheduling administrative tasks
Managing scheduled administration tasks
Scheduling reports and documents: Subscriptions
528
530
531
Types of subscriptions
532
Creating subscriptions
534
Managing subscriptions
542
Configuring and administering Distribution Services
545
Overview of Distribution Services
546
Best practices for using Distribution Services
549
High-level checklist to set up a report delivery system
550
Creating and managing transmitters
551
Creating and managing devices
558
Creating and managing contacts
568
13. Administering MicroStrategy Web and Mobile
xii
507
577
Assigning privileges for MicroStrategy Web
578
Using the MicroStrategy Web Administrator page
579
© 2015, MicroStrategy Inc.
System Administration Guide
Controlling access to the Administrator page
Defining project defaults
Loading and applying default values
Using additional security features for MicroStrategy Web and Mobile
580
581
582
583
Using firewalls
583
Using cookies
586
Using encryption
587
Applying file-level security
588
Sample MicroStrategy system
589
Integrating Narrowcast Server with MicroStrategy Web products
590
Enabling users to install MicroStrategy Office from Web
592
FAQs for configuring and tuning MicroStrategy Web products
592
How do I configure my MicroStrategy Web environment if I have a user
community of x users? How much hardware am I going to need?
592
How do time-out settings in MicroStrategy Web and Intelligence Server
affect MicroStrategy Web users?
593
How can I tune my MicroStrategy Web server for best performance?
594
14. Combining Administrative Tasks with System Manager
Creating a workflow
597
598
Using connectors to create the logical order of a workflow
605
Using entry processes to determine the first step in a workflow
607
Using decisions to determine the next step in a workflow
608
Using exit processes to end a workflow
611
Processing related tasks one by one
613
Processing multiple tasks simultaneously
615
Using comments to provide context and information to a workflow
620
Validating a workflow
621
Supporting loops in a workflow to attempt configurations multiple times
623
Sample workflows: Templates
625
Defining processes
© 2015, MicroStrategy Inc.
633
xiii
System Administration Guide
Configuring MicroStrategy components
634
Managing projects
637
Administering Intelligence Servers and other MicroStrategy services
642
Automating administrative tasks
645
Verifying reports and documents
648
Creating data source names
651
Completing a separate System Manager workflow
665
Retrieving MicroStrategy information
667
Performing system processes
667
Administering cloud-based environments
685
Determining process resolution using exit codes
699
Using parameters for processes
699
Using wildcard characters in processes
705
Deploying a workflow
706
Using System Manager to test and deploy a workflow
707
Using the command line to deploy a workflow
709
15. Automating Administrative Tasks with Command Manager
Using Command Manager
xiv
713
714
Privileges required for using Command Manager
715
Creating and executing scripts
715
Procedures in Command Manager
717
Executing a Command Manager script
718
Encrypting Command Manager scripts
721
Project and configuration locking
722
Handling syntax errors
723
Handling execution errors
723
Timeout errors
724
Command Manager script syntax
724
Using Command Manager from the command line
726
© 2015, MicroStrategy Inc.
System Administration Guide
Using Command Manager with OEM software
16. Verifying Reports and Documents with Integrity Manager
727
729
What is an integrity test?
730
Types of integrity tests
731
Testing Intelligence Server performance
732
Best practices for using Integrity Manager
733
Creating an integrity test
734
Saving and loading a test
Executing an integrity test
736
737
Executing a test from the command line
737
Executing a test against a remote Intelligence Server
741
Executing prompted reports with Integrity Manager
741
Executing a test under multiple MicroStrategy user accounts
745
Ignoring dynamic SQL when comparing SQL
747
Matching equivalent SQL strings
748
Viewing the results of a test
748
Viewing and editing notes
750
Grouping differences in graph and PDF reports
750
Accessing the saved results of a test
751
List of tags in the integrity test file
17. Maintaining Your MicroStrategy System with Health Center
754
765
Accessing the Health Center console
766
Configuring and managing a Health Center system
767
Best practices for configuring a Health Center system
767
The Master Health Agent
768
Health Agents
770
Adding Health Agents to the system
771
Diagnosing and fixing problems
Fixing problems found by Health Center
© 2015, MicroStrategy Inc.
775
777
xv
System Administration Guide
Analyzing log files
777
Collecting and sending information for MicroStrategy Technical Support
778
Keeping Health Center up to date
780
Manually updating your Health Center system
781
List of system checks
781
System checks for Configuration
783
System checks for Developer
783
System checks for Enterprise Manager
784
System checks for Intelligence Server
785
System checks for Narrowcast Server
789
System checks for MicroStrategy Web products
790
Using a response file to configure a Health Agent or Master Health Agent
Creating a response file
792
Executing a response file
792
Health Center response file parameters
794
18. Troubleshooting
799
Methodology for finding trouble spots
800
Intelligence Server stopped
800
The system is slow
800
Users cannot log in
801
Finding trouble spots using diagnostics
801
Configuring what is logged
802
Viewing and analyzing log files
816
Analyzing a server state dump
818
Memory depletion troubleshooting
822
Basic memory concepts
822
Potential causes of memory depletion
824
Authentication troubleshooting
827
Troubleshooting Windows authentication in MicroStrategy Web
xvi
792
828
© 2015, MicroStrategy Inc.
System Administration Guide
Failure to log in to server (three-tier) project source
828
Troubleshooting LDAP authentication
829
Fixing inconsistencies in the metadata
Fixing deleted items
834
834
Object dependencies troubleshooting
837
Date/time functions troubleshooting
838
Performance troubleshooting
838
Project performance
838
Schema update performance
839
Cache Monitor and Intelligent Cube Monitor performance
840
Troubleshooting data imported from a file
840
Subscription and report results troubleshooting
841
Drilled-to report returns no data or incorrect data
841
Graph report results
841
Number of report result rows
842
Subscription with a prompt is not sent and disappears
842
Contact does not appear in list of contacts when subscribing
842
SQL/MDX string length
843
Freeform SQL report error
844
Internationalization troubleshooting
844
Object displays translations in a language different from the project or
object default language
845
User’s preferred language defaults to project default language
845
Custom names for system objects are not retained after upgrade
845
Troubleshooting Intelligence Server
846
Logon failure
846
Failure to activate Intelligence Server
847
Multiple instances of Intelligence Server
847
Clustered environments troubleshooting
© 2015, MicroStrategy Inc.
848
xvii
System Administration Guide
Problems in a clustered environment
What order should I start the server nodes?
848
Which node am I connected to?
848
Do I need multiple project sources?
848
Does it matter which node I connect to in Developer?
848
Can I control which node I connect to in MicroStrategy Web?
849
Caches in a clustered environment
849
Node synchronization in a clustered environment
849
Statistics logging troubleshooting
850
Statistics are not being logged
850
Statistics on subscriptions and deliveries
853
Additional resources for troubleshooting
xviii
848
854
MicroStrategy Readme and release notes
854
MicroStrategy Knowledge Base
855
Customer Forums
856
Technical Support
857
Glossary
859
Index
873
© 2015, MicroStrategy Inc.
OVERVIEW AND
ADDITIONAL
RESOURCES
Description of this guide
This guide is to be 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.
For additional reference information about seldom-used or advanced topics
such as VLDB properties, internationalization, and the Intelligence Server
statistics data dictionaries, see the Supplemental Reference for System
Administration.
The chapters provide the following information:
•
Chapter 1, Introduction to MicroStrategy System Administration
This chapter provides an overview of the architecture and how the
MicroStrategy system interacts with the various external
© 2015, MicroStrategy Inc.
1
System Administration Guide
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 2, Setting Up User Security
This chapter 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 chapter 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 3, Identifying Users: Authentication
Authentication is the process through which the system identifies the user.
This chapter describes the modes of authentication that MicroStrategy
supports, and how to configure them so that they support your user
community.
•
Chapter 4, Enabling Secure Communication
This chapter describes the steps to enable secure, encrypted
communications between MicroStrategy components using SSL.
•
Chapter 5, Managing Your Licenses
This chapter 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 6, Managing Your Projects
In a MicroStrategy system, a project is the environment in which reporting
is done. This chapter 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.
2
© 2015, MicroStrategy Inc.
System Administration Guide
•
Chapter 7, Monitoring System Usage
This chapter 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 8, Tuning Your System for Best Performance
This chapter 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 9, 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
chapter describes how to cluster Intelligence Servers, how to manage
clustered projects, and how to connect MicroStrategy Web to a cluster.
•
Chapter 10, Improving Report and Document Response Time: Caching
This chapter 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 11, Managing Intelligent Cubes
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 chapter provides details to understand and to create
Intelligent Cubes your users can access when the execute reports and
documents.
•
Chapter 12, Scheduling Jobs and Administrative Tasks
This chapter 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 13, Administering MicroStrategy Web and Mobile
© 2015, MicroStrategy Inc.
3
System Administration Guide
This chapter provides a high-level overview for some of the administrative
tasks that are unique to administering MicroStrategy Web, Web Universal,
and Mobile Server.
•
Chapter 14, 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 15, 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 chapter describes how to create and execute these scripts.
•
Chapter 16, 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 chapter
describes how to configure Integrity Manager and how to create and
execute an integrity test, and provides best practices for using Integrity
Manager.
•
Chapter 17, 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 chapter describes how to
configure your Health Center network and how to schedule system checks
for MicroStrategy components.
•
Chapter 18, Troubleshooting
This chapter 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 book
The following sections provide the location of additional examples and
describe the user roles for which the information in this book was designed.
4
© 2015, MicroStrategy Inc.
System Administration Guide
*
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.
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 MicroStrategy Basic Reporting Guide.
Detailed examples of advanced reporting functionality can be found in the
MicroStrategy 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
•
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, page 155.
•
System Manager:
▫
Encrypt or decrypt specified text or a file (see Encrypting/Decrypting
text or files, page 668).
▫
Determine the state of Amazon Cloud image (see Getting cloud image
status, page 688).
MicroStrategy Analytics Enterprise
•
The name of MicroStrategy Desktop has been changed to MicroStrategy
Developer.
MicroStrategy 9.4
•
System Manager:
© 2015, MicroStrategy Inc.
How to find business scenarios and examples
5
System Administration Guide
▫
Retrieve information from sources including a folder, the contents of a
file, or a System Manager parameter. This information can then be
passed to another process in the System Manager workflow for
processing a task (see Processing related tasks one by one, page 613).
▫
Create a file or folder as part of a System Manager workflow with the
new Rename Files process (see Creating a file or folder, page 670).
▫
Determine the number of files in a folder as part of a System Manager
workflow with the new Count File process (see Determining the
number of files in a folder, page 671).
▫
Rename a file or folder as part of a System Manager workflow with the
new Rename Files process (see Renaming a file or folder, page 674).
▫
Provide a network name and determine how IP addresses are assigned
when creating a new virtual machine (see Creating a virtual machine,
page 696).
•
When implementing LDAP authentication, it is recommended that you use
the LDAP Connectivity Wizard. For instructions, see Implementing LDAP
authentication, page 116.
•
Link users’ integrated authentication IDs to their LDAP user and group
information. For steps, see Linking integrated authentication users to
LDAP users, page 156.
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:
6
•
Implementing MicroStrategy: Development and Deployment
•
MicroStrategy Administration
Who should use this guide
© 2015, MicroStrategy Inc.
System Administration Guide
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
The steps to access the manuals are described in Accessing manuals and
other documentation sources, page 13.
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
For the most up-to-date translations of MicroStrategy documentation, refer to
the MicroStrategy Knowledge Base. 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.
© 2015, MicroStrategy Inc.
Who should use this guide
7
System Administration Guide
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:
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.
Manuals for MicroStrategy overview and evaluation
•
Introduction to MicroStrategy: Evaluation Guide
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.
•
8
MicroStrategy Evaluation Edition Quick Start Guide
Manuals for MicroStrategy overview and evaluation
© 2015, MicroStrategy Inc.
System Administration Guide
Overview of the installation and evaluation process, and additional
resources.
•
MicroStrategy Suite: Quick Start Guide
Evaluate MicroStrategy as a departmental solution. Provides detailed
information to download, install, configure, and use the MicroStrategy
Suite.
Resources for Identity and Loyalty
•
Alert Commerce Management System (CMS) Guide and Alert API
Reference
Content resources providing steps to deliver and manage marketing and
commerce content through the Alert mobile applications.
•
Usher Administration Guide
Steps to perform mobile identity validation using the Usher mobile
identity network to issue electronic badges for identifying users.
Manuals for query, reporting, and analysis
•
MicroStrategy Installation and Configuration 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: Enhancing Your Business
Intelligence Application
Instructions for advanced topics in the MicroStrategy system, building on
information in the Basic Reporting Guide. Topics include reports, Freeform
© 2015, MicroStrategy Inc.
Resources for Identity and Loyalty
9
System Administration Guide
SQL reports, Query Builder reports, filters, metrics, Data Mining Services,
custom groups, consolidations, and prompts.
•
Document and Dashboard Analysis Guide
Instructions for a business analyst to execute and analyze a document in
MicroStrategy Developer and MicroStrategy Web, building on basic
concepts about projects and reports presented in the MicroStrategy Basic
Reporting Guide.
•
MicroStrategy Report Services Document Creation Guide: Creating
Boardroom Quality Documents
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: Creating
Interactive Dashboards for your Data
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 OLAP Services Guide
Information on MicroStrategy OLAP Services, which is an extension of
MicroStrategy Intelligence Server. OLAP Services features include
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: Analyzing Data with
MicroStrategy Mobile
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: A Platform for
Mobile Intelligence
Information and instructions to install and configure MicroStrategy Mobile,
as well as instructions for a designer working in MicroStrategy Developer
10
Manuals for query, reporting, and analysis
© 2015, MicroStrategy Inc.
System Administration Guide
or MicroStrategy Web to create effective reports and documents for use
with MicroStrategy Mobile.
•
MicroStrategy System Administration Guide: Tuning, Monitoring, and
Troubleshooting your MicroStrategy Business Intelligence System
Concepts and high-level steps to implement, deploy, maintain, tune, and
troubleshoot a MicroStrategy business intelligence system.
•
MicroStrategy Supplemental Reference for System Administration: VLDB
Properties, Internationalization, User Privileges, and other Supplemental
Information for Administrators
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
•
Analytics Modules Installation and Porting Guide
•
Customer Analysis Module Reference
•
Sales Force Analysis Module Reference
•
Financial Reporting Analysis Module Reference
•
Sales and Distribution Analysis Module Reference
•
Human Resources Analysis Module Reference
Manuals for Narrowcast Services products
•
MicroStrategy Narrowcast Server Getting Started Guide
Instructions to work with the tutorial to learn Narrowcast Server
interfaces and features.
•
MicroStrategy Narrowcast Server Installation and Configuration Guide
© 2015, MicroStrategy Inc.
Manuals for Analytics Modules
11
System Administration Guide
Information to install and configure Narrowcast Server.
•
MicroStrategy Narrowcast Server Application Designer Guide
Fundamentals of designing Narrowcast Server applications.
•
MicroStrategy Narrowcast Server System Administrator Guide
Concepts and high-level steps to implement, maintain, tune, and
troubleshoot Narrowcast Server.
•
MicroStrategy Narrowcast Server Upgrade Guide
Instructions to upgrade an existing Narrowcast Server.
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.
•
Narrowcast Server SDK Guide
Instructions to customize Narrowcast Server functionality, integrate
Narrowcast Server with other systems, and embed Narrowcast Server
functionality within other applications. Documents the Narrowcast Server
Delivery Engine and Subscription Portal APIs, and the Narrowcast Server
SPI.
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.
This resource can be accessed from the MicroStrategy Product Manuals
page, as described in Accessing manuals and other documentation sources,
page 13.
12
Software Development Kits
© 2015, MicroStrategy Inc.
System Administration Guide
Documentation for MicroStrategy GIS Connectors
•
GIS Integration Help
Information to help you integrate MicroStrategy with Geospatial
Information Systems (GIS), including specific examples for integrating with
various third-party mapping services.
This resource can be accessed from the MicroStrategy Product Manuals
page, as described in Accessing manuals and other documentation sources,
page 13.
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 contextsensitive 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 from http://www.microstrategy.com/producthelp,
as well as from your MicroStrategy disk or the machine where MicroStrategy
was installed.
© 2015, MicroStrategy Inc.
Documentation for MicroStrategy GIS Connectors
13
System Administration Guide
*
Adobe Acrobat Reader is required to view these manuals. If you do not
have Acrobat Reader installed on your computer, you can download it from
http://get.adobe.com/reader/.
The best place for all users to begin is with the MicroStrategy Basic Reporting
Guide.
To access the installed manuals and other documentation sources, see the
following procedures:
•
To access documentation resources from any location, page 14
•
To access documentation resources on Windows, page 14
•
To access documentation resources on UNIX and Linux , page 14
To access documentation resources from any location
Visit http://www.microstrategy.com/producthelp.
1
To access documentation resources on Windows
1
From the Windows Start menu, choose Programs (or All Programs),
MicroStrategy Documentation, then Product Manuals. A page opens in your
browser showing a list of available manuals in PDF format and other
documentation sources.
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.
To access documentation resources on UNIX and Linux
1
14
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.
Accessing manuals and other documentation sources
© 2015, MicroStrategy Inc.
System Administration Guide
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
font
© 2015, MicroStrategy Inc.
•
Calculations
•
Code samples
•
Registry keys
•
Path and file names
•
URLs
•
Messages displayed in the screen
•
Text to be entered by the user
Documentation standards
15
System Administration Guide
Type
Indicates
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.
*
~
16
A warning icon alerts you to important information such as potential security risks; these
should be read before continuing.
Documentation standards
© 2015, MicroStrategy Inc.
1
INTRODUCTION TO
MICROSTRATEGY SYSTEM
ADMINISTRATION
Introduction
This chapter 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, page 2
•
Understanding the MicroStrategy architecture, page 3
•
Communicating with databases, page 7
•
Managing Intelligence Server, page 13
•
Managing and monitoring projects, page 26
•
Processing jobs, page 35
•
Using automated installation techniques, page 51
•
Security checklist before deploying the system, page 52
© 2015, MicroStrategy Inc.
1
System Administration Guide
Best practices for MicroStrategy system
administration
MicroStrategy recommends the following best practices to keep your system
running smoothly and efficiently:
•
Use the project life cycle of development, testing, production to fully test
your reports, metrics, and other objects before releasing them to users. For
an in-depth explanation of the project life cycle, see The project life cycle,
page 240.
•
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
The role-based administration model, page 78. For an introduction to the
MicroStrategy security model, including users and privileges, see Chapter
2, Setting Up User Security.
•
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 8, 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 on Enterprise
Manager, see the Enterprise Manager chapter in the MicroStrategy
Operations Manager Guide.
•
If you have multiple machines available to run Intelligence Server, you can
cluster those machines to improve performance and reliability. For
detailed information about clustering, including instructions, see Chapter 9,
Clustering Multiple MicroStrategy Servers.
•
Create caches for commonly used reports and documents to reduce the
database load and improve the system response time. For information
about caching, including instructions on how to set up caching, see Chapter
10, 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. For an overview of Intelligent
Cubes, see Chapter 11, Managing Intelligent Cubes.
2
© 2015, MicroStrategy Inc.
System Administration Guide
•
Schedule administrative tasks and reports to run during off-peak hours, so
that they do not adversely affect system performance. For instructions on
scheduling reports and administrative tasks, see Chapter 12, 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. For an
overview of Distribution Services, see Overview of Distribution
Services, page 546.
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.
•
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, page 4 and Indexing your data:
MicroStrategy metadata, page 4.
•
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, page 6.
© 2015, MicroStrategy Inc.
3
System Administration Guide
*
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 information on two-tier project
sources, see Tying it all together: projects and project sources, page 6.
•
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 13, Administering MicroStrategy Web and Mobile.
•
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.
*
For a more complete discussion of business intelligence architecture, see the
first chapter of the MicroStrategy Project Design Guide.
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 that the ETL process uses.
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.
4
Storing information: the data warehouse
© 2015, MicroStrategy Inc.
System Administration Guide
*
For more information about running the MicroStrategy Configuration
Wizard, see the MicroStrategy 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 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:
•
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 MicroStrategy Project Design Guide is devoted to
explaining schema objects.
•
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 MicroStrategy Basic
Reporting Guide and Advanced Reporting Guide are devoted to explaining
application objects.
•
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. Configuration objects are primarily covered in
the MicroStrategy System Administration Guide.
© 2015, MicroStrategy Inc.
Indexing your data: MicroStrategy metadata
5
System Administration Guide
Processing your data: Intelligence Server
Intelligence Server is the second tier in the MicroStrategy system. It must be
running for users to get information from your 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 on the
results of those reports to the users. For detailed information about
Intelligence Server, including how to start and stop it, see Managing
Intelligence Server, page 13.
A server definition is an instance of Intelligence Server and all 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 9, 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:
•
Metadata connectivity information, such as:
▫
Metadata DSN
▫
Metadata ID and encrypted password
•
MicroStrategy administrator user name
•
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 MicroStrategy Project Design Guide.
You can manage your projects using the System Administration Monitor. For
details, see Managing and monitoring projects, page 26.
6
Processing your data: Intelligence Server
© 2015, MicroStrategy Inc.
System Administration Guide
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:
•
Server connection, or three-tier, which specifies the Intelligence Server to
connect to.
•
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 MicroStrategy 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
MicroStrategy 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 10.
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:
© 2015, MicroStrategy Inc.
Connecting to the MicroStrategy metadata
7
System Administration Guide
•
How does a Developer user access the metadata?
•
How does a user connect to Intelligence Server?
•
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 MicroStrategy Installation and Configuration Guide.
8
Connecting to the MicroStrategy metadata
© 2015, 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:
•
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.
•
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.
•
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.
•
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 MicroStrategy
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:
•
Busy: connections that are actively submitting a query to a database
© 2015, MicroStrategy Inc.
Connecting to the data warehouse
9
System Administration Guide
•
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:
•
The connection string for the cached connection matches the connection
string that will be used for the job.
•
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.
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.
10
Monitoring database instance connections
© 2015, MicroStrategy Inc.
System Administration Guide
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:
•
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.
•
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.
•
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.
•
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.
•
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.
•
Prioritized access to databases—You can set access priority by user,
project, estimated job cost, or any combination of these.
•
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.
•
Database optimizations—Using VLDB properties, Intelligence Server is able
to take advantage of the unique performance optimizations that different
database servers offer.
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:
•
Join options, such as the star join and full outer join
•
Metric calculation options, such as when to check for NULLs and zeros
© 2015, MicroStrategy Inc.
Benefiting from centralized database access control
11
System Administration Guide
•
Pre- and post-SQL statements
•
Query optimizations, such as sub-queries and driving tables
•
Table types, such as temporary tables or derived tables
For more information about all the VLDB properties, see the VLDB Properties
chapter in the Supplemental Reference for System Administration.
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 databasespecific 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:
•
Loads newly supported database types. For example, properties for the
newest database servers that were recently added.
•
Loads updated properties for existing database types that are still
supported.
•
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. This will become
12
Updating VLDB properties for ODBC connections
© 2015, MicroStrategy Inc.
System Administration Guide
apparent if date/time functions stop working, particularly in Enterprise
Manager.
For more information about VLDB properties, see the VLDB Properties
chapter in the Supplemental Reference for System Administration.
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. The Upgrade Database Type dialog box opens.
For more detailed information about manually upgrading VLDB properties,
functions, and SQL syntax for your database server, see the MicroStrategy
Developer Help.
*
The MicroStrategy 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 8,
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,
© 2015, MicroStrategy Inc.
What happens when Intelligence Server starts?
13
System Administration Guide
and the metadata ID and encrypted password. For more information on server
definitions, see MicroStrategy Installation and Configuration Guide.
When Intelligence Server starts, it does the following:
•
Initializes internal processing units
•
Reads from the machine registry which server definition it is supposed to
use and connects to the specified metadata database
•
Loads configuration and schema information for each loaded project
•
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.
•
Loads schedules
•
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 chapter of the MicroStrategy
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:
•
Writes cache and History List information to backup files
•
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.
14
•
Closes database connections
•
Logs out connected users from the system
What happens when Intelligence Server stops?
© 2015, MicroStrategy Inc.
System Administration Guide
•
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 16.
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 21.
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:
•
From the Configuration Wizard: on the Specify a Port Number page, ensure
that the Register Intelligence Server as a Service check box is selected.
•
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
© 2015, MicroStrategy Inc.
Running Intelligence Server as an application or a service
15
System Administration Guide
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:
•
Routine maintenance on the Intelligence Server machine
•
Changes to Intelligence Server configuration options that cannot be
changed while Intelligence Server is running
•
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:
•
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 17.
•
If you are already using Developer, you may need to start and stop
Intelligence Server from within Developer. For instructions, see Developer,
page 19.
•
Use the web-based monitoring tool, MicroStrategy Operations Manager, to
stop and start local and remote Intelligence Servers. For an overview, see
Operations Manager, page 19
•
You can start and stop Intelligence Server as part of a Command Manager
script. For details, see Command Manager, page 20.
•
Finally, you can start and stop Intelligence Server from the command line
using MicroStrategy Server Control Utility. For instructions, see Command
line, page 20.
Prerequisites for starting and stopping Intelligence Server
16
•
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 63. For
a list of the permission groupings for server definition objects, see
Permissions for server governing and configuration, page 67.
•
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.
Running Intelligence Server as an application or a service
© 2015, MicroStrategy Inc.
System Administration Guide
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.
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.
The MicroStrategy Service Manager dialog box opens.
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. The MicroStrategy Service
Manager dialog box opens.
© 2015, MicroStrategy Inc.
Running Intelligence Server as an application or a service
17
System Administration Guide
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
18
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, then select Service Manager. The MicroStrategy Service Manager
dialog box opens.
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. The Service Options dialog box opens.
5
Select Automatic as the Startup Type option.
6
Click OK.
Running Intelligence Server as an application or a service
© 2015, MicroStrategy Inc.
System Administration Guide
*
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. The MicroStrategy Service Manager
dialog box opens.
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. The Service Options dialog box opens.
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.
Operations Manager
Operations Manager is a web-based console used to manage and monitor your
MicroStrategy system. You can use Operations Manager to start and stop local
and remote Intelligence Servers in your environment. For steps, see the
MicroStrategy Operations Manager Guide.
© 2015, MicroStrategy Inc.
Running Intelligence Server as an application or a service
19
System Administration Guide
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.
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 15, 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 22.
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
20
1
On the Windows Start menu, point to Settings, then choose Control Panel.
The Control Panel window opens.
2
Double-click Administrative Tools, and then double-click Services. The
Services window opens.
3
From the Services list, select MicroStrategy Intelligence Server. The
Properties dialog box for the Intelligence Server service opens.
4
You can do any of the following:
Running Intelligence Server as an application or a service
© 2015, MicroStrategy Inc.
System Administration Guide
•
To start the service, click Start.
•
To stop the service, click Stop.
•
To change the startup type, select a startup option from the drop-down
list.
— Automatic means that the service starts when the computer starts.
— Manual means that you must start the service manually.
— Disabled means that you cannot start the service until you change
the startup type to one of the other types.
5
When you are finished, click OK to close the Properties dialog box.
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:
•
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.
•
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.
•
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 15.
The default path for the Intelligence Server application executable is
C:\Program Files (x86)
© 2015, MicroStrategy Inc.
Running Intelligence Server as an application or a service
21
System Administration Guide
\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.
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, page 6.
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:
22
Managing MicroStrategy services from the command line
© 2015, MicroStrategy Inc.
System Administration Guide
•
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.
•
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.
•
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
machinename ls.
* -m
•
command is one of the commands from the list below.
•
instancename is the name of a server instance, where required. If a
name is not specified, the command uses the default instance name.
•
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
Note: This command does not require a machine name, login, or
service name.
--help
Display the version number of the Server Control Utility.
-V
Note: This command does not require a machine name, login, or
service name.
--version
Get information about the MicroStrategy network
List machines that the Server Control Utility can see and affect.
lm
Note: This command does not require a machine name, login, or
service name.
list-machines
List the MicroStrategy services available on a machine.
ls
Note: This command does not require a service name.
List the ODBC DSNs available on a machine.
Note: This command does not require a service name.
list-servers
lod
list-odbc-dsn
Configure a service
Display the configuration information for a service, in XML format.
For more information, see Using files to store output and provide
input, page 26.
gsvc instancename [>
filename.xml]
Note: You can optionally specify a file to save the configuration
properties to.
get-service-configuration
instancename [>
© 2015, MicroStrategy Inc.
Managing MicroStrategy services from the command line
23
System Administration Guide
If you want to. . .
Then use this command. . .
filename.xml]
Specify the configuration information for a service, in XML format.
For more information, see Using files to store output and provide
input, page 26.
ssvc instancename [<
filename.xml]
Note: 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 information, see Using files to store output and provide
input, page 26.
Note: You can optionally specify a file to save the configuration
properties to.
Specify the configuration properties of a server, in XML format.
For more information, see Using files to store output and provide
input, page 26.
Note: You can optionally specify a file to read the configuration
properties from.
gsc [> filename.xml]
get-server-configuration
[> filename.xml]
ssc [< filename.xml]
set-server-configuration
[< filename.xml]
Configure a server instance
Display the configuration information for a server instance, in XML
format. For more information, see Using files to store output and
provide input, page 26.
gsic instancename [>
filename.xml]
Note: You can optionally specify a file to save the configuration
properties to.
get-server-instanceconfiguration instancename
[> filename.xml]
Specify the configuration information for a server instance, in XML
format. For more information, see Using files to store output and
provide input, page 26.
ssic instancename
Note: You can optionally specify a file to read the configuration
properties from.
set-server-instanceconfiguration 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
24
Managing MicroStrategy services from the command line
© 2015, MicroStrategy Inc.
System Administration Guide
If you want to. . .
Then use this command. . .
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 newinstancename.
cpi instancename
newinstancename
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 Starting Intelligence Server as an application, page 21.
start --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 instancename
terminate instancename
© 2015, MicroStrategy Inc.
Managing MicroStrategy services from the command line
25
System Administration Guide
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:
26
Managing MicroStrategy services from the command line
© 2015, MicroStrategy Inc.
System Administration Guide
•
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 27.
•
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 28.
•
The Scheduled Maintenance monitor, which lists all the scheduled
maintenance tasks. For detailed information, see Scheduling
administrative tasks, page 528.
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 425.
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
© 2015, MicroStrategy Inc.
Managing project status, configuration, or security: Project view
27
System Administration Guide
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:
•
Manage the users and security filters for a project
•
View the change journal for a project (for details, see Monitoring system
activity: Change journaling, page 307)
•
Export and print the project’s schema or other project documentation
•
Load or unload projects from Intelligence Server, or idle or resume
projects for maintenance (for details, see Changing the status of a project,
page 32)
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 28.
•
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 528.
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
28
Expand Administration in the project source’s folder list.
Managing clustered Intelligence Servers: Cluster view
© 2015, MicroStrategy Inc.
System Administration Guide
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:
•
Manage the security policy settings for the project source
•
Join or leave a cluster
•
Manage the change journaling for projects on a cluster
•
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 Changing the status of
a project, page 32) 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 428.
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:
•
Loaded, page 30
•
Unloaded, page 30
•
Request Idle, page 30
•
Execution Idle, page 30
•
Warehouse Execution Idle, page 31
•
Full Idle, page 32
•
Partial Idle, page 32
For instructions on changing a project’s status, see Changing the status of a
project, page 32.
© 2015, MicroStrategy Inc.
Setting the status of a project
29
System Administration Guide
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 34.
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.
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:
•
Stops accepting new user requests from the clients for the project.
•
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
30
Setting the status of a project
© 2015, MicroStrategy Inc.
System Administration Guide
Intelligence Server. In this mode, Intelligence Server:
•
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.
•
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.
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:
•
Accepts new user requests from clients for the project, but it does not
submit any SQL to the data warehouse.
•
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.
•
Completes any jobs that do not require SQL to be executed against the
data warehouse.
© 2015, MicroStrategy Inc.
Setting the status of a project
31
System Administration Guide
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.
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 29.
32
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
Setting the status of a project
© 2015, MicroStrategy Inc.
System Administration Guide
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 29.
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. The Idle/Resume dialog box opens.
4
Select the options for the idle mode that you want to set the project to:
•
Request Idle (Request Idle): all executing and queued jobs finish
executing, and any newly submitted jobs are rejected.
•
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.
•
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.
© 2015, MicroStrategy Inc.
Setting the status of a project
33
System Administration Guide
5
•
Full Idle (Request Idle and Execution Idle for All jobs): all executing
and queued jobs are canceled, and any newly submitted jobs are
rejected.
•
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.
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:
34
•
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.
•
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 warehouseindependent activity to execute. Project1 now has dedicated access to the
data warehouse until Project2 is reset to Loaded.
•
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 reduce user access to
Project and data warehouse maintenance example scenarios
© 2015, MicroStrategy Inc.
System Administration Guide
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 50.
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 373.
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
© 2015, MicroStrategy Inc.
Intelligence Server job processing (common to all jobs)
35
System Administration Guide
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 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 36
•
Processing object browsing, page 40
•
Processing element browsing, page 41
•
Processing Report Services document execution, page 43
•
Processing HTML document execution, page 45
•
Client-specific job processing, page 47
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.
36
Processing report execution
© 2015, MicroStrategy Inc.
System Administration Guide
Component
Function
Analytical
Engine
Server
Performs complex calculations on a result set returned from the data warehouse, such as
statistical and financial functions. Also, sorts raw results returned from the Query 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
Server
Controls all access to the metadata for the entire project.
Object
Server
Creates, modifies, saves, loads and deletes objects from metadata. Also maintains a 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.
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
Server
Resolves prompts for report requests. Works in conjunction with Object Server and Element Server
to retrieve necessary objects and elements for a given request.
SQL Engine
Server
Generates the SQL needed for the report.
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.
Client
1
9
MicroStrategy Intelligence Server
Intelligence Pipeline
2
4
Resolution
Server
Object
cache
Object
Server
3
9
Report
Server
5
SQL
Engine
6
8
Query
Engine
7
Analytical
Engine
Report
cache
Metadata
Server
SQL/ODBC
Metadata
© 2015, MicroStrategy Inc.
SQL/ODBC
Data
Warehouse
Processing report execution
37
System Administration Guide
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, page 38.
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 exists for the report,
Intelligence Server creates the task list necessary to execute the report. For
more information on caching, see Result caches, page 438.
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, page 36):
1
38
Intelligence Server sends the job to the Resolution Server component. The
Resolution Server discovers that the report definition contains a prompt
Processing report execution
© 2015, MicroStrategy Inc.
System Administration Guide
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.
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, page 36). 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.
© 2015, MicroStrategy Inc.
Processing report execution
39
System Administration Guide
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 494.
The most prominent Intelligence Server components related to object
browsing are listed here.
Component
Function
Metadata
Server
Controls all access to the metadata for the entire project.
Object Server
Creates, modifies, saves, loads and deletes objects from metadata. Also maintains a server
cache of recently used objects.
Source Net
Server
Receives, de-serializes, and passes metadata object requests to the object server.
The diagram below shows the object request execution steps. An explanation
of each step follows the diagram.
Client
1
5
MicroStrategy Intelligence Server
Intelligence Pipeline
2
Object
cache
4
Object
Server
3
Metadata
Server
SQL/ODBC
Metadata
40
Processing object browsing
© 2015, MicroStrategy Inc.
System Administration Guide
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.
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 MicroStrategy 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 482.
The most prominent Intelligence Server components related to element
browsing are listed here.
© 2015, MicroStrategy Inc.
Processing element browsing
41
System Administration Guide
Component
Function
DB Element
Server
Transforms element requests into report requests and then sends report requests to the
warehouse.
Element
Net Server
Receives, de-serializes, and passes element request messages to the Element 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
Server
Resolves prompts for report requests. Works in conjunction with Object Server and Element
Server to retrieve necessary objects and elements for a given request.
SQL Engine
Server
Generates the SQL needed for the report.
The diagram below shows the element request execution steps. An explanation
of each step follows the diagram.
Client
1
9
MicroStrategy Intelligence Server
Intelligence Pipeline
2
Element
cache
8
Element
Server
5
Resolution
Server
6
SQL
Engine
7
Query
Engine
3
DB Element
Server
4
Report
Server
SQL/ODBC
Data
Warehouse
1
42
Intelligence Server receives the request.
Processing element browsing
© 2015, MicroStrategy Inc.
System Administration Guide
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.
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.
© 2015, MicroStrategy Inc.
Processing Report Services document execution
43
System Administration Guide
Client
1
8
3
MicroStrategy Intelligence Server
Intelligence Pipeline
5
4
2
Analytical
Engine
Document
Server
Resolution
Server
7a
6
Object
Server
Export
Engine
Metadata
Server
SQL/ODBC
Metadata
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.
44
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 in Processing report execution, page 36.
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
Processing Report Services document execution
© 2015, MicroStrategy Inc.
System Administration Guide
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:
8
•
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.
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.
© 2015, MicroStrategy Inc.
Processing HTML document execution
45
System Administration Guide
Client
1
5
MicroStrategy Intelligence Server
Intelligence Pipeline
2
3
4
HTML
Document
Server
Resolution
Server
Object
Server
Metadata
Server
SQL /ODBC
Metadata
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.
46
Processing HTML document execution
© 2015, MicroStrategy Inc.
System Administration Guide
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. These discussions cover the following clients:
•
Processing jobs from MicroStrategy Web products, page 47
•
Processing jobs from Narrowcast Server, page 49
For information about the processing steps performed by Intelligence Server
for all jobs, see Intelligence Server job processing (common to all jobs), page
35.
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 36).
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:
6
•
In MicroStrategy Web, the conversion is primarily performed in ASP
code.
•
In MicroStrategy Web Universal, the conversion is performed within
the Java transform classes.
•
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.
MicroStrategy Web sends the HTML to the client’s browser, which displays
the results.
© 2015, MicroStrategy Inc.
Client-specific job processing
47
System Administration Guide
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.
Reports in MicroStrategy Web can be exported to the following formats:
•
Export to Comma Separated File (CSV) or Excel with Plain Text, page 48
•
Export to Excel with Formatting, page 49
•
Export to PDF, page 49
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 382 and the
following sections.
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:
48
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.
Client-specific job processing
© 2015, MicroStrategy Inc.
System Administration Guide
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.
Note the following:
*•
•
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.
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.
© 2015, MicroStrategy Inc.
Client-specific job processing
49
System Administration Guide
*
For detailed information about Narrowcast Server, see the MicroStrategy
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 36.) 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:
•
Executing
•
Waiting in the queue
•
Waiting for a user to reply to a prompt
•
Canceling
•
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
50
Monitoring currently executing jobs
© 2015, MicroStrategy Inc.
System Administration Guide
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. A Quick View
dialog box opens.
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 wish 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
the MicroStrategy Installation and Configuration Guide.
© 2015, MicroStrategy Inc.
Monitoring currently executing jobs
51
System Administration 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 MicroStrategy Installation and
Configuration 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 MicroStrategy
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 MicroStrategy
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 chapter.
52
Using a Response file to install the product
© 2015, MicroStrategy Inc.
System Administration Guide
Completed
Security implementation
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 80). 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 56). Use this
model to:
•
Select and implement a system authentication mode to identify users
•
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. Note: There may
be a noticeable performance degradation because the system must encrypt and decrypt all
network traffic.
© 2015, MicroStrategy Inc.
Running a silent installation
53
System Administration Guide
Completed
Security implementation
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:
54
•
The asp directory
•
Admin.aspx
Running a silent installation
© 2015, MicroStrategy Inc.
2
SETTING UP USER SECURITY
Introduction
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 56
•
Controlling access to application functionality, page 62
•
Controlling access to data, page 80
•
Merging users or groups, page 102
Authentication, the process by which the system identifies the user, is an
integral part of any security model. Authenticating users is addressed in
Chapter 3, Identifying Users: Authentication.
© 2015, MicroStrategy Inc.
55
System Administration Guide
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 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
146.
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.
56
About MicroStrategy users
© 2015, MicroStrategy Inc.
System Administration Guide
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.
The following groups are provided with your MicroStrategy installation:
•
The Everyone group, page 57
•
Authentication-related groups, page 57
•
Groups corresponding to product offerings, page 58
•
Administrator groups, page 59
For a list of the privileges assigned to each group, see the List of Privileges
chapter in the Supplemental Reference for System Administration.
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-ofthe-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.
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 3, Identifying Users: Authentication.
•
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
© 2015, MicroStrategy Inc.
About MicroStrategy user groups
57
System Administration Guide
information about anonymous authentication and the Public/Guest group,
see Implementing anonymous authentication, page 112.
•
3rd Party Users: Users who access MicroStrategy projects through thirdparty (OEM) software.
•
LDAP Users: The group into which users that are imported from an LDAP
server are added.
•
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.
•
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 productspecific privileges.
58
•
Architect: Architects function as project designers and can create
attributes, facts, hierarchies, projects, and so on.
•
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.
•
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.
•
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.
•
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.
•
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.
About MicroStrategy user groups
© 2015, MicroStrategy Inc.
System Administration Guide
Administrator groups
•
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 72.
For a list of all user and group privileges in MicroStrategy, see the List of
Privileges chapter in the Supplemental Reference for System Administration.
To see which users are using certain privileges, use the License Manager. See
Using License Manager, page 227.
To view a user’s privileges
1
In Developer, log into 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. A list of users in the selected group appears in the main pane of
Developer.
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.
© 2015, MicroStrategy Inc.
Privileges
59
System Administration Guide
*
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 63.
To view the permissions for an object
1
From within Developer, right-click the object and select Properties. The
Properties dialog box opens.
2
Expand the Security category. The dialog box lists all users and groups with
access to the object, and what permissions those users and groups have for
the object.
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 15, 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 into 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
From the File menu, point to New and then select User. The User Editor
opens.
4
Specify the user information for each category in the editor. For details
about each field, see the MicroStrategy Developer Help.
*
60
The user login ID is limited to 50 characters.
Creating, importing, and deleting users and groups
© 2015, MicroStrategy Inc.
System Administration Guide
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 into 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 to continue.
5
If the user owns a profile folder, a dialog box opens asking if you want to
delete the user’s profile folder:
•
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.
•
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
© 2015, MicroStrategy Inc.
Monitoring users’ connections to projects
61
System Administration Guide
logged in to, plus one connection for <Server> indicating that the user is
logged in to the project source.
Note the following:
*—
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. A Quick View dialog box
opens.
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.
2
Press DELETE. Confirm that you wish to disconnect the user.
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 80), 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:
62
Monitoring users’ connections to projects
© 2015, MicroStrategy Inc.
System Administration Guide
•
Controlling access to objects: Permissions, page 63
•
Controlling access to functionality: Privileges, page 72
•
Defining sets of privileges: Security roles, page 75
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 72.
To modify permissions for an object in Developer
1
In Developer, right-click the object and select Properties. The Properties
dialog box for that object opens.
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.
© 2015, MicroStrategy Inc.
Controlling access to objects: Permissions
63
System Administration Guide
*
For specific information about each setting in the dialog box, press F1 to
see the Help.
To modify permissions for an object in MicroStrategy Web
1
In MicroStrategy Web, right-click an object and select Share. The Share
dialog box for that object opens.
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. The User/Group browser opens.
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. The users or groups are added to the list of users or groups,
with the specified permissions.
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. The
dialog box closes and your changes are saved.
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:
•
The Managers and Executive user groups have View access to the report.
•
The Developers user group (people who create and modify your
applications) has Modify access.
•
The Administrators user group has Full Control of the report.
•
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:
64
Controlling access to objects: Permissions
© 2015, MicroStrategy Inc.
System Administration Guide
•
The owner (the user who created the object) has Full Control permission.
•
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.
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. When you copy an object, 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
translations for an object’s name and description.
•
Browse
•
Read
•
Use
•
Execute
•
Browse
•
Read
•
Write
•
Delete
•
Use
•
Execute
Modify
Full Control
Grants permission to view and/or modify the object.
Grants all permissions for the object and also allows to modify the ACL for
the object.
© 2015, MicroStrategy Inc.
Control and all
other
permissions are
granted
Controlling access to objects: Permissions
65
System Administration Guide
Grouping
Description
Permissions
granted
Denied All
Explicitly denies all permissions for the object. None of the permissions
are assigned.
none; all are
denied
Default
Neither grants nor denies permissions. All permissions are inherited from
the groups to which the user or group belongs.
none
Custom
Allows the user or group to have a custom combination of permissions
that you can define.
custom choice
Consume
(Intelligent Cube only) Grants permission to create and execute reports
based on this Intelligent Cube.
•
Browse
•
Read
•
Use
•
Browse
•
Read
•
Use
•
Execute
•
Browse
•
Read
•
Write
•
Delete
•
Use
•
Execute
(Only available
in
MicroStrategy
Web)
Add
(Only available
in
MicroStrategy
Web)
Collaborate
(Only available
in
MicroStrategy
Web)
(Intelligent Cube only) Grants permission to create and execute reports
based on this Intelligent Cube, and republish/re-execute the Intelligent
Cube to update the data.
(Intelligent Cube only) Grants permission to create and execute reports
based on this Intelligent Cube, republish/re-execute the Intelligent Cube
to update the data, and modify the Intelligent Cube.
The permissions actually assigned to the user or group when you select a
permission grouping are explained in the table below.
66
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
Controlling access to objects: Permissions
© 2015, 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 70. 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.
Note: 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 70. This permission is checked at run time.
Note: 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.
© 2015, MicroStrategy Inc.
Controlling access to objects: Permissions
67
System Administration Guide
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.
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
Configuration
•
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
•
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
"Default"
Perform any task on that server.
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:
68
•
User identity: The user identity is what determines an object’s owner when
an object is created. The user identity also determines whether or not 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.
Controlling access to objects: Permissions
© 2015, MicroStrategy Inc.
System Administration Guide
•
Special privileges: A user may possess a special privilege that causes the
normal access checks to be bypassed:
▫
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
© 2015, MicroStrategy Inc.
Controlling access to objects: Permissions
69
System Administration Guide
▫
•
Public/Guest: Browse
Inherited ACL
▫
Administrator: Default
▫
Everyone: View
▫
Public/Guest: View
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:
70
•
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.
Controlling access to objects: Permissions
© 2015, MicroStrategy Inc.
System Administration Guide
*
•
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 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
© 2015, MicroStrategy Inc.
Controlling access to objects: Permissions
71
System Administration Guide
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 XML caches, page 442.
Controlling access to functionality: Privileges
As discussed earlier in this chapter, 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 control over all objects. For information about
permissions, see Controlling access to objects: Permissions, page 63.
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 227).
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 chapter in the Supplemental Reference for System
Administration.
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 75).
72
Controlling access to functionality: Privileges
© 2015, MicroStrategy Inc.
System Administration Guide
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 75.
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. The Find and
Replace Privileges dialog box opens. For detailed instructions on how to find
and replace privileges, see the MicroStrategy Developer Help.
How are privileges inherited?
A user’s privileges within a given project include the following:
•
Privileges assigned directly to the user (see Assigning privileges to users
and groups, page 72)
•
Privileges assigned to any groups of which the user is a member (see About
MicroStrategy user groups, page 56)
Groups also inherit privileges from their parent groups.
*
• Privileges assigned to any security roles that are assigned to the user
within the project (see Defining sets of privileges: Security roles, page 75)
© 2015, MicroStrategy Inc.
Controlling access to functionality: Privileges
73
System Administration Guide
•
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
56. These groups possess the following privileges:
•
Everyone, Public/Guest, Third Party Users, LDAP Public/Guest, and LDAP
Users, have no predefined privileges.
•
The predefined product-based user groups possess all the privileges
associated with their corresponding products. For a list of these groups,
see Groups corresponding to product offerings, page 58.
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.
•
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 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.
•
74
System Monitors
Controlling access to functionality: Privileges
© 2015, MicroStrategy Inc.
System Administration Guide
▫
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:
•
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.
•
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 How are privileges inherited?, page 73.
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 77.
© 2015, MicroStrategy Inc.
Defining sets of privileges: Security roles
75
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. The
Security Role Editor opens.
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.
Note the following:
*—
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. The security
role is assigned to the selected users and groups and the Security Role
Editor closes.
To create a security role
76
1
In Developer, log in to a project in 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.
Defining sets of privileges: Security roles
© 2015, MicroStrategy Inc.
System Administration Guide
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 chapter in the Supplemental Reference
for System Administration.
To select all privileges in a privilege group, select the group.
*
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 76.
8
Click OK to close the Security Role Editor and create 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 15, 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.
© 2015, MicroStrategy Inc.
Defining sets of privileges: Security roles
77
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. The Project Configuration Editor opens.
2
Expand the Project Access category. The Project Access - General dialog
box opens.
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. For
example, select the Normal Users security role.
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. For example,
remove the Everyone group.
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. The User Editor opens.
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
78
Defining sets of privileges: Security roles
© 2015, MicroStrategy Inc.
System Administration Guide
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 in common. For a list of the privileges
included with each predefined security role, see the List of Privileges chapter
in the Supplemental Reference for System Administration.
The predefined administration security roles are:
•
Power Users, which have the largest subset of privileges of any security
role.
•
Project Bulk Administrators, who can perform administrative functions on
multiple objects with Object Manager (see Copying objects between
projects: Object Manager, page 254), Command Manager (see Chapter 15,
Automating Administrative Tasks with Command Manager), and the Bulk
Repository Translation Tool.
•
Project Operations Administrators, who can perform maintenance on
various aspects of a project.
•
Project Operations Monitors, who can view the various Intelligence Server
monitors but cannot make any changes to the monitored systems.
•
Project Resource Settings Administrators, who can configure project-level
settings.
•
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 75.
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-ofthe-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.
© 2015, MicroStrategy Inc.
Defining sets of privileges: Security roles
79
System Administration Guide
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, page 80
•
Linking database users and MicroStrategy users: Passthrough execution,
page 84
•
Restricting access to data: Security filters, page 86
•
Controlling access to data at the database (RDBMS) level, page 98
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 98.
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
80
Controlling access to the database: Connection mappings
© 2015, MicroStrategy Inc.
System Administration Guide
diagram below in which all jobs running against the data warehouse use the
“MSTR users” database login.
Database
Connection
DSN
Project
All
users
Database
Database
Instance
Instance
DB Login :
MSTR users
Data
Warehouse
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 9.
To create a connection mapping
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. The Project Configuration Editor opens.
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.
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). The Add Members dialog box opens.
7
Select the desired user or group and click OK. That user or group is now
associated with the connection mapping.
8
Click OK to close the Project Configuration Editor. The new connection
mapping is saved.
© 2015, MicroStrategy Inc.
Controlling access to the database: Connection mappings
81
System Administration Guide
Connection mapping example
One case in which you may wish to use connection mappings is if you have
existing security views defined in the data warehouse and you wish to allow
MicroStrategy users’ jobs to execute on the data warehouse using those
specific login IDs. For example,
•
The CEO can access all data (warehouse login ID = “CEO”)
•
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:
•
Create a new database login definition for the CEO in MicroStrategy so it
matches his or her existing login ID on the data warehouse
•
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.”
All
users
Project
Database
Database
Instance
Instance
Database
Connection
DSN
DB Login :
MSTR users
DB Login:
CEO
CEO
Data
Warehouse
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.
If we were to create a connection mapping in the MicroStrategy Tutorial
project according to this example, it would look like the diagram below.
82
Controlling access to the database: Connection mappings
© 2015, MicroStrategy Inc.
System Administration Guide
For information on creating a new database connection, see Connecting to the
data warehouse, page 9. For information on creating a new database login, see
Connecting to the data warehouse, page 9.
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:
•
“US users” connect to the U.S. data warehouse (data warehouse login ID
“MSTR users”)
•
“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:
•
Create two database connections in MicroStrategy—one to each data
warehouse (this assumes that DSNs already exist for each data warehouse)
•
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.
© 2015, MicroStrategy Inc.
Controlling access to the database: Connection mappings
83
System Administration Guide
US
users
Database
Database
Instance
Instance
Project
Europe
users
Database
Connection: US
Database
Connection: Europe
DSN: US
DSN: Europe
DB Login :
MSTR users
DB Login :
MSTR users
Data
Warehouse
(US)
Data
Warehouse
(London)
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
114) 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.
84
Linking database users and MicroStrategy users: Passthrough
execution
© 2015, MicroStrategy Inc.
System Administration Guide
Why use passthrough execution?
You may wish to use passthrough execution for these reasons:
•
RDBMS auditing: If you wish 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.
•
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.
•
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
9.
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. The Project Configuration Editor opens.
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. The Project Configuration Editor closes and the changes are
saved.
© 2015, MicroStrategy Inc.
Linking database users and MicroStrategy users: Passthrough
execution
85
System Administration Guide
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.
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 98.
For more information about security filters, see the following:
•
Security filter example, page 86
•
How security filters work, page 87
•
Creating and applying a security filter, page 88
•
Security filters and metric levels, page 89
•
Using a single security filter for multiple users: System prompts, page 96
•
Merging security filters, page 93
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.
86
Restricting access to data: Security filters
© 2015, 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 chapter in the MicroStrategy 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 89.
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 10, Improving Report and Document Response
Time: Caching.
© 2015, MicroStrategy Inc.
Restricting access to data: Security filters
87
System Administration Guide
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 93.
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.
Prerequisites
To create security filters, you must have the following privileges:
•
Create Application Objects (under the Common Privileges privilege group)
•
Use Report Filter Editor (under the Developer privilege group)
•
Use Security Filter Manager (under the Administration privilege group)
To create and apply a security filter for a user or group
1
In Developer, from the Administration menu, point to Projects and then
select Security Filter Manager. The Security Filter Manager opens.
2
From the Choose a project drop-down list, select the project that you want
to create a security filter for.
Create a security filter
88
3
Select the Security Filters tab.
4
Select one:
•
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.
•
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.
Restricting access to data: Security filters
© 2015, MicroStrategy Inc.
System Administration Guide
Apply the security filter to a user or group
5
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.
6
In the right side of the Security Filter Manager, select Security Filters.
7
Browse to the user or group that you want to apply the security filter to,
and select that user or group.
8
Click > to apply the selected security filter to the selected user or group.
9
Click OK to close the Security Filter Manager.
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. The Project Configuration Editor opens.
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 to close the Project Configuration Editor.
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 chapter in the
Advanced Reporting 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.
© 2015, MicroStrategy Inc.
Restricting access to data: Security filters
89
System Administration Guide
This behavior can be modified by using the top range attribute and bottom
range attribute properties.
•
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.
•
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 92.
The examples below use a report with Category, Subcategory, and Item on the
rows, and three metrics in the columns:
•
Revenue
•
Subcategory Revenue, which is defined with absolute filtering to the
Subcategory level
•
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.
90
Restricting access to data: Security filters
© 2015, MicroStrategy Inc.
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.
© 2015, MicroStrategy Inc.
Restricting access to data: Security filters
91
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.
Prerequisites
To modify security filters, you must have the Use Security Filter Manager
privilege.
92
Restricting access to data: Security filters
© 2015, MicroStrategy Inc.
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. The Security Filter Manager opens.
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:
6
7
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.
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.
Click OK to close the Security Filter Manager.
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:
© 2015, MicroStrategy Inc.
Restricting access to data: Security filters
93
System Administration Guide
•
Merging related security filters with OR and unrelated security filters
with AND, page 94 (This is the default method for merging security filters)
•
Merging all security filters with AND, page 95
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
Invalidating result caches, page 452.
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:
94
Restricting access to data: Security filters
© 2015, MicroStrategy Inc.
System Administration Guide
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.
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
© 2015, MicroStrategy Inc.
Restricting access to data: Security filters
95
System Administration Guide
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.
Prerequisites
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. The Project Configuration Editor opens.
3
Expand the Security Filter category, and then select General.
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 94)
•
Intersect (AND) all Security Filters (see Merging all security filters with
AND, page 95)
5
Click OK to close the Project Configuration Editor.
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.
Note the following:
*•
•
96
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
Restricting access to data: Security filters
© 2015, MicroStrategy Inc.
System Administration Guide
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 Using LDAP attributes in security
filters, page 144.
For examples of how to use system prompts in security filters, see:
•
Simplifying the security filter definition process, page 98
•
Implementing a report-level security filter, page 98
•
Using database tables that contain security information, page 98
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. The Security Filter Manager opens.
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. The Security Filter Editor opens.
5
Double-click on the text Double-click here to add a qualification. The
Filtering Options pane opens.
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 chapter of the MicroStrategy Advanced Reporting
Guide.
9
When you have finished typing your custom expression, click Validate to
make sure that its syntax is correct.
© 2015, MicroStrategy Inc.
Restricting access to data: Security filters
97
System Administration Guide
10 Click Save and close. Type a name for the security filter and click Save. The
new security filter is saved.
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.
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
98
Controlling access to data at the database (RDBMS) level
© 2015, MicroStrategy Inc.
System Administration Guide
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.
In addition to the security features that different database management
systems offer, MicroStrategy is designed to work with general database
security techniques such as:
•
Security views, page 99
•
Splitting fact tables by rows, page 99
•
Splitting fact tables by columns, page 101
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.
© 2015, MicroStrategy Inc.
Controlling access to data at the database (RDBMS) level
99
System Administration Guide
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
ID
Customer
Address
Member
Bank
Transaction Amount
($)
Current Balance
($)
123456
12 Elm St.
1st National
400.80
40,450.00
945940
888 Oak St.
Eastern
Credit
150.00
60,010.70
908974
45 Crest Dr.
People’s
Bank
3,000.00
100,009.00
886580
907 Grove Rd.
1st National
76.35
10,333.45
562055
1 Ocean Blvd.
Eastern
Credit
888.50
1,000.00
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
ID
Customer
Address
Member
Bank
Transaction Amount
($)
Current Balance
($)
123456
12 Elm St.
1st National
400.80
40,450.00
886580
907 Grove Rd.
1st National
76.35
10,333.45
The table for Eastern Credit would look like this:
Customer
ID
Customer
Address
Member
Bank
Transaction Amount
($)
Current Balance
($)
945940
888 Oak St.
Eastern
Credit
150.00
60,010.70
562055
1 Ocean Blvd.
Eastern
Credit
888.50
1,000.00
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
100
Controlling access to data at the database (RDBMS) level
© 2015, MicroStrategy Inc.
System Administration Guide
by rows for performance benefits. For more information on partitioning, see
the MicroStrategy Advanced Reporting 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
ID
Customer
Address
Member
Bank
Transaction
Amount ($)
Current
Balance ($)
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
ID
Customer
Address
Member
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
ID
© 2015, MicroStrategy Inc.
Transaction
Amount ($)
Current
Balance ($)
Controlling access to data at the database (RDBMS) level
101
System Administration Guide
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:
•
How users and groups are merged, page 102
•
Running the User Merge Wizard, page 104
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 253.
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. Batchmerging 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.
102
How users and groups are merged
© 2015, MicroStrategy Inc.
System Administration Guide
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.
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.
© 2015, MicroStrategy Inc.
How users and groups are merged
103
System Administration Guide
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 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.
104
Running the User Merge Wizard
© 2015, MicroStrategy Inc.
System Administration Guide
To merge users or groups
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select User Merge Wizard. The User Merge Wizard opens.
2
Specify the project source containing the users/groups you wish to merge.
3
Select whether you wish 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
102.
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 wish 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. They display below the selected destination user or group.
7
On the Summary page, review your selections, and click Finish. The users
or groups are merged.
© 2015, MicroStrategy Inc.
Running the User Merge Wizard
105
System Administration Guide
106
Running the User Merge Wizard
© 2015, MicroStrategy Inc.
3
IDENTIFYING USERS:
AUTHENTICATION
Introduction
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 108.
•
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
© 2015, MicroStrategy Inc.
107
System Administration Guide
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.
▫
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 are:
108
•
Standard: Intelligence Server is the authentication authority. This is the
default authentication mode. For more information, see Implementing
standard authentication, page 111.
•
Anonymous: Users log in as “Guest” and do not need to provide a
password. This authentication mode may be required to enable other
© 2015, MicroStrategy Inc.
System Administration Guide
authentication modes, such as database warehouse or LDAP. For more
information, see Implementing anonymous authentication, page 112.
•
Database warehouse: The data warehouse database is the authentication
authority. For more information, see Implementing database warehouse
authentication, page 114.
•
LDAP (lightweight directory access protocol): An LDAP server is the
authentication authority. For more information, see Implementing LDAP
authentication, page 116.
•
Single sign-on: Single sign-on encompasses several different third-party
authentication methods, including:
•
▫
Windows authentication: Windows is the authentication authority. For
more information, see Implementing Windows NT authentication, page
147.
▫
Integrated authentication: A domain controller using Kerberos
authentication is the authentication authority. For more information,
see Enabling integrated authentication, page 155.
▫
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 177.
MicroStrategy Usher: Users log into Web and Mobile using MicroStrategy
Usher. Usher enables users to electronically validate their identity using
the Usher app and mobile badge on their smartphone, instead of entering a
password. For steps, see Enabling Usher authentication for Web and
Mobile, page 194.
For examples of situations where you might want to implement specific
authentication modes, and the steps to do so, see Authentication examples,
page 198.
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 111).
© 2015, MicroStrategy Inc.
Configuring the authentication mode for a project source
109
System Administration Guide
To configure the authentication mode for a project source
1
In Developer, from the Tools menu, select Project Source Manager. The
Project Source Manager opens.
2
Select the appropriate project source and click Modify. The Project Source
Manager for that project source opens.
3
On the Advanced tab, select the appropriate option for the default
authentication mode that you want to use.
4
Click OK twice. The Project Source Manager closes and the specified
authentication mode is now the default for that project source.
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:
•
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.)
•
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 “connect” or map multiple
authentication systems to a single user object in the MicroStrategy metadata.
110
Importing users from different authentication systems
© 2015, MicroStrategy Inc.
System Administration Guide
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 9. 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
© 2015, MicroStrategy Inc.
Sharing user accounts between users
111
System Administration Guide
▫
The minimum number of upper-case characters that the password must
contain
▫
The minimum number of lower-case characters that the password must
contain
▫
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
112
Steps to implement standard authentication
© 2015, MicroStrategy Inc.
System Administration Guide
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 access
to functionality: Privileges, page 72 and Controlling access to objects:
Permissions, page 63.
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. The Properties - project source
name dialog box opens.
4
In the Security tab, click Add. The Select Developer Users and Groups
dialog box opens.
5
Select the Public/Guest group.
6
In the Access Permission list, select Connect.
7
Click OK. The Select Developer Users and Groups dialog box closes.
8
Click OK. The Properties dialog box closes.
© 2015, MicroStrategy Inc.
Steps to implement standard authentication
113
System Administration Guide
9
Follow the procedure in Configuring the authentication mode for a project
source, page 109 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 database warehouse
authentication
This mode of authentication identifies users by means of a login ID and
password stored in the data warehouse database. The RDBMS is the
authentication authority and verifies that the login ID and password are valid.
Each report is executed on the RDBMS under the RDBMS account of the user
who submitted the report from the MicroStrategy system. Users log in to the
MicroStrategy system with their RDBMS login and password, and each
MicroStrategy user is linked to an RDBMS account.
Use database warehouse authentication if you want the data warehouse
RDBMS to be the authority for identifying users and you do not want to
maintain user credentials in Intelligence Server as well as the RDBMS. You can
also use this configuration if you need to keep an audit trail at the RDBMS
level for each query executed by each individual user.
If you use database authentication, for security reasons MicroStrategy
~ recommends that you use the setting Create caches per database login.
This ensures that users who execute their reports using different database
login IDs cannot use the same cache. You can set this in the Project
Configuration Editor in the Caching: Result Caches: Creation category.
Database warehouse authentication information flow
The following scenario presents an overview of the general flow of information
between Intelligence Server and a database server when a database user logs
into Developer or MicroStrategy Web.
1
The user anonymously logs in to a project source.
This is done anonymously because the user has not yet logged in to a
specific project. Because a warehouse database is not associated with the
project source itself, users are not authenticated until they select a project
to use. For more information about anonymous authentication, including
instructions on enabling it for a project source, see Implementing
anonymous authentication, page 112.
114
Database warehouse authentication information flow
© 2015, MicroStrategy Inc.
System Administration Guide
Note the following:
*—
By default, the Public/Guest group is denied access to all projects.
A security role with View access to the projects must be explicitly
assigned to the Public/Guest group, so that these users can see and
log in to the available projects.
— All users logging in to a database warehouse authentication project
source can see all projects visible to the Guest user. Project access
is then granted or denied for each individual user when the user
attempts to log into the project.
2
The user selects a project, and then logs in to that project using her data
warehouse login ID and password. She is authenticated against the data
warehouse database associated with that project.
To enable database authentication, you must link the users in the
MicroStrategy metadata to RDBMS users. Linking causes Intelligence
Server to map a warehouse database user to a MicroStrategy user. If a user
attempts to log in to a project without having been linked to a
MicroStrategy user, a “User not found” error message is returned.
Steps to implement database warehouse
authentication
The procedure below gives the high-level steps for configuring your
Intelligence Server for database warehouse authentication. For additional
information about any of these steps, see the MicroStrategy Developer Help.
High-level steps for configuring database warehouse authentication
1
Create a DSN and a database instance for the authentication database.
2
Configure the project source to allow anonymous authentication (see
Implementing standard authentication, page 111).
3
Configure the project source to use database warehouse authentication (see
Configuring the authentication mode for a project source, page 109).
4
Assign a security role to the Public/Guest group for each project to which
you want to provide access (see Managing security roles, page 75).
5
Link each MicroStrategy user to an RDBMS user. In the User Editor, in the
Authentication: Metadata category, type the data warehouse login ID in
the Database Login field.
© 2015, MicroStrategy Inc.
Steps to implement database warehouse authentication
115
System Administration Guide
*
You can create the MicroStrategy users by importing a list of the
RDBMS users into the MicroStrategy system. For instructions, see
Creating, importing, and deleting users and groups, page 60.
6
For each project, in the Project Configuration Editor, in the Database
instances: Authentication: Metadata category, specify the database
instance for the authentication database.
7
For each project, enable database execution using linked warehouse logins
(see Linking database users and MicroStrategy users: Passthrough
execution, page 84).
8
To enable database authentication in MicroStrategy Web, log in as an
administrator. On the Preferences page, select Project Defaults. The
Project Defaults page is displayed.
9
Under Security, select the Database Authentication check box, and then
click Apply.
Database warehouse and metadata (6.x)
authentication
This mode of authentication uses the login ID and password entered by the
user for both the metadata and data warehouse databases. It is available only
for connecting to MicroStrategy 6.X project sources.
Under this authentication mode, Intelligence Server passes the login
credentials to the metadata database when you log in to the project source.
You implement this authentication mode by following the same general steps
as for database warehouse authentication, in Steps to implement database
warehouse authentication, page 115.
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.
116
Database warehouse and metadata (6.x) authentication
© 2015, MicroStrategy Inc.
System Administration Guide
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, Microsoft Directory Services, and
Sun ONE 5.1/iPlanet. For the latest set of certified and supported LDAP
servers, refer to the MicroStrategy 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, page 136.
4
To make changes in your LDAP configuration, use the procedures described
in Managing LDAP authentication, page 138.
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.
© 2015, MicroStrategy Inc.
LDAP information flow
117
System Administration Guide
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.
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:
▫
118
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
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
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, page 122.
•
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 124.
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 128.
•
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 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 129.
•
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.
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
119
System Administration Guide
For additional information on database passthrough authentication, see
Determining whether to enable database passthrough authentication with
LDAP, page 130.
•
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 131.
•
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 134.
•
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.
▫
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 124.
120
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
▫
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 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
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
121
System Administration Guide
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 Using LDAP attributes in security filters, page 144.
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, page 136.
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 MicroStrategy 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 UNIX and Linux platforms
~
In order for LDAP to work properly with Intelligence Server Universal,
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.
122
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
1
The behavior between Intelligence Server and the LDAP SDK varies
slightly depending on the LDAP SDK used. The MicroStrategy 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
MicroStrategy 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:
4
•
Windows environment: Add the path of the LDAP SDK libraries as a
system environment variable so that Intelligence Server can locate
them.
•
UNIX/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 below.
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.
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
123
System Administration Guide
1
In a UNIX/Linux console window, browse to <HOME_PATH> where
<HOME_PATH> is the directory you specified as the home directory during
MicroStrategy 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 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:
124
•
Highest level to start an LDAP search: Search root, page 125 provides
examples of these parameters as well as additional details of each
parameter and some LDAP server-specific notes.
•
Finding users: user search filters, page 126 provides an overview of LDAP
user search filters.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
•
Finding groups: group search filters, page 127 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.
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
Operations, Consultants, and Sales
Sales
Include all users and groups from
Operations, Consultants, and Technology
Departments (with an exclusion clause in the User/Group search
filter to exclude users who belong to Marketing and Administration)
Include all users and groups from
Technology and Operations but not
Consultants.
Departments (with an exclusion clause in the User/Group search
filter to exclude users who belong to 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”:
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
125
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 127).
User search filters are generally in the form (&(objectclass=LDAP_
USER_OBJECT_CLASS)(LDAP_LOGIN_ATTR=#LDAP_LOGIN#)) where:
•
LDAP_USER_OBJECT_CLASS indicates the object class of the LDAP users.
For example, you can enter (&(objectclass=person)(cn=#LDAP_
LOGIN#)).
•
LDAP_LOGIN_ATTR indicates which LDAP attribute to use to store LDAP
logins. For example, you can enter (&(objectclass=person)
(cn=#LDAP_LOGIN#)).
•
#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#)),
126
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
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):
•
(&(objectclass=LDAP_GROUP_OBJECT_CLASS) (LDAP_MEMBER_
LOGIN_ATTR=#LDAP_LOGIN#))
•
(&(objectclass=LDAP_GROUP_OBJECT_CLASS) (LDAP_MEMBER_
DN_ATTR=#LDAP_DN#))
•
(&(objectclass=LDAP_GROUP_OBJECT_CLASS)
(gidNumber=#LDAP_GIDNUMBER#))
The group search filter forms listed above have the following placeholders:
•
LDAP_GROUP_OBJECT_CLASS indicates the object class of the LDAP
groups. For example, you can enter (&(objectclass=groupOfNames)
(member=#LDAP_DN#)).
•
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#)).
•
#LDAP_DN# can be used in this filter to represent the distinguished name
of an LDAP user.
•
#LDAP_LOGIN# can be used in this filter to represent an LDAP user’s
login.
•
#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.
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
127
System Administration Guide
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.
128
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, 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:
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
129
System Administration Guide
•
Whether the LDAP password is incorrect, has been locked out, or has
expired
•
Whether the LDAP user account has been disabled, or has been identified
as an intruder and is locked out
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 56.
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.
130
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
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.
Connection
Type
Benefits
Considerations
Import LDAP
users and
groups
•
Users and groups are created in the
metadata.
•
•
Users and groups can be assigned
additional privileges and permissions in
MicroStrategy.
In environments that have many LDAP
users, importing can quickly fill the
metadata with these users and their
related information.
•
Users and groups may not have the correct
permissions and privileges when they are
initially imported into MicroStrategy.
•
Users to be linked to must already exist in
the MicroStrategy metadata.
•
Privileges are limited to those for the
Public/Guest group.
•
Users’ personal folders and Inboxes are
deleted from the system after they log out.
•
Users have their own inboxes and
personal folders in MicroStrategy.
Link users and
groups
without
importing
•
For environments that have many LDAP
users, linking avoids filling the metadata
with users and their related information.
•
You can use Command Manager to
automate the linking process using
scripts. See the Command Manager
Help for details.
Allow
anonymous or
guest users
•
Users can log in immediately without
having to create a new MicroStrategy
user.
The options for importing users into MicroStrategy are described in detail in
the following sections:
•
Importing LDAP users and groups into MicroStrategy, page 132
•
Linking users and groups without importing, page 133
•
Allowing anonymous/guest users with LDAP authentication, page 133
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 described in Managing
LDAP authentication, page 138.
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
131
System Administration Guide
Importing LDAP users and groups into MicroStrategy
You can choose to import LDAP users and groups at login, in a batch process,
or a combination of the two. Imported users are automatically members of
MicroStrategy’s LDAP Users group, and are assigned the access control list
(ACL) and privileges of that group. To assign different ACLs or privileges to a
user, you can move the user to another MicroStrategy user group.
When an LDAP user is imported into MicroStrategy, you can also choose to
import that user’s LDAP groups. If a user belongs to more than one group, all
the user’s groups are imported and created in the metadata. Imported LDAP
groups are created within MicroStrategy’s LDAP Users folder and in
MicroStrategy’s User Manager.
LDAP users and LDAP groups are all created within the MicroStrategy LDAP
Users group at the same level. While the LDAP relationship between a user
and any associated groups exists in the MicroStrategy metadata, the
relationship is not visually represented in Developer. For example, looking in
the LDAP Users folder in MicroStrategy immediately after an import or
synchronization, you might see the following list of imported LDAP users and
groups:
If you want a users’ groups to be shown in MicroStrategy, you must manually
move them into the appropriate groups.
The relationship between an imported LDAP user or group and the
MicroStrategy user or group is maintained by a link in the MicroStrategy
metadata, which is in the form of a Distinguished Name. A Distinguished
Name (DN) is the unique identifier of an entry (in this case a user or group) in
the LDAP directory.
*
The MicroStrategy user’s Distinguished Name is different from the DN
assigned for the authentication user. The authentication user’s DN is the
DN of the MicroStrategy account that is used to connect to the LDAP
server and search the LDAP directory. The authentication user can be
anyone who has search privileges in the LDAP server, and is generally the
LDAP administrator.
Removing a user from the LDAP directory does not effect the user’s presence
in the MicroStrategy metadata. Deleted LDAP users are not automatically
deleted from the MicroStrategy metadata during synchronization. You can
revoke a user’s privileges in MicroStrategy, or remove the user manually.
You cannot export users or groups from MicroStrategy to an LDAP directory.
132
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
Linking users and groups without importing
A link is a connection between an LDAP user or group and a MicroStrategy
user or group which allows an LDAP user to log in to MicroStrategy. Unlike an
imported LDAP user, a linked LDAP user is not created in the MicroStrategy
metadata.
An LDAP group can only be linked to a MicroStrategy group, and an LDAP
user can only be linked to a MicroStrategy user. It is not possible to link a
group to a user without giving the user membership in the group.
When an LDAP user or group is linked to an existing MicroStrategy user or
group, no new user or group is created within the MicroStrategy metadata as
with importing. Instead, a link is established between an existing
MicroStrategy user or group and an LDAP user or group, which allows the
LDAP user to log in to MicroStrategy.
The link between an LDAP user or group and the MicroStrategy user or group
is maintained in the MicroStrategy metadata in the form of a shared
Distinguished Name.
The user’s or group’s LDAP privileges are not linked with the MicroStrategy
user. In MicroStrategy, a linked LDAP user or group receives the privileges of
the MicroStrategy user or group to which it is linked.
LDAP groups cannot be linked to MicroStrategy user groups. For example, you
cannot link an LDAP group to MicroStrategy’s Everyone group. However, it is
possible to link an LDAP user to a MicroStrategy user that has membership in
a MicroStrategy group.
Allowing anonymous/guest users with LDAP authentication
An anonymous or guest LDAP user in MicroStrategy is an existing LDAP user
who logs in to MicroStrategy using any login and password that is not
imported into MicroStrategy or linked to a MicroStrategy user.
LDAP guest users can use MicroStrategy’s capabilities and be authenticated as
LDAP guests. All LDAP guest users receive the privileges of the LDAP
Public/Guest and the Public/Guest groups in MicroStrategy.
The LDAP server must be configured to allow anonymous or guest
authentication requests from MicroStrategy.
Because guest users are not present in the metadata, there are certain
* actions these users cannot perform in MicroStrategy, even if the associated
privileges and permissions are explicitly assigned. Examples include most
administrative actions.
When the user is logged in as an anonymous/guest user:
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
133
System Administration Guide
•
The user does not have a History List, because the user is not physically
present in the metadata.
•
The user cannot create objects and cannot schedule reports.
•
The User Connection monitor records the LDAP user’s user name.
•
Intelligence Server statistics record the session information under the user
name LDAP USER.
Determining whether to automatically synchronize LDAP user and
group information
In any company’s security model, steps must be taken to account for a
changing group of employees. Adding new users and removing ones that are no
longer with the company is straightforward. Accounting for changes in a user’s
name or group membership can prove more complicated. To ease this process,
MicroStrategy supports user name/login and group synchronization with the
information contained within an LDAP directory.
If you choose to have MicroStrategy automatically synchronize LDAP users
and groups, any LDAP group changes that have occurred within the LDAP
server will be applied within MicroStrategy the next time an LDAP user logs
in to MicroStrategy. This keeps the LDAP directory and the MicroStrategy
metadata in synchronization.
By synchronizing users and groups between your LDAP server and
MicroStrategy, you can update the imported LDAP users and groups in the
MicroStrategy metadata with the following modifications:
•
User synchronization:
▫
•
User details such as user name in MicroStrategy are updated with the
latest definitions in the LDAP directory.
Group synchronization:
▫
Group details such as group name in MicroStrategy are updated with
the latest definitions in the LDAP directory.
When synchronizing LDAP users and groups in MicroStrategy, you should be
aware of the following circumstances:
•
If an LDAP user or group has been given new membership to a group that
has not been imported or linked to a group in MicroStrategy and import
options are turned off, the group cannot be imported into MicroStrategy
and thus cannot apply its permissions in MicroStrategy.
For example, User1 is a member of Group1 in the LDAP directory, and
both have been imported into MicroStrategy. Then, in the LDAP directory,
User1 is removed from Group1 and given membership to Group2.
However, Group2 is not imported or linked to a MicroStrategy group.
134
Checklist: Information required for connecting your LDAP server to
MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
Upon synchronization, in MicroStrategy, User1 is removed from Group1,
and is recognized as a member of Group2. However, any permissions for
Group2 are not applied for the user until Group2 is imported or linked to
a MicroStrategy group. In the interim, User1 is given the privileges and
permissions of the LDAP Users group.
•
When users and groups are deleted from the LDAP directory, the
corresponding MicroStrategy users and groups that have been imported
from the LDAP directory remain in the MicroStrategy metadata. You can
revoke users’ and groups’ privileges in MicroStrategy and remove the users
and groups manually.
•
Regardless of your synchronization settings, if a user’s password is
modified in the LDAP directory, a user must log in to MicroStrategy with
the new password. LDAP passwords are not stored in the MicroStrategy
metadata. MicroStrategy uses the credentials provided by the user to
search for and validate the user in the LDAP directory.
Consider a user named Joe Doe who belongs to a particular group, Sales, when
he is imported into MicroStrategy. Later, he is moved to a different group,
Marketing, in the LDAP directory. The LDAP user Joe Doe and LDAP groups
Sales and Marketing have been imported into MicroStrategy. Finally, the user
name for Joe Doe is changed to Joseph Doe, and the group name for
Marketing is changed to MarketingLDAP.
The images below show a sample LDAP directory with user Joe Doe being
moved within the LDAP directory from Sales to Marketing.
The following table describes what happens with users and groups in
MicroStrategy if users, groups, or both users and groups are synchronized.
© 2015, MicroStrategy Inc.
Checklist: Information required for connecting your LDAP server to
MicroStrategy
135
System Administration Guide
Sync
Users?
Sync
Groups?
User Name After
Synchronization
Group Name After
Synchronization
User Membership After
Synchronization
No
No
Joe Doe
Marketing
Sales
No
Yes
Joe Doe
MarketingLDAP
Sales
Yes
No
Joseph Doe
Marketing
Marketing
Yes
Yes
Joseph Doe
MarketingLDAP
MarketingLDAP
Setting up LDAP authentication in MicroStrategy
When you have collected the connection information for your LDAP server and
your LDAP SDK, you can use the LDAP Connectivity Wizard to set up your
LDAP connection. The LDAP Connectivity Wizard helps step you through the
initial setup of using your LDAP server to authenticate users and groups in
MicroStrategy. The steps to set up your LDAP connection are described below.
Prerequisites
•
You have collected the information for your LDAP server, and made
decisions regarding the LDAP authentication methods you want to use, as
described in Checklist: Information required for connecting your LDAP
server to MicroStrategy, page 118.
•
If you want Intelligence Server to access your LDAP server over a secure
SSL connection, you must do the following:
a
Obtain a valid certificate from your LDAP server and save it on the
machine where Intelligence Server is installed. The steps to obtain the
certificate depend on your LDAP vendor, and the operating system that
your LDAP server runs on. For specific steps, refer to the
documentation for your LDAP vendor.
b
Follow the procedure recommended by your operating system to install
the certificate.
To set up LDAP authentication in MicroStrategy
Connecting your LDAP server using the LDAP Connectivity Wizard
136
1
In Developer, log in to a project source, as a user with administrative
privileges.
2
From the Administration menu, select Server, and click LDAP Connectivity
Wizard. The LDAP Connectivity Wizard opens.
Setting up LDAP authentication in MicroStrategy
© 2015, MicroStrategy Inc.
System Administration Guide
3
On the Welcome page, click Next. The LDAP Server Information page
opens.
4
Type the following information:
•
Host: The machine name or IP address of the LDAP server.
•
Port: The network port that the LDAP server uses. For clear text
connections, the default value is 389. If you want Intelligence Server to
access your LDAP over an encrypted SSL connection, the default value
is 636.
5
If you want Intelligence Server to access your LDAP over an encrypted SSL
connection, select SSL (encrypted). The Server Certificate file field is
enabled.
6
In the Server Certificate file field, depending on your LDAP server vendor,
point to the SSL certificate in the following ways:
•
Microsoft Active Directory: No information is required.
•
Sun ONE/iPlanet: Provide the path to the certificate. Do not include the
file name.
•
Novell: Provide the path to the certificate, including the file name.
•
IBM: Use Java GSKit 7 to import the certificate, and provide the key
database name with full path, starting with the home directory.
•
Open LDAP: Provide the path to the directory that contains the CA
certificate file cacert.pem, the server certificate file
servercrt.pem, and the server certificate key file serverkey.pem.
•
HP-UX: Provide the path to the certificate. Do not include the file name.
7
Click Next. The Platform Connectivity page opens.
8
Enter the details of your LDAP SDK, and click Next.
9
Step through the LDAP Connectivity Wizard to enter the remaining
information, such as the LDAP search filters to use to find users, whether
to import users into MicroStrategy, and so on. For help on specific options
in the wizard, click Help to open the System Administrator Help.
10 When you have entered all the information, click Finish to exit the LDAP
Connectivity Wizard. You are prompted to test the LDAP connection. It is
recommended that you test the connection to catch any errors with the
connection parameters you have provided.
Enabling LDAP authentication for your project source
11 In the Folder List, right-click the project source, and select Modify Project
Source. The Project Source Manager opens.
12 On the Advanced tab, select Use LDAP Authentication.
© 2015, MicroStrategy Inc.
Setting up LDAP authentication in MicroStrategy
137
System Administration Guide
13 Click OK to accept your changes and close the Project Source Manager.
Enabling LDAP authentication for MicroStrategy Web
14 From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Web Administrator. The Web Administrator Page
opens in a web browser.
15 On the left, under Intelligence Server, select Default Properties.
16 In the Login area, for LDAP Authentication, select the Enabled check box.
17 If you want LDAP authentication to be the default authentication mode for
MicroStrategy Web, for LDAP Authentication, select the Default option.
If your environment includes multiple Intelligence Servers connected to
* one MicroStrategy Web server, users are authenticated to all the
Intelligence Servers using their LDAP credentials, and then shown a list
of projects they can access. However, if one or more of the Intelligence
Servers does not use LDAP authentication, the projects for those
servers may not be displayed. To avoid this scenario, in the Project list
drop-down menu, ensure that Show all the projects connected to the
Web Server before the user logs in is selected.
18 Click Save.
Managing LDAP authentication
While working with MicroStrategy and implementing LDAP authentication,
you may want to improve performance or troubleshoot your LDAP
implementation. The sections below cover steps that can help your LDAP
authentication and MicroStrategy systems work as a cohesive unit.
138
•
If your LDAP server information changes, or to edit your LDAP
authentication settings in general, see Modifying your LDAP
authentication settings, page 139.
•
If you want to modify the settings for importing users into MicroStrategy,
for example, if you initially chose not to import users, and now want to
import users and groups, see Importing LDAP users and groups into
MicroStrategy, page 140.
•
If you choose to synchronize users and groups in batches, and want to
select a synchronization schedule, see Selecting schedules for importing
and synchronizing users, page 143.
•
If you are using single sign-on (SSO) authentication systems, such as
Windows NT authentication or trusted authentication, you can link users’
Managing LDAP authentication
© 2015, MicroStrategy Inc.
System Administration Guide
SSO credentials to their LDAP user names, as described in Using LDAP
with single sign-on authentication systems, page 144.
•
Depending on the way your LDAP directory is configured, You can import
additional LDAP attributes for users, for example, a countryCode
attribute, indicating the user’s location. These additional LDAP attributes
can be used to create security filters for users, such as displaying data that
is relevant to the user’s country. For information on creating these security
filters, see Using LDAP attributes in security filters, page 144.
Modifying your LDAP authentication settings
Depending on changes in your organization’s policies, you may need to modify
the LDAP authentication settings in MicroStrategy. To modify your LDAP
authentication settings, you can use the Intelligence Server Configuration
Editor. The steps to access the LDAP settings in the Intelligence Server
Configuration Editor are described below.
To access LDAP authentication settings in the Intelligence Server
Configuration Editor
1
In Developer, log in to a project source as a user with administrative
privileges.
2
From the Administration menu, select Server, and click Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category. The LDAP settings are displayed. You can
modify the following:
4
•
Your LDAP server settings, such as the machine name, port, and so on.
•
Your LDAP SDK information, such as the location of the LDAP SDK
DLL files.
•
The LDAP search filters that Intelligence Server uses to find and
authenticate users.
•
If you are importing and synchronizing users or groups in batches, the
synchronization schedules.
•
If you are importing users and groups, the import settings.
For help on specific options in the LDAP category, click Help to open the
System Administrator Help.
© 2015, MicroStrategy Inc.
Managing LDAP authentication
139
System Administration Guide
Importing LDAP users and groups into MicroStrategy
You can choose to import LDAP users and groups at login, in a batch process,
or a combination of the two, described as follows:
•
Importing users and groups at login: When an LDAP user logs in to
MicroStrategy for the first time, that user is imported into MicroStrategy
and a physical MicroStrategy user is created in the MicroStrategy
metadata. Any groups associated with that user that are not already in
MicroStrategy are also imported and created in the metadata.
•
Importing users and groups in batches: The list of users and groups are
returned from user and group searches on your LDAP directory.
MicroStrategy users and groups are created in the MicroStrategy metadata
for all imported LDAP users and groups.
This section covers the following:
•
For information on setting up user and group import options, see
Importing users and groups into MicroStrategy, page 140.
•
Once you have set up user and group import options, you can import
additional LDAP information, such as users’ email addresses, or specific
LDAP attributes. For steps, see Importing users’ email addresses, page
142.
•
For information on assigning security settings after users are imported, see
User privileges and security settings after import, page 143.
Importing users and groups into MicroStrategy
You can choose to import users and their associated groups when a user logs
in to MicroStrategy for the first time.
Prerequisites
•
•
140
Ensure that you have reviewed the information and made decisions
regarding your organization’s policy on importing and synchronizing user
information, described in the following sections:
▫
Determining whether to import LDAP users into MicroStrategy, page
131
▫
Determining whether to automatically synchronize LDAP user and
group information, page 134
If you want to import users and groups in batches, you must define the
LDAP search filters to return lists of users and groups to import into
MicroStrategy. For information on defining search filters, see Defining
LDAP search filters to verify and import users and groups at login, page
124.
Managing LDAP authentication
© 2015, MicroStrategy Inc.
System Administration Guide
To import users and/or groups into MicroStrategy
1
In Developer, log in to a project source as a user with administrative
privileges.
2
From the Administration menu, select Server, and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category, then expand Import, and then select
Import/Synchronize.
4
If you want to import user and group information when users log in, in the
Import/Synchronize at Login area, do the following:
5
6
•
To import users at login, select Import Users.
•
To allow MicroStrategy’s user information to automatically synchronize
with the LDAP user information, select Synchronize MicroStrategy User
Login/User Name with LDAP.
•
To import groups at login, select the Import Groups.
•
To allow MicroStrategy’s group information to automatically
synchronize with the LDAP group information, select Synchronize
MicroStrategy Group Name with LDAP.
If you want to import user and group information in batches, in the
Import/Synchronize in Batch area, do the following:
•
To import users in batches, select Import Users. You must also enter a
user search filter in the Enter search filter for importing list of users
field to return a list of users to import.
•
To synchronize MicroStrategy’s user information with the LDAP user
information, select Synchronize MicroStrategy User Login/User Name
with LDAP.
•
To import groups in batches, select Import Groups. You must also enter
a group search filter in the Enter search filter for importing list of
groups field to return a list of users to import.
•
To synchronize MicroStrategy’s group information with the LDAP
group information, select Synchronize MicroStrategy Group Name with
LDAP.
To modify the way that LDAP user and group information is imported, for
example, to import group names as the LDAP distinguished name, under
the LDAP category, under Import, click User/Group. For specific
information on the options available, click Help to open the System
Administrator Help.
© 2015, MicroStrategy Inc.
Managing LDAP authentication
141
System Administration Guide
7
To save your changes and close the Intelligence Server Configuration
Editor, click OK.
Once a user or group is created in MicroStrategy, the users are given their own
inboxes and personal folders. Additionally, you can do the following:
•
Import users’ email addresses. For steps, see Importing users’ email
addresses, page 142.
•
Assign privileges and security settings that control what a user can access
in MicroStrategy. For information on assigning security settings after users
are imported, see User privileges and security settings after import, page
143.
•
Import additional LDAP attributes, which can then be used in security
filters for users. For steps, see Using LDAP attributes in security filters,
page 144.
Importing users’ email addresses
Depending on your requirements, you can import additional information, such
as users’ email addresses, from your LDAP directory. For example, If you have
a license for MicroStrategy Distribution Services, then when you import LDAP
users, either in a batch or at login, you can import these email addresses as
contacts associated with those users. For information about Distribution
Services, see Overview of Distribution Services, page 546.
MicroStrategy 9 imports the primary email address for each LDAP user.
To import users’ email addresses from LDAP
142
1
In Developer, log in to a project source as a user with administrative
privileges.
2
From the Administration menu, select Server, and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category, then expand Import, and select Options.
4
Select Import Email Address.
5
Select whether to use the default LDAP email address attribute of mail, or
to use a different attribute. If you want to use a different attribute, specify
it in the text field.
6
From the Device drop-down list, select the email device that the email
addresses are to be associated with.
Managing LDAP authentication
© 2015, MicroStrategy Inc.
System Administration Guide
7
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
User privileges and security settings after import
A user’s LDAP privileges and security settings are not imported along with a
user. Imported users receive the privileges of the MicroStrategy LDAP Users
group. You can add additional privileges to specific users in the LDAP Users
group using the standard MicroStrategy process in the User Editor. You can
also adjust privileges for the LDAP Users group as a whole.
Similarly, a group’s LDAP privileges and security settings are not imported
along with the group. Group privileges can be modified using the
MicroStrategy Group Editor.
The privileges and security settings assigned to LDAP users imported in
MicroStrategy depend on the users’ associated MicroStrategy group privileges
and security permissions. To see the default privileges assigned to a user or
group, in the folder list, expand your project source, expand Administration,
and then expand User Manager. Right-click the group (or select the group and
right-click the user) and select Edit. The Project Access tab displays all
privileges for each project in the project source. For details on editing user
and group privileges, see the MicroStrategy Developer Help.
The process of synchronizing users and groups can modify which groups a user
belongs to, and thus modify the user’s privileges and security settings.
Selecting schedules for importing and synchronizing users
If you choose to synchronize users and groups in batches, you can select a
schedule that dictates when LDAP users and groups are synchronized in
MicroStrategy. For information on creating and using schedules, see Creating
and managing schedules, page 522. To select a synchronization schedule for
LDAP, follow the steps below.
To select a schedule for importing and synchronizing users
1
In Developer, log in to a project source as a user with administrative
privileges.
2
From the Administration menu, select Server, and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category, then click Schedules. The available schedules
are displayed. By default, all the check boxes for all the schedules are
cleared.
© 2015, MicroStrategy Inc.
Managing LDAP authentication
143
System Administration Guide
4
Select the schedules to use as LDAP user and group synchronization
schedules.
5
To synchronize your MicroStrategy users and groups with the latest LDAP
users and groups immediately, select Run schedules on save.
6
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
Using LDAP with single sign-on authentication systems
If you are using single sign-on (SSO) authentication systems, such as Windows
NT authentication or trusted authentication, you can link users’ SSO
credentials to their LDAP user names, and import the LDAP user and group
information into MicroStrategy. For information about configuring a single
sign-on system, see Enabling single sign-on authentication, page 146.
Depending on the SSO authentication system you are using, refer to one of the
following sections for steps:
•
If you are using Windows NT authentication, see Linking a Windows login
to an LDAP user, page 152.
•
If you are using integrated or trusted authentication, see Linking
integrated authentication users to LDAP users, page 156.
Using LDAP attributes in security filters
You may want to integrate LDAP attributes into your MicroStrategy security
model. For example, you want users to only see sales data about their country.
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.
LDAP attributes are imported into MicroStrategy as system prompts. A
system prompt is a special type of prompt that is answered automatically by
Intelligence Server. The LDAP attribute system prompts are answered with the
related LDAP attribute value for the user who executes the object containing
the system prompt. You import LDAP attributes into MicroStrategy from the
Intelligence Server Configuration Editor.
Once you have created system prompts based on your LDAP attributes, you
can use those system prompts in security filters to restrict the data that your
users can see based on their LDAP attributes. For information about using
system prompts in security filters, including instructions, see Using a single
security filter for multiple users: System prompts, page 96. For general
information about security filters, see Restricting access to data: Security
filters, page 86.
144
Managing LDAP authentication
© 2015, MicroStrategy Inc.
System Administration Guide
To import an LDAP attribute into a project
1
In Developer, log into a project source.
2
From the Administration menu, point to Server and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category, then expand the Import category, and then
select Attributes.
4
From the Select LDAP Attributes drop-down list, select the LDAP attribute
to import.
5
From the Data Type drop-down list, select the data type of that attribute.
6
Click Add. A system prompt is created based on that attribute. You can
now use that system prompt in filters and security filters.
7
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
Controlling project access with LDAP attributes
By default, an LDAP user can log in to a project source even if the LDAP
attributes that are used in system prompts are not defined for that user. To
increase the security of the system, you can prevent LDAP users from logging
in to a project source if all LDAP attributes that are used in system prompts
are not defined for that user.
When you select this option, you prevent all LDAP users from logging in to the
project source if they do not have all the required LDAP attributes. This
affects all users using LDAP authentication, and also any users using Windows,
Trusted, or Integrated authentication if those authentication systems have
been configured to use LDAP. For example, if you are using Trusted
authentication with a SiteMinder single sign-on system, and SiteMinder is
configured to use an LDAP directory, this option prevents SiteMinder users
from logging in if they do not have all the required LDAP attributes.
Be aware of the following:
~•
•
This setting prevents users from logging in to all projects in a project
source.
If your system uses multiple LDAP servers, make sure that all LDAP
attributes used by Intelligence Server are defined on all LDAP servers.
If a required LDAP attribute is defined on LDAP server A and not on
LDAP server B, and the User login fails if LDAP attribute value is not
© 2015, MicroStrategy Inc.
Managing LDAP authentication
145
System Administration Guide
read from the LDAP server check box is selected, users from LDAP
server B will not be able to log in to MicroStrategy.
To only allow users with all required LDAP attributes to log in to the
system
1
In Developer, log into a project source.
2
From the Administration menu, point to Server and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category, then expand the Import category, and then
select Attributes.
4
Select the User logon fails if LDAP attribute value is not read from the LDAP
server check box.
5
Click OK to accept your changes and close the Intelligence Server
Configuration Editor. You may need to restart Intelligence Server for this
change to take effect.
Troubleshooting
There may be situations where you can encounter problems or errors while
trying to integrate MicroStrategy with your LDAP directory. For
troubleshooting information and procedures, see Troubleshooting LDAP
authentication, page 829.
Enabling single sign-on authentication
Enabling authentication to several programs using a single login is known as
single sign-on authentication. There are three different types of authentication
that can be used to enable single sign-on in MicroStrategy. These types of
authentication are:
146
•
Windows — Implementing Windows NT authentication, page 147
•
Integrated - Enabling integrated authentication, page 155
•
Third-party authentication - Enabling Single Sign-on to Web, Mobile, and
Office with third-party authentication, page 177
Troubleshooting
© 2015, MicroStrategy Inc.
System Administration Guide
Implementing Windows NT authentication
If you use Windows 2003 as your network operating system and your users
are already defined in a Windows 2003 directory, then you can enable
Windows authentication in MicroStrategy to allow users access without having
to enter their login information.
The Apple Safari web browser does not support Windows authentication
~ with MicroStrategy Web.
Use the procedures in the rest of this section to enable single sign-on with
Windows authentication in MicroStrategy Web. For high-level steps to
configure these settings, see Steps to enable single sign-on to MicroStrategy
Web using Windows authentication, page 148.
To use Windows authentication you must create users in the MicroStrategy
environment and then link them to Windows users. Linking enables
Intelligence Server to map a Windows user to a MicroStrategy user. See
Linking a Windows domain user to a MicroStrategy user, page 151.
You can also create MicroStrategy users from existing Windows by importing
either user definitions or group definitions. For more information on
importing users or groups, see the MicroStrategy Developer Help.
To use Windows authentication with MicroStrategy Web, you must be running
MicroStrategy Web or Web Universal under Microsoft IIS. Non-IIS web
servers do not support Windows authentication. See Enabling integrated
authentication for IIS, page 163.
If the Windows domain account information is linked to a MicroStrategy user
definition, a MicroStrategy Web user can be logged in automatically through
MicroStrategy Web. When a user accesses MicroStrategy Web, IIS detects the
Windows user and sends the login information to Intelligence Server. If the
Windows user is linked to a MicroStrategy user, Intelligence Server starts a
session for that user. For information on setting up MicroStrategy Web to
allow single sign-on using Windows authentication, see Enabling Windows
authentication login for MicroStrategy Web, page 153.
Enabling Windows authentication in MicroStrategy Web to allow
single sign-on
Single sign-on authentication allows users to type their login credentials once,
and have access to multiple software applications securely, because the system
can apply that single authentication request to all the applications that the
user need access to. It is possible to use Windows authentication to enable
single sign-on for MicroStrategy Web.
There are several configurations that you must make to enable Windows
authentication in MicroStrategy Web. To properly configure MicroStrategy
© 2015, MicroStrategy Inc.
Implementing Windows NT authentication
147
System Administration Guide
Web, Microsoft Internet Information Services (IIS), and the link between
Microsoft and MicroStrategy users, follow the procedure Steps to enable
single sign-on to MicroStrategy Web using Windows authentication, page
148.
Steps to use Windows authentication with Microsoft Sharepoint and
MicroStrategy Web are in the MicroStrategy Developer Library (MSDL). The
MicroStrategy SDK and MSDL contain information on customizing
MicroStrategy Web.
Prerequisites
Before continuing with the procedures described in the rest of this section, you
must first set up a Windows domain that contains a domain name for each
user that you want to allow single sign-on access to MicroStrategy Web with
Windows authentication.
In addition, you must be connected to the MicroStrategy Web machine without
a proxy. Windows authentication does not work over a proxy connection. For
more information, including some possible work-arounds, see Microsoft’s IIS
documentation.
Steps to enable single sign-on to MicroStrategy Web using Windows
authentication
148
1
Enable integrated Windows authentication for Microsoft IIS. See Enabling
Windows authentication for Microsoft IIS, page 149.
2
If you are using MicroStrategy Web Universal on a J2EE-based application
server such as Apache Tomcat, enable the MicroStrategy ISAPI filter in IIS,
to support Windows authentication. For steps, see Enabling Windows
authentication for J2EE-based application servers, page 150.
3
Create a link between a Windows domain user and a MicroStrategy Web
user for each person that will be accessing MicroStrategy Web with
Windows authentication. See Linking a Windows domain user to a
MicroStrategy user, page 151.
4
Define a project source to use Windows authentication. See Defining a
project source to use Windows authentication, page 153.
5
Enable Windows authentication in MicroStrategy Web. See Enabling
Windows authentication login for MicroStrategy Web, page 153.
6
Configure each MicroStrategy Web user’s browser for single sign-on. See
Configuring a browser for single sign-on to MicroStrategy Web, page 154.
Implementing Windows NT authentication
© 2015, MicroStrategy Inc.
System Administration Guide
Enabling Windows authentication for Microsoft IIS
Microsoft Internet Information Services is an Internet server that is integral to
Windows authentication. You must configure IIS to enable Windows
authentication in the MicroStrategy virtual directory to support integrated
authentication to MicroStrategy Web.
The steps to perform this configuration are provided in the procedure below,
which may vary depending on your version of IIS. The following links can help
you find information on how to enable integrated authentication for your
version of IIS:
•
IIS 7: See http://technet.microsoft.com/en-us/library/
cc754628(WS.10).aspx for information on enabling Windows authentication
for IIS 7.
If you are using IIS 7 on Windows Server 2008, ensure the following:
*▫
▫
The MicroStrategyWebPool application pool is started, and the
Managed Pipeline is set to Integrated.
ASP.NET Impersonation is enabled. For information on enabling
ASP.NET Impersonation in IIS 7, see
http://technet.microsoft.com/en-us/library/cc730708(WS.10).aspx.
•
IIS 6: See http://technet.microsoft.com/en-us/library/
cc780160(WS.10).aspx for information on enabling Windows authentication
for IIS 6.
•
IIS 5: See http://support.microsoft.com/kb/215383 for information on
enabling Windows authentication for IIS 5.
The third-party products discussed below are manufactured by vendors
~ independent of MicroStrategy, and the information provided is subject to
change. Refer to the appropriate third-party vendor documentation for
updated IIS support information.
To enable Windows authentication in Microsoft IIS
1
On the MicroStrategy Web server machine, access the IIS Internet Service
Manager.
2
Navigate to and right-click the MicroStrategy virtual folder, and select
Properties.
3
Select the Directory Security tab, and then under Anonymous access and
authentication control, click Edit. The Authentication Methods dialog box
opens.
4
Clear the Anonymous access check box.
© 2015, MicroStrategy Inc.
Implementing Windows NT authentication
149
System Administration Guide
5
Select the Integrated Windows authentication check box.
6
Click OK to save your changes and close the Authentication Methods dialog
box.
7
Click OK again to save your changes to the MicroStrategy virtual folder.
8
Restart IIS for the changes to take effect.
Enabling Windows authentication for J2EE-based application servers
If you use a J2EE-compliant application server other than IIS to deploy
MicroStrategy Web Universal, you must configure IIS to share users’ Windows
authentication credentials with your application server. To allow IIS to share
users’ Windows authentication credentials with your applications server, you
must add the MicroStrategy ISAPI filter to IIS, as described in the steps below.
The third-party products discussed below are manufactured by vendors
~ independent of MicroStrategy, and the information provided is subject to
change. Refer to the appropriate third-party vendor documentation for the
latest information.
Prerequisites
•
In your MicroStrategy installation folder, locate the MBWBAUTH.dll file.
By default, the file is located in C:\Program Files (x86)\Common
Files\MicroStrategy.
Depending on the version of IIS you are using, refer to one of the following
procedures to enable the MicroStrategy ISAPI filter:
•
To enable the MicroStrategy ISAPI filter in IIS 6, page 150
•
To enable the MicroStrategy ISAPI filter in IIS 7, page 151
To enable the MicroStrategy ISAPI filter in IIS 6
150
1
In IIS, right-click the default web site, and select Properties. The Default
Web Site Properties dialog box opens.
2
Click the ISAPI Filters tab. A list of ISAPI filters for your IIS installation is
shown.
3
Click Add. An Open File dialog box is displayed.
4
Browse to the location of the MBWBAUTH.dll file. By default, the file is
located in C:\Program Files (x86)\Common
Files\MicroStrategy.
Implementing Windows NT authentication
© 2015, MicroStrategy Inc.
System Administration Guide
5
Select MBWBAUTH.dll and click OK. The MBWBAUTH ISAPI filter is added
to the list of ISAPI filters.
6
Restart your IIS server.
To enable the MicroStrategy ISAPI filter in IIS 7
1
In IIS, select the default web site. The Default Web Site Home page is
shown.
2
In the Default Web Site Home page, double-click ISAPI Filters. A list of
ISAPI filters for your IIS installation is shown.
3
In the Actions pane, click Add. The Add ISAPI Filter dialog box opens.
4
In the Filter name field, type a name for the filter. For example,
MicroStrategy ISAPI Filter.
5
Next to the Executable field, click Browse (...). An Open File dialog box
opens.
6
Browse to the location of the MBWBAUTH.dll file. By default, the file is
located in C:\Program Files (x86)\Common
Files\MicroStrategy.
7
Select MBWBAUTH.dll and click OK. The path of the file is shown in the
Executable field.
8
Click OK. The ISAPI filter is added to IIS.
9
Restart your IIS server.
Linking a Windows domain user to a MicroStrategy user
Once IIS has been configured to allow integrated Windows authentication, a
link must be created between a user’s MicroStrategy user name and the user’s
Windows domain user name. The required steps are detailed below.
To link a Windows domain user to a MicroStrategy user
1
In Developer, log in to a project source using an account with
administrative privileges.
2
From the Folder List, expand a project source, then expand Administration,
and then expand User Manager.
3
Navigate to the MicroStrategy user you want to link a Windows user to.
Right-click the MicroStrategy user and select Edit. The User Editor opens.
© 2015, MicroStrategy Inc.
Implementing Windows NT authentication
151
System Administration Guide
4
Expand Authentication, then select Metadata.
5
Under Windows Authentication, in the Link Windows user area, provide the
Windows user name for the user you want to link the MicroStrategy user
to. There are two ways to do this:
6
•
Click Browse to select the user from the list of Windows users
displayed.
•
Click Search to search for a specific Windows user by providing the
Windows login to search for and, optionally, the Windows domain to
search. Then click OK to run the search.
Click OK to save your changes and close the User Editor.
Linking a Windows login to an LDAP user
When using LDAP with MicroStrategy, you can reduce the number of times a
user needs to enter the same login and password by linking their Windows
system login with their LDAP login used in MicroStrategy.
By creating a link between a Windows system login, an LDAP user, and a
MicroStrategy user, a single login into the machine authenticates the user for
the machine as well as in MicroStrategy.
For example, a user logs in to their Windows machine with a linked LDAP
login and password and is authenticated. The user then opens Developer and
connects to a project source using Windows authentication. Rather than having
to enter their login and password to log in to MicroStrategy, the user’s login
and password authenticated when logging in to their machine is used to
authenticate the user. During this process, the user account and any relevant
user groups are imported and synchronized for the user.
Prerequisites
•
The LDAP Server is configured as the Microsoft Active Directory Server
domain controller, which stores the Windows system login information.
To link a Windows login with LDAP and MicroStrategy
152
1
In Developer, log in to a project source. You must log in as a user with
administrative privileges.
2
From the Administration menu, select Server, and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category, then expand Import, and then select Options.
The Import Options are displayed.
Implementing Windows NT authentication
© 2015, MicroStrategy Inc.
System Administration Guide
4
Select the Synchronize user/group information with LDAP during Windows
authentication and import Windows link during Batch Import check box.
5
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
Defining a project source to use Windows authentication
For MicroStrategy Web users to gain access to a project in a specific project
source using Windows authentication, the project source must first be
configured have Windows authentication enabled. The steps for enabling this
configuration are detailed below.
To define a project source to use Windows authentication
1
In Developer, log in to a project source using an account with
administrative privileges.
2
Right-click the project source and select Modify Project Source. The Project
Source Manager opens.
3
On the Advanced tab, select the Use network login id (Windows
authentication) option.
4
Click OK. The Project Source Manager closes.
Enabling Windows authentication login for MicroStrategy Web
There are two ways to enable access to MicroStrategy Web using Windows
authentication. Access can be enabled for the MicroStrategy Web application
as a whole, or it can be enabled for individual projects at the project level.
For steps to enable Windows authentication for all of MicroStrategy Web, see
To enable Windows authentication login for MicroStrategy Web, page 153.
For steps to enable Windows authentication for a project, see To enable
Windows authentication login for a project, page 154.
To enable Windows authentication login for MicroStrategy Web
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Web Administrator. The Web Administrator Page
opens in a web browser.
2
On the left, under Intelligence Server, select Default Properties.
© 2015, MicroStrategy Inc.
Implementing Windows NT authentication
153
System Administration Guide
3
In the Login area, for Windows Authentication, select the Enabled check
box.
If you want Windows authentication to be the default login mode for
* MicroStrategy Web, for Windows Authentication, select the Default
option.
4
Click Save.
To enable Windows authentication login for a project
1
Log into a MicroStrategy Web project as a user with administrative
privileges.
2
At the upper left of the page, click the MicroStrategy icon, and select
Preferences. The Preferences page opens.
3
On the left, select Project Defaults, then Security.
4
In the Login modes area, for Windows Authentication, select the Enabled
check box.
If you want Windows authentication to be the default login mode for
* this project in MicroStrategy Web, also select the Default option.
5
Next to Apply, choose whether to apply these settings to all projects, or
just to the one you are currently logged into.
6
Click Apply.
Configuring a browser for single sign-on to MicroStrategy Web
If a MicroStrategy Web user plans to use single sign-on to log in to
MicroStrategy Web, each user’s browser must be configured to enable
integrated authentication. The process to enable integrated authentication is
different depending on the browser they use:
154
•
For Internet Explorer, you must enable integrated authentication for the
browser, as well as add the MicroStrategy Web server URL as a trusted
site. Depending on your security policy, integrated authentication may be
enabled by default for Internet Explorer.
•
For Firefox, you must add the MicroStrategy Web server URL as a trusted
site. The URL must be listed in the about:config page, in the settings
network.negotiate-auth.trusted-uris and network.negotiateauth.delegation-uris.
Implementing Windows NT authentication
© 2015, MicroStrategy Inc.
System Administration Guide
Enabling integrated authentication
Integrated authentication enables a Windows user to log in once to their
Windows machine. The user does not need to log in again separately to
Developer or MicroStrategy Web. This type of authentication uses Kerberos to
validate a user’s credentials.
In addition to authenticating users to Developer and MicroStrategy Web,
integrated authentication also passes user credentials down to the database
server. This allows each user’s credentials to be used to return data from the
database.
For single sign-on with integrated authentication to work, users must have
user names and passwords that are printable, US-ASCII characters. This
limitation is expected behavior in Kerberos. This limitation is important to
keep in mind when creating a multilingual environment in MicroStrategy.
Required machine configurations for integrated authentication
To support this type of authentication, you must properly configure
MicroStrategy, as well as some third-party tools and options. The table below
lists the configurations required, and on which machine the configurations
must be performed.
The third-party products discussed in the table and sections below are
~ manufactured by vendors independent of MicroStrategy, and the
information provided is subject to change. Refer to the appropriate thirdparty vendor documentation for details on supporting integrated
authentication.
Machine
Required Configurations
Machine hosting the
domain controller
Configure a Windows domain controller with Microsoft Active Directory:
© 2015, MicroStrategy Inc.
•
To allow users created in a domain to use integrated authentication in
MicroStrategy, you must clear the Account is sensitive and cannot be delegated
authentication option for each user. For information on this configuration, see
Configuring a domain controller and users, page 157.
•
If Intelligence Server is run as an application with a particular user account, you
must create a user in the domain with the Account is trusted for delegation
authentication option selected. This user account can then be used to run
Intelligence Server as an application. For information on this configuration, see
Trusting Intelligence Server for delegation, page 158.
•
If Intelligence Server is run as a service, define the Intelligence Server machine to
be trusted for delegation. You can do this by selecting the Trust computer for
delegation authentication option for the host machine. For information on this
configuration, see Trusting Intelligence Server for delegation, page 158.
•
Define the web server for MicroStrategy Web host machine to be trusted for
delegation. To do this, select the Trust computer for delegation authentication
option for the host machine. For information on this configuration, see Trusting
Enabling integrated authentication
155
System Administration Guide
Machine
Required Configurations
the MicroStrategy Web and Mobile server host for delegation, page 159.
UNIX/Linux machine
hosting Intelligence
Server Universal
If you use Intelligence Server Universal hosted on a UNIX/Linux machine, you must
install and configure Kerberos 5 on your UNIX/Linux machine. For information on this
configuration, see Configuring Intelligence Server Universal on UNIX/Linux for
integrated authentication, page 159.
Machine hosting
Internet Information
Services (IIS) or other
MicroStrategy Web
application server
Enable integrated authentication for IIS, as described in Enabling integrated
authentication for IIS, page 163.
To enable single sign-on authentication to MicroStrategy Web, MicroStrategy Mobile,
or MicroStrategy Web Services from a Microsoft Windows machine, you must modify a
Windows registry setting (allowtgtsessionkey). For information on this
configuration, see Enabling session keys for Kerberos security, page 164.
If you use Intelligence Server or MicroStrategy Web Services hosted on a Windows
machine, you must configure the krb5.ini file. For information on this configuration, see
Configuring the krb5.ini file, page 165
Machine hosting a
J2EE-compliant
application server
If you use a J2EE-compliant application server to deploy MicroStrategy Web Universal,
MicroStrategy Mobile Server, or MicroStrategy Web Services, you must perform
various configurations to enable integrated authentication, as described in Enabling
integrated authentication for J2EE-compliant application servers, page 166.
Note: If you are using integrated authentication for MicroStrategy Mobile, your J2EEcompliant application server must use JDK 1.8 or higher.
MicroStrategy Web
user’s machine
If a MicroStrategy Web user plans to use single sign-on to log in to MicroStrategy Web,
the user must configure their browser to enable integrated authentication. For
instructions, see Configuring a browser for single sign-on to MicroStrategy Web, page
172.
Any machine with the
required software for
the task
In Developer, link a MicroStrategy user to the domain user. For information on this
configuration, see Linking a domain user to a MicroStrategy user, page 173.
In Developer, configure a project source to use integrated authentication. For
information on this configuration, see Using integrated authentication for a project
source, page 173.
In MicroStrategy Web Administrator, configure MicroStrategy Web to include
integrated authentication as an authentication option. For information on this
configuration, see Enabling integrated authentication login mode for MicroStrategy
Web, page 174.
In MicroStrategy Mobile Administrator, create a Mobile configuration to allow your iOS
and Android users to log into MicroStrategy Mobile using integrated authentication. For
steps to create a Mobile configuration, see the Mobile Server Help.
In addition to authenticating users to Developer and MicroStrategy Web, integrated
authentication can also be extended to pass user credentials down to the database
server. To support this optional configuration, see Enabling integrated authentication
to data sources, page 175.
Linking integrated authentication users to LDAP users
When users log in to MicroStrategy using their integrated authentication
credentials, their LDAP group memberships can be imported and
synchronized.
156
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
By default, users’ integrated authentication information is stored in the
userPrincipalName LDAP attribute. If your system stores integrated
authentication information in a different LDAP attribute, you can specify the
attribute when you configure the import.
Prerequisites
•
The LDAP server has been configured, as described in Setting up LDAP
authentication in MicroStrategy, page 136.
•
You have configured the settings for importing users from your LDAP
directory, as described in Importing LDAP users and groups into
MicroStrategy, page 140.
To import LDAP user and group information for integrated
authentication users
1
In Developer, log in to a project source. You must log in as a user with
administrative privileges.
2
From the Administration menu, select Server, and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the LDAP category, then expand Import, and then select Options.
The Import Options are displayed.
4
Select the Synchronize user/group information with LDAP during Windows
authentication and import Windows link during Batch Import check box.
5
Select the Batch import Integrated Authentication/Trusted Authentication
unique ID check box. The Use Default LDAP Attribute option is enabled.
6
By default, users’ integrated authentication IDs are stored in the
userPrincipalName LDAP attribute. If your system stores integrated
authentication information in a different LDAP attribute, click Other, and
type the LDAP attribute that contains users’ IDs.
7
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
Configuring a domain controller and users
To enable users to be authenticated in MicroStrategy using their Windows
login credentials, you must configure a Microsoft Active Directory domain
controller to apply user authentication and delegation policies. High-level
steps to configure Active Directory to work with integrated authentication in
MicroStrategy are provided below. Refer to your Microsoft documentation for
detailed information on configuring Active Directory.
© 2015, MicroStrategy Inc.
Enabling integrated authentication
157
System Administration Guide
For users to be authenticated in MicroStrategy using their Windows login,
their Windows user accounts must be created in an Active Directory domain
and defined to be delegated. This requires that once the account is created, you
must clear the Account is sensitive and cannot be delegated account option for
a user.
Trusting Intelligence Server for delegation
For Intelligence Server to pass login credentials to enable integrated
authentication in MicroStrategy, it must be trusted for delegation.
To trust Intelligence Server for delegation, you must perform the following
tasks:
•
You must create a Service Principal Name (SPN) for Intelligence Server,
and map it to the domain user that Intelligence Server runs as. The SPN
identifies Intelligence Server as a service that uses Kerberos. For
instructions on creating an SPN, refer to the Kerberos documentation.
If you are running Intelligence Server as a service, the SPN should be in the
following format:
MSTRSVRSvc/IS_MachineName:ISport
If you are running Intelligence Server as an application, the SPN should be
in the following format:
MSTRSVRSvc/IS_MachineName:ISport@DOMAIN_REALM
The formats are explained below:
•
MSTRSVRSvc: The Service Class for the Intelligence Server.
This must be entered exactly as above, with matching case.
*
• IS_MachineName: The fully qualified host name for the machine
which is running Intelligence Server.
•
ISPort: The port where Intelligence Server is hosted.
•
DOMAIN_REALM: The domain realm of the Intelligence Server, which
must be entered in uppercase. It is usually of the form EXAMPLE.COM.
The domain realm is required if you are running Intelligence Server
* as an application. If you are running Intelligence Server as a service,
the domain realm is optional.
•
158
In your Active Directory, you must configure the Intelligence Server’s
domain user to be trusted for delegation, and map the user to this SPN.
For example, if the Intelligence Server runs as the user mstriserver, you must enable the Account is trusted for delegation option
for the user, and map the user to the SPN.
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
•
Trust Intelligence Server for delegation. For the user account that
Intelligence Server runs under, enable the Account is trusted for delegation
authentication option.
If you are running Intelligence Server as a service, you must also enable
* the Trust this computer for delegation to any service (Kerberos only)
option for the Intelligence Server machine.
•
Map the Intelligence Server user account to the SPN you created above.
If you are running Intelligence Server Universal on UNIX or Linux, you must
perform additional steps on the Intelligence Server machine, as described in
Configuring Intelligence Server Universal on UNIX/Linux for integrated
authentication, page 159.
Trusting the MicroStrategy Web and Mobile server host for delegation
The web server hosts for MicroStrategy Web and MicroStrategy Mobile must
be trusted for delegation so that it can pass login credentials to enable
integrated authentication in MicroStrategy. You can configure this delegation
for the MicroStrategy Web and Mobile server machines in your domain
controller. You must select the Trust this computer for delegation to any
service (Kerberos only) option for the MicroStrategy Web and MicroStrategy
Mobile server machines.
Depending on your network, this setting may require a few minutes to take
* effect.
Configuring Intelligence Server Universal on UNIX/Linux for integrated
authentication
If you use Intelligence Server Universal hosted on a UNIX or Linux machine,
you must install and configure Kerberos 5 on your UNIX/Linux machine.
Configuring Kerberos on your UNIX/Linux machine hosting Intelligence Server
Universal enables secure communications to your Windows domain controller.
The configurations listed below are required to configure Intelligence Server
Universal with your Windows domain controller and Kerberos security:
•
Install Kerberos 5, page 160
•
Ensure that the environment variables are set, page 160
•
Configure the krb5.keytab file for the Intelligence Server, page 160
•
Configure the krb5.conf file for the Intelligence Server, page 162
© 2015, MicroStrategy Inc.
Enabling integrated authentication
159
System Administration Guide
~
Kerberos only supports US-ASCII characters. Do not use any special
characters when installing or configuring Kerberos.
Prerequisites
•
Ensure that you have created a Service Principal Name (SPN) for your
Intelligence Server, and configured your domain controller to trust
Intelligence Server, as described in Trusting Intelligence Server for
delegation, page 158.
•
Ensure that the system clock of the Intelligence Server machine is in sync
with the clock on your domain controller.
Install Kerberos 5
You must have Kerberos 5 installed on your UNIX or Linux machine that hosts
Intelligence Server Universal. Your UNIX or Linux operating system may come
with Kerberos 5 installed. If Kerberos 5 is not installed on your UNIX or Linux
machine, refer to the Kerberos documentation for steps to install it.
Ensure that the environment variables are set
Once you have installed Kerberos 5, you must ensure that the following
environment variables have been created:
Variable
Description
Default
Required/Optional
${KRB5_HOME}
Location of all Kerberos configuration
files
/etc/krb5
Optional
${KRB5_
CONFIG}
Location of the default Kerberos
configuration file
/etc/krb5/krb5.conf
Required
${KRB5CCNAME}
Location of the Kerberos credential
cache
/etc/krb5/krb5_
ccache
Optional
${KRB5_
KTNAME}
Location of the Kerberos keytab file
/etc/krb5/krb5.keytab
Required
Configure the krb5.keytab file for the Intelligence Server
You must create and configure the krb5.keytab file. The steps to configure
this file on your UNIX or Linux machine are provided in the procedure below.
Prerequisites
The procedure below requires a few variables to be entered for various
commands. This includes information you can gather before you begin the
160
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
procedure. The required variables in the following procedure are described
below:
•
ISMachineName: The name of the Intelligence Server machine.
•
ISPort: The port number for Intelligence Server.
•
KeyVersionNumber: The key version number, retrieved as part of this
procedure.
•
EncryptionType: The encryption type used.
It is recommended that you use rc4-hmac as the encryption type.
* Other encryption types may cause compatibility issues with the
Windows Active Directory.
•
DOMAIN_REALM: The domain realm for your Intelligence Server, which
must be entered in uppercase.
To create a krb5.keytab file
1
Log in to your UNIX or Linux machine.
2
Retrieve the key version number for your Intelligence Server service
principal name, using the following command:
kvno MSTRSVRSvc/ISMachineName:ISPort@DOMAIN_REALM
The key version number is displayed on the command line.
3
In the command line, type the following commands:
4
ktutil
addent -password -p MSTRSVRSvc/
ISMachineName:ISPort@DOMAIN_REALM -k KeyVersionNumber e EncryptionType
wkt /etc/krb5/krb5.keytab
exit
To verify the keytab file, type the following command:
kinit -k -t /etc/krb5/krb5.keytab
MSTRSVRSvc/ISMachineName:ISPort@DOMAIN_REALM
The command should run without prompting you for a username and
password.
© 2015, MicroStrategy Inc.
Enabling integrated authentication
161
System Administration Guide
Configure the krb5.conf file for the Intelligence Server
You must create and configure a file named krb5.conf. This file is stored in
the /etc/krb5/ directory by default.
If you create a krb5.conf file in a directory other than the default, you
~ must update the KRB5_CONFIG environment variable with the new
location. Refer to your Kerberos documentation for steps to modify the
KRB5_CONFIG environment variable.
The contents of the krb5.conf should be as shown below:
[libdefaults]
default_realm = DOMAIN_REALM
default_keytab_name = FILE:/etc/krb5/krb5.keytab
forwardable = true
no_addresses = true
[realms]
DOMAIN_REALM = {
kdc = DC_Address:88
admin_server = DC_Admin_Address:749
}
[domain_realm]
.domain.com = DOMAIN_REALM
domain.com = DOMAIN_REALM
.subdomain.domain.com = DOMAIN_REALM
subdomain.domain.com = DOMAIN_REALM
The variables in the syntax above are described below:
162
•
DOMAIN_REALM: The domain realm used for authentication purposes. A
domain realm is commonly of the form EXAMPLE.COM, and must be
entered in uppercase.
•
domain.com and subdomain.domain.com: Use this for all domains
and subdomains whose users must be authenticated using the default
Kerberos realm.
•
DC_Address: The host name or IP address of the Windows machine that
hosts your Active Directory domain controller. This can be the same
address as DC_Admin_Address.
•
DC_Admin_Address: The host name or IP address of the Windows
machine that hosts your Active Directory domain controller administration
server. This can be the same address as DC_Address.
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
Enabling integrated authentication for IIS
Integrated authentication in MicroStrategy requires communication between
your Kerberos security system, IIS, and your database.
If you use a J2EE-compliant application server other than IIS to deploy
MicroStrategy Web Universal, MicroStrategy Mobile Server, or MicroStrategy
Web Services, see Enabling integrated authentication for J2EE-compliant
application servers, page 166.
You must configure IIS to enable integrated authentication to:
•
•
The MicroStrategy virtual directory to support integrated authentication to
MicroStrategy Web, or MicroStrategy Web Services to support
MicroStrategy Office. The steps to perform this configuration are provided
in the procedure below, which may vary depending on your version of IIS.
The following URLs may provide additional information to configure IIS,
depending on the version you are using:
▫
IIS 7: http://technet.microsoft.com/en-us/library/
cc754628(WS.10).aspx
▫
IIS 6: http://technet.microsoft.com/en-us/library/
cc780160(WS.10).aspx
▫
IIS 5: http://support.microsoft.com/kb/215383
Optionally, the data warehouse. For instructions to enable integrated
authentication for the data warehouse, refer to Enabling integrated
authentication to data sources, page 175.
If you are using Microsoft Analysis Services, to support report
* subscriptions, you must use connection mapping to pass users’
credentials to Analysis Services. For steps to enable connection
mapping, see Connection maps: Standard authentication, connection
maps, and partitioned fact tables, page 199.
To configure IIS to enable integrated authentication to the
MicroStrategy virtual directory
1
On the MicroStrategy Web server machine, access the IIS Internet Service
Manager.
2
Browse to and right-click the MicroStrategy virtual folder and select
Properties.
3
Select the Directory Security tab, and then under Anonymous access and
authentication control, click Edit. The Authentication Methods dialog box
opens.
© 2015, MicroStrategy Inc.
Enabling integrated authentication
163
System Administration Guide
4
Clear the Enable anonymous access check box.
5
Select the Integrated Windows authentication check box.
6
Click OK to save your changes and close the Authentication Methods dialog
box.
7
Click OK again to save your changes to the MicroStrategy virtual folder.
8
If you want to enable integrated authentication for MicroStrategy Mobile,
repeat the above procedure for the MicroStrategyMobile virtual folder.
9
If you want to enable integrated authentication for MicroStrategy Web
Services, repeat the above procedure for the MicroStrategyWS virtual
folder.
10 Restart IIS for the changes to take effect.
Creating a Service Principal Name for IIS
It is recommended that you create a Service Principal Name (SPN) for IIS, and
map it to the domain user that the application server runs as. The SPN
identifies your application server as a service that uses Kerberos. For
instructions on creating an SPN, refer to the Kerberos documentation.
The SPN should be in the following format:
HTTP/ASMachineName
The format is described below:
•
HTTP: This is the service class for the application server.
•
ASMachineName: This is the fully qualified host name of the server where
the application server is running. It is of the form machinename.example.com.
In your Active Directory, configure the application server’s domain user to be
trusted for delegation, and map the user to this SPN. For example, if IIS runs
as the user iis, you must enable the Account is trusted for delegation option
for the user, and map the user to the SPN. You must also enable the Trust this
computer for delegation to any service (Kerberos only) option for the machine
where IIS is hosted.
Enabling session keys for Kerberos security
To enable single sign-on authentication to MicroStrategy Web from a
Microsoft Windows machine, you must modify a Windows registry setting on
the machine hosting IIS.
Modification of the allowtgtsessionkey registry setting is required by
Microsoft to work with Kerberos security. For information on the implications
164
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
of modifying the registry setting and steps to modify the registry setting, see
the following Microsoft documentation:
The documentation below is produced by a third-party vendor and thus is
~ subject to change. MicroStrategy makes no guarantee on the availability or
accuracy of third-party documentation.
•
For Microsoft Windows 2003 http://support.microsoft.com/kb/837361
Configuring the krb5.ini file
If you use Intelligence Server Universal hosted on a Windows machine, you
must configure the krb5.ini file. This file is included with an installation of
MicroStrategy Web, and can be found in the following directory:
C:\Program Files (x86)\Common Files\MicroStrategy\
The path listed above assumes you have installed MicroStrategy in the
C:\Program Files (x86) directory.
Kerberos only supports US-ASCII characters. Do not use any special
~ characters when installing or configuring Kerberos.
Once you locate the krb5.ini file, open it in a text editor. The content within
the file is shown below:
[libdefaults]
default_realm = <DOMAIN NAME>
default_keytab_name = <path to keytab file>
forwardable = true
no_addresses = true
[realms]
<REALM_NAME> = {
kdc = <IP address of KDC>:88
admin_server = <IP address of KDC admin>:749
}
[domain_realm]
.domain.com = <DOMAIN NAME>
domain.com = <DOMAIN NAME>
.subdomain.domain.com = <DOMAIN NAME>
subdomain.domain.com = <DOMAIN NAME>
You must configure the krb5.ini file to support your environment by
replacing the entries enclosed in <>, which are described below:
•
<DOMAIN NAME> and <REALM_NAME>: The domain realm used for
authentication purposes. A domain realm is commonly of the form
EXAMPLE.COM, and must be entered in uppercase.
© 2015, MicroStrategy Inc.
Enabling integrated authentication
165
System Administration Guide
•
<IP address of KDC>: The IP address or host name of the Windows
machine that hosts your Active Directory domain controller. This can be
the same address as <IP address of KDC admin>.
•
<IP address of KDC admin>: The host name or IP address of the
Windows machine that hosts your Active Directory domain controller
administration server. This can be the same address as <IP address of
KDC>.
•
domain.com and subdomain.domain.com: Use this for all domains
and subdomains whose users must be authenticated using the default
Kerberos realm.
Enabling integrated authentication for J2EE-compliant application
servers
If you use a J2EE-compliant application server to deploy MicroStrategy Web
Universal, MicroStrategy Mobile Server, or to deploy MicroStrategy Web
Services to support MicroStrategy Office, you can support integrated
authentication.
To enable integrated authentication, you must set up a Service Principal Name
(SPN) for the application server, and configure the Kerberos keytab and
configuration files. The following is an overview of the tasks you need to
perform:
•
Create a Service Principal Name for your application server, page 166
•
Configure the krb5.keytab file for the application server, page 167
•
Enabling integrated authentication for J2EE-compliant application
servers, page 166
•
Configure the jaas.conf file for the application server, page 170
•
Configure the JVM startup parameters, page 171
•
Enable the SPNEGO mechanism, page 171
Create a Service Principal Name for your application server
You must create a Service Principal Name (SPN) for your J2EE application
server, and map it to the domain user that the application server runs as. The
SPN identifies your application server as a service that uses Kerberos. For
instructions on creating an SPN, refer to the Kerberos documentation.
The SPN should be in the following format:
HTTP/ASMachineName
The format is described below:
•
166
HTTP: This is the service class for the application server.
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
•
ASMachineName: This is the fully qualified host name of the server where
the application server is running. It is of the form machinename.example.com.
In your Active Directory, you must configure the application server’s domain
user to be trusted for delegation, and map the user to this SPN. For example,
if your application server runs as the user j2ee-http, you must enable the
Account is trusted for delegation option for the user, and map the user to the
SPN. You must also enable the Trust this computer for delegation to any
service (Kerberos only) option for the machine where your application server is
hosted.
Configure the krb5.keytab file for the application server
You must create and configure a krb5.keytab file for the application server.
In UNIX, you must use the kutil utility to create this file. In Windows, you
must use the ktpass utility to create the keytab file.
The steps to configure this file on your UNIX or Linux machine are provided in
To create a krb5.keytab file in UNIX or Linux, page 168.
The steps to configure this file on a Windows machine are provided in To
create a krb5.keytab file in Windows, page 168.
Prerequisites
The procedure below requires a few variables to be entered for various
commands. This includes information you can gather before you begin the
procedure. The required variables in the following procedure are described
below:
•
ASMachineName: The name of the machine that the application server is
installed on.
•
KeyVersionNumber: The key version number, retrieved as part of this
procedure.
•
DOMAIN_REALM: The domain realm for the application server. It is of the
form EXAMPLE.COM, and must be entered in uppercase.
•
EncryptionType: The encryption type used.
It is recommended that you use rc4-hmac as the encryption type.
* Other encryption types may cause compatibility issues with the
Windows Active Directory.
•
Keytab_Path: For J2EE application servers under Windows, this
specifies the location of the krb5.keytab file. It is of the form
C:\temp\example.keytab.
© 2015, MicroStrategy Inc.
Enabling integrated authentication
167
System Administration Guide
•
ASUser and ASUserPassword: The user account under which the
application server runs, and the password for the account.
To create a krb5.keytab file in UNIX or Linux
*
If your application server and Intelligence Server are hosted on the same
machine, it is required that you use separate keytab and configuration files
for each. For example, if you are using krb5.keytab and krb5.conf for
the Intelligence Server, use krb5-http.keytab and krb5-http.conf
for the application server.
1
Log in to your UNIX or Linux machine.
2
Retrieve the key version number for your application server service
principal name, using the command shown below:
kvno HTTP/ASMachineName@DOMAIN_REALM
The variables are described in the prerequisites above.
The key version number is displayed on the command line.
3
In the command line, type the following commands:
If your application server is installed on the same machine as the
* Intelligence Server, replace krb5.keytab below with a different file
name than the one used for the Intelligence Server, such as krb5http.keytab.
ktutil
addent -password -p HTTP/ASMachineName@DOMAIN_NAME -k
KeyVersionNumber -e EncryptionType
wkt /etc/krb5/krb5.keytab
exit
4
To verify the keytab file, type the following command:
kinit -k -t /etc/krb5/krb5.keytab HTTP/ASMachineName
The command should run without prompting you for a password.
To create a krb5.keytab file in Windows
1
168
Log in to your Windows machine.
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
2
From a command prompt, type the following command:
ktpass -out Keytab_Path
-princ HTTP/ASMachine@DOMAIN_REALM
-mapUser ASUser
-mapOp set
-pass ASUserPassword
-crypto Encryption_Type
-pType KRB5_NT_PRINCIPAL
Configure the krb5.conf file for the application server
You must create and configure a file named krb5.conf.
For UNIX/Linux only: If your application server and Intelligence Server
* are hosted on the same machine, it is required that you use a separate
configuration file. For example, if you created krb5.conf for the
Intelligence Server, use krb5-http.conf for the application server.
If you have created a different keytab file in Configure the krb5.keytab file for
the application server, page 167, replace krb5.keytab below with your own
keytab file.
The contents of the krb5.conf should be as shown below:
[libdefaults]
default_realm = DOMAIN_REALM
default_keytab_name = Keytab_Path
forwardable = true
no_addresses = true
[realms]
DOMAIN_REALM = {
kdc = DC_Address:88
admin_server = DC_Admin_Address:749
}
[domain_realm]
.domain.com = DOMAIN_REALM
domain.com = DOMAIN_REALM
.subdomain.domain.com = DOMAIN_REALM
subdomain.domain.com = DOMAIN_REALM
The variables in the syntax above are described below:
•
DOMAIN_REALM: The domain realm used for authentication purposes. A
domain realm is commonly of the form EXAMPLE.COM, and must be
entered in uppercase
© 2015, MicroStrategy Inc.
Enabling integrated authentication
169
System Administration Guide
•
Keytab_Path: The location of your krb5.keytab file. In UNIX or
Linux, it is of the form /etc/krb5/krb5.keytab. In Windows, it is of
the form C:\temp\krb5.keytab.
•
domain.com and subdomain.domain.com: Use this for all domains
and subdomains whose users must be authenticated using the default
Kerberos realm.
•
DC_Address: The host name or IP address of the Windows machine that
hosts your Active Directory domain controller. This can be the same
address as DC_Admin_Address.
•
DC_Admin_Address: The host name or IP address of the Windows
machine that hosts your Active Directory domain controller administration
server. This can be the same address as DC_Address.
Configure the jaas.conf file for the application server
You must configure the Java Authentication and Authorization Service (JAAS)
configuration file for your application server.
Depending on the version of the Java Development Kit (JDK) used by your
application server, the format of the jaas.conf file varies slightly. Refer to
your JDK documentation for the appropriate format. Sample jaas.conf files for
the Sun and IBM JDKs follow. The following variables are used:
•
ASMachineName: The name of the machine that the application server is
installed on.
•
DOMAIN_REALM: The domain realm used for authentication purposes. It is
of the form EXAMPLE.COM, and must be entered in uppercase.
Note that the parameters are entered in the .accept section of the
* jaas.conf file.
Sample jaas.conf for Sun JDK 1.5
com.sun.security.jgss.accept { com.sun.security.auth.module.Krb5LoginModule required
principal="HTTP/ASMachineName@DOMAIN_REALM"
useKeyTab=true
doNotPrompt=true
storeKey=true
debug=true;
};
Sample jaas.conf for Sun JDK 1.6
com.sun.security.jgss.krb5.accept { com.sun.security.auth.module.Krb5LoginModule required
principal="HTTP/ASMachineName@DOMAIN_REALM"
useKeyTab=true
170
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
doNotPrompt=true
storeKey=true
debug=true;
};
Sample jaas.conf for IBM JDK
com.ibm.security.jgss.accept {
com.ibm.security.auth.module.Krb5LoginModule required
useDefaultKeytab=true
principal="HTTP/ASMachineName@DOMAIN_REALM"
credsType=acceptor
forwardable=true
debug=true
storeKey=true;
};
Save the jaas.conf file to the same location as your krb5.conf file.
Configure the JVM startup parameters
For your J2EE-compliant application server, you must set the appropriate
JVM startup parameters. The variables used are described below:
•
JAAS_Path: The path to the jaas.conf file. In UNIX/Linux, it is of the
form /etc/krb5/jaas.conf. In Windows, it is of the form
C:\temp\jaas.conf.
•
KRB5_Path: The path to the krb5.conf file. In UNIX/Linux, it is of the form
/etc/krb5/krb5.conf. In Windows, it is of the form
C:\temp\krb5.conf.
You must modify the JVM startup parameters listed below:
•
-Djava.security.auth.login.config=JAAS_Path
•
-Djava.security.krb5.conf=KRB5_Path
•
-Djavax.security.auth.useSubjectCredsOnly=false
Enable the SPNEGO mechanism
As part of a MicroStrategy Web Universal or Mobile Server JSP deployment,
you must modify the web.xml file for MicroStrategy Web or Mobile, to
enable the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO).
This is accomplished by removing the comments around the following
information in the web.xml file:
For MicroStrategy Web:
<filter>
© 2015, MicroStrategy Inc.
Enabling integrated authentication
171
System Administration Guide
<display-name>SpnegoFilter</display-name>
<filter-name>SpnegoFilter</filter-name>
<filterclass>com.microstrategy.web.filter.SpnegoFilter</fil
ter-class>
</filter>
<filter-mapping>
<filter-name>SpnegoFilter</filter-name>
<servlet-name>mstrWeb</servlet-name>
</filter-mapping>
For MicroStrategy Mobile Server:
<filter>
<display-name>SpnegoFilter</display-name>
<filter-name>SpnegoFilter</filter-name>
<filterclass>com.microstrategy.mobile.filter.SpnegoFilter</
filter-class>
</filter>
<filter-mapping>
<filter-name>SpnegoFilter</filter-name>
<servlet-name>mstrMobileAdmin</servlet-name>
</filter-mapping>
Restart your application server for all the above settings to take effect.
Configuring a browser for single sign-on to MicroStrategy Web
If a MicroStrategy Web user plans to use single sign-on to log in to
MicroStrategy Web, the user must configure their browser to enable
integrated authentication. The process to enable integrated authentication is
different depending on the browser you use:
•
For Internet Explorer, you must enable integrated authentication for the
browser, as well as add the MicroStrategy Web server URL as a trusted
site.
Depending on your security policy, integrated authentication may be
* enabled by default for Internet Explorer.
•
172
For Firefox, you must add the MicroStrategy Web server URL as a trusted
site. The URL must be listed in the about:config page, in the settings
network.negotiate-auth.trusted-uris and
network.negotiate-auth.delegation-uris.
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
Linking a domain user to a MicroStrategy user
To apply security and privileges to a user in MicroStrategy, you must link the
domain user to a MicroStrategy user. This also enables the domain user to be
logged into MicroStrategy projects they have access to without having to type
their login credentials again.
Prerequisites
•
A domain user included in a domain to support integrated authentication.
For information on configuring a user in a domain, see Configuring a
domain controller and users, page 157.
•
A MicroStrategy user (object) to link to a domain user.
•
A MicroStrategy user with administrative privileges to make the required
user modifications.
To link a domain user to a MicroStrategy user
1
In Developer, log in to a project source using an account with
administrative privileges.
2
From the Folder List, expand a project source, expand Administration, and
then expand User Manager.
3
Browse to the MicroStrategy user you want to link a Windows user to.
Right-click the MicroStrategy user and select Edit. The User Editor opens.
4
Expand Authentication, then select Metadata.
5
In the Trusted Authenticated Request area, type the domain user in the
User ID field. Valid syntax is shown below:
DomainUserName@DOMAIN_REALM
For example, to link User1 who is in the example.com domain realm, you
must type [email protected]. The domain realm name must be in
uppercase.
6
Click OK to save your changes and close the User Editor.
Using integrated authentication for a project source
To enable users to log in to a project source in MicroStrategy with integrated
authentication, you must define the project source to use integrated
authentication. The procedure below describes the steps to define a project
source to use integrated authentication.
Prerequisites
© 2015, MicroStrategy Inc.
Enabling integrated authentication
173
System Administration Guide
•
A MicroStrategy user with administrative privileges to make the required
user modifications.
To use integrated authentication for a project source
1
In Developer, log in to a project source using an account with
administrative privileges.
2
Right-click a project source, and then click Modify Project Source. The
Project Source Manager opens.
3
On the Connection tab, under Server Name, type the server name exactly as
it appears is the Service Principal Name created in Trusting Intelligence
Server for delegation, page 158. For example, if the SPN is
MSTRSVRSvc\server.example.com:1234, the Server Name for the
project source should be server.example.com.
4
On the Advanced tab, select the Use Integrated Authentication option.
Enabling integrated authentication login mode for MicroStrategy Web
For MicroStrategy Web users to be able to use their Windows credentials to
log in to MicroStrategy Web, you must enable integrated authentication as an
available login mode. The procedure below describes the required steps for
this configuration.
To enable integrated authentication login mode for MicroStrategy
Web
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Web Administrator. The Web Administrator page
opens in a browser.
2
On the left, select Default Properties.
3
In the Login area, for Integrated Authentication, select the Enabled check
box.
If you want integrated authentication to be the default login mode for
* MicroStrategy Web, for Integrated Authentication, select the Default
option.
4
174
Click Save to save your changes.
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
Enabling integrated authentication for MicroStrategy Mobile
To allow your MicroStrategy Mobile users to use their Windows credentials to
log into MicroStrategy, you create a Mobile configuration, and select
Integrated Authentication as the authentication method. For steps to create a
Mobile configuration for your organization, see the Mobile Server Help.
Enabling integrated authentication to data sources
Through the use of integrated authentication, you can allow each user’s
credentials to be passed to your database server. You must enable this option
at the project level.
If your reports or documents use subscriptions, using integrated
~ authentication for your data sources prevents the subscriptions from
running.
The steps to configure this optional support are described below.
Prerequisites
•
Your database server must be configured to allow integrated authentication
for all MicroStrategy users that use it as a data warehouse. Refer to your
third-party database server documentation for instructions on enabling this
support.
To enable integrated authentication to data sources
1
In Developer, log in to the project whose data sources you want to
configure.
2
In the Administration menu, select Projects, then choose Project
Configuration. The Project Configuration dialog box opens.
3
Expand the Database instances category.
4
Expand Authentication, and select Warehouse.
5
Enable the For selected database instances radio button.
6
From the Metadata authentication type drop-down list, choose Kerberos.
7
In the Database Instance pane, enable the check boxes for all the database
instances for which you want to use integrated authentication, as shown
below.
© 2015, MicroStrategy Inc.
Enabling integrated authentication
175
System Administration Guide
*
8
If you are connecting to a Microsoft SQL Server, Teradata, or TM1 data
source, use this setting only if your Intelligence Server is running on
Windows.
Click OK. The Project Configuration dialog box closes.
Enabling integrated authentication for the MicroStrategy Hadoop
Gateway
The MicroStrategy Hadoop Gateway is a data processing engine that you
install in your Hadoop® environment. The Hadoop Gateway lets you analyze
unstructured data in Hadoop, and provides high-speed parallel data transfer
between the Hadoop Distributed File System (HDFS) and your MicroStrategy
Intelligence Server.
Before enabling integrated authentication for your Hadoop cluster, ensure that
you have met the following prerequisites. To enable integrated authentication
for your Hadoop cluster, refer to your third-party documentation.
Prerequisites
176
•
You have installed the Hadoop Gateway in your Hadoop cluster. For steps
to install the Hadoop Gateway, see the Installation and Configuration
Guide.
•
You have enabled integrated authentication for Intelligence Server and
Web, as described in Enabling integrated authentication for IIS, page 163
or Enabling integrated authentication for J2EE-compliant application
servers, page 166, depending on your platform.
•
In your Hadoop cluster, you have set up a user account that has
permissions to create new users.
Enabling integrated authentication
© 2015, MicroStrategy Inc.
System Administration Guide
•
Your Hadoop cluster can access your Kerberos domain controller.
For specific steps to enable integrated authentication for your Hadoop cluster,
refer to the documentation for your Hadoop cluster distribution.
Enabling Single Sign-on to Web, Mobile, and Office
with third-party authentication
You can enable Single Sign-on (SSO) authentication for the following
MicroStrategy applications using a third-party tool such as IBM Tivoli Access
Manager, CA SiteMinder, Oracle Access Manager, or PingFederate®:
•
MicroStrategy Web
•
MicroStrategy Mobile
•
MicroStrategy Web Services, to support MicroStrategy Office (IBM Tivoli
Access Manager and CA SiteMinder only)
Once a user is authenticated in the third-party system, the user’s permissions
are retrieved from a user directory, such as LDAP, and access is granted to the
MicroStrategy application.
In this security model, there are several layers. For example, when a user logs
in to Tivoli, Tivoli determines whether or not the user’s credentials are valid.
If the user logs in with valid credentials to Tivoli, the user directory (such as
LDAP) determines whether that valid user can connect to MicroStrategy. The
user’s MicroStrategy privileges are stored within the MicroStrategy Access
Control List (ACL). What a user can and cannot do within the MicroStrategy
application is stored on Intelligence Server in the metadata within these ACLs.
For more information about privileges and ACLs in MicroStrategy, see
Chapter 2, Setting Up User Security.
For MicroStrategy to be able to get a user’s privileges from the metadata,
Intelligence Server must be configured to be a trusted machine in
MicroStrategy Web, Mobile, and Office. This allows the information to be
passed between the two machines.
The following diagram illustrates the architecture of a security system that
uses third-party authentication.
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
177
System Administration Guide
MicroStrategy enables this type of access by passing tokens between
MicroStrategy, the user directory, and the third-party authentication provider.
Properly configuring these levels of communication is critical to implementing
SSO authentication.
The distinguished name of the user passed from the third-party provider is
* URL-decoded by default within MicroStrategy Web, Mobile, or Web
Services before it is passed to the Intelligence Server.
Single sign-on authentication performs the step of allowing a user access to
MicroStrategy products. You also must configure MicroStrategy users to define
privileges and permissions that control what a user can perform and access
within the products.
Setting up third-party SSO authentication in MicroStrategy products
The following high-level steps are required to set up third-party SSO
authentication in MicroStrategy Web, Mobile, or Web Services, and each is
detailed below:
178
•
Creating users and links in third-party authentication systems, page 179
•
Enabling single sign-on authentication to MicroStrategy Web, Mobile or
Office, page 179
•
Importing and linking third-party authentication users in MicroStrategy,
page 189
•
To log in to MicroStrategy Web using Tivoli single sign-on, page 194
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
Creating users and links in third-party authentication systems
Before MicroStrategy can be configured to accept Tivoli, SiteMinder,
PingFederate or Oracle Access Manager authentication, certain preliminary
settings must be established. This ensures that a link exists between the
authentication provider and MicroStrategy products, and that the link is
functioning as required.
You must complete all of the following steps to ensure proper configuration of
your authentication provider and MicroStrategy products.
Creating a user in your third-party authentication system
You can enable SSO authentication in MicroStrategy by associating a
MicroStrategy user to a user in Tivoli, SiteMinder, PingFederate or Oracle
Access Manager. To test this association, you must create a user in your
authentication system to confirm that access has been properly configured in
MicroStrategy products.
For steps to create a new user, refer to your authentication provider’s
documentation.
Creating a link to MicroStrategy applications in your third-party authentication
system
You link Tivoli to MicroStrategy applications using junctions, SiteMinder using
Web Agents, and Oracle Access Manager using Webgates. These links redirect
users from the respective provider to MicroStrategy, and are required to
enable SSO authentication. You must create one link each, as applicable, for
MicroStrategy Web, MicroStrategy Mobile, and MicroStrategy Web Services to
support MicroStrategy Office.
Oracle Access Manager authentication is only available for MicroStrategy
* Web.
For steps to create a junction (in Tivoli), a Web Agent (in SiteMinder), or a
Webgate (Oracle Access Manager), refer to the product’s documentation.
Enabling single sign-on authentication to MicroStrategy Web, Mobile
or Office
Once the initial third-party authentication setup is complete, you must enable
trusted authentication in MicroStrategy Web, Mobile or Office, and establish
trust between the MicroStrategy product and Intelligence Server. This allows
the authentication token to be passed from one system to the other.
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
179
System Administration Guide
*
Note that for MicroStrategy Web Services to support MicroStrategy Office,
you must establish trust between Office and the Intelligence server, and
enable trusted authentication in the configuration files for Web Services.
This section explains the following required steps to enable SSO authentication
in MicroStrategy Web, Mobile, or Web Services:
•
Enabling trusted authentication in MicroStrategy Web, page 180
•
Enabling trusted authentication in MicroStrategy Mobile, page 181
•
Establishing trust between MicroStrategy Web or Mobile and Intelligence
Server, page 182
•
Establishing trust between MicroStrategy Web Services and Intelligence
Server, to support MicroStrategy Office, page 186
•
Enabling trusted authentication in MicroStrategy Web Services to support
MicroStrategy Office, page 187
If you use Internet Information Services (IIS) as your web server for
MicroStrategy Web or Web Services, you must enable anonymous
authentication to the MicroStrategy virtual directories to support SSO
authentication to MicroStrategy Web, Mobile, or Office. This is discussed in
Enabling anonymous authentication for Internet Information Services, page
188.
Enabling trusted authentication in MicroStrategy Web
To enable users to log in to MicroStrategy Web using SSO authentication, you
must enable trusted authentication as an available authentication mode in
MicroStrategy Web.
To enable trusted authentication in MicroStrategy Web
180
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Web Administrator. The MicroStrategy Web
Administrator page opens.
2
On the left side of the page, click Default Properties. The Default
Properties page opens.
3
Scroll down to the Login area and, under Login mode, select the Enabled
check box next to Trusted Authentication Request. Also select the Default
option next to Trusted Authentication Request, as shown below:
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
4
From the Trusted Authentication Providers drop-down list, select IBM Tivoli
Access Manager, CA SiteMinder, PingFederate, or Oracle Access Manager.
To use a custom authentication provider, select Custom SSO. For
information about adding custom authentication providers, refer to your
MicroStrategy SDK documentation.
5
At the bottom of the page, click Save.
Using certificate authentication with SiteMinder
CA SiteMinder can be configured to use either certificate authentication or
basic authentication. MicroStrategy Web’s siteminder_
security.properties file indicates that the first SiteMinder header
variable to be used is SM_UNIVERSALID. This variable provides information
for certificate authentication. If this variable is empty, then the information in
the variable SM_USER is used for basic authentication. For information about
configuring your SiteMinder system to use certificate authentication, see the
SiteMinder documentation.
Enabling trusted authentication in MicroStrategy Mobile
To enable users to log in to MicroStrategy Mobile using SSO authentication,
you must enable trusted authentication as an available authentication mode in
MicroStrategy Mobile. For instructions on configuring mobile devices to use
trusted authentication, refer to the Administering MicroStrategy Mobile
chapter in the MicroStrategy Mobile Design and Administration Guide.
To enable trusted authentication in MicroStrategy Mobile
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Mobile Administrator. The MicroStrategy Mobile
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
181
System Administration Guide
Server Administrator page opens.
2
On the left side of the page, click Default Properties. The Default
Properties page opens.
3
From the Trusted Authentication Providers drop-down list, select IBM Tivoli
Access Manager, CA SiteMinder, PingFederate, or Oracle Access Manager.
To use a custom authentication provider, select Custom SSO. For
information about adding custom authentication providers, refer to your
MicroStrategy SDK documentation.
At the bottom of the page, click Save.
4
To create a mobile configuration to send to users’ mobile devices, refer to the
Administering MicroStrategy Mobile chapter in the MicroStrategy Mobile
Design and Administration Guide.
Establishing trust between MicroStrategy Web or Mobile and Intelligence
Server
To enable the authentication token to pass from your third-party
authentication provider to MicroStrategy Web or Mobile, and then to
Intelligence Server, a trust relationship must be established between
MicroStrategy Web or Mobile and Intelligence Server. The steps to establish
trust are described below.
If you need to delete an established trust relationship, see To delete a trust
relationship, page 184.
*
If you are using multiple Intelligence Server machines in a cluster, you
must first set up the cluster, as described in Chapter 9, Clustering Multiple
MicroStrategy Servers, and then establish trust between Web or Mobile
Server and the cluster.
Prerequisites
To establish trust between MicroStrategy Web or Mobile and Intelligence
Server, you must have the following privileges:
•
Bypass all object security access checks
•
Configure security settings
•
Enable Intelligence Server administration from Web
•
Web administration
For information on assigning privileges to users, see Chapter , Controlling
access to functionality: Privileges.
182
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
To establish trust between MicroStrategy Web or Mobile and
Intelligence Server
1
Open MicroStrategy Web Administrator or MicroStrategy Mobile
Administrator, as applicable:
•
From the Windows Start menu, point to All Programs, then
MicroStrategy Tools, and then select Web Administrator. The
MicroStrategy Web Administrator page opens.
•
From the Windows Start menu, point to All Programs, then
MicroStrategy Tools, and then select Mobile Administrator. The
MicroStrategy Mobile Server Administrator page opens.
2
On the left, click Servers.
3
Confirm that MicroStrategy Web or Mobile Server is currently connected
to an Intelligence Server. If an Intelligence Server is not connected, in the
Unconnected Servers table, under Action, click Connect for the appropriate
Intelligence Server.
4
In the Connected Servers table, under Properties, click the Modify icon
. The Server Properties page opens, as shown below.
5
Next to Trust relationship between Web/Mobile Server and MicroStrategy
Intelligence Server, as applicable, click Setup. The Setup Trust Relationship
with MicroStrategy Intelligence Server page opens.
6
Type a User name and Password in the appropriate fields. The user must
have administrative privileges for MicroStrategy Web or Mobile, as
applicable.
7
From the options provided, select the authentication mode used to
authenticate the administrative user.
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
183
System Administration Guide
8
In the Web Server Application or Mobile Server Application field, type a
unique name for the trust relationship.
For example, you can use the URLs for the applications using Tivoli, as
follows:
MicroStrategy Web:
https://MachineName/JunctionName/MicroStrategy/asp
MicroStrategy Mobile:
https://
MachineName/JunctionName/MicroStrategyMobile/asp
9
Click Create Trust Relationship. The Server Properties page opens.
10 Click Save to create the trust relationship.
To verify the trust relationship
11 From the Windows Start menu, point to All Programs, then MicroStrategy
Products, and then select Developer. Developer opens.
12 Log in to a project source as a user with administrative privileges.
13 From the Administration menu, point to Server, and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
14 On the left, expand the Web Single Sign-on category, and verify that the
trusted relationship is listed in the Trusted Web Application Registration
list.
15 Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
To delete a trust relationship
1
2
184
Open MicroStrategy Web Administrator or MicroStrategy Mobile
Administrator, as applicable:
•
From the Windows Start menu, point to All Programs, then
MicroStrategy Tools, and then select Web Administrator. The
MicroStrategy Web Administrator page opens.
•
From the Windows Start menu, point to All Programs, then
MicroStrategy Tools, and then select Mobile Administrator. The
MicroStrategy Mobile Server Administrator page opens.
On the left, click Servers.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
3
Confirm that MicroStrategy Mobile is currently connected to an
Intelligence Server. If an Intelligence Server is not connected, in the
Unconnected Servers table, under Action, click Connect for the appropriate
Intelligence Server.
4
In the Connected Servers table, under Properties, click the Modify icon
. The Server Properties page opens.
5
Next to Trust relationship between MicroStrategy Web/Mobile Server and
MicroStrategy Intelligence Server, as applicable, click Delete.
The Delete Trust Relationship with MicroStrategy Intelligence Server page
opens.
6
Provide your login information in the appropriate fields.
7
Click Delete trust relationship.
The Server Properties page opens.
8
Click Save.
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
185
System Administration Guide
Establishing trust between MicroStrategy Web Services and Intelligence Server,
to support MicroStrategy Office
To establish trust between MicroStrategy Office and Intelligence Server, you
must use MicroStrategy Office to connect to the project source you want to use
trusted authentication for, and then establish the trust relationship between
Office and the Intelligence Server. Once you have completed this step, you
must edit the projectsources.xml file for Web Services to enable trusted
authentication for the project source. Both procedures are described below.
To establish trust between MicroStrategy Web Services and
Intelligence Server
1
On a machine where MicroStrategy Office is installed, open a Microsoft
Office product, such as Excel.
2
In the Microsoft Office ribbon, under the MicroStrategy Office tab, click
MicroStrategy Office. MicroStrategy Office starts, with a list of project
sources you can connect to.
3
From the list of project sources on the left, select the project source you
want to enable trusted authentication for.
4
In the right pane, enter the login ID and password for a user with
administrative privileges, and click Get Projects. A list of projects is
displayed.
5
Select any project, and click OK. The project is loaded, and the Shared
Reports folder is loaded in a new window.
6
In the MicroStrategy Office toolbar, click Options. The MicroStrategy Office
Options dialog box opens.
7
Under the General category, select Server. The Server Options pane is
displayed on the right.
8
Next to Trust relationship between Web Services and Intelligence Server,
click Create. An alert is displayed when the trust relationship has been
established.
To use the third-party authentication URL for Web Services
9
In the Web Services URL field, enter the URL for the Tivoli Junction or
SiteMinder Web Agent, as applicable, that you created for MicroStrategy
Web Services.
10 Click OK to save the changes.
186
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
Enabling trusted authentication in MicroStrategy Web Services to support
MicroStrategy Office
To allow users to log in to MicroStrategy Office using single sign-on (SSO),
you must do the following:
•
Edit the web.config file for Web Services or MWSConfig.properties
file for J2EE application servers, to choose a trusted authentication
provider.
•
Edit the projectsources.xml file for MicroStrategy Web Services and
configure the project source to use a third-party security plug-in. For
additional information on the settings in the projectsources.xml file,
refer to the Installing and Administering MicroStrategy Office chapter in
the MicroStrategy Office User Guide.
Prerequisite
•
You need administrative access to the machine where MicroStrategy Web
Services is installed.
To enable trusted authentication in MicroStrategy Office
To choose a trusted authentication provider
1
2
Depending on your Web Services environment, on the machine where
MicroStrategy Web Services is installed, do one of the following:
•
If you are using IIS as your application server, open the web.config
file in a text editor, such as Notepad. By default, the file is located in
C:\Program Files (x86)\MicroStrategy\Web Services.
•
If you are using Web Services in a J2EE-compliant application server,
open the MWSConfig.properties file in a text editor, such as
Notepad. By default, the file is located in the folder where your
application server deploys Web Services.
Depending on your Web Services environment, do the following:
•
In the web.config file, locate the following line:
<add key="TRUSTEDAUTHPROVIDER" value="1" />
•
In the MWSConfig.properties file, locate the following line:
TRUSTEDAUTHPROVIDER=1
3
Change value or TRUSTEDAUTHPROVIDER, as applicable, to one of the
following, as applicable:
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
187
System Administration Guide
•
To use Tivoli as the authentication provider, type 1.
•
To use SiteMinder as the authentication provider, type 2.
•
To use a custom authentication provider, type 3.
If you are using a custom authentication provider, you must make
* additional modifications to the custom_security.properties file,
which is located by default in C:\Program Files (x86)
\MicroStrategy\Web Services\resources. For information on
these modifications, refer to the MicroStrategy Developer Library
(MSDL).
To configure Web Services to use trusted authentication
4
On the machine where MicroStrategy Web Services is installed, open the
projectsources.xml file in a text editor, such as Notepad. By default,
the file is located in C:\Program Files (x86)\MicroStrategy\Web
Services.
5
In the projectsources.xml file, locate the <ProjectSource> tag
describing the project source you want to enable SSO for.
6
In the <ProjectSource> tag, replace the content of the <AuthMode>
tag with MWSSimpleSecurityPlugin. The contents of the new
<ProjectSource> tag should appear similar to the following:
7
<ProjectSource>
<ProjectSourceName>Name</ProjectSourceName>
<ServerName>Name</ServerName>
<AuthMode>MWSSimpleSecurityPlugIn</AuthMode>
<PortNumber>0</PortNumber>
</ProjectSource>
Save projectsources.xml.
Enabling anonymous authentication for Internet Information Services
If you use Internet Information Services (IIS) as your web server, you must
enable anonymous authentication to the MicroStrategy virtual directory to
support SSO authentication to MicroStrategy Web, Web Services or Mobile.
The steps to perform this configuration are provided below, which may vary
depending on your version of IIS. The following links may contain information
to enable anonymous authentication for your version of IIS:
188
•
IIS 7: http://technet.microsoft.com/en-us/library/
cc770966(WS.10).aspx
•
IIS 6: http://technet.microsoft.com/en-us/library/
cc737887(WS.10).aspx
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
•
IIS 5: http://support.microsoft.com/kb/310344
You cannot use Windows authentication to authenticate users in
~ MicroStrategy Web or Mobile if you enable anonymous authentication to
the MicroStrategy virtual directory in IIS. The steps below should only be
used as part of an SSO authentication solution with Tivoli.
To configure IIS to enable anonymous authentication to the
MicroStrategy Web, Web Services, and Mobile virtual directories
1
On the MicroStrategy Web server machine, access the IIS Internet Service
Manager.
2
Browse to and right-click the MicroStrategy virtual folder and select
Properties.
3
On the Directory Security tab, under Anonymous access and authentication
control, click Edit. The Authentication Methods dialog box opens
4
Select the Allow anonymous access check box.
5
Click OK to save your changes and close the Authentication Methods dialog
box.
6
Click OK again to save your changes to the MicroStrategy virtual folder.
7
To enable anonymous authentication to MicroStrategy Web Services,
repeat the above procedure for the MicroStrategyWS virtual directory.
8
To enable anonymous authentication to MicroStrategy Mobile, repeat the
above procedure for the MicroStrategyMobile virtual directory on the
Mobile Server machine.
9
Restart IIS for the changes to take effect.
Importing and linking third-party authentication users in
MicroStrategy
For third-party authentication users to access MicroStrategy applications, the
users must be granted MicroStrategy privileges. The following flowchart
illustrates the various ways that MicroStrategy users are handled when they
log in to Tivoli or SiteMinder:
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
189
System Administration Guide
Whether or not the LDAP DN is sent in the request to Intelligence Server is
configured when the Tivoli junction or SiteMinder Web Agent is created. For
details about creating a junction or Web Agent, refer to your Tivoli or
SiteMinder documentation.
A Tivoli or SiteMinder user can be:
•
Imported as a new MicroStrategy user upon logging in to MicroStrategy
Web, which assigns the user privileges that are defined for the
MicroStrategy user. For steps to perform this configuration, see Importing
Tivoli users as MicroStrategy users, page 191.
•
Allowed guest access to MicroStrategy Web. The Tivoli user inherits the
privileges of the Public/Guest group in MicroStrategy. Guest access to
MicroStrategy Web is not necessary for imported or linked Tivoli users.
For steps to perform this configuration, see Enabling guest access to
MicroStrategy Web or Mobile for Tivoli users, page 193.
A Tivoli or SiteMinder user can also be associated with an existing
MicroStrategy user, using the MicroStrategy User Editor. Associating Tivoli
users rather than enabling Tivoli users to be imported when they log in to
MicroStrategy Web enables you to assign MicroStrategy privileges and other
security settings for the user prior to their initial login. For steps to perform
this configuration, see Linking Tivoli users to existing MicroStrategy users,
page 192.
190
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
If a Tivoli or SiteMinder user has already been imported into MicroStrategy,
and a MicroStrategy user has been associated with the Tivoli or SiteMinder
user, the MicroStrategy metadata is synchronized with the information from
the user directory, such as the LDAP server. The way this synchronization
takes place depends upon several factors. The following flowchart shows how
the synchronization is handled.
Importing Tivoli users as MicroStrategy users
When MicroStrategy is configured to import a Tivoli user, the Tivoli user is
imported as a MicroStrategy user the first time that the user logs in to
MicroStrategy Web after the configuration is completed. A Tivoli user is
imported into MicroStrategy only if the Tivoli user has not already been
imported as or associated with a MicroStrategy user.
When a Tivoli user is imported into MicroStrategy:
•
The Tivoli user name is imported as the trusted authentication request
user ID for the new MicroStrategy user.
•
The MicroStrategy user is added to the Everyone group by default. If no
privileges are defined through a user directory such as LDAP, then the
imported user inherits the privileges associated with the MicroStrategy
Everyone group.
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
191
System Administration Guide
•
Security privileges are not imported from Tivoli; these must be defined in
MicroStrategy by an administrator.
To import Tivoli users as MicroStrategy users
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Products, and then select Developer. Developer opens.
2
Log in to a project source as a user with administrative privileges.
3
From the Administration menu, point to Server, and then Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
4
On the left, expand the Web Single Sign-on category.
5
On the right, select the Import user at login check box.
6
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
Linking Tivoli users to existing MicroStrategy users
As an alternative to importing users, you can link (or associate) Tivoli users to
existing MicroStrategy users to retain the existing privileges and
configurations defined for the MicroStrategy users. Linking Tivoli users rather
than enabling Tivoli users to be imported when they log in to MicroStrategy
Web enables you to assign privileges and other security settings for the user
prior to their initial login.
To link Tivoli users to existing MicroStrategy users
192
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Products, and then select Developer. Developer opens.
2
Log in to a project source as a user with administrative privileges.
3
In the folder list on the left, expand Administration, and then expand User
Manager.
4
Browse to the MicroStrategy user to link to a Tivoli user.
5
Right click the user and select Edit. The User Editor opens.
6
Expand Authentication, then select Metadata.
7
Under Trusted Authentication Request, in the User ID field, type the Tivoli
user name to link to the MicroStrategy user.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
© 2015, MicroStrategy Inc.
System Administration Guide
*
8
The name you type in the User ID field should be the same as the one
that the user employs when providing his Tivoli login credentials.
Click OK.
Enabling guest access to MicroStrategy Web or Mobile for Tivoli users
If you choose to not import or link Tivoli users to a MicroStrategy user, you
can enable guest access to MicroStrategy Web for the Tivoli users. Guest users
inherit their privileges from the MicroStrategy Public/Guest group.
To enable guest access to MicroStrategy Web or Mobile for Tivoli
users
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Products, and then select Developer. Developer opens.
2
Log in to a project source as a user with administrative privileges.
3
From the Administration menu, point to Server, and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
4
On the left, expand the Web Single Sign-on category.
5
On the right, in the Trusted Web Application Registration area, select the
MicroStrategy Web or MicroStrategy Mobile application, as applicable.
6
Select the Allow user to log in if Web Single Sign-on - MicroStrategy user link
not found check box.
7
On the right, expand the LDAP category, then expand the Import
subcategory, and select Options.
8
Select the Synchronize user/group information with LDAP during Trusted
authentication check box.
9
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
Logging in to MicroStrategy Web using Tivoli single sign-on
Once all of the preliminary steps have been completed and tested, users may
begin to sign in to MicroStrategy using their Tivoli credentials. Sign-on steps
are provided in the procedure below.
© 2015, MicroStrategy Inc.
Enabling Single Sign-on to Web, Mobile, and Office with third-party
authentication
193
System Administration Guide
To log in to MicroStrategy Web using Tivoli single sign-on
1
Open a web browser.
2
Type the following URL in the address field:
https://MachineName/JunctionName/MicroStrategyWebURL
Where the variables in italics are as follows:
•
MachineName is the name of the machine running Tivoli.
•
JunctionName is the name of the junction created in Tivoli.
•
MicroStrategyWebURL is the URL to access MicroStrategy Web. For
example, MicroStrategy/asp.
3
Type your Tivoli user name and password.
4
Connect to a MicroStrategy project.
5
Click Trusted Authentication.
You are logged in to the MicroStrategy project with your Tivoli user
credentials.
If you are prompted to display both secure and non-secure items on the web
page, you can configure your web browser to hide this warning message. Refer
to your web browser documentation regarding this configuration.
Enabling Usher authentication for Web and Mobile
If you use an LDAP directory to centrally manage users in your environment,
you can add them to your Usher network, and allow them to log into
MicroStrategy Web or Mobile by using their Usher badges.
The users in your LDAP directory can log into MicroStrategy Web by:
•
Scanning a QR code using the Usher app on their smart phones, if Usher is
configured as the primary authentication method.
•
Supplementing their user name and password with a numerical Usher code
that is provided via the Usher app on their smart phones, if Usher is
configured as the second factor of authentication.
The high-level steps to enable Usher authentication for Web and Mobile are as
follows:
1
194
Set up an Usher network, and badges for your users. Your network is the
group of users in your organization who can use the Usher app on their
smart phone to validate their identity to log in to MicroStrategy. For steps
to create an Usher network, see the Usher Help.
Enabling Usher authentication for Web and Mobile
© 2015, MicroStrategy Inc.
System Administration Guide
2
Add your LDAP directory to your Usher network. For steps to add your
LDAP directory to Usher, see the Usher Help.
3
Connect your LDAP directory to MicroStrategy. For steps to connect your
LDAP directory to MicroStrategy, see Implementing LDAP authentication,
page 116.
4
Register your MicroStrategy environment with Usher. For steps, see
Registering your MicroStrategy products with Usher, page 195.
5
Configure Usher in MicroStrategy Web and Mobile. For steps, see
Configuring Usher in MicroStrategy Web and Mobile, page 196.
Registering your MicroStrategy products with Usher
To establish a connection between Usher and your MicroStrategy products,
you must register your MicroStrategy products with Usher, using the steps
below.
Prerequisites
•
You have created an Usher network, and badges for your users. Your
network is the group of users in your organization who can use the Usher
app on their smart phone to validate their identity to log in to
MicroStrategy. For steps to create an Usher network, see the Usher Help.
•
You have connected an LDAP user directory to MicroStrategy. For steps to
connect your LDAP directory to MicroStrategy, see Implementing LDAP
authentication, page 116.
To register MicroStrategy with Usher
1
In a web browser, log in to Usher Network Manager, using one of the
following methods:
•
If you have installed Usher in your IT infrastructure, navigate to the
server where you installed Usher Network Manager.
•
If you are using Usher in the cloud, navigate to https://go.usher.com.
2
Click Gateway Configuration. The Gateway Configuration page opens.
3
In the MicroStrategy Platform Login area, click the MicroStrategy icon.
Review the message, then click Continue.
4
To change the image that is displayed on the login page when users open
MicroStrategy Web, click Import an Icon. Select an image to display, and
click Open.
© 2015, MicroStrategy Inc.
Enabling Usher authentication for Web and Mobile
195
System Administration Guide
5
In the Enter Display Name field, type a name to display on your
MicroStrategy login page.
6
Click Next. The Set Up Your MicroStrategy Platform page is shown, with
the details to configure your MicroStrategy Intelligence Server.
7
Note the values for Organization ID, Application ID, and Token. You use
these values to configure MicroStrategy Intelligence Server.
8
Click Done.
Configuring Usher in MicroStrategy Web and Mobile
To allow your users to log into MicroStrategy Web and Mobile with their
Usher badges, you must configure Usher as a trusted authentication provider
in Web Administrator and Mobile Administrator, as described in the steps
below.
Prerequisites
•
You have registered your MicroStrategy products with Usher, as described
in Registering your MicroStrategy products with Usher, page 195, and
noted the Organization ID, Application ID, and Token provided by Usher.
•
You have upgraded your MicroStrategy metadata. For steps to upgrade
your MicroStrategy metadata, see the Upgrade Guide.
Enabling Usher authentication without upgrading your metadata may
~ cause your users to be locked out of MicroStrategy applications.
•
If you are enabling two-factor authentication for Web using Usher, you
have added at least one user to the Two-factor Exempt (2FAX) user group
in your MicroStrategy project. MicroStrategy users who are members of
the Two-factor Exempt (2FAX) group are exempt from two-factor
authentication, and do not need to provide an Usher code to log into
MicroStrategy Web. It is recommended that these users have a secure
password for their accounts, and use their accounts for troubleshooting
MicroStrategy Web.
To enable Usher authentication in Web and Mobile
To configure Intelligence Server for Usher authentication
1
196
From the Windows Start menu, select All Programs, then MicroStrategy
Tools, and click Web Administrator. The Web Administrator page opens,
with a list of your Intelligence Servers.
Enabling Usher authentication for Web and Mobile
© 2015, MicroStrategy Inc.
System Administration Guide
2
For your Intelligence Server, click Modify. The Server Properties page
opens.
3
Next to Usher Configuration, click Setup. The Usher Configuration page
opens.
4
In the Connectivity section, in the Usher Server URL field, enter one of the
following:
•
If you are using Usher in the cloud, type https://uvsv2.usher.com.
•
If you have installed Usher in your infrastructure, type the URL for the
Usher Server you installed.
5
In the OrgID field, type the Organization ID from Usher Network Manager.
6
In the AppID field, type the Application ID from Usher Network Manager.
7
If you want to use Usher as a two-factor authentication system, select the
Enable two-factor authentication check box. The Security token field is
enabled.
MicroStrategy users who are members of the Two-factor Exempt
~ (2FAX) group are exempt from two-factor authentication, and do not
need to provide an Usher code to log into MicroStrategy Web. It is
recommended that these users have a secure password for their
accounts, and use their accounts for troubleshooting MicroStrategy
Web.
8
In the Security token field, type the Security Token from Usher Network
Manager.
9
Click Save to save your changes. To save the Usher configuration, you are
prompted for your MicroStrategy credentials.
10 Type your MicroStrategy user name and password, and click Login. The
settings are saved.
To enable Usher authentication in Web and Mobile
11 In Web Administrator, from the menu on the left, click Default Properties.
The Default Server Properties page opens.
12 In the Login area, for Trusted Authentication Request, select the Enabled
check box.
13 From the Trusted Authentication Providers drop-down menu, select Usher.
14 Click Save to save your changes.
15 Repeat the above steps to add Usher as a trusted authentication provider
in Mobile Administrator. To open Mobile Administrator, in the Start
© 2015, MicroStrategy Inc.
Enabling Usher authentication for Web and Mobile
197
System Administration Guide
menu, select All Programs, then MicroStrategy Tools, and click Mobile
Administrator.
Authentication examples
Below are a few examples of how the different methods for user authentication
can be combined with different methods for database authentication to achieve
the security requirements of your MicroStrategy system. These examples
illustrate a few possibilities; other combinations are possible.
Security views: Windows authentication and linked
warehouse login
You may want to use this configuration if you are using security views to
implement access control policies for data. For example, two different users
executing the same SQL query receive different results, reflecting their
different levels of access. For the security views to work, each report is
executed under the RDBMS account of the user who submitted the report from
the MicroStrategy system. Even though this approach requires users to have
accounts on the RDBMS, you may choose to use Windows authentication so
that users do not have to remember their RDBMS login ID and password when
logging in to the MicroStrategy system. With Windows authentication, users
are automatically logged in to the MicroStrategy system using their Windows
ID and password.
For detailed information about security views, see Security views, page 99.
To establish this configuration
198
1
In Developer, open the Project Source Manager, and on the Advanced tab,
select Use network login ID (Windows authentication) as the Authentication
mode.
2
From Web, log in as an administrator and select Preferences, select
Project Defaults, select Security, and then enable Windows Authentication
as the login mode.
3
In Developer, in the User Editor, expand Authentication, then select
Warehouse.
Security views: Windows authentication and linked warehouse login
© 2015, MicroStrategy Inc.
System Administration Guide
4
Link users to their respective database user IDs using the Warehouse
passthrough Login and Warehouse passthrough password boxes for each
user. For details on each option, click Help.
5
Enable the setting for database execution to use linked warehouse logins
on each project that you wish to use linked warehouse logins for database
execution. To do this, right-click the project and select Project
Configuration, expand the Database instances category, click Execution,
and select the Use linked warehouse login for execution check box.
Connection maps: Standard authentication, connection
maps, and partitioned fact tables
You may want to use this configuration if you implement access control
policies in the RDBMS so that you can have multiple user accounts in the
RDBMS, but not necessarily one for every user. In addition, you must use
connection maps to enable report subscriptions if you are using Microsoft
Analysis Services with integrated authentication.
For example, you are partitioning fact tables by rows, as described in Splitting
fact tables by rows, page 99. You have a user ID for the 1st National Bank that
only has access to the table containing records for that bank and another user
ID for the Eastern Credit Bank that only has access to its corresponding table.
Depending on the user ID used to log in to the RDBMS, a different table is
used in SQL queries.
Although there are only a small number of user IDs in the RDBMS, there are
many more users who access the MicroStrategy application. When users access
the MicroStrategy system, they log in using their MicroStrategy user names
and passwords. Using connection maps, Intelligence Server uses different
database accounts to execute queries, depending on the user who submitted
the report.
To establish this configuration
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) as the Authentication mode. This is the default
setting.
3
From Web, log in as an administrator and select Preferences, select
Project Defaults, select Security, and then enable Standard (user name &
password) as the login mode.
4
Create a database login for each of the RDBMS accounts.
© 2015, MicroStrategy Inc.
Connection maps: Standard authentication, connection maps, and
partitioned fact tables
199
System Administration Guide
200
5
Create a user group in the MicroStrategy system corresponding to each of
the RDBMS accounts and then assign multiple users to these groups as
necessary.
6
Define a connection mapping that maps each user group to the appropriate
database login.
Connection maps: Standard authentication, connection maps, and
partitioned fact tables
© 2015, MicroStrategy Inc.
4
ENABLING SECURE
COMMUNICATION
Introduction
SSL (secure socket layer) is an encryption technology that encodes
communication over the Internet or local network so that only the recipient
can read it.
This chapter describes the steps to enable secure, encrypted communications
between MicroStrategy components using SSL.
The documentation below refers to third-party software, and thus is
~ subject to change. MicroStrategy makes no guarantee on the availability or
accuracy of third party documentation.
Overview of SSL and encryption in
MicroStrategy
To enable private communications between MicroStrategy components, you
can configure them to use SSL encryption while communicating with each
other. You can use SSL to encrypt communications between the following
applications:
© 2015, MicroStrategy Inc.
201
System Administration Guide
•
Intelligence Server and Developer, MicroStrategy Web, and Mobile Server
•
MicroStrategy Web and users’ browsers
•
Mobile Server and MicroStrategy Mobile for iPhone, iPad, and Android
•
Web Services and Office
In addition, you can set up encrypted communications between Intelligence
Server and Web or Mobile Server, using AES encryption. For steps to set up
encryption between Web or Mobile Server and Intelligence Server, see
Enabling encryption between Web or Mobile Server and Intelligence Server ,
page 215.
The following is an overview of the tasks you need to perform to set up SSL
for MicroStrategy applications:
•
Obtain an SSL Certificate for the MicroStrategy applications. For steps, see
Obtaining SSL certificates, page 202.
•
Install the SSL certificates on the servers, where applicable. For steps, see
Installing the SSL certificates, page 206.
•
Configure MicroStrategy applications to require SSL access. For steps, see
Configuring the MicroStrategy applications to use SSL, page 209.
•
Test SSL access. For steps, see Testing SSL access, page 213.
•
Configure client applications, such as Office and Mobile, to use the SSL
HTTPS URL. For steps, see Configuring MicroStrategy client applications
to use an HTTPS URL, page 214.
Obtaining SSL certificates
To enable secure communications between MicroStrategy components, you
must obtain an SSL certificate for the following MicroStrategy applications, as
applicable:
•
Intelligence Server
•
Developer (optional)
•
MicroStrategy Web
•
Mobile Server
•
If you use Office, MicroStrategy Web Services
Use the following table to determine which applications you need to obtain
SSL certificates for:
202
© 2015, MicroStrategy Inc.
System Administration Guide
Requirement
Obtain SSL
certificates for:
Secure communications between Intelligence Server and
Developer
•
Intelligence
Server
•
Developer
(optional)
Secure communications between MicroStrategy Web and users’
browsers
•
MicroStrategy
Web
Secure communications between Mobile Server and Mobile for
iPhone, iPad, and Android
•
Mobile Server
Secure communications between Web Services and MicroStrategy
Office
•
Web Services
The high-level overview of the process is as follows:
•
Generate SSL Certificate Requests for the servers that the MicroStrategy
components run on. For steps, see Generating an SSL Certificate Signing
Request, page 204.
•
Submit the Certificate Requests, and receive the corresponding certificates.
For steps, see Submitting a Certificate Request, page 205.
Prerequisites
Before enabling SSL for your installed products, you require access to a
Certificate Authority (CA), which may be one of the following:
•
An enterprise CA, which is set up on your local network. The decision to
set up an enterprise CA should be made at the executive level. To set up an
enterprise CA on your network, refer to your server operating system’s
documentation.
•
A commercial CA, such as VeriSign.
•
If you need certificates for a development or proof-of-concept environment,
you can set up your own CA to create self-signed certificates. For steps, see
Self-signed certificates: Creating a Certificate Authority for development,
page 216.
If you are using an enterprise CA or self-signed certificates for use with
* Android devices, it is recommended that you use devices that are running
Android 4.0 (Ice Cream Sandwich) or better.
© 2015, MicroStrategy Inc.
Prerequisites
203
System Administration Guide
Generating an SSL Certificate Signing Request
You can use the OpenSSL utility to create an SSL Certificate Signing Request
(CSR) for each of your applications.
If you are using a UNIX or Linux machine, the OpenSSL utility should be
installed by default. If you are using a Windows machine, you can download
the OpenSSL utility from http://www.openssl.org/.
To generate an SSL Certificate Signing Request using OpenSSL
1
Depending on your platform, do one of the following:
•
UNIX/Linux: Open a terminal window.
•
Windows: Open a command prompt window, and navigate to the
location where OpenSSL is installed. By default, this is C:\OpenSSLWin32\bin.
To generate a private key for the server
2
Type the following command, and press Enter:
openssl genrsa –des3 –out Server_key.key
Where Server_key.key is the name of the private key file. By default,
the private key file is created in the current location. To create the file at a
different location, replace Server_key.key with a path to create the new
file.
You are prompted for a pass-phrase for the key.
3
Type a secure pass-phrase for the key, and press Enter. The key file is
created.
To generate the Certificate Signing Request
4
Type the following command, and press Enter:
openssl req –new –key Server_key.key –out Server_
CSR.csr
Where Server_key.key is the private key file that you created, and
Server_CSR is the CSR file.
5
204
You are prompted for information such as your organization’s name,
department name, country code, and so on. Type the information about
your organization as you are prompted. When prompted for a Common
Name, type the fully qualified domain name of the server that the
application runs on. For example, if Intelligence Server runs on a machine
Generating an SSL Certificate Signing Request
© 2015, MicroStrategy Inc.
System Administration Guide
called intelligenceserver, and your domain is yourcompany.com,
the fully qualified domain name is
intelligenceserver.yourcompany.com.
When you have entered all the required information, the CSR file is
created.
6
Repeat this procedure for every application that you need a certificate for.
Submitting a Certificate Request
Once you have created a Certificate Request, you must submit it to a
Certificate Authority (CA) to obtain an SSL certificate. If you are using a
commercial CA, such as VeriSign, refer to their documentation for the
procedure to submit the certificate.
If you have an enterprise CA running Microsoft Certificate Services on your
local network, use the following procedure to submit a Certificate Request.
To submit a Certificate Request to an enterprise CA running Microsoft
Certificate Services
1
Open the request file generated in Generating an SSL Certificate Signing
Request, page 204 with Microsoft Notepad, and copy the contents.
2
In your browser, open the following URL: http://hostname/
CertSrv, where hostname is the server on which Microsoft Certificate
Services was installed. The Microsoft Certificate Services page opens.
3
Click Request a Certificate. The Choose Request Type page opens.
4
Click Advanced Request and click Next. The Submit a Certificate Request
or Renewal Request page opens.
5
In the Base64 Encoded Certificate Request field, paste the contents of the
request file, and click Submit. The Certificate Pending page is displayed.
You may need to contact the administrator of the CA to ensure that the
* Certificate Request is approved.
6
Once the Certificate Request is approved, open the Certificate Services URL
above.
You must access the Certificate Services URL using the same machine
* and browser that you used to submit the certificate request.
© 2015, MicroStrategy Inc.
Submitting a Certificate Request
205
System Administration Guide
7
Click View the status of a pending certificate request. The Pending
Requests page opens.
8
Click the link for the certificate request you made. If the certificate has
been issued, the Certificate Issued page opens.
9
Select the Base 64 encoded option, and click Download certificate. The
certificate is downloaded.
10 Once you have downloaded the certificates for the applications you need,
copy them to the machines where the applications are installed.
Installing the SSL certificates
You need to install the SSL certificates on the application servers that host the
following applications:
•
MicroStrategy Web, to enable secure communication between Web and
users’ browsers.
•
MicroStrategy Mobile Server, to enable secure communication between
Mobile Server and Mobile for iPhone, iPad, and Android.
•
MicroStrategy Web Services, to enable secure communication between
Web Services and Office.
When you have downloaded the SSL certificate from your enterprise or
commercial CA, perform the following steps to install it on the application
servers.
The following procedure describes the steps to install an SSL certificate in
IIS 6 running on Microsoft Windows Server. If you have a different version of
IIS, or are using a different application server, such as Tomcat, refer to the
product’s documentation for instructions to install SSL certificates.
To install the SSL certificates for Web, Mobile Server, or Web Services
in IIS 6
206
1
From the Start menu, select Settings, then Control Panel, then select
Administrative Tools. Open the Internet Services Manager tool.
2
On the left, navigate to the website that contains the application’s virtual
directory. By default, this is Default Web Site. Right-click the website and
click Properties. The Properties dialog box opens.
Submitting a Certificate Request
© 2015, MicroStrategy Inc.
System Administration Guide
3
On the Directory Security tab, click Server Certificate. The Web Server
Certificate Wizard opens. Click Next to close the Welcome page.
4
Click Process the pending request and install the certificate. Click Next.
The Process a Pending Request page opens.
5
Enter the path and file name of the issued certificate and click Next. The
Certificate Summary page opens.
6
Review the information in the Certificate Summary, click Next, and then
click Finish to install the certificate on the application server.
In addition, if you obtained the SSL certificate from an enterprise CA, you
* must add the CA as a trusted certificate authority using the steps described
in Adding your enterprise CA as a trusted certificate authority below.
Adding your enterprise CA as a trusted certificate
authority
If you used an enterprise CA on your network, or if you created a CA for
demos, as described in Self-signed certificates: Creating a Certificate
Authority for development, page 216, the CA’s root certificate must be
installed as a trusted root certificate authority in the following locations:
•
The servers where Web, Mobile Server, or Web Services are installed, as
applicable. For steps, see To add your enterprise CA as a trusted
certificate authority for Web, Mobile Server, or Web Services, page 208.
•
Mobile devices, such as iPhone, iPad, or Android phones and tablets. For
steps to add a trusted CA for iPhone and iPad, see To add your enterprise
CA as a trusted certificate authority for iOS devices, page 208.
*
For Android devices, you must add the certificate as a trusted
certificate while creating a configuration for your devices in Mobile
Administrator. For steps to configure Android devices, see the
Administering MicroStrategy Mobile chapter in the Mobile Design and
Administration Guide.
Prerequisite
•
You must have access to a copy of your enterprise CA’s root certificate to
perform this procedure.
If your enterprise CA uses Microsoft Certificate Services, open the
following URL in a browser window: http://hostname/CertSrv,
where hostname is the computer on which Certificate Services is installed,
click Download a CA certificate, certificate chain, or CRL, and under
Encoding method, select Base 64. Click Download CA certificate and save it
to the computer.
© 2015, MicroStrategy Inc.
Adding your enterprise CA as a trusted certificate authority
207
System Administration Guide
If your enterprise CA uses OpenSSL, contact your administrator for a copy
of the certificate.
To add your enterprise CA as a trusted certificate authority for Web,
Mobile Server, or Web Services
1
On the machine where Web, Mobile Server, or Web Services is installed,
from the Start menu, select Run, type mmc, and press Enter. The Microsoft
Management Console opens.
2
From the File menu, select Console, and then select Add/Remove Snap-in.
The Add/Remove Snap-in dialog box opens.
3
Click Add to open the Add Standalone Snap-in dialog box, click
Certificates, and then click Add. The Certificates Snap-in dialog box opens.
4
Select Computer Account and click Next. The Select Computer page opens.
5
Click Local Computer and then click Finish. The Certificates snap-in is
displayed in the list of selected snap-ins.
6
Click OK to return to the Console Root dialog box.
7
On the left, expand the Certificates snap-in, then expand Trusted Root
Certificate Authorities.
8
Click Action, then All Tasks, then Import. The Certificate Import Wizard
opens.
9
Click Browse, and select the certificate you downloaded from your CA.
10 Click Next. The Certificate Store page opens.
11 Select Place all certificates in the following store.
12 Click Browse, and select the Trusted Root Certification Authorities folder.
13 Click Next, then click Finish. A message is displayed, indicating that the
import was successful.
To add your enterprise CA as a trusted certificate authority for iOS
devices
1
To distribute your enterprise CA’s root certificate to users, do one of the
following:
•
208
Send the certificate as an email attachment to all iOS users.
Adding your enterprise CA as a trusted certificate authority
© 2015, MicroStrategy Inc.
System Administration Guide
•
On a server on your network, create a basic web page that allows users
to download the certificate, and email the URL of the web page to your
users.
The following steps must be performed for every iOS device in your
* organization.
2
On an iPhone or iPad, open the email or URL that contains the link to the
certificate.
3
Tap the link to download the certificate. The certificate is downloaded, and
is opened in the Install Profile dialog in the device’s Settings screen.
4
In the Install Profile dialog, tap Install. A warning may be displayed,
indicating that the authenticity of the certificate cannot be verified.
5
Click Install. The certificate is installed, and is shown as a trusted
certificate.
*
If the device is protected with a passcode, you must type the passcode
to install the certificate.
Configuring the MicroStrategy applications to
use SSL
Use the following table to determine which MicroStrategy applications you
need to configure SSL access for.
Requirement
Refer to:
Secure communications between
Intelligence Server and Developer,
MicroStrategy Web, or Mobile Server
Configuring SSL between Intelligence
Server and Developer, MicroStrategy Web,
or Mobile Server, page 210
Secure communications between Web and
users’ browsers
Configuring Web, Mobile Server, and Web
Services to require SSL access, page 212
Secure communications between Mobile
Server and Mobile for iPhone, iPad, and
Android
Configuring Web, Mobile Server, and Web
Services to require SSL access, page 212
Secure communications between Web
Services and MicroStrategy Office
Configuring Web, Mobile Server, and Web
Services to require SSL access, page 212
© 2015, MicroStrategy Inc.
Adding your enterprise CA as a trusted certificate authority
209
System Administration Guide
Configuring SSL between Intelligence Server and
Developer, MicroStrategy Web, or Mobile Server
To enable Intelligence Server and Developer, MicroStrategy Web, or Mobile
Server to communicate using SSL, you must first use the Configuration Wizard
to add the SSL certificate to use for Intelligence Server, and then enable SSL in
the respective applications.
Configuring SSL for Intelligence Server
Prerequisites
•
You must have the SSL certificate you created for Intelligence Server.
•
You must have the private key file that you created while requesting a
certificate for Intelligence Server, as described in Generating an SSL
Certificate Signing Request, page 204.
To configure SSL for Intelligence Server
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Configuration Wizard. The Configuration Wizard
opens.
2
On the Welcome screen, select Configure Intelligence Server, and click
Next. The Metadata Connection page opens.
3
If you have previously configured Intelligence Server, click Next until you
reach the SSL Configuration page. If this is the first time you are
configuring Intelligence Server, click Help for instructions to configure
Intelligence Server.
4
In the SSL Configuration page, enable the Configure SSL check box.
5
Click the button next to the Certificate field and browse to the certificate
you created for Intelligence Server.
6
Click the button next to the Key field and browse to the private key file you
created while requesting the certificate for Intelligence Server.
7
In the Password field, type the password that you used while creating the
private key for the certificate.
8
In the SSL Port field, type the port number to use for SSL access. By
default, the port is 39321.
Configuring SSL for Developer
Prerequisites
210
Configuring SSL between Intelligence Server and Developer,
MicroStrategy Web, or Mobile Server
© 2015, MicroStrategy Inc.
System Administration Guide
•
You must use the Configuration Wizard to set up SSL for Intelligence
Server, as described in To configure SSL for Intelligence Server, page 210.
•
For additional security, you can enable Developer to verify Intelligence
Server’s certificate with the Certificate Authority (CA) before transmitting
any data. If you want to enable this option, you must obtain the following:
▫
Your CA’s SSL certificate. If you are using a commercial CA, refer to
their documentation for instructions to download their certificate.
If you are using an enterprise CA that has Microsoft Certificate Services
installed, visit http://hostname/CertSrv, where hostname is the
computer on which Certificate Services is installed, and click Download
a CA certificate, certificate chain, or CRL. Under Encoding method,
select Base64.
To configure SSL for Developer
1
In Developer, right-click the server-based project source that you use to
connect to Intelligence Server, and select Modify Project Source.
2
On the Connection tab, select the Use SSL check box.
3
If you want Developer to verify Intelligence Server’s certificate with the CA
every time a connection is made, select the Verify Server Certificate check
box.
*
You must perform the following tasks to verify the server’s certificate:
— Download the CA’s certificate to the computer running
Developer.
— In the Client SSL Certificate Authority Certificate field, enter the
path to the CA’s certificate. For example,
C:\Certificates\desktop.cer.
4
Click OK to save the changes.
Configuring SSL for Web and Mobile Server
Prerequisites
•
You must use the Configuration Wizard to set up SSL for Intelligence
Server, as described in To configure SSL for Intelligence Server, page 210.
© 2015, MicroStrategy Inc.
Configuring SSL between Intelligence Server and Developer,
MicroStrategy Web, or Mobile Server
211
System Administration Guide
To configure SSL for Web and Mobile Server
1
Open MicroStrategy Web Administrator or MicroStrategy Mobile
Administrator, as applicable:
•
From the Windows Start menu, point to All Programs, then
MicroStrategy Tools, and then select Web Administrator. The
MicroStrategy Web Administrator page opens.
•
From the Windows Start menu, point to All Programs, then
MicroStrategy Tools, and then select Mobile Administrator. The
MicroStrategy Mobile Server Administrator page opens.
2
On the left, click Security. The Security page opens.
3
Under Traffic to the Intelligence Server, select the SSL option.
4
If you want Web or Mobile Server to verify Intelligence Server’s SSL
certificate, select Validate Intelligence Server certificate.
5
Click Save to save your changes.
Configuring Web, Mobile Server, and Web Services to
require SSL access
You can configure your application server to require that clients, such as users’
web browsers, access the following applications with SSL, using the HTTPS
protocol:
•
MicroStrategy Web, to enable secure communication between Web and
users’ browsers.
•
MicroStrategy Mobile Server, to enable secure communication between
Mobile Server and Mobile for iPhone, iPad and Android.
•
MicroStrategy Web Services, to enable secure communication between
Web Services and Office.
The following procedure describes the steps to require SSL access using IIS 6
running on Microsoft Windows Server. If you have a different version of IIS, or
are using a different application server, such as Tomcat, refer to the product’s
documentation for instructions to require SSL for applications.
212
Configuring Web, Mobile Server, and Web Services to require SSL
access
© 2015, MicroStrategy Inc.
System Administration Guide
To configure Web, Mobile Server, or Web Services to require SSL
access
1
From the Windows Start menu, point to Settings, then Control Panel, and
then select Administrative Tools. Open the Internet Information Services
Manager tool.
2
On the left, navigate to the application’s virtual directory. By default, these
are:
•
Web: MicroStrategy
•
Mobile Server: MicroStrategyMobile
•
Web Services: MicroStrategyWS
Right-click the virtual directory and click Properties. The Properties dialog
box opens.
3
On the Directory Security tab, in the Secure Communications panel, click
Edit. The Secure Communications dialog box opens.
4
Click Require secure channel (SSL) to require the use of HTTPS.
5
Click OK, then click OK again to close the Properties dialog box.
6
Repeat this procedure for the applications that apply to your requirements.
7
Close the Internet Information Services Manager.
Testing SSL access
You can perform the following steps to test SSL access to Web and Web
Services.
To test SSL access to Web and Web Services
1
In your browser, enter the URL to access Web and Web Services. By
default, these are:
•
Web (ASP.net): http://hostname/MicroStrategy/asp/, where
hostname is the name of the server that Web is running on.
© 2015, MicroStrategy Inc.
Configuring Web, Mobile Server, and Web Services to require SSL
access
213
System Administration Guide
•
Web (J2EE):
http://hostname/MicroStrategy/servlet/mstrWeb, where
hostname is the name of the server that Web is running on.
•
Web Services:
http://hostname/MicroStrategyWS/MSTRWS.asmx, where
hostname is the name of the server that Web Services is running on.
An error page should be displayed, with a 403.4 error indicating that SSL
is required to access the page.
2
In the above URLs, replace http:// with https://. After a short delay,
Web should open, or the Web Services method list should be displayed (as
applicable), indicating that the SSL access is working.
Configuring MicroStrategy client applications to
use an HTTPS URL
To require iPhones, iPads, and Android devices to use HTTPS to connect to
Mobile Server, you must update your device configurations in Mobile Server.
To require MicroStrategy Office to use SSL to connect to Web Services, in the
Options dialog box, you must add the https:// prefix to the URL for Web
Services, as described in To configure MicroStrategy Office to use SSL, page
215.
To configure MicroStrategy Mobile for iPhone, iPad and Android to use
SSL
214
1
Open the Mobile Administrator page.
2
Click Mobile Configuration. The Mobile Configuration page opens.
3
For the configuration you want to edit, click Modify. The configuration
opens.
4
Click the Connectivity Settings tab.
5
For the Mobile Server that has SSL enabled, from the Request Type dropdown list, select HTTPS.
6
Click Save to save the configuration.
7
Repeat this procedure for every configuration that includes the above
Mobile Server.
Configuring Web, Mobile Server, and Web Services to require SSL
access
© 2015, MicroStrategy Inc.
System Administration Guide
To configure MicroStrategy Office to use SSL
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Office Configuration.
2
Under General, select Server.
3
In the Web Services URL field, replace the http:// prefix with
https://.
4
Click OK to save the changes and close the MicroStrategy Office Options
dialog box.
Enabling encryption between Web or Mobile
Server and Intelligence Server
You can also encrypt communication between the application and Intelligence
Server, using AES encryption. Use the following procedure to enable
encryption.
There is additional overhead involved in encrypting and decrypting the data
* between Web or Mobile Server and Intelligence Server, so you may
experience a drop in performance. It is recommended that you use SSL to
create a secure connection between Web or Mobile Server and Intelligence
Server.
To enable encryption between Web or Mobile Server and Intelligence
Server
1
Open the Administrator page for Web or Mobile Server, as applicable.
2
In the column on the left, click Security. The Security settings page opens.
3
Under Traffic to the Intelligence Server, select the AES Tunneling option.
4
Click Save to save your changes.
© 2015, MicroStrategy Inc.
Configuring Web, Mobile Server, and Web Services to require SSL
access
215
System Administration Guide
Self-signed certificates: Creating a Certificate
Authority for development
If you are creating demos or proofs-of-concept that require SSL, you can set up
a server that can act as a Certificate Authority (CA) to sign the certificates for
the MicroStrategy applications.
It is recommended that you use self-signed certificates only in demo or
~ development environments. Self-signed certificates are not recommended
in a production environment for the following reasons:
▫
If the CA server is compromised, an attacker can use it to sign
certificates for malicious sites.
▫
By default, users’ devices and browsers do not accept self-signed
certificates, which may cause users to receive security warnings and
disrupt their workflows.
You can set up a CA server using the OpenSSL utility. If you are using a UNIX
or Linux machine, OpenSSL should be installed by default. If you are using a
Windows machine, you can download the OpenSSL utility from
http://www.openssl.org/.
To set up a CA, you need to perform the following tasks:
•
Create the directories and configuration files for the CA. See Creating the
directories and configuration files for your CA, page 216.
•
Create the server’s private key and root certificate. See Creating the
private key and root certificate for the CA, page 218.
•
Add the root certificate as a trusted certificate on your network. See
Adding your enterprise CA as a trusted certificate authority, page 207.
•
Configure OpenSSL to use the server’s private key and certificate to sign
certificate requests. See Configuring OpenSSL to use your private key and
root certificate, page 219.
•
Create certificates for the MicroStrategy applications. See Signing
certificate requests using your CA, page 220.
Creating the directories and configuration files for your
CA
To create your CA using OpenSSL, you must create directories to store
important files for the CA, such as the server’s private keys, certificates that
216
Creating the directories and configuration files for your CA
© 2015, MicroStrategy Inc.
System Administration Guide
have been signed, and so on. In addition, you must create the files that track
the certificates that have been created, and an OpenSSL configuration file for
your CA.
To create the directories and files for the CA
1
Using Windows Explorer or the UNIX Terminal, as applicable, create the
following directories:
Directory
Folder name
A root directory for the CA.
A name of your choice. For example,
devCA
A subdirectory to store the CA’s private key
private
For example, devCA/private
A subdirectory to store new certificates issued by the
CA
certs
For example, devCA/certs
A subdirectory to store the new certificates in an
unencrypted format
newcerts
For example,
devCA/newcerts
2
3
In the root directory for the CA, use a text editor to create the following
files:
Filename
Description
serial (no
extension)
Contains the serial number for the next certificate. When you create
the file, you must add the serial number for the first certificate. For
example, 01.
index.txt
Used as a database to track certificates that have been issued.
Depending on your platform, do one of the following:
•
UNIX/Linux: Open a terminal window, and navigate to the location
where OpenSSL is installed.
The default installation folder may depend on the distribution you
* are using. For example, for Red Hat Enterprise Linux, the default
folder is /etc/pki/tls.
© 2015, MicroStrategy Inc.
Creating the directories and configuration files for your CA
217
System Administration Guide
•
4
Windows: Open a command prompt window, and navigate to the
location where OpenSSL is installed. By default, this is C:\OpenSSLWin32\bin.
Create a copy of the OpenSSL configuration file openssl.cnf, and paste
it in the root directory you created for your CA. Use a different file name,
for example, openssl.dev.cnf.
Creating the private key and root certificate for the CA
Once you have set up the files and directories for your CA, you can create a
root certificate, which is used to sign certificate requests from MicroStrategy
applications.
This procedure assumes that you have followed all the steps in Creating the
directories and configuration files for your CA, page 216.
To create the private key and root certificate for the CA
1
2
Depending on your platform, do one of the following:
•
UNIX/Linux: Open a terminal window.
•
Windows: Open a command prompt window, and navigate to the
location where OpenSSL is installed. By default, this is C:\OpenSSLWin32\bin.
To create the private key and root certificate, type the following command,
and press Enter:
openssl req -config devCApath/openssl.dev.cnf -new x509 -extensions v3_ca -keyout
devCApath/private/devCA.key -out
devCApath/certs/devCA.crt -days 1825
Substitute the values in italics based on the following:
218
•
devCApath: The root directory for your CA, which is created as part
of the procedure described in Creating the directories and
configuration files for your CA, page 216. For example,
/etc/pki/tls/devCA.
•
openssl.dev.cnf: The copy of the default OpenSSL configuration
file, created in the root directory for your CA.
•
devCA.key: The filename for the private key.
•
devCA.crt: The filename for the root certificate.
Creating the private key and root certificate for the CA
© 2015, MicroStrategy Inc.
System Administration Guide
3
You are prompted for a pass-phrase for the key, and for information about
your CA, such as your location, organization name, and so on. Use a strong
pass-phrase to secure your private key, and type the required information
for the CA. The private key and root certificate are created.
Configuring OpenSSL to use your private key and root
certificate
To start creating certificates for the MicroStrategy applications in your
development environment, you must configure OpenSSL to use your CA’s
private key and root certificate to sign certificate requests. For information on
creating certificate requests for applications, see Generating an SSL Certificate
Signing Request, page 204.
Prerequisites
This procedure assumes that you have completed the following steps:
•
Create the files and directory structure for your CA, including a copy of the
default OpenSSL configuration file, as described in Creating the directories
and configuration files for your CA, page 216.
•
Create a private key and root certificate for your CA, as described in
Creating the private key and root certificate for the CA, page 218.
To configure OpenSSL to use your CA’s root certificate
1
Use a text editor, such as Notepad, to open the copy of the OpenSSL
configuration file in your CA’s root directory. For example,
openssl.dev.cnf.
2
Scroll to the CA_default section, and edit the following values:
3
•
dir: Change this value to the root folder that you created for your CA.
For example, /etc/pki/tsl/devCA.
•
certificate: Change this value to $dir/certs/devCA.crt,
where devCA.crt is the root certificate that you created for your CA.
•
private_key: Change this value to $dir/private/devCA.key,
where devCA.key is the private key that you created for your CA.
Save the file.
© 2015, MicroStrategy Inc.
Configuring OpenSSL to use your private key and root certificate
219
System Administration Guide
Signing certificate requests using your CA
Once you have configured OpenSSL to use your CA’s private key and root
certificate, you can sign certificate requests to create the SSL certificates for
the MicroStrategy applications. The steps to create certificates follow.
Prerequisites
This procedure assumes that you have completed the following steps:
•
Create the files and directory structure for your CA, including a copy of the
default OpenSSL configuration file, as described in Creating the directories
and configuration files for your CA, page 216.
•
Create a private key and root certificate for your CA, as described in
Creating the private key and root certificate for the CA, page 218.
•
Configure OpenSSL to use the private key and root certificate, as described
in Configuring OpenSSL to use your private key and root certificate, page
219.
•
Create a certificate signing request (CSR file) for the applications that
require SSL certificates, as described in Generating an SSL Certificate
Signing Request, page 204. Copy the CSR file to the server that hosts your
CA.
To sign certificate requests using your CA
1
Depending on your platform, do one of the following:
•
UNIX/Linux: Open a terminal window, and navigate to the location
where OpenSSL is installed.
*
•
2
The default installation folder may depend on the distribution you
are using. For example, for Red Hat Enterprise Linux, the default
folder is /etc/pki/tls.
Windows: Open a command prompt window, and navigate to the
location where OpenSSL is installed. By default, this is C:\OpenSSLWin32\bin.
Type the following command, and press Enter:
openssl ca -config devCApath/openssl.dev.cnf -policy
policy_anything -out devCApath/certs/mstrapp.crt infiles CSRpath/mstrapp.csr
Substitute the values in italics based on the following:
220
Signing certificate requests using your CA
© 2015, MicroStrategy Inc.
System Administration Guide
•
devCApath: The root directory for your CA, which is created as part
of the procedure described in Creating the directories and
configuration files for your CA, page 216. For example,
/etc/pki/tls/devCA.
•
openssl.dev.cnf: The OpenSSL configuration file for your CA,
configured to use your CA’s private key and root certificate, as
described in Configuring OpenSSL to use your private key and root
certificate, page 219.
•
mstrapp.crt: The filename for the certificate to be generated for the
MicroStrategy application.
•
CSRpath: The folder where the certificate signing request is stored.
•
mstrapp.csr: The certificate signing request for the MicroStrategy
application.
The certificate is generated, and is stored in the certs folder.
3
Copy the generated certificate to the machine where the MicroStrategy
application is hosted.
4
Repeat this procedure for all MicroStrategy applications that require SSL
certificates.
© 2015, MicroStrategy Inc.
Signing certificate requests using your CA
221
System Administration Guide
222
Signing certificate requests using your CA
© 2015, MicroStrategy Inc.
5
MANAGING YOUR LICENSES
Introduction
As a system administrator, it is important that you manage your
MicroStrategy product licenses to maintain license compliance. Managing your
licenses can also help you take full advantage of your licenses. For example,
you might have a CPU-based Intelligence Server license for four CPUs, but
only be using two CPUs. An audit of your licenses can alert you to this issue
and you can then modify your setup so that you use all four of your licensed
CPUs.
This chapter covers how to manage the licenses involved in your MicroStrategy
system. Topics include:
•
Managing and verifying your licenses, page 223
•
Auditing and updating licenses, page 227
•
Updating CPU affinity, page 231
Managing and verifying your licenses
MicroStrategy licenses are managed differently according to the license type
that is purchased. Refer to your MicroStrategy contract and any accompanying
© 2015, MicroStrategy Inc.
223
System Administration Guide
contract documentation for descriptions of the different MicroStrategy license
types.
MicroStrategy uses two main categories of licenses:
•
Named User licenses, page 224, in which the number of users with access
to specific functionality are restricted
•
CPU licenses, page 226, in which the number and speed of the CPUs used
by MicroStrategy server products are restricted
MicroStrategy License Manager can assist you in administering your
MicroStrategy licenses. For information about License Manager, see Using
License Manager, page 227.
*
When you obtain additional licenses from MicroStrategy, use License
Manager to update your license information. For details, see Updating
your license, page 230.
Named User licenses
In a Named User licensing scheme, the privileges given to users and groups
determine what licenses are assigned to users and groups. Intelligence Server
monitors the number of users in your MicroStrategy system with each
privilege, and compares that to the number of available licenses.
For example, the Web Use Filter Editor privilege is a Web Professional
privilege. If you assign this privilege to User1, then Intelligence Server grants a
Web Professional license to User1. If you only have one Web Professional
license in your system and you assign any Web Professional privilege, for
example Web Edit Drilling And Links, to User2, Intelligence Server displays an
error message when any user attempts to log in to MicroStrategy Web.
The Administrator user that is created with the repository is not
* considered in the licensed user count.
To fix this problem, you can either change the user privileges to match the
number of licenses you have, or you can obtain additional licenses from
MicroStrategy. License Manager can determine which users are causing the
metadata to exceed your licenses and which privileges for those users are
causing each user to be classified as a particular license type (see Using
License Manager, page 227).
For more information about the privileges associated with each license type,
see the List of Privileges chapter in the Supplemental Reference for System
Administration. Each privilege group has an introduction indicating any license
that the privileges in that group are associated with. Users without any
product-based privileges are listed in License Manager in the group Users
224
Named User licenses
© 2015, MicroStrategy Inc.
System Administration Guide
without license association, and are not counted against any MicroStrategy
licenses.
Note the following:
*•
•
Privileges that relate to OLAP Services, Report Services, and
Distribution Services licenses are present in multiple privilege groups.
These privileges are marked with asterisks, and are listed at the top of
each group’s list of privileges.
Only users who have the Use Developer privilege in the Analyst group
are granted Analyst or Developer licenses. Users who do not have the
Use Developer privilege are not granted either of these licenses, even if
they have all other privileges from these privilege groups.
Verifying Named User licenses
To verify your Named User licenses, Intelligence Server scans the metadata
repository daily for the number of users fitting each Named User license type.
If the number of licenses for a given type has been exceeded, an error message
is displayed when a user logs in to a MicroStrategy product. Contact your
MicroStrategy account executive to increase your number of Named User
licenses. For detailed information on the effects of being out of compliance
with your licenses, see Effects of being out of compliance with your licenses,
page 226.
For steps to manually verify your Named User licenses using License Manager,
see Auditing your system for the proper licenses, page 229.
You can configure the time of day that Intelligence Server verifies your Named
User licenses.
To configure the time when Named User licenses are verified
1
In Developer, right-click a project source and select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
2
Expand the Server category, and select Advanced.
3
Specify the time in the Time to run license check (24 hr format) field.
4
Click OK to accept any changes and close the Intelligence Server
Configuration Editor.
© 2015, MicroStrategy Inc.
Named User licenses
225
System Administration Guide
CPU licenses
When you purchase licenses in the CPU format, the system monitors the
number of CPUs being used by Intelligence Server in your implementation and
compares it to the number of licenses that you have. You cannot assign
privileges related to certain licenses if the system detects that more CPUs are
being used than are licensed. For example, this could happen if you have
MicroStrategy Web installed on two dual-processor machines (four CPUs) and
you have a license for only two CPUs.
To fix this problem, you can either use License Manager to reduce the number
of CPUs being used on a given machine so it matches the number of licenses
you have, or you can obtain additional licenses from MicroStrategy. To use
License Manager to determine the number of CPUs licensed and, if necessary,
to change the number of CPUs being used, see Using License Manager, page
227.
The ability to deploy Intelligence Server or MicroStrategy Web on specific,
selected CPUs (a subset of the total number of physical CPUs) on a given
machine is called CPU affinity. For details on setting up CPU affinity, see
Updating CPU affinity, page 231.
Verifying CPU licenses
To verify your CPU licenses, Intelligence Server scans the network to count the
number of CPUs in use by Intelligence Servers. If the number of CPU licenses
has been exceeded, an error message is displayed when a user logs in to a
MicroStrategy product. Contact your MicroStrategy account executive to
increase your number of CPU licenses. For detailed information on the effects
of being out of compliance with your licenses, see Effects of being out of
compliance with your licenses, page 226.
For steps to manually verify your CPU licenses using License Manager, see
Auditing your system for the proper licenses, page 229.
Effects of being out of compliance with your licenses
If your system is determined to be out of compliance with your licenses, an
error message is displayed any time a user accesses an administrative product,
such as the MicroStrategy Web Administrator page or the Administration icon
in Developer. This message describes the specific types of licenses that are not
in compliance and states how many days remain before Intelligence Server can
no longer be restarted. This error message is only a warning, and users can
still use the administrative product.
After the system has been out of compliance for fifteen days, an additional
error message is displayed to all users when they log into a project source,
warning them that the system is out of compliance with the available licenses.
226
CPU licenses
© 2015, MicroStrategy Inc.
System Administration Guide
This error message is only a warning, and users can still log in to the project
source.
After the system has been out of compliance for thirty days, Intelligence Server
can no longer be restarted once it is shut down. In addition, if the system is
out of compliance with Named User licenses, the privileges associated with the
out-of-compliance products are disabled in the User Editor, Group Editor, and
Security Role Editor to prevent them from being assigned to any additional
users.
Contact your MicroStrategy account executive to purchase additional licenses.
For information on how Intelligence Server verifies licenses, see Verifying
Named User licenses, page 225 and Verifying CPU licenses, page 226.
Auditing and updating licenses
Once your MicroStrategy system is in place, Intelligence Server verifies how
your system is being used in relation to licenses and users. You can use
License Manager to ensure that your system is in compliance with your
licenses.
You can check for and manage the following licensing issues:
•
More copies of a MicroStrategy product are installed and being used than
you have licenses for.
•
More users are using the system than you have licenses for.
•
More CPUs are being used with Intelligence Server than you have licenses
for.
Using License Manager
License Manager is a tool for auditing and administering your MicroStrategy
licenses and installation. You can run License Manager as a graphical user
interface (GUI) or as a command line tool, in either Windows or UNIX/Linux
environments.
In both GUI mode and command line mode, License Manager allows you to:
•
Audit your MicroStrategy products.
•
Request an Activation Code and activate your MicroStrategy installation.
•
Update your license key.
Additionally, in GUI mode License Manager allows you to:
© 2015, MicroStrategy Inc.
Using License Manager
227
System Administration Guide
•
Determine the number of product licenses in use by a specified user group.
•
Display the enabled or disabled licenses used by a particular user group for
selected products.
*
•
•
From this information, you can determine whether you have the
number of licenses that you need. You can also print a report, or create
and view a Web page with this information.
Update licenses by providing the new license key, without re-installing the
products. For example, you can:
▫
Upgrade from an evaluation edition to a standard edition.
▫
Update the number of Intelligence Server processors allowed.
▫
Update the processor speed allowed.
Activate or deactivate your MicroStrategy installation.
For more information on activating your MicroStrategy installation, see
* the MicroStrategy Installation and Configuration Guide.
•
Change the number of CPUs being used for a given MicroStrategy product,
such as Intelligence Server or MicroStrategy Web, if your licenses are
based on CPUs.
•
Trigger a license verification check after you have made any license
management changes, so the system can immediately return to normal
behavior.
•
View your machine’s configuration including hardware and operating
system information.
•
View your MicroStrategy installation history including all license keys that
have been applied.
•
View the version, edition, and expiration date of the MicroStrategy
products installed on the machine.
If the edition is not an Evaluation edition, the expiration date has a
* value of “Never.”
For detailed steps to perform all of these procedures, see the License Manager
Help (from within License Manager, press F1).
228
Using License Manager
© 2015 , MicroStrategy Inc.
System Administration Guide
To start License Manager
License Manager can be run on Windows or UNIX, in either GUI mode or
command line mode.
•
Windows GUI: From the Windows Start menu, point to All Programs,
then MicroStrategy Tools, and then select License Manager. License
Manager opens in GUI mode.
•
Windows command line: From the Start menu, select Run. Type CMD
and press ENTER. A command prompt window opens. Type malicmgr
and press ENTER. License Manager opens in command line mode, and
instructions on how to use the command line mode are displayed.
•
UNIX/Linux GUI: In a UNIX or Linux console window, browse to
<HOME_PATH> where <HOME_PATH> is the directory that you specified
as the home directory during installation. Browse to the folder bin and
type ./mstrlicmgr, then press ENTER. License Manager opens in
GUI mode.
•
UNIX/Linux command line: In a UNIX or Linux console window, browse
to <HOME_PATH> where <HOME_PATH> is the directory that you
specified as the home directory during installation. Browse to the
folder bin and type ./mstrlicmgr -console, then press ENTER.
License Manager opens in command line mode, and instructions on
how to use the command line mode are displayed.
Auditing your system for the proper licenses
License Manager counts the number of licenses based on the number of users
with at least one privilege for a given product. The Administrator user that is
created by default with the repository is not considered in the count.
To audit your system, perform the procedure below on each server machine in
your system.
Note the following:
*•
•
In rare cases, an audit can fail if your metadata is too large for the Java
Virtual Machine heap size. For steps to modify the Java Virtual
Machine heap size in your system registry settings, see MicroStrategy
Tech Notes TN6446 and TN30885.
If you are using License Manager on the physical machine on which
Intelligence Server is installed, and a three-tier project source does not
exist on that machine, you cannot log in to the server. To audit your
licenses in this case, you must first create a three-tier project source
pointing to the Intelligence Server. You can use either MicroStrategy
© 2015, MicroStrategy Inc.
Auditing your system for the proper licenses
229
System Administration Guide
Configuration Wizard or Developer's Project Source Manager to create
this project source.
To audit your MicroStrategy licenses
1
Open MicroStrategy License Manager. For instructions, see To start
License Manager, page 229.
In command line mode, the steps to audit licenses vary from those
~ below. Refer to the License Manager command line prompts to guide
you through the steps to audit licenses.
2
On the Audit tab, expand the Intelligence Server folder.
3
Double-click a project source name (PSN). A Login dialog box opens.
4
Type your MicroStrategy login and password for the selected Intelligence
Server and click Connect. If you are in compliance, a message appears
notifying you that you are in compliance with your software license
agreement. Click OK to proceed.
5
Select the Everyone group and click Audit. A folder tree of the assigned
licenses is listed in the Number of licenses pane.
Users with no product-based privileges are listed under Users without
license association.
6
Count the number of licenses per product for enabled users. Disabled users
do not count against the licensed user total, and should not be counted in
your audit.
7
To print the summary information, click Print.
For detailed information, click Report to create and view XML, HTML, and
CSV reports. You can also have the report display all privileges for each
user based on the license type. To do this, select the Show User Privileges
in Report check box.
8
Total the number of users with each license across all machines.
Updating your license
If you need to update a license and you receive a new license key from
MicroStrategy, use the License Manager to perform the upgrade. If you have
licenses based on the number of CPUs being used, you can also use the update
process to change the number of CPUs being used by a given product. For
complete details on performing an upgrade in your environment, see the
MicroStrategy Upgrade Guide.
230
Updating your license
© 2015, MicroStrategy Inc.
System Administration Guide
You must update your license key on all machines where MicroStrategy
products are installed. License Manager updates the license information for
the products that are installed on that machine.
To update a MicroStrategy license
1
Acquire a new license key from MicroStrategy.
2
Open MicroStrategy License Manager. For instructions, see To start
License Manager, page 229.
In command line mode, the steps to update your license vary from
~ those below. Refer to the License Manager command line prompts to
guide you through the steps to update your license.
3
On the License Administration tab, select the Update local license key
option and click Next.
4
Type or paste the new key in the New License Key field and click Next.
If you have one or more products that are licensed based on CPU usage,
* the Upgrade window opens, showing the maximum number of CPUs
each product is licensed to use on that machine. You can change these
numbers to fit your license agreement. For example, if you purchase a
license that allows more CPUs to be used, you can increase the number
of CPUs being used by a product.
5
The results of the upgrade are shown in the Upgrade Results dialog box.
License Manager can automatically request an Activation Code for your
license after you update.
6
If you have updated your license information, restart Intelligence Server
after the update. This allows the system to recognize the license key update
and system behavior can return to normal.
Updating CPU affinity
Depending on the number of CPU-based licenses you purchase, you can have
multiple processors (CPUs) running Intelligence Server and MicroStrategy
Web. The ability to deploy Intelligence Server or MicroStrategy Web on
specific, selected CPUs (a subset of the total number of physical CPUs) on a
given machine is called CPU affinity (or processor affinity). As part of the
© 2015, MicroStrategy Inc.
Updating your license
231
System Administration Guide
installation process you must provide the number of processors to be used by
Intelligence Server or MicroStrategy Web on that machine.
CPU affinity for Intelligence Server on Windows
Upon installation, if the target machine contains more than one physical
processor and the MicroStrategy license key allows more than one CPU to run
Intelligence Server, you are prompted to provide the number of CPUs to be
deployed. The upper limit is either the number of licensed CPUs or the
physical CPU count, whichever is lower.
After installation you can specify CPU affinity through the MicroStrategy
Service Manager. This requires administrator privileges on the target machine.
To change CPU affinity settings in Service Manager
1
On the machine whose CPU affinity you want to change, from the Windows
Start menu, point to All Programs, then MicroStrategy Tools, and then
select Service Manager. Service Manager opens.
2
From the Service drop-down list, select MicroStrategy Intelligence Server.
3
Click Options. The Service Options dialog box opens.
4
Select the Intelligence Server Options tab.
5
In the Processor Usage section, select which processors Intelligence Server
should use.
6
Click OK. The Service Options dialog box closes and CPU affinity has been
changed.
CPU affinity for Intelligence Server on UNIX/Linux
CPU affinity behaves in a similar manner in both Windows and UNIX/Linux
environments. This section describes details for setting up CPU affinity for
running Intelligence Server Universal Edition in a UNIX or Linux environment.
Information specific to AIX and Solaris is also discussed.
The ability to set CPU affinity on UNIX/Linux requires special system-level
privileges. MicroStrategy must be run under the root UNIX/Linux account,
otherwise an error message appears.
If the target machine contains more than one physical processor and the
MicroStrategy license key allows more than one CPU to run Intelligence
Server Universal Edition, you are prompted to provide the number of CPUs to
232
CPU affinity for Intelligence Server on Windows
© 2015, MicroStrategy Inc.
System Administration Guide
be deployed. The upper limit is either the number of licensed CPUs or the
physical CPU count, whichever is lower.
Each UNIX/Linux platform exposes its own set of functionality to bind
processes to processors. However, UNIX/Linux also provides commands to
easily change the processor assignments. As a result, Intelligence Server
periodically checks its own CPU affinity and takes steps whenever the CPU
affinity mask does not match the overall CPU licensing. Whenever your
licenses do not match your deployment, CPU affinity is automatically adjusted
to the number of CPUs necessary to be accurate again.
This automatic adjustment for CPU affinity attempts to apply the user’s
specified CPU affinity value when it adjusts the system, but it may not always
be able to do so depending on the availability of processors. For example, if
you own two CPU licenses and CPU affinity is manually set to use Processor 1
and Processor 2, the CPU affinity adjustment may reset CPU usage to
Processor 0 and Processor 1 when the system is automatically adjusted.
Under HP-UX, Processor 0 is always grayed out and cannot be assigned to
* Intelligence Server. This is because in HP-UX, Processor 0 is always
assigned to the default processor set, and cannot be reassigned to any other
user-created processor set. Intelligence Server uses processor sets to
implement multi-CPU Processor Affinity. The only times Intelligence
Server can use Processor 0 are when it is set to “all CPUs,” or when it is
set to “one CPU.” For additional detail about processor sets in HP-UX, see
Processor sets, page 234.
Changing CPU affinity in UNIX/Linux
You can specify CPU affinity either through the MicroStrategy Service
Manager, or by modifying Intelligence Server options. If you want to view and
modify Intelligence Server’s options, it must be registered as a service. You can
register Intelligence Server Universal as a service using the Configuration
Wizard by selecting the Register Intelligence Server as a Service option;
alternatively, you can follow the procedure below.
To set up Intelligence Server to run as a service
1
Navigate to the bin directory in the installation location.
2
Type the following command:
mstrctl -s IntelligenceServerName rs
Whenever you change the CPU affinity, you must restart the machine.
© 2015, MicroStrategy Inc.
CPU affinity for Intelligence Server on UNIX/Linux
233
System Administration Guide
CPU affinity implementation on AIX
This section describes resource sets, Intelligence Server startup and shutdown,
and using a non-root account.
Resource sets
On an AIX system, CPU affinity is implemented using resource sets. A resource
set is a logical structure that contains a list of specific CPUs that will be used.
Processors are bound to a resource set. Resource sets do not define exclusive
use of a resource; the same CPU can be part of several different resource sets.
Intelligence Server startup and shutdown
When Intelligence Server starts, it creates a resource set, assigns CPUs to that
resource set, and binds the server process to that resource set. Resource sets
exist only for the lifetime of the process. If the process shuts down, whether
normally or unexpectedly, the resource set is cleaned from the system.
Using a non-root account
While the root account is mandatory for installing MicroStrategy with a CPUbased license, it can be possible to run Intelligence Server as a non-root
account. If this occurs, you must manually define the resource set to be used
by Intelligence Server because the automatic adjustments to correct CPU
affinity cannot be made.
For example, consider a scenario in which Intelligence Server only has a
license for three CPUs, and is running from a non-root account. If the user
assigns a resource set to Intelligence Server that has five CPUs, Intelligence
Server attempts to use all five CPUs because it cannot restrict itself to the
required three CPUs when running under a non-root account. This results in
an out-of-compliance situation.
To fix this problem, either run Intelligence Server from a root account, or do
not assign a resource set to Intelligence Server that contains more CPUs than
your CPU license allows.
CPU affinity implementation on Solaris and HP-UX
This section describes processor sets, Intelligence Server startup and
shutdown, and how to specify a processor set.
Processor sets
On a Solaris or HP-UX system, multi-CPU affinity is implemented using
processor set binding. A processor set is a collection of processors. A process
234
CPU affinity for Intelligence Server on UNIX/Linux
© 2015, MicroStrategy Inc.
System Administration Guide
assigned to a processor set can only use the CPUs specified for that processor
set. Additionally, a processor set takes exclusive ownership of the CPUs
assigned to it. Only the processes assigned to the processor set can use the
processor set’s CPUs. Other processes are not allowed to use any of these
CPUs.
A processor set exists beyond the lifetime of the process that created it.
Therefore, when a process is shut down, the process must delete the processor
set that was created. For example, if a process creates a processor set with
three CPUs and the process unexpectedly terminates without deleting the
processor set it created, the three CPUs cannot be utilized by any other
process until the system is rebooted or the processor set is manually deleted.
Whenever the CPU license is limited to a single CPU, Intelligence Server
* dynamically binds the process to the selected CPU without creating a
processor set.
Intelligence Server startup and shutdown
When Intelligence Server starts, it creates a processor set, assigns CPUs to
that processor set, and binds the server process to that processor set.
However, Intelligence Server creates processor sets only on machines that
have more than two physical CPUs and only when the number of physical
CPUs is greater than the number of CPUs licensed. For example, if Intelligence
Server licensed for two CPUs is installed on a four-CPU machine, a processor
set containing two CPUs is created. However, if Intelligence Server licensed for
four CPUs is installed on the same machine, the processor set is not created,
because the number of physical CPUs is not greater than the number of
licensed CPUs.
Intelligence Server deletes the processor set before shutting down so that the
related processes do not remain locked. If Intelligence Server terminates
unexpectedly, when restarted it performs a cleanup of the processor set it had
created. However, if Intelligence Server is not restarted immediately after
termination, you may need to manually delete the processor set so the CPUs
are free to be used by other applications.
Specifying a processor set
You can specify an existing processor set for Intelligence Server to use. To do
so, type the following command:
Prset -e <processorsetID> mstrsvr
Intelligence Server may automatically modify the existing processor set to
keep your licenses mapped properly, if necessary.
For example, consider a scenario where an existing processor set is comprised
of Processor 0, Processor 1, and Processor 2. A CPU-based license for
© 2015, MicroStrategy Inc.
CPU affinity for Intelligence Server on UNIX/Linux
235
System Administration Guide
Intelligence Server allows two physical CPUs to be used. Intelligence Server is
installed and configured to use this existing processor set at startup. In this
scenario, Intelligence Server modifies the existing processor set to use only
two physical CPUs so that it matches its license. Intelligence Server does not
create a new processor set, and when it shuts down it does not delete this
processor set.
CPU affinity for MicroStrategy Web
If you have CPU-based licenses for MicroStrategy Web, the CPU affinity
feature allows you to match your CPUs and licenses by choosing which
processors MicroStrategy Web uses on a given machine.
This feature is only available in the ASP.NET version of MicroStrategy
~ Web. It is not implemented in MicroStrategy Web Universal.
This section describes settings that may interact with CPU affinity that you
must consider, and provides steps to update CPU affinity in your environment.
CPU affinity and IIS
Before configuring CPU affinity for MicroStrategy Web, you should understand
how the CPU affinity setting behaves on different configurations of IIS, and
how it interacts with other IIS settings such as the Web Garden mode.
IIS versions
CPU affinity can be configured on machines running IIS 6.0 or 7.0. The overall
behavior depends on how IIS is configured. The following cases are considered:
236
•
Worker process isolation mode: In this mode, the CPU affinity setting is
applied at the application pool level. When MicroStrategy Web CPU
affinity is enabled, it is applied to all ASP.NET applications running in the
same application pool. By default, MicroStrategy Web runs in its own
application pool. The CPU affinity setting is shared by all instances of
MicroStrategy Web on a given machine. Worker process isolation mode is
the default mode of operation on IIS 6.0 when the machine has not been
upgraded from an older version of Windows.
•
IIS 5.0 compatibility mode: In this mode, all ASP.NET applications run in
the same process. This means that when MicroStrategy Web CPU affinity is
enabled, it is applied to all ASP.NET applications running on the Web
server machine. A warning is displayed before installation or before the
CPU affinity tool (described below) attempts to set the CPU affinity on a
machine with IIS running in IIS 5.0 compatibility mode.
CPU affinity for MicroStrategy Web
© 2015, MicroStrategy Inc.
System Administration Guide
*
This is the default mode of operation when the machine has been
upgraded from an older version of Windows.
Web Garden mode
Both IIS 6.0 and IIS 7.0 support a "Web Garden" mode, in which IIS creates
some number of processes, each with affinity to a single CPU, instead of
creating a single process that uses all available CPUs. The administrator
specifies the total number of CPUs that are used. The Web Garden settings can
interact with and affect MicroStrategy CPU affinity.
The Web Garden setting should not be used with MicroStrategy Web. At
~ runtime, the MicroStrategy Web CPU affinity setting is applied after IIS
sets the CPU affinity for the Web Garden feature. Using these settings
together can produce unintended results.
In both IIS 6.0 and IIS 7.0, the Web Garden feature is disabled by default.
CPU affinity interaction depends on how IIS is configured, as described below:
•
In worker process isolation mode, the Web Garden setting is applied at the
application pool level. You specify the number of CPUs to be used. A given
number of CPUs are specified, and IIS creates that number of w3wp.exe
instances. Each of the instances runs all of the ASP.NET applications
associated with the application pool. The Web Garden feature is configured
through the application pool settings. For more information, refer to your
IIS documentation.
•
In IIS 5.0 compatibility mode, a single setting affects all ASP.NET
applications. The Web Garden feature is enabled or disabled using the
WebGarden and cpuMask attributes under the processModel node in
machine.config. A given number of CPUs are specified in the mask, and IIS
creates that number of aspnet_wp.exe instances. Each of these instances
runs the ASP.NET applications. For more information, refer to your IIS
documentation.
IIS provides metabase properties (SMPAffinitized and
~ SMPProcessorAffinityMask) to determine the CPU affinity for a given
application pool. Do not use these settings in conjunction with the
MicroStrategy Web CPU affinity setting.
Updating CPU affinity changes
After MicroStrategy Web is installed in your environment, you can update
MicroStrategy Web's CPU affinity using a tool called MAWebAff.exe. This
tool is located in the root directory of the MicroStrategy Web application,
which is located by default at C:\Program Files (x86)
© 2015, MicroStrategy Inc.
CPU affinity for MicroStrategy Web
237
System Administration Guide
\MicroStrategy\Web ASPx. The MAWebAff.exe tool allows you to
choose the physical CPUs MicroStrategy Web can use. The number of CPUs
that can be used depends on the limit specified by the license.
The MAWebAff.exe tool is shown below:
The MAWebAff.exe tool lists each physical CPU on a machine. You can add
or remove CPUs or disable CPU affinity using the associated check boxes.
Clearing all check boxes prevents the MicroStrategy Web CPU affinity setting
from overriding any IIS-related CPU affinity settings.
To update CPU affinity
1
Double-click the MAWebAff.exe tool to open the CPU affinity tool.
2
Select or clear the check boxes for each processor as desired.
3
Click Apply to apply the settings without closing the tool, or click OK to
apply settings and close the tool.
Clicking Exit closes the tool without saving any settings.
*
4 Restart IIS to apply your CPU affinity changes.
238
CPU affinity for MicroStrategy Web
© 2015, MicroStrategy Inc.
6
MANAGING YOUR PROJECTS
Introduction
In a MicroStrategy system, a project is the environment in which reporting is
done. A project:
•
Determines the set of data warehouse tables to be used, and therefore the
set of data available to be analyzed.
•
Contains all schema objects used to interpret the data in those tables.
Schema objects include objects such as facts, attributes, and hierarchies.
•
Contains all application objects used to create reports and analyze the data.
Application objects include objects such as reports, metrics, and filters.
•
Defines the security scheme for the user community that accesses these
objects. Security objects include objects such as security roles, privileges,
and access control lists.
The recommended methodology and tools for managing projects in the
MicroStrategy system include:
•
The project life cycle, page 240
•
Implementing the recommended life cycle, page 244
•
Duplicating a project, page 245
•
Updating projects with new objects, page 251
•
Copying objects between projects: Object Manager, page 254
© 2015, MicroStrategy Inc.
239
System Administration Guide
•
Merging projects to synchronize objects, page 290
•
Comparing and tracking projects, page 298
•
Deleting unused schema objects: managed objects, page 302
For information about creating a project, creating attributes and facts, building
a logical data model, and other project design tasks, see the MicroStrategy
Project Design Guide.
The project life cycle
A MicroStrategy business intelligence application consists of many objects
within projects. These objects are ultimately used to create reports that
display data to the end user. As in other software systems, these objects
should be developed and tested before they can be used in a production
system. We call this process the project life cycle. This section discusses
several project life cycle scenarios and the tools you can use to implement
them.
*
In many cases, an application consists of a single project delivered to an
end user. MicroStrategy OEM developers may choose to bundle several
projects together to make a single application.
•
For a description of the recommended scenario, see Recommended
scenario: Development, test, and production, page 240
•
For a real-life scenario, see Real-life scenario: New version from a project
developer, page 243
•
For details on how to implement the project life cycle in your
MicroStrategy environment, see Implementing the recommended life cycle,
page 244
Recommended scenario: Development, test, and
production
This commonly used scenario is the project life cycle that MicroStrategy
recommends you use as you develop your projects. In this scenario, you
typically use three environments: development, test, and production. Each
environment contains a MicroStrategy project.
MicroStrategy recommends that if you want to copy objects between two
projects, such as from the development project to the test project, those
projects should be related. Two projects are considered to be related if one
240
Recommended scenario: Development, test, and production
© 2015, MicroStrategy Inc.
System Administration Guide
was originally a duplicate of the other. To establish different development,
test, and production projects, for example, you can create the test project by
copying the development project, and you can create the production project by
copying the test project. All three of these projects are related to each other.
For more information about duplicating a project, see Duplicating a project,
page 245.
This scenario is shown in the diagram below in which objects iterate between
the development and test projects until they are ready for general users. Once
ready, they are promoted to the production project.
The development project
In the development environment project, you create objects. This may be a
project in which developers work. They think about the design of the whole
system as they create the project’s schema and application objects. For
detailed instructions on how to design a project schema and create application
objects, see the MicroStrategy Project Design Guide.
The test project
Once the objects’ definitions have stabilized, you move them to a test project
that a wider set of people can use for testing. You may have people run
through scripts or typical usage scenarios that users at your organization
commonly perform. The testers look for accuracy (are the numbers in the
reports correct?), stability (did the objects work? do their dependent objects
work?), and performance (did the objects work efficiently, not producing
overload on the data warehouse?).
In this test environment, you want the project to initially connect to a
development data warehouse for initial testing. Later, for more stringent
testing, connect the test project to the production data warehouse. If objects
need further work, they are changed in the development project and recopied
to the test project, but not changed in the test project.
The production project
After the objects have been tested and shown to be ready for use in a system
accessible to all users, you copy them into the production project. This is the
project used by most of the people in your company. It provides up-to-date
reports and tracks various business objectives.
© 2015, MicroStrategy Inc.
Recommended scenario: Development, test, and production
241
System Administration Guide
Implementing the recommended scenario
When migrating changes into a testing or development environment, be as
thorough as possible. Carefully consider how your business users will access
and use their application, reports, and dashboards on a daily basis. Anticipate
the needs of your business users, and test every type of scenario before
officially migrating to a production environment.
To set up the development, test, and production projects so that they all have
related schemas, you need to first create the development project. For
instructions on how to create a project, see the MicroStrategy Project Design
Guide. Once the development project has been created, you can duplicate it to
create the test and production projects using the Project Duplication Wizard.
For detailed information about the Project Duplication Wizard, see
Duplicating a project, page 245.
Once the projects have been created, you can migrate specific objects between
them via Object Manager. For example, after a new metric has been created in
the development project, you can copy it to the test project. For detailed
information about Object Manager, see Copying objects between projects:
Object Manager, page 254.
You can also merge two related projects with the Project Merge Wizard. This
is useful when you have a large number of objects to copy. The Project Merge
Wizard copies all the objects in a given project to another project. For an
example of a situation in which you would want to use the Project Merge
Wizard, see Real-life scenario: New version from a project developer, page
243. For detailed information about Project Merge, see Merging projects to
synchronize objects, page 290.
*
To help you decide whether you should use Object Manager or Project
merge, see Comparing Project Merge to Object Manager, page 252.
The Project Comparison Wizard can help you determine what objects in a
project have changed since your last update. You can also save the results of
search objects and use those searches to track the changes in your projects.
For detailed information about the Project Comparison Wizard, see
Comparing and tracking projects, page 298. For instructions on how to use
search objects to track changes in a project, see Tracking your projects with
the Search Export feature, page 300.
Integrity Manager helps you ensure that your changes have not caused any
problems with your reports. Integrity Manager executes some or all of the
reports in a project, and can compare them against another project or a
previously established baseline. For detailed information about Integrity
Manager, see Chapter 16, Verifying Reports and Documents with Integrity
Manager.
242
Recommended scenario: Development, test, and production
© 2015, MicroStrategy Inc.
System Administration Guide
Real-life scenario: New version from a project
developer
In this scenario, you have initially purchased a project from a vendor whose
products are specialized for analyzing sales data. This is project version 1. Over
the course of time, your developers have customized objects in the project,
resulting in what you called version 1.1 and later, version 1.2., and so on. Now
you have purchased version 2 of the project from the same vendor, and you
wish to merge the new (Version 2) project with your existing (Version 1.2)
project.
MicroStrategy encourages vendors in these situations to include in the
* installation of version 2 an “automatic” upgrade to the project using
Project Merge. In this way the vendor, rather than the user or purchaser,
can configure the rules for this project merge. For information about
executing Project Merge without user input, see Running Project Merge
from the command line, page 294.
This combination of the two projects creates Project version 2.1, as shown in
the diagram below.
The vendor’s new Version 2 project has new objects that are not in yours,
which you feel confident in moving over. But some of the objects in the
Version 2 project may conflict with objects that you had customized in the
Version 1.2 project. How do you determine which of the Version 2 objects you
want move into your system, or which of your Version 1.2 objects to modify?
© 2015, MicroStrategy Inc.
Real-life scenario: New version from a project developer
243
System Administration Guide
You could perform this merge object-by-object and migrate them manually
using Object Manager, but this will be time-consuming if the project is large. It
may be more efficient to use the Project Merge tool. With this tool, you can
define rules for merging projects that help you identify conflicting objects and
handle them a certain way. Project Merge then applies those rules while
merging the projects. For more information about using the MicroStrategy
Project Merge tool, see Merging projects to synchronize objects, page 290.
Implementing the recommended life cycle
The following section provides a high-level, simplified overview of the
procedure for implementing the recommended project life cycle in your
company’s MicroStrategy environment. This is a simplified version of the
workflow you are likely to see at your organization. However, you should be
able to apply the basic principles to your specific situation.
1
Create the development project.
Creating the development project involves setting up the database
connections and project schema, configuring user security, and building the
initial schema and application objects. For information on creating a
project, see the MicroStrategy Project Design Guide.
2
Create the test and production projects by duplicating the development
project.
MicroStrategy recommends that you duplicate the development project to
create the test and production projects, rather than creating them
separately. Duplicating ensures that all three projects have related
schemas, enabling you to safely use Object Manager or Project Merge to
copy objects between the projects.
For instructions on how to duplicate a project, see Duplicating a project,
page 245.
3
Create objects in the development project.
In the recommended scenario, all objects (attributes, metrics, reports) are
created in the development project, and then migrated to the other
projects. For more information about the development project, see The
development project, page 241.
For instructions on creating schema objects, see the MicroStrategy Project
Design Guide. For instructions on creating application objects, see the
MicroStrategy Basic Reporting Guide and MicroStrategy Advanced
Reporting Guide.
4
244
Migrate objects from the development project to the test project.
Real-life scenario: New version from a project developer
© 2015, MicroStrategy Inc.
System Administration Guide
Once the objects have been created and are relatively stable, they can be
migrated to the test project for testing. For instructions on how to migrate
objects, see Updating projects with new objects, page 251.
Depending on the number of objects you have created or changed, you can
use either Object Manager or Project Merge to copy the objects from the
development project to the test project. For a comparison of the two tools,
see Comparing Project Merge to Object Manager, page 252. For a tool to
determine what objects have changed, see Comparing and tracking
projects, page 298.
5
Test the new objects.
Testing involves making sure that the new objects produce the expected
results, do not cause data errors, and do not put undue strain on the data
warehouse. If the objects are found to contain errors, these errors are
reported to the development team so that they can be fixed and tested
again. For more information about the test project, see The test project,
page 241.
Integrity Manager is an invaluable tool in testing whether new objects
cause reports to generate different results. For detailed information about
Integrity Manager, see Chapter 16, Verifying Reports and Documents with
Integrity Manager.
6
Migrate objects from the test project to the production project.
Once the objects have been thoroughly tested, they can be migrated to the
production project and put into full use. For instructions on how to
migrate objects, see Updating projects with new objects, page 251.
7
Repeat steps 3 through 6 as necessary.
The project life cycle does not end with the first migration of new objects
into the production project. A developer may come up with a new way to
use an attribute in a metric, or a manager may request a specific new
report. These objects pass through the project life cycle in the same way as
the project’s initial objects.
Duplicating a project
Duplicating a project is an important part of the application life cycle. If you
want to copy objects between two projects, MicroStrategy recommends that
the projects have related schemas. This means that one must have originally
been a duplicate of the other, or both must have been duplicates of a third
project.
© 2015, MicroStrategy Inc.
Real-life scenario: New version from a project developer
245
System Administration Guide
*
Autostyles, which give a uniform appearance to reports, can be freely
moved between projects regardless of whether their schemas are related.
For instructions on migrating autostyles between projects, see the
Advanced Reporting Guide.
Project duplication is done using the Project Duplication Wizard. For detailed
information about the duplication process, including step-by-step instructions,
see The Project Duplication Wizard, page 247.
*
To migrate a project from a Microsoft Access database to another database
platform, you must use the Project Mover Wizard. For detailed
information about this migration, see Migrating a project to a new
database platform, page 249.
You can duplicate a MicroStrategy project in one of the following ways:
•
From a three-tier (server) project source to a three-tier (server) project
source
•
From a three-tier (server) project source to a two-tier (direct) project
source
•
From a two-tier (direct) project source to a two-tier (direct) project source
•
From a two-tier (direct) project source to a three-tier (server) project
source
A server (three-tier) project source is connected to an Intelligence Server, and
has the full range of administrative options available. A direct (two-tier)
project source is not connected to an Intelligence Server. For more
information on three-tier and two-tier project sources, see the MicroStrategy
Project Design Guide.
~
Do not refresh the warehouse catalog in the destination project. Refresh
the warehouse catalog in the source project, and then use Object Manager
to move the updated objects into the destination project. For information
about the warehouse catalog, see the Optimizing and Maintaining your
Project chapter in the MicroStrategy Project Design Guide.
What objects are duplicated with a project?
When you duplicate a project, all schema objects (attributes, facts, hierarchies,
and transformations) are duplicated. By default all application objects (reports,
documents, metrics, and so forth) contained in the project are also duplicated.
If you are copying a project to another project source, you have the option to
duplicate configuration objects as well. Specifically:
246
What objects are duplicated with a project?
© 2015, MicroStrategy Inc.
System Administration Guide
•
You can choose whether to duplicate all configuration objects, or only the
objects used by the project.
•
You can choose to duplicate all users and groups, only the users and groups
used by the project, no users and groups, or a custom selection of users
and groups.
•
You can choose to duplicate user, contact, and subscription information.
For each type of configuration object (user/group, security role, schedule,
contact/contact group, database connection/instance, database login) you must
choose whether to duplicate the object if it already exists in the destination
project source metadata. For users/groups and security roles, you can also
choose to merge the privileges of the source and destination versions.
Duplicating projects in multiple languages
When you duplicate a project that contains warehouse data in multiple
languages, you have the option of duplicating all, some, or none of those
languages. In addition, you can select the new default language for the project.
Whenever you duplicate a project or update the metadata, a language check
ensures that the language settings in the CURRENT_USER registry key, the
LOCAL_MACHINE registry key, and the Project locale property all match
before an update takes place. The system performs the following checks:
•
In a direct (two-tier) configuration, without an Intelligence Server, the
system checks that the language under the LOCAL_MACHINE registry key
matches the language under the CURRENT_USER registry key.
•
In a server (three-tier) configuration, with an Intelligence Server, the
system checks that the language under the CURRENT_USER registry key
on the client machine matches the language under the LOCAL_MACHINE
registry key on the server machine.
The MicroStrategy interface obtains the language information from the
CURRENT_USER registry key and the server obtains the language information
from the LOCAL_MACHINE registry key. This can lead to inconsistencies in
the language display. The language check prevents these inconsistencies and
ensures that the language display is consistent across the interface.
The internationalization settings in Object Manager allow you to create related
projects in different languages. For more information on this process, see
Copying objects between projects in different languages, page 265.
The Project Duplication Wizard
You should always use the Project Duplication Wizard to duplicate your
projects. This ensures that all project objects are duplicated properly, and that
© 2015, MicroStrategy Inc.
Duplicating projects in multiple languages
247
System Administration Guide
the new project’s schema is identical to the source project’s schema.
To duplicate a project, you must have the Bypass All Object Security Access
* Checks privilege for that project. In addition, you must have the Create
Schema Objects privilege for the target project source.
The following high-level procedure provides an overview of what the Project
Duplication Wizard does. For an explanation of the information required at
any given page in the wizard, see the Help (from the wizard, click Help, or
press F1).
High-level steps to duplicate a project with the Project Duplication
Wizard
1
From Object Manager select the Project menu (or from Developer select
the Schema menu), then select Duplicate Project. The Project Duplication
Wizard opens.
2
Specify the project source and project information that you are copying
from (the source).
3
Specify the project source and project information that you are copying to
(the destination).
4
Indicate what types of objects to copy.
5
Specify whether to keep or merge configuration object properties if these
already exist in the destination project source. For example, if properties
such as password expiration and so on are different by default between the
project sources, which set of properties do you want to use?
6
Specify whether you wish to see the event messages as they happen and, if
so, what types. Also specify whether to create log files and, if so, what
types of events to log, and where to locate the log files. By default Project
Duplicator shows you error messages as they occur, and logs most events
to a text file. This log file is created by default in C:\Program Files
(x86)\Common Files\MicroStrategy\.
Scheduling project duplication
At the end of the Project Duplication Wizard, you are given the option of
saving your settings in an XML file. You can load the settings from this file
later to speed up the project duplication process. The settings can be loaded at
the beginning of the Project Duplication Wizard.
You can also use the settings file to run the wizard in command-line mode. The
Project Duplication Wizard command line interface enables you to duplicate a
project without having to load the graphical interface, or to schedule a
248
The Project Duplication Wizard
© 2015, MicroStrategy Inc.
System Administration Guide
duplication to run at a specific time. For example, you may want to run the
project duplication in the evening, when the load on Intelligence Server is
lessened. You can create an XML settings file, and then use the Windows AT
command or the Unix scheduler to schedule the duplication to take place at
night.
To duplicate a project from the command line
After saving the settings from the Project Duplication Wizard, invoke the
Project Duplication Wizard executable ProjectDuplicate.exe. By default
this executable is located in C:\Program Files (x86)\Common
Files\MicroStrategy.
The syntax is:
ProjectDuplicate.exe -f Path\XMLFilename [-sp
SourcePassword] [-dp DestinationPassword] [-sup] [-md] [dn OverwriteName]
where:
•
Path is the path to the saved XML settings file.
•
XMLFilename is the name of the saved XML settings file.
•
SourcePassword is the password for the source project’s project source.
•
TargetPassword is the password for the destination project’s project
source.
•
-sup indicates that feedback messages will be suppressed (silent mode).
•
-md indicates that the metadata of the destination project source will be
updated if it is older than the source project source’s metadata.
•
-dn OverwriteName specifies the name of the destination project. This
overrides the name specified in the XML settings file.
For information on the syntax for the Windows AT command or a UNIX
scheduler, see the documentation for your operating system.
Migrating a project to a new database platform
The Project Mover Wizard guides you through the process of migrating a
MicroStrategy project from a Microsoft Access database to a new database
platform. This can be useful for creating and testing a new project before it is
placed in the production database.
For example, a business analyst has an idea for a new business intelligence
application using MicroStrategy. The analyst needs to create a proof-of-concept
© 2015, MicroStrategy Inc.
Migrating a project to a new database platform
249
System Administration Guide
project to show her manager. The project will eventually be used in the
development and production environment, but the system administrator might
decide that it is not ideal to create the demo project in the production
database. Instead the analyst puts the project together on her laptop, using a
local Microsoft Access database. Once she demonstrates the project and
receives approval for it, the administrator can use the Project Mover Wizard
to move the project from the laptop’s Access database into the development
environment’s database platform.
The following high-level procedure provides an overview of what the Project
Mover Wizard does. For an explanation of the information required at any
given page in the wizard, see the Help (from the wizard, click Help, or press
F1).
Prerequisites
•
The project must be contained in a Microsoft Access database.
•
To migrate a project to a new database platform, you must have the Bypass
All Object Security Access Checks privilege for that project.
•
The source project and destination project source must be the same
version of MicroStrategy metadata. For example, if you have updated the
destination project source to the latest version of MicroStrategy, you must
also update the source project before using Project Mover to migrate it.
For information about updating a project’s metadata, see the
MicroStrategy Upgrade Guide.
To migrate a project to a different database
250
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Project Mover. The Project Mover Wizard opens.
2
Select the Microsoft Access warehouse and metadata databases that contain
the source project, and then select the source project.
3
Select any SQL scripts you want to run on the data warehouse, either
before or after project migration.
4
Select the database into which the project is to be migrated.
5
If project metadata already exists in the destination database, select
whether to append the migrated project to the existing data, or overwrite
that data.
6
Review your choices and click Finish on the Summary page of the Project
Mover Wizard. The wizard migrates your project to the new database.
Migrating a project to a new database platform
© 2015, MicroStrategy Inc.
System Administration Guide
Migrating a project automatically
In addition to accepting user input and then immediately moving a project, the
Project Mover Wizard can record your input in a response file. This file
contains all the information needed to move a project to a new database
platform, and can be later used to move a project without any additional user
input. This is especially useful for scheduling a project migration for a time
when there are not many users on the system.
To create a response file, from the first page of the Project Mover Wizard click
Advanced. On the Advanced Options page, select Generate a response file and
enter the name and location of the new response file in the text field.
To execute a response file from the Project Mover Wizard, from the first page
of the wizard click Advanced. Then select the Use Response File option and
load the response file. The Wizard opens the Summary page, which lists all the
options set by the response file. After reviewing these options, click Finish. The
Project Mover Wizard begins moving the project.
To execute a response file from the command line, you need to invoke the
Project Mover executable, demomover.exe. By default, this directory is
C:\Program Files (x86)\Common Files\Microstrategy.
The syntax is:
demomover.exe -r "File Location\Filename.ini"
where "File Location" is the path to the response file and
"Filename.ini" is the name of the response file.
Updating projects with new objects
When you create or modify an object in your development environment, you
eventually need to copy that object to the test project, and later to the
production project.
For example, a developer creates a new metric in the development project.
Once the metric is ready to be tested, it needs to be present in the test project.
You could re-create the metric in the test project based on the same
specifications, but it can be easy to miss an important setting in the metric. A
quicker and more reliable method is to use MicroStrategy Object Manager to
migrate the new metric from the development project to the test project.
Then, when the metric is ready to be rolled out to your users, you can use
Object Manager again to migrate it from the test project to the production
project.
MicroStrategy has the following tools available for updating the objects in a
project:
© 2015, MicroStrategy Inc.
Migrating a project to a new database platform
251
System Administration Guide
•
Object Manager migrates a few objects at a time. For information about
Object Manager, see Copying objects between projects: Object Manager,
page 254.
•
An update package migrates a previously specified group of objects. Update
packages are part of Object Manager. For information about update
packages, see Copying objects in a batch: Update packages, page 273.
•
Project Merge migrates all the objects in a project at once. For information
about Project Merge, see Merging projects to synchronize objects, page
290.
For a comparison of these tools, see Comparing Project Merge to Object
Manager, page 252.
Note the following:
*•
•
If you want to move or copy objects between projects, MicroStrategy
recommends that those projects have related schemas. This means that
either one project must be a duplicate of the other, or both projects
must be duplicates of a third project. For information about duplicating
projects, including instructions, see Duplicating a project, page 245.
If one of the projects is updated to a new MicroStrategy release, but
another project is not updated, you cannot move or copy objects
between the projects. You must first update the other project before
you can copy objects between the projects.
Comparing Project Merge to Object Manager
Object Manager and Project Merge are both designed for migrating objects
between projects. Both tools involve copying objects between projects in a
definite order according to object types. Which tool you should use depends on
several factors, such as how many objects you need to move at once. The
following are some of the differences between the tools:
252
•
Object Manager can move just a few objects, or just the objects in a few
folders. Project Merge moves all the objects in a project.
•
Using Object Manager to merge whole projects means moving many
objects individually or as a subset of all objects. This can be a long and
tedious task. Project Merge packages the functionality for easier use
because it moves all objects at one time.
•
Object Manager must locate the dependents of the copied objects and then
determine their differences before performing the copy operation. Project
Merge does not do a dependency search, since all the objects in the project
are to be copied.
Comparing Project Merge to Object Manager
© 2015, MicroStrategy Inc.
System Administration Guide
•
The Project Merge Wizard allows you to store merge settings and rules in
an XML file. These rules define what is copied and how conflicts are
resolved. Once they are in the XML file, you can load the rules and “replay”
them with Project Merge. This can be useful if you need to perform the
same merge on a recurring schedule. For example, if a project developer
sends you a new project version quarterly, Project Merge can make this
process easier.
•
Project Merge can be run from the command prompt in Microsoft
Windows. An added benefit of this feature is that project merges can be
scheduled using the at command in Windows and can be run silently in an
installation routine.
•
The changes to be made through Object Manager can be saved as an update
package and applied at a later time. For instructions on how to create and
use update packages, see Copying objects in a batch: Update packages,
page 273.
•
The changes to be made through an Object Manager update package can be
reversed using an undo package. For instructions on how to roll back
changes using Object Manager, see Rolling back changes: Undo packages,
page 290.
Locking projects
When you open a project in Project Merge, you automatically place a metadata
lock on the project. You also place a metadata lock on the project if you open
it in read/write mode in Object Manager, or if you create or import an update
package from the command line. For more information about read/write mode
versus read-only mode in Object Manager, see Project locking with Object
Manager, page 255.
A metadata lock prevents other MicroStrategy users from modifying any
objects in the project in Developer or MicroStrategy Web, while objects are
being copied with Object Manager or Project Merge. It also prevents other
MicroStrategy users from modifying any configuration objects, such as users or
groups, in the project source. Locking a project prevents metadata
inconsistencies.
When other users attempt to open an object in a locked project using
Developer or MicroStrategy Web, they see a message that informs them that
the project is locked because a user that opened the project first is modifying
it. Users can then choose to open the object in read-only mode or view more
details about the lock. Users can execute reports in a locked project, but the
report definition that is used is the last definition saved prior to the project
being locked.
If you lock a project by opening it in Object Manager, you can unlock the
project by right-clicking the project in Object Manager, and choosing
Disconnect from Project Source.
© 2015, MicroStrategy Inc.
Locking projects
253
System Administration Guide
*
Only the user who locked a project, or another user with the Bypass All
Object Security Access Checks and Create Configuration Objects privileges,
can unlock a project.
You can also lock or unlock a project or a configuration manually using
Developer. For detailed steps on locking and unlocking projects manually, see
the MicroStrategy Developer Help.
Command Manager scripts can be used to automate metadata lock
management. For information about Command Manager, see Chapter 15,
Automating Administrative Tasks with Command Manager. For Command
Manager syntax for managing metadata locks, see the Command Manager Help
(press F1 from within Command Manager).
Copying objects between projects: Object
Manager
MicroStrategy Object Manager can help you manage objects as they progress
through your project’s life cycle. Using Object Manager, you can copy objects
within a project or across projects.
Object Manager and Project Merge both copy multiple objects between
projects. Use Object Manager when you have only a few objects that need to be
copied. For the differences between Object Manager and Project Merge, see
Comparing Project Merge to Object Manager, page 252.
This section includes:
•
Prerequisites for copying objects between projects, page 254
•
Project locking with Object Manager, page 255
•
Copying objects, page 256
•
What happens when you copy or move an object, page 260
•
Resolving conflicts when copying objects, page 266
•
Copying objects in a batch: Update packages, page 273
Prerequisites for copying objects between projects
•
254
To use Object Manager to copy objects between projects, you must have
the Use Object Manager privilege for both projects. You do not need to
have ACL permissions for the objects you are migrating, because the Use
Prerequisites for copying objects between projects
© 2015, MicroStrategy Inc.
System Administration Guide
Object Manager privilege automatically grants its user the Bypass All
Object Security Access Checks privilege when that user is using Object
Manager.
•
To create an update package, you must have either the Use Object Manager
privilege or the Use Object Manager Read-only privilege for the project
from which you are creating an update package.
•
If you want to migrate objects between projects with Object Manager,
MicroStrategy recommends that those projects have related schemas. This
means that either one project must be a duplicate of the other, or both
projects must be duplicates of a third project. For information about
duplicating projects, including instructions, see Duplicating a project, page
245.
•
To move system objects between projects that do not have related
schemas, the projects must either have been created with MicroStrategy
9.0.1 or later, or have been updated to version 9.0.1 or later using the
Perform system object ID unification option. For information about this
upgrade, see the MicroStrategy Upgrade Guide.
•
If one of the projects is updated to a new MicroStrategy release, but
another project is not updated, you cannot move or copy objects from the
project using the updated version of MicroStrategy to the older version.
However, you can move objects from the older version to the updated
project if the older version is interoperable with the updated version. For
detailed information about interoperability between versions of
MicroStrategy, see the MicroStrategy Readme.
Project locking with Object Manager
Opening a connection to a project with Object Manager causes the project
metadata to become locked. Other users cannot make any changes to the
project until it becomes unlocked. For detailed information about the effects of
locking a project, see Locking projects, page 253.
If you need to allow other users to change objects in projects while the
projects are opened in Object Manager, you can configure Object Manager to
connect to projects in read-only mode. You can also allow changes to
configuration objects by connecting to project sources in read-only mode.
Connecting to a project or project source in read-only mode has the following
limitations:
•
A connection in read-only mode may not display the most recent
information. For example, if you view a folder in Object Manager in a readonly connection, and then another user adds an object to that folder, the
object is not displayed in Object Manager.
•
You cannot copy objects into a read-only project or project source. If you
connect to a project in read-only mode, you can still move, copy, and delete
© 2015, MicroStrategy Inc.
Project locking with Object Manager
255
System Administration Guide
objects in a project, but you cannot copy objects from another project into
that project.
•
By default, users cannot create update packages in read-only mode. This is
because objects, and their used dependencies, may be changed between the
time they are selected for inclusion in the update package and the time the
package is actually generated. If necessary, you can configure Object
Manager to allow the creation of update packages in read-only mode. For
information about update packages, see Copying objects in a batch: Update
packages, page 273.
To open projects or connections in read-only mode
1
From the Tools menu, select Preferences. The Object Manager Preferences
dialog box opens.
2
Expand the Object Manager category, and then select Connection.
3
To open project sources in read-only mode, select the Open configuration in
read-only mode check box.
4
To open projects in read-only mode, select the Open project in read-only
mode check box.
5
To allow the creation of update packages in read-only mode, select the
Allow update package creation in read-only mode check box.
6
Click OK. The Object Manager Preferences dialog box closes and your
preferences are saved.
Copying objects
Object Manager can copy application, schema, and configuration objects.
•
Application objects include reports and documents, and the objects used to
create them, such as templates, metrics, filters, prompts, and searches.
Folders are also considered to be application objects.
•
Schema objects include attributes, facts, hierarchies, transformations,
functions, partition mappings, columns, and tables.
•
Configuration objects include objects that are used by all projects in a
project source, such as users and user groups, database instances and
logins, security roles, and Distribution Services devices, transmitters, and
contacts.
If you use Object Manager to copy a user or user group between project
~ sources, the user or group reverts to default inherited access for all
256
Copying objects
© 2015, MicroStrategy Inc.
System Administration Guide
projects in the project source. To copy a user or group’s security
information for a project, you must copy the user or group in a
configuration update package. For information about update packages,
see About update packages, page 273.
For background information on these objects, including how they are created
and what roles they perform in a project, see the MicroStrategy Project
Design Guide.
In a MicroStrategy system, each object has a unique Object ID. Object Manager
identifies objects based on their Object ID, not their name. Hence, objects with
different names are treated as versions of the same object if they have the
same Object ID.
Best practices for copying objects
MicroStrategy recommends that you observe the following practices when
copying objects:
•
Back up your metadata before copying any objects. Object Manager cannot
undo the copying and replacing of objects.
•
Ensure that the Dependency Search, Conflict Resolution, International, and
Migration options in the Object Manager Preferences dialog box are set to
fit your project’s needs. For details about the Dependency Search options,
see Migrating dependent objects, page 263. For details about the Conflict
Resolution options, see Resolving conflicts when copying objects, page
266. For details about the Migration options, see What happens when you
copy or move an object, page 260. The Object Manager Help also provides
a detailed explanation for each of these options.
•
Copy application objects into the following project folders:
▫
My Personal Objects or any subfolder of My Personal Objects
▫
Public Objects or any subfolder of Public Objects.
•
Copy schema objects into the appropriate Schema Objects sub- or
descendent folders only. For example, if you are copying a hierarchy, you
should only paste the hierarchy into the Project Name\Schema
Objects\Hierarchies folder.
•
When copying MDX cubes between projects, make sure that the conflict
resolution action for the cubes, cube attributes, and reports that use the
cubes is set to Replace.
•
If you need to copy objects from multiple folders at once, you can create a
new folder, and create shortcuts in the folder to all the objects you want to
copy. Then copy that folder. Object Manager copies the folder, its contents
(the shortcuts), and their dependencies (the target objects of those
shortcuts) to the new project.
© 2015, MicroStrategy Inc.
Copying objects
257
System Administration Guide
•
Another way to copy objects from multiple folders at once is to create an
update package from the source project, and then import it into the target
project. For more information about update packages, including step-bystep instructions, see Copying objects in a batch: Update packages, page
273.
•
If you are using update packages to update the objects in your projects, use
the Export option to create a list of all the objects in each update package.
•
When copying objects that contain location-specific strings (such as metric
aliases, custom group names, or text boxes in documents), make sure that
you either disable Advanced Conflict Resolution, or use the same option in
the translation preferences and in the conflict resolution. Otherwise there
may be inconsistencies between the object definition and the translation in
the destination project. For an explanation of the advanced conflict
resolution options, including how to enable or disable these options, see
Copying objects between projects in different languages, page 265.
•
Regardless of the translation preferences, when copying objects with
location-specific strings, you should always verify the results. For example,
empty translations in the source or destination may result in incorrect
translations being saved with the new object. You can use Integrity
Manager to identify reports or documents that have unexpected
translations. For information about Integrity Manager, see Chapter 16,
Verifying Reports and Documents with Integrity Manager.
To copy objects between projects
Note the following:
*•
•
To log in to a project source using Object Manager, you must have the
Use Object Manager privilege for that project.
If you want to copy application or schema objects between projects,
MicroStrategy recommends that the two projects have related schemas
(one must be a duplicate of the other or both must be duplicates of a
common project). For details on this, see Duplicating a project, page
245.
Log in to the projects in Object Manager
1
258
From the Windows Start menu, point to All Programs, then MicroStrategy
Products, and then select Object Manager. The Open Project Source dialog
box opens.
Copying objects
© 2015, MicroStrategy Inc.
System Administration Guide
2
In the list of project sources, select the check box for the project source
you want to access. You can select more than one project source.
3
Click Open. You are prompted to log in to each project source that you
have selected.
4
When you have logged into each project source, MicroStrategy Object
Manager opens.
Use the appropriate sub-procedure below depending on whether you want
to Copy application and schema objects or Copy configuration objects.
Copy application and schema objects
5
In the Folder List, expand the project that contains the object you want to
copy, then navigate to the object.
6
Copy the object by right-clicking and selecting Copy.
7
Expand the destination project in which you want to paste the object, and
then select the folder in which you want to paste the object.
8
Paste the application or schema object into the appropriate destination
folder by right-clicking and selecting Paste.
For information about additional objects that may be copied with a given
object, see Used dependencies, page 261.
If you are copying objects between two different project sources, two
* windows are open within the main Object Manager window. In this
case, instead of right-clicking and selecting Copy and Paste, you can
drag and drop objects between the projects.
9
If you copied any schema objects, you must update the destination project’s
schema. Select the destination project, and from the Project menu, select
Update Schema.
© 2015, MicroStrategy Inc.
Copying objects
259
System Administration Guide
Copy configuration objects
10 In the Folder Lists for both the source and destination projects, expand the
Administration folder, then select the appropriate manager for the type of
configuration object you want to copy (Database Instance Manager,
Schedule Manager, or User Manager).
11 From the list of objects displayed on the right-hand side in the source
project source, drag the desired object into the destination project source
and drop it.
To display the list of users on the right-hand side, expand User
* Manager, then on the left-hand side select a group.
What happens when you copy or move an object
If the object you are copying does not exist in the destination project,
MicroStrategy Object Manager copies the object into the destination project.
This new object has the same name as the source object.
If the object you are copying does exist in the destination project, a conflict
occurs and Object Manager opens the Conflict Resolution dialog box. For
information about how to resolve conflicts, see Resolving conflicts when
copying objects, page 266.
For more information about handling specific situations, see:
•
Managing object dependencies, page 260
•
Migrating dependent objects, page 263
•
Timestamps for migrated objects, page 265
•
Copying objects between projects in different languages, page 265
Managing object dependencies
When an object uses another object in its definition, the objects are said to
depend on one another. Object Manager recognizes two types of object
dependencies: used dependencies and used-by dependencies.
When you migrate an object to another project, by default any objects used by
that object in its definition (its used dependencies) are also migrated. You can
exclude certain objects and tables from the dependency check and migration.
For instructions, see Excluding dependent attributes or tables from object
migration, page 264.
260
What happens when you copy or move an object
© 2015, MicroStrategy Inc.
System Administration Guide
Used dependencies
A used dependency occurs when an object uses other objects in its definition.
For example, in the MicroStrategy Tutorial project, the metric named Revenue
uses the base formula named Revenue in its definition. The Revenue metric is
said to have a used dependency on the Revenue base formula. (Additionally,
the Revenue base formula has a used-by dependency of the Revenue metric.)
When you migrate an object to another project, any objects used by that object
in its definition (its used dependencies) are also migrated. The order of these
dependent relationships is maintained.
To manage used or used-by dependencies of an object
1
After you have opened a project source and a project using Object
Manager, in the Folder List select the object.
2
From the Tools menu, select Object used dependencies. The Used
dependencies dialog box opens and displays a list of objects that the
selected object uses in its definition. The image below shows the used
dependencies of the Revenue metric in the MicroStrategy Tutorial project:
in this case, the used dependency is the Revenue base formula.
3
In the Used dependencies dialog box, you can do any the following:
•
View used dependencies for any object in the list by selecting the object
and clicking the Object used dependencies toolbar icon.
•
Open the Used-by dependencies dialog box for any object in the list by
selecting the object and clicking the Object used-by dependencies icon
on the toolbar. For information about used-by dependencies, see Usedby dependencies, page 262.
•
View the properties of any object, such as its ID, version number, and
access control lists, by selecting the object and from the File menu
choosing Properties.
© 2015, MicroStrategy Inc.
What happens when you copy or move an object
261
System Administration Guide
Used-by dependencies
A used-by dependency occurs when an object is used as part of the definition
of other objects. For example, in the MicroStrategy Tutorial project, the
Revenue metric has used-by dependencies of many reports and even other
metrics. The Revenue metric is said to be used by these other objects.
Used-by dependents are not automatically migrated with their used objects.
However, you cannot delete an object that has used-by dependencies without
first deleting its used objects.
To manage the used-by dependencies of an object
262
1
After you have opened a project source and a project using Object
Manager, from the Folder List select the object.
2
From the Tools menu, choose Object used-by dependencies. The Used-by
dependencies dialog box opens and displays a list of objects that depend on
the selected object for part of their definition. The image below shows
some of the used-by dependencies for the Revenue metric in the
MicroStrategy Tutorial project.
3
In the Used-by dependencies dialog box, you can do any of the following:
•
View used-by dependencies for any object in the list by selecting the
object and clicking the Object used-by dependencies icon on the
toolbar.
•
Open the Used dependencies dialog box for any object in the list by
selecting the object and clicking the Object used dependencies icon on
the toolbar. For information about used dependencies, see Used
dependencies, page 261.
What happens when you copy or move an object
© 2015, MicroStrategy Inc.
System Administration Guide
•
View the properties of any object, such as its ID, version number, and
access control lists, by selecting the object and from the File menu
choosing Properties.
Migrating dependent objects
When you copy an object using Object Manager, it checks for any used
dependents of that object and copies them as well. These dependent objects
are copied to the same path as in the source project. If this path does not
already exist in the destination project, Object Manager creates the path.
For example, a user copies a report from the source project to the destination
project. In the source project, all dependents of the report are stored in the
Public Objects\Report Dependents folder. Object Manager looks in
the destination project’s Public Objects folder for a subfolder named Report
Dependents (the same path as in the source project). If the folder exists, the
dependent objects are saved in that folder. If the destination project does not
have a folder in Public Objects with the name User, Object Manager creates it
and saves all dependent objects there.
When you create an update package, click Add All Used Dependencies to
~ make sure all used dependencies are included in the package. If the
dependent objects for a specific object do not exist in either the destination
project source or in the update package, the update package cannot be
applied. If you choose not to add dependent objects to the package, make
sure that all dependent objects are included in the destination project
source.
Object dependencies
Some objects have dependencies that are not immediately obvious. These are
listed below:
•
Folders have a used dependency on each object in the folder. If you copy a
folder using Object Manager, all the objects in that folder are also copied.
A folder that is copied as part of an update package does not have a
* used dependency on its contents.
•
Shortcut objects have a used dependency on the object they are a shortcut
to. If you copy a shortcut using Object Manager, the object it is a shortcut
to is also copied.
•
Security filters, users, and user groups have a used dependency on the user
groups they belong to. If you copy a security filter, user, or user group, the
groups that it belongs to are also copied.
© 2015, MicroStrategy Inc.
What happens when you copy or move an object
263
System Administration Guide
*
•
Groups have a used-by dependency on the users and security filters that
are associated with them. Copying a group does not automatically copy
the users or security filters that belong to that group. To copy the users
or security filters in a group, select the users from a list of that group’s
used-by dependents and then copy them.
Attributes used in fact expressions are listed as dependents of the fact.
When the fact is copied, the attribute is also copied.
*
Attributes used in fact entry levels are not dependents of the fact.
Excluding dependent attributes or tables from object migration
When you copy an object, or add dependent objects to an update package,
Object Manager searches for that object’s used dependencies so it can copy
those objects also. Depending on the options you set in the Object Manager
Preferences, you can exclude certain types of dependent objects from this
migration.
The options are:
•
Exclude all parent attributes from an attribute and Exclude all child
attributes from an attribute: An attribute has a used dependency on its
parent and child attributes in a hierarchy. Thus, migrating an attribute may
result in migrating its entire hierarchy. To exclude the parent or child
attributes from being migrated, select the corresponding option.
•
Exclude non-lookup tables from an attribute and Exclude all tables from a
fact: An attribute or fact has a used dependency on each table that is
referenced by the attribute or fact. Thus, by default, migrating an attribute
or fact results in migrating all its associated tables. You can choose to
exclude the tables from the dependency search if, for example, you have
mapped additional tables to an attribute or fact for testing purposes but do
not need those tables in the production project.
For attributes, the lookup table must always exist in the destination
* project, so it is always migrated.
To exclude types of dependent objects
264
1
From the Tools menu, select Object Manager Preferences. The Object
Manager Preferences dialog box opens.
2
Expand Dependency search, and then select Dependency search.
What happens when you copy or move an object
© 2015, MicroStrategy Inc.
System Administration Guide
3
Select the check boxes for the objects you want to exclude from Object
Manager’s dependency checking.
4
Click OK. The Object Manager Preferences dialog box closes and your
preferences are saved.
Timestamps for migrated objects
By default, when an object is migrated, the object’s modification timestamp is
updated to the destination Intelligence Server’s migration process time. You
can change this behavior so that the timestamp remains as the last
modification time the object had in the source project.
To set the migrated object modification timestamp
1
From the Tools menu, select Object Manager Preferences. The Object
Manager Preferences dialog box opens.
2
Expand Migration, and then select Migration.
3
To cause objects to keep the modification timestamp from the source
project, select the Preserve object modification timestamp during migration
check box. If this check box is cleared, objects take the modification
timestamp from the destination Intelligence Server at the time of
migration.
4
Click OK. The Object Manager Preferences dialog box closes and your
preferences are saved.
Copying objects between projects in different languages
Object Manager’s internationalization options allow you to specify the locale
settings to be used when copying objects. You can also retain the object’s
name, description, and long description from the destination project, when
replacing objects in the destination project using Object Manager.
The ability to retain the name, description, and long description is important
in internationalized environments. When replacing the objects to resolve
conflicts, retaining these properties of the objects in the destination project
facilitates support of internationalized environments. For example, if the
destination project contains objects with French names but the source project
has been developed in English (including English names), you can retain the
French names and descriptions for objects in the destination project.
Alternately, you can update the project with the English names and not change
the object itself.
© 2015, MicroStrategy Inc.
What happens when you copy or move an object
265
System Administration Guide
To set the internationalization options
1
From the Tools menu, select Object Manager Preferences. The Object
Manager Preferences dialog box opens.
2
Expand the International category, and select Language.
3
From the Interface Language drop-down list, select the language to be
used in Object Manager. By default this is the language used in all
MicroStrategy products installed on this system.
4
From the Language for metadata and warehouse data if user and project
level preferences are set to default drop-down list, select whether copied
objects use the locale settings from Developer or from the machine’s
regional settings.
For more information on metadata and warehouse data languages, see
* About internationalization in the Supplemental Reference for System
Administration Guide, and for a table on the prioritization of user- and
project-level language preferences, see Configuring metadata object
and report data language preferences in the Supplemental Reference
for System Administration Guide.
5
In the International category, select Translation.
6
To resolve translations with a different action than that specified for the
object associated with the translation, select the Enable advanced conflict
resolution check box.
•
To always use the translations in the destination project, select Keep
Existing.
•
To always use the translations in the source project, select Replace.
7
Select the Merge translations even if object exists identically check box to
update the translations for all copied objects in the destination project,
according to the option specified above (Keep Existing or Replace
(Default)), even if the object exists identically in both projects.
8
Click OK. The Object Manager Preferences dialog box closes and your
preferences are saved.
Resolving conflicts when copying objects
In the MicroStrategy system, every object has an ID (or GUID) and a version.
The version changes every time the object is updated; the ID is created when
the object is created and remains constant for the life of the object. To see the
ID and version of an object, right-click the object and select Properties.
266
Resolving conflicts when copying objects
© 2015, MicroStrategy Inc.
System Administration Guide
When copying objects across projects with Object Manager, if an object with
the same ID as the source object exists anywhere in the destination project, a
conflict occurs and the Conflict Resolution dialog box (shown below) opens. It
prompts you to resolve the conflict.
The table below lists the different kinds of conflict:
Conflict
Explanation
Exists
identically
The object ID, object version, and path are the same in the source and destination projects.
Exists
differently
The object ID is the same in the source and destination projects, but the object versions are
different. The path may be the same or different.
Exists
identically
except for
path
The object ID and object version are the same in the source and destination projects, but the
paths are different. This occurs when one of the objects exists in a different folder.
Note: If your language preferences for the source and destination projects are different, objects
that are identical between the projects may be reported as Exists Identically Except For Path. This
occurs because when different languages are used for the path names, Object Manager treats
them as different paths. To resolve this, set your language preferences for the projects to the
same language.
If you resolve the conflict with the Replace action, the destination object is updated to reflect the
path of the source object.
Exists
identically
except for
Distribution
Services
objects
(User only) The object ID and object version of the user are the same in the source and destination
projects, but at least one associated Distribution Services contact or contact group is different.
This may occur if you modified a contact or contact group linked to this user in the source project.
Does not
exist
The object exists in the source project but not in the destination project.
If you resolve the conflict with the Replace action, the destination user is updated to reflect the
contacts and contact groups of the source user.
Note: If you clear the Show new objects that exist only in the source check box in the
Migration category of the Object Manager Preferences dialog box, objects that do not exist in the
destination project are copied automatically with no need for conflict resolution.
Choosing an action to resolve a conflict
If a conflict occurs you must determine what action Object Manager should
take. The different actions are explained in the table below.
When Object Manager reports a conflict it also suggests a default action to
take for that conflict. For information on changing the default action, see
Setting default actions for conflict resolutions, page 269.
© 2015, MicroStrategy Inc.
Resolving conflicts when copying objects
267
System Administration Guide
User
Action
Effect
Use existing
No change is made to the destination object. The source object is not copied.
Replace
The destination object is replaced with the source object.
Note:
If the conflict type is Exists Identically Except For Path, or Exists Identically Except For Distribution
Services Objects, the destination object is updated to reflect the path or Distribution Services
addresses and contacts of the source object.
Replace moves the object into same parent folder as the source object. If the parent path is the
same between source and destination but the grandparent path is different, Replace may appear
to do nothing because Replace puts the object into the same parent path.
Non-empty folders in the destination location will never have the same version ID and
modification time as the source, because the folder is copied first and the objects are added to it,
thus changing the version ID and modification times during the copy process.
Keep both
No change is made to the destination object. The source object is duplicated in the destination
location.
Use newer
If the source object’s modification time is more recent than the destination object’s, the Replace
action is used.
Otherwise, the Use existing action is used.
Use older
If the source object’s modification time is more recent than the destination object’s, the Use
existing action is used.
Otherwise, the Replace action is used.
Merge
(user/group
only)
The privileges, security roles, groups, and Distribution Services addresses and contacts of the
source user or group are added to those of the destination user or group.
Do not
move (table
only)
The selected table is not created in the destination project. This option is only available if the
Allow to override table creation for non-lookup tables that exist only at source project check
box in the Migration category of the Object Manager Preferences dialog box is selected.
Force
replace
(Update
packages
only)
Replace the object in the destination project with the version of the object in the update package,
even if both versions of the object have the same Version ID.
Delete
(Update
packages
only)
Delete the object from the destination project. The version of the object in the update package is
not imported into the destination project.
Warning : If the object in the destination has any used-by dependencies when you import the
update package, the import will fail.
Warehouse and other database tables associated with the objects moved
* are handled in specific ways, depending on your conflict resolution choices.
For details, see Conflict resolution and tables, page 271.
If you choose to replace a schema object, the following message may appear:
The schema has been modified. In order for the changes to
take effect, you must update the schema.
268
Resolving conflicts when copying objects
© 2015, MicroStrategy Inc.
System Administration Guide
This message also appears if you choose to replace an application object that
depends on an attribute, and you have made changes to that attribute by
modifying its form properties at the report level or its column definition
through another attribute. For information about modifying the properties of
an attribute, see the MicroStrategy Project Design Guide.
To update the project schema, from the Object Manager Project menu, select
Update Schema. For details about updating the project schema, see the
Optimizing and Maintaining your Project chapter in the MicroStrategy
Project Design Guide.
To resolve a conflict
1
Select the object or objects that you want to resolve the conflict for. You
can select multiple objects by holding down SHIFT or CTRL when selecting.
2
Choose an option from the Action drop-down list (see table above). This
option is set for all selected objects.
3
On the toolbar, click Proceed. The conflict is resolved according to the
selected action.
Setting default actions for conflict resolutions
You can determine the default actions that display in the Conflict Resolution
dialog box when a conflict occurs. This includes setting the default actions for
the following object categories and types:
•
Application objects
•
Schema objects
•
Configuration objects
•
Folders
•
Users and user groups
For a list of application, configuration, and schema objects, see Copying
objects, page 256. For an explanation of each object action, see Choosing an
action to resolve a conflict, page 267.
You can set a different default action for objects specifically selected by the
user, and for objects that are included because they are dependents of selected
objects. For example, you can set selected application objects to default to Use
newer to ensure that you always have the most recent version of any metrics
and reports. You can set dependent schema objects to default to Replace to
use the source project’s version of attributes, facts, and hierarchies.
© 2015, MicroStrategy Inc.
Resolving conflicts when copying objects
269
System Administration Guide
These selections are only the default actions. You can always change the
conflict resolution action for a given object when you copy that object.
To set the default conflict resolution actions
1
From the Tools menu, select Object Manager Preferences. The Object
Manager Preferences dialog box opens.
2
Expand the Conflict Resolution category, and select Default Object Actions.
3
Make any changes to the default actions for each category of objects.
4
•
For an explanation of the differences between application,
configuration, and schema objects, see Copying objects, page 256.
•
For an explanation of each object action, see Choosing an action to
resolve a conflict, page 267.
Click OK. The Object Manager Preferences dialog box closes and your
preferences are saved.
Conflict resolution and access control lists
When you update or add an object in the destination project, by default the
object keeps its access control list (ACL) from the source project. You can
change this behavior in two ways:
•
If you resolve a conflict with the Replace action, and the access control lists
(ACL) of the objects are different between the two projects, you can choose
whether to keep the existing ACL in the destination project or replace it
with the ACL from the source project.
•
If you add a new object to the destination project with the Create New or
Keep Both action, you can choose to have the object inherit its ACL from
the destination folder instead of keeping its own ACL. This is helpful when
copying an object into a user’s profile folder, so that the user can have full
control over the object.
The Use Older or Use Newer actions always keep the ACL of whichever object
(source or destination) is used.
To set the ACL options
270
1
From the Tools menu, select Object Manager Preferences. The Object
Manager Preferences dialog box opens.
2
Expand the Conflict Resolution category, and select Access Control List.
Resolving conflicts when copying objects
© 2015, MicroStrategy Inc.
System Administration Guide
3
Under ACL option on replacing objects, select how to handle the ACL for
conflicts resolved with the Replace action:
•
To use the ACL of the source object, select Keep existing ACL when
replacing objects.
•
To use the ACL of the replaced destination object, select Replace
existing ACL when replacing objects.
If this option is selected, the ACL is replaced even if the source and
* destination objects are identical.
4
5
Under ACL option on new objects, select how to handle the ACL for new
objects added to the destination project:
•
To use the ACL of the source object, select Keep ACL as in the source
objects.
•
To inherit the ACL from the destination folder, select Inherit ACL from
the destination folder.
Click OK. The Object Manager Preferences dialog box closes and your
preferences are saved.
Conflict resolution and tables
When an attribute or fact is migrated from one project to another using Object
Manager, either specifically or because it is a dependent of another object, by
default all dependent tables are also migrated. This includes warehouse tables
as well as MDX tables and XDA tables.
You can choose not to create a dependent table in the destination project by
changing the Action for the table from Create New to Ignore. You can also
choose not to migrate any dependent tables by specifying that they not be
included in Object Manager’s dependency search. For detailed information,
including instructions, see Migrating dependent objects, page 263.
The following list and related tables explain how the attribute - table or fact table relationship is handled, based on the existing objects and tables and the
conflict resolution action you select.
In the following list and tables, attribute, fact, and table descriptions refer
* to the destination project. For example, “new attribute” means the
attribute is new to the destination project: it exists in the source project
but not the destination project.
•
New attribute or fact, new table: There is no conflict resolution. By default
the table is moved with the object. You can choose not to create the
dependent table in the destination project by changing the Action for the
table from Create New to Ignore.
© 2015, MicroStrategy Inc.
Resolving conflicts when copying objects
271
System Administration Guide
•
New attribute or fact, existing table: The object in the source project
contains a reference to the table in its definition. The table in the
destination project has no reference to the object because the object is not
present in the destination project. In this case the new object will have the
same references to the table as it did in the source project.
•
Existing attribute or fact, new table: The object in the destination project
does not refer to the table because the table does not exist in the
destination project. The object in the source project contains a reference to
the table in its definition.
•
•
272
Object
Action
What happens in the destination project
Use
Existing
The object does not reference the table.
Replace
The object has the same references to the table as it does in the source project.
Keep
Both
No change is made to the destination object. The source object is duplicated in the destination
project. The duplicated object will have the same references to the table as it does in the source
project.
Existing attribute or fact, existing table: The object has a reference to the
table in the source project but has no reference to it in the destination
project.
Object
Action
What happens in the destination project
Use
Existing
The object does not reference the table.
Replace
The object has the same references to the table as it does in the source project.
Keep
Both
No change is made to the destination object. The source object is duplicated in the destination
project. The duplicated object will have the same references to the table as it does in the source
project.
Existing attribute or fact, existing table: The object has no reference to the
table in the source project but has a reference to it in the destination
project.
Object
Action
What happens in the destination project
Use
Existing
The object has the same references to the table as it did before the action.
Replace
The object does not reference the table.
Keep
Both
No change is made to the destination object. The source object is duplicated in the destination
project. The duplicated object will not reference the table.
Resolving conflicts when copying objects
© 2015, MicroStrategy Inc.
System Administration Guide
Copying objects in a batch: Update packages
In some cases, you may need to update the objects in several folders at once,
or at a time when the source project is offline. Object Manager allows you to
save the objects you want to copy in an update package, and import that
package into any number of destination projects at a later date.
For example, you have several developers who are each responsible for a
subset of the objects in the development project. The developers can submit
update packages, with a list of the objects in the packages, to the project
administrator. The administrator can then import those packages into the test
project to apply the changes from each developer. If a change causes a problem
with the test project, the administrator can undo the package import process.
~
If your update package includes any schema objects, you may need to
update the project schema after importing the package. For more
information about updating the schema after importing an update package,
see Update packages and updating the project schema, page 289.
About update packages
An update package is a file containing a set of object definitions and conflict
resolution rules. When you create an update package, you first add objects, and
then specify how any conflict involving the objects is resolved. For more
information on resolving conflicts with objects, see Resolving conflicts when
copying objects, page 266.
In addition to the standard Object Manager conflict resolution rules (see
Choosing an action to resolve a conflict, page 267), two additional rules are
available for update packages:
•
Force Replace: Replace the object in the destination project with the
version of the object in the update package, even if both versions of the
object have the same Version ID.
•
Delete: Delete the object from the destination project. The version of the
object in the update package is not imported into the destination project.
If the object in the destination has any used-by dependencies when you
~ import the update package, the import will fail.
Object Manager supports the following kinds of update packages:
•
Project update packages contain application and schema objects from a
single project.
•
Configuration update packages contain configuration objects from a single
project source.
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
273
System Administration Guide
▫
•
Project security update packages contain security information about
users and user groups, such as privileges, security roles, and security
filters, for a single project. Since these update packages involve users
and groups, which are configuration objects, they are created at the
same time as configuration update packages.
Undo packages enable you to reverse the changes made by importing one
of the other types of packages. You create undo packages based on existing
update packages. For more information about undo packages, including
instructions on creating and importing them, see Rolling back changes:
Undo packages, page 290.
Updating project access information for users and groups
You can include users and groups in a configuration update package. However,
the project access information, such as privileges, security roles, and security
filters, for those users and groups is not included in the configuration update
package, because this information can be different for each project.
*
Specifically, configuration update packages do not include the information
found in the Project Access and Security Filter categories of the User
Editor or Group Editor. All other user and group information is included in
the configuration update package when you add a user or group to the
package.
To update your users and groups with the project access information for each
project, you must create a project security update package for each project.
You create these packages at the same time that you create the configuration
update package, by selecting the Create project security packages check box
and specifying which projects you want to create a project security update
package for. For detailed instructions on creating a configuration update
package and project security update packages, see Creating a configuration
update package, page 277.
You must import the configuration update package before importing the
~ project security update packages.
Creating an update package
You create update packages from within Object Manager. From the Create
Package dialog box, you select the objects to copy from the source project, and
the rules that govern the cases when these objects already exist in the
destination project.
You can also create update packages from the command line, using rules
specified in an XML file. In the Create Package dialog box, you specify a
container object, such as a folder, search object, or object prompt, and specify
the conflict resolution rules. Object Manager creates an XML file based on
274
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
your specifications. You can then use that XML file to create an update
package that contains all objects included in the container. For more
information and instructions, see Creating an update package from the
command line, page 279.
Note the following:
*•
•
Configuration update packages and project security update packages are
created slightly differently from project update packages. For
instructions on how to create a configuration update package and
associated project security update packages, see Creating a
configuration update package, page 277.
By default, users cannot create project update packages in read-only
mode. This is because objects, and their used dependencies, may be
changed between the time they are selected for inclusion in the update
package and the time the package is actually generated. For more
information, see Project locking with Object Manager, page 255.
To create a project update package
1
In Object Manager, log in to a project.
2
From the Tools menu, select Create Package. The Create Package dialog
box opens.
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
275
System Administration Guide
*
You can also open this dialog box from the Conflict Resolution dialog
box by clicking Create Package. In this case, all objects in the Conflict
Resolution dialog box, and all dependents of those objects, are
automatically included in the package.
Adding objects to the package
3
4
To add objects to the package, do one of the following:
•
Drag and drop objects from the Object Browser into the Create Package
dialog box.
•
Click Add. An Add Objects dialog box opens. Select the desired objects
and click >. Then click OK.
•
Click Add. An Add Objects dialog box opens. You can import the results
of a previously saved search object.
To add the dependents of all objects to the package, click Add all used
dependencies. All dependent objects of all objects currently listed in the
package are added to the package.
If the dependent objects for a specific object do not exist in either the
~ destination project source or in the update package, the update package
cannot be applied. If you choose not to add dependent objects to the
package, make sure that all dependent objects are included in the
destination project source.
5
To add the dependents of specific objects, select those objects, right-click,
and select Add used dependencies. All dependent objects of those objects
are added to the package.
Configuring the package
276
6
To change the conflict resolution action for an object, double-click the
Action column for the object and select the new action from the drop-down
list. For an explanation of the actions, see Choosing an action to resolve a
conflict, page 267.
7
Select the schema update options for this package. For more details on
these options, see Update packages and updating the project schema, page
289.
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
8
Select the ACL options for objects in this package. For more details on
these options, see Conflict resolution and access control lists, page 270.
Saving the package
9
Enter the name and location of the package file in the Save As field. The
default file extension for update packages is .mmp.
You can set the default location in the Object Manager Preferences
* dialog box, in the Object Manager: Browsing category.
10 To save a log file containing information about the package’s contents in
the Object Manager directory, from the File menu select Save As Text File
or Save As Excel File.
11 When you have added all objects to the package, click Proceed. The
package is created in the specified location.
Creating a configuration update package
A configuration update package contains configuration objects from a project
source, instead of application and schema objects from a single project. As
such, configuration update packages are created at the project source level.
If you choose to include users or groups in a configuration update package,
* project access information (such as privileges, security roles, and security
filters) is not included in the configuration package. To migrate project
access information about the users or groups, you must create a project
security update package for each project at the same time you create the
configuration update package. For more information about project security
packages, see Updating project access information for users and groups,
page 274.
To create a configuration update package
1
In Object Manager, log in to a project source.
2
In the folder list, select the top-level project source.
3
From the Tools menu, select Create Configuration Package. The Create
Package dialog box opens.
You can also open this dialog box from the Conflict Resolution dialog
* box by clicking Create Package. In this case, all objects in the Conflict
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
277
System Administration Guide
Resolution dialog box, and all dependents of those objects, are
automatically included in the package.
Adding configuration objects to the package
4
To add configuration objects to the package, click Add Configuration
Objects. A Configuration - Search Objects dialog box opens.
5
Search for the objects you want to add to the package. For instructions on
performing a search, see the Help.
6
When the objects are loaded in the search area, click and drag them to the
Create Package dialog box.
7
When you have added all the desired objects to the package, close the
Configuration - Search for Objects dialog box.
8
To add the dependents of all objects to the package, click Add all used
dependencies. All dependent objects of all objects currently listed in the
package are added to the package.
If the dependent objects for a specific object do not exist in either the
~ destination project source or in the update package, the update package
cannot be applied. If you choose not to add dependent objects to the
package, make sure that all dependent objects are included in the
destination project source.
9
To add the dependents of specific objects, select those objects and click Add
used dependencies. All dependent objects of those objects are added to the
package.
Creating packages for project-level user and group access
10 If your project includes users or groups, and you want to include projectlevel information about those users or groups, select the Create project
security packages check box. For information about project security
packages, see Updating project access information for users and groups,
page 274.
11 In the Projects area, select the check boxes next to the projects you want
to create project security packages for.
278
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
Configuring the package
12 To change the conflict resolution action for an object, double-click the
Action column for the object and select the new action from the drop-down
list. For an explanation of the actions, see Choosing an action to resolve a
conflict, page 267.
If you are creating project security update packages, you must select
~ Replace as the conflict resolution action for all users and groups.
Otherwise the project-level security information about those users and
groups is not copied into the destination project.
13 Select the ACL options for objects in this package. For more details on
these options, see Conflict resolution and access control lists, page 270.
Saving the package
14 Enter the name and location of the package file in the Save As field. The
default file extension for update packages is .mmp.
Project security update packages are named ProjectSource_
* ProjectName.mmp, and are created in the same location as the
configuration update package.
15 To save a log file containing information about the package’s contents in
the Object Manager directory, from the File menu select Save As Text File
or Save As Excel File.
16 When you have added all objects to the package, click Proceed. The
configuration update package and any associated project security update
packages are created in the specified location.
Creating an update package from the command line
You may want to schedule the creation of an update package at a later time, so
that the project is not locked during normal business hours. Or you may want
to create a package containing certain objects on a specific schedule. For
example, you may want to create a new package every week that contains all
the new metrics from the development project.
You can use Object Manager to create an XML file specifying what objects are
to be included in the update package. That XML file can then be used to create
the package from the command line.
The XML file specifies a container object in the source project, that is, a folder,
search object, or object prompt. When you create the package from the XML
file, all objects included in that container object are included in the update
package, as listed in the table below:
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
279
System Administration Guide
If the XML file specifies a...
The update package contains...
Folder
All objects in the folder
Search object
All objects returned by the search
Object prompt
All objects returned by the prompt
To create an XML file for a configuration update package, see Manually
* creating an update package creation XML file, page 282. You cannot
create a configuration update package XML file from within Object
Manager because container objects do not exist at the project source level.
To create an XML file for creating an update package from the
command line
1
In Object Manager, log in to a project.
2
From the Tools menu, select Create Package. The Create Package dialog
box opens.
Adding a container object to the package
3
Click Add. The Add Objects dialog box opens.
4
You need to specify what to use as a container object. You can use a search
object, object prompt, or folder. To specify a search object or object
prompt as the container object:
5
280
a
Make sure the Import selected objects option is selected.
b
In the Available objects area, browse to the search object or object
prompt.
c
Select the search object or object prompt and click >.
OR, to specify a folder as the container object:
a
Select the Import folder and children recursively option.
b
Type the name of the folder in the field, or click ... (the browse button)
and browse to the folder.
6
Select the Return as a container to create XML check box.
7
Click OK. The Add Objects dialog box closes.
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
8
To add the dependents of all objects to the package, select the Add all used
dependencies check box. All dependent objects of all objects included in
the container object will be included in the package when it is created.
If the dependent objects for a specific object do not exist in either the
~ destination project or in the update package, the update package cannot
be applied. If you choose not to include dependent objects in the
package, make sure that all dependent objects are included in the
destination project.
Configuring the package
9
To change the conflict resolution action for an object, double-click the
Action column for the object and select the new action from the drop-down
list. For an explanation of the actions, see Choosing an action to resolve a
conflict, page 267.
10 Select the schema update options for this package. For more details on
these options, see Update packages and updating the project schema, page
289.
11 Select the ACL options for objects in this package. For more details on
these options, see Conflict resolution and access control lists, page 270.
Saving the XML file
12 Enter the name and location of the package file to be created by this XML
in the Save As field. The default file extension for update packages is .mmp.
You can set the default location in the Object Manager Preferences
* dialog box, in the Object Manager: Browsing category.
13 Click Create XML. You are prompted to type the name and location of the
XML file. By default, this is the same as the name and location of the
package file, with an .xml extension instead of .mmp.
14 Click Save. The XML file is saved.
To create an update package from an XML file
Creating a package from the command line locks the project metadata
~ for the duration of the package creation. Other users cannot make any
changes to the project until it becomes unlocked. For detailed
information about the effects of locking a project, see Locking projects,
page 253.
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
281
System Administration Guide
Call the Project Merge executable, projectmerge.exe, with the
following parameters:
Effect
Parameter
Use this XML file to create an update package (required)
-f
Filename.xml
Log into the project source with this password (the login ID to be used is stored in
the XML file)
spPassword
Log into the project with this password (the login ID to be used is stored in the
XML file)
smp
Password
Suppress status updates (useful for creating an update package in the background,
so that the status window does not appear)
-sup
Manually creating an update package creation XML file
You can also create the XML file to create an update package without opening
Object Manager. To do this, you first copy a sample XML file that contains the
necessary parameters, and then edit that copy to include a list of the objects to
be migrated and conflict resolution rules for those objects.
This is the only way to create an XML file to create a configuration update
* package.
Sample package creation XML files for project update packages and
configuration update packages are in the Object Manager folder. By default this
folder is C:\Program Files (x86)\MicroStrategy\Object
Manager\.
*
The XML file has the same structure as an XML file created using the
Project Merge Wizard. For more information about creating an XML file
for use with Project Merge, see Merging projects to synchronize objects,
page 290.
High-level steps to manually create an update package creation XML
file
1
Make a copy of one of the sample XML files:
•
282
To create a project update package, copy the file
createProjectPackage.xml.
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
•
2
To create a configuration update package, copy the file
createConfigPackage.xml.
Edit your copy of the XML file to include the following information, in the
appropriate XML tags:
•
SearchID (project update package only): The GUID of a search object
that returns the objects to be added to the project update package.
•
TimeStamp (configuration update package only): A timestamp, of the
form MM/DD/YYYY hh:mm:ss (am/pm). All configuration objects
modified after that timestamp are included in the update package.
•
PackageFile: The name and path of the update package. If a package
with this name already exists in this path, the creation timestamp is
appended to the name of the package created by this file.
•
AddDependents:
— Yes for the package to include all dependents of all objects in the
package.
— No for the package to only include the specified objects.
•
Location: In a three-tier system, this is the name of the machine that is
used to connect to the project source. In a two-tier system, this is the
DSN used to connect to the project source.
•
Project (project update package only): The project containing the
objects to include in the update package.
•
ConnectionMode:
— 2-tier for a direct (2-tier) project source connection.
— 3-tier for a server (3-tier) project source connection.
•
AuthenticationMode: The authentication mode used to connect to the
project source, either Standard or Windows.
•
Login: The user name to connect to the project source. You must
provide a password for the user name when you run the XML file from
the command line.
3
For a project update package, you can specify conflict resolution rules for
individual objects. In an Operation block, specify the ID (GUID) and Type of
the object, and the action to be taken. For information about the actions
that can be taken in conflict resolution, see Choosing an action to resolve a
conflict, page 267.
4
Save the XML file.
5
When you are ready to create the update package from the XML file, call
the Project Merge executable, projectmerge.exe, as described in To
create an update package from an XML file, page 281.
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
283
System Administration Guide
Editing an update package
You can make changes to an update package after it has been created. You can
remove objects from the package, change the conflict resolution rules for
objects in the package, and set the schema update and ACL options for the
package.
*
You cannot add objects to an update package once it has been created.
Instead, you can create a new package containing those objects.
To edit an update package
1
In Object Manager, log in to a project or project source.
2
From the Tools menu, select Import Package or Import Configuration
Package. The Import Package or Import Configuration Package dialog box
opens.
3
In the Selected Package field, type the name and path of the update
package, or click ... (the browse button) to browse to the update package.
4
Click Edit. The Editing pane opens at the bottom of the dialog box, as
shown below.
5
To change the conflict resolution action for an object, double-click in the
Definition Rule column for that object and, from the drop-down list, select
the new conflict resolution rule.
When you edit a package, the Create New action is changed to the
* Replace action.
6
284
To rename an object in the destination project, double-click in the Rename
column for that object and type the new name for the object.
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
7
To remove an object from the update package, select the object and click
Remove.
8
You can also change the schema update options (for a project update
package only) or the access control list conflict resolution options. For
information about the schema update options, see Update packages and
updating the project schema, page 289. For information about the ACL
conflict resolution options, see Conflict resolution and access control lists,
page 270.
9
To create a text file containing a list of the objects in the update package
and their conflict resolution actions, click Export.
10 When you are done making changes to the update package, click Save As. A
Save dialog opens for you to save the edited package. The default new
name for the update package is the original name of the package with a
date and time stamp appended. Click Save to save the update package and
return to Object Manager.
Importing an update package
An update package is saved in a file, and can be freely copied and moved
between machines.
Importing a package causes the project metadata to become locked for the
~ duration of the import. Other users cannot make any changes to the project
until it becomes unlocked. For detailed information about the effects of
locking a project, see Locking projects, page 253.
You can import an update package into a project or project source in the
following ways:
•
From within Object Manager: You can use the Object Manager graphical
interface to import an update package.
•
From the command line: MicroStrategy provides a command line utility for
importing update packages. You can use a scheduler such as Windows
Scheduler to import the package at a later time, such as when the load on
the destination project is light.
The command line Import Package utility only supports Standard and
~ Windows Authentication. If your project source uses a different form of
authentication, you cannot use the Import Package utility to import an
update package.
You can also create an XML file to import an update package from the
command line, similar to using an XML file to create an update package as
described in Creating an update package from the command line, page
279.
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
285
System Administration Guide
•
Using a Command Manager script: You can also execute a Command
Manager script to import an update package without using Object Manager.
Command Manager is an administrative tool that enables you to perform
various administrative and project development tasks by using text
commands that can be saved as scripts. For more information about
Command Manager, see Chapter 15, Automating Administrative Tasks
with Command Manager.
Prerequisites
•
If you are importing a package that is stored on a machine other than the
Intelligence Server machine, make sure the package can be accessed by the
Intelligence Server machine.
•
Before importing any project security update packages, you must import
the associated configuration update package.
To import an update package from Object Manager
286
1
In Object Manager, log in to the destination project or project source.
2
From the Tools menu, select Import Package (for a project update package)
or Import Configuration Package (for a configuration update package). The
Import Package or Import Configuration Package dialog box opens.
3
In the Selected Package field, type the name and path of the update
package, or click ... (the browse button) to browse to the update package.
4
In the Undo Package Options, select whether to import this update
package, generate an undo package for this update package, or both. For
more information about undo packages, see Rolling back changes: Undo
packages, page 290.
5
To create a log file describing the changes that would be made if the update
package were imported, instead of importing the update package, select the
Generate Log Only check box.
6
Click Proceed. All objects in the update package are copied to the
destination project or project source, following the rules specified in the
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
update package. A log file containing information about the import process
is created in the Object Manager directory.
Any objects that exist in different folders in the update package and the
* destination project are handled according to the Synchronize folder
locations in source and destination for migrated objects preference in
the Migration category in the Object Manager Preferences dialog box.
7
If the package made any changes to the project schema, you may need to
update the schema for the changes to take effect. To update the project
schema, from the Object Manager Project menu, select Update Schema.
To import an update package from the command line
Call the Import Package executable, MAImportPackage.exe. By default,
this file is located in C:\Program Files (x86)\Common
Files\MicroStrategy. Use the following parameters:
Only Standard Authentication and Windows Authentication are
* supported by the Import Package utility.
Effect
Parameter
Import package into this project source (required)
-n
ProjectSourceName
Log into the project source with this MicroStrategy username and
password, using standard authentication (required unless you are
using Windows authentication)
-u UserName
Import this package into the specified project source (required)
-f
PackageLocation
Note: The location must be specified relative to the Intelligence
Server machine, not relative to the machine running the Import
Package utility.
-p Password
Import the package into this project (required for project update
packages)
-j ProjectName
Log information about the import process to this file
-l LogLocation
Note: The location of the log file must be specified relative to the
machine running the Import Package utility.
Force a configuration or project lock prior to importing the package.
This lock is released after the package is imported. For more
information about project and configuration locking, see Locking
projects, page 253.
-forcelocking
A full list of parameters can be accessed from a command prompt by entering
importpackage.exe -h.
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
287
System Administration Guide
To import an update package using an XML file
Create the XML file
1
In Object Manager, log in to the destination project or project source.
2
From the Tools menu, select Import Package (for a project update package)
or Import Configuration Package (for a configuration update package). The
Import Package or Import Configuration Package dialog box opens.
3
In the Selected Package field, type the name and path of the update
package, or click ... (the browse button) to browse to the update package.
4
Select the Save import package XML file check box.
5
Click Proceed. You are prompted to type the name and location of the
XML file. By default, this is the same as the name and location of the
package file, with an .xml extension instead of .mmp. Click Save. The XML
file is saved.
Import the package from the command line
6
When you are ready to import the update package, call the Project Merge
executable, projectmerge.exe, with the following parameters:
Effect
Parameter
Use this XML file to import an update package (required)
-f
Filename.xml
Log into the project source with this password (the login ID to be used is stored in
the XML file)
spPassword
Log into the project with this password (the login ID to be used is stored in the
XML file)
smp
Password
Suppress status updates (useful for importing an update package in the
background, so that the status window does not appear)
-sup
To import an update package using Command Manager
Call a Command Manager script that contains the following command:
IMPORT PACKAGE “Filename.mmp” [FOR PROJECT
“ProjectName”];
288
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
where “Filename” is the name and location of the update package, and
“ProjectName” is the name of the project that the update is to be
applied to.
If the package made any changes to the project schema, you need to
* update the schema for the changes to take effect. The syntax for
updating the schema in a Command Manager script is
UPDATE SCHEMA [REFRESHSCHEMA] [RECALTABLEKEYS]
[RECALTABLELOGICAL] [RECALOBJECTCACHE] FOR PROJECT
“ProjectName”;
Update packages and updating the project schema
If a project update package contains new or replacement schema objects, then
when the package is imported the user must update the in-memory definitions
of these objects. This is done by updating the project schema.
When you create an update package, you can configure it to automatically
perform the following schema update functions:
•
Recalculate table keys and fact entry levels, if you changed the key
structure of a table or if you changed the level at which a fact is stored.
•
Recalculate table logical sizes, to override any modifications that you have
made to logical table sizes. (Logical table sizes affect how the
MicroStrategy SQL Engine determines which tables to use in a query.)
The update package cannot recalculate the object client cache size, and it
cannot update the schema logical information. These tasks must be performed
manually. So, for example, if you import an attribute that has a new attribute
form, you must manually update the project schema before any objects in the
project can use that attribute form.
You can update the project schema in the following ways:
•
In Object Manager, select the project and, from the Project menu, select
Update Schema.
•
In Developer, log into the project and, from the Schema menu, select
Update Schema.
•
Call a Command Manager script with the following command:
UPDATE SCHEMA [REFRESHSCHEMA] [RECALTABLEKEYS]
[RECALTABLELOGICAL] [RECALOBJECTCACHE] FOR PROJECT
“projectname”;
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
289
System Administration Guide
*
Updating the schema can also be accomplished by unloading and reloading
the project. For information on loading and unloading projects, see Setting
the status of a project, page 29.
For more detailed information about updating the project schema, see the
Optimizing and Maintaining your Project chapter in the MicroStrategy
Project Design Guide.
Rolling back changes: Undo packages
You can use undo packages to roll back the changes made by an update
package. An undo package is an automatically created update package
consisting of all the objects in an update package, as they are currently
configured in the destination project. For example, if you create an undo
package for an update package containing a new version of three metrics, the
undo package contains the version of those three metrics that currently exists
in the destination project.
When you import an update package, you have the option of creating an undo
package at the same time as the import. Alternately, you can choose to create
an undo package without importing the associated update package.
You import an undo package in the same way as you import any update
package. When you import an undo package, the Version ID and Modification
Date of all objects in the undo package are restored to their values before the
original update package was imported.
The Intelligence Server change journal records the importing of both the
* original update package and the undo package. Importing an undo package
does not remove the change journal record of the original update package.
For more information about the change journal, see Monitoring system
activity: Change journaling, page 307.
Merging projects to synchronize objects
You can use MicroStrategy Project Merge to synchronize a large number of
objects between projects. Project Merge streamlines the task of migrating
objects from one project to another. While you can use Object Manager to
copy objects individually, Project Merge can be used as a bulk copy tool. For
differences between Object Manager and Project Merge, see Comparing
Project Merge to Object Manager, page 252.
The rules that you use to resolve conflicts between the two projects in Project
Merge can be saved to an XML file and reused. You can then execute Project
290
Copying objects in a batch: Update packages
© 2015, MicroStrategy Inc.
System Administration Guide
Merge repeatedly using this rule file. This allows you to schedule a project
merge on a recurring basis. For more details about scheduling project merges,
see Scheduling a project merge, page 296.
Project Merge migrates an entire project. All objects are copied to the
destination project. Any objects that are present in the source project but not
the destination project are created in the destination project.
Note the following:
*•
If you want to merge two projects, MicroStrategy recommends that the
projects have related schemas. This means that either one project must
be a duplicate of the other, or both projects must be duplicates of a
third project. For information about duplicating projects, including
instructions, see Duplicating a project, page 245.
•
To merge two projects that do not have related schemas, the projects
must either have been created with MicroStrategy 9.0.1 or later, or
have been updated to version 9.0.1 or later using the Perform system
object ID unification option. For information about this upgrade, see the
MicroStrategy Upgrade Guide.
•
Project Merge does not transfer user and group permissions on objects.
To migrate permissions from one project to another, use a project
security update package. For more information, see Updating project
access information for users and groups, page 274.
Projects may need to be merged at various points during their life cycle. These
points may include:
•
Migrating objects through development, testing, and production projects as
the objects become ready for use.
•
Receiving a new version of a project from a project developer.
In either case, you must move objects from development to testing, and then
to the production projects that your users use every day.
Topics covered in this section include:
•
What happens when you merge projects, page 292
•
Merging projects with the Project Merge Wizard, page 292
•
Running Project Merge from the command line, page 294
•
Scheduling a project merge, page 296
•
Resolving conflicts when merging projects, page 297
© 2015, MicroStrategy Inc.
Copying objects in a batch: Update packages
291
System Administration Guide
What happens when you merge projects
Project Merge requires a source project, a destination project, and a set of
rules to resolve object conflicts between the two projects. This set of rules is
defined in the Project Merge Wizard or loaded from an XML file.
In the MicroStrategy system, every object has an ID (or GUID) and a version.
(To see the ID and version of an object, right-click the object and select
Properties.) Project Merge checks the destination project for the existence of
every object in the source project, by ID. The resulting possibilities are
described below:
•
If an object ID does not exist in the destination project, the object is copied
from the source project to the destination project.
•
If an object exists in the destination project and has the same object ID and
version in both projects, the objects are identical and a copy is not
performed.
•
If an object exists in the destination project and has the same object ID in
both projects but a different version, there is a conflict that must be
resolved. The conflict is resolved by following the set of rules specified in
the Project Merge Wizard and stored in an XML file. The possible conflict
resolutions are discussed in Project Merge conflict resolution rules, page
297.
Merging projects with the Project Merge Wizard does not update the
* modification date of the project, as shown in the Project Configuration
Editor. This is because, when copying objects between projects, only the
objects themselves change. The definition of the project itself is not
modified by Project Merge.
Merging projects with the Project Merge Wizard
The Project Merge Wizard allows you to specify rules and settings for a project
merge. For details about all settings available when running the wizard, see
the Help. For information about the rules for resolving conflicts, see Resolving
conflicts when merging projects, page 297.
After going through the steps in the wizard, you can either execute the merge
right away or save the rules and settings in a Project Merge XML file. You can
use this file to run Project Merge from the Windows command prompt (see
Running Project Merge from the command line, page 294) or to schedule a
merge (see Scheduling a project merge, page 296).
Before you use Project Merge in a server (three-tier) environment, check
* the project source time out setting. In Developer, right-click on the project
292
What happens when you merge projects
© 2015, MicroStrategy Inc.
System Administration Guide
source and select Modify Project Source to open the Project Source
Manager. On the Connection tab, either disable the Connection times out
after setting by clearing its check box, or else enter a sufficient number of
minutes for when the connection should time out, considering how long the
merge processes may take based on the size of the projects. If you are
unsure about a setting and have noticed other processes taking a long time,
it is recommended you disable the time out setting.
The following scenario runs through the Project Merge Wizard several times,
each time fine-tuning the rules, and the final time actually performing the
merge.
To safely perform a project merge
Both the source and the destination project must be loaded for the project
* merge to complete. For more information on loading projects, see Setting
the status of a project, page 29.
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Tools, and then select Project Merge Wizard. The Project Merge Wizard
opens.
2
Follow the steps in the wizard to set your options and conflict resolution
rules.
For details about all settings available when running the wizard, see the
* Help (press F1 from within the Project Merge Wizard). For information
about the rules for resolving conflicts, see Resolving conflicts when
merging projects, page 297.
3
Near the end of the wizard, when you are prompted to perform the merge
or generate a log file only, select Generate log file only. Also, choose to
Save Project Merge XML. At the end of the wizard, click Finish. Because you
selected to generate a log file only, this serves as a trial merge.
4
After the trial merge is finished, you can read through the log files to see
what would have been copied (or not copied) if the merge had actually
been performed.
5
Based on what you learn from the log files, you may wish to change some
of the conflict resolution rules you set when going through the wizard. To
do this, run the wizard again and, at the beginning of the wizard, choose to
Load Project Merge XML that you created in the previous run. As you
proceed through the wizard, you can fine-tune the settings you specified
earlier. At the end of the wizard, choose to Generate the log file only
(thereby performing another trial) and choose Save Project Merge XML.
© 2015, MicroStrategy Inc.
Merging projects with the Project Merge Wizard
293
System Administration Guide
Repeat this step as many times as necessary until the log file indicates that
objects are copied or skipped as you desire.
6
When you are satisfied that no more rule changes are needed, run the
wizard a final time. At the beginning of the wizard, load the Project Merge
XML as you did before. At the end of the wizard, when prompted to
perform the merge or generate a log file only, select Perform merge and
generate log file.
Running Project Merge from the command line
A Project Merge can be launched from the Windows command line. You can
also run several sessions of the Project Merge Wizard with the same source
project, using the command prompt. For information on running multiple
sessions, see Multiple project merges from the same project, page 295.
The settings for this routine must be saved in an XML file which can easily be
created using the Project Merge Wizard. Once created, the XML file serves as
the input parameter to the command.
The syntax for the projectmerge.exe command is shown below. The syntax
for the command is simplified.
projectmerge -f[ ] -sp[ ] -dp[ ] -smp[ ] -dmp[ ] -sup[ ]
-MD -SU -lto -h
All command line parameters are described in the table below.
Parameter
Description and use
-f[ ]
Specifies the path and file name (without spaces) of the XML file to use. (You must have already
created the file using the Project Merge Wizard.) Example: -fc:\files\merge.xml
-sp[ ]
Password for SOURCE Project Source. (The login ID to be used is stored in the XML file.) Example:
-sphello
294
-dp[ ]
Password for DESTINATION Project Source. (The login ID to be used is stored in the XML file.)
Example: -dphello
-smp[ ]
Password for SOURCE metadata. (The login ID to be used is stored in the XML file.) Example: -
-dmp[ ]
Password for DESTINATION metadata. (The login ID to be used is stored in the XML file.) Example:
-sup
Suppress progress window. This is useful for running a project merge in the background, and the
window displaying status of the merge does not appear.
-MD
Forces metadata update of DESTINATION metadata if it is older than the SOURCE metadata.
Project Merge will not execute unless DESTINATION metadata is the same version as or more
recent than SOURCE metadata.
smphello
-dmphello
Merging projects with the Project Merge Wizard
© 2015, MicroStrategy Inc.
System Administration Guide
Parameter
Description and use
-SU
Updates the schema of the DESTINATION project after the Project Merge is completed. This update
is required when you make any changes to schema objects (facts, attributes, or hierarchies).
Note: Do not use this switch if the Project Merge configuration XML contains an instruction to
update the schema.
-lto
Take ownership of any metadata locks that exist on the source or destination projects. For more
information about metadata locking, see Locking projects, page 253.
-h
Displays help and explanations for all of the above parameters.
A sample command using this syntax is provided below. The command
assumes that “hello” is the password for all the project source and database
connections. The login IDs used with these passwords are stored in the XML
file created by the Project Merge Wizard.
projectmerge -fc:\temp\merge.xml -sphello -dphello smphello -dmphello -lto -MD -SU
If the XML file contains a space in the name or the path, you must enclose
* the name in double quotes, such as:
projectmerge -f “c:program files (x86)\xml\
merge.xml” -sphello -dphello -smphello -dmphello -MD
-SU
Multiple project merges from the same project
The Project Merge Wizard can perform multiple simultaneous merges from
the same project source. This can be useful when you wish to propagate a
change to several projects simultaneously.
During a multiple merge, the Project Merge Wizard is prevented from
~ locking the projects. This is so that multiple sessions of the wizard can
access the source projects. You will need to manually lock the source
project before beginning the merge. You will also need to manually lock
the destination projects at the configuration level before beginning the
merge. Failing to do this may result in errors in project creation due to
objects being changed in the middle of a merge. For information on locking
and unlocking projects, see Locking projects, page 253. For detailed
instructions on how to manually lock and unlock projects, see the
MicroStrategy Developer Help.
To do this, you must modify the Project Merge XML file, and then make a
copy of it for each session that you want to run.
© 2015, MicroStrategy Inc.
Merging projects with the Project Merge Wizard
295
System Administration Guide
To execute multiple simultaneous merges from one project
1
In a text editor, open the Project Merge Wizard XML file.
2
In the OMOnOffSettings section of the file, add the following node:
<Option><ID>OMOnOffSettings</ID><SkipProjectMergeSourc
eLockingSkipProjectMergeDestConfigLocking/></Option>.
3
Make one copy of the XML file for each session of the Project Merge
Wizard you wish to run.
4
In each XML file, make the following changes:
•
Correct the name of the destination project.
•
Ensure that each file uses a different Project Merge log file name.
5
Manually lock the source project. For detailed steps on locking projects
manually, see the MicroStrategy Developer Help.
6
Manually lock the destination projects at the configuration level. For
detailed steps on locking projects manually, see the MicroStrategy
Developer Help.
7
For each XML file, run one instance of the Project Merge Wizard from the
command line.
Scheduling a project merge
To schedule a delayed or recurring Project Merge, use the AT command, which
is part of the Microsoft Windows operating system. For instructions on how to
use the AT command, refer to the Microsoft Windows help. The sample AT
command below schedules Project Merge to run at 6:00 PM (18:00) every
Friday (/every:F).
at 18:00 /every:F projectmerge -fc:\temp\merge.xml sphello -dphello -smphello -dmphello -MD -SU
For a list of the syntax options for this command, see Running Project Merge
from the command line, page 294.
To schedule a project merge using the Windows command prompt
296
1
From the Microsoft Windows machine where Project Merge is installed,
from the Start menu, select Programs, then choose Command Prompt.
2
Change the drive to the one on which the Project Merge utility is installed.
The default installation location is the C: drive (the prompt appears as:
C:\>)
Merging projects with the Project Merge Wizard
© 2015, MicroStrategy Inc.
System Administration Guide
3
Type an AT command that calls the projectmerge command. For a list
of the syntax options for this command, see Running Project Merge from
the command line, page 294.
Resolving conflicts when merging projects
Conflicts occur when a destination object’s version differs from the source
object’s version. This difference usually means that the object has been
modified in one or both of the projects. These conflicts are resolved by
following a set of rules you define as you step through the Project Merge
Wizard.
When you define the rules for Project Merge to use, you first set the default
conflict resolution action for each category of objects (schema, application, and
configuration). (For a list of objects included in each category, see click here.)
Then you can specify conflict resolution rules at the object type level
(attributes, facts, reports, consolidations, events, schedules, and so on). Object
type rules override object category rules. Next you can specify rules for specific
folders and their contents, which override the object type and object category
rules. Finally you can specify rules for specific objects, which, in turn, override
object type rules, object category rules, and folder rules.
For example, the Use Newer action replaces the destination object with the
source object if the source object has been modified more recently than the
destination object. If you specified the Use newer action for all metrics, but the
Sales metric has been changed recently and is not yet ready for the production
system, you can specify Use existing (use the object in the destination project)
for that metric only and it will not be replaced.
Project Merge conflict resolution rules
If the source object has a different version than the destination object, that is,
the objects exist differently, you must determine what action should occur. The
various actions that can be taken to resolve conflicts are explained in the table
below.
Action
Effect
Use
existing
No change is made to the destination object. The source object is not copied.
Replace
The destination object is replaced with the source object.
Note: Non-empty folders in the destination location will never have the same version ID and
modification time as the source, because the folder is copied first and the objects are added to it, thus
changing the version ID and modification times during the copy process.
Keep
both
No change is made to the destination object. The source object is duplicated in the destination
location.
© 2015, MicroStrategy Inc.
Resolving conflicts when merging projects
297
System Administration Guide
Action
Effect
Use
newer
If the source object’s modification time is more recent than the destination object’s, the Replace
action is used. Otherwise, the Use existing action is used.
Use
older
If the source object’s modification time is more recent than the destination object’s, the Use existing
action is used. Otherwise, the Replace action is used.
Comparing and tracking projects
Often during the project life cycle, you do not know exactly which objects need
to be moved from one project to another. This is because there are many
developers working on a project and it is difficult for a single person to know
all of the work that has been done. The migration process becomes much
easier if you first compare objects in the source and destination projects.
You can use the MicroStrategy Project Comparison Wizard to compare objects
in related projects. This wizard tells you which objects are different between
the two projects, and which objects exist in one project but not in the other.
From this list you can decide what objects to move between projects, using
Object Manager. For instructions on moving objects with Object Manager, see
Copying objects between projects: Object Manager, page 254.
You can track changes to your projects with the MicroStrategy Search feature,
or retrieve a list of all unused objects in a project with the Find Unreferenced
Objects feature of Object Manager.
This section covers the following topics:
•
Comparing objects between two projects, page 298
•
Tracking your projects with the Search Export feature, page 300
•
Listing unused objects in a project, page 301
Comparing objects between two projects
The Project Comparison Wizard compares objects in a source project and a
destination project.
For the source project, you specify whether to compare objects from the entire
project, or just from a single folder and all its subfolders. You also specify
what types of objects (such as reports, attributes, or metrics) to include in the
comparison.
Every object in a MicroStrategy project has a unique ID. Project Comparison
looks at each object ID in the source project, and compares it to the object in
298
Comparing objects between two projects
© 2015, MicroStrategy Inc.
System Administration Guide
the destination project with the same ID. For each object ID, Project
Comparison indicates whether the object is:
•
Identical in both projects
•
Identical in both projects except for the folder path
•
Only present in the source or destination project
•
Different between projects, and newer in the source or destination project
You can print this result list, or save it as a text file or an Excel file.
Since the Project Comparison Wizard is a part of Object Manager, you can also
select objects from the result set to immediately migrate from the source
project to the destination project. For more information about migrating
objects using Object Manager, see Copying objects between projects: Object
Manager, page 254.
Using the Project Comparison Wizard
The following high-level procedure provides an overview of what the Project
Comparison Wizard does. For an explanation of the information required at
any given page in the wizard, see the Help (from the wizard, click Help, or
press F1).
To compare two projects
Note the following:
*•
•
To compare two projects with the Project Comparison Wizard, those
projects must have related schemas. This means that either one project
must be a duplicate of the other, or both projects must be duplicates of
a third project. For information about duplicating projects, including
instructions, see Duplicating a project, page 245.
The Project Comparison Wizard is a part of Object Manager, and thus
requires the Use Object Manager privilege to run. For an overview of
Object Manager, see Copying objects between projects: Object
Manager, page 254.
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Products, and then select Object Manager. Object Manager opens.
2
Open a project source in Object Manager.
3
From the Project menu, select Compare Projects. The Project Comparison
Wizard opens.
4
Select the source and destination projects.
© 2015, MicroStrategy Inc.
Comparing objects between two projects
299
System Administration Guide
5
Specify whether to compare all objects or just objects in a specific folder,
and what types of objects to compare.
6
Review your choices at the summary screen and click Finish. The objects in
the two projects are compared and the Project Comparison Result Set
dialog opens. This dialog lists all the objects you selected and the results of
their comparison.
7
To save the results, from the File menu select Save as Text File or Save as
Excel File.
8
To migrate objects from the source project to the destination project using
Object Manager, select those objects in the list and click Proceed. For
more information about Object Manager, see Copying objects between
projects: Object Manager, page 254.
Tracking your projects with the Search Export feature
Exporting the results of a search object can be a useful way to keep track of
changes to a project. The Search Export feature enables you to perform a
search for either a specific object in a project or for a group of objects that
meet certain criteria. After the search is performed, you can save your search
definition and search results to a text file, and save the search object itself for
later reuse.
For example, you can create a search object in the development project that
returns all objects that have been changed after a certain date. This lets you
know what objects have been updated and need to be migrated to the test
project. For more information about development and test projects, see The
project life cycle, page 240.
The search export file contains the following information:
300
•
The user who was logged in when the search was performed.
•
The search type, date and time, and project name.
•
Any search criteria entered into the tabs of the Search for Objects dialog
box.
•
Any miscellaneous settings in Developer that affected the search (such as
whether hidden and managed objects were included in the search).
•
A list of all the objects returned by the search, including any folders. The
list includes object names and paths (object locations in the Developer
interface).
Tracking your projects with the Search Export feature
© 2015, MicroStrategy Inc.
System Administration Guide
To search for objects and save the results in a text file
1
In Developer, from the Tools menu, select Search for Objects. The Search
for Objects dialog box opens.
2
Perform your search. For information on how to configure a search in
Developer, see the MicroStrategy Developer Help.
3
After your search is complete, from the Tools menu in the Search for
Objects dialog box, select Export to Text. The text file is saved by default to
C:\Program Files (x86)\MicroStrategy\Desktop\
SearchResults_<date and timestamp>.txt, where <date and
timestamp> is the day and time when the search was saved. For example,
the text file named SearchResult_022607152554.txt was saved on
February 26, 2007, at 15:25:54, or 3:25 PM.
Listing unused objects in a project
In Object Manager, you can retrieve a list of all the objects in a project that
are not used by any other objects. For example, you can find which attributes
or metrics are no longer used in any reports, so that you can delete those
objects.
To find unused objects
Finding unused objects is a part of Object Manager, and thus requires the
* Use Object Manager privilege to run. For an overview of Object Manager,
see Copying objects between projects: Object Manager, page 254.
1
From the Windows Start menu, point to All Programs, then MicroStrategy
Products, and then select Object Manager. Object Manager opens.
2
Open a project source in Object Manager.
3
From the Tools menu, select Find Unreferenced Objects. The Search for
Objects dialog box opens.
4
In the Look In field, enter the folder you want to start your search in.
5
Make sure the Include Subfolders check box is selected.
6
Click Find Now. The unused objects are listed at the bottom of the dialog
box.
© 2015, MicroStrategy Inc.
Listing unused objects in a project
301
System Administration Guide
Deleting unused schema objects: managed
objects
MicroStrategy projects contain schemas and related schema objects, including
attributes, tables, hierarchies, and so on. For an introduction to schema
objects, see the MicroStrategy Project Design Guide.
Certain MicroStrategy features automatically create new schema objects,
referred to as managed objects, which are not directly related to the project
schema. The features that create their own managed objects are:
•
Freeform SQL and Query Builder. For information on Freeform SQL and
Query Builder, see the MicroStrategy Advanced Reporting Guide.
•
MDX cube sources such as SAP BW, Hyperion Essbase, Microsoft Analysis
Services, and IBM Cognos TM1. For information on MDX cube sources, see
the MicroStrategy MDX Cube Reporting Guide.
•
Import Data, which lets you use MicroStrategy Web to import data from
different data sources, such as an Excel file, a table in a database, or the
results of a SQL query, with minimum project design requirements. For
more information on how to use the Import Data feature, refer to the
MicroStrategy Web Help.
Managed objects are stored in a special system folder, and can be difficult to
delete individually due to how these objects are created and stored. If you use
one of the features listed above, and then decide to remove some or all of that
feature’s related reports and MDX cubes from the project, there may be
unused managed objects included in your project that can be deleted.
This section covers the following topics:
•
Deleting managed objects one-by-one, page 302
•
Deleting all unused managed objects, page 303
Deleting managed objects one-by-one
When you delete managed objects one-by-one, you individually select which
managed objects you want to delete and which you want to keep. You can
perform this clean-up for any of the Freeform SQL, Query Builder, or MDX
cube source database instances included for your project.
For example, you decide to delete a single Freeform SQL report that
automatically created a new managed object named Store. When you delete
the report, the managed object Store is not automatically deleted. You do not
plan to use the object again; however, you do plan to create more Freeform
SQL reports and want to keep the database instance included in the project.
302
Deleting managed objects one-by-one
© 2015, MicroStrategy Inc.
System Administration Guide
Instead of deleting the entire Freeform SQL schema, you can delete only the
managed object Store.
To delete managed objects one-by-one
1
In Developer, delete any Freeform SQL, Query Builder, or MDX cube
reports in the project that depend on the managed objects you want to
delete.
If you are removing MDX cube managed objects, you must also remove any
MDX cubes that these managed objects depend on.
2
Right-click the project and select Search for Objects. The Search for Objects
dialog box opens.
3
From the Tools menu, select Options. The Search Options dialog box opens.
4
Select the Display managed objects and Display managed objects only check
boxes.
5
Click OK to return to the Search for Objects dialog box.
6
Enter your search criteria and select Find Now. A list of managed objects
appears.
7
Manually delete managed objects by right-clicking their name in the search
result and selecting Delete.
Deleting all unused managed objects
Managed objects can become unused in a project when you stop using the
feature that created the managed objects. You can delete all unused managed
objects to clean up your project.
For example, you can create a separate database instance for your Freeform
SQL reports in your project. Later on, you may decide to no longer use
Freeform SQL, or any of the reports created with the Freeform SQL feature.
After you delete all the Freeform SQL reports, you can remove the Freeform
SQL database instance from the project. Once you remove the database
instance from the project, any Freeform SQL managed objects that depended
solely on that database instance can be deleted.
You can implement the same process when removing database instances for
Query Builder, SAP BW, Essbase, and Analysis Services.
© 2015, MicroStrategy Inc.
Deleting all unused managed objects
303
System Administration Guide
To delete all unused managed objects from a project
1
Remove all reports created with Freeform SQL, Query Builder, or MDX
cubes.
If you are removing MDX cube managed objects, you must also remove
* all imported MDX cubes.
2
In Developer, right-click the project and select Project Configuration. The
Project Configuration Editor opens.
3
Expand the Database instances category.
4
Select either SQL data warehouses or MDX data warehouses, depending on
the database instance you want to remove.
Freeform SQL and Query Builder use relational database instances,
* while SAP BW, Essbase, and Analysis Services use MDX cube database
instances. For more information on the difference between the two, see
the MicroStrategy Installation and Configuration Guide.
5
Clear the check box for the database instance you want to remove from the
project. You can only remove a database instance from a project if the
database instance has no dependent objects in the project.
6
Click OK to accept the changes and close the Project Configuration Editor.
This procedure removes some preliminary object dependencies.
~ Attribute and metric managed objects are not automatically deleted by
this procedure, because you can reuse the managed attributes and
metrics at a later time. If you do not plan to use the attribute and
metric managed objects and want to delete them permanently from
your project, continue through the rest of this procedure.
To delete unused attribute and metric managed objects
7
304
In Developer, from the Administration menu, select Projects, and then
select Delete unused managed objects.
Deleting all unused managed objects
© 2015, MicroStrategy Inc.
7
MONITORING SYSTEM USAGE
Introduction
MicroStrategy provides several ways to track user activity, resource usage, and
performance in your system. These include the following:
•
MicroStrategy system monitors, page 305
•
Monitoring system activity: Change journaling, page 307
•
Monitoring system usage: Intelligence Server statistics, page 314
•
Additional monitoring tools, page 326
MicroStrategy system monitors
You can monitor various aspects of your MicroStrategy system from within
Developer. The Administration category for a project source contains several
system monitors for that project source. These monitors are listed in the table
below, and are described in detail in the relevant section of this guide.
© 2015, MicroStrategy Inc.
305
System Administration Guide
For information about monitoring...
See...
Projects loaded on Intelligence Server, or on all
nodes of the cluster
Managing and monitoring projects, page 26
Projects loaded on specific nodes of the cluster
Managing your projects across nodes of a
cluster, page 428
Jobs that are currently executing
Monitoring currently executing jobs, page 50
Users that are currently connected to Intelligence
Server
Monitoring users’ connections to projects, page
61
Active and cached database connections
Monitoring database instance connections, page
10
Report and document caches
Monitoring result caches, page 447
History List messages
Monitoring History List messages, page 481
Intelligent Cubes, whether they are loaded on
Intelligence Server
Managing Intelligent Cubes: Intelligent Cube
Monitor, page 500
Prerequisites
•
Before you can view a system monitor, you must have the appropriate
privilege to access that monitor. For example, to view the Job Monitor,
you must have the Monitor Jobs privilege. For more information about
privileges, see Controlling access to functionality: Privileges, page 72.
•
In addition, you must have Monitoring permission for the server definition
that contains that monitor. You can view and modify the ACL for the server
definition by right-clicking the Administration icon, selecting Properties,
and then selecting the Security tab. For more information about
permissions and ACLs, see Controlling access to objects: Permissions, page
63.
To view a system monitor
306
1
In Developer, log in to the project source that you want to monitor. You
must log in as a user with the appropriate administrative privilege.
2
Expand the Administration category.
3
To monitor projects or clusters, expand the System Administration category
and select either Project or Cluster Nodes.
4
To view additional system monitors, expand the System Monitors category
and select the desired monitor. For a list of the different monitors
available, and where you can find more information about each monitor,
see the table above.
© 2015, MicroStrategy Inc.
System Administration Guide
Monitoring system activity: Change journaling
Change journaling is the process of logging information about changes to
objects in a project. Change journaling tracks the changes to each object in the
system. This makes it easier for administrators to quickly determine when and
by whom certain changes were made. For example, reports using a certain
metric executed correctly in a test two weeks ago, but no longer execute
correctly in this morning’s test. The administrator can search the change
journal to determine who has made changes to that metric within the last two
weeks.
The logged information includes items such as the user who made the change,
the date and time of the change, and the type of change (such as saving,
copying, or deleting an object). With change journaling, you can keep track of
all object changes, from simple user actions such as saving or moving objects
to project-wide changes such as project duplication or project merging.
Certain business regulations, such as Sarbanes-Oxley in the United States,
require detailed records of changes made to a BI system. Enabling change
journaling on all projects in your production environment can aid in
compliance with these regulations.
Enabling change journaling
When change journaling is enabled for a project or project source, Intelligence
Server logs information in the change journal about any change made to any
object in the project or project source. This includes changes made in
Developer or MicroStrategy Web as well as through other MicroStrategy tools
such as Command Manager or Project Merge.
You can enable change journaling for any number of projects in a project
source. For each project, when change journaling is enabled, all changes to all
objects in that project are logged.
You can also enable change journaling at the project source level. In this case
information about all changes to the project configuration objects, such as
users or schedules, is logged in the change journal.
By default, change journaling is enabled in all newly created projects and
project sources.
To enable or disable change journaling for a project source
1
In Developer, log in to a project source. You must log in as a user with the
Configure Change Journaling privilege.
© 2015, MicroStrategy Inc.
Enabling change journaling
307
System Administration Guide
2
Expand Administration, and then expand System Monitors.
3
Right-click Change Journal Transactions and select Manage Change Journal.
The Change Journal Manager opens.
4
To enable or disable change journaling for this project source, select or
clear the Enable change journaling check box.
5
In the Comments field, enter any comments that you may have about the
reason for enabling or disabling change journaling.
6
To enable or disable change journaling for all projects in the project
source, select the Apply to all projects check box. To determine which
projects have change journaling on a project-by-project basis, leave this
check box cleared.
7
Click OK. The Change Journal Manager closes. A transaction is logged in
the change journal for each project that enables or disables change
journaling.
To enable or disable change journaling for a project
308
1
From Developer, right-click the project and select Project Configuration.
The Project Configuration Editor opens.
2
Expand Project definition, and then select Change Journaling.
Enabling change journaling
© 2015, MicroStrategy Inc.
System Administration Guide
3
To enable or disable change journaling for this project, select or clear the
Enable Change Journaling check box.
4
Click OK. The Project Configuration Editor closes. A transaction is logged
in the change journal when this project enables or disables change
journaling.
Change journal comments
When change journaling is enabled, users are prompted for comments every
time they change an object. These comments can provide documentation as to
the nature of the changes made to objects.
You can disable the requests for object comments from the Developer
Preferences dialog box.
To disable the requests for change journaling comments
1
Open Developer.
2
From the Tools menu, select MicroStrategy Developer Preferences. The
Developer Preferences dialog box opens.
3
Expand Optional Actions, and then select General.
4
Clear the Display change journal comments input dialog check box.
5
Click OK. The Developer Preferences dialog box closes. You are no longer
prompted to enter a comment when you save objects.
Viewing the change journal entries
When an object is changed, information about the change is entered in the
change journal. To view the change journal for all projects in a project source,
in Developer, expand Administration, then expand System Monitors, and then
select Change Journal Transactions. The change journal entries are listed in the
main window of Developer.
You must have the Audit Change Journal privilege to view the change
* journal.
To view the detailed information for a change journal entry, double-click that
entry. Each entry contains the following information:
© 2015, MicroStrategy Inc.
Viewing the change journal entries
309
System Administration Guide
Entry
Details
Object name
The name of the object that is changed.
Object type
The type of object changed. For example, Metric, User, or Server Definition.
User name
The name of the MicroStrategy user that made the change.
Transaction
timestamp
The date and time of the change, based on the time on the Intelligence Server machine.
Transaction type
The type of change and the target of the change. For example, Delete Objects, Save
Objects, or Enable Logging.
Transaction
source
The application that made the change. For example, Developer, Command Manager,
MicroStrategy Web, or Scheduler.
Project name
The name of the project that contains the object that was changed.
Note: If the object is a configuration object, the project name is listed as <Configuration>
Comments
Any comments entered in the Comments dialog box at the time of the change.
Object ID
The object’s GUID, a unique MicroStrategy system identifier.
Machine name
The name of the machine that the object was changed on.
Change type
The type of change that was made. For example, Create, Change, or Delete.
Transaction ID
A unique 32-digit hexadecimal number that identifies this change.
Session ID
A unique 32-digit hexadecimal number that identifies the user session in which the change
was made.
Link ID
For MicroStrategy use.
This information can also be viewed in the columns of the change journal. To
change the visible columns, right-click anywhere in the change journal and
select View Options. In the View Options dialog box, select the columns you
want to see.
Increasing the number of change journal entries to
view or export
By default the change journal displays and exports the last 1,000 entries. You
can increase this number in the Browsing category of the Developer
Preferences dialog box. Viewing more entries may make the browsing and
exporting process take longer.
310
Increasing the number of change journal entries to view or export
© 2015, MicroStrategy Inc.
System Administration Guide
To increase the number of displayed or exported change journal
entries
1
In Developer, from the Tools menu select MicroStrategy Developer
Preferences. The Developer Preferences dialog box opens.
2
In the General category, select Browsing.
3
In the Maximum number of monitoring objects displayed per page field,
specify the maximum number of change journal entries to display.
4
In the Maximum number of transactions retrieved per metadata change
journaling search field, specify the maximum number of change journal
entries to export.
5
Click OK. The dialog box closes and your changes are saved.
Searching the change journal for relevant entries
Because the change journal records every transaction, finding the relevant
records can be daunting. To make searching the change journal easier, you can
filter it so that you see the relevant entries.
For example:
•
To find out when certain users were given certain permissions, you can
view entries related to Users.
•
To discover which user made a change that caused a report to stop
executing correctly, you can view the entries related to that report.
You can also quickly filter the entries so that you see the entries for an object
or the changes made by a specific user. To do this, right-click one of the
entries for that object or that user and select either Filter view by object or
Filter view by user. To remove the filter, right-click in the change journal and
select Clear filter view.
To filter the change journal for relevant entries
1
In the Change Journal Transactions Monitor, right-click and select Filter.
The Change Journal Monitor Filter dialog box opens.
2
To filter the change journal by changed object type, project, transaction
type, or source of the change, select from the appropriate drop-down list.
© 2015, MicroStrategy Inc.
Searching the change journal for relevant entries
311
System Administration Guide
3
To filter the change journal by multiple conditions, click Advanced. The
advanced filtering options panel opens at the bottom of the dialog box.
Enter the columns and conditions.
4
To see changes made in a specific time range, enter the start and end time
and date.
5
To view all transactions, not just those that change the version of an object,
clear the Show version changes only and Hide Empty Transactions check
boxes.
If the Show version changes only check box is cleared, two transactions
* named “LinkItem” are listed for every time an application object is
saved. These transactions are monitored for MicroStrategy technical
support use and do not indicate that the application object has been
changed. Any time the object has actually been changed, a SaveObjects
transaction with the name of the application object is listed.
6
Click OK to close the dialog box and filter the change journal.
To quickly filter the change journal by object or user
1
2
In the Change Journal Transactions Monitor, right-click an entry for the
object or user you want to filter by, and select the type of filtering:
•
To see the changes to this object, select Filter view by object.
•
To see the changes made by this user, select Filter view by user.
To remove a quick filter, right-click in the change journal and select Clear
filter view.
Exporting the change journal
You can export the contents of the change journal to a text file. This can be
useful so that you can save this file to an archival location, or email it to
MicroStrategy technical support for assistance with a problem.
The name of this file is AuditLog_MMDDYYhhmmss.txt, where MMDDYY is
the month, date, and last two digits of the year, and hhmmss is the timestamp,
in 24-hour format. This file is saved in the MicroStrategy Common Files
directory. By default this directory is C:\Program Files (x86)\Common
Files\MicroStrategy\.
When you export the change journal, any filters that you have used to view
~ the results of the change journal are also applied to the export. If you want
312
Exporting the change journal
© 2015, MicroStrategy Inc.
System Administration Guide
to export the entire change journal, make sure that no filters are currently
in use. To do this, right-click in the change journal and select Clear filter
view.
To export the change journal to a file
1
In Developer, expand Administration, and then expand System Monitors.
2
Right-click Change Audit and select Export list. The change journal is
exported to a text file.
A prompt is displayed informing you that the list was exported and noting the
folder and file name, and asks if you want to view the file. To view the file,
click Yes.
Purging the change journal
You can keep the size of the change journal to a manageable size by
periodically purging older entries that you no longer need to keep.
When you purge the change journal, you specify a date and time. All entries in
the change journal that were recorded prior to that date and time are deleted.
You can purge the change journal for an individual project, or for all projects
in a project source.
MicroStrategy recommends archiving your change journal entries before
~ purging. For instructions on how to archive the change journal, see
Exporting the change journal, page 312.
To purge the change journal for all projects in a project source
1
In Developer, expand Administration, and then expand System Monitors.
2
Right-click Change Journal Transactions and select Manage change journal.
The Change Journal Manager opens.
3
Set the date and time. All data recorded before this date and time is
deleted from the change journal.
4
To purge data for all projects, select the Apply to all projects check box. To
purge data relating to the project source configuration, leave this check box
cleared.
© 2015, MicroStrategy Inc.
Purging the change journal
313
System Administration Guide
5
Click Purge Now. When the warning dialog box opens, click Yes to purge
the data, or No to cancel the purge. If you click Yes, change journal
information recorded before the specified date is deleted.
If you are logging transactions for this project source, a Purge Log
* transaction is logged when you purge the change journal.
6
Click Cancel. The Change Journal Manager closes.
To purge the change journal for a single project
1
In Developer, right-click on the project and select Project Configuration.
The Project Configuration Editor for that project opens.
2
Expand Project definition, and then select Change Journaling.
3
Under Purge Change Journal, set the date and time. All change journal data
for this project from before this date and time will be deleted from the
change journal.
4
In the Purge timeout (seconds) field, specify the timeout setting in seconds.
5
Click Purge Now. When the warning dialog box opens, click Yes to purge
the data, or No to cancel the purge. If you click Yes, change journal
information for this project from before the specified date and time is
deleted.
6
Click OK. The Project Configuration Editor closes.
Monitoring system usage: Intelligence Server
statistics
To tune your system for best performance, you need information about how
the system is being used. Intelligence Server can record usage and performance
statistics for each project in your system. You can then analyze these statistics
to determine what changes need to be made.
This section provides the following information about Intelligence Server
statistics:
314
•
Overview of Intelligence Server statistics, page 315
•
Best practices for recording Intelligence Server statistics, page 319
•
Configuring Intelligence Server to log statistics, page 320
Purging the change journal
© 2015, MicroStrategy Inc.
System Administration Guide
*
MicroStrategy Enterprise Manager can help you analyze the Intelligence
Server statistics data. Enterprise Manager consists of a MicroStrategy
project containing a wide variety of reports and dashboards that present
the statistics data in an easy-to-understand format. For more information
about Enterprise Manager, see the Enterprise Manager chapter in the
MicroStrategy Operations Manager Guide.
Overview of Intelligence Server statistics
Intelligence Server can record a wide variety of statistics relating to user
activity, data warehouse activity, report SQL, and system performance. These
statistics are logged in the statistics database (see The statistics database,
page 317).
The statistics that are logged for each project are set in the Project
Configuration Editor, in the Statistics: General subcategory. The options are as
follows:
Statistics logging option
Statistics logged
All basic statistics
User session and project session analysis. This option must be selected for any
statistics to be logged.
Report job steps
Detailed statistics on the processing of each report.
Document job steps
Detailed statistics on the processing of each document.
Report job SQL
The generated SQL for all report jobs.
Warning : This option can create a very large statistics table. Select this
option when you need the job SQL data.
Report job tables/columns
accessed
Data warehouse tables and columns accessed by each report.
Mobile Clients
Detailed statistics on reports and documents that are executed on a mobile
device.
Mobile Clients Manipulations
Detailed statistics on actions performed by end users on a mobile client.
This option is available if
Mobile Clients is selected
Only purge statistics logged
from the current Intelligence
Server.
Purge statistics from the database if they are from the Intelligence Server you
are now using. This is applicable if you are using clustered Intelligence
Servers.
You can log different statistics for each project. For example, you may want to
log the report job SQL for your test project when tracking down an error. If
you logged report job SQL for your production project, and your users are
running many reports, the statistics database would quickly grow to an
unwieldy size.
© 2015, MicroStrategy Inc.
Overview of Intelligence Server statistics
315
System Administration Guide
Recording performance counters in the statistics tables
Intelligence Server can be configured to collect performance information from
the Diagnostics and Performance Logging Tool and record that information in
the statistics database. For more information about logging performance
counters, see Performance configuration, page 806.
Intelligence Server can collect and log information from the MicroStrategy
Server Jobs and MicroStrategy Server Users categories. On UNIX or Linux,
Intelligence Server can also collect and log information from the following
categories:
•
Memory
•
System
•
Process
•
Processor
•
Network Interface
•
Physical Disk
This information is recorded in the STG_IS_PERF_MON_STATS table in the
statistics database.
To configure the performance counters to record information in the
statistics repository
1
Open the Diagnostics and Performance Logging Tool.
•
From Developer: From the Tools menu, select Diagnostics.
If the Diagnostics option does not appear on the Tools menu, it has not
* been enabled. To enable this option, from the Tools menu, select
MicroStrategy Developer Preferences. In the General category, in the
Advanced subcategory, select the Show Diagnostics Menu Option check
box and click OK.
316
•
In Windows: From the Windows Start menu, point to All Programs,
then MicroStrategy Tools, and then select Diagnostics Configuration.
•
In UNIX/Linux: Navigate to the directory ~/MicroStrategy/bin
and enter mstrdiag.
2
From the Select Configuration drop-down list, select CastorServer
Instance.
3
Select the Performance Configuration tab.
Overview of Intelligence Server statistics
© 2015, MicroStrategy Inc.
System Administration Guide
4
Make sure the Use Machine Default Performance Configuration check box is
cleared so that your logging settings are not overridden by the default
settings.
5
In the Statistics column, select the check boxes for the counters that you
want to log to the statistics repository.
6
In the Statistics Properties group, in the Logging Frequency (min), specify
how often (in minutes) you want the performance counters to log
information.
7
From the Persist statistics drop-down list, select Yes.
8
From the File menu, select Save. The changes that you have made to the
logging properties are saved.
The statistics database
Intelligence Server logs the specified statistics to the staging tables in the
statistics repository. For a detailed examination of the staging tables in the
statistics repository, see the Statistics Data Dictionary in the Supplemental
Reference for System Administration.
If you are using Enterprise Manager to monitor your statistics, the database
that hosts the staging tables also contains the Enterprise Manager data
warehouse. The information in the staging tables is processed and loaded into
the data warehouse as part of the data load process. For information about the
structure of the Enterprise Manager data warehouse, see the Enterprise
Manager Data Dictionary in the Supplemental Reference for System
Administration. For steps on configuring Enterprise Manager and scheduling
data loads, see the Enterprise Manager chapter in the MicroStrategy
Operations Manager Guide.
Intelligence Server may open up to one database connection for each project
that is configured to log statistics. For example, in a project source with four
projects, each of which is logging statistics, there may be up to four database
connections opened for logging statistics. However, the maximum number of
database connections is typically seen in high-concurrency environments.
In a clustered environment, each node of the cluster requires a database
* connection for each project loaded onto that node. For example, a two-
node cluster with 10 projects loaded on each node has 20 connections to
the warehouse (10 for each node). Even if the same 10 projects are loaded
on both nodes, 20 database connections exist.
Supported database platforms
MicroStrategy supports the following database platforms for use with
Intelligence Server statistics:
© 2015, MicroStrategy Inc.
Overview of Intelligence Server statistics
317
System Administration Guide
▫
SQL Server
▫
Oracle
▫
Teradata
▫
IBM DB2 UDB
▫
Sybase ASE
For information about the specific versions of each database that are
supported, see the MicroStrategy Readme.
Logging all statistics from a project source to the same database
By default, all projects for a project source must be configured to log statistics
individually. This configuration is called Complete Session Logging. It allows
some projects to log statistics to a database and some projects to log to
another database.
The Enterprise Manager data warehouse must be in the same database as
* the statistics repository for a project. If you are using Enterprise Manager
in a complete session logging configuration, there are as many Enterprise
Manager data warehouses as there are statistics repositories. A separate
Enterprise Manager project must be configured for each statistics
repository.
MicroStrategy recommends that you configure all projects in your project
source to log statistics to the same database. This is accomplished by
configuring your system to use Single Instance Session Logging. This can
minimize session logging and optimize system performance.
Under single instance session logging, you must still specify which statistics
are logged for each individual project in the project source, as described in
Overview of Intelligence Server statistics, page 315.
To use single instance session logging successfully, the selected single
~ instance session logging project must be loaded onto the Intelligence
Server at startup. If clustered Intelligence Servers are being used, the
project must be loaded onto all the clustered Intelligence Servers. Failing
to load this project on all servers at startup results in a loss of session
statistics for any Intelligence Server on which the project is not loaded at
startup. For details on the possible side effects of not loading all projects,
see MicroStrategy Tech Note TN14591.
318
Overview of Intelligence Server statistics
© 2015, MicroStrategy Inc.
System Administration Guide
To log all statistics from a project source to the same database
1
In Developer, right-click the project source and select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
2
On the left, expand Statistics, then select General.
3
Select the Single Instance Session Logging option.
4
Select a project from the drop-down list. The statistics for all projects on
this Intelligence Server are logged to the database instance specified for
this project.
5
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
Best practices for recording Intelligence Server
statistics
MicroStrategy recommends the following best practices for logging Intelligence
Server statistics:
•
Configure your system for single instance session logging, so that all
projects for a project source use the same statistics repository. This can
reduce duplication, minimize database write time, and improve
performance. For information about single instance session logging, see
Logging all statistics from a project source to the same database, page
318.
•
Use the sizing guidelines (see Sizing guidelines for the statistics repository,
page 319) to plan how much hard disk space you need for the statistics
repository.
•
Use Enterprise Manager to monitor and analyze the statistics information.
For more information about Enterprise Manager, see the Enterprise
Manager chapter in the MicroStrategy Operations Manager Guide.
Sizing guidelines for the statistics repository
The following guidelines can help you determine how much space you need for
the statistics repository. These guidelines are for planning purposes;
MicroStrategy recommends that you monitor the size of your statistics
repository and adjust your hardware requirements accordingly.
•
When the Basic Statistics, Report Job Steps, Document Job Steps, Report
SQL, Report Job Tables/Columns Accessed, and Prompt Answers statistics
© 2015, MicroStrategy Inc.
Best practices for recording Intelligence Server statistics
319
System Administration Guide
are logged, a user executing a report increases the statistics database size
by an average of 70 kilobytes.
This value assumes that large and complex reports are run as often as
small reports. In contrast, in an environment where more than 85 percent
of the reports that are executed return fewer than 1,000 cells, the average
report increases the statistics database size by less than 10 kilobytes.
•
When the Subscription Deliveries and Inbox Messages statistics are logged,
each subscription that is delivered increases the statistics database size by
less than 100 kilobytes. This is in addition to the database increase from
logging the report execution.
•
When performance counters are logged to the statistics database, each
performance counter value that is logged increases the database size by an
average of 0.4 kilobyte. You can control this table’s growth by specifying
what counters to log and how often to log each. For more information on
logging performance counters to the statistics database, including
instructions, see Recording performance counters in the statistics tables,
page 316.
To determine how large a database you need, multiply the space required for a
report by the number of reports that will be run over the amount of time you
are keeping statistics. For example, you may plan to keep the statistics
database current for six months and archive and purge statistics data that are
older than six months. You expect users to run an average of 400 reports per
day, of which 250, or 63 percent, return fewer than 1,000 rows, so you assume
that each report will increase the statistics table by about 25 kilobytes.
25 KB/report * 400 reports/day * 30 days/month * 6 months
= 1,800,000 KB or 1.8 GB
According to these usage assumptions, you decide to allocate 2 GB of disk
space for the statistics database.
Configuring Intelligence Server to log statistics
Below is a high-level overview of the steps to configure a project to log
statistics.
320
1
Create the statistics database (see Creating the statistics database, page
321).
2
Create the statistics tables in the statistics database (see Creating statistics
tables in the statistics database, page 321).
3
Configure your project to log statistics to the specified database (see
Setting the statistics database instance for a project, page 323).
4
Choose what statistics to log from that project (see Specifying which
statistics to log, page 325).
Configuring Intelligence Server to log statistics
© 2015, MicroStrategy Inc.
System Administration Guide
Creating the statistics database
You can store Intelligence Server statistics in an existing database in your
system, or create a new database.
Do not store the statistics in the same database that you are using for
~ either your MicroStrategy metadata or your data warehouse.
•
To use an existing database, note its Data Source Name (DSN). This DSN is
used when you create the statistics tables.
If you choose to use Enterprise Manager to analyze the statistics, this
* DSN is also used to specify the data warehouse location for Enterprise
Manager. For information on Enterprise Manager, see the Enterprise
Manager chapter in the MicroStrategy Operations Manager Guide.
•
To create a new database, follow the procedure below. For a list of
databases that are certified for use with Intelligence Server statistics, see
Supported database platforms, page 317, or see the MicroStrategy
Readme.
To create a new statistics database
1
Create the empty data warehouse database. (This is generally performed by
your database administrator.) This database must be one of the databases
certified for Intelligence Server statistics, as listed in the MicroStrategy
Readme.
2
Use the MicroStrategy Connectivity Wizard to create a Data Source Name
for the data warehouse. Note this DSN for later.
To access the Connectivity Wizard, from the Windows Start menu, point to
All Programs, then MicroStrategy Tools, and select Connectivity Wizard. For
detailed instructions on using the Connectivity Wizard, see the
MicroStrategy Installation and Configuration Guide.
To avoid a situation in which some statistics database entries reports have
* incomplete information, synchronize the time of the Intelligence Server
machine with the database time, if possible.
Creating statistics tables in the statistics database
After the statistics database has been created, or you have noted your existing
database’s DSN, you need to create the empty statistics tables for Intelligence
Server to use. The MicroStrategy Configuration Wizard walks you through this
process.
© 2015, MicroStrategy Inc.
Configuring Intelligence Server to log statistics
321
System Administration Guide
To create the empty statistics tables
1
Start the MicroStrategy Configuration Wizard.
•
Windows: From the Windows Start menu, point to All Programs, then
MicroStrategy Tools, and then select Configuration Wizard.
•
UNIX/Linux: Browse to the directory specified as the home directory
during MicroStrategy installation, then browse to the folder bin and
type ./mstrcfgwiz and press ENTER.
2
On the Welcome page, select Create Metadata, History List and Enterprise
Manager Repositories and click Next. The Repository Configuration:
Repository Types page opens.
3
Select the Statistics & Enterprise Manager option and clear the other
options. Click Next. The Repository Configuration: Statistics and Enterprise
Manager Repository page opens.
4
From the DSN drop-down list, select the Data Source Name for the
database that will contain your Enterprise Manager repository (the same
database that you will use to log Intelligence Server statistics).
~
5
Any table in this database that has the same name as a MicroStrategy
statistics table is dropped. For a list of the MicroStrategy statistics
tables, see the Statistics Data Dictionary in the Supplemental
Reference for System Administration.
In the User Name and Password fields, enter a valid login and password for
the data warehouse database.
The user name you specify must have permission to create and drop
* tables in the database, and permission to create views.
6
7
If you want to use a custom SQL script for creating the repository, click
Advanced.
•
In the Script field, the default script file name is displayed. The selected
script depends on the database type that you specified earlier.
•
To select a different script, click ... (the Browse button) to browse to
and select a script that corresponds to the DBMS for the repository.
Click Next. The Configuration Wizard connects to the database.
If Enterprise Manager statistics tables already exist in this database, it
prompts you for whether to re-create the tables. To re-create them, click
Yes. To leave the existing tables in place, click No.
~
322
Clicking Yes deletes the existing tables and all information in them.
Configuring Intelligence Server to log statistics
© 2015, MicroStrategy Inc.
System Administration Guide
8
The Summary page lists the tasks that will be performed. To create the
tables, click Finish. The process can take several minutes.
Setting the statistics database instance for a project
Once the statistics repository has been created, you must configure your
project to log statistics to this database.
MicroStrategy recommends that you configure your system to use single
instance session logging. In this configuration, statistics for all projects in a
project source are logged to a single database. To enable single instance
session logging, in the Intelligence Server Configuration Editor, in the
Statistics: General category, select Single Instance Session Logging and, from
the drop-down list, select a project. Then specify that project’s statistics
database using the procedure below. For steps on enabling single instance
session logging, see Logging all statistics from a project source to the same
database, page 318.
To set up a project to log statistics
1
In Developer, log in to the server (three-tier) project source containing the
projects for which you want to log statistics. You must log in as a user with
the Configure Server Basic privilege.
2
Right-click the project that you want to monitor and select Project
Configuration. The Project Configuration Editor opens.
*
If you are using single instance session logging, the project that you
select to configure must be the project that you selected when you set
up single instance session logging.
3
Expand the Database Instances category, and select the SQL Data
warehouses subcategory.
4
You need to create a new database instance for the statistics repository
database. Click New. The Database Instances dialog box opens.
© 2015, MicroStrategy Inc.
Configuring Intelligence Server to log statistics
323
System Administration Guide
5
In the Database instance name field, type in a name for the statistics
repository database instance.
6
From the Database connection type drop-down list, select the database
type and version that corresponds to the statistics repository database
DBMS.
7
You need to create a new database connection to connect to the database
instance. Click New. The Database Connections dialog box opens.
8
In the Database connection name field, type a name for the database
connection.
9
From the ODBC Data Sources list, select the Data Source Name used to
connect to the statistics repository database.
10 Enable parameterized queries in the statistics repository database
connection. To do this, on the Advanced tab, select the Use parameterized
queries check box.
11 You need to create a new database login to log in to the database instance.
On the General tab, click New. The Database Logins dialog box opens.
12 Type a name for the new database login in the Database login field.
If this database login is more than 32 characters long, the statistics
~ logging will generate errors in the DSS Errors log.
13 Type a valid database login ID and password in the corresponding fields.
MicroStrategy does not validate this login ID and password, so be
~ careful to type them correctly.
324
Configuring Intelligence Server to log statistics
© 2015, MicroStrategy Inc.
System Administration Guide
14 Click OK three times to return to the Project Configuration Editor. In each
case before clicking OK, make sure your new database login and database
connection are selected.
15 In the Database Instances category, select the Statistics subcategory.
16 From the Statistics database instance drop-down list, select your new
statistics database instance.
17 Click OK. Your selections are saved, and the Project Configuration Editor
closes.
Configure an additional database driver setting
If your statistics and Enterprise Manager repository is in an Oracle, Sybase,
or Teradata database, you must configure an additional ODBC driver
setting so the information is recorded properly in the statistics repository.
18 Open the ODBC Data Source Administrator tool in Windows.
19 Select the DSN for your statistics and Enterprise Manager repository and
click Modify. The ODBC Driver Setup dialog box opens.
20 Perform the following according to your database:
•
Oracle: click the Advanced tab and select the Enable SQLDescribeParam
check box.
•
Sybase: click the Advanced tab and select the Enable Describe
Parameter check box.
•
Teradata: click Options and select the Enable Extended Statement
Information check box.
21 Click OK twice to save the change and close the ODBC Data Source
Administrator dialog box.
Specifying which statistics to log
Once you have specified a statistics database instance for a project, you can
select what statistics to log. For detailed information about what statistics can
be logged, see Overview of Intelligence Server statistics, page 315.
You must specify what statistics to log for all projects that log statistics. Single
instance session logging (see Logging all statistics from a project source to the
same database, page 318) causes all projects on a project source to share the
same statistics database, but not to log the same statistics.
To log information from performance counters, use the Diagnostics and
* Performance Logging Tool. For steps on how to log performance
© 2015, MicroStrategy Inc.
Configuring Intelligence Server to log statistics
325
System Administration Guide
information, see Recording performance counters in the statistics tables,
page 316.
To specify which statistics to log
1
In Developer, log in to the project source containing the project for which
you want to log statistics. You must log in as a user with the Configure
Server Basic privilege.
2
Right-click the project that you want to monitor and select Project
Configuration. The Project Configuration Editor opens.
3
Expand the Statistics category, and select the General subcategory.
4
Select the Basic Statistics check box.
5
To log advanced statistics, select the check boxes for the statistics you wish
to log. For information about each check box, see Overview of Intelligence
Server statistics, page 315.
6
Click OK. The Project Configuration Editor closes and your selections are
saved.
7
To begin logging statistics, unload and reload the project for which you are
logging statistics:
a
In Developer, expand Administration, then expand System
Administration, then select Project. A list of all projects on this project
source is displayed.
b
Right-click the project, point to Administer Project, and select Unload.
The project is unloaded.
c
Right-click the project, point to Administer Project, and select Load.
The project is reloaded and configured to log statistics.
Additional monitoring tools
In addition to the logging tools and system monitors listed above,
MicroStrategy provides several tools that help you track system usage and
changes to the system. An overview of each tool is given below, along with a
location for more information.
326
Configuring Intelligence Server to log statistics
© 2015, MicroStrategy Inc.
System Administration Guide
Diagnostics and Performance Logging Tool
MicroStrategy log files are records of all low-level system activities. You can
configure Intelligence Server to record diagnostics information at various
levels. You can also log performance information, such as the time taken to
perform various operations and the total number of operations performed.
You manage log files through the MicroStrategy Diagnostics and Performance
Logging tool. For information about this tool, including instructions, see
Finding trouble spots using diagnostics, page 801.
Integrity Manager
MicroStrategy Integrity Manager can compare reports and documents between
two projects. This can help you determine how specific changes in a project
environment, such as the regular maintenance changes to metadata objects or
hardware and software upgrades, affect the reports and documents in that
project. Integrity Manager can also provide performance data for reports and
documents, by recording the amount of time each report or document takes to
execute.
For more information about Integrity Manager, see Chapter 16, Verifying
Reports and Documents with Integrity Manager.
Enterprise Manager
MicroStrategy Enterprise Manager helps you analyze Intelligence Server
statistics. Enterprise Manager provides a prebuilt MicroStrategy project with
more than a hundred reports and dashboards covering all aspects of
Intelligence Server operation. You can also use Enterprise Manager’s prebuilt
facts and attributes to create your own reports so you can have immediate
access to the performance and system usage information.
For steps on setting up Enterprise Manager and using the reports in it, see the
Enterprise Manager chapter in the MicroStrategy Operations Manager Guide.
Health Center
MicroStrategy Health Center can help you prevent, diagnose, and fix problems
in your MicroStrategy system. It can scan your system for problems,
recommend an immediate solution to many of them, and prepare a diagnostic
package of log files and other relevant system information to be sent to
MicroStrategy Technical Support if necessary. Health Center can also view the
log files generated with the Diagnostics and Performance Logging Tool.
For more information about Health Center, see Chapter 17, Maintaining Your
MicroStrategy System with Health Center.
© 2015, MicroStrategy Inc.
Diagnostics and Performance Logging Tool
327
System Administration Guide
Windows Performance Monitor
The Windows Performance Monitor is not part of MicroStrategy, but it can be
useful for monitoring your system resources. For information about using the
Windows Performance Monitor to monitor how MicroStrategy system
components are using system resources, see Managing system memory and
resources: Windows Performance Monitor, page 339.
328
Windows Performance Monitor
© 2015 , MicroStrategy Inc.
8
TUNING YOUR SYSTEM FOR
BEST PERFORMANCE
Introduction
Tuning a MicroStrategy system is not an exact science. Because your system
resources, application performance, and user requirements and expectations
are unique, it is not possible for MicroStrategy to include an exact
methodology or set of recommendations for optimization.
One of your most important jobs as a MicroStrategy system administrator is
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. This chapter
discusses how to analyze your users’ requirements, and the ways you can
configure and tune your system to meet those requirements.
The topics covered in this section include:
•
Tuning overview and best practices, page 330
•
Designing system architecture, page 334
•
Managing system resources, page 338
•
Managing user sessions, page 355
•
Governing requests, page 363
•
Managing job execution, page 368
© 2015, MicroStrategy Inc.
329
System Administration Guide
•
Governing results delivery, page 381
•
Tuning your system for in-memory datasets
•
Designing reports, page 387
•
Configuring Intelligence Server and projects, page 390
•
Tuning Narrowcast Server and Intelligence Server, page 402
Tuning overview and best practices
To get the best performance out of your MicroStrategy system, you must be
familiar with the characteristics of your system and how it performs under
different conditions. In addition to this, you need a plan for tuning the system.
For example, you should have a base record of certain key configuration
settings and performance measures, such as Enterprise Manager reports or
diagnostics logs, before you begin experimenting with those settings. Make one
change at a time and test the system performance. Compare the new
performance to the base and see if it improved. If it did not improve, change
the setting back to its previous value. This way, when system performance
improves, you know which change is responsible.
The specifications of the machines that you use to run Intelligence Server, how
you tune those machines, and how they are used depend on the number of
users, number of concurrently active users, their usage patterns, and so on.
MicroStrategy provides up-to-date recommendations for these areas on the
MicroStrategy Knowledge Base.
As a high-level overview of tuning the system, you should first define your
system requirements, and then configure the system’s design using those
requirements. The following topics lay the foundation for the specific tuning
guidelines that make up the rest of this chapter.
•
Defining the system requirements, page 330
•
Configuring the system design, page 331
•
Best practices for tuning your system, page 333
Defining the system requirements
You most likely have certain expectations or requirements that the system
must meet for it to be considered a success. For example, you may have a set
of requirements similar to one of these scenarios:
330
Defining the system requirements
© 2015, MicroStrategy Inc.
System Administration Guide
•
Global Web-based deployment for 400 users with 15-second response time
for prompted reports and the ability to subscribe to personalized weekly
sales reports.
•
Internal deployment for 200 market research analysts accessing an
enterprise data warehouse on a completely ad hoc basis.
•
Web-based deployment for 1,500 remote users with access to pre-defined
daily sales and inventory reports with 5-second response time.
These scenarios share common requirements that can help you define your
own expectations for the system, such as the following:
•
You may require that the system be able to handle a certain number of
concurrent users logged in, or a certain number of active users running
reports and otherwise interacting with the system.
•
You may require a certain level of performance, such as report results
returning to the users within a certain time, or that the results of report
manipulation happen quickly, or that a certain number of reports can be
run within an hour or within a day.
•
You may require that users have access to certain features, such as
scheduling a report for later execution, or sending a report to someone else
via email, or that your users will be able to access their reports online
through MicroStrategy Web.
•
You may require that certain functionality be available in the system, such
as allowing report flexibility so users can run ad hoc, predefined,
prompted, page-by, or Intelligent Cube reports.
Configuring the system design
It is important to understand that the MicroStrategy business intelligence
system has a limited capacity. It cannot serve an unlimited number of users
and process an unlimited number of jobs in a short time. This capacity can be
thought of as a box shared by the two important goals of serving the necessary
number of user sessions (through which users submit requests) and
maximizing the number of jobs executed (which return results).
The limits that the system encounters may be Intelligence Server machine
capacity, the data warehouse’s throughput capacity, or the network’s capacity.
The main factors that affect the system’s capacity are:
•
The system resources available (including memory)
•
The architecture of the system and network
•
The design of the reports that are executed
© 2015, MicroStrategy Inc.
Configuring the system design
331
System Administration Guide
•
The configuration of Intelligence Server and projects to determine how
system resources can be used
The diagram below illustrates these factors that influence the system’s
capacity.
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
UNIX and Linux systems allow processes and applications to run in a
* virtual environment. Intelligence Server Universal installs on UNIX and
Linux systems with the required environment variables set to ensure that
the server’s jobs are processed correctly. However, you can tune these
system settings to fit your system requirements and improve performance.
For more information, see the Planning Your Installation chapter of the
MicroStrategy Installation and Configuration Guide.
Configuring run-time capacity variables
Run-time capacity variables are factors that influence performance and
capacity after Intelligence Server has started. The two run-time capacity
variables are user sessions (see Managing user sessions, page 355) and
executing jobs (see Managing job execution, page 368).
These runtime capacity variables are interrelated with system capacity. If you
change settings in one, the others are affected. For example, if you place more
emphasis on serving more user sessions, the job execution may suffer because
it does not have as much of the system capacity available to use. Or, for
example, if you increase Intelligence Server’s capacity, it could execute jobs
more quickly or it could serve more user sessions.
Accessing the system configuration editors
Many of the options in the following sections are specified in the Intelligence
Server Configuration Editor or the Project Configuration Editor.
Prerequisites
•
332
You must have the Configure Governing privilege for the project or project
source.
Configuring the system design
© 2015, MicroStrategy Inc.
System Administration Guide
•
You must have Configuration permissions for the server object. In addition,
to access the Project Configuration Editor you must have Write permission
for the project object. For more information about server object
permissions, see Permissions for server governing and configuration, page
67.
To access the Intelligence Server Configuration Editor
1
In Developer, log into a project source.
2
From the Administration menu, point to Server and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
To access the Project Configuration Editor for a project
1
In Developer, log into a project source.
2
Expand the project that you want to configure.
3
From the Administration menu, point to Projects and then select Project
Configuration. The Project Configuration Editor opens.
Best practices for tuning your system
MicroStrategy recommends the following best practices for designing,
configuring, and tuning your MicroStrategy system. For detailed information
about increasing system performance by tuning the governing settings, see the
remainder of this chapter.
•
When designing your projects and data warehouse, follow the
MicroStrategy best practices as outlined in the MicroStrategy Project
Design Guide.
•
When configuring your network, follow the MicroStrategy best practices as
outlined in Network configuration best practices, page 336.
•
Use the Windows Performance Monitor to track the usage of system
resources on Intelligence Server machines, as described in Managing
system memory and resources: Windows Performance Monitor, page 339.
•
Use Intelligence Server’s Memory Contract Manager to manage memory
usage, as described in Governing Intelligence Server memory use with
Memory Contract Manager, page 345.
© 2015, MicroStrategy Inc.
Best practices for tuning your system
333
System Administration Guide
•
Use MicroStrategy system privileges to restrict users’ access to certain
features, as described in Governing user profiles, page 361.
•
Assign a high priority to more time-sensitive jobs, and a low priority to
jobs that may use a great deal of system resources, as described in
Prioritizing jobs, page 373.
•
Enable Intelligence Server thread balancing, as described in Intelligence
Server thread balancing, page 377.
•
Ensure that report and document designers are aware of the features that
can place an exceptionally heavy load on the system. These features are
listed in detail in Designing reports, page 387.
Designing system architecture
The choices that you make when designing the architecture of your
MicroStrategy system have a significant impact on system performance and
capacity.
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
Choices that you must make when designing your system architecture include:
334
•
How the data warehouse is configured (see How the data warehouse can
affect performance, page 335)
•
The physical location of machines relative to each other and the amount of
bandwidth between them (see How the network can affect performance,
page 335)
•
Whether you cluster several Intelligence Servers together and what
benefits you can get from clustering (see How clustering can affect
performance, page 338)
Best practices for tuning your system
© 2015, MicroStrategy Inc.
System Administration Guide
How the data warehouse can affect performance
The data warehouse is a crucial component of the business intelligence system.
If it does not perform well, the entire system’s performance suffers. The data
warehouse platform or RDBMS and the data warehouse’s design and tuning
are factors that can affect your system’s performance.
Platform considerations
The size and speed of the machines hosting your data warehouse and the
database platform (RDBMS) running your data warehouse both affect the
system’s performance. A list of supported RDBMSs can be found in the
MicroStrategy Readme. You should have an idea of the amount of data and the
number of users that your system serves, and research which RDBMS can
handle that type of load.
Design and tuning considerations
Your data warehouse’s design (also called the physical warehouse schema) and
tuning are important and unique to your organization. They also affect the
performance of your business intelligence system. The discussion of the set of
trade-offs that you must make when designing and tuning the data warehouse
is out of the scope of this guide. Examples of the types of decisions that you
must make include:
•
Will you use a normalized, moderately normalized, or fully denormalized
schema?
•
What kind of lookup, relate, and fact tables will you need?
•
What aggregate tables will you need?
•
What tables do you need to partition and how?
•
What tables will you index?
For more information about data warehouse design and data modeling, see the
MicroStrategy Advanced Reporting Guide and Project Design Guide.
How the network can affect performance
The various components of the MicroStrategy system need to be installed on
different machines for performance reasons. The network plays an important
role in connecting these components. In the diagram below, the separate
components of the MicroStrategy system are linked by lines representing the
network. The steps that occur over each connection are described in the table
below the diagram.
© 2015, MicroStrategy Inc.
How the data warehouse can affect performance
335
System Administration Guide
Step
Protocol
Details
1
HTTP
HTML sent from Web server to client. Data size is small compared to other points because
results have been incrementally fetched from Intelligence Server and HTML results do not
contain any unnecessary information.
2
TPC/IP
XML requests are sent to Intelligence Server. XML report results are incrementally fetched
from Intelligence Server.
3
TCP/IP
Requests are sent to Intelligence Server. (No incremental fetch is used.)
4
TCP/IP
Broadcasts between all nodes of the cluster (if implemented): metadata changes, Inbox,
report caches. Files containing cache and Inbox messages are exchanged between
Intelligence Server nodes.
5
TCP/IP
Files containing cache and Inbox messages may also be exchanged between Intelligence
Server nodes and a shared cache file server if implemented (see Sharing result caches and
Intelligent Cubes in a cluster, page 410).
6
ODBC
Object requests and transactions to metadata. Request results are stored locally in
Intelligence Server object cache.
7
ODBC
Complete result set is retrieved from database and stored in Intelligence Server memory
and/or caches.
The maximum number of threads used in steps 2 and 3 can be controlled in
the Intelligence Server Configuration Editor, in the Server Definition: General
category, in the Number of Network Threads field. Depending on how your
network is configured, one network thread may be sufficient to serve anywhere
from 64 to 1028 user connections.
Network configuration best practices
The network configuration, that is, where the components are installed in
relation to each other, can have a large effect on performance. For example, if
the physical distance between Intelligence Server and the data warehouse is
336
How the network can affect performance
© 2015, MicroStrategy Inc.
System Administration Guide
great, you may see poor performance due to network delays between the two
machines.
MicroStrategy recommends the following best practices for network design:
•
Place the Web server machines close to the Intelligence Server machines.
•
Place Intelligence Server close to the both the data warehouse and the
metadata repository.
•
Dedicate a machine for the metadata repository.
•
If you use Enterprise Manager, dedicate a machine for the Enterprise
Manager database (statistics tables and data warehouse).
•
If you have a clustered environment with a shared cache file server, place
the shared cache file server close to the Intelligence Server machines.
Network bandwidth and how its capacity is used
Your network design depends on the type of reports that your users typically
run. These reports, in turn, determine the load they place on the system and
how much network traffic occurs between the system components.
The ability of the network to quickly transport data between the components
of the system greatly affects its performance. For large result sets, the highest
load or the most traffic typically occurs between the data warehouse and the
Intelligence Servers (indicated by C in the diagram below). The load between
Intelligence Server and Web server is somewhat less (B), followed by the least
load between the Web server and the Web browser (A).
This is illustrated in the diagram and explained below.
A
Web client
B
MicroStrategy Web
Server
C
Intelligence
Server(s)
Data
Warehouse
•
Incremental fetch size directly influences the amount of traffic at A.
•
Graphics increase network bandwidth at B.
•
The load at C is determined primarily by the number of rows retrieved
from the data warehouse. Actions such as sending SQL or retrieving objects
from the metadata result in minimal traffic.
▫
Cached reports do not cause any network traffic at C.
© 2015, MicroStrategy Inc.
How the network can affect performance
337
System Administration Guide
▫
Report manipulations that do not cause SQL to be generated and sent
to the data warehouse (such as pivot, sort, and page-by) are similar to
running cached reports.
▫
Report manipulations that cause SQL to be generated and sent to the
data warehouse are similar to running non-cached reports of the same
size.
After noting where the highest load is on your network, you can adjust your
network bandwidth or change the placement of system components to improve
the network’s performance.
You can tell whether or not your network configuration has a negative effect
on your system’s performance by monitoring how much of your network’s
capacity is being used. Use the Windows Performance Monitor for the object
Network Interface, and the watch the counter Total bytes/sec as a percent of
your network’s bandwidth. If it is consistently greater than 60 percent (for
example), it may indicate that the network is negatively affecting the system’s
performance. You may wish to use a figure different than 60 percent for your
system.
To calculate the network capacity utilization percent, take the total capacity, in
terms of bits per second, and divide it by (Total bytes per second * 8).
(Multiply the Total Bytes per second by 8 because 1 byte = 8 bits.)
The Current Bandwidth counter in Performance Monitor gives an approximate
value of total capacity because it is only an estimate. You may want to use
another network monitoring utility such as NetPerf to get the actual
bandwidth figure.
How clustering can affect performance
Clustering several Intelligence Server machines provides substantial gains in
memory and CPU capacity because multiple machines are sharing the work.
Clustering has additional benefits for your system as well. The clustering
feature is built into Intelligence Server and is available out of the box if you
have the proper license. For more information on clustering Intelligence
Servers, including instructions, see Chapter 9, Clustering Multiple
MicroStrategy Servers.
Managing system resources
If you had unlimited money, you could create a system that would impose few
limits on system capacity. While system resources is not the place to save
338
How clustering can affect performance
© 2015, MicroStrategy Inc.
System Administration Guide
money when building a business intelligence system, you may not have the
resources that you wish you could have.
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
You must make certain choices about how to maximize the use of your
system’s resources. Because Intelligence Server is the main component of the
MicroStrategy system, it is important that the machines running it have
sufficient resources for your needs. These resources include:
•
The processors (Processor type, speed, and number of processors, page
340)
•
Physical disk characteristics (Physical disk, page 340)
•
The amount of memory (Memory, page 341)
The MicroStrategy Installation and Configuration Guide contains detailed
* information about small, medium, and large configurations.
Managing system memory and resources: Windows
Performance Monitor
Microsoft’s Performance Monitor is a tool that is part of the Windows
operating system. You can use it to monitor how memory and other resources
are being used on a machine. You can also use it to access specific
MicroStrategy performance counters.
For more information on Windows Performance monitor, see
http://www.microsoft.com/.
To view the MicroStrategy-specific performance counters
1
In the Windows Performance Monitor, on the toolbar, click the View Log
Data icon. The System Monitor Properties dialog box opens.
© 2015, MicroStrategy Inc.
Managing system memory and resources: Windows Performance
Monitor
339
System Administration Guide
2
Select the Data tab.
3
Click Add. The Add Counters dialog box opens.
4
From the Performance Object drop-down list, select either MicroStrategy
Server Jobs or MicroStrategy Server Users.
5
Select the desired counters from the list and click Add.
6
Click Close, then click OK. The dialog boxes close and the desired counters
are now displayed in the Performance Monitor.
Processor type, speed, and number of processors
Intelligence Server recognizes the type and speed of the machine’s CPUs, and
performs faster on a machine with multiple CPUs. If Intelligence Server is
consistently using a great deal of processor capacity, greater than 80 percent,
for example, it may be a sign that a faster processor would improve the
system’s capacity. In Windows, you can monitor the processor usage with the
Windows Performance Monitor. For instructions, see Managing system
memory and resources: Windows Performance Monitor, page 339.
If you upgrade a machine’s CPU, make sure you have the appropriate license to
run Intelligence Server on the faster CPU. For example, if you upgrade the
processor on the Intelligence Server machine from a 2 GHz to a 2.5 GHz
processor, you should obtain a new license key from MicroStrategy.
Intelligence Server is also aware of the number of processors it is allowed to
use according to the license key that you have purchased. For example, if a
machine running Intelligence Server has two processors and you upgrade it to
four, Intelligence Server uses only the two processors and ignores the
additional two until you purchase a new license key from MicroStrategy. Also,
if several Intelligence Server machines are clustered, the application ensures
that the total number of processors being used does not exceed the number
licensed.
For detailed information about CPU licensing, see CPU licenses, page 226.
Physical disk
If the physical disk is used too much on a machine hosting Intelligence Server,
it can indicate a bottleneck in the system’s performance. To monitor physical
disk usage in Windows, use the Windows Performance Monitor counters for
the object Physical Disk and the counter % Disk Time. If the counter is greater
than 80 percent on average, it may indicate that the machine does not have
enough memory. This is because when the machine’s physical RAM is full, the
operating system starts swapping memory in and out of the page file on disk.
This is not as efficient as using RAM. Therefore, Intelligence Server’s
performance may suffer.
340
Processor type, speed, and number of processors
© 2015, MicroStrategy Inc.
System Administration Guide
By monitoring the disk utilization, you can see if the machine is consistently
swapping at a high level. Defragmenting the physical disk may help lessen the
amount of swapping. If that does not sufficiently lessen the utilization,
consider increasing the amount of physical RAM in the machine. For
information on how Intelligence Server uses memory, see Memory, page 341.
MicroStrategy recommends that you establish a benchmark or baseline of a
* machine’s normal disk utilization, perhaps even before Intelligence Server
is installed. This way you can determine whether or not Intelligence Server
is responsible for excessive swapping because of limited RAM.
Another performance counter that you can use to gauge the disk’s utilization is
the Current disk queue length, which indicates how many requests are waiting
at a time. MicroStrategy recommends using the % Disk Time and Current Disk
Queue Length counters to monitor the disk utilization.
For instructions on how to use Windows Performance Monitor, see Managing
system memory and resources: Windows Performance Monitor, page 339.
Memory
If the machine hosting Intelligence Server has too little memory, it may run
slowly, or even shut down during memory-intensive operations. You can use
the Windows Performance Monitor to monitor the available memory, and you
can govern Intelligence Server’s memory use with the Memory Contract
Manager. The following topics can help you understand the best way to govern
Intelligence Server’s memory use:
•
Memory limitations: virtual memory, page 341
•
Monitoring memory use with Performance Monitor, page 342
•
How much memory does Intelligence Server use when it starts up?, page
343
•
How does Intelligence Server use memory after it is running?, page 344
•
Governing Intelligence Server memory use with Memory Contract
Manager, page 345
Memory limitations: virtual memory
The memory used by Intelligence Server is limited by the machine’s virtual
memory.
Virtual memory is the amount of physical memory (RAM) plus the Disk Page
file (swap file). It is shared by all processes running on the machine, including
the operating system.
© 2015, MicroStrategy Inc.
Memory
341
System Administration Guide
When a machine runs out of virtual memory, processes on the machine are no
longer able to process instructions and eventually the operating system may
shut down. More virtual memory can be obtained by making sure that as few
programs or services as possible are executing on the machine, or by
increasing the amount of physical memory or the size of the page file.
Increasing the amount of virtual memory, and therefore the available
* private bytes, by increasing the page file size may have adverse effects on
Intelligence Server performance because of increased swapping.
Private bytes are the bytes of virtual memory that are allocated to a process.
Private bytes are so named because they cannot be shared with other
processes: when a process such as Intelligence Server needs memory, it
allocates an amount of virtual memory for its own use. The private bytes used
by a process can be measured with the Private Bytes counter in the Windows
Performance Monitor.
The governing settings built into Intelligence Server control its demand for
private bytes by limiting the number and scale of operations which it may
perform simultaneously. In most production environments, depletion of virtual
memory through private bytes is not an issue with Intelligence Server.
Monitoring memory use with Performance Monitor
Microsoft’s Performance Monitor is a useful tool for monitoring the amount of
memory used on the entire machine or by a certain process (such as
Intelligence Server). For instructions on how to use Performance Monitor to
track Intelligence Server memory usage in your environment, see Managing
system memory and resources: Windows Performance Monitor, page 339.
The two memory-related counters you should log with Performance Monitor
are Private Bytes and Virtual Bytes for the Intelligence Server process
(Mstrsvr.exe). A sample log of these two counters (along with others) for
Intelligence Server is shown in the diagram below.
342
Memory
© 2015, MicroStrategy Inc.
System Administration Guide
The diagram above illustrates the gap between private bytes and virtual bytes
in Intelligence Server. The Virtual Bytes counter represents memory that is
reserved, not committed, for the process. Private Bytes represents memory
actually being used by the process. Intelligence Server reserves regions of
memory (called heaps) for use within the process. The heaps that are used by
Intelligence Server cannot share reserved memory between themselves,
causing the gap between reserved memory (virtual bytes) and memory being
used by the process (private bytes) to increase further.
How much memory does Intelligence Server use when it starts up?
The amount of memory consumed during startup is affected by a number of
factors such as metadata size, the number of projects, schema size, number of
processing units, number of database connection threads required, and
whether Intelligence Server is in a clustered configuration. Because these
factors are generally static, the amount of memory consumed at startup is
fairly constant. This lets you accurately estimate how much memory is
available to users at runtime.
When Intelligence Server starts up, it uses memory in the following ways:
•
It initializes all internal components and loads the static DLLs necessary
for operation. This consumes 25 MB of private bytes and 110 MB of virtual
bytes. You cannot control this memory usage.
•
It loads all server definition settings and all configuration objects. This
consumes an additional 10 MB of private bytes and an additional 40 MB of
virtual bytes. This brings the total memory consumption at this point to 35
MB of private bytes and 150 MB of virtual bytes. You cannot control this
memory usage.
© 2015, MicroStrategy Inc.
Memory
343
System Administration Guide
•
It loads the project schema (needed by the SQL engine component) into
memory. The number and size of projects greatly impacts the amount of
memory used. This consumes an amount of private bytes equal to three
times the schema size and an amount of virtual bytes equal to four times
the schema size. For example, with a schema size of 5 MB, the private bytes
consumption would increase by 15 MB (3 * 5 MB). The virtual bytes
consumption would increase by 20 MB (4 * 5 MB). You can control this
memory usage by limiting the number of projects that load at startup time.
•
It creates the database connection threads. This primarily affects virtual
bytes consumption, with an increase of 1 MB per thread regardless of
whether that thread is actually connected to the database. You cannot
control this memory usage.
To calculate the amount of memory that Intelligence Server uses
when it starts
If you are not performing this procedure in a production environment,
* make sure that you set all the configuration options as they exist in your
production environment. Otherwise, the measurements will not reflect the
actual production memory consumption.
1
Start Intelligence Server.
2
Once Intelligence Server has started, use Windows Performance Monitor to
create and start a performance log that measures Private and Virtual bytes
of the MSTRSVR process. For instructions on using the Windows
Performance Monitor, see Managing system memory and resources:
Windows Performance Monitor, page 339.
3
While logging with Performance Monitor, stop Intelligence Server.
Performance Monitor continues to log information for the Intelligence
Server process. You can confirm this by logging the counter information to
the current activity window as well as the performance log.
4
Start Intelligence Server again. The amount of memory consumed should
be easily measured.
How does Intelligence Server use memory after it is running?
Intelligence Server increases its memory use as needed during its operation.
The following factors determine when memory use increases:
•
344
Additional configuration objects: caching of user, connection map, and
schedule and subscription information created or used after Intelligence
Server has been started.
Memory
© 2015, MicroStrategy Inc.
System Administration Guide
•
Caches: result (report and document) caches, object caches, and element
caches created after Intelligence Server has been started. The maximum
amount of memory that Intelligence Server uses for result caches is
configured at the project level. For more information about caches, see
Chapter 10, Improving Report and Document Response Time: Caching.
•
Intelligent Cubes: any Intelligent Cubes that have been loaded after
Intelligence Server has been started. The maximum amount of memory
used for Intelligent Cubes is configured at the project level. For details, see
Chapter 11, Managing Intelligent Cubes.
•
User session-related resources: History List and Working set memory,
which are greatly influenced by governing settings, report size, and report
design. For details, see Managing user sessions, page 355 and Saving
report results: History List, page 466.
•
Request and results processing: memory needed by Intelligence Server
components to process requests and report results. This is primarily
influenced by report size and report design with respect to analytical
complexity. For details, see Governing requests, page 363 and Results
processing, page 376.
•
Clustering: memory used by Intelligence Server to communicate with other
cluster nodes and maintain synchronized report cache and History List
information. For more information about clustering, see Chapter 9,
Clustering Multiple MicroStrategy Servers.
•
Scheduling: memory used by scheduler while executing reports for users
when they are not logged in to the system. For more information about
scheduling, see Chapter 12, Scheduling Jobs and Administrative Tasks.
Governing Intelligence Server memory use with
Memory Contract Manager
Memory Contract Manager (MCM) is designed to protect Intelligence Server in
cases where a memory request would cause the system to approach a state of
memory depletion. When enabled, MCM grants or denies requests for memory
from tasks in Intelligence Server. The requests are granted or denied according
to user-configured limits on the amount of memory Intelligence Server is
allowed to use. Because MCM is a component in Intelligence Server, it does
not manage the actual memory used by Intelligence Server itself.
MCM governs the following types of requests:
•
Database requests from either the MicroStrategy metadata or the data
warehouse
•
SQL generation
© 2015, MicroStrategy Inc.
Governing Intelligence Server memory use with Memory Contract
Manager
345
System Administration Guide
•
Analytical Engine processing (subtotals, cross tabulation, analytic
functions)
•
Cache creation and updating
•
Report parsing and serialization for network transfer
•
XML generation
The memory load of the requests governed by MCM depends on the amount of
data that is returned from the data warehouse. Therefore, this memory load
cannot be predicted.
Requests such as graphing, cache lookup, or document generation use a
predictable amount of memory and, thus, are not governed by MCM. For
example, a request for a report returns an acceptable amount of data. A graph
of the report’s results would be based on the same data and, thus, would be
allowed. Therefore, MCM is not involved in graphing requests. If the report
was not returned because it exceeded memory limits, the graphing request
would never be issued.
Using the Memory Contract Manager
The MCM settings are in the Intelligence Server Configuration Editor, in the
Governing Rules: Default: Memory Settings category.
The Enable single memory allocation governing option lets you specify how
much memory can be reserved for a single Intelligence Server operation at a
time. When this option is enabled, each memory request is compared to the
Maximum single allocation size (MBytes) setting. If the request exceeds this
346
Governing Intelligence Server memory use with Memory Contract
Manager
© 2015, MicroStrategy Inc.
System Administration Guide
limit, the request is denied. For example, if the allocation limit is set to 100
MB and a request is made for 120 MB, the request is denied, but a request for
90 MB is allowed.
If the Intelligence Server machine has additional software running on it, you
may wish to set aside some memory for those processes to use. To reserve this
memory, you can specify the Minimum reserved memory in terms of either the
number of MB or the percent of total system memory. In this case, the total
available memory is calculated as the initial size of the page file plus the RAM.
It is possible that a machine has more virtual memory than MCM knows about
if the maximum page file size is greater than the initial size.
Intelligence Server always reserves up to 500 MB for its own operation. If
* the machine does not have this much memory, or if the Minimum reserved
memory would leave less than 500 MB available for Intelligence Server, no
memory is reserved for other processes.
When MCM receives a request that would cause Intelligence Server’s memory
usage to exceed the Minimum reserved memory settings, it denies the request
and goes into memory request idle mode. In this mode, MCM denies any
requests that would deplete memory. MCM remains in memory request idle
mode until the memory used by Intelligence Server falls below a certain limit,
known as the low water mark. For information on how the low water mark is
calculated, see Memory water marks, page 349. For information about how
MCM handles memory request idle mode, see Memory request idle mode,
page 351.
The Maximum use of virtual address space is applicable in 32-bit Windows
* operating systems. For 64-bit operating systems, use the Minimum reserved
memory setting to control the amount of memory available for Intelligence
Server.
The Memory request idle time is the longest time MCM remains in memory
request idle mode. If the memory usage has not fallen below the low water
mark by the end of the Memory request idle time, MCM restarts Intelligence
Server. Setting the idle time to -1 causes Intelligence Server to remain idle
until the memory usage falls below the low water mark.
How does MCM grant or deny a request?
When a task requests memory, it provides MCM with an estimate of how
much memory it requires. If the request is granted, MCM decreases the
amount of available memory and the task allocates memory from the memory
subsystem. When the task is completed or canceled, the memory is released
and the amount of available memory increases.
MCM does not submit memory allocations to the memory subsystem (such as
a memory manager) on behalf of a task. Rather, it keeps a record of how much
© 2015, MicroStrategy Inc.
Governing Intelligence Server memory use with Memory Contract
Manager
347
System Administration Guide
memory is available and how much memory has been contracted out to the
tasks.
A memory request is granted if it meets the following criteria:
•
It is smaller than the Maximum single allocation size setting.
•
It is smaller than the high water mark, or the low water mark if
Intelligence Server is in memory request idle mode. These water marks are
derived from the Intelligence Server memory usage and the Maximum use
of virtual address space and Minimum reserved memory settings. For
detailed explanations of the memory water marks, see Memory water
marks, page 349.
•
It is smaller than 80 percent of the largest contiguous block of free
memory to account for memory fragmentation.
To determine whether a memory request is granted or denied, MCM follows
the logic in the flowchart below.
348
Governing Intelligence Server memory use with Memory Contract
Manager
© 2015, MicroStrategy Inc.
System Administration Guide
Key :
I-Server = Intelligence Server
PB = Private Bytes
VB = Virtual Bytes
HWM = High Watermark
LWM = Low Watermark
Memory
request
with contract size
Update I -Server
PB & VB values
10 MB of requests
since I -Server values
updated ?
YES
st
1 time I -Server
VB > Maximum
Use setting ?
NO
NO
Calculate HWM 1 (I-Server PB
+ Available System Memory
)
YES
Set HWM as minimum of
HWM 1 and HWM 2
Calculate HWM 2
(I-Server PB )
Calculate LWM
(0.95 * HWM )
Single
YES
Memory Allocation
Governing enabled ?
Contract
size < Max Single
Allocation Size ?
NO
YES
NO
I-Server
in Memory Request
Idle mode ?
Calculate Max contract request size
LWM – [1.05 * ( I-Server PB ) +
Contracted Memory ]
NO
Memory
Request Idle time
limit reached ?
=
Contract size <
Max Request Size ?
NO
NO
YES
=
NO
Deny request
and enter Memory
Request Idle mode
YES
Request > 80 %
of largest free
block ?
Deny request
and restart I -server
Contract size <
Max Request Size ?
Largest free
block updated in last
100 requests ?
Update
largest free
block
YES
NO
Calculate Max contract request size
HWM – [1.05 * ( I-Server PB ) +
Contracted Memory ]
YES
YES
Deny request
YES
NO
Deny request
Grant request
and exit Memory Request
Idle mode if in it
Deny request
Memory water marks
The high water mark (HWM) is the highest value that the sum of private bytes
and outstanding memory contracts can reach before triggering memory request
idle mode. The low water mark (LWM) is the value that Intelligence Server’s
private byte usage must drop to before MCM exits memory request idle mode.
© 2015, MicroStrategy Inc.
Governing Intelligence Server memory use with Memory Contract
Manager
349
System Administration Guide
MCM recalculates the high and low water marks after every 10 MB of memory
requests. The 10 MB value is a built-in benchmark and cannot be changed.
Two possible values are calculated for the high water mark: one based on
virtual memory, and one based on virtual bytes. For an explanation of the
different types of memory, such as virtual bytes and private bytes, see
Memory, page 341.
•
The high water mark for virtual memory (HWM1 in the diagram above) is
calculated as (Intelligence Server private bytes +
available system memory). It is recalculated for each potential
memory depletion.
The available system memory is calculated using the Minimum reserved
* memory limit if the actual memory used by other processes is less than
this limit.
•
The high water mark for virtual bytes (HWM2 in the diagram above) is
calculated as (Intelligence Server private bytes). It is
calculated the first time the virtual byte usage exceeds the amount
specified in the Maximum use of virtual address space or Minimum
Reserved Memory settings. Because MCM ensures that Intelligence Server
private byte usage cannot increase beyond the initial calculation, it is not
recalculated until after Intelligence Server returns from the memory
request idle state.
The high water mark used by MCM is the lower of these two values. This
accounts for the scenario in which, after the virtual bytes HWM is calculated,
Intelligence Server releases memory but other processes consume more
available memory. This can cause a later calculation of the virtual memory
HWM to be lower than the virtual bytes HWM.
The low water mark is calculated as 95 percent of the HWM. It is recalculated
every time the HWM changes.
Memory contract management
Once the high and low water marks have been established, MCM checks to see
if single memory allocation governing is enabled. If it is, and the request is for
an amount of memory larger than the Maximum single allocation size setting,
the request is denied.
If single memory allocation governing is not enabled, or if the request is for a
block smaller than the Maximum single allocation size limit, MCM checks
whether it is in memory request idle mode, and calculates the maximum
contract request size accordingly:
•
350
For normal Intelligence Server operation, the maximum request size is
based on the high water mark. The formula is [HWM - (1.05 *
Governing Intelligence Server memory use with Memory Contract
Manager
© 2015, MicroStrategy Inc.
System Administration Guide
(Intelligence Server Private Bytes) + Outstanding
Contracts)].
•
In memory request idle mode, the maximum request size is based on the
low water mark. The formula is [LWM - (1.05 *(Intelligence
Server Private Bytes) + Outstanding Contracts)].
The value of 1.05 is a built-in safety factor.
*
For normal Intelligence Server operation, if the request is larger than the
maximum request size, MCM denies the request. It then enters memory
request idle mode.
If MCM is already in memory request idle mode and the request is larger than
the maximum request size, MCM denies the request. It then checks whether
the memory request idle time has been exceeded, and if so, it restarts
Intelligence Server. For a detailed explanation of memory request idle mode,
see Memory request idle mode, page 351.
If the request is smaller than the maximum request size, MCM performs a
final check to account for potential fragmentation of virtual address space.
MCM checks whether its record of the largest free block of memory has been
updated in the last 100 requests, and if not, updates the record with the size of
the current largest free block. It then compares the request against the largest
free block. If the request is more than 80 percent of the largest free block, the
request is denied. Otherwise, the request is granted.
After granting a request, if MCM has been in memory request idle mode, it
returns to normal operation.
Memory request idle mode
When MCM first denies a request, it enters memory request idle mode. In this
mode, MCM denies all requests that would keep Intelligence Server’s private
byte usage above the low water mark. MCM remains in memory request idle
mode until one of the following situations occurs:
•
Intelligence Server’s memory usage drops below the low water mark. In
this case, MCM exits memory request idle mode and resumes normal
operation.
•
MCM has been in memory request idle mode for longer than the Memory
request idle time. In this case, MCM restarts Intelligence Server. This frees
up the memory that had been allocated to Intelligence Server tasks, and
avoids memory depletion.
The Memory request idle time limit is not enforced via an internal clock or
scheduler. Instead, after every denied request MCM checks how much time has
passed since the memory request idle mode was triggered. If this time is more
than the memory request idle time limit, Intelligence Server restarts.
© 2015, MicroStrategy Inc.
Governing Intelligence Server memory use with Memory Contract
Manager
351
System Administration Guide
This eliminates a potentially unnecessary Intelligence Server restart. For
example, a memory request causes the request idle mode to be triggered, but
then no more requests are submitted for some time. A scheduled check at the
end of the Memory request idle time would restart Intelligence Server even
though no new jobs are being submitted. However, because Intelligence Server
is completing its existing contracts and releasing memory, it is possible that
the next contract request submitted will be below the low water mark. In this
case, MCM accepts the request and resumes normal operation, without having
to restart Intelligence Server.
When MCM forces Intelligence Server to restart because of the Memory
* request idle time being exceeded, it also writes the contents of Intelligence
Server’s memory use to disk. This memory dump is saved in the file
MCMServerStallDump.dmp in the Intelligence Server folder. By default,
this folder is located at C:\Program Files (x86)
\MicroStrategy\Intelligence Server\.
MicroStrategy recommends setting the Memory request idle time to slightly
longer than the time it takes most large reports in your system to run. This
way, Intelligence Server does not shut down needlessly while waiting for a task
to complete. To help you determine the time limit, use Enterprise Manager to
find out the average and maximum report execution times for your system.
For instructions on using Enterprise Manager, see the MicroStrategy
Operations Manager Guide.
System Memory Depletion
The diagram below shows an example of a potential depletion of system
memory.
In this example, MCM grants memory request A. Once granted, a new memory
contract is accounted for in the available system memory. Request B is then
352
Governing Intelligence Server memory use with Memory Contract
Manager
© 2015, MicroStrategy Inc.
System Administration Guide
denied because it exceeds the high water mark, as derived from the Maximum
use of virtual address space setting.
Once request B has been denied, Intelligence Server enters the memory
request idle mode. In this mode of operation, it denies all requests that would
push the total memory used above the low water mark.
In the example above, request C falls above the low water mark. Because
Intelligence Server is in memory request idle mode, this request is denied
unless Intelligence Server releases memory from elsewhere, such as other
completed contracts.
Request D is below the low water mark, so it is granted. Once it has been
granted, Intelligence Server switches out of request idle mode and resumes
normal operation.
If Intelligence Server continues receiving requests for memory above the low
water mark before the Memory request idle time is exceeded, MCM shuts down
and restarts Intelligence Server.
Virtual Byte Depletion
Below is a diagram of potential memory depletion due to available bytes in the
Intelligence Server virtual address space.
In this example, Intelligence Server has increased its private byte usage to the
point that existing contracts are pushed above the high water mark. Request A
is denied because the requested memory would further deplete Intelligence
Server’s virtual address space.
Once request A has been denied, Intelligence Server enters the memory
request idle mode. In this mode of operation, all requests that would push the
total memory used above the low water mark are denied.
The low water mark is 95 percent of the high water mark. In this scenario, the
high water mark is the amount of Intelligence Server private bytes at the time
© 2015, MicroStrategy Inc.
Governing Intelligence Server memory use with Memory Contract
Manager
353
System Administration Guide
when the memory depletion was first detected. Once the virtual byte high
water mark has been set, it is not recalculated. Thus, for Intelligence Server to
exit memory request idle mode, it must release some of the private bytes.
Although the virtual bytes high water mark is not recalculated, the virtual
* memory high water mark is recalculated after each request. MCM
calculates the low water mark based on the lower of the virtual memory
high water mark and the virtual bytes high water mark. This accounts for
the scenario in which, after the virtual bytes high water mark is calculated,
Intelligence Server releases memory but other processes consume more
available memory. This can cause a later calculation of the virtual memory
high water mark to be lower than the virtual bytes high water mark.
Intelligence Server remains in memory request idle mode until the memory
usage looks like it does at the time of request B. The Intelligence Server
private byte usage has dropped to the point where a request can be made that
is below the low water mark. This request is granted, and MCM exits memory
request idle mode.
If Intelligence Server does not free up enough memory to process request B
before the Memory request idle time is exceeded, MCM restarts Intelligence
Server.
Governing memory for requests from MicroStrategy
Web products
You can limit the total amount of memory that Intelligence Server can use for
serving requests from MicroStrategy Web, and you can set the amount of
memory that must be kept free for requests from MicroStrategy Web. These
limits are enabled when the Web Request job throttling check box is selected.
If either condition is met, all requests from MicroStrategy Web of any nature
(log in, report execution, search, folder browsing) are denied until the
conditions are resolved. For more details about each setting, see below.
•
Maximum Intelligence Server use of total memory sets the maximum
amount of total system memory (RAM plus Page File) that can be used by
the Intelligence Server process compared to the total amount of memory
on the machine.
This setting is useful to prevent the system from servicing a Web request if
memory is depleted. If the condition is met, Intelligence Server denies all
requests from a MicroStrategy Web product or a client built with the
MicroStrategy Web API.
•
354
Minimum machine free physical memory sets the minimum amount of RAM
that must remain available for Web requests. This value is a percentage of
the total amount of physical memory on the machine, not including the
Page File memory.
Governing memory for requests from MicroStrategy Web products
© 2015, MicroStrategy Inc.
System Administration Guide
This can be useful if the machine is running applications other than
Intelligence Server and you want to increase the chances that requests from
MicroStrategy Web products are serviced using RAM and not the Page File,
which does not work as efficiently.
Managing user sessions
Each user connection from a MicroStrategy client (MicroStrategy Web,
Developer, Narrowcast Server, and others) establishes a user session on
Intelligence Server. Each user session consumes a set amount of resources on
the Intelligence Server machine and can consume additional resources
depending on the actions that the user takes while she is connected.
The number of active users in a system (those actually executing reports
* and using the system) is considered a different category of user from
concurrent users (those simply logged in).
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
This section covers:
•
How the concurrent users and user sessions on your system use system
resources just by logging in to the system (see Governing concurrent users,
page 356)
•
How memory and CPU are used by active users when they execute jobs,
run reports, and make requests, and how you can govern those requests
(see Governing user resources, page 358)
•
How user profiles can determine what users are able to do when they are
logged in to the system, and how you can govern those profiles (see
Governing user profiles, page 361)
© 2015, MicroStrategy Inc.
Governing memory for requests from MicroStrategy Web products
355
System Administration Guide
With the User Connection Monitor, you can track the users who are connected
to the system. For details about how to use this system monitor, see
Monitoring users’ connections to projects, page 61.
Governing concurrent users
When a user logs in to a MicroStrategy system, a user session is established.
This user session remains open until the user logs out of the system or the
system logs the user out. Users that are logged in but are not doing anything
still consume some resources on Intelligence Server. The more user sessions
that are allowed on Intelligence Server, the more load those users can put on
the system because each session can run multiple jobs.
To help control the load that user sessions can put on the system, you can
limit the number of concurrent user sessions allowed for each project and for
Intelligence Server. Also, both Developer and MicroStrategy Web have session
timeouts so that when users forget to log out, the system logs them out and
their sessions do not unnecessarily use up Intelligence Server resources.
For example, a user logs in, runs a report, then leaves for lunch without
logging out of the system. If Intelligence Server is serving the maximum
number of user sessions and another user attempts to log in to the system,
that user is not allowed to log in. You can set a time limit for the total
duration of a user session, and you can limit how long a session remains open
if it is inactive or not being used. In this case, if you set the inactive time limit
to 15 minutes, the person who left for lunch has her session ended by
Intelligence Server. After that, another user can log in.
Intelligence Server does not end a user session until all the jobs submitted
~ by that user have completed or timed out. This includes reports that are
waiting for autoprompt answers. For example, if a MicroStrategy Web or
Web Universal user runs a report with an autoprompt and, instead of
answering the prompt, clicks the browser’s Back button, an open job is
created. If the user then closes his or her browser or logs out without
canceling the job, the user session remains open until the open job
“Waiting for Autoprompt” times out.
These user session limits are discussed below as they relate to software
features and products.
Limiting the number of user sessions on Intelligence Server
This setting limits the number of user sessions that can be connected to an
Intelligence Server. This includes connections made from MicroStrategy Web
products, Developer, Distribution Services, Scheduler, or other applications
that you may have created with the SDK. A single user account can establish
multiple sessions on an Intelligence Server. Each session connects once to
Intelligence Server and once to each project that the user accesses. In the User
356
Governing concurrent users
© 2015, MicroStrategy Inc.
System Administration Guide
Connection Monitor, the connections made to Intelligence Server display as
<Server> in the Project column. Project sessions are governed separately with
a project level setting, User sessions per project, which is discussed below.
When the maximum number of user sessions on Intelligence Server is reached,
users cannot log in, except for the administrator, who can disconnect current
users by means of the User Connection Monitor or increase this governing
setting.
To specify this setting, in the Intelligence Server Configuration Editor, select
the Governing Rules: Default: General category and type the number in the
Maximum number of user sessions field.
Limiting user sessions per project
When a user accesses a project, a connection (called a user session) is
established for the project and Intelligence Server. In the User Connection
Monitor, the connections made to the project display the project name in the
Project column. If you sort the list of connections by the Project column, you
can see the total number of user sessions for each project.
You can limit the number of sessions that are allowed for each project. When
the maximum number of user sessions for a project is reached, users cannot
log in to the system. An exception is made for the system administrator, who
can log in to disconnect current users by means of the User Connection
Monitor or increase this governing setting.
To specify this setting, in the Project Configuration Editor for the project,
select the Governing Rules: Default: User sessions category and type the
number in the User sessions per project field.
You can also limit the number of concurrent sessions per user. This can be
useful if one user account, such as “Guest,” is used for multiple connections. To
specify this setting, in the Project Configuration Editor for the project, select
the Governing Rules: Default: User sessions category and type the number in
the Concurrent interactive project sessions per user field.
Limiting user session idle times
When a user logs in to Developer (in a three-tier configuration) or
MicroStrategy Web, a user session is established. As long as the user logged
into that session is using the project, creating or executing reports, and so on,
the session is considered active. When the user stops actively using the
session, this is considered idle time. You can specify the maximum amount of
time a session can remain idle before Intelligence Server disconnects that
session. This frees up the system resources that the idle session was using and
allows other users to log in to the system if the maximum number of user
sessions has been reached.
To specify this setting for Developer, in the Intelligence Server Configuration
Editor, select the Governing Rules: Default: General category and, in the User
© 2015, MicroStrategy Inc.
Governing concurrent users
357
System Administration Guide
session idle time (sec) field, type the number of seconds of idle time that you
want to allow.
To specify this setting for MicroStrategy Web, in the Intelligence Server
Configuration Editor, select the Governing Rules: Default: General category and,
in the Web user session idle time (sec) field, type the number of seconds of idle
time that you want to allow.
If designers are building Report Services documents and dashboards in
* MicroStrategy Web, set the Web user session idle time (sec) to 3600 to
avoid a project source timeout.
Governing user resources
User sessions consume system resources when users log in to the system,
especially when they use the History List and, in MicroStrategy Web, the
Working Set. If a Web user’s session expires and the system is configured to
allow users to recover their session information, the stored session
information uses resources. This section discusses these features and how you
can govern them.
Like all requests, user resources are also governed by the Memory
* Contract Manager settings. For more information about Memory Contract
Manager, see Governing Intelligence Server memory use with Memory
Contract Manager, page 345.
History List
The History List is an in-memory message list that references reports that a
user has executed or scheduled. The results are stored as History or MatchingHistory caches on Intelligence Server.
The History List can consume much of the system’s resources. You can govern
the resources used by old History List messages in the following ways:
358
•
You can delete messages from the History List with a scheduled
administrative task. For more information and instructions on scheduling
this task, see Scheduling administrative tasks, page 528.
•
In the Intelligence Server Configuration Editor, in the History settings:
General category, you can limit the Maximum number of messages per
user. If a user has hit this maximum and tries to add another message to
the History List, the oldest message is automatically purged.
•
In the Intelligence Server Configuration Editor, in the History settings:
General category, you can set the Message lifetime (days). Intelligence
Server automatically deletes any History List messages that are older than
the specified message lifetime.
Governing user resources
© 2015, MicroStrategy Inc.
System Administration Guide
For more information about the History List, including details on History List
governing settings, see Saving report results: History List, page 466.
Working set (MicroStrategy Web only)
When a user runs a report from MicroStrategy Web or Web Universal, the
results from the report are added to the working set for that user’s session
and stored in memory on Intelligence Server. The working set is a collection of
messages that reference in-memory report instances. A message is added to
the working set when a user executes a report or retrieves a message from the
History List. The purpose of the working set is to:
•
Improve MicroStrategy Web performance for report manipulations,
without having to run SQL against the data warehouse for each change
•
Allow the efficient use of the web browser’s Back button
•
Allow users to manually add messages to the History List
Each message in the working set can store two versions of the report instance
in memory: the original version and the result version. The original version of
the report instance is created the first time the report is executed and is held
in memory the entire time a message is part of the working set. The result
version of the report instance is added to the working set only after the user
manipulates the report. Each report manipulation adds what is called a delta
XML to the report message. On each successive manipulation, a new delta
XML is applied to the result version. When the user clicks the browser’s Back
button, previous delta XMLs are applied to the original report instance up to
the state that the user is requesting. For example, if a user has made four
manipulations, the report has four delta XMLs; when the user clicks the Back
button, the three previous XMLs are applied to the original version.
Governing History List and Working set memory use in MicroStrategy Web
You can control the amount of the memory that is used by the History List
and Working set in these ways:
•
Limit the number of reports that a user can keep available for
manipulation in a MicroStrategy Web product. This number is defined in
the MicroStrategy Web products’ interface in Project defaults: History List
settings. You must select the Manually option for adding messages to the
History List, then specify the number in the field labeled If manually, how
many of the most recently run reports and documents do you want to keep
available for manipulation? The default is 10 and the minimum is 1. The
higher the number, the more memory the reports may consume. For
details, see the MicroStrategy Web Help.
•
Limit the maximum amount of RAM that all users can use for the working
set. When the limit is reached and new report instances are created, the
least recently used report instance is swapped to disk. To set this, in the
© 2015, MicroStrategy Inc.
Governing user resources
359
System Administration Guide
Intelligence Server Configuration Editor, under the Governing Rules:
Default: Working Set category, type the limit in the Maximum RAM for
Working Set cache (MB) field.
~
Be aware of the following:
— If you set this limit to more memory than the operating system
can make available, Intelligence Server uses a value of 100 MB.
The maximum value for this setting is 65,536 MB (64 GB) on
most operating systems. It is 2048 MB (2 GB) under Windows
2003.
— If you set this limit too low and you do not have enough hard
disk space to handle the amount of disk swapping, reports may
fail to execute in peak usage periods because the reports cannot
write to memory or to disk.
If a user session has an open job, the user session remains open and that
* job’s report instance is removed from the Working set when the job has
finished or timed out. In this way, jobs can continue executing even after
the user has logged out. This may cause excessive memory usage on
Intelligence Server because the session’s working set is held in memory
until the session is closed. For instructions on how to set the timeout
period for jobs, see Limiting the maximum report execution time, page
366.
Governing saved user session information (MicroStrategy Web only)
You can allow Web users to recover their document, report, or dashboard after
their user session has been ended. If this feature is enabled and, for example,
the user runs a report and walks away from his desk and the session times out,
the user session information is saved. The next time the Web user logs in, if
the recoverable session has not expired, the user can click a link to return to
his recovered report. Enabling this feature uses disk space for storing the
information. You can govern how long the sessions are stored before expiring.
Long expiration times allow more information to be stored, thus using more
system disk space. Shortening the expiration time more quickly frees up the
system resources that the saved session was using.
To configure these settings, access the Intelligence Server Configuration Editor,
select the Governing Rules: Default: Temporary Storage Settings category. To
enable the feature, select the Enable Web User Session Recovery on Logout
check box, and in the Session Recovery backup expiration (hrs) field, type the
number of hours you want to allow a session to be stored. In Session Recovery
and Deferred Inbox storage directory, specify the folder where the user session
information is stored.
360
Governing user resources
© 2015, MicroStrategy Inc.
System Administration Guide
Governing user profiles
The user profile can be defined as what the user can do when logged in to the
system. If you allow users to use certain features in the system, they can affect
the system’s performance. For example, when users schedule report
executions, this creates user sessions on Intelligence Server, thus placing a
load on it even when the users are not actively logged in.
You can limit these types of activities by restricting various privileges, as
discussed below. For general information about privileges and the
MicroStrategy security model, including instructions on how to grant and
revoke privileges, see Controlling access to functionality: Privileges, page 72.
Subscription-related privileges
Allowing users to subscribe to reports to be run later can affect system
performance. You can limit the use of subscriptions by using the Web
Scheduled Reports and Schedule Request privileges.
If you have Distribution Services or Narrowcast Server implemented in
* your system and users have the Web Scheduled Email or Web Send Now
privileges, they can have a report emailed either at a set time or
immediately. This causes the system to create a user session on
Intelligence Server when the report is emailed.
For detailed information about subscribing to reports and documents, see
Scheduling reports and documents: Subscriptions, page 531. For information
about Distribution Services, see Overview of Distribution Services, page 546.
History List privileges
Allowing users to use the History List can consume extra system resources.
Governing History List usage is discussed more fully in the previous section
(see History List, page 358). The non-administrative privileges relating to the
History List are:
•
Web Subscribe To History List
•
Web View History List
•
Web Add To History List
•
Use Link To History List in Email (Distribution Services)
•
Use History List
© 2015, MicroStrategy Inc.
Governing user profiles
361
System Administration Guide
Report manipulation privileges
The more manipulations that you allow users to do, the greater the potential
for using more system resources. Manipulations that can use extra system
resources include pivoting, page-by, and sorting. You can limit these
manipulations with the following privileges:
•
To limit the use of pivoting, use the Web Pivot Report and Pivot Report
privileges.
•
To limit the use of page-by, use the Web Switch Page-by Elements
privilege.
•
To limit the use of sorting, use the Web Sort and Modify Sorting privilege.
Exporting privileges
Exporting reports can consume large amounts of memory, especially when
reports are exported to Excel with formatting. For more information on how
to limit this memory usage, see Limiting the number of XML cells, page 383.
The privileges related to exporting reports are found in the Common privilege
group, and are as follows:
•
Export to Excel
•
Export to Flash
•
Export to HTML
•
Export to MicroStrategy File
•
Export to PDF
•
Export to Text
*
To restrict users from exporting any reports from MicroStrategy Web, use
the Web Export privilege in the Web Reporter privilege group.
OLAP Services privileges
If you have purchased OLAP Services licenses for your users, they could use a
great deal of the available system resources. For example, if your users are
creating large Intelligent Cubes and doing many manipulations on them, the
system will be loaded much more than if they are running occasional, small
reports and not performing many manipulations.
The OLAP Services privileges are marked with a * in the list of all privileges
(see the List of Privileges chapter in the Supplemental Reference for System
Administration). For more details about how OLAP Services uses system
resources, see Intelligent Cubes, page 390.
362
Governing user profiles
© 2015, MicroStrategy Inc.
System Administration Guide
Governing requests
Each user session can execute multiple concurrent jobs or requests. This
happens when users run documents that submit multiple child reports at a
time or when they send a report to the History List, then execute another
while the first one is still executing. Users can also log in to the system
multiple times and run reports simultaneously. Again, this may use up a great
deal of the available system resources.
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
To control the number of jobs that can be running at the same time, you can
set limits on the requests that can be executed. You can limit the requests per
user and per project. You can also choose to exclude reports submitted as part
of a Report Services document from the job limits (see Excluding document
datasets from the job limits, page 364).
Specifically, you can limit:
•
The total number of jobs (Limiting the total number of jobs, page 364)
•
The number of jobs per project (Limiting the number of jobs per project,
page 364)
•
The number of jobs per user account and per user session (Limiting the
number of jobs per user session and per user account, page 365)
•
The number of executing reports or data marts per user account (not
counting element requests, metadata requests, and report manipulations)
(Limiting the number of executing jobs per user and project, page 366)
•
The amount of time reports can execute (Limiting the maximum report
execution time, page 366)
•
A report's SQL (per pass) including both its size and the time it executes
(Limiting a report's SQL per pass, page 367)
•
The amount of memory used for Intelligent Cubes (Governing Intelligent
Cube memory usage, page 507)
© 2015, MicroStrategy Inc.
Governing user profiles
363
System Administration Guide
Excluding document datasets from the job limits
Multiple jobs may be submitted when documents and reports are executed.
For example, if you execute a document that has a prompt and three reports
embedded in it, Intelligence Server processes five jobs: one for the document,
one for the prompt, and three for the embedded dataset reports.
To avoid unexpectedly preventing document from executing, you can exclude
report jobs submitted as part of document execution from the job limits. In
this case, if you execute a document that has a prompt and three reports
embedded in it, Intelligence Server would only count two jobs, the document
and the prompt, towards the job limits described below.
To exclude document dataset jobs from the job limits, in the Intelligence
Server Configuration Editor, select the Governing Rules: Default: General
category, and select the For Intelligence Server job and history list governing,
exclude reports embedded in Report Services documents from the counts check
box. This selection applies to the project-level job limits as well as to the
server-level limits.
Limiting the total number of jobs
You can limit the total number of concurrent jobs being processed by
Intelligence Server. Concurrent jobs include report requests, element requests,
and autoprompt requests that are executing or waiting to execute. Completed
(open) jobs, cached jobs, or jobs that have returned an error are not counted.
If the job limit is reached, a user sees an error message stating that the
maximum number of jobs has been reached. The user needs to submit the job
again.
To set this limit, in the Intelligence Server Configuration Editor, select the
Governing Rules: Default: General category, and specify the value in the
Maximum number of jobs field. You can also specify a maximum number of
interactive jobs (jobs executed by a direct user request) and scheduled jobs
(jobs executed by a scheduled request). A value of -1 indicates that there is no
limit on the number of jobs that can be executed.
Limiting the number of jobs per project
You can limit the number of concurrent jobs that are being processed by
Intelligence Server for a project. If you have multiple projects on an
Intelligence Server, each can have its own job limit setting. Limiting the
number of concurrent jobs per project helps reduce unnecessary strain on the
system by limiting the amount of resources that concurrently executing jobs
can take up.
Concurrent jobs include report requests, element requests, and autoprompt
requests that are executing or waiting to execute. Finished jobs that are still
364
Excluding document datasets from the job limits
© 2015, MicroStrategy Inc.
System Administration Guide
open, cached jobs, and jobs that returned an error are not counted. If the limit
is reached, a user sees an error message stating that the number of jobs per
project is too high. The user then needs to submit the job again.
In a clustered system, these settings limit the number of concurrent jobs
~ per project on each node of the cluster.
To specify this job limit setting, in the Project Configuration Editor for the
project, select the Governing Rules: Default: Jobs category, and specify the
number of concurrent jobs that you want to allow for the project in each Jobs
per project field. You can also specify a maximum number of interactive jobs
(jobs executed by a direct user request) and scheduled jobs (jobs executed by a
scheduled request). A value of -1 indicates that the number of jobs that can be
executed has no limit.
Limiting the number of jobs per user session and per
user account
If your users’ job requests place a heavy burden on the system, you can limit
the number of open jobs within Intelligence Server, including element
requests, autoprompts, and reports for a user.
•
To help control the number of jobs that can run in a project and thus
reduce their impact on system resources, you can limit the number of
concurrent jobs that a user can execute in a user session. For example, if
the Jobs per user session limit is set to four and a user has one session
open for the project, that user can only execute four jobs at a time.
However, the user can bypass this limit by logging in to the project
multiple times. (To prevent this, see the next setting, Jobs per user account
limit.)
To specify this setting, in the Project Configuration Editor for the project,
select the Governing Rules: Jobs category, and type the number in the Jobs
per user session field. A value of -1 indicates that the number of jobs that
can be executed has no limit
•
You can set a limit on the number of concurrent jobs that a user can
execute for each project regardless of the number of user sessions that user
has at the time. For example, if the user has two user sessions and the Jobs
per user session limit is set to four, the user can run eight jobs. But if this
Jobs per user account limit is set to five, that user can execute only five
jobs, regardless of the number of times the user logs in to the system.
Therefore, this limit can prevent users from circumventing the Jobs per
user session limit by logging in multiple times.
To specify this setting, in the Project Configuration Editor for the project,
select the Governing Rules: Jobs category, and type the number of jobs per
user account that you want to allow in the Jobs per user account field. A
© 2015, MicroStrategy Inc.
Limiting the number of jobs per user session and per user account
365
System Administration Guide
value of -1 indicates that the number of jobs that can be executed has no
limit.
These two limits count the number of report, element, and autoprompt job
requests that are executing or waiting to execute. Jobs that have finished,
cached jobs, or jobs that returned in error are not counted toward these limits.
If either limit is reached, any jobs the user submits do not execute and the
user sees an error message.
Limiting the number of executing jobs per user and
project
If your users tend to request jobs that do not place much burden on the
system, you may want to limit only executing reports and data marts, and still
allow users to answer autoprompts and issue element requests. You can limit
the number of concurrent reports (both regular reports and dataset reports in
a document) in a project per user account.
This limit is called Executing jobs per user. If the limit is reached for the
project, new report requests are placed in the Intelligence Server queue until
other jobs finish. They are then processed in the order in which they were
placed in the queue, which is controlled by the priority map (see Prioritizing
jobs, page 373).
To specify this limit setting, in the Project Configuration Editor for the project,
select the Governing Rules: Default: Jobs category, and type the number of
concurrent report jobs per user you want to allow in the Executing jobs per
user field. A value of -1 indicates that the number of jobs that can be executed
has no limit.
Limiting the maximum report execution time
You can limit a job in Intelligence Server by specifying the maximum amount
of time that a job can execute within a project. Intelligence Server cancels any
jobs that exceed the limit.
To set this limit, in the Project Configuration Editor, select the Governing
Rules: Default: Result Sets category, and specify the number of seconds in the
Intelligence Server Elapsed Time (sec) fields. You can set different limits for
ad-hoc reports and scheduled reports.
This limit applies to most operations that are entailed in a job from the time
it is submitted to the time the results are returned to the user. If the job
exceeds the limit, the user sees an error message and cannot view the report.
The figure below illustrates how job tasks make up the entire report execution
time. In this instance, the time limit includes the time waiting for the user to
complete report prompts. Each step is explained in the table below.
366
Limiting the number of executing jobs per user and project
© 2015, MicroStrategy Inc.
System Administration Guide
Step
Status
Comment
1
Waiting for Autoprompt
Resolving prompts
2*
Waiting (in queue)
Element request is waiting in job queue for execution
3*
Executing
Element request is executing on the database
4
Waiting for Autoprompt
Waiting for user to make prompt selections
5
Waiting (in queue)
Waiting in job queue for execution
6
Executing
Query engine executes SQL on database (can be multiple passes)
7
Executing
Analytical engine processes results
*Steps 2 and 3 are for an element request. They are executed as separate jobs.
During steps 2 and 3, the original report job has the status “Waiting for
Autoprompt.”
The following tasks are not shown in the example above because they
* consume very little time. However, they also count toward the report
execution time.
•
Element request SQL generation
•
Report SQL generation
•
Returning results from the database
For more information about the job processing steps, see Processing jobs,
page 35.
Limiting a report's SQL per pass
You can limit a report’s SQL size per pass. This includes limits on the amount
of time that each pass can take and the maximum size (in bytes) that the SQL
statement can be. These limits are set in the VLDB properties, as described
© 2015, MicroStrategy Inc.
Limiting a report's SQL per pass
367
System Administration Guide
below. For more information about VLDB properties in general, see the VLDB
Properties chapter in the Supplemental Reference for System Administration.
You can also limit the amount of memory that Intelligence Server uses during
report SQL generation. This limit is set for all reports generated on the server.
To set this limit, in the Project Configuration Editor, open the Governing
Rules: Default: Result Sets category, and specify the Memory consumption
during SQL generation. A value of -1 indicates no limit.
SQL Time Out (Per Pass) (database instance and report)
You can limit the amount of time that each pass of SQL can take within the
data warehouse. If the time for a SQL pass reaches the maximum, Intelligence
Server cancels the job and the user sees an error message. You can specify this
setting at either the database instance level or at the report level.
To specify this setting, edit the VLDB properties for the database instance or
for a report, expand Governing settings, then select the SQL Time Out (Per
Pass) option. For details, see the MicroStrategy Developer Help.
Maximum SQL Size (database instance)
You can limit the size (in bytes) of the SQL statement per pass before it is
submitted to the data warehouse. If the size for a SQL pass reaches the
maximum, Intelligence Server cancels the job and the user sees an error
message. You can specify this setting at the database instance level.
To specify this, edit the VLDB properties for the database instance, expand
Governing settings, then select the Maximum SQL Size option. For details, see
the MicroStrategy Developer Help.
Managing job execution
The system’s ability to execute jobs is limited by the available system
resources and by how those resources are used by Intelligence Server.
368
Limiting a report's SQL per pass
© 2015, MicroStrategy Inc.
System Administration Guide
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
This section discusses the different ways you have of managing job execution.
These include:
•
Managing database connection threads, page 369
•
Prioritizing jobs, page 373
•
Results processing, page 376 (the processing that Intelligence Server
performs on results returned from the data warehouse)
Managing database connection threads
The main factor that determines job execution performance is the number of
database connections that are made to the data warehouse. Report and
element requests are submitted from Intelligence Server to the data
warehouse through a database connection thread. Results of these requests are
also returned to Intelligence Server through the database connection thread.
You must determine the number of threads that strikes a good balance
between quickly serving each user request while not overloading the system.
The overall goal is to prioritize jobs and provide enough threads so that jobs
that must be processed immediately are processed immediately, and the
remainder of jobs are processed as timely as possible. If your system has
hundreds of concurrent users submitting requests, you must determine at what
point to limit the number of database connection threads by placing user
requests in a queue.
The number of available database connection threads falls in the range
depicted as the Optimal use of resources in the illustration below.
© 2015, MicroStrategy Inc.
Managing database connection threads
369
D atab ase execu tio n tim e
System Administration Guide
Optimal use of
resources
Number of database
connection threads
To monitor whether the number of database connection threads in your
system is effective, use the Database Connection Monitor. For more
information about this tool, see Monitoring database instance connections,
page 10. If all threads are “Busy” a high percentage of the time, consider
increasing the number of connection threads as long as your data warehouse
can handle the load and as long as Intelligence Server does not become
overloaded.
Once you have the number of threads calculated, you can then set job
priorities and control how many threads are dedicated to serving jobs meeting
certain criteria.
Limiting and prioritizing the number of database connections
To set the number of database connection threads allowed at a time, modify
the database instance used to connect to the data warehouse. Use the Job
Prioritization tab in the Database Instance Editor and specify the number of
high, medium, and low connections. The sum of these numbers is the total
number of concurrent connection threads allowed between Intelligence Server
and the data warehouse. These settings apply to all projects that use the
selected database instance.
You should have at least one low-priority connection available, because low
~ priority is the default job priority, and low-priority jobs can use only lowpriority database connection threads. Medium-priority connection threads
are reserved for medium- and high-priority jobs, and high-priority
connection threads are reserved for high-priority jobs only. For more
information about job priority, including instructions on how to set job
priority, see Prioritizing jobs, page 373.
370
Managing database connection threads
© 2015, MicroStrategy Inc.
System Administration Guide
*
If you set all connections to zero, jobs are not submitted to the data
warehouse. This may be a useful way for you to test whether scheduled
reports are processed by Intelligence Server properly. Jobs wait in the
queue and are not submitted to the data warehouse until you increase the
connection number, at which point they are then submitted to the data
warehouse. Once the testing is over, you can delete those jobs so they are
never submitted to the data warehouse.
Optimizing database connection threads using ODBC settings
In addition to limiting the number of database connection threads created
between Intelligence Server and the data warehouse, it is a good practice to
efficiently use those connection threads once they are established. You want to
ensure that the threads are being used and are not tied up by processes that
are running too long. To optimize how those threads are used, you can limit
the length of time they can be used by certain jobs. These limits are described
below.
To set these limits, edit the database instance, then modify the database
connection (at the bottom of the Database Instances dialog box), and on the
Database Connections dialog box, select the Advanced tab. A value of 0 or -1
indicates no limit.
Maximum cancel attempt time
When a user runs a report that executes for a long time on the data
warehouse, the user can cancel the job execution. This may be due to an error
in the report’s design, especially if it is in a project in a development
environment, or the user may simply not want to wait any longer. If the cancel
is not successful after 30 seconds, Intelligence Server deletes that job’s
database connection thread. The Maximum cancel attempt time (sec) field
controls how long you want Intelligence Server to wait in addition to the 30
seconds before deleting the thread.
Maximum query execution time
This is the maximum amount of time that a single pass of SQL can execute on
the data warehouse. When the SQL statement or fetch operation begins, a
timer starts counting. If the Maximum query execution time (sec) limit is
reached before the SQL operation is concluded, Intelligence Server cancels the
operation.
This setting is very similar to the SQL time out (per pass) VLDB setting (see
SQL Time Out (Per Pass) (database instance and report), page 368). That
VLDB setting overrides the Maximum query execution time (sec) setting. This
setting is made on the database connection and can be used to govern the
© 2015, MicroStrategy Inc.
Managing database connection threads
371
System Administration Guide
maximum query execution time across all projects that use that connection.
The VLDB setting can override this setting for a specific report.
Maximum connection attempt time
This is the maximum amount of time that Intelligence Server waits while
attempting to connect to the data warehouse. When the connection is initiated,
a timer starts counting. If the Maximum connection attempt time (sec) limit is
reached before the connection is successful, the connection is canceled and an
error message is displayed.
Limiting database connection caches
Establishing a database connection thread is expensive in terms of time and
resources. Because of this, Intelligence Server caches the threads so that every
SQL pass and job execution it performs does not need to create a new
connection. Rather, those processes simply use an existing cached thread.
However, the RDBMS may, after a certain time limit, delete the connection
threads without notifying Intelligence Server. If this happens and an
Intelligence Server job tries to use a cached connection thread, the user sees
an error message. To avoid this, you can limit the length of time that a
database connection cache can exist. You can limit the maximum lifetime of a
database connection (see Connection lifetime, page 372), and you can limit the
amount of time an inactive database connection remains open (see Connection
idle timeout, page 373).
To set these limits, edit the database instance, then modify the database
connection (at the bottom of the Database Instances dialog box), and on the
Database Connections dialog box, select the Advanced tab. For these settings, a
value of -1 indicates no limit, and a value of 0 indicates that the connection is
not cached and is deleted immediately when execution is complete.
Connection lifetime
The Connection lifetime (sec) limit is the maximum amount of time that a
database connection thread remains cached. The Connection lifetime should be
shorter than the data warehouse RDBMS connection time limit. Otherwise the
RDBMS may delete the connection in the middle of a job.
When the Connection lifetime is reached, one of the following occurs:
372
•
If the database connection has a status of Cached (it is idle, but available)
when the limit is reached, the connection is deleted.
•
If the database connection has a status of Busy (it is executing a job) when
the limit is reached, the connection is deleted as soon as the job completes.
The database connection does not go into a Cached state.
Managing database connection threads
© 2015, MicroStrategy Inc.
System Administration Guide
Connection idle timeout
The Connection idle timeout (sec) limit is the amount of time that an inactive
connection thread remains cached in Intelligence Server until it is terminated.
When a database connection finishes a job and no job is waiting to use it, the
connection becomes cached. If the connection remains cached for longer than
this timeout limit, the database connection thread is then deleted. This
prevents connections from tying up data warehouse and Intelligence Server
resources if they are not needed.
Prioritizing jobs
Job priority defines the order in which jobs are processed. Jobs are usually
executed as first-come, first-served. However, your system probably has
certain jobs that need to be processed before other jobs.
Job priority does not affect the amount of resources a job gets once it is
submitted to the data warehouse. Rather, it determines whether certain jobs
are submitted to the data warehouse before other jobs in the queue.
For example, an executive in your company runs reports at unplanned times
and you want to ensure that these reports are immediately processed. If no
priority is set for the executive’s reports, they are processed with the other
jobs in the system. Depending on data warehouse activity, this may require
some wait time. If you assign a high priority to all jobs from the executive’s
user group, Intelligence Server processes and submits those jobs to the data
warehouse first, rather than waiting for other jobs to finish.
Intelligence Server processes a job on a database connection that corresponds
to the job’s priority. If no priority is specified for a job, Intelligence Server
processes the job on a low-priority connection. For example, jobs with high
priority are processed by high-priority connections, and jobs with low or no
priority are processed by a low-priority connection. For information about
setting database connection thread priority, see Limiting and prioritizing the
number of database connections, page 370.
Intelligence Server also engages in connection borrowing when processing jobs.
Connection borrowing occurs when Intelligence Server executes a job on a
lower priority connection because no connections that correspond to the job’s
priority are available at execution time. High-priority jobs can run on high-,
medium-, and low-priority connections. Likewise, medium-priority jobs can
run on medium- and low-priority connections.
When a job is submitted and no connections are available to process it, either
with the same priority or with a lower priority, Intelligence Server places the
job in queue and then processes it when a connection becomes available.
You can set jobs to be high, medium, or low priority, by one or more of the
following variables:
© 2015, MicroStrategy Inc.
Prioritizing jobs
373
System Administration Guide
•
Request type: Report requests and element requests can have different
priority (Prioritizing jobs by request type, page 375).
•
Application type: Jobs submitted from different MicroStrategy applications,
such as Developer, Scheduler, MicroStrategy Web, or Narrowcast Server,
are processed according to the priority that you specify (Prioritizing jobs
by MicroStrategy application type, page 375).
•
User group: Jobs submitted by users in the groups you select are processed
according to the priority that you specify (Prioritizing jobs by user group,
page 375).
•
Cost: Jobs with a higher resource cost are processed according to the
priority that you specify (Prioritizing jobs by report cost, page 375). Job
cost is an arbitrary value you can assign to a report that represents the
resources used to process that job.
•
Project: Jobs submitted from different projects are processed according to
the priority that you specify (Prioritizing jobs by project, page 376).
These variables allow you to create sophisticated rules for which job requests
are processed first. For example, you could specify that any element requests
are high priority, any requests from your test project are low priority, and any
requests from users in the Developers group are medium priority.
A job is processed at the highest priority assigned to it by any rules. For
example, if you set all jobs from your test project at low priority, and all jobs
from users in the Developers group at medium priority, jobs in the test project
that are requested by users in the Developers group are processed at medium
priority.
To set job prioritization rules
374
1
On the Intelligence Server machine, in Developer, log in to a project
source. You must log in as a user with administrative privileges.
2
Expand the Administration folder, then expand Configuration Managers,
and then select Database Instances.
3
Right-click the database instance used to connect to the data warehouse
and select Prioritization. The Database Instances Editor opens with the Job
Prioritization tab selected. Any prioritization rules that have already been
created are listed in the tab.
4
To add new job prioritization rules, click New. The Job Prioritization
Wizard opens. For detailed instructions on using the wizard, press F1 to
view the Help for each page of the wizard.
Prioritizing jobs
© 2015, MicroStrategy Inc.
System Administration Guide
Prioritizing jobs by request type
You can select whether element requests or report requests are processed
first. For example, you may want element requests to be submitted to the data
warehouse before report requests, because element requests are generally used
in prompts and you do not want users to have to wait long while prompt
values load. In this case you might specify all element requests to be processed
at a high priority by default, and all report requests to be processed at a low
priority by default.
Prioritizing jobs by MicroStrategy application type
You can assign a different priority to jobs submitted from Developer,
MicroStrategy Web or Web Universal, Scheduler, and Narrowcast Server. All
jobs submitted from the specified application use the specified priority. For
example, you may want report designers to be able to quickly test their
reports, so you may specify that all jobs that are submitted from Developer
are processed at a high priority.
Prioritizing jobs by user group
You can assign a different priority to jobs submitted from different
MicroStrategy user groups. For example, you can assign all jobs from users in
the Executive user group to be processed at a high priority.
Prioritizing jobs by report cost
Report cost is an arbitrary value that you can assign to a report to help
determine its priority in relation to other requests. If you choose to use report
cost as a priority variable, you must define a set of priority groups based on
report cost. The default priority groups are:
•
Light: reports with costs between 0 and 334
•
Medium: reports with costs between 335 and 666
•
Heavy: reports with costs between 667 and 999
The set of cost groupings must cover all values from 0 to 999. You can then
assign a priority level to each priority group. For example, you can set heavy
reports to low priority, because they are likely to take a long time to process,
and set light reports to high priority, because they do not place much strain on
the system resources.
Once you determine the cost groupings, you can set the report cost value on
individual reports. For example, you notice that a report requires significantly
more processing time than most other reports. You can assign it a report cost
of 900 (heavy). In this sample configuration, the report has a low priority. For
© 2015, MicroStrategy Inc.
Prioritizing jobs
375
System Administration Guide
factors that may help you determine the cost of a report, see Results
processing, page 376.
You set the cost of a report in the report’s Properties dialog box, in the
Priority category. You must have system administrator privileges to set the
cost of a report.
To set the cost for a report
1
In Developer, right-click the report and select Properties. The Properties
dialog box opens.
2
Select the Priority category.
3
In the Report Cost field, type the cost of the report. Higher numbers
indicate a report that uses a great deal of system resources. Lower
numbers indicate a less resource-intensive report.
4
Click OK. The Properties dialog box closes and the cost of the report is set.
Prioritizing jobs by project
You can assign a different priority to reports from different projects. For
example, you may want all jobs submitted from your production project to
have a medium priority, so that they take precedence over reports from your
test project.
Results processing
When Intelligence Server processes results that are returned from the data
warehouse, several factors determine how much of the machine’s resources are
used. These factors include:
376
•
Whether Intelligence Server is using thread balancing (see Intelligence
Server thread balancing, page 377)
•
The size of the report (see Limiting the maximum report size, page 377)
•
Whether the report is an Intelligent Cube (see Limiting the size and
number of Intelligent Cubes, page 380)
•
Whether the report is imported from an external data source (see Limiting
the memory used during data fetching, page 381)
Results processing
© 2015, MicroStrategy Inc.
System Administration Guide
Intelligence Server thread balancing
By default, threads within Intelligence Server process tasks in the order that
they are received. You can configure Intelligence Server to allocate threads to
processes, such as object serving, element serving, SQL generation, and so
forth, that need them most, while less loaded processes can return threads to
the available pool.
To enable thread balancing for Intelligence Server, in the Intelligence Server
Configuration Editor, in the Server Definition: Advanced category, select the
Balance MicroStrategy Server threads check box.
Limiting the maximum report size
A report instance is the version of the report results that Intelligence Server
holds in memory for cache and working set results. The size of the report
instance is proportional to the size of the report results, that is, the row size
multiplied by the number of rows.
The row size depends on the data types of the attributes and metrics on the
report. Dates are the largest data type. Text strings, such as descriptions and
names, are next in size, unless the description is unusually long, in which case
they may be larger than dates. Numbers, such as IDs, totals, and metric values,
are the smallest.
The easiest way to estimate the amount of memory that a report uses is to
view the size of the cache files using the Cache Monitor in Developer. The
Cache Monitor shows the size of the report results in binary format, which
from testing has proven to be 30 to 50 percent of the actual size of the report
instance in memory. For instructions on how to use the Cache Monitor to view
the size of a cache, see Monitoring result caches, page 447.
Intelligence Server allows you to govern the size of a report or request in the
following ways:
•
Limiting the number of report result rows, page 377
•
Limiting the number of element rows, page 378
•
Limiting the number of intermediate rows, page 379
*
Like all requests, large report instances are also governed by the Memory
Contract Manager settings. For more information about Memory Contract
Manager, see Governing Intelligence Server memory use with Memory
Contract Manager, page 345.
Limiting the number of report result rows
Reports with a large number of result rows can take up a great deal of
memory at run time. For example, your data warehouse may contain daily
© 2015, MicroStrategy Inc.
Results processing
377
System Administration Guide
sales data for thousands of items over several years. If a user attempts to build
a report that lists the revenue from every item for every day in the data
warehouse, the report may use all available Intelligence Server memory.
You can limit a report’s size in Intelligence Server by setting a maximum limit
on the number of rows that a report can contain. This setting is applied by the
Query Engine when retrieving the results from the database. If the report
exceeds this limit, the report is not executed and an error message is
displayed.
To set the maximum number of result rows for all reports, data marts, and
Intelligent Cubes in a project, in the Project Configuration Editor, expand the
Governing Rules: Default: Result Sets category, and type the maximum number
in the appropriate Final Result Rows field. You can set different limits for
standard reports, Intelligent Cubes, and data marts.
You can also set the result row limit for a specific report in that report’s VLDB
properties. The VLDB properties limit for a report overrides the project limit.
For example, if you set the project limit at 10,000 rows, but set the limit to
20,000 rows for a specific report that usually returns more than 10,000 rows,
users are able to see that report without any errors.
To set the result set limit for a specific report
1
In Developer, right-click the report to set the limit for and select Edit. The
Report Editor opens.
2
From the Data menu, select VLDB properties. The VLDB Properties dialog
box opens.
3
Expand the Governing settings, then select Results Set Row Limit.
4
Make sure the Use default inherited value check box is cleared.
5
In the Results Set Row Limit field, type the limit.
6
Click Save and Close to save the VLDB properties and close the VLDB
Properties dialog box.
7
Click Save and Close to save the report and its changed VLDB properties.
Limiting the number of element rows
Another way that you can limit the size of a request is to limit the number of
element rows returned at a time. Element rows are returned when a user
accesses a report prompt, and when using the Data Explorer feature in
Developer.
Element rows are incrementally fetched, that is, returned in small batches,
from the data warehouse to Intelligence Server. The size of the increment
378
Results processing
© 2015, MicroStrategy Inc.
System Administration Guide
depends on the maximum number of element rows specified in the client.
Intelligence Server incrementally fetches four times the number for each
element request.
For more information about element requests, such as how they are created,
how incremental fetch works, and the caches that store the results, see
Element caches, page 482.
MicroStrategy recommends that you set the element row limit to be larger
than the maximum number of attribute element rows that you expect users to
browse. For example, if the Product table in the data warehouse has 10,000
rows that users want to browse and the Order table has 200,000 rows that
you do not expect users to browse, you should set this limit to 11,000.
Intelligence Server incrementally fetches the element rows. If the element
rows limit is reached, the user sees an error message and cannot view the
prompt or the data.
To set the maximum number of element rows returned for all element
requests in a project in Developer, in the Project Configuration Editor for that
project, expand the Governing Rules: Default: Result Sets category and type the
number in the All element browsing result rows field.
To set the number of objects returned for requests in MicroStrategy
Web
1
In MicroStrategy Web, log in to a project as a user with the Web
Administration privilege.
2
Click the MicroStrategy icon, then select Preferences. The Web Preferences
page opens.
3
Select Project defaults, and then select the General category.
4
In the Incremental Fetch section, specify the values in the Maximum
number of attribute elements per block and Maximum number of report
objects per block fields.
5
Click OK. The new maximum values are saved.
Limiting the number of intermediate rows
You can limit a report’s size on Intelligence Server by setting a maximum
number of intermediate result rows that are allowed in Intelligence Server.
This limit does not apply to the rows in intermediate or temporary tables
created in the data warehouse. Rather, it controls the number of rows held in
memory in the Analytical Engine processing unit of Intelligence Server for
analytic calculations that cannot be done on the database. Lowering this
setting reduces the amount of memory consumed for large reports. If the limit
© 2015, MicroStrategy Inc.
Results processing
379
System Administration Guide
is reached, the user sees an error message and cannot view the report. For
example, this may happen when you add a complex subtotal to a large report
or when you pivot a large report.
To specify this limit for all reports in a project, in the Project Configuration
Editor, select the Governing Rules: Default: Result Sets category and type the
number in the All intermediate result rows box.
You can also set the intermediate row limit for a specific report in that
report’s VLDB properties. The VLDB properties limit for the report overrides
the project limit. For example, if you set the project limit at 10,000 rows but
set the limit to 20,000 rows for a specific report that usually returns more
than 10,000 rows, users are able to see that report without any errors.
To set the Intermediate row limit for a specific report
1
In Developer, right-click the report to set the limit for and select Edit. The
Report Editor opens.
2
From the Data menu, select VLDB properties. The VLDB Properties dialog
box opens.
3
Expand the Governing settings, then select Intermediate Row Limit.
4
Make sure the Use default inherited value check box is cleared.
5
In the Intermediate Row Limit field, type the limit.
6
Click Save and Close to save the VLDB properties and close the VLDB
Properties dialog box.
7
Click Save and Close to save and close the report.
Limiting the size and number of Intelligent Cubes
If you have purchased OLAP Services licenses from MicroStrategy, your report
designers can create Intelligent Cube reports. These Intelligent Cubes must be
stored in Intelligence Server memory for reports to access their data. This may
cause a shortage of memory for other processes on the Intelligence Server
machine.
You can govern the amount of resources used by Intelligent Cubes by limiting
the amount of memory used by Intelligent Cubes and by limiting the number
of Intelligent Cubes that can be loaded into memory.
To specify these settings, in the Project Configuration Editor for the project,
select the Cubes: General category and type the new values in the Maximum
RAM usage (MBytes) and Maximum number of cubes fields. For detailed
information on governing Intelligent Cube memory usage, see Defining
memory limits for Intelligent Cubes, page 512.
380
Results processing
© 2015, MicroStrategy Inc.
System Administration Guide
Limiting the memory used during data fetching
Certain MicroStrategy features enable you to fetch data from external data
sources, such as web services, MDX cubes, or Excel spreadsheets. When data is
fetched from one of these data sources, it is temporarily stored in Intelligence
Server memory while being converted to a report. This can cause a shortage of
memory for other processes on the Intelligence Server machine.
You can govern the amount of memory used for an individual data fetch in the
Project Configuration Editor. Select the Governing Rules: Default: Result Sets
category, and type the new value in the Memory consumption during data
fetching (MB) field. The default value is -1, indicating no limit.
Governing results delivery
After Intelligence Server processes the results of a job (see Managing job
execution, page 368), it then delivers the results to the user. In a three-tier
system, results delivery uses very little of the system resources. Most of the
tuning options for results delivery are focused on a four-tier system involving
MicroStrategy Web.
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
To deliver results, when a report is first run or when it is manipulated,
Intelligence Server generates XML and sends it to the MicroStrategy Web
server. The Web server then translates the XML into HTML for display in the
user’s web browser.
You can set limits in two areas to control how much information is sent at a
time. The lower of these two settings determines the maximum size of results
that Intelligence Server delivers at a time:
•
How many rows and columns can be displayed simultaneously in
MicroStrategy Web (see Limiting the information displayed at one time,
page 382)
© 2015, MicroStrategy Inc.
Results processing
381
System Administration Guide
•
How many XML cells in a result set can be delivered simultaneously (see
Limiting the number of XML cells, page 383)
The following settings also govern results delivery:
•
The maximum size of a report that can be exported (see Limiting export
sizes, page 384 and Limiting the memory consumption for file generation,
page 384)
•
The number of XML drill paths in a report (see Limiting the total number
of XML drill paths, page 385)
Like all requests, displayed and exported reports are also governed by the
* Memory Contract Manager settings. For more information about Memory
Contract Manager, see Governing Intelligence Server memory use with
Memory Contract Manager, page 345.
Limiting the information displayed at one time
In MicroStrategy Web, if a report contains a large amount of data, it can use a
great deal of the system resources and take a significant amount of time before
it is displayed to the user. You can lessen the impact of these large reports by
limiting the maximum number of rows and columns that are displayed. If a
report’s result set is larger than these limits, the report is broken into pages
(increments) that are fetched from the server one at a time.
The size of these increments can be set as project defaults by the
MicroStrategy Web administrator. Users with the Web Change User
Preferences privilege can also customize these sizes. For more information
about these increments, see the information on Incremental fetch in the
MicroStrategy Web Help.
To limit the number of rows and columns for all users
382
1
In MicroStrategy Web, log in to a project as a user with the Web
Administration privilege.
2
Click the MicroStrategy icon, then click Preferences. The Web Preferences
page opens.
3
Select Project defaults, and then select the Grid display category.
4
Specify the values in the Maximum rows in grid and Maximum columns in
grid fields.
5
Click OK. The new maximum values are saved.
Limiting the information displayed at one time
© 2015, MicroStrategy Inc.
System Administration Guide
To limit the number of rows and columns for one user
1
In MicroStrategy Web, log in to a project as a user with the Web Change
User Preferences privilege.
2
Click the MicroStrategy icon, then click Preferences. The Web Preferences
page opens.
3
Select the Grid display category.
4
Specify the values in the Maximum rows in grid and Maximum columns in
grid fields.
*
5
If the user sets the number of rows and columns too high, the number
of XML cells limit that is set in Intelligence Server (see Limiting the
number of XML cells, page 383) governs the size of the result set.
Click OK. The new maximum values are saved for that user.
Limiting the number of XML cells
When large report result sets are generated into XML, they can require a
significant amount of Intelligence Server memory. MicroStrategy Web handles
this by implementing the incremental fetch feature (see Limiting the
information displayed at one time, page 382). You can also govern the result
set’s size by setting the Maximum number of XML cells at the Intelligence
Server level. This determines the maximum number of cells that can be
returned from Intelligence Server to the Web server at a time. For this limit,
the number of cells is the number of rows multiplied by the number of metric
columns. Attribute cells are not considered.
For example, if the XML limit is set at 10,000 and a report has 100,000
metric cells, the report is split into 10 pages. The user clicks the page number
to view the corresponding page.
Additionally, when users export large reports from MicroStrategy Web as
formatted data, the XML is generated in batches. This XML limit determines
how large the batches are. Depending on this XML limit, Intelligence Server
behaves differently:
•
If the limit is smaller, it takes a longer time to generate the XML because
it is generated in small batches, which use less memory and system
resources.
•
If the limit is larger, it takes a shorter time to generate the XML because it
is generated in fewer, but larger, batches, which use more memory and
system resources.
© 2015, MicroStrategy Inc.
Limiting the number of XML cells
383
System Administration Guide
To set the XML limit, in the Intelligence Server Configuration Editor, select
the Governing Rules: Default: File Generation category, then specify the
Maximum number of XML cells. You must restart Intelligence Server for the
new limit to take effect.
Limiting export sizes
When users export a report from MicroStrategy Web, the results are not
constrained by the incremental fetch limit or the XML limit. To govern the
size of reports that can be exported, you can set limits on the number of cells
for various export formats.
To limit the number of rows and columns for all users
1
In MicroStrategy Web, log in to a project as a user with the Web
Administration privilege.
2
Click the MicroStrategy icon, then click Preferences. The Web Preferences
page opens.
3
Select Project defaults, and then select the Export Reports category.
4
Specify the values in the Maximum number of cells to export to plain text
and Maximum number of cells to export to HTML and Excel with formatting
fields.
5
Click OK. The new maximum values are saved.
Limiting the memory consumption for file generation
Exporting a report to a different format can consume a great deal of memory.
The amount of memory available for use by exporting files from MicroStrategy
Web is governed by the maximum memory consumption limits in the
Intelligence Server Configuration Editor. If an export attempts to use more
memory than these settings allow, the export fails with the error message
“MicroStrategy Intelligence Server cannot handle your request because a
memory request has exceeded the configured limit. Please contact the server
administrator.”
The more formatting an exported report has, the more memory it consumes.
When exporting large reports the best options are plain text or CSV file
formats because formatting information is not included with the report data.
In contrast, exporting reports as Excel with formatting uses a significant
amount of memory because the exported Excel file contains both the report
data and all the formatting data. For more information about exporting
384
Limiting export sizes
© 2015, MicroStrategy Inc.
System Administration Guide
reports, see What happens when I export a report from MicroStrategy Web?,
page 48.
Because Excel export uses significantly more memory than other export
formats, you can limit the size of reports exported to Excel from Developer as
well as from Web. The default memory consumption limit is 100 MB.
To set the maximum memory consumption limits for exporting reports from
Web, in the Intelligence Server Configuration Editor, select the Governing
Rules: Default: File Generation category, and specify the Maximum memory
consumption for the XML, PDF, Excel, and HTML files.
Depending on your Memory Contract Manager settings, an export can use
* less memory than specified by these settings and still be denied because of
a lack of memory. For more information about Memory Contract Manager,
see Governing Intelligence Server memory use with Memory Contract
Manager, page 345.
To set the maximum memory consumption for Excel file generation
1
In Developer, log in to a project source using an account with the Configure
Server Basic privilege.
2
From the Tools menu, select Project Source Manager. The Project Source
Manager opens.
3
Select the project source and click Modify. The Project Source Manager for
that project source opens.
4
On the Governing tab, in the Export to Excel section, select Use custom
value. In the Maximum RAM Usage (MB) field, specify the maximum
memory consumption.
5
Click OK. The Project Source Manager closes and the limit is saved.
Limiting the total number of XML drill paths
Another way that you can prevent reports from consuming too much memory
is to limit the number of XML drill paths allowed on reports in MicroStrategy
Web products. The default drill map for reports uses all attributes included in
hierarchies marked as drill hierarchies. Report designers can significantly
reduce the size of an attribute’s drill path by modifying a report’s drill map to
include fewer drill options. You can also impose a limit for all reports coming
from MicroStrategy Web products by setting the Maximum number of XML
drill paths.
© 2015, MicroStrategy Inc.
Limiting the total number of XML drill paths
385
System Administration Guide
For more information about customizing drill maps, see the MicroStrategy
Advanced Reporting Guide.
To set this limit, in the Intelligence Server Configuration Editor, select the
Governing Rules: Default: File Generation category, then specify the Maximum
number of XML drill paths. You must restart Intelligence Server for the new
limit to take effect.
Disabling XML caching for a project may have a negative effect on
* performance, especially for large reports. For more information, see XML
caches, page 442 and ACLs and personalized drill paths in MicroStrategy
Web, page 71.
Tuning your system for in-memory datasets
You can import large datasets into your Intelligence Server’s memory as
Intelligent Cubes, and divide the Intelligent Cubes into multiple segments.
These segments, called partitions, are processed simultaneously, distributed
across the processor cores of your Intelligence Server.
By storing your data in your Intelligence Server’s memory and processing the
data using all the server’s processor cores, you can analyze large and complex
datasets with very fast response times.
The following sections cover the settings you can configure to improve the
performance of your in-memory datasets:
•
Configuring Intelligence Server for in-memory datasets, page 386
•
Configuring your projects for in-memory datasets, page 387
Configuring Intelligence Server for in-memory datasets
To ensure the best performance for your partitioned in-memory datasets, you
can configure the following settings for your Intelligence Server:
•
386
Consider increasing the number of database connections that Intelligence
Server uses to connect to data sources. When users import data into
Intelligence Server’s memory, the job to connect to the data source is given
a low priority. To allow Intelligence Server to retrieve large datasets, you
can increase the number of low-priority database connections that
Intelligence Server can make.
Configuring Intelligence Server for in-memory datasets
© 2015, MicroStrategy Inc.
System Administration Guide
For background information on prioritizing jobs, see Prioritizing jobs. For
background information on changing the number of database connections,
see Limiting and prioritizing the number of database connections.
•
Consider increasing the maximum time that a database query is allowed to
run, to ensure that the Intelligence Server has more time to retrieve large
datasets from the data source. For background information on increasing
the execution time for database queries, see Optimizing database
connection threads using ODBC settings
Configuring your projects for in-memory datasets
For each of your projects that uses in-memory datasets, you can make the
following changes to improve the performance of your in-memory datasets:
•
Increase the maximum size of the datasets that your users can import. If
your users need to import large datasets into a project, you can increase
the limit on the size of the dataset that they can import. For steps to
increase this limit, see Defining limits for Intelligent Cubes created using
the Import Data feature.
•
Enable parallel queries for the reports in your project, so that Intelligence
Server can execute database queries in parallel and retrieve more data
from your database. For steps to enable parallel queries, and to define the
maximum number of parallel queries that can be run for every report, see
the Supplemental Reference for System Administration.
Designing reports
In addition to the fact that large reports can exert a heavy toll on system
performance, a report’s design can also affect it. Some features consume more
of the system’s capacity than others when they are used.
© 2015, MicroStrategy Inc.
Configuring your projects for in-memory datasets
387
System Administration Guide
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
Some report design features that can use a great deal of system resources
include:
•
Complex analytic calculations (Analytic complexity, page 388)
•
Subtotals (Subtotals, page 388)
•
Page-by (Page-by feature, page 389)
•
Prompt complexity (Prompt complexity, page 389)
•
Report Services documents (Report Services documents, page 389)
•
Intelligent Cubes (Intelligent Cubes, page 390)
Analytic complexity
Calculations that cannot be done with SQL in the data warehouse are
performed by the Analytical Engine in Intelligence Server. These may result in
significant memory use during report execution. Some analytic calculations
(such as AvgDev) require the entire column of the fact table as input to the
calculation. The amount of memory used depends on the type of calculation
and the size of the report that is used. Make sure your report designers are
aware of the potential effects of these calculations.
Subtotals
The amount of memory required to calculate and store subtotals can be
significant. In some cases, the size of the subtotals can surpass the size of the
report result itself.
The size of the subtotals depends on the subtotaling option chosen, along with
the order and the number of unique attributes. The easiest way to determine
the number of subtotals being calculated is to examine the number of result
rows added with the different options selected in the Advanced Subtotals
388
Analytic complexity
© 2015, MicroStrategy Inc.
System Administration Guide
Options dialog box. To access this dialog box, view the report in Developer,
then point to Data, then Subtotals, and then choose Advanced. For more
detailed information about the different subtotal options, see the Reports
chapter in the Advanced Reporting Guide.
Subtotals can use a great deal of memory if you select the All Subtotals option
in the Pages drop-down list. This option calculates all possible subtotal
calculations at runtime and stores the results in the report instance.
MicroStrategy recommends that you encourage users and report designers to
use less taxing options for calculating subtotals across pages, such as Selected
Subtotals and Grand Total.
Page-by feature
If designers or users create reports that use the page-by feature, they may use
significant system resources. This is because the entire report is held in
memory even though the user is seeing only a portion of it at a time. To lessen
the potential effect of using page-by with large reports, consider splitting those
reports into multiple reports and eliminating the use of page-by. For more
information about page-by, see the Advanced Reporting Guide.
Prompt complexity
Each attribute element or hierarchy prompt requires an element request to be
executed by Intelligence Server. The number of prompts used and the number
of elements returned from the prompts determine how much load is placed on
Intelligence Server. Report designers should take this into account when
designing prompted reports.
In addition to limiting the number of elements returned from element
requests (as described in Limiting the number of element rows, page 378),
you should make sure your element caches are being used effectively. For
information on managing element caches, including instructions, see Element
caches, page 482.
Report Services documents
Report Services documents may contain multiple reports. Executing a
document can result in several report requests being submitted
simultaneously. In addition, Flash dashboards can often require a great deal of
resources to render.
To limit the effect of Report Services documents on the system, consider
enabling document caching. If the documents are cached on Intelligence Server,
less load is placed on the data warehouse and on the Intelligence Server
machine. For information about document caching, including instructions, see
Result caches, page 438.
© 2015, MicroStrategy Inc.
Page-by feature
389
System Administration Guide
Intelligent Cubes
With OLAP Services features, your report designers can create Intelligent Cube
reports. These reports allow data to be returned from the data warehouse,
stored in Intelligence Server memory, and then shared among multiple
reports.
Because Intelligent Cubes must be loaded into memory to be used in reports,
they can use a great deal of system resources. Make sure your report designers
are familiar with the Intelligent Cube design best practices found in Best
practices for reducing Intelligent Cube memory size, page 509.
You can also restrict the number and size of Intelligent Cubes that can be
loaded at once. For instructions, see Limiting the size and number of
Intelligent Cubes, page 380.
Configuring Intelligence Server and projects
At times you may need to adjust settings in the MicroStrategy system, either
as a result of changes to the system or to improve an aspect of system
efficiency. This section provides an overview of the governing settings
throughout the system.
System resources
Architecture
Intelligence Server
Capacity
Requests
User Sessions
- Active users
- User resources
- User profile
Number of users
Performance
Functionality
Executing Jobs
- Connection threads
- Job prioritization
- Results processing
Users
Databases
Results
Report design
Configuring Intelligence
Server and Projects
These governors are arranged by where in the interface you can find them.
390
•
Intelligence Server Configuration Editor (including project distribution
settings) (Intelligence Server Configuration Editor, page 391)
•
Project Configuration Editor (Project Configuration Editor, page 396)
•
Database connections (Database connection, page 400)
•
VLDB settings (VLDB settings, page 401)
Intelligent Cubes
© 2015, MicroStrategy Inc.
System Administration Guide
Intelligence Server Configuration Editor
To set the following governors in the Intelligence Server Configuration Editor,
right-click the project source, select Configure MicroStrategy Intelligence
Server, then select the category as described below.
Only the categories and settings in the Intelligence Server Configuration Editor
that affect system scalability are described below. Other categories and
settings that appear in the Intelligence Server Configuration Editor are
described elsewhere in this guide, and in the Help for the editor. (From within
the editor, press Help.)
Server definition: General category in Intelligence Server configuration
Governor
Description
See page
Number of
network
threads
Controls the number of network connections available for communication
between Intelligence Server and the client, such as Developer or
MicroStrategy Web.
How the network
can affect
performance
Server definition: Advanced category in Intelligence Server configuration
Governor
Description
See page
Backup
frequency
(minutes)
Controls the frequency (in minutes) at which cache and History List
messages are backed up to disk. A value of 0 means that cache and history
messages are backed up immediately after they are created.
Cache duration
(Hours)
Balance
MicroStrategy
Server threads
Controls whether threads in Intelligence Server are allocated to processes
such as object serving, element serving, SQL generation, and so on that
need them most, while processes with lighter loads can return threads to
the available pool.
Results
processing
Cache lookup
cleanup
frequency (sec)
Cleans up the cache lookup table at the specified frequency (in seconds).
This reduces the amount of memory the cache lookup table consumes and
the time Intelligence Server takes to back up the lookup table to disk.
Cache duration
(Hours)
Project failover
latency (min.)
The amount of time (the delay) before the project is loaded on another
server to maintain minimum level availability.
Project failover
latency
Configuration
recovery
latency (min.)
When the conditions that caused a project failover disappear, the failover
configuration reverts automatically to the original configuration. This
setting is the amount of time (the delay) before the failover configuration
reverts to the original configuration.
Configuration
recovery
latency
Enable
performance
monitoring
Configures additional MicroStrategy-specific monitors in Windows
Performance Monitor.
Monitoring
memory use
with
Performance
Monitor
Governing Rules: Default: General category in Intelligence Server configuration
© 2015, MicroStrategy Inc.
Intelligence Server Configuration Editor
391
System Administration Guide
Governor
Description
See page
Maximum number of
jobs
The maximum concurrent number of jobs that can exist on an
Intelligence Server.
Limiting the
total
number of
jobs
Maximum number of
interactive jobs
Limits the number of concurrent interactive (nonscheduled) jobs that
can exist on this Intelligence Server. A value of -1 indicates no limit.
Limiting the
total
number of
jobs
Maximum number of
scheduled jobs
Limits the number of concurrent scheduled jobs that can exist on this
Intelligence Server. A value of -1 indicates no limit.
Limiting the
total
number of
jobs
Maximum number of
user sessions
The maximum number of user sessions (connections) for an
Intelligence Server. A single user account may establish multiple
sessions to an Intelligence Server.
Limiting the
number of
user
sessions on
Intelligence
Server
User session idle time
(sec)
The time allowed for a Developer user to remain idle before his or her
session is ended. A user session is considered idle when it submits no
requests to Intelligence Server.
Limiting
user
session idle
times
Web user session idle
time (sec)
The time allowed for a Web user to remain idle before his or her
session is ended.
Limiting
user
session idle
times
Note: If designers will be building Report Services documents and
dashboards in MicroStrategy Web, set the Web user session idle
time (sec) to 3600 to avoid a project source timeout.
For Intelligence Server
and history list
governing, exclude
reports embedded in
Report Services
documents from the
counts
Do not include reports submitted as part of a document in the count
of jobs for the job limits.
Background Execution:
Enable background
execution of documents
after their caches are
hit.
If selected, when a document cache is hit, Intelligence Server displays
the cached document and re-executes the document in the
background. If this option is cleared, when a document cache is hit,
Intelligence Server displays the cached document and does not reexecute the document until a manipulation is performed. By default
this option is cleared.
Excluding
document
datasets
from the job
limits
Governing Rules: Default: File Generation category in Intelligence Server
configuration
392
Governor
Description
See page
XML Generation:
Maximum number
of XML cells
The maximum number of XML cells in a report result set that Intelligence
Server can send to the MicroStrategy Web products at a time. When this
limit is reached, the user sees an error message along with the partial
Limiting the
number of
XML cells
Intelligence Server Configuration Editor
© 2015, MicroStrategy Inc.
System Administration Guide
Governor
Description
See page
result set. The user can incrementally fetch the remaining cells.
XML Generation:
Maximum number
of XML drill paths
The maximum number of attribute elements that users can see in the
drill across menu in MicroStrategy Web products. If this setting is set too
low, the user does not see all the available drill attributes.
Limiting the
total number
of XML drill
paths
XML Generation:
Maximum
memory
consumption for
XML (MB)
The maximum amount of memory (in megabytes) that Intelligence Server
can use to generate a report or document in XML. If this limit is reached,
the XML document is not generated and the user sees an error message.
Limiting the
memory
consumption
for file
generation
PDF Generation:
Maximum
memory
consumption for
PDF files (MB)
The maximum amount of memory (in megabytes) that Intelligence Server
can use to generate a report or document in PDF. If this limit is reached,
the PDF document is not generated and the user sees an error message.
Limiting the
memory
consumption
for file
generation
Excel Generation:
Maximum
memory
consumption for
Excel files (MB)
The maximum amount of memory (in megabytes) that Intelligence Server
can use to generate a report or document in Excel. If this limit is reached,
the Excel document is not generated and the user sees an error message.
Limiting the
memory
consumption
for file
generation
HTML Generation:
Maximum
memory
consumption for
HTML files (MB)
The maximum amount of memory (in megabytes) that Intelligence Server
can use to generate a report or document in HTML. If this limit is
reached, the HTML document is not generated and the user sees an error
message.
Limiting the
memory
consumption
for file
generation
Governing Rules: Default: Memory Settings category in Intelligence Server
configuration
Governor
Description
See page
Enable Web
request job
throttling
A check box that enables the following governors:
Governing memory for requests
from MicroStrategy Web products
• Maximum Intelligence Server use of total
memory
• Minimum machine free physical memory
Maximum
Intelligence
Server use of
total memory
(%)
The maximum amount of total system memory (RAM +
Page File) that can be used by the Intelligence Server
process (MSTRSVR.exe) compared to the total
amount of memory on the machine. If the limit is met,
all requests from MicroStrategy Web products of any
nature (log in, report execution, search, folder
browsing) are denied until the conditions are resolved.
Maximum Intelligence Server use of
total memory sets the maximum
amount of total system memory
(RAM plus Page File) that can be
used by the Intelligence Server
process compared to the total
amount of memory on the machine.
Minimum
machine free
physical
memory (%)
The minimum amount of physical memory (RAM) that
needs to be available, as a percentage of the total
amount of physical memory on the machine. If the
limit is met, all requests from MicroStrategy Web
products (e.g., log in, report execution, search, folder
browsing) are denied until the conditions are resolved.
Minimum machine free physical
memory sets the minimum amount
of RAM that must remain available
for Web requests. This value is a
percentage of the total amount of
physical memory on the machine,
© 2015, MicroStrategy Inc.
Intelligence Server Configuration Editor
393
System Administration Guide
Governor
Description
See page
not including the Page File memory.
Enable single
memory
allocation
governing
A check box that enables the Maximum single
allocation size governor.
Using the Memory Contract
Manager
Maximum
single
allocation size
(MBytes)
Prevents Intelligence Server from granting a request
that would exceed this limit.
Using the Memory Contract
Manager
Enable
memory
contract
management
A check box that enables the following governors:
Using the Memory Contract
Manager
• Minimum reserved memory (MB or %)
• Maximum use of virtual address space (%)
• Memory request idle time
Minimum
reserved
memory
(MBytes or %)
The amount of system memory, in either MB or a
percent, that must be reserved for processes external
to Intelligence Server.
Using the Memory Contract
Manager
Maximum use
of virtual
address space
(%)
The maximum percent of the process’ virtual address
space that Intelligence Server can use before entering
memory request idle mode.
Using the Memory Contract
Manager
Memory
request idle
time (sec)
The amount of time Intelligence Server denies
requests that may result in memory depletion. If
Intelligence Server does not return to acceptable
memory conditions before the idle time is reached,
Intelligence Server shuts down and restarts.
Using the Memory Contract
Manager
Temporary
Storage
Setting:
Maximum
RAM for
Working Set
cache (MB)
The maximum amount of memory that can be used for
report instances referenced by messages in the
Working Set.
Working set (MicroStrategy Web
only)
This setting is used in 32-bit operating systems and is
no longer applicable. In 64-bit operating systems, to
control the amount of memory available for
Intelligence Server, use the Minimum reserved
memory governor.
Governing Rules: Default: Temporary Storage Settings category in Intelligence
Server configuration
394
Governor
Description
See page
Working Set file
directory
The location where the user's active working sets are written to
disk if they have been forced out of the pool of memory
allocated for the Maximum RAM for working set cache. The
default is
Governing saved user
session information
(MicroStrategy Web
only)
Intelligence Server Configuration Editor
© 2015, MicroStrategy Inc.
System Administration Guide
Governor
Description
See page
.\TmpPool
Session Recovery
and Deferred
Inbox storage
directory
Specifies the where the session information is written to disk.
The default is .\TmpPool
Governing saved user
session information
(MicroStrategy Web
only)
Enable Web User
Session Recovery
on Logout
If selected, allows Web users to recover their sessions.
Governing saved user
session information
(MicroStrategy Web
only)
Session Recovery
backup expiration
(hrs)
How many hours a session backup can remain on disk before it
is considered expired. After it is expired, the user cannot recover
the session.
Governing saved user
session information
(MicroStrategy Web
only)
Governing Rules: Default: Import Data category in Intelligence Server
configuration
Governor
Description
See page
Number of
connections
by priority
The number of connection threads to create for Import Data jobs, depending on
whether the priority of the job is high, medium or low. You must determine the
number of threads that quickly serves users without overloading the system.
Managing
database
connection
threads
Governing Rules: Default: Catalog cache category in Intelligence Server
configuration
Governor
Description
See
page
Enable catalog cache
A check box that enables the Maximum use of memory (MB) governor.
Maximum use of
memory (MB)
Limits the maximum amount of memory, in megabytes, used by the catalog
cache. The default value is 25 MB
History Settings: General category in Intelligence Server configuration
Governor
Description
See page
Maximum
number of
messages per
user
The maximum number of History messages that can exist in a user’s
History List at any time. When the limit is reached, the oldest
message is removed.
Saving report
results:
History List
© 2015, MicroStrategy Inc.
Intelligence Server Configuration Editor
395
System Administration Guide
Governor
Description
See page
Message
lifetime (days)
The length of time before a History List message expires and is
automatically deleted. A value of -1 indicates that messages do not
expire.
Saving report
results:
History List
Repository type
Select File Based for History List messages to be stored on disk in a
file system, or Database Based for History List messages to be
stored in a database (recommended).
Saving report
results:
History List
Project Configuration Editor
These governors can be set per project. To access them, right-click the project,
select Project Configuration, then select the category as noted below.
Project definition: Advanced category
Governor
Description
See page
Maximum number
of elements to
display
The maximum number of attribute elements that can
be being retrieved from the data warehouse at one
time.
Limiting the number of
elements displayed and cached
at a time
Governing Rules: Default: Result sets category in Project Configuration
396
Governor
Description
See page
Intelligence
Server
Elapsed Time
- Interactive
reports (sec)
The amount of time that an ad-hoc report request can take before it is
canceled. This includes time spent resolving prompts, waiting for autoprompts,
waiting in the job queue, executing SQL, analytical calculation, and preparing
report results.
Limiting the
maximum
report
execution
time
Intelligence
Server
Elapsed Time
- Scheduled
reports (sec)
The amount of time that a scheduled report request can take before it is
canceled. This includes time spent resolving prompts, waiting for autoprompts,
waiting in the job queue, executing SQL, analytical calculation, and preparing
report results.
Limiting the
maximum
report
execution
time
Final Result
Rows Intelligent
Cubes
The maximum number of rows that can be returned to Intelligence Server for
an Intelligent Cube request. This setting is applied by the Query Engine when
retrieving the results from the database. This is the default for all reports in a
project and can be overridden for individual reports by using the VLDB settings.
Limiting the
number of
report result
rows
Final Result
Rows - Data
marts
The maximum number of rows that can be returned to Intelligence Server for a
data mart report request. This setting is applied by the Query Engine when
retrieving the results from the database. This is the default for all reports in a
project and can be overridden for individual reports by using the VLDB settings.
Limiting the
number of
report result
rows
Final Result
Rows - All
The maximum number of rows that can be returned to Intelligence Server for a
standard report request. This setting is applied by the Query Engine when
Limiting the
number of
Project Configuration Editor
© 2015, MicroStrategy Inc.
System Administration Guide
Governor
Description
See page
other reports
retrieving the results from the database. This is the default for all reports in a
project and can be overridden for individual reports by using the VLDB settings.
report result
rows
All
intermediate
result rows
The maximum number of rows that can be in an intermediate result set used
for analytical processing in Intelligence Server. This is the default for all
reports in a project and can be overridden by using the VLDB settings for
individual reports.
Limiting the
number of
intermediate
rows
All element
browsing
result rows
The maximum number of rows that can be retrieved from the data warehouse
for an element request.
Limiting the
number of
element rows
Memory
consumption
during SQL
generation
(MB)
The maximum amount of memory (in megabytes) that Intelligence Server can
use for SQL generation. The default is -1, which indicates no limit.
Limiting a
report's SQL
per pass
Memory
consumption
during data
fetching (MB)
The maximum amount of memory (in megabytes) that Intelligence Server can
use for importing data. The default is 2048 MB (2 GB).
Limiting the
memory used
during data
fetching
Governing Rules: Default: Jobs category in Project Configuration
Governor
Description
See page
Jobs per
user
account
The maximum number of concurrent jobs per user account and
project.
Limiting the number of
jobs per user session
and per user account
Jobs per
user
session
The maximum number of concurrent jobs a user can have during a
session.
Limiting the number of
jobs per user session
and per user account
Executing
jobs per
user
The maximum number of concurrent jobs a single user account can
have executing in the project. If this condition is met, additional jobs
are placed in the queue until executing jobs finish.
Limiting the number of
executing jobs per user
and project
Jobs per
project interactive
The maximum number of concurrent ad-hoc jobs that the project can
process at a time.
Limiting the number of
jobs per project
Jobs per
project scheduled
The maximum number of concurrent scheduled jobs that the project
can process at a time.
Limiting the number of
jobs per project
Governing Rules: Default: User sessions category in Project Configuration
Governor
Description
See page
User sessions per
project
The maximum number of user sessions that are allowed in the
project. When the limit is reached, users other than the
Administrator cannot log in.
Limiting user
sessions per
project
© 2015, MicroStrategy Inc.
Project Configuration Editor
397
System Administration Guide
Governor
Description
See page
Concurrent interactive
project sessions per
user
The maximum number of concurrent sessions per user.
Limiting user
sessions per
project
Governing Rules: Default: Subscriptions category in Project Configuration
Governor
Description
See page
Maximum History List
subscriptions per user
The maximum number of reports or documents to which a user can
be subscribed for delivery to the History List.
Managing
subscriptions
Maximum Cache
Update subscriptions
per user
The maximum number of reports or documents to which a user can
be subscribed for updating caches.
Managing
subscriptions
Maximum email
subscriptions per user
The maximum number of reports or documents to which a user can
be subscribed for delivery to an email address (Distribution Services
only).
Managing
subscriptions
Maximum file
subscriptions per user
The maximum number of reports or documents to which a user can
be subscribed for delivery to a file location (Distribution Services
only).
Managing
subscriptions
Maximum print
subscriptions per user
The maximum number of reports or documents to which a user can
be subscribed for delivery to a printer (Distribution Services only).
Managing
subscriptions
Maximum Mobile
subscriptions per user
The maximum number of reports or documents to which a user can
be subscribed for delivery to a Mobile device (MicroStrategy Mobile
only).
Managing
subscriptions
Governing Rules: Default: Import Data category in Project Configuration
Governor
Description
See page
Maximum
file size (MB)
The maximum size for a file to be imported for use as a
data source. Files larger that this value cannot be opened
during data import.
Defining limits for Intelligent
Cubes created using the Import
Data feature
Maximum
quota per
user (MB)
The maximum size of all data import cubes for each
individual user.
Defining limits for Intelligent
Cubes created using the Import
Data feature
Caching: Result Caches: Storage category in Project Configuration
398
Governor
Description
See page
Datasets Maximum RAM
usage (MBytes)
The maximum amount of memory reserved for the creation and storage of
report and dataset caches. This setting should be configured to at least the
size of the largest cache file, or that report will not be cached.
Configuring
result cache
settings
Project Configuration Editor
© 2015, MicroStrategy Inc.
System Administration Guide
Governor
Description
See page
Datasets Maximum
number of
caches
The maximum number of report and dataset caches that the project can have
at a time.
Managing
result
caches
Formatted
Documents Maximum RAM
usage (MBytes)
The maximum amount of memory reserved for the creation and storage of
document caches. This setting should be configured to be at least the size of
the largest cache file, or that report will not be cached.
Configuring
result cache
settings
Formatted
Documents Maximum
number of
caches
The maximum number of document caches that the project can have at a
time.
Managing
result
caches
RAM swap
multiplier
The amount of memory that is swapped to disk, relative to the size of the
cache being swapped into memory. For example, if the RAM swap multiplier
setting is 2 and the requested cache is 80 Kbytes, 160 Kbytes are swapped
from memory to disk.
RAM swap
multiplier
Caching: Result caches: Maintenance category in Project Configuration
Governor
Description
See page
Never expire caches
Determines whether or not caches automatically
expire.
Never expire
caches
Cache duration (Hours)
The amount of time that a result cache remains
valid.
Cache duration
(Hours)
Do not Apply Automatic Expiration
Logic for reports containing dynamic
dates
Select this check box for report caches with dynamic
dates to expire in the same way as other report
caches.
Cache expiration
and dynamic
dates
Caching: Auxiliary Caches: Objects category in Project Configuration
Governor
Description
See page
Server - Maximum RAM
usage (MBytes)
The amount of memory that Intelligence Server
allocates for object caching.
Summary table of object
caching settings
Client - Maximum RAM
usage (MBytes)
The amount of memory that Developer allocates
for object caching.
Summary table of object
caching settings
Caching: Auxiliary Caches: Elements category in Project Configuration
Governor
Description
See page
Server - Maximum RAM
The amount of memory that Intelligence Server
Summary table of element
© 2015, MicroStrategy Inc.
Project Configuration Editor
399
System Administration Guide
Governor
Description
See page
usage (MBytes)
allocates for element caching.
cache settings
Client - Maximum RAM
usage (MBytes)
The amount of memory that Developer allocates
for object caching.
Summary table of element
cache settings
Caching: Subscription Execution category in Project Configuration
Governor
Description
See page
Re-run history list and
mobile subscriptions
against the warehouse
Causes new subscriptions to create caches or update existing
caches by default when a report or document is executed and
that report/document is subscribed to the History List or a
Mobile device.
Managing
scheduled
administration
tasks
Re-run file, email, print,
or ftp subscriptions
against the warehouse
Causes new subscriptions to create caches or update existing
caches by default when a report or document is executed and
that report/document is subscribed to a file, email, or print
device.
Managing
scheduled
administration
tasks
Do not create or update
matching caches
Prevents subscriptions from creating or updating caches by
default.
Managing
scheduled
administration
tasks
Keep document available
for manipulation for
History List subscriptions
only
Retains a document or report for later manipulation that was
delivered to the History List.
Managing
scheduled
administration
tasks
Intelligent Cubes: General category in Project Configuration
Governor
Description
See page
Maximum RAM
Usage (MBytes)
The maximum amount of memory used on Intelligence
Server by Intelligent Cubes for this project.
Defining memory limits
for Intelligent Cubes
Maximum number
of cubes
The maximum number of Intelligent Cubes that can be
loaded onto Intelligence Server for this project.
Defining memory limits
for Intelligent Cubes
Database connection
This set of governors can be set by modifying a project source’s database
instance and then modifying either the number of Job Prioritization
connections or the Database connection. For more details on each governor,
see the page references in the table below.
400
Database connection
© 2015, MicroStrategy Inc.
System Administration Guide
ODBC Settings
Governor
Description
See page
Number of
database
connection
threads
The total number of High, Medium, and Low database connections that are
allowed at a time between Intelligence Server and the data warehouse (set
on the database instance’s Job Prioritization tab).
Managing
database
connection
threads
Maximum
cancel attempt
time (sec)
The maximum amount of time that the Query Engine waits for a successful
attempt to cancel a query.
Maximum
cancel attempt
time
Maximum
query
execution time
(sec)
The maximum amount of time that a single pass of SQL may execute on the
data warehouse.
Maximum
query
execution time
Maximum
connection
attempt time
(sec)
The maximum amount of time that Intelligence Server waits to connect to
the data warehouse.
Maximum
connection
attempt time
Database Connection Caching
Governor
Description
See page
Connection
lifetime (sec)
The amount of time that an active database connection thread remains
open and cached on Intelligence Server.
Connection
lifetime
Connection idle
timeout (sec)
The amount of time that an inactive database connection thread
remains cached until it is terminated.
Connection idle
timeout
VLDB settings
These settings can be changed in the VLDB Properties dialog box for either
reports or the database instance. For information about accessing these
properties, see the page reference for each property in the table below. For
complete details about all VLDB properties, see the VLDB Properties chapter
in the Supplemental Reference for System Administration.
Governor
Description
See page
Intermediate
row limit
The maximum number of rows that can be in an intermediate table
used by Intelligence Server. This setting overrides the project’s default
Number of intermediate result rows setting
Limiting the number
of intermediate rows
Results Set
Row Limit
The maximum number of rows that can be in a report result set. This
setting overrides the project’s default Number of report result rows
set.
Limiting the number
of report result rows
SQL time out
(per pass)
The amount of time, in seconds, that any SQL pass can execute on the
data warehouse. This can be set at the database instance and report
SQL Time Out (Per
Pass) (database
© 2015, MicroStrategy Inc.
VLDB settings
401
System Administration Guide
Governor
Maximum
SQL size
Description
See page
levels.
instance and report)
The maximum size (in bytes) that the SQL statement can be. This can
be set at the database instance level.
Maximum SQL Size
(database instance)
Tuning Narrowcast Server and Intelligence
Server
If you are using Narrowcast Server as part of your system to deliver reports to
users, you should be aware of its impact on Intelligence Server system
resources. This section includes relevant discussions about:
•
How you design Narrowcast Server applications (Application design
considerations, page 402)
•
How Narrowcast Server connects to Intelligence Server (How Narrowcast
Server connects to Intelligence Server, page 403)
For more information, refer to the Narrowcast Server System Administrator
Guide.
Application design considerations
Depending on how you design applications in Narrowcast Server you can place
more or less load on Intelligence Server. Two main options to consider are
personal report execution and personal page execution.
Personal report execution (PRE) executes a separate report for each set of
users with unique personalization. Users can have reports executed under the
context of the corresponding Intelligence Server user if desired. Using this
option, security profiles defined in Developer are maintained. However if the
system contains many users who all have unique personalization, this option
can place a large load on Intelligence Server.
Personal page execution (PPE) executes one multi-page report for all users in
a segment and then uses this single report to provide personalized content
(pages) for different users. All users have their reports executed under the
context of the same Intelligence Server user, so individual security profiles are
not maintained. However, the load on Intelligence Server may be significantly
lower than for PRE in some cases.
402
Application design considerations
© 2015 , MicroStrategy Inc.
System Administration Guide
For more detailed information about these options, refer to the Narrowcast
Server Application Designer Guide, specifically the chapter on Page
Personalization and Dynamic Subscriptions.
Two additional points to consider in designing your Narrowcast Server
applications are:
•
Timing of Narrowcast Server jobs: You can schedule reports to run at offpeak hours when Intelligence Server’s load from MicroStrategy Web
products and Developer users is lowest.
•
Intelligence Server selection: You can send Narrowcast Server jobs to a
specific Intelligence Server to ensure that some Intelligence Servers are
used solely for MicroStrategy Web products or Developer.
How Narrowcast Server connects to Intelligence Server
Narrowcast Server can connect to a specific Intelligence Server. Narrowcast
Server does this by using one or more information sources to point to and
connect to the desired Intelligence Servers. Note the following points:
•
Intelligence Server provides automatic load balancing for Narrowcast
Server requests. Once an information source is configured, jobs using that
information source go to the appropriate Intelligence Server for the most
efficient response.
•
Narrowcast Server can connect to any Intelligence Server in a cluster—this
does not need to be the primary node.
•
You can balance the load manually by creating multiple information
sources or by using a single information source pointing to one Intelligence
Server, thereby designating it to handle all Narrowcast Server requests.
© 2015, MicroStrategy Inc.
How Narrowcast Server connects to Intelligence Server
403
System Administration Guide
404
How Narrowcast Server connects to Intelligence Server
© 2015, MicroStrategy Inc.
9
CLUSTERING MULTIPLE
MICROSTRATEGY SERVERS
Introduction
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. Intelligence Server provides
you the functionality to cluster a group of Intelligence Server machines to take
advantage of the many benefits available in a clustered environment.
This section provides the following information:
•
Overview of clustering, page 406
•
The clustered architecture, page 408
•
Prerequisites for clustering Intelligence Servers, page 414
•
Clustering Intelligence Servers, page 417
•
Managing your clustered system, page 427
•
Connecting MicroStrategy Web to a cluster, page 435
© 2015, MicroStrategy Inc.
405
System Administration Guide
Overview of clustering
A cluster is a group of two or more servers connected to each other in such a
way that they behave like a single server. Each machine in the cluster is called
a node. Because each machine in the cluster runs the same services as other
machines in the cluster, any machine can stand in for any other machine in the
cluster. This becomes important when one machine goes down or must be
taken out of service for a time. The remaining machines in the cluster can
seamlessly take over the work of the downed machine, providing users with
uninterrupted access to services and data.
You can cluster MicroStrategy components at two levels:
•
You can cluster Intelligence Servers using the built-in Clustering feature. A
Clustering license allows you to cluster up to four Intelligence Server
machines. For instructions on how to cluster Intelligence Servers, see
Clustering Intelligence Servers, page 417.
•
You can cluster MicroStrategy Web servers using third-party clustering
software, such as Cisco Local Router, Microsoft Windows Load Balancing
Service, or Microsoft Network Load Balancing. Most clustering tools work
by using IP distribution based on the incoming IP addresses. For details on
implementing this clustering method, see the documentation for your
third-party clustering software.
The built-in clustering feature allows you to connect MicroStrategy
* Web to a cluster of Intelligence Servers. For instructions, see
Connecting MicroStrategy Web to a cluster, page 435.
Benefits of clustering
Clustering Intelligence Servers provides the following benefits:
406
•
Increased resource availability: If one Intelligence Server in a cluster fails,
the other Intelligence Servers in the cluster can pick up the workload. This
prevents the loss of valuable time and information if a server fails.
•
Strategic resource usage: You can distribute projects across nodes in
whatever configuration you prefer. This reduces overhead because not all
machines need to be running all projects, and allows you to use your
resources flexibly.
•
Increased performance: Multiple machines provide greater processing
power.
•
Greater scalability: As your user base grows and report complexity
increases, your resources can grow.
Benefits of clustering
© 2015, MicroStrategy Inc.
System Administration Guide
•
Simplified management: Clustering simplifies the management of large or
rapidly growing systems.
Clustering enables you to implement the following strategies in your business
intelligence environment, all of which are discussed in this chapter:
•
Failover support (see Failover support, page 407)
•
Load balancing (see Load balancing, page 407)
•
Project distribution and project failover (see Project distribution and
project failover, page 407)
Failover support
Failover support ensures that a business intelligence system remains available
for use if an application or hardware failure occurs. Clustering provides
failover support in two ways:
•
Load redistribution: When a node fails, the work for which it is responsible
is directed to another node or set of nodes.
•
Request recovery: When a node fails, the system attempts to reconnect
MicroStrategy Web or Web Universal users with queued or processing
requests to another node. Users must log in again to be authenticated on
the new node. The user is prompted to resubmit job requests.
Load balancing
Load balancing is a strategy aimed at achieving even distribution of user
sessions across Intelligence Servers, so that no single machine is overwhelmed.
This strategy is especially valuable when it is difficult to predict the number of
requests a server will receive. MicroStrategy achieves four-tier load balancing
by incorporating load balancers into the MicroStrategy Web and Web
Universal products.
Load is calculated as the number of user sessions connected to a node. The
load balancers collect information on the number of user sessions each node is
carrying. Using this information at the time a user logs in to a project,
MicroStrategy Web or Web Universal connects them to the Intelligence Server
node that is carrying the lightest session load. All requests by that user are
routed to the node to which they are connected until the user disconnects from
the MicroStrategy Web product.
Project distribution and project failover
When you set up several server machines in a cluster, you can distribute
projects across those clustered machines or nodes in any configuration, in both
Windows and UNIX/Linux environments. All servers in a cluster do not need
to be running all projects. Each node in the cluster can host a different set of
© 2015, MicroStrategy Inc.
Benefits of clustering
407
System Administration Guide
projects, which means only a subset of projects need to be loaded on a specific
Intelligence Server machine. This feature provides you with flexibility in using
your resources, and it provides better scalability and performance because of
less overhead on each Intelligence Server machine.
Distributing projects across nodes also provides project failover support. For
example, one server is hosting project A and another server is hosting projects
B and C. If the first server fails, the other server can host all three projects to
ensure project availability.
Project creation, duplication, and deletion in a three-tier, or server, connection
are automatically broadcast to all nodes during runtime to ensure
synchronization across the cluster.
The clustered architecture
The diagram below shows report distribution in a four-tier clustered
environment. The clustered Intelligence Servers are shown in gray.
The node of the cluster that performs all job executions is the node that the
client application, such as Developer, connects to. This is also the node that
can be monitored by an administrator using the monitoring tools.
408
Benefits of clustering
© 2015, MicroStrategy Inc.
System Administration Guide
The following steps describe a typical job process in a clustered, four-tier
environment. They correspond to the numbers in the report distribution flow
diagram above.
1
MicroStrategy Web or Web Universal users log in to a project and request
reports from their Web browsers.
2
A third-party IP distribution tool such as Cisco Local Router, Microsoft
Network Load Balancing, or Microsoft Windows Load Balancing Service
distributes the user connections from the MicroStrategy Web clients
among web servers.
3
The MicroStrategy Web product load balancers on each server collect load
information from each cluster node and then connect the users to the
nodes that carry the lightest loads and that run the project the user
requested. All report requests are then processed by the nodes to which
the users are connected.
4
The Intelligence Server nodes receive the requests and process them. In
addition, the nodes communicate with each other to maintain metadata
synchronization and cache accessibility across nodes.
5
The nodes send the requests to the warehouse as queries.
Query flow in a clustered environment is identical to a standard query flow in
an unclustered environment (see Processing jobs, page 35), with two
exceptions:
•
Result (report and document) caches and Intelligent Cubes: When a query
is submitted by a user, if an Intelligent Cube or a cached report or
document is not available locally, the server will retrieve the cache (if it
exists) from another node in the cluster. For an introduction to report and
document caching, see Result caches, page 438. For an introduction to
Intelligent Cubes, see Chapter 11, Managing Intelligent Cubes.
•
History Lists: Each user’s History List, which is held in memory by each
node in the cluster, contains direct references to the relevant cache files.
Accessing a report through the History List bypasses many of the report
execution steps, for greater efficiency. For an introduction to History Lists,
see Saving report results: History List, page 466.
Synchronizing cached information across nodes in a
cluster
In a clustered environment, each node shares cached information with the
other nodes so that the information users see is consistent regardless of the
node to which they are connected when running reports. All nodes in the
cluster synchronize the following cached information:
© 2015, MicroStrategy Inc.
Synchronizing cached information across nodes in a cluster
409
System Administration Guide
•
Metadata information and object caches (for details, see Synchronizing
metadata, page 410)
•
Result caches and Intelligent Cubes (for details, see Sharing result caches
and Intelligent Cubes in a cluster, page 410)
•
History Lists (for details, see Synchronizing History Lists, page 413)
To view clustered cache information, such as cache hit counts, use the Cache
Monitor.
Result cache settings are configured per project, and different projects may use
different methods of result cache storage. Different projects may also use
different locations for their cache repositories. However, History List settings
are configured per project source. Therefore, different projects cannot use
different locations for their History List backups.
For result caches and History Lists, you must configure either multiple local
caches or a centralized cache for your cluster. The following sections describe
the caches that are affected by clustering, and it presents the procedures to
configure caches across cluster nodes.
Synchronizing metadata
Metadata synchronization refers to the process of synchronizing object caches
across all nodes in the cluster.
For example, when a user connected to a node in a cluster modifies a metadata
object, the cache for that object on other nodes is no longer valid. The node
that processed the change automatically notifies all other nodes in the cluster
that the object has changed. The other nodes then delete the old object cache
from memory. The next request for that object that is processed by another
node in the cluster is executed against the metadata, creating a new object
cache on that node.
In addition to server object caches, client object caches are also invalidated
* when a change occurs. When a user requests a changed object, the invalid
client cache is not used and the request is processed against the server
object cache. If the server object cache has not been refreshed with the
changed object, the request is executed against the metadata.
Sharing result caches and Intelligent Cubes in a cluster
In a non-clustered environment, Intelligent Cubes and report and document
caches (result caches) are typically stored on the Intelligence Server machine.
For an overview of Intelligent Cubes, see Chapter 11, Managing Intelligent
Cubes, or see the MicroStrategy In-memory Analytics Guide. For an overview
of result caches, see Result caches, page 438.
410
Synchronizing cached information across nodes in a cluster
© 2015, MicroStrategy Inc.
System Administration Guide
In a clustered environment, each node in a cluster must share its result caches
and Intelligent Cubes with the other nodes, so all clustered machines have the
latest cache information. For example, for a project, result caches on each node
that has loaded the project are shared among other nodes in the cluster that
have also loaded the project. Configuring caches to be shared among
appropriate nodes eliminates the overhead associated with executing the same
report or document on multiple nodes.
Note the following:
*•
•
Both memory and disk caches are shared among nodes.
When an Intelligent Cube is updated, either through Incremental
Refresh or by republishing the Intelligent Cube, the updated Intelligent
Cube is available on all nodes of the cluster as soon as it is loaded into
memory.
Intelligent Cube and result cache sharing among nodes can be configured in
one of the following ways:
•
Local caching: Each node hosts its own cache file directory and Intelligent
Cube directory. These directories need to be shared so that other nodes can
access them. For more information, see Local caching, page 412.
*
•
If you are using local caching, the cache directory must be shared as
“ClusterCaches” and the Intelligent Cube directory must be shared as
“ClusterCube”. These are the share names Intelligence Server looks for
on other nodes to retrieve caches and Intelligent Cubes.
Centralized caching: All nodes have the cache file directory and Intelligent
Cube directory set to the same network locations, \\<machine
name>\<shared cache folder name> and \\<machine
name>\<shared Intelligent Cube folder name>. For more
information, see Centralized caching, page 413.
For caches on Windows machines, and on UNIX/Linux machines using
name>\<shared cache
folder name>. For caches on UNIX/Linux machines, set the path to
//<SharedLocation>/<CacheFolder>.
* Samba, set the path to \\<machine
The following table summarizes the pros and cons of the result cache
configurations:
Local
caching
Pros
Cons
•
•
© 2015, MicroStrategy Inc.
Allows faster read and write operations
for cache files created by the local
server.
The local cache files may be temporarily
unavailable if an Intelligence Server is taken
off the network or powered down.
Synchronizing cached information across nodes in a cluster
411
System Administration Guide
Centralized
caching
Pros
Cons
•
Faster backup of cache lookup table.
•
•
Allows most caches to remain accessible
even if one node in a cluster goes
offline.
A document cache on one node may depend
on a dataset that is cached on another node,
creating a multi-node cluster dependency.
•
Allows for easier backup process.
•
•
Allows all cache files to be accessible
even if one node in a cluster goes
offline.
All cache operations are required to go over
the network if shared location is not on one of
the Intelligence Server machines.
•
Requires additional hardware if shared
location is not on an Intelligence Server.
•
All caches become inaccessible if the machine
hosting the centralized caches goes offline.
•
May better suit some security plans
because nodes using a network account
are accessing only one machine for files.
MicroStrategy recommends storing the result caches locally if your users
mostly do ad hoc reporting. In ad hoc reporting the caches are not used very
much, and the overhead incurred by creating the caches on a remote file server
outweighs the low probability that a cache may be used. On the other hand, if
the caches are to be heavily used, centralized caching may suit your system
better.
For steps to configure cache files with either method, see Configuring caches
in a cluster, page 417.
Local caching
In this cache configuration, each node maintains its own local Intelligent Cubes
and local cache file and, thus, maintains its own cache index file. Each node’s
caches are accessible by other nodes in the cluster through the cache index file.
This is illustrated in the diagram below.
For example, User A, who is connected to node 1, executes a report and thus
creates report cache A on node 1. User B, who is connected to node 2, executes
the report. Node 2 checks its own cache index file first. When it does not
locate report cache A in its own cache index file, it checks the index file of
other nodes in the cluster. Locating report cache A on node 1, it uses that
412
Synchronizing cached information across nodes in a cluster
© 2015, MicroStrategy Inc.
System Administration Guide
cache to service the request, rather than executing the report against the
warehouse.
Centralized caching
In this cache configuration, all nodes in the cluster use one shared, centralized
location for Intelligent Cubes and one shared, centralized cache file location.
These can be stored on one of the Intelligence Server machines or on a
separate machine dedicated to serving the caches. The Intelligent Cubes,
History List messages, and result caches for all the Intelligence Server
machines in the cluster are written to the same location. In this option, only
one cache index file is maintained. This is illustrated in the diagram below.
For example, User A, who is connected to node 1, executes report A and thus
creates report cache A, which is stored in a centralized file folder. User B, who
is connected to node 2, executes report A. Node 2 checks the centralized cache
index file for report cache A. Locating report cache A in the centralized file
folder, it uses that cache to service the request, regardless of the fact that node
1 originally created the cache.
Synchronizing History Lists
A History List is a set of pointers to cache files. Each user has his or her own
History List, and each node in a cluster stores the pointers created for each
user who is connected to that node. Each node’s History List is synchronized
with the rest of the cluster. Even if report caching is disabled, History List
functionality is not affected.
If you are using a database-based History List, History List messages and their
associated caches are stored in the database and automatically synchronized
across all nodes in the cluster.
If you are using a file-based History List, the Intelligence Server Inbox folder
contains the collection of History List messages for all users, which appear in
the History folder in Developer. Inbox synchronization refers to the process of
synchronizing History Lists across all nodes in the cluster, so that all nodes
© 2015, MicroStrategy Inc.
Synchronizing cached information across nodes in a cluster
413
System Administration Guide
contain the same History List messages. Inbox synchronization enables users
to view the same set of personal History List messages, regardless of the
cluster node to which they are connected.
For more background information on History Lists, see Saving report results:
History List, page 466. For steps to set up History List sharing in a file-based
system, see Configuring History List sharing using multiple local cache files,
page 420.
MicroStrategy recommends that you enable user affinity clustering to
minimize History List resource usage. User affinity clustering causes
Intelligence Server to connect all sessions for a user to the same node of the
cluster. This enables Intelligence Server to keep the user’s History List on one
node of the cluster. Resource use is minimized because the pointers to the
History List are not stored on multiple machines. In addition, if you are using
a file-based History List, the History List is never out of sync across multiple
nodes of the cluster. For instructions on how to enable user affinity clustering,
see Configuring History Lists in a clustered environment, page 423.
Prerequisites for clustering Intelligence Servers
Before you can cluster Intelligence Servers in your system, you must fulfil
these prerequisites.
MicroStrategy prerequisites
414
•
You must have purchased an Intelligence Server license that allows
clustering. To determine the license information, use the License Manager
tool and verify that the Clustering feature is available for Intelligence
Server. For more information on using License Manager, see Chapter 5,
Managing Your Licenses.
•
The computers to be clustered must all have the same version of
Intelligence Server installed.
•
All MicroStrategy projects on the clustered machines must be based on the
same metadata.
•
At least one project must be defined in the metadata.
•
No more than one Intelligence Server can be configured for a single
machine. Multiple instances of Intelligence Server should not run on the
same machine for clustering purposes.
•
The user account under which the Intelligence Server service is running
must have full control of cache and History List folders on all nodes.
MicroStrategy prerequisites
© 2015, MicroStrategy Inc.
System Administration Guide
Otherwise, Intelligence Server will not be able to create and access cache
and History List files.
•
Server definitions store Intelligence Server configuration information.
MicroStrategy strongly recommends that all servers in the cluster use the
same server definition. This ensures that all nodes have the same governing
settings.
Server definitions can be modified from Developer through the Intelligence
Server Configuration Editor and the Project Configuration Editor. For
instructions, see the MicroStrategy Developer Help.
•
Developer must be installed on a Windows machine to administer the
cluster. This version of Developer must be the same as the version of
Intelligence Servers. For example, if the Intelligence Servers are running
MicroStrategy Analytics Enterprise, Developer must also be Analytics
Enterprise.
•
You must have access to the Cluster view of the System Administration
monitor in Developer. Therefore, you must have the Administration
privilege to create a cluster. For details about the Cluster view of the
System Administration monitor, see Managing your clustered system,
page 427.
•
The computers that will be clustered must have the same intra-cluster
communication settings. To configure these settings, on each Intelligence
Server machine, in Developer, right-click the project source and select
Configure MicroStrategy Intelligence Server. The Intelligence Server
Configuration Editor opens. Under the Server definition category, select
General. For instructions, see the MicroStrategy Developer Help.
•
The same caching method (localized or centralized caching) should be used
for both result caches and file-based History Lists. For information about
localized and centralized caching, see Sharing result caches and Intelligent
Cubes in a cluster, page 410.
Server prerequisites
•
The machines to be clustered must be running the same version of the
same operating system. For example, you cannot cluster two machines
when one is running on Windows 2008 and one is running on Windows
2003.
•
Load balancing and system configuration are simpler if identical hardware
is used for each of the clustered nodes.
•
If you are using time-based schedules in a clustered environment, all the
nodes in the cluster must have their clocks synchronized.
•
The RDBMS containing the metadata and warehouse instances must
already be set up on machines separate from the Intelligence Server nodes.
© 2015, MicroStrategy Inc.
Server prerequisites
415
System Administration Guide
•
Information on the clustered configuration is stored in the metadata, so the
machines to be clustered must use the same metadata repository. The
metadata may be created from any of the nodes, and it needs to be set up
only once. When you create or modify the server definition in the
MicroStrategy Configuration Wizard, you can specify either a new or an
existing metadata repository for Intelligence Server to use.
•
The required data source names (DSNs) must be created and configured for
Intelligence Server on each machine. MicroStrategy strongly recommends
that you configure both servers to use the same metadata database,
warehouse, port number, and server definition.
•
All nodes must join the cluster before you make any changes to any
governing settings, such as in the Intelligence Server Configuration Editor.
Prerequisites for Windows clustering
•
On all machines to be clustered, each network card must be configured to
enable Netbios over TCP/IP. Otherwise, cache sharing is not possible using
Netbios names (ClusterCaches, ClusterCube, and ClusterInbox).
•
When Intelligence Server is installed, the last step is to choose a user
identity under which the service will run. To run a clustered configuration,
the user must be a domain account that has a trust relationship with each
of the computers in the cluster. This allows resources to be shared across
the network.
•
The service user’s Regional Options settings must be the same as the
clustered system’s Regional Options settings.
Prerequisites for UNIX/Linux clustering
•
MicroStrategy strongly recommends that all servers in a cluster use the
same server definition. Therefore, in some cases you cannot specify the
cache location with an absolute path such as /<machine_name>. This
occurs because the location would have to be different for each server
machine. To solve this problem, use relative paths and soft links. A soft
link is a special type of UNIX file that refers to another file by its path
name. A soft link is created with the ln (link) command:
ln -s OLDNAME NEWNAME
where
OLDNAME is the target of the link, usually a path name.
NEWNAME is the path name of the link itself.
416
Prerequisites for Windows clustering
© 2015, MicroStrategy Inc.
System Administration Guide
Most operations (open, read, write) on the soft link automatically dereference it and operate on its target (OLDNAME). Some operations (for
example, removing) work on the link itself (NEWNAME).
•
Confirm that each server machine works properly, and then shut each
down.
Clustering Intelligence Servers
Below is a high-level overview of the steps to cluster Intelligence Servers:
1
Confirm that you have fulfilled the prerequisites for clustering Intelligence
Servers.
For a list of these prerequisites, see Prerequisites for clustering
Intelligence Servers, page 414.
2
Configure the caches to synchronize information across nodes.
Before Intelligence Servers can be clustered, the information such as report
caches and History Lists must be synchronized among them. For steps, see
Configuring caches in a cluster, page 417.
3
Join nodes.
You create a cluster by joining Intelligence Servers that have been
synchronized. For steps, see Joining the nodes in a cluster, page 424.
4
Test the clustered system.
Once the cluster has been created, you should test it to make sure that the
caches and metadata are being shared properly among nodes. For steps on
performing various tests, see Verifying the clustered system is working,
page 424.
5
(Optional) Distribute projects across nodes.
Once the cluster has been created, you may wish to distribute your projects
across the cluster to improve performance. For more information and
steps, see Distributing projects across nodes in a cluster, page 425.
Configuring caches in a cluster
You can configure caches in one of two ways:
© 2015, MicroStrategy Inc.
Configuring caches in a cluster
417
System Administration Guide
•
Local caching: Each node hosts its own cache file directory and Intelligent
Cube directory. These directories need to be shared so that other nodes can
access them. For more information, see Local caching, page 412.
•
Centralized caching: All nodes have the cache file directory and Intelligent
Cube directory set to the same network locations. For more information,
see Centralized caching, page 413.
For steps to configure caches in either way, follow the instructions below
depending on your operating system:
•
Configuring caches in a cluster on Windows, page 418
•
Configuring caches in a cluster on UNIX/Linux, page 420
Configuring caches in a cluster on Windows
Use one of the procedures below to share cache files among the nodes in your
cluster. MicroStrategy strongly recommends that each node in your cluster use
the same server definition. In this case, you need to configure the cache
location in Intelligence Server only one time. However, you must create the
shared folders on each node separately. For a detailed explanation of the two
methods of cache sharing, see Sharing result caches and Intelligent Cubes in a
cluster, page 410.
To configure cache sharing using multiple local cache files
1
Open the Project Configuration Editor for the project.
2
Select Caching, then Result Caches, then Storage.
3
In the Cache file directory box, type:
.\Caches\ServerDefinition
where ServerDefinition is the name of the server definition.
This tells the other clustered nodes to search for caches in the following
path on all machines in the cluster:
<Intelligence Server Application
Folder>\Caches\ServerDefinition
4
Click OK.
5
On each machine in the cluster, open Windows Explorer and navigate to
the cache file folder. The default location is:
C:\Program Files (x86)\Common
Files\MicroStrategy\Intelligence
Server\Caches\ServerDefinition
418
Configuring caches in a cluster
© 2015, MicroStrategy Inc.
System Administration Guide
where ServerDefinition is the name of the server definition.
6
Right-click the cache file folder, and select Sharing. The [Server Definition]
Properties dialog box opens.
7
On the Sharing tab, select the Shared as option. In the Share Name box,
delete the existing text and type ClusterCaches.
8
Click OK. After you have completed these steps, you can cluster the nodes
using the Cluster Monitor.
To configure cache sharing using a centralized cache file
1
Open the Project Configuration Editor for the project.
2
Select Caching, then Result Caches, then Storage.
3
In the Cache file directory box, type one of the following:
\\<Machine Name>\<Shared Folder Name>
or
\\<IP Address>\<Shared Folder Name>
© 2015, MicroStrategy Inc.
Configuring caches in a cluster
419
System Administration Guide
For example, \\My_File_Server\My_Cache_Directory.
4
Click OK.
5
On the machine that is storing the centralized cache, create the file folder
that will be used as the shared folder. The file folder name must be
identical to the name you earlier specified in the Cache file directory box
(shown as Shared Folder Name above).
Make sure this cache directory is writable to the network account
* under which Intelligence Server is running. Each Intelligence Server
creates its own subdirectory.
Configuring History List sharing using multiple local cache files
If you are using a file-based History List, you can set up History Lists to use
multiple local disk backups on each node in the cluster, using a procedure
similar to the procedure above, To configure cache sharing using multiple
local cache files, page 418. The History List messages are stored in the
History folder. (To locate this folder, in the Intelligence Server Configuration
Editor, expand Governing Rules, expand Default, then select History settings.)
The History List location is .\Inbox\ServerDefinition, where Server
Definition is the name of the folder containing the History Lists. This
folder must be shared with the share name “ClusterInbox” because this is the
share name used by Intelligence Server to look for History Lists on other
nodes.
Configuring caches in a cluster on UNIX/Linux
To configure a cluster of Intelligence Servers in a UNIX/Linux environment, all
servers must have access to each others’ caches and inbox (History List) files.
Both cache and History List files are referred to generally as cache files
throughout this section. An Intelligence Server looks for cache files from other
nodes in the cluster by machine name. For an explanation and diagrams of
general cache synchronization setup, see Synchronizing cached information
across nodes in a cluster, page 409.
The cache and Inbox folders must be named as follows:
/<machine_name>/ClusterCaches
/<machine_name>/ClusterInbox
For example, a two-node cluster with Intelligence Servers is running on
machines UNIX1 and UNIX2. Intelligence Server running on UNIX1 looks for
caches of the other Intelligence Server only on /UNIX2/ClusterCaches.
420
Configuring caches in a cluster
© 2015, MicroStrategy Inc.
System Administration Guide
The procedures below demonstrate how to configure the caches on two
servers, named UNIX1 and UNIX2. Use these steps as a guideline for
configuring your own system.
You can choose to use either procedure below, depending on whether you want
to use centralized or local caching. For a detailed description and diagrams of
cache synchronization setup, see Synchronizing cached information across
nodes in a cluster, page 409.
To configure a cluster with a centralized cache
This procedure assumes that the UNIX/Linux machines are called UNIX1
* and UNIX2.
To configure the server definition and project
1
Start Intelligence Server on UNIX1.
2
In Developer, create project sources pointing to UNIX1 and UNIX2.
3
Connect to UNIX1 using Developer.
4
Right-click the project source of UNIX1 and select Configure Server.
5
Select the Server Definition category, and select History Settings.
6
Set the path using the following convention:
//<SharedLocation>/<InboxFolder>
In this example, set it as //sandbox/Inbox.
7
Right-click the project name and select Project Configuration.
8
Select Caching, then Result Caches, then Storage.
9
Following the convention //<SharedLocation>/<CacheFolder>, set
the path to //sandbox/Caches.
For caches stored on UNIX/Linux machines using Samba, set the path
name>\<shared folder name>.
* to \\<machine
10 Disconnect from the project source and shut down Intelligence Server.
To create the cache folder on the shared device
11 Create the folders for caches on the shared device (as described in
Prerequisites for UNIX/Linux clustering above):
mkdir /sandbox/Caches
© 2015, MicroStrategy Inc.
Configuring caches in a cluster
421
System Administration Guide
mkdir /sandbox/Inbox
12 Restart both Intelligence Servers.
To configure a cluster with multiple local cache files
This procedure makes the following assumptions:
*•
The UNIX/Linux machines are called UNIX1 and UNIX2.
•
Intelligence Server is installed in MSTR_<HOME_PATH> on each
machine.
•
The MSTR_HOME_PATH for each machine is /Build/BIN/SunOS/.
To configure the server definition and project
1
Start Intelligence Server on UNIX 1.
2
In Developer, create project sources pointing to UNIX1 and UNIX2.
3
Connect to UNIX1 using Developer.
4
Right-click the project source of UNIX1 and select Configure Server.
5
Select the Server Definition category, and select History Settings.
6
Set the path to ./ClusterInbox and click OK.
7
Right-click the project name and select Project Configuration.
8
Select Caching, then Result Caches, then Storage.
9
Set the path for the cache file directory to ./ClusterCaches.
10 Disconnect from the project source and shut down Intelligence Server.
To set up the UNIX1 machine
11 Create the folders for caches:
mkdir $MSTR_<HOME_PATH>/ClusterCaches
mkdir $MSTR_<HOME_PATH>/ClusterInbox
12 Mount the folders from UNIX2 on UNIX1. For example:
mkdir /UNIX2
mount UNIX2:/Build/BIN/SunOD /UNIX2
422
Configuring caches in a cluster
© 2015, MicroStrategy Inc.
System Administration Guide
To set up the UNIX2 machine
13 Create the folders for caches:
mkdir $MSTR_HOME_PATH/ClusterCaches
mkdir $MSTR_HOME_PATH/ClusterInbox
14 Mount the folders from UNIX2 on UNIX1. For example:
mkdir /UNIX1
mount UNIX1:/Build/BIN/SunOD /UNIX1
15 Restart both Intelligence Servers.
Configuring History Lists in a clustered environment
MicroStrategy recommends that you enable user affinity clustering to reduce
History List resource usage. User affinity clustering causes Intelligence Server
to connect all sessions for a user to the same node of the cluster. For
background information about user affinity clustering, see Synchronizing
History Lists, page 413.
If you are not using user affinity clustering, MicroStrategy recommends that
you set the cache backup frequency to 0 (zero) to ensure that History List
messages are synchronized correctly between nodes. For more information
about this setting, see Backup Frequency (minutes), page 456.
To configure the History List governing settings for a clustered
environment
1
In Developer, log into a project source. You must log in as a user that has
administrative privileges.
2
From the Administration menu, point to Server and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the Server Definition category, and then select Advanced.
4
Do one of the following:
5
•
To enable user affinity clustering, select the User Affinity Cluster check
box.
•
OR, if you do not want to enable user affinity clustering, in the Backup
frequency (minutes) field, type 0 (zero).
Click OK to accept your changes and close the Intelligence Server
Configuration Editor.
© 2015, MicroStrategy Inc.
Configuring caches in a cluster
423
System Administration Guide
6
Restart Intelligence Server.
Joining the nodes in a cluster
You join one node (or machine) to another node to form a cluster using the
Cluster Monitor.
To join a node to a cluster
1
In Developer, log in to a project source. You must log in as a user with the
Administer Cluster privilege.
2
Expand Administration, then expand System Administration, and then select
Cluster. Information about each node in the cluster information displays on
the right-hand side.
3
From the Administration menu, point to Server, then select Join cluster.
The Cluster Manager dialog box opens.
4
Type the name of the machine running Intelligence Server to which you are
adding this node, or click ... to browse for and select it.
5
Once you have specified or selected the server to join, click OK.
Verifying the clustered system is working
Once all nodes have been synchronized and added to the cluster, you can verify
that the cluster is working properly.
To verify from Developer
Verify the Cluster view
1
Connect to one Intelligence Server in the cluster and ensure that the
Cluster view in Developer (under Administration, under System
Administration) is showing all the proper nodes as members of the cluster.
Verify the cache
424
2
Connect to any node and run a large report.
3
Use the Cache Manager and view the report details to make sure the cache
is created.
Joining the nodes in a cluster
© 2015, MicroStrategy Inc.
System Administration Guide
Connect to a different node and run the same report. Verify that the report
used the cache created by the first node.
4
Verify the History List
5
Connect to any node and run a report.
6
Add the report to the History List.
7
Without logging out that user, log on to a different node with the same
user name.
8
Verify that the History List contains the report added in the first node.
To verify from MicroStrategy Web
1
Open the MicroStrategy Web Administrator page.
2
Connect to any node in the cluster. MicroStrategy Web Universal should
automatically recognize all nodes in the cluster and show them as
connected.
If MicroStrategy Web does not recognize all nodes in the cluster, it is
~ possible that the machine itself cannot resolve the name of that node.
MicroStrategy cluster implementation uses the names of the machines
for internal communication. Therefore, the Web machine should be
able to resolve names to IP addresses. You can edit the lmhost file to
relate IP addresses to machine names.
You can also perform the same cache and History List tests described above in
To verify from Developer.
Distributing projects across nodes in a cluster
You can distribute projects across nodes of a cluster in any clustered
configuration. Each node can host a different set of projects, which means only
a subset of projects needs to be loaded on an Intelligence Server. This provides
you with flexibility in using your resources and better scalability and
performance.
To distribute projects across the cluster, you manually assign the projects to
specific nodes in the cluster. Once a project has been assigned to a node, it is
available for use.
*
If you do not assign a project to a node, the project remains unloaded and
users cannot use it. You must then manually load the project for it to be
© 2015, MicroStrategy Inc.
Distributing projects across nodes in a cluster
425
System Administration Guide
available. To manually load a project, right-click the project in the Project
Monitor and select Load.
If you are using single instance session logging in Enterprise Manager with
~ clustered Intelligence Servers, the single instance session logging project
must be loaded onto all the clustered Intelligence Servers. Failure to load
this project on all servers at startup results in a loss of session statistics
for any Intelligence Server onto which the project is not loaded at startup.
For more information, see MicroStrategy Tech Note TN14591. For detailed
information about session logging in Enterprise Manager, see the
MicroStrategy Operations Manager Guide.
To distribute projects across nodes in a cluster
1
In Developer, from the Administration menu, point to Projects, then select
Select Projects. Intelligence Server Configuration Editor opens, at the
Projects: General category.
2
One column is displayed for each node in the cluster that is detected at the
time the Intelligence Server Configuration Editor opens. Select the
corresponding check box to configure the system to load a project on a
node. A selected box at the intersection of a project row and a node column
signifies that the project is to be loaded at startup on that node.
•
If no check boxes are selected for a project, the project is not loaded on
any node at startup. Likewise, if no check boxes are selected for a node,
no projects are loaded on that node at startup.
If you are using single instance session logging with Enterprise
~ Manager, the single instance session logging project must be loaded
onto all the clustered Intelligence Servers at startup. Failure to load
this project on all servers at startup results in a loss of session
statistics for any Intelligence Server onto which the project is not
loaded at startup. For steps on implementing single instance session
logging, see the MicroStrategy Operations Manager Guide. For more
information about this issue, see MicroStrategy Tech Note TN14591.
•
All Servers: If this check box is selected for a project, all nodes in the
cluster load this project at startup. All individual node check boxes are
also selected automatically. When you add a new node to the cluster,
any projects set to load on All Servers automatically load on the new
node.
If you select a check mark for a project to be loaded on every node but
* you do not select the All Servers check box, the system loads the project
426
Distributing projects across nodes in a cluster
© 2015 , MicroStrategy Inc.
System Administration Guide
on the selected nodes. When a new node is added to the cluster, this
project is not automatically loaded on that new node.
3
4
Select whether to display only the selected projects and whether to apply
the startup configuration on save:
•
Show selected projects only: Selecting this option allows you to display
only those projects that have been assigned to be loaded on a node. For
display purposes it filters out projects that are not loaded on any node
in the cluster.
•
Apply startup configuration on save: Selecting this option allows your
changes to be reflected immediately across the cluster. If this check box
is cleared, any changes are saved when you click OK, but they do not
take effect until Intelligence Server is restarted.
Click OK when you are finished configuring your projects across the nodes
in the cluster.
If you do not see the projects you want to load displayed in the Intelligence
Server Configuration Editor, you must configure Intelligence Server to use a
server definition that points to the metadata containing the project. Use the
MicroStrategy Configuration Wizard to configure this. For details, see the
MicroStrategy Installation and Configuration Guide.
~
It is possible that not all projects in the metadata are registered and listed
in the server definition when the Intelligence Server Configuration Editor
opens. This can occur if a project is created or duplicated in a two-tier
(direct connection) project source that points to the same metadata as that
being used by Intelligence Server while it is running. Creating, duplicating,
or deleting a project in two-tier while a server is started against the same
metadata is not recommended.
Managing your clustered system
Once your clustered system is up and running, you can monitor and configure
the projects that are running on each node of the cluster.
•
Managing your projects across nodes of a cluster, page 428
•
Project failover and latency, page 430
•
Shutting down a node, page 432
•
Maintaining result caches and History Lists in a clustered environment,
page 433
© 2015, MicroStrategy Inc.
Distributing projects across nodes in a cluster
427
System Administration Guide
Managing your projects across nodes of a cluster
Managing a project across all nodes of a cluster can be done through the
Project view of the System Administration monitor. From this view, you can
unload or idle a project during System Administration on Intelligence Server.
However, sometimes you need to perform maintenance on only one node of
the cluster. In this case, you can use the Cluster view to idle or unload a
project from that node, while leaving the project running on the other nodes of
the cluster.
For detailed information about the effects of the various idle states on a
project, see Setting the status of a project, page 29.
To manage the projects and nodes in a cluster
1
In Developer, log in to a project source. You must log in as a user with the
Administer Cluster privilege.
2
Expand Administration, then expand System Administration, and then select
Cluster. Information about each node in the cluster information displays 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.
You can perform an action on multiple servers or projects at the same
* time. To do this, select several projects (CTRL+click), then right-click and
select one of the options.
To idle or resume a project on a node
1
428
In the Cluster view, right-click the project whose status you want to
change, point to Administer project on node, and select Idle/Resume. The
Idle/Resume dialog box opens.
Managing your projects across nodes of a cluster
© 2015, MicroStrategy Inc.
System Administration Guide
2
Select the options for the idle mode that you want to set the project to:
•
Request Idle (Request Idle): all executing and queued jobs finish
executing, and any newly submitted jobs are rejected.
•
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.
•
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.
•
Full Idle (Request Idle and Execution Idle for All jobs): all executing
and queued jobs are canceled, and any newly submitted jobs are
rejected.
•
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 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.
3
Click OK. The Idle/Resume dialog box closes and the project goes into the
selected mode.
© 2015, MicroStrategy Inc.
Managing your projects across nodes of a cluster
429
System Administration Guide
To load or unload a project from a specific node
In the Cluster view, right-click the project whose status you want to
change, point to Administer project on node, and select Load or Unload. The
project is loaded or unloaded from that node.
Project failover and latency
Project failover support in a cluster is similar to system failover support. For
example, one server in a cluster is hosting project A and another server in the
cluster is running projects B and C. If the first server becomes unavailable, the
other can begin running all three projects. Project failover support ensures
that projects remain available even if hardware or an application fails.
Project failover is triggered when the number of nodes running a project
reaches zero due to node failure. At that point, the system automatically loads
any projects that were on the failed system onto another server in the cluster
to maintain the availability of those projects. Once the failed server recovers,
the system reloads the original project onto the recovered server. It also
removes the project from the server that had temporarily taken over.
Failover and latency take effect only when a server fails. If a server is manually
shut down, its projects are not automatically transferred to another server,
and are not automatically transferred back to that server when it restarts.
You can determine several settings that control the time delay, or latency
period, in the following instances:
•
After a machine fails, but before its projects are loaded onto to a different
machine
•
After the failed machine is recovered, but before its original projects are
reloaded
To set project failover latency
1
In Developer, from the Administration menu, select Server, then select
Configure MicroStrategy Intelligence Server. The Intelligence Server
Configuration Editor opens.
2
Expand the Server Definition category, then select Advanced.
3
Enter the Project Failover Latency and Configuration Recovery Latency, and
click OK.
When deciding on these latency period settings, consider how long it takes an
average project in your environment to load on a machine. If your projects are
430
Project failover and latency
© 2015, MicroStrategy Inc.
System Administration Guide
large, they may take some time to load, which presents a strain on your
system resources. With this consideration in mind, use the following
information to decide on a latency period.
Project failover latency
You can control the time delay (latency) before the project on a failed machine
is loaded on another node to maintain a minimum level of availability.
Latency takes effect only when a server fails. If a server is manually shut
* down, its projects are not automatically transferred to another machine.
Consider the following information when setting a latency period:
•
Setting a higher latency period prevents projects on the failed server from
being loaded onto other servers quickly. This can be a good idea if your
projects are large and you trust that your failed server will recover quickly.
A high latency period provides the failed server more time to come back
online before its projects need to be loaded on another server.
•
Setting a lower latency period causes projects from the failed machine to
be loaded relatively quickly onto another server. This is good if it is crucial
that your projects are available to users at all times.
•
Disabling the latency period or the failover process:
▫
If you enter 0 (zero), there is no latency period and thus there is no
delay; the project failover process begins immediately.
▫
If you enter -1, the failover process is disabled and projects are not
transferred to another node if there is a machine failure.
Configuration recovery latency
When the conditions that caused the project failover disappear, the system
automatically reverts to the original project distribution configuration by
removing the project from the surrogate server and loading the project back
onto the recovered server (the project’s original server).
Consider the following information when setting a latency period:
•
Setting a higher latency period leaves projects on the surrogate server
longer. This is good idea if your projects are large and you want to be sure
your recovered server stays online for a specific period before the project
load process begins. A high latency period provides the recovered server
more time after it comes back online before its projects are reloaded.
•
Setting a lower latency period causes projects on the surrogate machine to
be removed and loaded relatively quickly onto the recovered server. This is
desirable if you want to reduce the strain on the surrogate server as soon
as possible.
© 2015, MicroStrategy Inc.
Project failover and latency
431
System Administration Guide
You can also disable the latency period:
•
If you enter a 0 (zero), there is no latency period and thus there is no
delay. The configuration recovery process begins immediately.
•
If you enter a -1, the configuration recovery process is disabled and
projects are never automatically reloaded onto the recovered server.
Shutting down a node
A node can be shut down in two ways:
•
Administrative shutdown: This includes instances when a node is removed
from a cluster or the Intelligence Server service is stopped.
•
Node failure: This includes instances such as a power failure or a software
error; this is sometimes called a forceful shutdown. Forcefully shutdown
nodes retain their valid caches if they are available. However, while the
node is shut down, there is no way to monitor the caches, change their
status, or invalidate them. They can be deleted by manually deleting the
cache files on the local node or by deleting the appropriate cache files on a
shared network location. Be aware that cache files are named with object
IDs.
The results of each of these types of shutdown are discussed below.
Resource availability
If a node is rendered unavailable because of a forceful shutdown, its cache
resources are still valid to other nodes in the cluster and are accessed if they
are available. If they are not available, new caches are created on other nodes.
In an administrative shutdown, caches associated with the shut down node are
no longer valid for other nodes, even if they are physically available, such as on
a file server.
Client connection status
Developer
Client connections that are not cluster-aware, such as Developer, do not
experience any change if a node is removed from a cluster. However, the local
node must regenerate its own caches rather than accessing the resources of
other nodes. If Intelligence Server is shut down, any Developer clients
connected to that Intelligence Server receive an error message notifying them
of the lost connection, regardless of whether that Intelligence Server was in a
cluster.
432
Shutting down a node
© 2015, MicroStrategy Inc.
System Administration Guide
MicroStrategy Web
If a cluster node shuts down while MicroStrategy Web users are connected,
those jobs return an error message by default. The error message offers the
option to resubmit the job, in which case MicroStrategy Web automatically
reconnects the user to another node.
*
Customizations to MicroStrategy Web can alter this default behavior in
several ways.
If a node is removed from the cluster, all existing connections continue to
function and remain connected to that machine, although the machine no
longer has access to the clustered nodes’ resources. Future connections from
MicroStrategy Web will be to valid cluster nodes.
Status after reboot
If a node goes down for any reason, all jobs on that node are terminated.
Restarting the node provides an empty list of jobs in the job queue.
If a node is forcefully shut down in a Windows environment, it automatically
rejoins the cluster when it comes back up.
Note the following:
*•
•
You can define the nodes that should automatically rejoin the cluster
on restart from the Intelligence Server Configuration Editor. For steps
on configuring this, see the MicroStrategy Developer Help.
If multiple nodes in the cluster are restarted at the same time, they
may not all correctly rejoin the cluster. To prevent this, separate the
restart times by several minutes.
The nodes that are still in the cluster but not available are listed in the Cluster
Monitor with a status of Stopped.
Maintaining result caches and History Lists in a
clustered environment
Proper maintenance of result caches and History Lists is important in any
MicroStrategy system. For detailed information on caches and cache
management, including recommended best practices, see Result caches, page
438. For detailed information on History Lists, including best practices, see
Saving report results: History List, page 466.
When maintaining result caches and History Lists in a clustered environment,
be aware of the following:
© 2015, MicroStrategy Inc.
Maintaining result caches and History Lists in a clustered
environment
433
System Administration Guide
•
You can manage the caches on a node only if that node is active and joined
to the cluster and if the project containing the caches is loaded on that
node.
•
Whenever a cache on one node of the cluster is created or updated, any
copies of the old cache for that report, on the same node or on other
nodes, are automatically invalidated. This means that only one valid copy
of a cache exists at any time for a report on all nodes in the cluster. For
more information about invalidating caches, see Invalidating result caches,
page 452.
•
The Cache Monitor’s hit count number on a machine reflects only the
number of cache hits that machine initiated on any cache in the cluster. If a
different machine in the cluster hits a cache on the local machine, that hit
is not be counted on the local machine’s hit count. For more information
about the Cache Monitor, see Monitoring result caches, page 447.
For example, ServerA and ServerB are clustered, and the cluster is
configured to use local caching (see Local caching, page 412). A report is
executed on ServerA, creating a cache there. When the report is executed
on ServerB, it hits the report cache on ServerA. The cache monitor on
ServerA does not record this cache hit, because ServerA’s cache monitor
displays activity initiated by ServerA only.
•
To ensure that History List messages are synchronized correctly between
nodes and to reduce system overhead, either enable user affinity clustering
or set the cache backup frequency to 0 (zero). For a discussion of these
settings, including instructions, see Configuring History Lists in a clustered
environment, page 423.
Maintaining History Lists in a clustered environment
User affinity clustering causes Intelligence Server to connect all sessions for a
user to the same node of the cluster. This enables Intelligence Server to keep
the user’s History List on one node of the cluster. Resource use is minimized
because the History List is not stored on multiple machines, and the History
List is never out of sync across multiple nodes of the cluster.
MicroStrategy recommends that you enable user affinity clustering in any
clustered system. If you are not using user affinity clustering, MicroStrategy
recommends that you set the cache backup frequency to 0 (zero) to ensure that
History List messages are synchronized correctly among nodes. For more
information about this setting, see Backup Frequency (minutes), page 456.
434
Maintaining result caches and History Lists in a clustered
environment
© 2015, MicroStrategy Inc.
System Administration Guide
To configure the History List governing settings for a clustered
environment
1
In Developer, log into a project source. You must log in as a user with
administrative privileges.
2
From the Administration menu, point to Server and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the Server Definition category, and then select Advanced.
4
Do one of the following:
•
To enable user affinity clustering, select the User Affinity Cluster check
box.
•
OR, if you do not want to enable user affinity clustering, then in the
Backup frequency (minutes) field, type 0 (zero).
5
Click OK to close the Intelligence Server Configuration Editor.
6
Restart Intelligence Server.
Connecting MicroStrategy Web to a cluster
You connect MicroStrategy Web to a cluster using MicroStrategy Web’s
Administration page. If the Intelligence Servers are on the same subnet as
MicroStrategy Web and are accessible by User Datagram Protocol (UDP), the
MicroStrategy Web Administration page can dynamically list the servers by
looking for the listener service running on the machines. If the server is listed
that you want to connect to, you can connect from this page. Alternatively, you
can type the server name.
If the machine selected is part of a cluster, the entire cluster appears on the
Administration page and is labeled as a single cluster. Click Help on
MicroStrategy Web’s Administration page for steps to connect to an
Intelligence Server.
Once MicroStrategy Web is connected to a cluster, all nodes reference the
same project. Load balancing directs new Web connections to the least loaded
node, as measured by user connections. Once connected to a node, the Web
user runs all MicroStrategy activity on the same node.
© 2015, MicroStrategy Inc.
Maintaining result caches and History Lists in a clustered
environment
435
System Administration Guide
If nodes are manually removed from the cluster, projects are treated as
separate in MicroStrategy Web, and the node connected to depends on which
project is selected. However, all projects are still accessing the same metadata.
Clustering and firewalls
Connecting to Intelligence Server from MicroStrategy Web through a firewall
is the same process regardless of the cluster state. The only difference is that
allowable ports, sources, and destinations may be available between
MicroStrategy Web and each of the nodes in the cluster.
Exporting to PDF or Excel
In MicroStrategy Web, users can export reports to PDF or to Excel for later
viewing. Users must have the Write privilege for the Inbox folder on the
Intelligence Server machine to be able to export reports.
To export to PDF or Excel in a clustered environment, users must have the
Write privilege for the ClusterInbox folder on all Intelligence Servers in the
cluster. For instructions on how to set up the ClusterInbox folder, see
Configuring caches in a cluster, page 417.
Node failure
MicroStrategy Web or Web Universal users can be automatically connected to
another node when a node fails. To implement automatic load redistribution
for these users, on the Web Administrator page, under Web Server select
Security, and in the Login area select Allow Automatic Login if Session is Lost.
436
Clustering and firewalls
© 2015, MicroStrategy Inc.
10
IMPROVING REPORT AND
DOCUMENT RESPONSE TIME:
CACHING
Introduction
A cache is a result set that is stored on a system to improve response time in
future requests. With caching, users can retrieve results from Intelligence
Server rather than re-executing queries against a database.
Intelligence Server supports the following types of caches:
•
Result caches: Report and document results that have already been
calculated and processed, that are stored on the Intelligence Server
machine so they can be retrieved more quickly than re-executing the
request against the data warehouse. For more information on these, see
Result caches, page 438.
Intelligent Cubes can function in a similar fashion to result caches: they
* allow you to store data from the data warehouse in Intelligence Server
memory, rather than in the database. Intelligent Cubes are part of the
OLAP Services add-on to Intelligence Server. For detailed information
about Intelligent Cubes, see the MicroStrategy In-memory Analytics
Guide.
© 2015, MicroStrategy Inc.
437
System Administration Guide
•
The History List is a way of saving report results on a per-user basis. For
more information, see Saving report results: History List, page 466.
•
Element caches: Most-recently used lookup table elements that are stored
in memory on the Intelligence Server or Developer machines so they can
be retrieved more quickly. For more information on these, see Element
caches, page 482.
•
Object caches: Most-recently used metadata objects that are stored in
memory on the Intelligence Server and Developer machines so they can be
retrieved more quickly. For more information on these, see Object caches,
page 494.
You specify settings for all cache types except History List under Caching in
the Project Configuration Editor. History List settings are specified in the
Intelligence Server Configuration Editor.
Result, element, and object caches are created and stored for individual
projects; they are not shared across projects. History Lists are created and
stored for individual users.
To make changes to cache settings, you must have the Administer Caches
privilege. In addition, changes to cache settings do not take effect until you
stop and restart Intelligence Server.
*
For additional ways to improve your MicroStrategy system’s response
time, see Chapter 8, Tuning Your System for Best Performance.
Result caches
A result cache is a cache of an executed report or document that is stored on
Intelligence Server. Result caches are either report caches or document caches.
You cannot create or use result caches in a direct (two-tier) environment.
* Caches are stored in Intelligence Server, not retained on Developer.
Report caches can be created or used for a project only if the Enable report
server caching check box is selected in the Project Configuration Editor under
the Caching: Result Caches: Creation category.
Document caches can be created or used for a project only if the Enable
Document Output Caching in Selected Formats check box is selected in the
Project Configuration Editor under the Caching: Result Caches: Creation
category, and one or more formats are selected.
438
© 2015, MicroStrategy Inc.
System Administration Guide
~
Document caches are created or used only when a document is executed in
MicroStrategy Web. Document caches are not created or used when a
document is executed from Developer.
By default, result caching is enabled at the project level. It can also be set per
report and per document. For example, you can disable caching at the project
level, and enable caching only for specific, frequently used reports. For more
information, see Result cache settings at the report level, page 465.
A result cache is created when you do any of the following:
•
In MicroStrategy Web or Developer, execute a saved report or document
containing only static objects.
•
In MicroStrategy Web or Developer, execute a saved report or document
containing one or more prompts. Each unique set of prompt selections
corresponds to a distinct cache.
•
In MicroStrategy Web, execute a template and filter combination.
•
Execute a report or document based on a schedule. The schedule may be
associated with MicroStrategy Web, Developer, Mobile, Distribution
Services, or Narrowcast Server. For more information about scheduling
reports, see Scheduling reports and documents: Subscriptions, page 531.
Caching does not apply to a drill report request because the report is
* constructed on the fly.
When a user runs a report (or, from MicroStrategy Web, a document), a job is
submitted to Intelligence Server for processing. If a cache for that request is
not found on the server, a query is submitted to the data warehouse for
processing, and then the results of the report are cached. The next time
someone runs the report or document, the results are returned immediately
without having to wait for the database to process the query.
The Cache Monitor displays detailed information about caches on a machine;
for more information see Monitoring result caches, page 447.
*
If you are running Intelligence Server on HP-UX v2, and you notice a slow
response time when using the Cache Monitor, see Cache Monitor and
Intelligent Cube Monitor performance, page 840 for steps you can take to
improve performance.
You can easily check whether an individual report hit a cache by viewing the
report in SQL View. The image below shows the SQL View of a MicroStrategy
Tutorial report, Sales by Region. The fifth line of the SQL View of this report
shows “Cache Used: Yes.”
© 2015, MicroStrategy Inc.
439
System Administration Guide
*
Client-side analytical processing, such as ad hoc data sorting, pivoting, view
filters, derived metrics, and so on, does not cause Intelligence Server to
create a new cache.
This section discusses the following topics concerning result caching:
•
Cache management best practices, page 440
•
Types of result caches, page 441
•
Location of result caches, page 443
•
Cache matching algorithm, page 444
•
Disabling result caching, page 446
•
Monitoring result caches, page 447
•
Managing result caches, page 451
•
Configuring result cache settings, page 455
Cache management best practices
Good result cache management practices depend on a number of factors, such
as the number of reports and documents in the project, the available disk
440
Cache management best practices
© 2015, MicroStrategy Inc.
System Administration Guide
space for caches, the amount of personalization in reports and documents, and
whether you are using clustered Intelligence Servers.
MicroStrategy recommends the following best practices for cache management:
•
The drive that holds the result caches should always have at least 10% of
its capacity available.
•
In a project with many reports, consider enabling caching on a report-byreport basis. Use MicroStrategy Enterprise Manager to determine which
reports are used often and thus are good candidates for caching. For
information about Enterprise Manager, see the Enterprise Manager chapter
in the MicroStrategy Operations Manager Guide. For information about
enabling caching per report, see Result cache settings at the report level,
page 465.
•
Disable caching for reports and documents with a high amount of
personalization, such as prompt answers or security filters.
To reuse results for reports and documents with a high amount of
personalization, use MicroStrategy OLAP Services to create Intelligent
Cubes. For more information about OLAP Services, see the MicroStrategy
In-memory Analytics Guide.
•
If results are cached by user ID (see Create caches per user, page 460), it
may be better to disable caching and instead use the History List. For
information about the History List, see Saving report results: History List,
page 466.
•
Be aware of the various ways in which you can tune the caching properties
to improve your system’s performance. For a list of these properties, and
an explanation of each, see Configuring result cache settings, page 455.
•
If you are using clustered Intelligence Servers, caching presents additional
maintenance requirements. For information on maintaining caches in a
clustered system, see Maintaining result caches and History Lists in a
clustered environment, page 433.
Types of result caches
The following types of result caches are created by Intelligence Server:
•
Matching caches, page 442
•
History caches, page 442
•
Matching-History caches, page 442
•
XML caches, page 442
All document caches are Matching caches; documents do not generate History
caches or XML caches. Intelligent Cube reports do not create Matching caches.
© 2015, MicroStrategy Inc.
Types of result caches
441
System Administration Guide
Matching caches
Matching caches are the results of reports and documents that are retained for
later use by the same requests later on. In general, Matching caches are the
type of result caches that are used most often by Intelligence Server.
When result caching is enabled, Intelligence Server determines for each
request whether it can be served by an already existing Matching cache. If
there is no match, it then runs the report or document on the database and
creates a new Matching cache that can be reused if the same request is
submitted again. This caching process is managed by the system administrator
and is transparent to general users who simply benefit from faster response
times.
History caches
History caches are report results saved for future reference in the History List
by a specific user. When a report is executed, an option is available to the user
to send the report to the History List. Selecting this option creates a History
cache to hold the results of that report and a message in the user’s History
List pointing to that History cache. The user can later reuse that report result
set by accessing the corresponding message in the History List. It is possible
for multiple History List messages, created by different users, to refer to the
same History cache.
The main difference between Matching and History caches is that a Matching
cache holds the results of a report or document and is accessed during
execution; a History cache holds the data for a History List message and is
accessed only when that History List message is retrieved.
For more information about History Lists, see Saving report results: History
List, page 466.
Matching-History caches
A Matching-History cache is a Matching cache that is referenced by at least
one History List message. It is a single cache composed of a Matching cache
and a History cache. Properties associated with the Matching caches and
History caches discussed above correspond to the two parts of the MatchingHistory caches.
XML caches
An XML cache is a report cache in XML format that is used for personalized
drill paths. It is created when a report is executed from MicroStrategy Web,
and is available for reuse in Web. It is possible for an XML cache to be created
at the same time as its corresponding Matching cache. XML caches are
automatically removed when the associated report or History cache is
removed.
442
Types of result caches
© 2015, MicroStrategy Inc.
System Administration Guide
To disable XML caching, select the Enable Web personalized drill paths option
in the Project definition: Drilling category in the Project Configuration Editor.
Note that this may adversely affect Web performance. For more information
about XML caching, see ACLs and personalized drill paths in MicroStrategy
Web, page 71.
Location of result caches
Separate result caches are created for each project on an Intelligence Server.
They are kept in memory and on disk. The server manages the swapping of
these caches between memory and disk automatically. Caches are
automatically unloaded, beginning with the least recently used cache, until the
maximum memory governing limits are reached.
The amount of memory available to store result caches is limited by the
Memory Storage settings. For information, see Maximum RAM usage, page
461.
Result cache files
By default, result cache files are stored in the directory where Intelligence
Server is installed \Caches\ServerDefinition\Machine Name\. Report
caches are stored in this folder; document caches are stored in the
\RWDCache\ subfolder of this folder.
Report cache file format
Report caches are stored on the disk in a binary file format. Each report cache
has two parts:
•
Cache<cache ID>_Info.che contains information about the cache, such as
the user and prompt answers.
•
Cache<cache ID>.che contains the actual data for the cache.
Report cache index files
Intelligence Server creates two types of index files to identify and locate report
caches:
•
CachePool.idx is an index file that contains a list of all Matching and
History caches and pointers to the caches’ locations.
•
CacheLkUp.idx is a lookup table that contains the list of all Matching
caches and their corresponding cache keys. Incoming report requests are
matched to report cache keys in this table to determine whether a
Matching cache can be used. This process is called cache matching (see
Cache matching algorithm, page 444). This lookup table is always backed
© 2015, MicroStrategy Inc.
Location of result caches
443
System Administration Guide
up to disk when Intelligence Server shuts down. Additional backups are
based on the Backup frequency and the Lookup Cleanup Frequency settings
(see Result cache settings at the server level, page 456).
Document cache file format
Document caches are stored on the disk in a binary file format. Each document
cache has two parts:
•
<cache ID>_info.rwdc contains information about the cache, such as the
user and prompt answers.
•
<cache ID>.rwdc contains the actual data for the cache.
Document cache index files
Intelligence Server creates two types of index files to identify and locate
document caches:
•
RWDPool.idx is an index file that contains a list of all Matching caches and
pointers to the caches’ locations.
•
RWDLkUp.idx is a lookup table that contains the list of all Matching caches
and their corresponding cache keys. Incoming document requests from
Web are matched to document cache keys in this table to determine
whether a Matching cache can be used. This process is called cache
matching (see Cache matching algorithm, page 444). The lookup table is
always backed up to disk when Intelligence Server shuts down. Additional
backups are based on the Backup frequency and the Lookup Cleanup
Frequency settings (see Result cache settings at the server level, page
456).
Cache matching algorithm
When a user requests a report, or a document from Web, cache keys are used
to determine whether a cache can be used to satisfy the request. If the cache
keys in the request match the ones in the result cache, the cached report or
document results are used. The matching process takes several steps that
involve a number of cache keys, and each step is explained in detail below. If at
any step, the matching is not successful, then the cache is not used and the
request executes against the data warehouse.
Step 1: Check the IDs
To check whether the requested report/document and the cached
report/document are the same, Intelligence Server compares the ID and
Version ID of the two. If they match, the process continues to Step 2.
444
Cache matching algorithm
© 2015, MicroStrategy Inc.
System Administration Guide
Alternately, Intelligence Server checks the Template ID, Template Version ID,
Filter ID, and Filter Version ID in the requested report/document against the
ones in the cache. If all of them match, the process continues to Step 2.
If you are not using MicroStrategy OLAP Services, any modification to a
~ report, even a simple formatting change or an Access Control List (ACL)
modification, changes the Template Version ID and invalidates the report
cache. With MicroStrategy OLAP Services, the cache is invalidated only if
the contents of the Report Objects pane change. For more information
about OLAP Services, see Intelligent Cubes, page 390.
Step 2: Check the personalization impact
If the report or document contains prompts, Intelligence Server checks the
prompt answers selected for the report. Different prompt answers change the
content of the report; therefore, the cache is not used if the prompt answers in
the report request are not the same as the ones in the report cache. Each set of
distinct prompt answers creates a distinct cache.
Step 3: Check the security impact
Intelligence Server makes sure that users with different security filters cannot
access the same cache. Intelligence Server compares the Security ID and
Security Version ID of all the security filters applied to the user in the request,
including those inherited from the groups to which he or she belongs, with the
security profile of the user who originated the cache.
Step 4: Check the modification impact
Intelligence Server does not use a cache if an object in the report/document
changes. To check this, Intelligence Server compares the IDs and Version IDs of
all application objects used in the requested report/document with the ones
used in the cached report/document. If any of these IDs are different, the
existing cache is automatically invalidated.
Step 5: Check the data language
Intelligence Server makes sure a cache is not used if the user running the
report is using a different language than the user who created the cache. Each
different language creates a different cache.
Step 6: Check the database security impact (optional)
You may find it necessary to add optional criteria, listed below, to the cache
matching process. These criteria are useful if database security view and
connection mapping are used to ensure that users with different security
© 2015, MicroStrategy Inc.
Cache matching algorithm
445
System Administration Guide
profiles, who see different data from the data warehouse, cannot access the
same cache. For information about connection mapping, see Controlling access
to the database: Connection mappings, page 80).
•
User ID: To match caches by the global unique identifier (GUID) of the user
requesting the cache, in the Caching: Result Caches: Creation category in
the Project Configuration Editor, select the Create caches per user check
box.
•
Database login: To match caches by the GUID of the database login
assigned to the user via a connection mapping, in the Caching: Result
Caches: Creation category in the Project Configuration Editor, select the
Create caches per database login check box.
This option is especially useful if database warehouse authentication is
* used. For more information, see Implementing database warehouse
authentication, page 114.
•
Database connection: To match caches by the GUID of the database
connection assigned to the user via a connection mapping, in the Caching:
Result Caches: Creation category in the Project Configuration Editor, select
the Create caches per database connection check box.
Step 7: Check additional criteria for documents
Document caches have additional criteria that must match before a cache can
be used:
•
The Export Option (All or Current Page) and Locale of the document must
match the cache.
•
The selector and group-by options used in the document must match those
used in the cache.
•
The format of the document (PDF, Excel, HTML, or XML/Flash) must
match the format of the cache.
•
In Excel, the document and cache must both be either enabled or disabled
for use in MicroStrategy Office.
•
In XML/Flash, the mode of the document (View, Interactive, Editable,
Flash) must match the mode of the cache.
•
In XML/Flash, the Web preferences of the user executing the document
must match the Web preferences of the user who created the cache.
Disabling result caching
By default, result caching is enabled in Intelligence Server. If the performance
gain is marginal compared to the added overhead, you can disable report
446
Disabling result caching
© 2015, MicroStrategy Inc.
System Administration Guide
caching. You may wish to disable caching in the following situations:
•
The data warehouse is updated more than once a day.
•
Most reporting is ad hoc so caching provides little value.
•
Reports are heavily prompted, and the answer selections to the prompts
are different each time the reports are run.
•
Few users share the same security filters when accessing the reports.
If you disable result caching for a project, you can set exceptions by
* enabling caching for specific reports or documents. For more information,
see Result cache settings at the report level, page 465.
To disable result caching
1
Open the Project Configuration Editor for the project.
2
Expand Caching, expand Result Caches, then select Creation.
3
To disable report and document caching, clear the Enable report server
caching check box.
4
To disable document caching but not report caching, leave the Enable
report server caching check box selected and clear the Enable document
output caching in selected formats check box.
5
Click OK. Caching is now disabled for this project.
Monitoring result caches
You use the Cache Monitor in Developer to monitor result caches. When result
caching is enabled and a user executes a report or document, a cache entry is
listed in the Cache Monitor.
You can also use the Diagnostics Configuration Tool for diagnostic tracing of
result caches (see Diagnostics and Performance Logging Tool, page 450), and
Command Manager to automatically update information about result caches
(see Command Manager, page 450).
A cache’s hit count is the number of times the cache is used. When a report
* is executed (which creates a job) and the results of that report are
retrieved from a cache instead of from the data warehouse, Intelligence
Server increments the cache’s hit count. This can happen when a user runs
a report or when the report is run on a schedule for the user. This does not
include the case of a user retrieving a report from the History List (which
© 2015, MicroStrategy Inc.
Monitoring result caches
447
System Administration Guide
does not create a job). Even if that report is cached, it does not increase its
hit count.
To view all report or document caches for a project in the Cache
Monitor
1
In Developer, log in to a project source. You must log in as a user with the
Monitor Caches privilege.
2
Expand Administration, then expand System Monitors, then expand Caches,
and then select Reports or Documents. The Cache Monitor Options dialog
box opens.
3
Select the project for which you want to view the caches and click OK. The
Report Cache Monitor or Document Cache Monitor opens.
4
To view additional details about a cache, double-click that cache. A Cache
Quick View dialog box opens for that cache.
5
To view additional details about all caches, from the View menu select
Details.
6
To change the columns shown in the Details view, right-click in the Cache
Monitor and select View Options. The Cache Monitor View Options dialog
box opens. Select the columns you want to see and click OK.
7
To view caches from a different project, right-click in the Cache Monitor
and select Filter. The Cache Monitor Options dialog box opens. Select the
project for which you want to view caches and click OK. That project's
caches are now shown in the Cache Monitor.
8
To display History and XML caches in the Report Cache Monitor, rightclick in the Cache Monitor and select Filter. The Cache Monitor Options
dialog box opens. Select Show caches for History List messages or Show
XML caches and click OK. The XML or History caches for the specified
project are now shown in the Report Cache Monitor.
You can perform any of the following options after you select one or more
caches and right-click:
448
•
Delete: Removes the cache from both memory and disk
•
Invalidate: Marks the cache as unusable, but leaves a reference to it in
users’ History Lists (if any)
•
Load from disk: Loads into memory a cache that was previously unloaded
to disk
•
Unload to disk: Removes the cache from memory and stores it on disk
Monitoring result caches
© 2015, MicroStrategy Inc.
System Administration Guide
For detailed information about these actions, see Managing result caches,
page 451.
If you are running Intelligence Server on HP-UX v2, you may notice a slow
* response time when using the Cache Monitor. For information about this
delay, including steps you can take to improve performance, see Cache
Monitor and Intelligent Cube Monitor performance, page 840.
Cache statuses
A result cache’s status is displayed in the Report Cache Monitor using one or
more of the following letters:
Status
Stands
for
Description
R
The cache is valid and ready to be used.
P
The cache is currently being updated.
I
The cache has been invalidated, either manually or by a change to one of the objects used in
the cache. It is no longer used, and will be deleted by Intelligence Server. For information
about invalid caches, see Invalidating result caches, page 452.
E
The cache has been invalidated because its lifetime has elapsed. For information about
expired caches, see Expiring result caches, page 455.
L
The cache is loaded into Intelligence Server memory.
U
The cache file has been updated.
D
The cache has been updated in Intelligence Server memory since the last time it was saved
to disk.
F
The cache has been unloaded, and exists as a file on disk instead of in Intelligence Server
memory. For information about loading and unloading caches, see Unloading and loading
result caches to disk, page 452.
Cache types
Result caches can be of the following types:
Type
Description
Matching
The cache is valid and available for use.
Note: All document caches are Matching caches.
History
The cache referenced in at least one History List message.
MatchingHistory
The cache is valid and available for use, and also referenced in at least one History List message.
XML
(Web only) The cache exists as an XML file and is referenced by the matching cache. When the
corresponding Matching cache is deleted, the XML cache is deleted.
© 2015, MicroStrategy Inc.
Monitoring result caches
449
System Administration Guide
For more information about each type of cache, see Types of result caches,
page 441.
Diagnostics and Performance Logging Tool
The Intelligence Server logs are often useful when troubleshooting issues with
report caching in a MicroStrategy system. You can view these logs and
configure what information is logged using the Diagnostics and Performance
Logging Tool. For more information, see Configuring what is logged, page
802.
To enable diagnostic tracing of result caches
1
Open the MicroStrategy Diagnostics and Performance Logging Tool. (From
the Windows Start menu, point to All Programs, then MicroStrategy Tools,
and then select Diagnostics Configuration.)
2
In the Select Configuration drop-down list, select CastorServer Instance.
3
Clear the Use Machine Default Diagnostics Configuration check box.
4
In the Report Server component, in the Cache Trace dispatcher, click the
File Log (currently set to <None>) and select <New>. The Log Destination
Editor opens.
5
Enter the following information in the editor:
•
Select Log Destination: <New>
•
File Name: cacheTrace
•
Max File Size: 5000
•
File Type: Diagnostics
6
Click Save, and then click Close. The Log Destination Editor closes.
7
In the Report Server component, in the Cache Trace dispatcher, click the
File Log (currently set to <None>) and select cacheTrace. The creation and
deletion of report caches is now logged to this file.
Command Manager
You can also use the following Command Manager scripts to monitor result
caches:
•
450
LIST [ALL] REPORT CACHES [FOR PROJECT "<project_name>"]
lists all report caches on Intelligence Server for a project.
Monitoring result caches
© 2015, MicroStrategy Inc.
System Administration Guide
•
LIST [ALL] PROPERTIES FOR REPORT CACHE "<cache_name>"
IN PROJECT "<project_name>" lists information about a report
cache.
By default, these scripts are at C:\Program Files (x86)
\MicroStrategy\Command Manager\Outlines\Cache_Outlines.
For more information about Command Manager, see Chapter 15, Automating
Administrative Tasks with Command Manager, or the Command Manager
Help (from within Command Manager, press F1).
Managing result caches
As a system administrator, your greatest concerns about caching are
consistency and availability of the cached data. You have the important
responsibility of synchronizing the caches with the data in the data warehouse.
Therefore, as data changes in the data warehouse, you must ensure that the
outdated cached data is either updated or discarded. You can do this in two
main ways: Invalidating and Scheduling. These methods, along with other
maintenance operations that you can use when managing result caches, are
discussed below. They include:
•
Scheduling updates of result caches, page 451
•
Unloading and loading result caches to disk, page 452
•
Invalidating result caches, page 452
•
Deleting result caches, page 454
•
Purging all result caches in a project, page 454
•
Expiring result caches, page 455
Scheduling updates of result caches
You can schedule a report or document to be executed regularly, to ensure that
the result cache is up-to-date. Scheduling is a proactive measure aimed at
making sure result caches are readily available when needed.
Typically, reports and documents that are frequently used best qualify for
scheduling. Reports and documents that are not frequently used do not
necessarily need to be scheduled because the resource cost associated with
creating a cache on a schedule might not be worth it. For more information on
scheduling a result cache update, see Scheduling reports and documents:
Subscriptions, page 531.
© 2015, MicroStrategy Inc.
Managing result caches
451
System Administration Guide
Unloading and loading result caches to disk
You may need to unload caches from memory to disk to create free memory
for other operations on the Intelligence Server machine.
If a report cache is unloaded to disk and a user requests that report, the report
is then loaded back into memory automatically. You can also manually load a
report cache from the disk into memory.
Caches are saved to disk according to the Backup frequency setting (see Backup
Frequency (minutes), page 456). Caches are always saved to disk regardless of
whether they are loaded or unloaded; unloading or loading a cache affects only
the cache’s status in Intelligence Server memory.
Invalidating result caches
Invalidating a result cache indicates to Intelligence Server that this cache
should not be used. Invalidation is a preventive measure that you can take to
ensure that users do not run reports that are based on outdated cached data.
Examples of when the data may be outdated include:
•
When the data warehouse changes, the existing caches are no longer valid
because the data may be out of date. In this case, future report/document
requests should no longer use the caches.
•
When the definition of an application object (such as a report definition,
template, filter, and so on) changes, the related result cache is
automatically marked as invalid.
•
When the cache for any of the datasets for a document becomes invalidated
or deleted, the document cache is automatically invalidated.
Caches need to be invalidated when new data is loaded from the data
warehouse so that the outdated cache is not used to fulfill a request. You can
invalidate all caches that rely on a specific table in the data warehouse. For
example, you could invalidate all report/document caches that use the Sales_
Trans table in your data warehouse.
Only Matching and Matching-History caches can be invalidated. Invalidating a
cache has the following effects:
•
An invalid Matching cache is automatically deleted.
•
An invalid Matching-History cache is converted to a History cache. If all
History messages relating to this cache are deleted, the converted History
cache is also deleted.
MicroStrategy strongly recommends that you invalidate Matching and
~ Matching-History caches instead of deleting them directly.
452
Managing result caches
© 2015, MicroStrategy Inc.
System Administration Guide
Invalid caches are deleted automatically based on the Cache lookup cleanup
frequency setting. For more information about this setting, see Cache lookup
cleanup frequency (sec), page 457.
You can invalidate caches manually or by scheduling the invalidation process.
Invalidating a cache with a scheduled administration task
You can schedule a MicroStrategy administration task to invalidate caches on a
recurring schedule. In the Project Configuration Editor, in the Caches: Result
Caches (Maintenance) category, you can select a schedule to be used to
invalidate caches. For more information about scheduling tasks, see Scheduling
administrative tasks, page 528.
Invalidating a cache with a Command Manager script
You can update the data warehouse load routine to invoke a MicroStrategy
Command Manager script to invalidate the appropriate caches. This script is at
C:\Program Files (x86)\MicroStrategy\Command
Manager\Outlines\Cache_Outlines\Invalidate_Report_Cache_
Outline. For more information about Command Manager, see Chapter 15,
Automating Administrative Tasks with Command Manager.
To invoke Command Manager from the database server, use one of the
following commands:
•
SQL Server: exec xp.cmdshell cmdmgr
•
Oracle: host cmdmgr
•
DB2: ! cmdmgr
•
Teradata: os cmdmgr
Invalidating a cache manually
From the Cache Monitor, you can manually invalidate one or more caches.
To manually invalidate a cache
1
In Developer, log into a project source. You must log in as a user with the
Monitor Caches privilege.
2
Expand Administration, then expand System Monitors, then expand Caches,
and then select Reports or Documents. The Cache Monitor Options dialog
box opens.
© 2015, MicroStrategy Inc.
Managing result caches
453
System Administration Guide
3
Select the project for which you want to invalidate a cache and click OK.
The Report Cache Monitor or Document Cache Monitor opens.
4
Right-click the cache to invalidate and select Invalidate Cache. The cache is
invalidated.
Deleting result caches
Typically, you do not need to manually delete result caches if you are
invalidating caches and managing History List messages. Result caches are
automatically deleted by Intelligence Server if cache invalidation and History
Lists are performed and maintained properly, as follows:
•
A Matching cache is deleted automatically when it is invalidated.
•
A History cache is deleted automatically when all History List messages
that reference it are deleted. MicroStrategy recommends that you actively
maintain History List messages, as History caches are deleted
automatically.
•
A Matching-History cache is handled in the following way:
•
▫
When all the History List messages that reference a Matching-History
cache are deleted, the cache is converted to a Matching cache.
▫
When a Matching-History cache is invalidated, it is converted to a
History cache.
An XML cache is deleted automatically when its associated Matching or
History cache is deleted.
In all cases, cache deletion occurs based on the Cache lookup cleanup
frequency setting. For more information about this setting, see Cache lookup
cleanup frequency (sec), page 457.
You can manually delete caches via the Cache Monitor and Command Manager,
or schedule deletions via the Administration Tasks Scheduling, in the same
way that you manually invalidate caches. For details, see Invalidating result
caches, page 452.
Purging all result caches in a project
You can delete all the result caches in a project at once by selecting the Purge
Caches option in the Project Configuration Editor. This forces reports
executed after the purge to retrieve and display the latest data from the data
warehouse.
Purging deletes all result caches in a project, including caches that are still
~ referenced by the History List. Therefore, purge caches only when you are
sure that you no longer need to maintain any of the caches in the project,
and otherwise delete individual caches.
454
Managing result caches
© 2015, MicroStrategy Inc.
System Administration Guide
Even after purging caches, reports and documents may continue to display
cached data. This can occur because results may be cached at the object and
element levels, in addition to at the report/document level. To ensure that a
re-executed report or document displays the most recent data, purge all three
caches. For instructions on purging element and object caches, see Deleting all
element caches, page 493 and Deleting object caches, page 497.
To purge all result caches in a project
1
In Developer, right-click the project and select Project Configuration Editor.
The Project Configuration Editor opens.
2
Expand Caching, then Result Caches, and then select Maintenance.
3
Click Purge Now. The caches are purged.
Expiring result caches
Cache expiration is the process of marking a cache out of date. Expiring a
cache has the same result as invalidating a cache, and applies to Matching
caches and Matching-History caches. The only difference between expiration
and invalidation is that expiration happens after a set period of time. For
information on how invalidation works, see Invalidating result caches, page
452.
MicroStrategy strongly recommends that you invalidate a cache when changes
in the data from the data warehouse affect the cache, rather than relying on a
time interval to expire caches. To disable cache expiration, in the Caching:
Result Caches: Maintenance subcategory of the Project Configuration Editor,
select the Never expire caches check box.
Cache expiration occurs automatically according to the Cache duration (Hours)
setting in the Caching: Result Caches (Maintenance) subcategory in the Project
Configuration Editor.
When a cache is updated, the current cache lifetime is used to determine
* the cache expiration date based on the last update time of the cache. This
means that changing the Cache duration (Hours) setting or the Never Expire
Caches setting does not affect the expiration date of existing caches. It
affects only the new caches that are being or will be created.
Configuring result cache settings
Result cache settings can be configured at three levels:
•
At the server level (see Result cache settings at the server level, page 456)
© 2015, MicroStrategy Inc.
Configuring result cache settings
455
System Administration Guide
•
At the project level (see Result cache settings at the project level, page
457)
•
At the individual report/document level (see Result cache settings at the
report level, page 465)
Each is discussed in detail below.
Changes to any of the caching settings are in effect only after Intelligence
* Server restarts.
Result cache settings at the server level
You can configure the following caching settings in the Intelligence Server
Configuration Editor, in the Server Definition (Advanced) category. Each is
described below.
•
Backup Frequency (minutes), page 456
•
Cache lookup cleanup frequency (sec), page 457
You can also configure these settings using the Command Manager script,
Alter_Server_Config_Outline.otl, located at C:\Program Files
(x86)\MicroStrategy\Command Manager\Outlines\Cache_
Outlines.
Backup Frequency (minutes)
When a result cache is created, the cache is initially stored in memory on
Intelligence Server. Caches are backed up to disk as specified by the backup
frequency setting.
You can specify the cache backup frequency in the Backup frequency (minutes)
box under the Server Definition: Advanced subcategory in the Intelligence
Server Configuration Editor.
If you specify a backup frequency of 0 (zero), result caches are saved to disk as
soon as they are created. If you specify a backup frequency of 10 (minutes), the
result caches are backed up from memory to disk ten minutes after they are
created.
In a clustered environment, MicroStrategy recommends that you set the
backup frequency to 0 (zero) to ensure that History List messages are
synchronized correctly.
Backing up caches from memory to disk more frequently than necessary
* can drain resources.
456
Configuring result cache settings
© 2015, MicroStrategy Inc.
System Administration Guide
This setting also defines when Intelligent Cubes are saved to secondary
storage, as described in Defining when Intelligent Cubes are automatically
saved to secondary storage, page 517.
Cache lookup cleanup frequency (sec)
The Cache lookup cleanup frequency (sec) setting determines how frequently
the CacheLkUp.idx file is cleaned up. This file stores cache matching
information and can become significant in size, especially when a large number
of caches include a large number of prompts. The cleanup process reduces the
amount of memory that the file consumes and the time that it takes to back up
the lookup table to disk.
The default value for this setting is 0 (zero), which means that the cleanup
takes place only at server shutdown. You may change this value to another
based on your needs, but make sure that it does not negatively affect your
system performance. MicroStrategy recommends cleaning the cache lookup at
least daily but not more frequently than every half hour.
Result cache settings at the project level
You can configure the following caching settings in the Project Configuration
Editor, in the Result Caches category. Each is described below.
•
•
In the Result Caches (creation) subcategory
▫
Enable report server caching, page 458
▫
Enable document output caching in selected formats, page 458
▫
Enable prompted report and document caching, page 459
▫
Record prompt answers for cache monitoring, page 459
▫
Enable non-prompted report and document caching, page 459
▫
Enable XML caching for reports, page 459
▫
Create caches per user, page 460
▫
Create caches per database login, page 460
▫
Create caches per database connection, page 460
In the Result caches (storage) subcategory
▫
Cache file directory, page 460
▫
Cache encryption level on disk, page 461
▫
Maximum RAM usage, page 461 (separate settings for report and
document caches)
© 2015, MicroStrategy Inc.
Configuring result cache settings
457
System Administration Guide
•
•
▫
Maximum number of caches, page 462 (separate settings for report and
document caches)
▫
RAM swap multiplier, page 463
▫
Maximum RAM for cache index %, page 463
▫
Load caches on startup, page 463
In the Result caches (maintenance) subcategory
▫
Never expire caches, page 464
▫
Cache duration (Hours), page 464
▫
Cache expiration and dynamic dates, page 464
▫
Purging all result caches in a project, page 454
In the Subscription Execution subcategory
▫
Cache usage defaults for subscriptions, page 464
To locate these settings, right-click the project and select Project
Configuration. Then, in the Project Configuration Editor, expand Caching, and
then select Result Caches.
You can also configure these settings using Command Manager scripts located
at C:\Program Files (x86)\MicroStrategy\Command
Manager\Outlines\Cache_Outlines.
Enable report server caching
Result caches can be created or used for a project only if the Enable report
server caching check box is selected in the Project Configuration Editor in the
Caching: Result Caches: Creation category.
If this option is disabled, all the other options in the Result Caches: Creation
and Result Caches: Maintenance categories are grayed out, except for Purge
Now. By default, report server caching is enabled. For more information on
when report caching is used, see Result caches, page 438.
Enable document output caching in selected formats
Document caches can be created or used for a project only if the Enable
document output caching in selected formats check box is selected in the
Project Configuration Editor in the Caching: Result Caches: Creation category.
Document caches are created for documents that are executed in the selected
output formats. You can select all or any of the following: PDF, Excel, HTML,
and XML/Flash/HTML5.
458
Configuring result cache settings
© 2015, MicroStrategy Inc.
System Administration Guide
*
Document caches are created or used only when a document is executed
from MicroStrategy Web. They are not created or used in Developer.
Enable prompted report and document caching
Enabled by default, the Enable caching for prompted reports and documents
setting controls whether prompted reports and documents are cached. In an
environment where the majority of reports are prompted and each prompt is
likely to receive a different answer each time it is used, the probability of
matching an existing cache is low. In this case, caching these report datasets do
not provide significant benefits; therefore you may want to disable this setting.
To disable this setting, clear its check box in the Project Configuration Editor
under the Caching: Result Caches: Creation category.
Record prompt answers for cache monitoring
If you Enable caching for prompted reports and documents (see above), you
can also Record prompt answers for cache monitoring. This causes all prompt
answers to be listed in the Cache Monitor when browsing the result caches.
You can then invalidate specific caches based on prompt answers, either from
the Cache Monitor or with a custom Command Manager script.
This option is disabled by default. To enable it, select its check box in the
Project Configuration Editor under the Caching: Result Caches: Creation
category.
Enable non-prompted report and document caching
If you Enable caching for non-prompted reports and documents, reports and
documents without any prompts are cached.
This option is enabled by default. To disable it, clear its check box in the
Project Configuration Editor under the Caching: Result Caches: Creation
category.
Enable XML caching for reports
If you Enable XML caching for reports, reports executed from MicroStrategy
Web create XML caches in addition to any Matching or History caches they
may create. For information about XML caches, see XML caches, page 442.
This option is enabled by default. To disable it, clear its check box in the
Project Configuration Editor under the Caching: Result Caches: Creation
category.
© 2015, MicroStrategy Inc.
Configuring result cache settings
459
System Administration Guide
Create caches per user
If the Create caches per user setting is enabled, different users cannot share
the same result cache. Enable this setting only in situations where security
issues (such as database-level Security Views) require users to have their own
cache files. For more information, see Cache matching algorithm, page 444.
*
Instead of enabling this setting, it may be more efficient to disable caching
and instead use the History List. For information about the History List,
see Saving report results: History List, page 466.
This option is disabled by default. To enable it, select its check box in the
Project Configuration Editor under the Caching: Result Caches: Creation
category.
Create caches per database login
Select the Create caches per database login option if database authentication
is used. This means that users who execute their reports using different
database login IDs cannot use the same cache. For more information, see
Cache matching algorithm, page 444.
This option is disabled by default. To enable it, select its check box in the
Project Configuration Editor under the Caching: Result Caches: Creation
category.
Create caches per database connection
Select the Create caches per database connection option if connection
mapping is used. For more information, see Cache matching algorithm, page
444.
This option is disabled by default. To enable it, select its check box in the
Project Configuration Editor under the Caching: Result Caches: Creation
category.
Cache file directory
The Cache file directory, in the Project Configuration Editor under the Caching:
Result Caches: Storage category, specifies where all the cache-related files are
stored. By default these files are stored in the Intelligence Server installation
directory, in the \Caches\<Server definition name> subfolder.
In a non-clustered environment, report caches are typically stored on the same
machine that is running Intelligence Server.
In a clustered environment, there are two options:
460
Configuring result cache settings
© 2015, MicroStrategy Inc.
System Administration Guide
•
Local caching: Each node hosts its own cache file directory that needs to be
shared as “ClusterCache” so that other nodes can access it. ClusterCache is
the share name Intelligence Server looks for on other nodes to retrieve
caches.
•
Centralized caching: All nodes have the cache file directory set to the same
network location, \\<machine name>\<shared directory name>.
For example, \\My_File_Server\My_Cache_Directory.
Note the following:
*
• For caches located on Windows machines, and on UNIX/Linux
machines using Samba, set the path to \\<machine name>\<shared
directory name>. For caches stored on UNIX/Linux machines, set
the path to //<SharedLocation>/<CacheFolder>.
•
On UNIX systems, it is recommended that you mount the shared
location as a network drive. You must create a folder in your machine’s
Volumes directory before mounting the location. For example, mount
-t afp afp://my_file_server/my_inbox_directory
/Volumes/my_network_mount
Make sure this cache directory is writable from the network account
~ under which Intelligence Server is running. Each Intelligence Server
creates its own subdirectory.
For more information about which configuration may be best in clustered
environments, see Configuring caches in a cluster, page 417.
Cache encryption level on disk
The Cache encryption level on disk drop-down list controls the strength of the
encryption on result caches. You can configure result caches to use either
simple encryption or AES encryption with a 128-bit key. Encrypting caches
increases security, but may slow down the system.
By default the caches that are saved to disk are not encrypted. You can change
the encryption level in the Project Configuration Editor under the Caching:
Result Caches: Storage category.
Maximum RAM usage
The Maximum RAM usage settings, in the Project Configuration Editor under
the Caching: Result Caches: Storage category, control the amount of memory
that result caches consume on Intelligence Server. When this setting is about
to be exceeded, the least recently used caches are automatically unloaded to
disk.
© 2015, MicroStrategy Inc.
Configuring result cache settings
461
System Administration Guide
If the machine experiences problems because of high memory use, you may
want to reduce the Maximum RAM usage for the result caches. You need to
find a good balance between allowing sufficient memory for report caches and
freeing up memory for other uses on the machine. The default value is 25
megabytes for reports and datasets, and 256 megabytes for formatted
documents. The maximum value for each of these is 65536 megabytes, or 64
gigabytes.
MicroStrategy recommends that you initially set this value to 10% of the
system RAM if it is a dedicated Intelligence Server machine, that is, if no other
processes are running on it. This setting depends on the following factors:
•
The size of the largest report cache.
This setting should be at least as large as the largest report in the project
that you wish to be cached. If the amount of RAM available is not large
enough for the largest report cache, that cache will not be used and the
report will always execute against the warehouse. For example, if the
largest report you want to be cached in memory is 20 MB, the maximum
RAM usage needs to be at least 20 MB.
•
The average size and number of cache files.
•
The amount of memory on the Intelligence Server machine.
•
The amount of memory used while the system is at maximum capacity.
You should monitor the system’s performance when you change the Maximum
RAM usage setting. In general, it should not be more than 30% of the
machine’s total memory.
For more information about when report caches are moved in and out of
memory, see Location of result caches, page 443.
Maximum number of caches
The Maximum number of caches settings, in the Project Configuration Editor
under the Caching: Result Caches: Storage category, limit the number of result
caches, including Matching caches, History caches, Matching-History caches,
and XML caches, allowed in the project at one time. The default values are
10,000 datasets, and 100,000 formatted documents.
This setting depends on the following factors:
462
•
The number of users and the number of History List messages they keep.
•
The number of report caches and their average size.
•
The amount of hard disk space available in the cache directory.
Configuring result cache settings
© 2015, MicroStrategy Inc.
System Administration Guide
RAM swap multiplier
If the Intelligence Server memory that has been allocated for caches becomes
full, it must swap caches from memory to disk. The RAM swap multiplier
setting, in the Project Configuration Editor under the Caching: Result Caches:
Storage category, controls how much memory is swapped to disk, relative to
the size of the cache being swapped into memory. For example, if the RAM
swap multiplier setting is 2 and the requested cache is 80 kilobytes, 160
kilobytes are swapped from memory to disk.
If the cache memory is full and several concurrent reports are trying to swap
from disk, the swap attempts can fail and re-execute those reports. This
counteracts any gain in efficiency due to caching. In this case, increasing the
RAM swap multiplier setting provides additional free memory into which those
caches can be swapped.
The default value for this setting is 2.
Maximum RAM for cache index %
This setting determines what percentage of the amount of memory specified in
the Maximum RAM usage limits (see Maximum RAM usage, page 461) can be
used for result cache lookup tables. If your reports and documents contain
many prompt answers, the cache lookup table may reach this limit. At this
point, Intelligence Server no longer creates new caches. To continue creating
new caches, you must either remove existing caches to free up memory for the
cache lookup table, or increase this limit.
The default value for this parameter is 100%, and the values can range from
10% to 100%.
You can change this setting in the Project Configuration Editor under the
Caching: Result Caches: Storage category.
Load caches on startup
If report caching is enabled and the Load caches on startup setting is enabled,
when Intelligence Server starts up, it loads report caches from disk into
memory until it reaches the Maximum RAM usage limit (see Maximum RAM
usage, page 461). If the Load caches on startup setting is disabled, it loads
report caches only when requested by users.
Load caches on startup is enabled by default. To disable it, in the Project
Configuration Editor under the Caching: Result Caches: Storage category, clear
the Load caches on startup check box.
For large projects, loading caches on startup can take a long time so you have
the option to set the loading of caches on demand only. However, if caches are
not loaded in advance, there will be a small additional delay in response time
© 2015, MicroStrategy Inc.
Configuring result cache settings
463
System Administration Guide
when they are hit. Therefore, you need to decide which is best for your set of
user and system requirements.
Never expire caches
The Never expire caches setting, in the Project Configuration Editor under the
Caching: Result Caches: Maintenance category, causes caches to never
automatically expire. MicroStrategy recommends selecting this check box,
instead of using time-based result cache expiration. For more information, see
Expiring result caches, page 455.
Cache duration (Hours)
All caches that have existed for longer than the Cache duration (Hours) are
automatically expired. This duration is set to 24 hours by default. You can
change the duration in the Project Configuration Editor under the Caching:
Result Caches: Maintenance category.
As mentioned earlier, MicroStrategy recommends against using time-based
result cache expiration. For more information, see Expiring result caches, page
455.
Cache expiration and dynamic dates
By default, caches for reports based on filters that use dynamic dates always
expire at midnight of the last day in the dynamic date filter. This behavior
occurs even if the Cache Duration (see above) is set to zero.
For example, a report has a filter based on the dynamic date “Today.” If this
report is executed on Monday, the cache for this report expires at midnight on
Monday. This is because a user who executes the report on Tuesday expects to
see data from Tuesday, not the cached data from Monday. For more
information on dynamic date filters, see the Filters chapter in the
MicroStrategy Advanced Reporting Guide.
To change this behavior, in the Project Configuration Editor under the
Caching: Result Caches: Maintenance category, select the Do Not Apply
Automatic Expiration Logic for reports containing dynamic dates check box.
When this setting is enabled, report caches with dynamic dates expire in the
same way as other report caches do, according to the Cache duration setting.
Cache usage defaults for subscriptions
By default, if a cache is present for a subscribed report or document, the
report or document uses the cache instead of re-executing the report or
document. If no cache is present, one is created when the report or document
464
Configuring result cache settings
© 2015, MicroStrategy Inc.
System Administration Guide
is executed. For more information about subscriptions, see Scheduling reports
and documents: Subscriptions, page 531.
When you create a subscription, you can force the report or document to reexecute against the warehouse even if a cache is present. You can also prevent
the subscription from creating a new cache.
To change the default behavior for new subscriptions, use the following check
boxes in the Project Configuration Editor, in the Caching: Subscription
Execution category.
•
To cause new History List and Mobile subscriptions to execute against the
warehouse by default, select the Re-run History List and Mobile
subscriptions against the warehouse check box.
•
To cause new email, file, and print subscriptions to execute against the
warehouse by default, select the Re-run file, email, and print subscriptions
against the warehouse check box.
•
To prevent new subscriptions of all types from creating or updating caches
by default, select the Do not create or update matching caches check box.
Result cache settings at the report level
These setting allows you to disable or enable caching for a specific report or
document.
*
You must have the Use Design Mode privilege to configure
report/document-level cache settings.
Result caching options
•
To set the caching options from a report, in the Report Editor, from the
Data menu, select Report caching options. The Report Caching Options
dialog box opens.
•
To set the caching options for a document, in the Document Editor, from
the Format menu, select Document Properties. The Document Properties
dialog box opens. Select the Caching category.
To enable caching for a report or document even if caching is disabled at the
project level, select the Enable Caching option.
For a document, you can choose which formats, such as HTML or PDF, are
* cached. You can also choose to create a new cache for every page-by,
incremental fetch block, and selector setting.
To disable caching for a report or document even if caching is enabled at the
project level, select the Disable Caching option.
© 2015, MicroStrategy Inc.
Configuring result cache settings
465
System Administration Guide
To use the project-level setting for caching, select the Use default project-level
behavior option. This indicates that the caching settings configured at the
project level in the Project Configuration Editor apply to this specific report or
document as well.
Saving report results: History List
The History List is a folder where Intelligence Server places report and
document results for future reference. Each user has a unique History List.
With the History List, users can:
•
Keep shortcuts to previously run reports, like the Favorites list when
browsing the Internet.
•
Perform asynchronous report execution. For example, multiple reports can
be run at the same time within one browser, or pending reports can remain
displayed even after logging out of a project.
•
View the results of scheduled reports.
The History List is displayed at the user level, but is maintained at the project
source level. The History List folder contains messages for all the projects in
which the user is working. The number of messages in this folder is controlled
by the setting Maximum number of messages per user. For example, if you set
this number at 40, and you have 10 messages for Project A and 15 for Project
B, you can have no more than 15 for Project C. When the maximum number is
reached, the oldest message in the current project is purged automatically to
leave room for the new one.
~
If the current project has no messages but the message limit has been
reached in other projects in the project source, the user may be unable to
run any reports in the current project. In this case the user must log in to
one of the other projects and delete messages from the History list in that
project.
This section provides the following information about History Lists:
466
•
Understanding History Lists, page 467
•
Configuring History List data storage, page 470
•
Accessing History Lists, page 473
•
Archiving History List messages, page 475
•
Managing History Lists, page 476
Configuring result cache settings
© 2015, MicroStrategy Inc.
System Administration Guide
Understanding History Lists
A History List is a collection of pre-executed reports and documents that have
been sent to a user’s personal History folder. These pre-executed reports and
documents are called History List messages.
The data contained in these History List messages is stored in the History List
repository, which can be located on Intelligence Server, or in the database. For
more information about the differences between these storage options, see
Configuring History List data storage, page 470.
A History List message provides a snapshot of data at the time the message is
created. Using a different report filter on a History List message does not
cause the message to return different data. To view a report in the History List
with a different report filter, you must re-execute the report.
Each report that is sent to the History List creates a single History List
message. Each document creates a History List message for that document,
plus a message for each dataset report in the document.
You can send report results to the History List manually or automatically.
Sending a message to the History List manually
Report results can be manually sent to the History List any time you plan to
execute a report, during report execution, or even after a report is executed:
•
Before report execution:
▫
From Developer: Right-click the report or document name and select
Send to History from the shortcut menu. The report or document is
executed, and a message is generated in the History List.
This option is not available from a shortcut to a report or document.
*
▫ From Web: This option is not available.
•
In the middle of report execution:
▫
From Developer: While the report is being executed, select Send to
History List from the File menu.
This operation creates two jobs, one for executing the report (against
* the data warehouse) and another for sending the report to History List.
If caching is enabled, the second job remains in the waiting list for the
first job to finish; if caching is not enabled, the second job runs against
the data warehouse again. Therefore, to avoid wasting resources,
MicroStrategy recommends that if caching is not enabled, users not
send the report to History List in the middle of a report execution.
© 2015, MicroStrategy Inc.
Understanding History Lists
467
System Administration Guide
▫
From Web: While the report is being executed, click Add to History List
on the wait page.
This operation creates only one job because the first one is modified
* for the Send to History List request.
•
After report execution:
▫
From Developer: After the report is executed, select Send to History
from the File menu.
▫
From Web: After the report is executed, select Add to History List from
the Home menu.
*
Two jobs are created for Developer, and only one is created for Web.
Sending a message to the History List automatically
Report results can be automatically sent to the History List. There are two
different ways to automatically send messages to the History list. You can
either have every report or document that you execute sent to your History
List, or you can subscribe to specific reports or documents:
•
•
468
To automatically send every report and document that is executed to your
History List:
▫
From MicroStrategy Web: Select History List from the Project
Preferences, and then select Automatically for Add reports and
documents to my History List.
▫
From Developer: Select MicroStrategy Developer Preferences from the
Tools menu, then select History Options, and then select Automatically
send reports to History List during execution.
To schedule delivery of specific reports or documents:
▫
From MicroStrategy Web: On the reports page, under the name of the
report that you want to send to History List, select Subscriptions, and
then click Add History List subscription on the My Subscriptions page.
Choose a schedule for the report execution. A History List message is
generated automatically whenever the report is executed based on the
schedule.
▫
From Developer: Right-click a report or document and select Schedule
Delivery to and select History List. The History List Subscription Editor
opens. Define the subscription details. For specific information about
using the Subscription Editor, click Help.
Understanding History Lists
© 2015, MicroStrategy Inc.
System Administration Guide
Filtering and purging your History List messages in Developer
The History List Monitor filter can be used to either filter which messages are
displayed in the History List, or it can define the History List messages that
you want to purge from the History List. The History List Monitor filter
allows you to define various parameters to filter or purge your History List
messages.
To use the History List Monitor Filter to filter your History List messages,
right click the History List folder, and select Filter. After you have specified the
filter parameters, click OK. The History List Monitor Filter closes, and your
History List messages will be filtered accordingly.
To use the History List Monitor Filter to purge items from your History List
folder, right click the History List folder and select Purge. The History List
Monitor Filter opens. After you have specified the filter parameters, click
Purge. The History List Monitor Filter closes, and the History List Messages
that match the criteria defined in the History List Monitor Filter are deleted.
For more details about the History List Monitor Filter, click Help.
History Lists and caching
The History List is closely related to caching functionality. History Lists
consist of messages that point to report results, which are stored as History
caches. Therefore, when a History List message is deleted, the History cache
that the message points to is deleted as well.
Multiple messages can point to the same History cache. In this case, the
* History cache is deleted after all messages pointing to it have been deleted.
If you are using a database-based History List repository, by default,
duplicates of the report caches that are associated with the History List
messages are stored in the database, as well as being stored locally. This way,
if a user deletes the local report cache, the cache that is stored in the database
can still be accessed. This behavior applies to both History Caches and
History-Matching Caches. For more information about types of caches, see
Types of result caches, page 441. For more information about storing History
List data, see Configuring History List data storage, page 470.
If you are exporting a report or document to a database-based History List,
* only the most recent export is stored in the History List. For example, if
you export a document as an Excel file, and then export it as a PDF, only
the PDF is saved in the History List.
You can use the History List messages to retrieve report results, even when
report caching is disabled.
© 2015, MicroStrategy Inc.
Understanding History Lists
469
System Administration Guide
Configuring History List data storage
The History List repository is the location where all History List data is
stored.
There are several different ways that the History List repository can be
configured to store data for the History List. It can be stored in a database, or
in a file on the Intelligence Server machine. Alternately, you can use a hybrid
approach that stores the message information in a database for improved
search results and scalability, and the message results in a file for performance
reasons.
Configuring Intelligence Server to use a database-based or hybrid
History List repository
The caches associated with History Lists can be stored in a database. Storing
the History List messages in a database reduces the load on the machine that
hosts Intelligence Server.
If you are using a database-based History List repository, the caches that are
associated with a History List message are also stored in the History List
database.
You can also configure Intelligence Server to use a hybrid History List
repository. In this configuration the History List message information is
stored in a database, and the cached results are stored in a file. This approach
preserves the scalability of the database-based History List, while maintaining
the improved performance of the file-based History List.
Be aware of the following:
~•
•
Once Intelligence Server has been configured to store the History List
cached data in the database, this setting will apply to the entire server
definition.
MicroStrategy does not recommend reverting back to a file-based
History List repository. If you want to revert back to a file-based
repository, you must replace the existing server definition with a new
one.
Prerequisites
470
•
The storage location for the History List data (the History List repository)
must have been created in the database. For information about creating the
History List repository in the database, see the MicroStrategy Installation
and Configuration Guide.
•
If you are using a hybrid History List repository, the storage location for
the History List results must have been created and shared on the
Intelligence Server machine. For information about how to configure this
Configuring History List data storage
© 2015, MicroStrategy Inc.
System Administration Guide
location, see Configuring Intelligence Server to use a file-based History
List repository, page 472.
To configure Intelligence Server to use a database-based or hybrid
History List repository
1
In Developer, log in to the project source as a user with administrative
privileges.
2
From the Administration menu, select Server, then Configure MicroStrategy
Intelligence Server. The Intelligence Server Configuration Editor opens.
3
On the left, expand History Settings and select General.
4
Select Database based. The following warning message is displayed:
~
Once Intelligence Server has been configured to store the History List
cached data in the database, this setting will apply to the entire server
definition.
5
Click Yes. The warning message closes.
6
By default, History List caches are backed up to the database. To store only
History List caches on the server, clear the Backup report history caches to
the database check box.
7
To use a hybrid History List repository, in the External central storage
directory for Database-based History List field, type the location for the filebased History List message storage. For information about how the cached
results are stored, see Configuring Intelligence Server to use a file-based
History List repository, page 472.
You can browse to the file location by clicking the . . . (browse) button.
*
8 Expand Server Definition, and then select General.
© 2015, MicroStrategy Inc.
Configuring History List data storage
471
System Administration Guide
9
Under Content Server Location, from the Database Instance menu, select
the database instance that points to the History List repository in the
database.
10 Click OK. The Intelligence Server Configuration Editor closes.
11 Restart Intelligence Server for the changes to take effect.
To confirm that the History List repository has been configured correctly
12 Log in to the project source as a user with administrative privileges.
13 From the Administration menu, select Server, then Configure MicroStrategy
Intelligence Server. The Intelligence Server Configuration Editor opens.
14 On the left, expand History Settings and select General. If you have
configured Intelligence Server properly, the following message is displayed
in the Repository Type area of the Intelligence Server Configuration Editor:
Configuring Intelligence Server to use a file-based History List
repository
When you initially set up your History List, you can store the History List in a
file folder on the machine that hosts Intelligence Server. The default location
of this folder is relative to the installation path of Intelligence Server:
.\Inbox\<Server definition name>
For example, C:\Program Files (x86)
\MicroStrategy\Intelligence Server\Inbox\MicroStrategy Tu
torial Server.
In a non-clustered environment, History List cached data is typically stored on
the same machine that is running Intelligence Server.
In a clustered environment, there are two storage options:
•
Local caching: Each node hosts its own cache file directory that needs to be
shared as “ClusterCache” so that other nodes can access it.
•
Centralized caching: All nodes have the cache file directory set to the same
network location, \\<machine name>\<shared directory name>.
For example, \\My_File_Server\My_Inbox_Directory.
*
472
Note the following:
Configuring History List data storage
© 2015, MicroStrategy Inc.
System Administration Guide
For caches stored on Windows machines, and on UNIX/Linux machines using
Samba, set the path to \\<machine name>\<shared directory name>.
For caches stored on UNIX/Linux machines, set the path to
//<SharedLocation>/<CacheFolder>.
On UNIX systems, it is recommended that you mount the shared location as a
network drive. You must create a folder in your machine’s Volumes directory
before mounting the location. For example, mount -t afp afp://my_
file_server/my_inbox_directory/Volumes/my_network_mount.
~
Make sure that the network directory is writable from the network
account under which Intelligence Server is running. Each Intelligence
Server creates its own subdirectory.
For steps to configure Intelligence Server to store cached History List data in
a file-based repository, see the procedure below.
To configure Intelligence Server to use a file-based History List
repository
1
Log in to the project source as a user with administrative privileges.
2
From the Administration menu, select Server, then Configure MicroStrategy
Intelligence Server. The Intelligence Server Configuration Editor opens.
3
On the left, expand History Settings and select General.
4
Select File based, and type the file location in the History directory field.
You can browse to the file location by clicking the . . . (browse) button.
*
5 Click OK. The Intelligence Server Configuration Editor closes.
Accessing History Lists
History Lists can be accessed from both MicroStrategy Web and Developer.
You cannot see the History Lists for all users unless you have access to the
History List Messages Monitor. For more information about the History List
Messages Monitor, see Managing History Lists, page 476.
Accessing the History List folder in MicroStrategy Web
In MicroStrategy Web, log in to the desired project and click the History List
link in the top navigation bar. This displays all history list messages for the
user that is currently logged in. The following information is available:
•
Name: Name (or alias) of the report.
© 2015, MicroStrategy Inc.
Accessing History Lists
473
System Administration Guide
•
Status: Status of a report job, for example, executing, processing on
another node, ready, and so on.
If you are working in a clustered environment, only Ready and Error
* statuses are synchronized across nodes. While a job on one node is
reported as Executing, it is reported as Processing On Another Node on
all the other nodes.
•
Message Creation Time: The time the message was created, in the currently
selected time zone.
•
Details: More information about the report, including total number of
rows, total number of columns, server name, report path, message ID,
report ID, status, message created, message last updated, start time, finish
time, owner, report description, template, report filter, view filter,
template details, prompt details, and SQL statements.
Each time a user submits a report that contains a prompt, the dialog
* requires that he answer the prompt. As a result, multiple listings of the
same report may occur. The differences among these reports can be found
by checking the timestamp and the data contents.
You can export a message, view a message in PDF format, or rename a
message. For more detailed instructions, see the MicroStrategy Web Help.
Accessing the History List folder in Developer
In Developer, History List messages are located in the History folder under
the project name. The number next to the History List folder indicates how
many unread History List messages are contained in the folder. Click the
History folder to view all the messages. Each message is listed with the
following information:
•
Name: Name of the report
•
Finish Time: The time the report execution is finished
•
Folder name: Name of the folder where the original report is saved
•
Last update time: The time when the original report was last updated
•
Message text: The status message for the History List message
•
Start time: The time the report execution was started
•
Status: Status of a report job, for example, has been executed successfully
and is ready, is not executed successfully, is currently executing, or is
waiting to execute
You can see more details of any message by right-clicking it and selecting
Quick View. This opens a new window with the following information:
474
Accessing History Lists
© 2015, MicroStrategy Inc.
System Administration Guide
•
Report definition: Expand this category to see information about the report
definition, including the description, owner, time and date it was last
modified, the project it resides in, the report ID, the path to the report’s
location, and report details.
•
Job execution statistics: Expand this category to see information about the
report execution, including the start and end time, the total number of
rows and columns in the report, the total number of rows and columns that
contain raw data, whether a cache was used, the job ID, and the SQL
produced.
•
Message status: Expand this category to see information about the
message itself, including the language, user creation time, last update time,
read status, format, request type, application, message ID, and message
text.
Archiving History List messages
Generally, you archive History List messages if you want to see the report
results as they were when the messages were originally created. This feature is
useful when you need to track changes in the report results for a scheduled
report.
Intelligence Server automatically marks History List messages as archived
when, in the Subscription Editor, the The new scheduled report will overwrite
older versions of itself check box is cleared. Archived messages can also be
created in a MicroStrategy Web subscription if, on the Project Defaults History List Preferences page, the The new scheduled report will overwrite
older versions of itself check box is cleared.
To archive all History List messages in a project in Web
1
In Preferences Levels category, select Project defaults.
2
In the Preferences category, select History List.
3
Clear the check box for The new scheduled report will overwrite older
versions of itself.
To archive History List messages in Developer
1
From the Administration menu, select Scheduling and then select
Subscription Creation Wizard. The Subscription Creation Wizard opens.
2
Review the steps displayed, and click Next.
3
Specify the following characteristics of the schedule:
© 2015, MicroStrategy Inc.
Archiving History List messages
475
System Administration Guide
•
Choose the schedule that you want to use.
•
Choose the project that contains the object that you want to archive.
•
Choose History List from the Delivery Type drop-down menu.
Click Next.
4
5
Choose the reports or documents that you wish to archive:
•
Browse to the report or document that you want to archive. You can
select multiple reports or documents by holding the Ctrl key while
clicking them.
•
Click the right arrow to add the report or document.
•
Click Next when all of the reports or documents that you want to
archive have been added.
Select a user group to receive the message for the archived report or
document:
•
Browse to the user group that you want to send the archived report to.
You can select multiple reports or documents by holding the Ctrl key
while clicking them.
•
Click the right arrow to add the group.
•
Click Next when all of the user groups that you want to receive the
archived report or document have been added.
All members in the user group receive the History List message.
*
6 Specify the subscription properties. You can choose to do the following:
•
Run the schedule immediately
•
Set the expiration date for the subscription
•
Send a delivery notification to all users included in the subscription.
7
Clear the The new scheduled report will overwrite older versions of itself
check box, and click Next.
8
Review the summary screen and click Finish. The Subscription Creation
Wizard closes.
Managing History Lists
Administrators manage History Lists and the History caches at the same time.
For information on the relationship between the History caches and History
Lists, see History caches, page 442.
476
Managing History Lists
© 2015, MicroStrategy Inc.
System Administration Guide
An administrator can control the size of the History List and thus control
resource usage through the following settings:
•
The maximum size of the History List is governed at the project level. Each
user can have a maximum number of History List messages, set by an
administrator. For more details, including instructions, see Controlling the
maximum size of the History List, page 477.
•
Message lifetime is the length of time before a History List message is
automatically deleted. For more details about message lifetime, see
Controlling the lifetime of History List messages, page 478.
•
You can also delete History List messages according to a schedule. For
more details, including instructions, see Scheduling History List message
deletion, page 479.
•
If you are using a database-based History List, you can reduce the size of
the database by disabling the History List backup caches. For more details,
including instructions, see Backing up History caches to the History List
database, page 480.
If you are using a database-based History List repository and you have the
proper permissions, you have access to the History List Messages Monitor.
This powerful tool allows you to view and manage History List messages for
all users. For more information, see Monitoring History List messages, page
481.
History List backup frequency
The backup frequency for History List messages is the same as for caching.
History List messages are backed up to disk as frequently as the server backup
frequency setting specifies. For more information, see Backup Frequency
(minutes), page 456.
History Lists in a clustered environment
In a clustered environment, each server maintains its own History List file.
However, the same messages are retrieved and presented to the user
regardless of the machine from which the History List is accessed. For
complete details on History Lists in a clustered environment, see
Synchronizing History Lists, page 413.
Controlling the maximum size of the History List
The maximum size of the History List is governed at the project level. The
project administrator can set a maximum number of History List messages for
each user. The default value is -1, which means that there is no maximum
number of History List messages.
© 2015, MicroStrategy Inc.
Managing History Lists
477
System Administration Guide
The administrator can also specify whether to create separate messages for
each dataset report that is included in a Report Services document or to create
only a message for the document itself, and whether to create messages for
documents that have been exported in other formats, such as Excel or PDF.
Not creating these additional History List messages can improve History List
performance, at the cost of excluding some data from the History List. By
default, all reports and documents create History List messages.
To configure the messages that are stored in the History List
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. The Project Configuration Editor opens.
3
Expand the Project Definition category and select the History list
subcategory.
4
In the Maximum number of messages per user field, type the maximum
number of History List messages to store for each user, or type -1 for no
limit.
5
To create a History List message for each dataset report included in a
Report Services document, select the Save Report Services document
dataset messages to History List check box. To create only a message for
the document, and not for the dataset reports, clear this check box.
6
To create History List messages for Report Services documents that are
exported to other formats, select the Save exported results for interactive
executions sent to History List check box. To not create messages for
documents when they are exported, clear this check box.
7
Click OK to close the Project Configuration Editor.
8
Restart Intelligence Server for your changes to take effect.
Controlling the lifetime of History List messages
Message lifetime controls how long (in days) messages can exist in a user’s
History List. This setting allows administrators to ensure that no History List
messages reside in the system indefinitely. Messages are tested against this
setting at user logout and deleted if found to be older than the established
lifetime.
When a message is deleted for this reason, any associated History caches are
also deleted. For more information about History caches, see History caches,
page 442.
478
Managing History Lists
© 2015, MicroStrategy Inc.
System Administration Guide
The default value is -1, which means that messages can stay in the system
indefinitely until the user manually deletes them.
To set message lifetime
1
In Developer, log into a project source.
2
From the Administration menu, point to Server and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand History Settings on the left, then select General.
4
Type a number in the Message lifetime (days) field.
5
Click OK. The Intelligence Server Configuration Editor closes.
Scheduling History List message deletion
You can delete History List messages using the Schedule Administration Tasks
feature, which is accessed by selecting Scheduling from the Administration
menu. This allows you to periodically and selectively purge History List
messages of certain users and groups. You can choose to target only certain
messages, including:
•
Messages for a certain project or for all projects
•
Messages in the History Lists of all users in a certain group
•
Messages that are read or unread
•
Messages that were created more than x number of days ago
The Delete History List messages feature can also be used for one-time
maintenance by using a non-recurring schedule.
To schedule History List message deletion
1
In Developer, log into a project source.
2
From the Administration menu, select Scheduling, then select Schedule
Administration Tasks. The Schedule Administration Tasks window opens.
3
Select a project from the Available Projects list.
4
Select Delete History List messages as the action.
© 2015, MicroStrategy Inc.
Managing History Lists
479
System Administration Guide
5
Select a schedule from the preconfigured options, for example, at close of
business (weekday), first of month, on database load, and so on.
6
Type a number in the Lifetime (days) box.
7
Select an option for the messages status:
•
Read
•
Unread
•
All
8
Click ... (the browse button) to select a user/group for which the History
List messages will be deleted.
9
Click OK.
Cleaning up the History List Database
You can clean up the History List database using the Schedule Administration
Tasks feature, which is accessed by selecting Scheduling from the
Administration menu. This allows you to periodically remove orphaned entries
from the database, and it allows you to remove history list messages for
deleted users.
The Clean History List database feature can also be used for one-time
maintenance by using a non-recurring schedule.
To schedule History List database cleanup
1
In Developer, log into a project source.
2
From the Administration menu, select Scheduling, then select Schedule
Administration Tasks. The Schedule Administration Tasks window opens.
3
Select a project from the Available Projects list.
4
Select Clean History List database as the action.
5
Click OK.
Backing up History caches to the History List database
By default, in a database-based History List, the History caches are backed up
to the database. This provides increased scalability in large systems, and
increases availability to the History caches in the event of a node failure. It
also allows you to set longer message lifetimes for History List messages,
because older History caches can be deleted from the Intelligence Server
machine’s hard disk and can be served by the database instead.
480
Managing History Lists
© 2015, MicroStrategy Inc.
System Administration Guide
If you are concerned about the size of the database used for a database-based
History List, you can disable the use of the database as a long-term backup for
History caches.
To disable the database backup for History caches
1
In Developer, log into a project source.
2
From the Administration menu, point to Server and then select Configure
MicroStrategy Intelligence Server. The Intelligence Server Configuration
Editor opens.
3
Expand the History Settings category, and select General.
4
Clear the Backup report history caches to database check box.
5
Click OK to exit the Intelligence Server Configuration Editor.
Monitoring History List messages
The History List Messages Monitor allows you to view all History List
messages for all users, view detailed information about each message, and
purge the messages based on certain conditions.
To use the History List Messages Monitor, your History List repository must
be stored in a database. For more information about configuring the History
List repository, see Configuring Intelligence Server to use a database-based
or hybrid History List repository, page 470.
To monitor the History List messages
1
In Developer, log in to a project source. You must log in as a user with the
Administer History List Monitor and the Monitor History List privileges.
2
Expand Administration, then expand System Monitors, and then select
History List Messages. All History List messages are displayed, as shown
below:
© 2015, MicroStrategy Inc.
Managing History Lists
481
System Administration Guide
3
To view the details of a History List message, double-click that message. A
Quick View window opens, with detailed information about the message.
4
To filter the messages displayed based on criteria that you define, rightclick a message and select Filter.
To purge a History List message
1
Select the message in the History List Monitor.
2
Right-click the message and select Purge. The message is purged from the
database.
Element caches
When a user runs a prompted report containing an attribute element prompt
or a hierarchy prompt, an element request is created. (Additional ways to
create an element request are listed below.) An element request is actually a
SQL statement that is submitted to the data warehouse. Once the element
request is completed, the prompt can be resolved and sent back to the user.
Element caching, set by default, allows for this element to be stored in
memory so it can be retrieved rapidly for subsequent element requests
without triggering new SQL statements against the data warehouse.
For example, if ten users run a report with a prompt to select a region from a
list, when the first user runs the report, a SQL statement executes and
retrieves the region elements from the data warehouse to store in an element
cache. The next nine users see the list of elements return much faster than the
first user because the results are retrieved from the element cache in memory.
If element caching is not enabled, when the next nine users run the report,
nine additional SQL statements will be submitted to the data warehouse,
which puts unnecessary load on the data warehouse.
482
Managing History Lists
© 2015, MicroStrategy Inc.
System Administration Guide
Element caches are the most-recently used lookup table elements that are
stored in memory on the Intelligence Server or Developer machines so they
can be retrieved more quickly. They are created when users:
•
Browse attribute elements in Developer using the Data Explorer, either in
the Folder List or the Report Editor
•
Browse attribute elements in the Filter Editor
•
Execute a report containing a prompt exposing an attribute list (which
includes hierarchies and element list types). The element list is displayed
when the report executes and creates an element cache.
This section discusses the following topics concerning element caching:
•
Element caching terminology, page 483
•
Location of element caches, page 484
•
Cache matching algorithm, page 484
•
Enabling or disabling element caching, page 485
•
Limiting the number of elements displayed and cached at a time, page
486
•
Caching algorithm, page 489
•
Limiting the amount of memory available for element caches, page 489
•
Limiting which attribute elements a user can see, page 491
•
Limiting element caches by database connection, page 492
•
Result cache files, page 443
•
Deleting all element caches, page 493
•
Summary table of element cache settings, page 494
Element caching terminology
The following terminology is helpful in understanding the concept of element
caching:
•
Element Request/Browse Query: A SQL request issued to the data
warehouse to retrieve a list of attribute elements. This request accesses the
attributes lookup table, which is defined when the attribute is created in
Architect. If the key to the lookup table is the attribute itself, a SELECT is
issued for the element request. If the attributes lookup table is in a lowerlevel lookup table (for example, month in the lookup date table) a SELECT
DISTINCT is used for the element request. Element requests may also
© 2015, MicroStrategy Inc.
Element caching terminology
483
System Administration Guide
contain a WHERE clause if resulting from a search, filtered hierarchy
prompt, drill request on a hierarchy prompt, or a security filter.
•
Element Cache Pool: The amount of memory Intelligence Server allocates
for element caching. In the interface, this value is called Maximum RAM
usage, set in the Project Configuration Editor in the Caching: Auxiliary
Caches: Elements category. The default value for this setting is 1 MB.
Intelligence Server estimates that each object uses 512 bytes; therefore, by
default, Intelligence Server caches about 2,048 element objects. If an
element request results in more objects needing to be cached than what the
maximum size of the element cache pool allows, the request is not cached.
•
Element Incremental Fetch Size: The maximum number of elements for
display in the interface per element request. On Developer, the default for
the Element Incremental Fetch setting is 1,000 elements; on Web, the
default is 15 elements.
Location of element caches
Element caches are stored only in memory and are not saved to disk. They can
exist on both Intelligence Server and Developer machines.
When a Developer user triggers an element request, the cache within the
Developer machine’s memory is checked first. If it is not there, the Intelligence
Server memory is checked. If it is not there, the results are retrieved from the
data warehouse. Each option is successively slower than the previous one, for
example, the response time could be 1 second for Developer, 2 seconds for
Intelligence Server, and 20 seconds for the data warehouse.
Cache matching algorithm
For an element cache to be used, the cache must be valid, and it must match
the job being executed. The following cache keys are used in the matching
process:
484
•
Attribute ID
•
Attribute version ID
•
Element ID
•
Search criteria
•
Database connection (if the project is configured to check for the cache
key)
•
Database login (if the project is configured to check for the cache key)
•
Security filter (if the project and attributes are configured to use the cache
key)
Location of element caches
© 2015, MicroStrategy Inc.
System Administration Guide
Enabling or disabling element caching
When the MicroStrategy system is installed for the first time, the element
caching is enabled by default. You can disable it for an entire project, for a
Developer client, or for a specific attribute in the project’s schema. The data
source cache setting DssCacheSettingElementMaxMemoryConsumption
controls the total amount of memory used by the element server cache. Setting
this value to zero completely disables the element cache.
*
In situations where the data warehouse is loaded more that once a day, it
may be desirable to disable element caching.
To disable element caching for a project
In the Project Configuration Editor, in the Caching: Auxiliary Caches
(Elements) category, under Server, set the Maximum RAM usage (KBytes)
to 0 (zero).
To disable element caching for Developer
In the Project Source Manager, select the Memory tab, set the Maximum
RAM usage (KBytes) to 0 (zero).
You might want to perform this operation if you always want to use the caches
on Intelligence Server. This is because when element caches are purged, only
the ones on Intelligence Server are eliminated automatically while the ones in
Developer remain intact. Caches are generally purged because there are
frequent changes in the data warehouse that make the caches invalid.
To disable element caching for an attribute
1
In Developer, right-click the attribute and select Edit. The Attribute Editor
opens.
2
On the Display tab, clear the Enable element caching check box.
© 2015, MicroStrategy Inc.
Enabling or disabling element caching
485
System Administration Guide
Limiting the number of elements displayed and cached
at a time
Incremental element fetching reduces the amount of memory Intelligence
Server uses to retrieve elements from the data warehouse and improves the
efficiency of Intelligence Server’s element caching. You can set the maximum
number of elements to display in the interface per element request in the
Project Configuration Editor, by using the Maximum number of elements to
display setting in the Project definition: Advanced category. The default value
is 1,000 for Developer and 15 for Web.
Attribute element requests can be quite large (sometimes exceeding 100,000
elements). Requests of this size take a large amount of memory and time to
pull into Intelligence Server and typically force many of the smaller element
caches out of the element cache pool. Caching such large element lists is often
unnecessary because users rarely page through extremely large element lists;
they do a search instead.
When the incremental element fetching is used, an additional pass of SQL is
added to each element request. This pass of SQL determines the total number
of elements that exist for a given request. This number helps users decide how
to browse a given attributes element list. This additional pass of SQL
generates a SELECT COUNT DISTINCT on the lookup table of the attribute
followed by a second SELECT statement (using an ORDER BY) on the same
table. From the result of the first query, Intelligence Server determines if it
should cache all of the elements or only an incremental set.
The incremental retrieval limit is four times the incremental fetch size. For
example, if your MicroStrategy Web product is configured to retrieve 50
elements at a time, 200 elements along with the distinct count value are
placed in the element cache. The user must click the next option four times to
introduce another SELECT pass, which retrieves another 200 records in this
example. Because the SELECT COUNT DISTINCT value was cached, this
would not be issued a second time the SELECT statement is issued.
To optimize the incremental element caching feature (if you have large
element fetch limits or small element cache pool sizes), Intelligence Server
uses only 10 percent of the element cache on any single cache request. For
example, if 200 elements use 20 percent of the cache pool, Intelligence Server
caches only 100 elements, which is 10 percent of the available memory for
element caches.
The number of elements retrieved per element cache can be set for Developer
users at the project level, MicroStrategy Web product users, a hierarchy, or an
attribute. Each is discussed below.
486
Limiting the number of elements displayed and cached at a time
© 2015, MicroStrategy Inc.
System Administration Guide
To limit the number of elements displayed for a project (affects only
Developer users)
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. The Project Configuration Editor opens.
3
Expand Project definition, then select Advanced.
4
Type the limit in the Maximum number of elements to display box.
To limit the number of elements displayed for MicroStrategy Web
product users
1
In MicroStrategy Web, log in to a project as a user with the Web
Administration privilege.
2
Click the MicroStrategy icon, then click Preferences. The Web Preferences
page opens.
3
Select Project Defaults in the Preferences Level category.
4
Select General in the Preferences category.
5
Type the limit for the Maximum number of attribute elements per block
setting in the Incremental Fetch subcategory.
To limit the number of elements displayed on a hierarchy
1
Open the Hierarchy editor, right-click the attribute and select Element
Display from the shortcut menu, and then select Limit. The Limit dialog box
opens.
2
Type a number in the Limit box.
To limit the number of elements displayed for an Attribute
1
Open the Attribute Editor.
2
Select the Display tab.
© 2015, MicroStrategy Inc.
Limiting the number of elements displayed and cached at a time
487
System Administration Guide
3
In the Element Display category, select the Limit option and type a number
in the box.
The element display limit set for hierarchies and attributes may further
* limit the number of elements set in the project properties or Web
preferences. For example, if you set 1,000 for the project, 500 for the
attribute, and 100 for the hierarchy, Intelligence Server retrieves only 100
elements.
Optimizing element requests
You may find the incremental element fetching feature’s additional SELECT
COUNT DISTINCT query to be costly on your data warehouse. In some cases,
this additional query adds minutes to the element browse time, making this
performance unacceptable for production environments.
To make this more efficient, you can set a VLDB option to control how the
total rows are calculated. The default is to use the SELECT COUNT
DISTINCT. The other option is to have Intelligence Server loop through the
table after the initial SELECT pass, eventually gett">