MicroStrategy Web Services

Administration Guide

Version: 9.2
Document Number: 09430920
Tenth Edition, March 2011, version 9.2
To ensure that you are using the documentation that corresponds to the software you are licensed to use, compare this version number with the software
version shown in “About MicroStrategy...” in the Help menu of your software.
Document number: 09430920
Copyright © 2011 by MicroStrategy Incorporated. All rights reserved.
If you have not executed a written or electronic agreement with MicroStrategy or any authorized MicroStrategy distributor, 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-2011 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, Inc. 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, Inc., 1850 Towers Crescent Plaza, Vienna, VA 22182. Rights are reserved under copyright laws of the United States with
respect to unpublished portions of the Software.
The following are either trademarks or registered trademarks of MicroStrategy Incorporated in the United States and certain other countries:
MicroStrategy, MicroStrategy 6, MicroStrategy 7, MicroStrategy 7i, MicroStrategy 7i Evaluation Edition, MicroStrategy 7i Olap Services, MicroStrategy 8,
MicroStrategy 9, MicroStrategy Distribution Services, MicroStrategy MultiSource Option, MicroStrategy Command Manager, MicroStrategy Enterprise
Manager, MicroStrategy Object Manager, MicroStrategy Reporting Suite, MicroStrategy Power User, MicroStrategy Analyst, MicroStrategy Consumer,
MicroStrategy Email Delivery, MicroStrategy BI Author, MicroStrategy BI Modeler, MicroStrategy Evaluation Edition, MicroStrategy Administrator,
MicroStrategy Agent, MicroStrategy Architect, MicroStrategy BI Developer Kit, MicroStrategy Broadcast Server, MicroStrategy Broadcaster,
MicroStrategy Broadcaster Server, MicroStrategy Business Intelligence Platform, MicroStrategy Consulting, MicroStrategy CRM Applications,
MicroStrategy Customer Analyzer, MicroStrategy Desktop, MicroStrategy Desktop Analyst, MicroStrategy Desktop Designer, MicroStrategy eCRM 7,
MicroStrategy Education, MicroStrategy eTrainer, MicroStrategy Executive, MicroStrategy Infocenter, MicroStrategy Intelligence Server, MicroStrategy
Intelligence Server Universal Edition, MicroStrategy MDX Adapter, MicroStrategy Narrowcast Server, MicroStrategy Objects, MicroStrategy OLAP
Provider, MicroStrategy SDK, MicroStrategy Support, MicroStrategy Telecaster, MicroStrategy Transactor, MicroStrategy Web, MicroStrategy Web
Business Analyzer, MicroStrategy World, Application Development and Sophisticated Analysis, Best In Business Intelligence, Centralized Application
Management, Information Like Water, Intelligence Through Every Phone, Intelligence To Every Decision Maker, Intelligent E-Business, Personalized
Intelligence Portal, Query Tone, Rapid Application Development, MicroStrategy Intelligent Cubes, The Foundation For Intelligent E-Business, The
Integrated Business Intelligence Platform Built For The Enterprise, The Platform For Intelligent E-Business, The Scalable Business Intelligence Platform
Built For The Internet, Industrial-Strength Business Intelligence, Office Intelligence, MicroStrategy Office, MicroStrategy Report Services, MicroStrategy
Web MMT, MicroStrategy Web Services, Pixel Perfect, Pixel-Perfect, MicroStrategy Mobile, MicroStrategy Integrity Manager and MicroStrategy Data
Mining Services are all registered trademarks or trademarks of MicroStrategy Incorporated.
All other company and product names may be trademarks of the respective companies with which they are associated. Specifications subject to change
without notice. MicroStrategy is not responsible for errors or omissions. MicroStrategy makes no warranties or commitments concerning the availability
of future products or versions that may be planned or under development.
Patent Information
This product is patented. One or more of the following patents may apply to the product sold herein: U.S. Patent Nos. 6,154,766, 6,173,310, 6,260,050,
6,263,051, 6,269,393, 6,279,033, 6,567,796, 6,587,547, 6,606,596, 6,658,093, 6,658,432, 6,662,195, 6,671,715, 6,691,100, 6,694,316, 6,697,808,
6,704,723, 6,741,980, 6,765,997, 6,768,788, 6,772,137, 6,788,768, 6,798,867, 6,801,910, 6,820,073, 6,829,334, 6,836,537, 6,850,603, 6,859,798,
6,873,693, 6,885,734, 6,940,953, 6,964,012, 6,977,992, 6,996,568, 6,996,569, 7,003,512, 7,010,518, 7,016,480, 7,020,251, 7,039,165, 7,082,422,
7,113,993, 7,127,403, 7,174,349, 7,181,417, 7,194,457, 7,197,461, 7,228,303, 7,260,577, 7,266,181, 7,272,212, 7,302,639, 7,324,942, 7,330,847,
7,340,040, 7,356,758, 7,356,840, 7,415,438, 7,428,302, 7,430,562, 7,440,898, 7,486,780, 7,509,671, 7,516,181, 7,559,048, 7,574,376, 7,617,201,
7,725,811, 7,801,967, 7,836,178, 7,861,161, 7,861,253, and 7,881,443. Other patent applications are pending.
Various MicroStrategy products contain the copyrighted technology of third parties. This product may contain one or more of the following copyrighted
technologies:
Graph Generation Engine Copyright © 1998-2011. Three D Graphics, Inc. All rights reserved.
Actuate® Formula One. Copyright © 1993-2011 Actuate Corporation. All rights reserved.
XML parser Copyright © 2003-2011 Microsoft Corporation. All rights reserved.
Xalan XSLT processor. Copyright © 1999-2011. The Apache Software Foundation. All rights reserved.
Xerces XML parser. Copyright © 1999-2011. The Apache Software Foundation. All rights reserved.
FOP XSL formatting objects. Copyright © 2004-2011. The Apache Software Foundation. All rights reserved.
Portions of Intelligence Server memory management Copyright © 1991-2011 Compuware Corporation. All rights reserved.
ASIHTTPRequest library. Copyright © 2007-2011, All-Seeing Interactive. All rights reserved.
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)
International Components for Unicode
Copyright © 1999-2011 Compaq Computer Corporation
Copyright © 1999-2011 Hewlett-Packard Company
Copyright © 1999-2011 IBM Corporation
Copyright © 1999-2011 Hummingbird Communications Ltd.
Copyright © 1999-2011 Silicon Graphics, Inc.
Copyright © 1999-2011 Sun Microsystems, Inc.
Copyright © 1999-2011 The Open Group
All rights reserved.
Real Player and RealJukebox are included under license from Real Networks, Inc. Copyright © 1999-2011. All rights reserved.
CONTENTS

About this book ...............................................................................x

How to find business scenarios and examples ........................xi
What’s new in this guide ..........................................................xi
Prerequisites ............................................................................xi
Who should use this guide...................................................... xii
Resources..................................................................................... xii
Documentation........................................................................ xii
Education ................................................................................xx
Consulting .............................................................................. xxi
International support .............................................................. xxi
Technical Support .................................................................. xxi
Feedback ................................................................................... xxvi

1. Architecture Web Services................................................................................. 1

ASP.NET implementation of Web Services................................... 2
J2EE implementation of Web Services.......................................... 3
Web Services in the MicroStrategy architecture............................ 4
Versions of IIS supporting ASP.NET ............................................. 5

2. Installation and Setup Installation locations ...................................................................... 7

ASP.NET Web Services security requirements............................. 8
Access permissions ................................................................. 9
Advanced security settings .................................................... 11
J2EE Web Services security requirements.................................. 11
Verifying your ASP.NET installation ............................................ 13

© 2011 MicroStrategy, Inc. v

Contents MicroStrategy Web Services Administration

Verifying your J2EE installation ................................................... 16

MicroStrategy Office licensing requirement ................................. 20

3. Basic Administrative Editing project sources ................................................................ 22

Operations
Editing ASP.NET configuration settings ...................................... 22
Editing J2EE configuration settings ............................................. 28
View the service definition ........................................................... 33
Test the services.......................................................................... 34
Supporting images in reports and documents ............................. 34
Supporting third-party widget files in dashboard documents ....... 36
Controlling Web Services logs..................................................... 36

4. Application ASP.NET configuration settings .................................................. 39

Configuration and ProcessModel ........................................................................ 40
Tuning for ASP.NET httpRuntime ........................................................................... 43
Authentication and identify settings ....................................... 45
Performance monitoring and tuning............................................. 45
Performance Monitor ............................................................. 45
Basic counters ....................................................................... 47

5. Advanced Setting up SSL for encryption ...................................................... 58

Installations
Web Farm .................................................................................... 64
Web Garden ................................................................................ 67

6. Diagnostics Tools Using event and error logs........................................................... 70

Windows event log................................................................. 70
Windows Web and HTTPERR error logs............................... 71
Java application server error logs................................................ 74
Verifying Web Services availability .............................................. 75
TcpTrace for message analysis................................................... 75
Initializing tcpTrace to intercept and forward messages ........ 76
Configuring MicroStrategy Office to send messages to
tcpTrace ................................................................................. 77
Capturing and viewing messages .......................................... 77
Web Services tracing for ASP.NET message analysis................ 79
Configuring the Java log .............................................................. 79

vi © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Contents

Configuring the ASP.NET log ...................................................... 81

Microsoft debugging tools............................................................ 82

7. Troubleshooting HTTP errors ................................................................................. 84

Key error phrases ........................................................................ 85
Other symptoms .......................................................................... 88
Frequently asked questions......................................................... 89

Glossary ..................................................................................... 91

Index ........................................................................................... 97

© 2011 MicroStrategy, Inc. vii

Contents MicroStrategy Web Services Administration

viii © 2011 MicroStrategy, Inc.

PREFACE

Description of Guide

 This book will no longer be updated. The Web Services API described
in this book has been deprecated, and is included only to support
MicroStrategy Office.

If you are administering MicroStrategy Office, refer to the

MicroStrategy Office User Guide.

If you are developing applications that use MicroStrategy data, it is

recommended that you use the new Web Services SDK. For additional
information, refer to the MicroStrategy Developer Library (MSDL).

This guide is designed to assist administrators who are supporting

MicroStrategy Office and MicroStrategy Web Services, and developers using
MicroStrategy Web Services. It describes the concepts and tasks necessary
for installation, configuration, tuning, and troubleshooting MicroStrategy
Web Services.

MicroStrategy Web Services provides ASP.NET and J2EE Web

Services to support MicroStrategy Office only. If you are developing
applications that use MicroStrategy data, it is recommended that you
use the MicroStrategy Web Services SDK. Refer to the MicroStrategy
Developer Library (MSDL) for information on the Web Services SDK.

The chapters provide information about

• Web Services architecture in both ASP.NET and J2EE implementations

• Installation and setup of Web Services for ASP.NET and J2EE

implementations, including access permissions, security settings, and
verifying your installation

© 2011 MicroStrategy, Inc. ix

Preface MicroStrategy Web Services Administration

• Basic administrative operations, such as editing a project source, editing

configuration settings, viewing a service definition, testing the services,
and controlling Web Services logs

• Application configuration and tuning for ASP.NET, including

configuration settings and Performance Monitor tuning

• Steps for advanced installations, including SSL connectivity, Web Farms,

and Web Gardens

• Information on configuring and working with diagnostic tools, including

event and error logs, tracing, messages, and Microsoft debugging tools

• Common troubleshooting issues and solutions

This guide does NOT cover the following information:

• Installing MicroStrategy Web Services. See the MicroStrategy

Installation and Configuration Guide for information.
• Administering a MicroStrategy Intelligence Server. See the
MicroStrategy System Administrator Guide for information.

• Administering MicroStrategy Web Server. See the MicroStrategy System

Administrator Guide for information.

• Using the MicroStrategy Web Services API. See the MicroStrategy

Developer Library (MSDL) for information.
• Installing and using MicroStrategy Office. See the MicroStrategy Office
online help for information.

About this book

This book is divided into chapters that begin with a brief overview of the
chapter’s content.

Dates in the MicroStrategy Tutorial project are updated to reflect the

current year. The sample documents and images in this guide, as well
as the procedures, were created with dates that may no longer be
available in the Tutorial project. Replace them with the first year of
data in your Tutorial project.

x About this book © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

How to find business scenarios and examples

Within this guide, examples for procedures are provided wherever
practicable.

For examples of reporting functionality, see the MicroStrategy Tutorial,

which is MicroStrategy’s sample warehouse, metadata, and project.
Information about the MicroStrategy Tutorial 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 Modules, which include a set
of precreated sample reports, each from a different business area. Sample
reports present data for analysis in such business areas as financial
reporting, human resources, and customer analysis.

What’s new in this guide

MicroStrategy 9.0
• The Web Services API described in this book has been deprecated. It is
recommended that you use the new Web Services SDK to develop
applications that use MicroStrategy data.
• Take advantage of support for Microsoft Windows IIS 7 and Windows
2008 (see ASP.NET implementation of Web Services, page 2.)

Prerequisites
Before working with this document, you should be familiar with:

• Web Services technologies such as SOAP, WSDL, XML and XSD at a

basic level

• The deployment and operation of websites using ASP.NET and IIS

technologies

© 2011 MicroStrategy, Inc. About this book xi

Preface MicroStrategy Web Services Administration

• The deployment and operation of servlets using J2EE technologies

• MicroStrategy Intelligence Server architecture, deployment, and

operation at a basic level

Who should use this guide

This document is designed for

• MicroStrategy Web Services administrators responsible for configuring

and maintaining Web Services operation

• MicroStrategy Web administrators responsible for configuring and

maintaining the Web server on which MicroStrategy Web Services
executes

• System administrators responsible for configuring and maintaining the

MicroStrategy business intelligence system

• Network administrators who may need to configure network connections

between the system’s components

Resources

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 xviii. Most of these manuals are also
available printed in a bound, soft cover format. To purchase printed
manuals, contact your MicroStrategy account executive or email
documentationfeedback@microstrategy.com.

xii Resources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

• Help: In general, MicroStrategy help provides:

Detailed steps to perform procedures

Descriptions of each option on every software screen

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. For the most
up-to-date translations, refer to the MicroStrategy Knowledge Base.

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.
• MicroStrategy Quick Start Guide

Overview of the installation and evaluation process, and additional

resources.

• Evaluate MicroStrategy for Linux Guide

Evaluate MicroStrategy for Linux, in a Microsoft Windows or Linux

environment, with the MicroStrategy Evaluation Edition Virtual
Appliance. This guide provides all details to download, activate, and
evaluate MicroStrategy software running in a Linux environment.
• MicroStrategy Reporting Suite Quick Start Guide

Evaluate MicroStrategy as a departmental solution. Provides detailed

information to download, install, configure, and use the MicroStrategy
Reporting Suite.

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.

© 2011 MicroStrategy, Inc. Resources xiii

Preface MicroStrategy Web Services Administration

• 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 Desktop 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

Instructions for advanced topics in the MicroStrategy system, building on

information in the Basic Reporting Guide. Topics include reports,
Freeform SQL reports, Query Builder reports, filters, metrics, Data
Mining Services, custom groups, consolidations, and prompts.

• MicroStrategy Report Services Document Creation Guide

Instructions to design and create Report Services documents, building on

information in the Basic Reporting Guide and Advanced Reporting
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, Word, and
Outlook, to analyze, format, and distribute business data.

• MicroStrategy Mobile User Guide

Instructions for using MicroStrategy Mobile to view and analyze data,

and perform other business tasks with MicroStrategy reports and
documents on a mobile device. Covers installation and configuration of
MicroStrategy Mobile and how a designer working in MicroStrategy
Desktop or MicroStrategy Web can create effective reports and
documents for use with MicroStrategy Mobile.

xiv Resources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

• MicroStrategy System Administration Guide Volume 1

Concepts and high-level steps to implement, deploy, maintain, tune, and

troubleshoot a MicroStrategy business intelligence system.

• MicroStrategy System Administration Guide Volume 2

Concepts and high-level steps for using various administrative tools such
as MicroStrategy Command Manager, MicroStrategy Enterprise
Manager, MicroStrategy Integrity Manager, and MicroStrategy Health
Center.

• 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 such as SAP BW, Microsoft
Analysis Services, and Hyperion Essbase into your MicroStrategy projects
and applications.

• MicroStrategy Web Services Administration Guide

This book will no longer be updated. The Web Services API described in
this book has been deprecated, and is included only to support
MicroStrategy Office.

If you are administering MicroStrategy Office, refer to the MicroStrategy

Office User Guide.
If you are developing applications that use MicroStrategy data, it is
recommended that you use the new Web Services SDK. For additional
information, refer to the MicroStrategy Developer Library (MSDL).

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

© 2011 MicroStrategy, Inc. Resources xv

Preface MicroStrategy Web Services Administration

• 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

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 sold as 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.

xvi Resources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

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 using the MicroStrategy Product Manuals

page, as described in Accessing manuals and other documentation
sources, page xviii.

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 ESRI mapping services.

This resource can be accessed using the MicroStrategy Product Manuals

page, as described in Accessing manuals and other documentation
sources, page xviii.

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.

© 2011 MicroStrategy, Inc. Resources xvii

Preface MicroStrategy Web Services Administration

• F1 key: Press F1 to see context-sensitive help that describes each option in

the software window you are currently viewing.

For MicroStrategy Web, MicroStrategy Web Administrator, and

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

Accessing manuals and other documentation sources

The manuals are available from your MicroStrategy disk or the machine
where MicroStrategy was installed.

Adobe Acrobat Reader is required to view these manuals. If you do not

have Acrobat Reader installed on your computer, you can download it
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 installed manuals and other documentation sources on
Windows, page xviii

• To access installed manuals and other documentation sources on UNIX

and Linux, page xix

To access installed manuals and other documentation sources on Windows

1 From the Windows Start menu, choose Programs (or All Programs),
MicroStrategy, 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

xviii Resources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

downloaded. Select Open this file from its current location, and click
OK.

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

To access installed manuals and other documentation sources on UNIX and

Linux

1 Within your UNIX or Linux machine, navigate to the directory where you
installed MicroStrategy. The default location is /opt/MicroStrategy,
or $HOME/MicroStrategy/install if you do not have write access to
/opt/MicroStrategy.

2 From the MicroStrategy installation directory, open the

Documentation 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.

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

© 2011 MicroStrategy, Inc. Resources xix

Preface MicroStrategy Web Services Administration

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
• Text to be entered by the user
Example: Click Select Warehouse.
Example: Type cmdmgr -f scriptfile.scp and press Enter.

italic • New terms defined within the text and in the glossary
• Names of other product manuals
• When part of a command syntax, indicates variable information to be replaced by the
user
Example: The aggregation level is the level of calculation for the metric.
Example: Type copy c:\filename d:\foldername\filename

Courier • Calculations
font • Code samples
• Registry keys
• Path and file names
• URLs
• Messages displayed in the screen
Example: Sum(revenue)/number of months.

+ A keyboard command that calls for the use of more than one key (for example,
SHIFT+F1)

A note icon indicates helpful information for specific situations.

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

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. For a detailed description of education offerings and course
curriculums, visit http://www.microstrategy.com/Education.

xx Resources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

Consulting
MicroStrategy Consulting Services provides proven methods for delivering
leading-edge technology solutions. Offerings include complex security
architecture designs, performance and tuning, project and testing strategies
and recommendations, strategic planning, and more. For a detailed
description of consulting offerings, visit
http://www.microstrategy.com/Consulting.

International support
MicroStrategy supports several locales. Support for a locale typically includes
native database and operating system support, support for date formats,
numeric formats, currency symbols, and availability of translated interfaces
and certain documentation.

MicroStrategy is certified in homogeneous configurations (where all the

components lie in the same locale) in the following languages—English (US),
French, German, Italian, Japanese, Korean, Portuguese (Brazilian), Spanish,
Chinese (Simplified), Chinese (Traditional), Danish, and Swedish. A
translated user interface is available in each of the above languages. For
information on specific languages supported by individual MicroStrategy
system components, see the MicroStrategy readme.

MicroStrategy also provides limited support for heterogeneous

configurations (where some of the components may lie in different locales).
Please contact MicroStrategy Technical Support for more details.

A translated user interface is available in each of the above languages.

Technical Support
If you have questions about a specific MicroStrategy product, you should:

1 Consult the product guides, Help, and readme files. Locations to access
each are described above.

2 Consult the MicroStrategy Knowledge Base online at

https://resource.microstrategy.com/support.

Ayoutechnical administrator in your organization may be able to help

resolve your issues immediately.

© 2011 MicroStrategy, Inc. Resources xxi

Preface MicroStrategy Web Services Administration

3 If the resources listed in the steps above do not provide a solution,

contact MicroStrategy Technical Support directly. To ensure the most
productive relationship with MicroStrategy Technical Support, review the
Policies and Procedures document in your language, posted at
http://www.microstrategy.com/Support/Policies. Refer to the terms of
your purchase agreement to determine the type of support available to
you.

MicroStrategy Technical Support can be contacted by your company’s

Support Liaison. A Support Liaison is a person whom your company has
designated as a point-of-contact with MicroStrategy’s support personnel. All
customer inquiries and case communications must come through these
named individuals. Your company may designate two employees to serve as
their Support Liaisons, and can request to change their Support Liaisons two
times per year with prior written notice to MicroStrategy Technical Support.

It is recommended that you designate Support Liaisons who have

MicroStrategy Administrator privileges. This can eliminate security conflicts
and improve case resolution time. When troubleshooting and researching
issues, MicroStrategy Technical Support personnel may make
recommendations that require administrative privileges within
MicroStrategy, or that assume that the designated Support Liaison has a
security level that permits them to fully manipulate the MicroStrategy
projects and has access to potentially sensitive project data such as security
filter definitions.

Ensure issues are resolved quickly

Before logging a case with MicroStrategy Technical Support, the Support

Liaison may follow the steps below to ensure that issues are resolved quickly:

1 Verify that the issue is with MicroStrategy software and not a third party
software.

2 Verify that the system is using a currently supported version of

MicroStrategy software by checking the Product Support Expiration
Schedule at http://www.microstrategy.com/Support/Expiration.asp.

3 Attempt to reproduce the issue and determine whether it occurs

consistently.

4 Minimize the complexity of the system or project object definition to

isolate the cause.

xxii Resources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

5 Determine whether the issue occurs on a local machine or on multiple

machines in the customer environment.

6 Discuss the issue with other users by posting a question about the issue
on the MicroStrategy Customer Forum at
https://resource.microstrategy.com/forum/.

The following table shows where, when, and how to contact MicroStrategy
Technical Support. If your Support Liaison is unable to reach MicroStrategy
Technical Support by phone during the hours of operation, they can leave a
voicemail message, send email or fax, or log a case using the Online Support
Interface. The individual Technical Support Centers are closed on certain
public holidays.

North America Email: support@microstrategy.com

Web: https://resource.microstrategy.com/support
Fax: (703) 842–8709
Phone: (703) 848–8700
Hours: 9:00 A.M.–7:00 P.M. Eastern Time, Monday–Friday except holidays

EMEA: Email: eurosupp@microstrategy.com

Europe Web: https://resource.microstrategy.com/support
The Middle East Fax: +44 (0) 208 711 2525
The European Technical Support Centre is closed on national public holidays in each country.
Africa
Phone:
• Belgium: + 32 2792 0436
• France: +33 17 099 4737
• Germany: +49 22 16501 0609
• Ireland: +353 1436 0916
• Italy: +39 023626 9668
• Poland: +48 22 321 8680
• Scandinavia & Finland: +46 8505 20421
• Spain: +34 91788 9852
• The Netherlands: +31 20 794 8425
• UK: +44 (0) 208 080 2182
• International distributors: +44 (0) 208 080 2183
Hours:
• United Kingdom: 9:00 A.M.–6:00 P.M. GMT, Monday-Friday except holidays
• EMEA (except UK): 9:00 A.M.–6:00 P.M. CET, Monday-Friday except holidays

© 2011 MicroStrategy, Inc. Resources xxiii

Preface MicroStrategy Web Services Administration

Asia Pacific Email: apsupport@microstrategy.com

Web: https://resource.microstrategy.com/support
Phone:
• Australia: +61 2 9333 6499
• Korea: +82 2 560 6565 Fax: +82 2 560 6555
• Japan: +81 3 3511 6720 Fax: +81 3 3511 6740
• Singapore: +65 6303 8969 Fax: +65 6303 8999
• Asia Pacific (except Australia, Japan, Korea, and Singapore): +86 571 8526 8067 Fax: +86
571 8848 0977
Hours:
• Japan and Korea: 9:00 A.M.–6:00 P.M. JST (Tokyo), Monday-Friday except holidays
• Asia Pacific (except Japan and Korea): 7 A.M.-6 P.M. (Singapore) Monday-Friday except
holidays

Latin America Email: latamsupport@microstrategy.com

Web: https://resource.microstrategy.com/support
Phone:
• LATAM (except Brazil and Argentina): +54 11 5222 9360 Fax: +54 11 5222 9355
• Argentina: 0 800 444 MSTR Fax: +54 11 5222 9355
• Brazil: +55 11 3054 1010 Fax: +55 11 3044 4088
Hours:
• Latin America (except Brazil): 9:00 A.M.–7:00 P.M. (Buenos Aires), Monday-Friday except
holidays
• Brazil: 9 A.M. - 6 P.M. (São Paulo), Monday–Friday except holidays

Support Liaisons should contact the Technical Support Center from which
they obtained their MicroStrategy software licenses or the Technical Support
Center to which they have been designated.

Required information when calling

When contacting MicroStrategy Technical Support, please provide the

following information:
• Personal information:

Name (first and last)

Company and customer site (if different from company)

Contact information (phone and fax numbers, e-mail addresses)

• Case details:

Configuration information, including MicroStrategy software

product(s) and versions

xxiv Resources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Preface

Full description of the case including symptoms, error messages(s),

and steps taken to troubleshoot the case thus far

• Business/system impact

If this is the Support Liaison’s first call, they should also be prepared to
provide the following:

• Street address

• Phone number

• Fax number

• Email address

To help the Technical Support representative resolve the problem promptly

and effectively, be prepared to provide the following additional information:

• Case number: Please keep a record of the number assigned to each case
logged with MicroStrategy Technical Support, and be ready to provide it
when inquiring about an existing case

• Software version and product registration numbers of the MicroStrategy

software products you are using

• Case description:

What causes the condition to occur?

Does the condition occur sporadically or each time a certain action is

performed?
Does the condition occur on all machines or just on one?

When did the condition first occur?

What events took place immediately prior to the first occurrence of

the condition (for example, a major database load, a database move,
or a software upgrade)?
If there was an error message, what was its exact wording?

What steps have you taken to isolate and resolve the issue? What were
the results?

• System configuration (the information needed depends on the nature of

the problem; not all items listed below may be necessary):

Computer hardware specifications (processor speed, RAM, disk space,

and so on)

© 2011 MicroStrategy, Inc. Resources xxv

Preface MicroStrategy Web Services Administration

Network protocol used

ODBC driver manufacturer and version

Database gateway software version

(For MicroStrategy Web-related problems) browser manufacturer

and version

(For MicroStrategy Web-related problems) Web server manufacturer

and version

If the issue requires additional investigation or testing, the Support Liaison

and the MicroStrategy Technical Support representative should agree on
certain action items to be performed. The Support Liaison should perform
any agreed-upon actions before contacting MicroStrategy Technical Support
again regarding the issue. If the Technical Support representative is
responsible for an action item, the Support Liaison may call MicroStrategy
Technical Support at any time to inquire about the status of the issue.

Feedback
Please send any comments or suggestions about user documentation for
MicroStrategy products to:

documentationfeedback@microstrategy.com

Send suggestions for product enhancements to:

support@microstrategy.com

When you provide feedback to us, please include the name and version of the
products you are currently using. Your feedback is important to us as we
prepare for future releases.

xxvi Feedback © 2011 MicroStrategy, Inc.

 1
1. ARCHITECTURE

Introduction

MicroStrategy Web Services provides ASP.NET and J2EE Web Services

support to the MicroStrategy Office product. MicroStrategy Web Services has
also been tested with .NET and Java Web Services development tools
supporting C#, VB.NET, and Java languages.

MicroStrategy Web Services provides ASP.NET and J2EE Web

Services to support MicroStrategy Office only. If you are developing
applications that use MicroStrategy data, it is recommended that you
use the MicroStrategy Web Services SDK. Refer to the MicroStrategy
Developer Library (MSDL) for information on the Web Services SDK.

Web Services
XML Web Services provides remote access to processes and data using open
Web standards. It can be a form of remote procedure call (RPC) or
messaging, but it is not tied to any company’s proprietary standards.

© 2011 MicroStrategy, Inc. Web Services 1

 1 Architecture MicroStrategy Web Services Administration

Typically, XML Web Services is shortened to Web Services and assumes the
use of XML to exchange messages. The advantages of Web Services
compared to earlier RPC or messaging technologies include the following:

• No dependence on proprietary technologies

• Access to technology from multiple platforms and languages

• ability to exchange messages through firewalls

• Readable messages using XML format as opposed to binary or text

formats that are not self-descriptive.

The following diagram shows two clients talking to a Web Server using Web
Services messages:

The diagram shows that the XML Web Services is carried to and from the
Web Server over HTTP. Client A creates the XML messages directly. Client B
uses a language library, or proxy, which is generated by a programmer
development environment. This proxy provides functions in the language of
choice that represent the Web Services methods. Internally, the proxy
translates between the XML Web Service messages and the library functions.

ASP.NET implementation of Web Services

ASP.NET implements Web Services using its handler technology. Handlers
are modules that are registered to handle certain Web resources by name or
extension. In the case of Web Services, resources ending with asmx are
handed off to the Web Services handler. A Web Services class defined in an

2 ASP.NET implementation of Web Services © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Architecture 1

asmx file is derived from the .NET class

System.Web.Services.WebService that provides the functionality to
support the handler translation of designated methods in these new Web
Services classes to and from XML messages.

The relationship of these components is shown in the following diagram:

The diagram above shows the ASP.NET architecture in an IIS 5.1 ASP.NET
implementation provided in a Windows XP server environment. The IIS 6.0
ASP.NET environment provided by a Windows 2003 server environment is
similar. A key difference is that IIS 6.0 uses a device driver, HTTP.SYS,
instead of IIS for request and response communications support.

IIS7.0, used in Windows 2008, is a more open, modular environment. In IIS

7.0, HTTP communications is still supported by HTTP.SYS and is used by
MicroStrategy Web Services, though Web Services can be configured to use
other protocol listeners.

J2EE implementation of Web Services

The J2EE implementation of MicroStrategy Web Services uses the Apache
Axis2 SOAP engine implemented as a J2EE servlet and a supporting class
infrastructure. Axis2 implements Web Services using a handler technology
with a chaining framework.

Specifically, messages are received by a listener implemented as a servlet. As

shown in the diagram below, the messages are received by the HTTP Server
and then handed off to the Axis servlet via the servlet container. The
messages are then processed by the SOAP engine and ultimately passed to
the Service. When the Service completes processing, it returns results as Java

© 2011 MicroStrategy, Inc. J2EE implementation of Web Services 3

 1 Architecture MicroStrategy Web Services Administration

classes to the SOAP engine. The engine ultimately translates those classes
back to messages which are transported out as SOAP responses over HTTP.
The relationship of these components is shown in the following diagram:

The HTTP Server/servlet container combination could be Apache Server

with Tomcat or IBM WebSphere, for example.

Web Services in the MicroStrategy architecture

MicroStrategy Office communicates with MicroStrategy Intelligence Server
using MicroStrategy Web Services. The following diagram shows the
communications path between these products in the ASP.NET environment.

4 Web Services in the MicroStrategy architecture © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Architecture 1

MicroStrategy Office submits and consumes Web Services messages to and

from MicroStrategy Web Services (MWS). These messages are received by
the .NET classes. The core service processing for each of these methods is
performed by the MWS Objects, which are Java classes that implement Web
Services functions using MicroStrategy WebObjects API. To communicate
between the .NET classes and the Java classes, .NET JNI Bridge classes are
used. The Java WebObjects communicate over the network with one or more
Intelligence Servers.

The next diagram shows the communications path in the J2EE environment.

In this flow, the .NET classes and JNI layers are replaced with a single set of
MicroStrategy Web Services Java API classes. These classes are the target
and source of Java class to XML translations used by the SOAP engine. The
bulk of Web Services processing is performed by the MWS objects and is
shared between the ASP.NET and J2EE implementations.

For detailed information on how jobs are processed within MicroStrategy,

see the System Administration Guide, Vol. 1.

Versions of IIS supporting ASP.NET

Microsoft ASP.NET is a plug-in environment that runs in the Internet
Information Services environment on Microsoft Windows XP, 2003, and
2008 operating systems. When ASP.NET is installed on Windows XP, it uses
tinetinfo.exe to handle protocol messaging. In Windows 2003 and 2008,
ASP.NET is enabled via the Manage Your Computer wizard, and messages
are processed by http.sys.

Windows XP is supported for demonstration purposes only.

MicroStrategy strongly recommends against running MicroStrategy
Web Services on Windows XP in a production environment.

© 2011 MicroStrategy, Inc. Versions of IIS supporting ASP.NET 5

 1 Architecture MicroStrategy Web Services Administration

The IIS versions for different environments are as follows:

• 6.0 on Windows XP

• 6.0 on Windows 2003

• 7.0 on Windows 2008

.NET also has multiple versions; versions 2.0 (32-bit and 64-bit) and
3.0 (32-bit and 64-bit) are supported for use with MicroStrategy Web
Services.

6 Versions of IIS supporting ASP.NET © 2011 MicroStrategy, Inc.

 2
2. INSTALLATION AND SETUP

Introduction

This chapter provides additional information on installation and setup of

MicroStrategy Web Services in both the ASP.NET and J2EE environments. It
its intended to be used in conjunction with the MicroStrategy Installation
and Configuration Guide. The information in this chapter helps you
properly configure security for Web Services and provides a series of steps to
verify that the installation is working.

MicroStrategy Web Services provides ASP.NET and J2EE Web

Services to support MicroStrategy Office only. If you are developing
applications that use MicroStrategy data, it is recommended that you
use the MicroStrategy Web Services SDK. Refer to the MicroStrategy
Developer Library (MSDL) for information on the Web Services SDK.

Installation locations
MicroStrategy Web Services (MWS) is installed as part of the master
MicroStrategy installation. See the MicroStrategy Installation and
Configuration Guide for details on how to use the installation utility.

© 2011 MicroStrategy, Inc. Installation locations 7

 2 Installation and Setup MicroStrategy Web Services Administration

By default, MWS for ASP.NET is installed in the following directory and

virtual directory during a Windows platform installation:

• Directory: c:\Program Files\MicroStrategy\Web Services

• Virtual directory: MicroStrategyWS

For J2EE, the war file used for deployment are installed during platform
installation. You will find the file MicroStrategyWS.war in the following
directory :

• Directory: c:\Program Files\MicroStrategy\Web Services

J2EE

The procedure used to deploy the war file to the target J2EE server depends
on the specific server. The target directory for installation depends on the
platform.

ASP.NET Web Services security requirements

To access the Web Services, Windows NT authentication is required by
default. This means that the Web server will request and authenticate
credentials from your client computer when you access Web Services either
directly with a browser or via a program client such as MicroStrategy Office.
In the Windows NT environment, your credentials consist of your domain
name, user name, and a password. If you cannot be authenticated, you
trigger an HTTP 401 (Access Denied) response from the Web server. A client
such as MicroStrategy Office can intercept this error and allow you to log on
and try another set of credentials (domain, username, and password).

To achieve this configuration, settings in the Web Services web.config file

interact with settings made using Internet Information Systems (IIS)
Manager. The web.config file, which is in the Web Services virtual directory,
has the following settings:
<authentication mode=“Windows” />

<identity impersonate=“true” />

The settings above, which are in the <system.web> element, indicate that the
Web Services will use Windows authentication and that the Web Services
code will impersonate the calling user. This means that once a user passes
authentication tests, that user must be authorized to execute the code and
access its resources.

8 ASP.NET Web Services security requirements © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Installation and Setup 2

In conjunction with the above settings, IIS Manager is also set to use
Integrated Windows Authentication. In the Authentication Methods dialog
box, Anonymous Access is turned off and Integrated Windows
Authentication is turned on. The user must have the appropriate
authorization for necessary resources in order to run, as discussed above.

Access permissions
The following table shows the types of access permissions that ASP.NET in
general and ASP.NET Web Services must have in order to access the listed
locations:
Location Access Type Account Comments

installroot\ASP.NET Read/write Process or configured The location for dynamically compiled

Temporary Files impersonation files. Beneath this location, application
code generation takes place in a discrete
directory for each application. The root
location can be configured using the
tempDir attribute of the <compilation>
section.

systemroot\ Read Process or configured The location of the global assembly cache.
assembly impersonation

systemroot\ Read Process Contains system DLLs loaded by the .NET

system32 Framework.

systemroot\temp Read/write/ Process For Web Services support.

delete

userprofile directory Read/write Process Used by the global assembly cache lock
files and the common language runtime
security configuration caching mechanism.
If the user profile directory for the account
does not exist, ASP.NET uses the default
userprofile directory.

application directory Read Process or configured The location for application files.
impersonation

installroot hierarchy Read Process or configured ASP.NET must be able to access the
impersonation system assemblies referenced in the
machine.config file in the config
subdirectory under installroot.

Default Web site Read Process For file change notification monitoring.
monitoring

© 2011 MicroStrategy, Inc. ASP.NET Web Services security requirements 9

 2 Installation and Setup MicroStrategy Web Services Administration

Additionally, the following table shows a unique MWS requirement:

Location Access Type Account Comments

application directory Modify/read & execute Process The .NET application log is created and
list folder contents/write updated in this directory.

In“Process”
the Account column in the tables above, the account is either
or “Process or configured impersonation”. The Process
account depends on which server platform Web Services is installed
and how it is configured.

ASP.NET adds the ASPNET user that runs the ASP.NET worker process. On
a Windows XP system, this process is aspnet_wp.exe. On a Windows 2003 or
2008 system, the process is w3wp.exe.

To support the above requirements, the following authorizations for MWS

are added during installation:

• Windows XP: The following authorizations are added to the Web

Services application directory:

Account Access Type

Everyone • Modify
• Read & Execute
• List Folder Contents
• Read/Write

Users • Modify
• Read & Execute
• List Folder Contents

Normally, the Users group includes ASPNET and all authenticated users.
The Everyone group includes all authenticated users.

• Windows 2003/2008: MWS is configured to run in a separate application

pool that is run under the System Account. The name of the application
pool is MicroStrategyWebServicesPool.

Be aware that authorizations required by ASP.NET depend on the default

authorizations. If these have been modified, the application may fail with a
security-derived error. However, it may not be obvious that security is the
problem. The failure may be due to an assembly binding error or a Resource
Not Found error.

10 ASP.NET Web Services security requirements © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Installation and Setup 2

If you encounter or suspect security issues, you can set up your Web Services
to use Anonymous access. In the Authentication Methods dialog box, turn on
Anonymous authentication and provide a user name and password that meet
the above requirements.

Advanced security settings

When viewing security settings, you may need to consider the Advanced
settings. You can navigate to the Advanced security settings from within
Windows Explorer.

To view advanced permissions

1 Right-click on the Web Services directory. The Context Menu opens.

2 Click Properties. The Web Services Properties dialog box opens.

3 Click Advanced. The Access Control Settings for Web Services dialog box
opens.

4 Select one of the entries, such as Everyone, and click View/Edit. The
Permission Entry for Web Services dialog box opens. A detailed list of
permissions based on your selection is displayed.

J2EE Web Services security requirements

To access Web Services in the J2EE environment, you can configure your
Web Services for an HTTP Authentication protocol, such as basic
authentication. Part of this configuration involves proper security setup of
your application server and part is a generic configuration for a J2EE servlet.

The following assumes that you have created the role user1 and assigned an
account to that role using the user account management facility of the
application server. Add the following entries to the web.xml file as the last
entries in the <web-app> element to configure basic authentication for the
application and provide access to the defined role:
<!-- Define a Security Constraint on this Application -->

<security-constraint>

© 2011 MicroStrategy, Inc. J2EE Web Services security requirements 11

 2 Installation and Setup MicroStrategy Web Services Administration

<web-resource-collection>

<web-resource-name>mstrws application</web-resource-name>

<url-pattern>/*</url-pattern>

</web-resource-collection>

<auth-constraint>

<!-- NOTE: This role is not present in the default users file -->

<role-name>user1</role-name>

</auth-constraint>

</security-constraint>

<!-- Define the Login Configuration for this Application -->

<login-config>

<auth-method>BASIC</auth-method>

<realm-name>MSTRWS Application</realm-name>

</login-config>

<!-- Security roles referenced by this web application -->

<security-role>

<description>

The role that is required to log in to the Manager Application

</description>

<role-name>manager</role-name>

</security-role>

The <login-config> element contains the element <auth-element> which is

used to set the authentication method. It also allows you to scope your
authentication with the <realm-name> which you can define for your
purpose.

12 J2EE Web Services security requirements © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Installation and Setup 2

Verifying your ASP.NET installation

After installation, you can verify that MWS is properly configured by using
your browser. The following procedure assumes you selected the default
virtual directory location during installation.

To verify installation

1 On the machine on which you installed MicroStrategy Web Services, type

http://localhost/MicroStrategyWS/MSTRWS.asmx in your
browser. An output similar to the following should appear:

2 In the application directory, locate the file named projectsources.xml.

This file contains a list of all MicroStrategy servers visible to Web
Services. Assuming you selected the default directories during
installation, this file is located at C:\Program Files\
MicroStrategy\Web Services. By default, this file contains one

© 2011 MicroStrategy, Inc. Verifying your ASP.NET installation 13

 2 Installation and Setup MicroStrategy Web Services Administration

definition that works if you have installed both Web Services and
Intelligence Server on the same machine. This file contains the following
content:
<?xml version=”1.0” ?>
<1 - -
This file contains the list of project sources supported by the
MicroStrategy Web Services product

The structure of this file is:

<ProjectSources>
<ProjectSource>
<ProjectSourceName>Name</ProjectSourceName>
<ServerName>Name</ServerName>
<AuthMode>MWSStandard/MWSNTCredential/WMWSPassThru/MWSAnonymous/MWSLDAP
/MWSWarehousePassThru/MWSSimpleSecurityPlugIn/MWSIntegrated</AuthMode>
<MaxPooledConnections>Integer</MaxPooledConnections>
<PortNumber>Integer</PortNumber>
</ProjectSource>
...
</ProjectSources>

ProjectSourceName can be any name chosen by the user.

It is associated with the iServer to be used as a project source, and is
a mandatory field.

ServerName is the name of the iServer to be used as a project source, and

is a mandatory field.

AuthMode designates which authentication mode will be used to connect to

the associated iServer, and is a mandatory field.

PortNumber designates the port on which the iServer will be contacted. A

value of zero (0) defaults the port number to 34952, which is the default
iServer port. This field is not mandatory. If this field is missing, a
value of zero (0) is used.

MaxPooledConnections designates the number of available connections that

the associated iServer will provide for connecting users. It is set upon
first connection to a specific iServer. This field is not mandatory. If
this field is missing, a value is chosen form the web.config file
configuration parameter.

-->

<ProjectSources>
<ProjectSourceName>MicroStrategy Tutorial
</ProjectSourceName>
<ServerName>localhost</ServerName>
<AuthMode>MWSStandard</AuthMode>
<PortNumber>0</PortNumber>
<MaxPooledConnections>100</MaxPooledConnections>
</ProjectSource>

<!-- You can add another data source here. For example, <ProjectSource>
<ProjectSourceName>Local Connection</ProjectSourceName>
<ServerName>BURLAKLAP</ServerName>
<AuthMode>MWSNTCredential</AuthMode>

14 Verifying your ASP.NET installation © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Installation and Setup 2

<MaxPooledConnections>150</MaxPooledConnections>
</ProjectSource>
-->
</ProjectSources>

Add a new project source definition

3 You can add a new project source definition to this file. For example, if
you have a server with a DNS name of Stealth, it uses Windows NT
authentication, and you would like to name it My Server with default port
and connection pool settings, add the following:
<ProjectSource>
<ProjectSourceName>My Server</ProjectSourceName>
<ServerName>Stealth</ServerName>
<AuthMode>MWSNTCredential</AuthMode>
</ProjectSource>

4 Once you have made the changes and saved the file, return to the
MSTRWS.asmx page. On the same machine on which Web Services is
installed, in the browser click the GetProjectSources API link to display
the documentation/test page for this service API, as shown below:

© 2011 MicroStrategy, Inc. Verifying your ASP.NET installation 15

 2 Installation and Setup MicroStrategy Web Services Administration

5 Click Invoke. An XML response appears that lists the sources in your
projectsources.xml file, as shown below:

6 Once you have verified access and operation with GetProjectSources, you
can test operations with an Intelligence Server using TestService. On the
MSTRWS.asmx Web page, click the TestService link.

7 Enter a MicroStrategy server name, a project name, and a login and

password in the designated fields. Click Invoke.

• If TestService succeeds, a screen similar to the following appears:

• If TestService fails, a browser error page appears.

When you install a client such as MicroStrategy Office, you must use the URL
for your server. If the server you have installed is <servername>, then the
default URL is http://<servername>/MicroStrategyWS/
MSTRWS.asmx.

Verifying your J2EE installation

After installation, you can verify that MWS J2EE is properly configured by
using your browser. The following procedure assumes you accepted the
default configuration during installation for a Tomcat installation.

16 Verifying your J2EE installation © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Installation and Setup 2

To verify installation

1 On the machine on which you installed MicroStrategy Web Services, type

http://localhost:8080/MicroStrategyWS/in your browser. The
following output should appear:

2 In the application directory, locate the file named projectsources.xml. (In

Tomcat, the default location is webapps\MicroStrategyWS.) This file
contains a list of all MicroStrategy servers visible to Web Services. By
default, this file contains one definition that works if you have installed
both Web Services and Intelligence Server on the same machine. This file
contains the following content:
<?xml version=”1.0” ?>
<1 - -
This file contains the list of project sources supported by the
MicroStrategy Web Services product

The structure of this file is:

<ProjectSources>
<ProjectSource>
<ProjectSourceName>Name</ProjectSourceName>
<ServerName>Name</ServerName>
<AuthMode>MWSStandard/MWSNTCredential/WMWSPassThru/MWSAnonymous/MWSLDAP
/MWSWarehousePassThru/MWSSimpleSecurityPlugIn/MWSIntegrated</AuthMode>
<MaxPooledConnections>Integer</MaxPooledConnections>
<PortNumber>Integer</PortNumber>

© 2011 MicroStrategy, Inc. Verifying your J2EE installation 17

 2 Installation and Setup MicroStrategy Web Services Administration

</ProjectSource>
...
</ProjectSources>

ProjectSourceName can be any name chosen by the user.

It is associated with the iServer to be used as a project source, and is
a mandatory field.

ServerName is the name of the iServer to be used as a project source, and

is a mandatory field.

AuthMode designates which authentication mode will be used to connect to

the associated iServer, and is a mandatory field.

PortNumber designates the port on which the iServer will be contacted. A

value of zero (0) defaults the port number to 34952, which is the default
iServer port. This field is not mandatory. If this field is missing, a
value of zero (0) is used.

MaxPooledConnections designates the number of available connections that

the associated iServer will provide for connecting users. It is set upon
first connection to a specific iServer. This field is not mandatory. If
this field is missing, a value is chosen form the web.config file
configuration parameter.

-->

<ProjectSources>
<ProjectSourceName>MicroStrategy Tutorial
</ProjectSourceName>
<ServerName>localhost</ServerName>
<AuthMode>MWSStandard</AuthMode>
<PortNumber>0</PortNumber>
<MaxPooledConnections>100</MaxPooledConnections>
</ProjectSource>

<!-- You can add another data source here. For example, <ProjectSource>
<ProjectSourceName>Local Connection</ProjectSourceName>
<ServerName>BURLAKLAP</ServerName>
<AuthMode>MWSNTCredential</AuthMode>
<MaxPooledConnections>150</MaxPooledConnections>
</ProjectSource>
-->
</ProjectSources>

Add a new project source definition

3 You can easily add a new project source definition to this file. For
example, if you have a server with a DNS name of Stealth, it uses
Standard authentication, and you would like to name it My Server with
default port and connection pool settings, add the following:
<ProjectSource>
<ProjectSourceName>My Server</ProjectSourceName>
<ServerName>Stealth</ServerName>
<AuthMode>MWSStandard</AuthMode>
</ProjectSource>

18 Verifying your J2EE installation © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Installation and Setup 2

4 Once you have made the changes and saved the file, return to the
MicroStrategyWS page. Click Validate to determine whether MWS has
access to all of the runtime files required. You should see a display similar
to the following:

If any Needed Components are missing or incompatible, you must correct

the situation before proceeding.

5 On the same machine on which Web Services is installed, you can enter
the following values:
• Web Services URL:
http://localhost:8080/MicroStrategyWS/services/MSTRWSJ

• Intelligence Server: localhost

• ProjectName: MicroStrategy Tutorial

• Login: Administrator

• Password: <blank>

Then click Run.

© 2011 MicroStrategy, Inc. Verifying your J2EE installation 19

 2 Installation and Setup MicroStrategy Web Services Administration

• If TestService succeeds, a screen similar to the following appears:

• If TestService fails, you only see the text “TestService Results” with
the exception that occurred. Check the error logs for more details.

When you install a client such as MicroStrategy Office, you must use the URL
for your server. The default URL is
http://<servername>:8080/MicroStrategyWS/services/
MSTRWSJ

where <servername> is the server you have installed.

MicroStrategy Office licensing requirement

MicroStrategy Web Services can detect when MicroStrategy Office is the
client. In this case, the user must have MicroStrategy Office privileges on the
Intelligence Server for which a connection is requested. If privileges are not
present, the Web Services request fails.

20 MicroStrategy Office licensing requirement © 2011 MicroStrategy, Inc.

 3
3. BASIC ADMINISTRATIVE
OPERATIONS

Introduction

The following administrative tasks described in this chapter are either

required or useful at one time or another with MicroStrategy Web Services:

• Editing project sources, page 22

• Editing ASP.NET configuration settings, page 22

• Editing J2EE configuration settings, page 28

• View the service definition, page 33

• Test the services, page 34

• Supporting images in reports and documents, page 34

• Supporting third-party widget files in dashboard documents, page 36

• Controlling Web Services logs, page 36

© 2011 MicroStrategy, Inc. 21

 3 Basic Administrative Operations MicroStrategy Web Services Administration

Editing project sources

A project source identifies an Intelligence Server with a specific type of
authentication. All projects defined on this Intelligence Server are available
for use with MicroStrategy Web Services (MWS). In the MWS application
directory, the file named projectsources.xml contains a list of all
MicroStrategy servers visible to Web Services. If you have selected the
default directories during ASP.NET installation, this file is located at
C:\Program Files\MicroStrategy\Web Services. With ASP.NET
this file can be viewed in your browser with the following URL:
http://<hostname>/MicroStrategyWS/ProjectSources.xml.

For a J2EE installation, the projectsources.xml file is in the

MicroStrategyWS application directory. With J2EE this file can be viewed in
your browser with the following URL:
http://<hostname>:8080/MicroStrategyWS/
ProjectSources.xml.

This file contains one definition by default that works if you have installed
both MWS and Intelligence Server on the same machine. The contents of this
file can be seen in Chapter 2 in either the Verifying your ASP.NET
installation, page 13 section or the Verifying your J2EE installation,
page 16 section. Steps to add a new project source definition to this file can
be found in Chapter 2, Installation and Setup.

If you change the project source and you are using MicroStrategy Office, you
must restart your client application (such as Microsoft Excel, Word, or
PowerPoint) to see the new project sources. For ASP.NET Web Services, the
list of new sources is available the next time you call the GetProjectSources
method. For J2EE Web Services, you must restart the MWS application. For
a custom client, any project source change is immediately available.

Editing ASP.NET configuration settings

MicroStrategy Web Services (MWS) for ASP.NET maintains a list of custom
settings in the <appSettings> section of the web.config file. This file is
located in the MWS application directory. If you selected the default
directories during installation, this file is located at C:\Program
Files\MicroStrategy\Web Services. Unlike the projectsources.xml file, this

22 Editing project sources © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

file cannot be viewed with a browser. To view and change this file, open this
file in an editor on the server machine. Only administrators should change
this file.

Any changes you make to the web.config file will cause the application
to recompile, which will impact performance if performed too
frequently. Additionally, if there is a syntax error of any kind, the
application will fail when accessed.

<appSettings> is a child element in the <configuration> root element and

can be found at the end of the default web.config file. The following is the
default content for an ASP.NET MWS implementation:
<appSettings>

<!-- IMAGESUBDIRECTORY identifies the subdirectory under

the installation directory containing MicroStrategy Web
Services specific image files.

-->

<add key="IMAGESUBDIRECTORY" value="images" />

<!-- FLASHSUBDIRECTORY identifies the subdirectory under the

installation directory containing swf files for Flash View
Mode support.

-->

<add key="FLASHSUBDIRECTORY" value="swf" />

<!-- BUNDLESUBDIRECTORY identifies the subdirectory under

the installation directory containing date and string resource
bundles for Flash View Mode support.

-->

<add key="BUNDLESUBDIRECTORY"

value="resBundles" />

<!-- STRINGSBUNDLEPREFIX identifies the file name prefix

for the strings resource bundle used in Flash View Mode
support.

-->

© 2011 MicroStrategy, Inc. Editing ASP.NET configuration settings 23

 3 Basic Administrative Operations MicroStrategy Web Services Administration

<add key="STRINGSBUNDLEPREFIX"
value="DashboardViewerBundle_" />

<!-- DATESBUNDLEPREFIX identifies the file name prefix for

the dates resource bundle used in Flash View Mode support.

-->

<add key="DATESBUNDLEPREFIX" value="DashboardDatesBundle_"

/>

<!-- DASHBOARDVERSION allows the Flash dashboard swf

version to be set to something other than the default build
version.

<add key="DASHBOARDVERSION" value="9.x.yyy.xxx" />

-->

<!-- BLOCKOFFICEUPDATE will prevent Office Install

executable information from being sent to the client.

<add key="BLOCKOFFICEUPDATE" value="true" />

-->

<!-- OFFICEINSTALLURL allows the admin to set an

alternate location for the Office install executable.

If the executable is remote to the server

then the OFFICEINSTALLVERSION config parameter must also be
set.

For example:
"file://ServerOrRemoteHost/fileShare/Setup.exe"On server
fileshare
"http://ServerOrRemoteHost/MicroStrategyWS/Office/Setup.exe"
From another installation

...where fileShare is a directory setup to be

shareable by local and remote hosts, and MicroStrategyWS is
mapped to a virtual directory.

Be aware that the URL is relative to the

client, so a reference to "localhost" will refer to the
client.

24 Editing ASP.NET configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

<add key="OFFICEINSTALLURL" value="" />

-->

<!-- OFFICEINSTALLVERSION can be used to identify

the version of the Office install executable, if the file
location is not accessible from the web server. Normally, the
version is obtained by querying the file.

<add key="OFFICEINSTALLVERSION" value="

9.x.yyy.zzz" />

-->

<!-- OFFICEINSTALLCONFIGFILELOC allows the admin to

set an alternate location for the default

MicroStrategy Office config file that is

supplied on the web server. The default location for this file
is:

"C:/Program
Files/MicroStrategy/Web Services/Office/moimain.dll.config"

or:

"../WebServiceRootPath/Office/moimain.dll.config"

The location can be specified as:

"Office/moimain.dll.config" relative
path under web service root

"C:/OtherDirectory/moimain.dll.config"absolute path on web

server

"//ServerName/FileShare/OtherDirectory/moimain.dll.config"
network path

"file://ServerName/FileShare/moimain.dll.config"file URL

© 2011 MicroStrategy, Inc. Editing ASP.NET configuration settings 25

 3 Basic Administrative Operations MicroStrategy Web Services Administration

<add key="OFFICEINSTALLCONFIGFILELOC"
value="Office/moimain.dll.config" />

-->

<!-- Additional entries for JVM Classpath.

Each directory path, or JAR file spec should be

separated by a semi-colon ";". No environment variable
substitution is done, so full paths are needed.

(eg. "C:/ClassFiles;C:/MWSVirtualDir/MWS.jar")

Note that the web service root path is

automatically added to the classpath. Also, any newly
specified classpath is simply added to the front of the
existing classpath specified in the registry.

-->

<add key="JVMCLASSPATH" value="" />

<!-- Trace file setup.

If TRACE is set to ON, trace files will grow to the

specified size(MAXTRACEFILESIZE) before being backed up. Once
the specified number of backup files have been created
(NUMBACKUPTRACEFILES),the first backup file will be
overwritten, and so on, in a circular fashion. The trace file
will be named MWSTraceLog.txt and will be located at the web
service root filepath, along with its backup files ie.
C:\Program Files\MicroStrategy\Web Services).

-->

<add key="TRACE" value="ON" />

<!-- Specified in K bytes -->

<add key="MAXTRACEFILESIZE" value="1024" />

<add key="NUMBACKUPTRACEFILES" value="4" />

<!-- Web Admin config settings

26 Editing ASP.NET configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

SERVERBUSYTIMEOUT and REQUESTTIMEOUT are set at

application startup and apply to all connections.
REPORTSTATEWORKINGSET is set at each session connect.
MAXPOOLEDCONNECTIONS is set at connection time for each
server. This value in web.config is only used as a default
when the projectsource.xml file value for
MaxPooledConnections for a specific projectsource is missing.

-->

<!-- Specified in seconds -->

<add key="SERVERBUSYTIMEOUT" value="300" />

<!-- Specified in seconds -->

<add key="REQUESTTIMEOUT" value="300" />

<!-- Number of session cached report states. -->

<add key="REPORTSTATEWORKINGSET" value="5" />

<add key="MAXPOOLEDCONNECTIONS" value="100" />

</appSettings>

The following table presents each of the settings that appear in the
web.config file (shown above) and information about their values:
Setting Description

TRACE If set to ON, trace files grow to the specified size

(MAXTRACEFILESIZE) before being backed up. Once the specified
number of backup files have been created
(NUMBACKUPTRACEFILES), the first backup file is overwritten, and so
on in a circular fashion. The trace file (MWSTraceLog.txt) is located at
the Web root, along with its backup files.

MAXTRACEFILESIZE Size to which each trace file will grow before being archived.

NUMBACKUPTRACEFILES Number of archived trace files that are preserved.

SERVERBUSYTIMEOUT Amount of time an operation waits for Intelligence Server, if busy.

REQUESTTIMEOUT Amount of time the underlying MicroStrategy Web SDK called during a
Web Services operation waits for a response from Intelligence Server.

MAXPOOLEDCONNECTIONS Maximum number of connections that will be opened in a pool between

the Web Services computer and a given Intelligence Server.

IMAGESUBDIRECTORY Identifies the subdirectory under the installation directory containing

MicroStrategy Web Services specific image files.

© 2011 MicroStrategy, Inc. Editing ASP.NET configuration settings 27

 3 Basic Administrative Operations MicroStrategy Web Services Administration

Setting Description

FLASHSUBDIRECTORY Identifies the subdirectory under the installation directory containing swf
files for Flash View Mode support.

BUNDLESUBDIRECTORY Identifies the subdirectory under the installation directory containing date
and string resources bundles for Flash View Mode support.

STRINGSBUNDLEEPREFIX Identifies the file name prefix for the strings resource bundle used in
Flash View Mode support.

DATESBUNDLEPREFIX Identifies the file name prefix for the dates resource bundle used in
Flash View Mode support.

DASHBOARDVERSION Allows the Flash dashboard swf version to be set to something other
than the default build version.

BLOCKOFFICEUPDATE A value of “true” prevents Office Install executable information from

being sent to the client.

OFFICEINSTALLURL Allows the administrator to set an alternate location for the Office install
executable. If the executable is remote to the server, then the
OFFICEINSTALLVERSION config parameter must also be set.

For a server fileshare, use:

File://<serverOrRemoteHost>/fileShare/Setup.exe
For another installation, use:
HTTP://<ServerOrRemoteHost>/MicroStrategyWS/Office/
Setup.exe

Be aware that the URL is relative to the client, so a reference to

LocalHost will refer to the client.

OFFICEINSTALLVERSION Can be used to identify the version of the Office install executable, if the
file location is not accessible from the web server. Normally, the version
is obtained by querying the file.

Editing J2EE configuration settings

MicroStrategy Web Services (MWS) for J2EE maintains a list of custom
settings in the MWSConfig.properties file which are located in the
MicroStrategyWS application directory. If you keep the default configuration
during deployment, this file is located in the webapps/MicroStrategyWS
directory.

28 Editing J2EE configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

Unlike the projectsources.xml file, this file cannot be viewed with a

browser. To view and change this file, open this file in an editor on the server
machine. Only administrators should change this file.

affect
Any changes you make to the MWSConfig.properties file do not take
until the MWS application is restarted.

The following is the default content for a J2EE MWS implementation:

###MicroStrategy Web Services J2EE Configuration###

########################

#iServer config settings

########################

#SERVERBUSYTIMEOUT and REQUESTTIMEOUT are set at #application

startup and apply to all #connections.

#seconds

REQUESTTIMEOUT=120

#seconds

SERVERBUSYTIMEOUT=300

#MAXPOOLEDCONNECTIONS is set at connection time #for each

server. This value in #MWSConfig.properties is only used as a
default #when the projectsource.xml file value for
#MaxPooledConnections for a specific #projectsource is
missing.

MAXPOOLEDCONNECTIONS=100

#Maximum number of report/document execution #states saved per

iserver session. Affects the #number of asynchronous report
executions that #can be done concurrently.

REPORTSTATEWORKINGSET=5

#####################################

#MicroStrategy Office config settings

© 2011 MicroStrategy, Inc. Editing J2EE configuration settings 29

 3 Basic Administrative Operations MicroStrategy Web Services Administration

#####################################

#OFFICEINSTALLVERSION defines the build version #of the

setup.exe file associated with Office. It #defaults to the
same build version

#associated with the current version of the Web #Service, and

can be overridden by using the #config parm below.

#OFFICEINSTALLVERSION=9.x.yyy.zzz

#BLOCKOFFICEUPDATE will prevent Office Install #executable

information from being sent to the #client.

#BLOCKOFFICEUPDATE=true

#OFFICEINSTALLURL allows the admin to set an #alternate

location for the Office install #executable.

#Be aware that the URL is relative to the client, #so a

reference to "localhost" will refer to the #client.

#For example:

#On server fileshare...where fileShare is a #directory setup

to be shareable by local and #remote hosts

#OFFICEINSTALLURL=file://ServerOrRemoteHost/fileshare/setup.e
xe

#From another installation...where #MicroStrategyWS is mapped

to a virtual directory.

#OFFICEINSTALLURL=http://ServerOrRemoteHost:8080/MicroStrateg
yWS/Office/Setup.exe

#OFFICEINSTALLCONFIGFILELOC allows the admin to #set an

alternate location for the default

30 Editing J2EE configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

#Office config file that is supplied on the web #server. The

default location for this file is:

# "C:/Program Files/MicroStrategy/Web
Services/Office/moimain.dll.config"

# or:

# "../WebServiceRootPath/Office/moimain.dll.config"

#For example:

#absolute path on web server

#OFFICEINSTALLCONFIGFILELOC="C:/OtherDirectory/moimain.dll.co
nfig"

#network path

#OFFICEINSTALLCONFIGFILELOC="//ServerName/FileShare/OtherDire
ctory/moimain.dll.config"

#file URL

#OFFICEINSTALLCONFIGFILELOC="file://ServerName/FileShare/moim
ain.dll.config"

#relative path under web service root

#OFFICEINSTALLCONFIGFILELOC="Office/moimain.dll.config"

########################

#MSTRWS config settings

########################

#IMAGESUBDIRECTORY identifies the subdirectory #under the

installation directory

#containing MicroStrategy Web Services specific #image files.

IMAGESUBDIRECTORY=images

© 2011 MicroStrategy, Inc. Editing J2EE configuration settings 31

 3 Basic Administrative Operations MicroStrategy Web Services Administration

#FLASHSUBDIRECTORY identifies the subdirectory #under the

installation directory

#containing swf files for Flash View Mode support.

FLASHSUBDIRECTORY=swf

#BUNDLESUBDIRECTORY identifies the subdirectory #under the

installation

#directory containing date and string resource bundles for

Flash View Mode support.

BUNDLESUBDIRECTORY=resBundles

#STRINGSBUNDLEPREFIX identifies the file name #prefix for the

#strings resource bundle used in Flash View Mode #support.

STRINGSBUNDLEPREFIX=DashboardViewerBundle_

#DATESBUNDLEPREFIX identifies the file name #prefix for

thedates resource bundle used in #Flash View Mode support.

DATESBUNDLEPREFIX=DashboardDatesBundle_

#DASHBOARDVERSION allows the Flash dashboard swf #version

#to be set to something other than the default #build version.

#DASHBOARDVERSION=9.x.yyy.zzz

Note that some configuration options occur for both ASP.NET and J2EE
deployments, whereas others apply only to one or the other. The following
table presents each of the settings that appear in the MWSConfig.properties
file shown above, and information about their values:
Setting Description

SERVERBUSYTIMEOUT Amount of time an operation waits for Intelligence Server, if busy.

REQUESTTIMEOUT Amount of time the underlying MicroStrategy Web SDK called during a
Web Services operation waits for a response from Intelligence Server.

MAXPOOLEDCONNECTIONS Maximum number of connections that will be opened in a pool between

the Web Services computer and a given Intelligence Server.

IMAGESUBDIRECTORY Identifies the subdirectory under the installation directory containing

MicroStrategy Web Services specific image files.

32 Editing J2EE configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

Setting Description

FLASHSUBDIRECTORY Identifies the subdirectory under the installation directory containing swf
files for Flash View Mode support

BUNDLESUBDIRECTORY Identifies the subdirectory under the installation directory containing date
and string resource bundles for Flash View Mode support.

STRINGSBUNDLEPREFIX Identifies the file name prefix for the strings resource bundle used in
Flash View Mode support.

DATESBUNDLEPREFIX Identifies the file name prefix for the dates resource bundle used in
Flash View Mode Support.

DASHBOARDVERSION Allows the Flash dashboard swf version to be set to something other
than the default build version.

BLOCKOFFICEUPDATE A value of “true” prevents Office Install executable information from

being sent to the client.

OFFICEINSTALLURL Allows the administrator to set an alternate location for the Office install
executable. If the executable is remote to the server then the
OFFICEINSTALLVERSION config parameter must also be set.

For a server fileshare, use:

File://<ServerOrRemoteHost>fileShare/Setup.exe
For another installation, use:
http://<ServerOrRemoteHost>MicroStrategyWS/Office/
Setup.exe

Be aware that the URL is relative to the client, so a reference to

localhost will refer to the client.

OFFICEINSTALLVERSION Can be used to identify the version of the Office install executable, if the
file location is not accessible from the web server. Normally, the version
is obtained by querying the file.

OFFICEINSTALLCONFIGFILE Allows the administrator to set an alternate location for the default
LOC MicroStrategy Office Config file that is supplied on the web server.

JVMCLASSPATH Path to the JVM is different from the registered path.

REPORTWORKINGSET Number of working sets for report processing, which will limit the number
of reports that can be executed in parallel for a single session.

View the service definition

When viewed with a browser, MSTRWS.asmx provides a listing of the
available Web Services methods. The Services Definition link provides a Web
Services Description Language (WSDL) definition of all the MicroStrategy

© 2011 MicroStrategy, Inc. View the service definition 33

 3 Basic Administrative Operations MicroStrategy Web Services Administration

Web Services. The WSDL defines a Web Service using the XML Schema
language. It defines the message formats, data types, operations, and end
points, as well as other information to describe the Web Service and allow a
client to learn about the message formats. Details of WSDL can be found at
http://www.w3c.org.

For ASP.NET, to view the WSDL for MWS, on the MSTRWS.asmx Web page
click Services Description. To view a sample of an XML request and
response, click a method such as GetProjects.

For J2EE first use a browser to access the application home page, for
example http://localhost:8080/MicroStrategyWS for Tomcat. Click WSDL
next to the text View Service Description to view the WSDL for MWS.

Test the services

For ASP.NET, GetProjectSources and TestService can be invoked on the
same computer or, if configuration settings are changed, from a remote
computer. For J2EE, TestService can be invoked in any configuration. See
the appropriate procedure in Chapter 2, in either the Verifying your
ASP.NET installation, page 13 section or the Verifying your J2EE
installation, page 16 section for details on how to use these methods to verify
a MWS installation. See Chapter 6, Verifying Web Services availability
section for instructions to change the configuration to allow testing from a
remote computer for ASP.NET.

Supporting images in reports and documents

Images may be included in reports and Report Services documents as image
objects or threshold images. For more information on what a threshold
object is and how they are used, see the MicroStrategy Basic Reporting
Guide. These images can be included with the following reference types that
are supported by MicroStrategy Web Services:

Note the following:

• Paths on MicroStrategy Web Services machines are case-sensitive
when running MicroStrategy Web Services J2EE.

• For an image to appear in reports or documents, the user must

have authorization to access the image and image location.

34 Test the services © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

• Absolute path references — for example, C:\Images\image.jpg

• Network path references — for example,

\\Server\Share\Images\image.jpg

• Web path references — for example,

http://Server/Images/image.jpg

Web path references require more advanced security administration

since the Web Services server must connect to a second server to pass
along or delegate the user’s credentials.

• Relative path references — for example, images\image.jpg

Relative image paths are resolved to absolute file locations by

determining their base location. The absolute file location is resolved by
appending the relative path to the base location path. For Web Services,
the base location depends on the type of object referencing an image:

For images in reports, the base location depends on the version of

Web Services:

MicroStrategy Web
Base Location Example
Services

ASPx Web Services virtual directory C:\Program Files \MicroStrategy\

Web Services

J2EE MicroStrategy Web Services C:\Program Files\Tomcat 5.5

war file deployment directory \webapps\MicroStrategyWS

For images in Report Services documents, including Flash

dashboards, the base location depends on the output or mode with
which the document is being handled:

Output/Mode Base Location Example

Excel XML output Windows temporary directory C:\Documents and Settings

on the client machine \User\Local Settings\Temp

Flash view mode Web Services virtual directory C:\Program Files

\MicroStrategy\Web Services

PDF output Relative to the Intelligence C:\Program

Server installation Files\MicroStrategy\
Intelligence Server

© 2011 MicroStrategy, Inc. Supporting images in reports and documents 35

 3 Basic Administrative Operations MicroStrategy Web Services Administration

If an image cannot be found or accessed, MicroStrategy Web Services returns

a standard image indicating that the image could not be retrieved.

Images in HTML documents are not processed by MicroStrategy Web

Services since HTML documents are executed as a collection of
MicroStrategy reports.

Supporting third-party widget files in

dashboard documents
MicroStrategy Web Services distributes dashboard documents viewed in
Flash mode and any third-party widget files as .SWF files. A dashboard
document can reference a combination of one or more MicroStrategy widgets
and third-party widgets implemented as .SWF files. When a MicroStrategy
Web Services client application accesses a dashboard document requiring
one or more .SWF files, Web Services retrieves the .SWF files from the SWF
subdirectory of your Web Services deployment directory.

MicroStrategy widget files are included in the SWF subdirectory by default.

However, to include any third-party widget files you must first deploy the
widget in MicroStrategy Web. This automatically updates the widgets .XML
file. After the widget has been deployed, the widget files must be copied to
the .SWF subdirectory.

You can register third-party widget files with the use of MicroStrategy SDK
customizations. For information on the MicroStrategy SDK and how to
register third-party widget files with MicroStrategy, see the MicroStrategy
Developer Library. If you do not have a license for MicroStrategy SDK,
contact your MicroStrategy account executive.

Controlling Web Services logs

There are two logs for MWS error messages and information related to
MWS. In the MWS application directory, files appear in the form
MWSJavaLogMMDDYYY_n.log. In these files, log messages appear from the
Java MWS Object classes. You can control the logging with settings in the
mwsLogger.properties file found in the MicroStrategy Web Services
application directory. See the Configuring the ASP.NET log section in
Chapter 6 for more information about configuring the .NET logging.

36 Supporting third-party widget files in dashboard documents © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Basic Administrative Operations 3

Messages from the .NET portion of MWS are found in the log
MWSTraceLog.txt file located in the MWS application directory. This log is
controlled with settings in the web.config file. See Chapter 6, Configuring
the ASP.NET log section for more information about configuring the .NET
logging.

For J2EE there is also an infrastructure log with the name

MWSAxisJavaLog.txt. There are also logs managed by the application
server that may contain messages relevant to MWS. Consult your application
server documentation for more information about standard locations and
administration of these logs.

© 2011 MicroStrategy, Inc. Controlling Web Services logs 37

 3 Basic Administrative Operations MicroStrategy Web Services Administration

38 Controlling Web Services logs © 2011 MicroStrategy, Inc.

 4
4. APPLICATION CONFIGURATION
AND TUNING FOR ASP.NET

Introduction

This chapter presents details on several settings in the machine.config file

and the web.config file. It also discusses available performance counters
and how to use them to monitor and tune your Web Services deployment in
the ASP.NET environment.

ASP.NET configuration settings

The .NET environment uses a hierarchy of XML configuration settings to
control the processing of .NET applications. ASP.NET makes use of this
hierarchy with a machine.config file that sets system-wide configuration and
a hierarchy of web.config files that control the application and its
components. Some settings can only be managed in the machine.config
file. When settings appear in both files, a setting in the web.config file
overrides the setting in the machine.config file. Custom settings can be
defined and managed by handler components for application-specific
control.

© 2011 MicroStrategy, Inc. ASP.NET configuration settings 39

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

Although all settings can impact .NET Web Services either directly or
indirectly, certain groups of settings can directly impact the performance and
operation of Web Services. The discussion in this section focuses on certain
elements of the configuration files only. For a complete reference to the
settings, consult your Microsoft .NET documentation.

The following elements are discussed in more detail in this section:

• ProcessModel

• HttpRuntime

• Authentication

• Identity

The machine.config file is located at:

%windir%\Microsoft.NET\Framework\[version]\
CONFIG\machine.config

The web.config file is located in the MicroStrategy Web Services

application directory.

ProcessModel
The processModel element specifies how IIS will start and end ASP.NET
worker processes. This element appears in machine.config only. The
following table displays the attributes for processModel. In some cases, a
recommended setting for MicroStrategy Web Services is noted. If there is no
recommended setting, use the default. In all cases, optimized settings for
your environment depend on your workload. Several of these settings are
discussed in more detail below the table.

Recommended
Attribute Value Default Value Description
Value

enable true | false true Enables processModel.

timeout Infinite | Infinite Total life of process, once

HH:MM:SS expired process is shut
down and a new process is
created.

idleTimeout Infinite | Infinite Total idle life of process,

HH:MM:SS once expired process is
automatically shut down.

40 ASP.NET configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

Recommended
Attribute Value Default Value Description
Value

shutdownTimeout Infinite | 0:00:05 Time process is given to

HH:MM:SS shut down gracefully before
being killed.

requestLimit Infinite | number Infinite Total number of requests to

serve before process is
shut down.

requestQueueLimit Infinite | number 1000 5000 Number of queued requests

allowed before process is
shut down.

restartQueueLimit Infinite | number 10 100 Number of requests kept in

queue while process is
restarting.

memoryLimit Number 60 Percentage of physical

memory process is allowed
to use before process is
recycled.

webGarden true | false false Whether a process should

be affinitized with a
particular CPU.

cpuMask bit mask Oxffffffff Number of available CPUs

for ASP.NET processes
(WebGarden must be set to
true).

userName User machine Windows user to run the

process as:
• Special users:
“SYSTEM” runs as local
system (high privilege
admin) account.
• “machine”: Runs as a
low privilege user
account named
“ASPNET”.
• Other users: If domain is
not specified, the current
machine name is
assumed to be the
domain name.

password AutoGenerate | AutoGenerate Password of Windows user.

password For special users (SYSTEM
and machine), specify
AutoGenerate.

logLevel All | None | Errors Event types logged to the

Errors event log.

© 2011 MicroStrategy, Inc. ASP.NET configuration settings 41

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

Recommended
Attribute Value Default Value Description
Value

clientConnected HH:MM:SS 0:00:05 Time a request is left in the

Check queue before ASP.NET
does a client connected
check.

comAuthentication Default | None | Connect Level of authentication for

Level Connect | Call | DCOM security.
Pkt | PktIntegrity
| PktPrivacy

comImpersonationL Default | Impersonate Authentication level for

evel Anonymous | COM security.
Identify |
Impersonate |
Delegate

responseDeadlockI Infinite | 00:03:00 For deadlock detection,

nterval HH:MM:SS timeout for responses when
there are executing
requests.

maxWorkerThreads Number 20 100 Maximum number of worker

threads per CPU int he
thread pool.

maxIoThreads Number 20 Maximum number of IO

threads per CPU in the
thread pool.

serverErrorMessag Filename Customization for “Server

eFile Unavailable” message.

IIS 6.0 and the IIS Manager

When running under IIS 6, ASP.NET uses the IIS Manager to set several
processModel settings. Some processModel settings are still read from the
processModel element in the machine.config file. These include the
following:

• requestQueueLimit

• responseDeadlockInterval

• maxWorkerThreads

• maxIoThreads

42 ASP.NET configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

• minWorkerThreads

• minIoThreads

The other settings are managed in the IIS Manager Properties dialogs. See
the Microsoft IIS Manager documentation for complete details.

To set the values in IIS Manager, open the Properties dialog for the
MicroStrategyWebServicesPool application pool. The settings are located on
the Recycling, Performance, and Health tabs.

Thread pool limits

The process thread pool services incoming requests. The number of threads
is limited to prevent exhausting system resources for thread management,
which may degrade performance. If there is a free thread and a request
arrives, that request acquires the thread. If all threads are busy, the request is
queued until there is a free thread.

The default number of threads is 20 per processor. MicroStrategy

recommends raising this setting to 100. It is a good idea to tune this based on
your Web Services server CPU utilization and your Intelligence Server
utilization. If both are low, you can increase this setting if requests are
queueing.

httpRuntime
The following table displays the attributes for httpRuntime with a
recommended setting for MWS if different from the default and one has been
identified. Several of these settings are discussed in more detail below the
table.

Recommended
Attribute Value Default Value Description
Value

executionTimeout seconds 90 Time in seconds before a

request is automatically
timed out.

maxRequestLength KBytes 4096 Size in kilobytes of

maximum request length to
accept.

useFullyQualified true | false false Fully qualifies the URL for

RedirectUrl client redirects.

© 2011 MicroStrategy, Inc. ASP.NET configuration settings 43

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

Recommended
Attribute Value Default Value Description
Value

minFreeThreads count 8 20 Minimum number of free

threads to allow execution of
new requests.

minLocalRequest count 4 10 Minimum number of free

FreeThreads threads to allow execution of
new local requests.

appRequestQueue count 100 500 Maximum number of

Limit requests queued for the
application.

enableKernelOutput true | false true Enables the http.sys cache

Cache on IIS 6 and higher.

enableVersion true | false true Outputs the

Header ASP.NET-Version header
with each request.

maxWorkerThreads, maxIoThreads, and minFreeThreads

If request processing and queueing capacity are exhausted, requests will be

rejected. HTTP clients will receive HTTP 503 errors with the message “The
service is temporarily overloaded.” This error is caused when the application
queue is full, which is controlled by the appRequestQueueLimit setting. If
there are only minFreeThreads left of the maxWorkerThreads defined, and
maxIoThreads are in use for IO processing, and appRequestQueueLimit
requests are waiting, then requests are rejected.

maxWorkerThreads and maxIoThreads are set in the machine.config file in

the processModel element (discussed above) and impact all ASP.NET
applications. The default value for each is 20 threads per processor.

minFreeThreads is set in either the machine.config or web.config file in the

httpRuntime element. If the number of free threads is smaller than this
value, new requests will be queued. This allows threads to be available to
finish a request in process to prevent deadlocks. The minFreeThreads setting
is 8 and must be increased if the maxWorkerThreads is increased.

44 ASP.NET configuration settings © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

Authentication and identify settings

The authentication and identify settings are in the system.web element and
can be set in both the machine.config and web.config files. The
authentication and identify settings are set as follows for MicroStrategy Web
Services:

<authentication mode=“Windows” />

<identity impersonate=“true” />

These settings allow for NT authentication with impersonation, in

conjunction with disabling Anonymous authentication in IIS.

Identity controls the application identity of the application. It defines the

user context under which the application thread will execute. As the Web
Service executes, it is restricted to those resources that the user has
authorization to use.

Performance monitoring and tuning

This section describes how to start the Performance Monitor and add
counters. It lists and describes useful counters for ASP.NET Web Services
monitoring, and provides details for several counters as they relate to
monitoring and tuning MicroStrategy Web Services (MWS).

There are many additional standard and custom performance

counters from Microsoft, MicroStrategy, and other companies.

Performance Monitor
Performance analysis of ASP.NET application is enabled using performance
counters and the Performance Monitoring tool. With this tool, you can
obtain quantitative measures of application and server characteristics during
application operations. With these measures, you can:
• Understand the loads placed on your application.

• Understand the bottlenecks of your deployment.

• Evaluate the capacity needs of your application.

© 2011 MicroStrategy, Inc. Performance monitoring and tuning 45

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

• Debug issues caused by excessive demand or insufficient capacity.

• Measure the effects of server changes on the application.

Starting the Performance Monitor

To start the Performance Monitor

1 From your Windows Start menu, select Settings, then select Control
Panel.

2 Double-click Administrative Tools.

3 Double-click Performance to start the Performance Monitor.

To add a counter to the Performance Monitor

1 Start the Performance Monitor.

2 Click System Monitor if it is not already visible. Then click to expand the
Add Counters dialog box.

3 Click Use local counters, or select counters from your computer and
select the target computer from the list box.

4 Select the counter category from the Performance Object list box, and
click Select counters from list. From the list, select the counters
desired. Use the Ctrl or Shift keys to select multiple counters.

5 If the counter you chose supports instances, click Select instances from
list and select an instance. Click Add to add one or more instances to the
Performance Monitor.

6 Click Close to close the Add Counters window.

See your Microsoft documentation for complete details on this and other
Performance Monitor features.

46 Performance monitoring and tuning © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

Basic counters
Whenever you are testing application performance, the following counters
should be included. They provide a useful foundation of data for detailed
analysis. Each counter in the table is described in more detail in the following
sections.

Category Instance Counter

Processor _Total % Processor Time

Process • Windows XP: aspnet_wp % Processor Time

• Windows 2003/2008: aspnet_w3wp

Process • Windows XP: aspnet_wp Private Bytes

• Windows 2003/2008: aspnet_w3wp

Process • Windows XP: aspnet_wp Virtual Bytes

• Windows 2003/2008: aspnet_w3wp

Process • Windows XP: aspnet_wp Handle Count

• Windows 2003/2008: aspnet_w3wp

.NET CLR Exceptions #Exceps Thrown / sec

ASP.NET Application Restarts

ASP.NET Requests Rejected

ASP.NET Worker Process Restarts

Memory Available Mbytes

Web Service Current Connections

.NET CLR counters

These counters provide details about the .NET Common Language Runtime
environment that underlies the ASP.NET infrastructure.

Category Instance Counter Comments

.NET CLR #Exceps thrown / sec Total number of managed

Exceptions exceptions thrown per
second. Performance
degrades as this number
increases.

.NET CLR • Windows XP: aspnet_wp Current AppDomains Number of AppDomains

Loading • Windows 2003/2008: loaded in the process.
aspnet_w3wp

© 2011 MicroStrategy, Inc. Performance monitoring and tuning 47

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

Category Instance Counter Comments

.NET CLR • Windows XP: aspnet_wp Current Assemblies Number of assemblies

Loading • Windows 2003/2008: loaded in the process.
aspnet_w3wp

.NET CLR • Windows XP: aspnet_wp Bytes in Loader Heap Number of bytes committed
Loading • Windows 2003/2008: by the class loaded across all
aspnet_w3wp AppDomains.

.NET CLR • Windows XP: aspnet_wp # Bytes in All Heaps Number of bytes committed
Memory • Windows 2003/2008: by managed objects. Sum of
aspnet_w3wp the large object heap and
Generation 0, 1, and 2
heaps.

.NET CLR • Windows XP: aspnet_wp # Gen 0 Collections Number of times Generation
Memory • Windows 2003/2008: 0 objects have been garbage
aspnet_w3wp collected.

.NET CLR • Windows XP: aspnet_wp # Gen 1 Collections Number of times Generation
Memory • Windows 2003/2008: 1 objects have been garbage
aspnet_w3wp collected.

.NET CLR • Windows XP: aspnet_wp # Gen 2 Collections Number of times Generation
Memory • Windows 2003/2008: 2 objects have been garbage
aspnet_w3wp collected.

• .NET CLR Exceptions\Exceps thrown/sec: Performance degrades as

this number increases. Certain methods such as Response.Redirect can
trigger exceptions that are logged with this counter. Even if not caused by
Web Services, other applications running may raise this number and
lower overall performance. This number should remain below 5% of the
Requests Per Second counter.

• .NET CLR Loading\Current AppDomains: This number should be the

number of Web applications, + 1 for the default domain.

• .NET CLR Loading\Current Assemblies: Web Services are

implemented as ASMX files. Along with ASPX and ASCX files, these are
grouped in an application based on dependencies, and one or more
assemblies will be created. If too many assemblies are loaded in the
process, memory use may be high. Assemblies cannot be unloaded, and
when recompilations occur, they build up in the process. After
recompilations exceed the limit set in numRecompilesBeforeAppRestart,
the application restarts.

• .NET CLR Loading\Bytes in Loader Heap: If this value does not level
out and continues to rise, check the Current Assemblies counter.

48 Performance monitoring and tuning © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

• .NET CLR Memory\# Bytes in all Heaps: This counter will be less than
Process/Private Bytes, which includes all regions of type
MEM_COMMIT. This counter is a subset of those regions. The gap
consists of memory used by unmanaged code. When memory use is high,
determine if it is in managed or unmanaged code.

• .NET CLR Memory\# Gen N Collections: The CLR does a garbage

collection, either when space is required for object allocation, or when
one is forced. Collections of higher generations take longer, and each
generation should have 10x that of the next generation. Along with the %
Time in GC counter (below), this counter can identify excessive
allocations.

• .NET CLR Memory\% Time in GC: All threads are suspended during
collection. This counter determines whether too much time is spent in
collection. A value of 5% or less is good, although occasionally higher
values may occur.

ASP.NET and ASP.NET Application counters

These counters provide details about the ASP.NET environment and the
individual applications. When working with ASP.NET application counters,
you may want to select the MicroStrategy Web Services instance that
includes the name of the virtual directory for this Web application. By
default, this is MicroStrategyWS.

An asterisk (*) in the table below denotes a wildcard.

Category Instance Counter Comments

ASP.NET Application Restarts Number of application restarts.

ASP.NET Applications Running Number of applications running.

ASP.NET Requests Current Number of requests currently being

handled by the ASP.NET ISAPI.

ASP.NET Request Execution Time taken to execute the last request, in

Time milliseconds.

ASP.NET Requests Queued Number of requests currently queued.

ASP.NET Requests Rejected Number of rejected requests.

ASP.NET Request Wait Time Number of milliseconds that the most

recent request spent waiting in the queue,
or named pipe, between inetinfo and
aspnet_wp.

© 2011 MicroStrategy, Inc. Performance monitoring and tuning 49

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

Category Instance Counter Comments

ASP.NET Worker Processes Current number of aspnet_wp worker

Running processes.

ASP.NET Worker Process Number of aspnet_wp process restarts.

Restarts

ASP.NET *MicroStrategyWS Cache Total Entries Current number of entries in cache.

Applications

ASP.NET *MicroStrategyWS Cache Total Hit Ratio Total hit-to-miss ratio of all cache
Applications requests.

ASP.NET *MicroStrategyWS Cache Total Turnover Number of additions and removals to the
Applications Rate cache per second.

ASP.NET *MicroStrategyWS Cache API Entries Number of entries currently in user cache.
Applications

ASP.NET *MicroStrategyWS Cache API Hit Ratio Total hit-to-miss ratio of User Cache
Applications requests.

ASP.NET *MicroStrategyWS Cache API Turnover Additions and removals to user cache per
Applications Rate second.

ASP.NET *MicroStrategyWS Output Cache Entries Number of entries currently in Output

Applications Cache.

ASP.NET *MicroStrategyWS Output Cache Hit Total hit-to-miss ratio of Output Cache
Applications Ratio requests.

ASP.NET *MicroStrategyWS Output Cache Additions and removals to the output

Applications Turnover Rate cache per second.

ASP.NET *MicroStrategyWS Pipeline Instance Number of active pipeline instances.

Applications Count

ASP.NET *MicroStrategyWS Compilations Total Total number of .NET files that have been
Applications compiled.

ASP.NET *MicroStrategyWS Errors During Number of configuration and parsing

Applications Preprocessing errors.

ASP.NET *MicroStrategyWS Errors During Total number of compilation errors.

Applications Compilation

ASP.NET *MicroStrategyWS Errors During Total number of errors while executing.

Applications Execution

ASP.NET *MicroStrategyWS Errors Unhandled Number of unhandled exceptions during

Applications During Execution execution.

ASP.NET *MicroStrategyWS Errors Unhandled Number of unhandled exceptions per

Applications During Execution/sec second during execution.

ASP.NET *MicroStrategyWS Errors Total Sum of Errors During Preprocessing,

Applications Errors During Compilation, and Errors
During Execution.

50 Performance monitoring and tuning © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

Category Instance Counter Comments

ASP.NET *MicroStrategyWS Errors Total/sec Total of Errors During Preprocessing,

Applications Errors During Compilation, and Errors
During Execution, per second.

ASP.NET *MicroStrategyWS Requests Executing Number of requests currently executing.

Applications

ASP.NET *MicroStrategyWS Request In Application Number of requests in the application

Applications Queue request queue.

ASP.NET *MicroStrategyWS Requests Not Found Number of requests for resources not
Applications found.

ASP.NET *MicroStrategyWS Requests Not Number of requests failed because of

Applications Authorized unauthorized access.

ASP.NET *MicroStrategyWS Requests Timed Out Number of requests that have timed out.
Applications

ASP.NET *MicroStrategyWS Requests Succeeded Number of requests successfully

Applications executed.

ASP.NET *MicroStrategyWS Requests Total Number of requests since the application

Applications started.

ASP.NET *MicroStrategyWS Requests/sec Number of requests executed per second.

Applications

• ASP.NET\Application Restarts: An application restart takes time and

occurs when one of the configuration files is modified, when global.asax
is modified, when recompilations exceed a preset threshold, if the
contents of the bin directory are modified, or as a result of other
administrative actions. If you maintain a farm of servers, it is
recommended you take each server offline before making these
administrative changes. A value greater than 0 should be investigated.

• ASP.NET\Requests Current: This includes requests queued, executing,

or waiting to be sent to the client. If the current value exceeds
requestQueueLimit in the processModel, ASP.NET will reject requests.
This configuration setting applies to all supported versions of IIS. Other
settings in this category include responseDeadlockInterval,
maxWorkerThreads, maxIoThreads, minWorkerThreads, and
minIoThreads.

Requests Queued used with Requests in Application Queue can

determine when requests will be rejected. When Requests Current
exceeds the requestQueueLimit, requests are rejected with a 503 status
code and the message “Server is too busy.”

© 2011 MicroStrategy, Inc. Performance monitoring and tuning 51

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

Deadlocks are detected using this counter. <process Model

response DeadlockInterval=X/> is the limit of duration for which
responses will be waited on if Requests Current is greater than the sum of
maxWorkerThreads plus maxIoThreads. The result is that the process is
terminated and a new one is started.

<httpRuntime executionTimeout=X/> should be less than

responseDeadlockInterval.

• ASP.NET\Request Execution Time: Execution time begins when the

HttpContext for the request is created, until the response is sent by IIS.
This counter varies widely from reading to reading.

• ASP.NET\Requests Queue: In IIS 6.0 and later, requests are posted to

the managed ThreadPool via a queue from native code, and a queue for
each virtual directory. Requests in all queues are summed. This count
increases with a shortage of worker threads.

Each application or virtual directory queues requests if worker and IO

threads fall below the limit set by <httpRuntime
minFreeThreads=X/>. The requests are queued until they reach the
limit in <httpRuntime appRequestQueueLimit=/>. At that point,
the request is rejected with a 503 status code and the message “Server too
busy.”

• ASP.NET\Requests Rejected: When a queue limit is exceeded, requests

are rejected. If request processing requires external resources that are
slow to respond, queues will fill up. Heavy loads and stress can cause the
queue to fill up even without using slow external resources.

Any time this counter is greater than 0, this should be investigated.

If requests are rejected, use this counter along with the following
counters, all of which are described in this section:

Process\% Processor Time

Process\Private Bytes

Process\Thread Count

Web Service\ISAPI Extension Requests/sec

ASP.NET\Requests Current

ASP.NET\Requests Queued

ASP.NET\Request Wait Time

52 Performance monitoring and tuning © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

ASP.NET\Applications\Pipeline Instance Count

ASP.NET\Applications\Requests in Application Queue

• ASP.NET\Request Wait Time: The queue is a named pipe between

inetinfo and aspnet_wp. This counter measures time spent in that queue
(but not the application queue). Any value above 1000 should be
investigated. The average request should wait 0 seconds.

• ASP.NET\Worker Processes Running: If a new worker process starts to

replace a current worker process, there may be two running at the same
time. If for some reason the old process does not terminate, this can be a
problem. This counter should not exceed 2 if webGarden is false. If
webGarden is true, this value should be no greater than the number of
CPUs +1.

• ASP.NET\Worker Process Restarts: Any restart should be investigated.

Configuration variables interact to trigger a controlled restart, whereas
exceptions may trigger unexpected restarts. Restart causes are recorded
in the Application Event log.

• ASP.NET Applications\Cache* counters: There are a number of Cache

counters that you might want to investigate. MicroStrategy Web Services
does not cache data in the ASP.NET cache. The underlying Web objects
and Intelligence Server caches are leveraged instead. However, some
system elements are cached and can be investigated when there are
performance issues.

ASP.NET uses the cache for objects that are expensive to create.

• ASP.NET Applications\Pipeline Instance Count: A pipeline instance

will have only one executing thread. This count measures the number of
concurrent requests for the application. If this number begins to rise,
there may be a problem with external resources.
• ASP.NET Applications\Compilations Total: This is the number of
ASP.NET code files that have been compiled, including ASMX Web
Services files. Compiled files are combined into assemblies; the number is
based on dependencies between files. Dependencies between files affect
recompilations as well as other settings. Web Services recompilations are
triggered by changes in files, including web.config, machine.config, and
global.asax. Changes to dependent assemblies in the bin folder will also
cause recompilations. Assemblies are saved in temporary locations.
Existing assemblies will be used if there are no relevant changes when an
application starts or restarts.

• ASP.NET\Errors* counters: Numerous Error counters are available to

analyze the volume and type of errors.

© 2011 MicroStrategy, Inc. Performance monitoring and tuning 53

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

• ASP.NET\Requests Executing: The number of currently executing

requests controlled by httpRuntime.

• ASP.NET\Requests in Application Queue: The number of requests in

the application request queue. Together with Requests Current, this
provides a warning that requests may be rejected. Increase
appRequestQueueLimit if necessary.

• ASP.NET\Requests/sec: The number of requests executed per second.

This value is affected by application restarts, whereas Web Service\ISAPI
Extension Requests/sec is not.

Process, Processor, Memory, and System counters

Category Instance Counter Comments

Process aspnet_wp, inetinfo, or w3wp % Processor Time Percentage of time threads in this
process spend using processors.

Process aspnet_wp, inetinfo, or w3wp Handle Count Count of handles in the process.

Process aspnet_wp, inetinfo, or w3wp Private Bytes Size, in bytes, of committed

memory for this process.

Process aspnet_wp, inetinfo, or w3wp Thread Count Number of threads active in the
process.

Process aspnet_wp, inetinfo, or w3wp Virtual Bytes Current number of bytes of the
virtual address space for this
process.

Processor % Processor Time Percentage of time all threads use

processors.

Memory Available Mbytes Amount of physical RAM available.

System Context Switches/sec Rate at which processors switch

thread contexts.

• Process\% Processor Time: If this value exceeds 70% for long periods,
then the system is underpowered.
• Process\Handle Count: If this number is in the 5000 or 10,000 range,
then performance will degrade and something is wrong. For instance, a
denial-of-service attack against IIS can cause this number to jump
beyond these levels.

• Process\Private Bytes: Memory leaks are revealed by a steady increase

in Private Bytes. Set a memory limit for Private Bytes with the
<processModel memoryLimit=X> setting if you are concerned about

54 Performance monitoring and tuning © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Application Configuration and Tuning for ASP.NET 4

a memory leak. A limit of 60% or 800 MB is recommended if you are not

using the /3GB switch. If you are using the /3GB switch, calculate the
percentage to be no more than 1800MB of physical memory.

• Process\Thread Count: Watch this number if it climbs to 75 +

((maxWorkerThread+maxIoThreads) * #CPUs).

• Process\Virtual Bytes: Watch this number if it becomes larger than

600MB less than the virtual address space. Use 1.4MB without /3GB and
2.4GB with /3GB.

• Processor\% Processor Time: A value greater than 70% means

underpowered hardware.

• Memory\Available Mbytes: The amount of physical RAM available. If

the value is less than 20%, a hardware issue exists.

• System\Context Switches/sec: A high number can mean high lock

contention. This number should increase linearly with throughput, load,
and the number of CPUs.

Web Service counters

Category Instance Counter Comments

Web Service Current Connections Number of current connections.

Web Service Total Method Requests/sec Method requests per second.

Web Service ISAPI Extension Requests/sec Includes requests to all ISAP extensions,
not just aspnet_isapi.dll.

• Web Service\Current Connections: Optimal values for your site will

depend on local factors. Once an expected level is understood, look for
spikes and trends.

• Web Service\Total Method Requests/sec: This is helpful for diagnosing

performance problems. Compare with Requests/sec and ISAPI Extension
Requests/sec.
• Web Service\ISAPI Extension Requests/sec: This is helpful for
diagnosing performance problems. Compare with Requests/sec and Total
Method Requests/sec.

© 2011 MicroStrategy, Inc. Performance monitoring and tuning 55

 4 Application Configuration and Tuning for ASP.NET MicroStrategy Web Services Administration

56 Performance monitoring and tuning © 2011 MicroStrategy, Inc.

 5
5. ADVANCED INSTALLATIONS

Introduction

MicroStrategy Web Services (MWS) support advanced features for security

and scalability. Authentication and authorization are handled through
standard operating system and Web Server mechanisms for ASP.NET and
J2EE. Web Services can provide message privacy by encrypting messages
using Secure Socket Layer (SSL).

There are three possible levels of service redundancy to increase scalability

and reliability of MWS:

• Web Farms: These are multiple Web Servers running MWS, and are
configured to appear as a single Web Service and provide fault tolerance
capabilities.

• Web Garden: This allows multiple processes on a single Web Server to

appear as one process, supporting balanced work across multiple CPUs
and fault tolerance.

• Clustering of MicroStrategy Intelligence Servers

© 2011 MicroStrategy, Inc. 57

 5 Advanced Installations MicroStrategy Web Services Administration

This section discusses setting up SSL, Web Gardens, and Web Farms using
Windows 2003. For J2EE platforms, consult your operating system and
application server documentation. Other hardware and software
technologies can be used to set up Web Farms. Clustering is discussed in the
MicroStrategy System Administration Guide.

Setting up SSL for encryption

MicroStrategy Web Services (MWS) can be configured to use Secure Socket
Layer (SSL) connection to create an encrypted channel between the client
and server. This protects messages from outside viewing to ensure privacy of
communications between the client and the server. The privacy of the
messages is protected, and SSL can guarantee the identification of one or
both parties in the transaction.

The following list summarizes the work involved in setting up SSL:

• Generate an SSL Certificate Request.

• Submit the Certificate Request and issue the certificate.

• Install the SSL certificate on the Web Server.

• Configure the Web Service to require SSL access.

• Test SSL access to the Web Service.

• Configure the client to use the SSL HTTPS URL.

• Establish trust between the client and server.

Generating an SSL Certificate Request

Perform the following steps to generate an SSL Certificate Request.

58 Setting up SSL for encryption © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Advanced Installations 5

To generate an SSL Certificate Request

1 If you purchased an SSL Certificate from a certificate authority (CA) or an

enterprise CA, begin with step 2. Otherwise, install the Certificate
Services for your Windows operating system, as follows:

• From the left-hand side of the Add/Remove Programs window, select

Add/Remove Windows Components. The list of available services is
displayed.
• Check the Certificate Services check box. To complete the
installation, follow the instructions that appear.

2 From your Start menu, select Settings, select Control Panel, and then
select Administrative Tools. Open the Internet Services Manager tool.

3 Use the tree control to navigate to the website containing the MWS
virtual directory. By default, this is the Default Web Site. Right-click on
the website and select Properties. The Properties dialog box opens.

4 On the Directory Security tab, select Server Certificate. The Web

Server Certificate Wizard opens.

5 In the Welcome dialog box, click Next. Click Create a New Certificate
and click Next again.

6 The following two options appear:

• Prepare the request now, but send it later: This allows you to
prepare the certificate request now, but send it later.
• Immediately send the request to a Certificate Authority: This
option only appears if you have a properly configured Microsoft
Certificate Server available in your domain. See your Microsoft
documentation for more details.
To use your own Certificate Services setup, select Prepare the request
now, but send it later and click Next.

7 Enter a name and bit length value and click Next.

8 Enter an organization name and an organization unit name, and click

Next.

© 2011 MicroStrategy, Inc. Setting up SSL for encryption 59

 5 Advanced Installations MicroStrategy Web Services Administration

9 Enter a common name for your site.

• If this site is on the Internet, you should use your URL, for example,
www.mysite.com.

• If this site is on an intranet, use the NetBIOS or DNS name of your

computer, which should be displayed by default.

For external users, if the common name does not match the URL, the
user receives a warning.

10 Enter your geographical information and click Next.

11 Enter a file name and click Next to see a Request File Summary. The file
contains a Base 64 encoded string containing the information in the
request as well as your public key. Additional information is signed with
your private key. A Certificate Authority can use your public key to verify
the information signed with your private key.

12 Click Next, and then click Finish.

Submitting a Certificate Request and issuing the certificate

Perform the following steps to submit an SSL Certificate Request and issue
the certificate.

To submit a Certificate Request and issue the certificate

1 Open the generated Request File with Notepad and copy the contents to
the clipboard.

2 In your browser, open the following URL:

http://<hostname>/CertSrv, for the <hostname> on which
Microsoft Certificate Services was installed.

3 Click Request a Certificate and click Next. The Choose Request Type
page opens.

4 Click Advanced Request and click Next. The Advanced Certificate

Requests page opens.

5 Click Base64 Encoded Certificate Request (PKCS #10 or #7) and click
Next. The Submit a Saved Request page opens.

60 Setting up SSL for encryption © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Advanced Installations 5

6 Paste the information from the Certificate Request file that you copied
previously, into the text box beneath the Saved Request header. Click
Submit to open the Certificate Pending page, and then close your
browser.

7 From your Start menu, select Settings, select Control Panel, and then
select Administrative Tools. Open the Certification Authority tool.

8 Open your Certification Authority branch, open the Pending Requests

folder, and click your request.

9 Click Action, then All Tasks, and then Issue. The request is deleted from
the Pending Requests folder and moved to the Issued Certificates folder.

10 Click Issued Certificates and double-click the new certificate. The

Certificate dialog box opens.

11 On the Details tab, click Copy to File.... The Certificate Export Wizard
opens.

12 Click Base-64 encoded X.509 certificate and click Next.

13 Enter a file name to save the certificate and click Next. The Completing
the Export Wizard page opens.

14 Verify the summary and click Finish.

15 Close the Certificate dialog box and close the Certificate Authority tool.

Installing the SSL certificate on the Web Server

Perform the following steps to install the SSL certificate on the Web Server.

To install the SSL certificate on the Web Server

1 From your Start menu, select Settings, select Control Panel, then select
Administrative Tools. Open the Internet Services Manager tool.

2 Use the tree control to navigate to the website containing the MWS
virtual directory. By default, this is the Default Web Site. Right-click on
the website and click Properties. The Properties dialog box opens.

© 2011 MicroStrategy, Inc. Setting up SSL for encryption 61

 5 Advanced Installations MicroStrategy Web Services Administration

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 Web Server.

Configuring Web Services to require SSL access

Perform the following steps to configure MWS to require SSL access.

To configure Web Services to require SSL access

1 From your Start menu, select Settings, select Control Panel, and select
Administrative Tools. Open the Internet Services Manager tool.

2 Use the tree control to navigate to the MWS virtual directory, which is
named MicroStrategyWS by default. Right-click the virtual directory
name 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 use of HTTPS.

5 Click OK, then click OK again to close the Properties dialog box.

6 Close the Internet Information Services Manager tool.

Testing SSL access to Web Services

Perform the following steps to test SSL access to Web Services.

62 Setting up SSL for encryption © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Advanced Installations 5

To test SSL access to Web Services

1 In your browser, enter the URL to access MWS. By default, this is

http://<hostname>/MicroStrategyWS/MSTRWS.asmx. An error
page should appear with a 403.4 error indicating the SSL is required to
access this page.

2 Enter the URL

https://<hostname>/MicroStrategyWS/MSTRWS.asmx. (Note the
different prefix.) After a short delay, the Web Services method list
appears indicating that the SSL access is working.

Configuring the client to use an SSL HTTPS URL

Perform one of the following procedures to configure the client to use an SSL
HTTPS URL, depending on whether you have a packaged client or you are
working with a Visual Studio .NET project.

To configure the client to use an SSL HTTPS URL

• Packaged client: If you have a packaged client such as MicroStrategy

Office, enter the URL that is prefixed with https://. In MicroStrategy
Office, you can enter this URL in the Options dialog box.

• Visual Studio .NET project: For Microsoft Visual Studio .NET projects,
when you add a Web Reference, you can specify an https URL as the
location of the XML Web service. If you have not done this, you can edit
the class that was created by Visual Studio .NET that wraps the Web
Service, by modifying the line of code that sets the URL. For a C# project,
the line of code may be similar to the following after modification:
this.Url = “https://mymachine/MyWS/Service1.asmx”;

Your XMLWeb Service will now be accessed over SSL.

Establishing trust between client and server

If you have issued your own certificate, your Certificate Authority’s

certificate must be installed on the client as a trusted root certificate
authority. Perform the following steps to establish trust between the client
and the server.

© 2011 MicroStrategy, Inc. Setting up SSL for encryption 63

 5 Advanced Installations MicroStrategy Web Services Administration

To establish trust between client and server

1 From your browser, open the following URL:

http://<hostname>/CertSrv, where <hostname> is the computer
on which Certificate Services was installed.

2 Click Retrieve the CA certificate or the certificate revocation list and

click Next.

3 Click the Install this CA certification path link to install the certificate.

4 If you are accessing the Certificate Authority’s certificate, it must be

added to the machine’s trusted root store. Repeat steps 1 and 2 above,
then click Download CA certificate and save it to your client computer.

5 From a command window, run the Microsoft Management Console by

typing mmc to start the console program.

6 From the File menu, select Console and then select Add/Remove
Snap-in.

The Add/Remove Snap-in dialog box opens.

7 Click Add to open the Add Standalone Snap-in dialog box, click
Certificates, and then click Add.

8 Click Computer Account and click Next.

9 Click Local Computer and then click Finish to see a list of certificate
categories that appear in the Snap-in window.

10 Click OK to return to the Console Root window.

11 Open the list of trusted root certificate authorities in the tree view.

12 Click Action, then All Tasks, then Import to add your Certificate
Authority to the list.

Web Farm
A Web Farm consists of several Web Server machines configured together to
act as a single server with a single IP address. MWS can be configured to run

64 Web Farm © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Advanced Installations 5

in a Web Farm to provide better performance, scalability, and reliability.

This section outlines the steps to set up a Web Farm using the Windows
Server 2003 Network Load Balancing Service. There are other software and
hardware load balancers or switches that can be used to set up a Web Farm.

Each Web Server in the cluster must be configured to be fully operational.

For MWS, this means it is fully installed and configured, including having all
required project sources in its projectsources.xml file. Windows XP, 2003.
and 2008 servers can be balanced in the same “cluster”. The following steps
use the Windows 2003 Network Load Balancing Manager to set up the
cluster. Make sure you have administrative access to each of the servers that
will be added to the cluster.

The following list summarizes the work involved in setting up a Web Farm:

• Install and configure MWS on each Web Server that will be network
load-balanced.
• Configure the cluster and each server for network load balancing.

Installing and configuring MicroStrategy Web Services

Perform the following steps to install and configure MWS.

To install and configure MWS

1 Follow the MWS installation instructions for each machine that will be
part of the set of load balanced servers.

2 Configure each machine to have the same sources in projectsources.xml.

Configuring the cluster and servers for network load

balancing

Perform the following steps to configure the cluster and each server for
network load balancing (NLB).

You can only use the Windows 2003/2008 NLB Manager to configure
all hosts if they are all on Windows 2003 and 2008. Otherwise, you
must use the local manager on each Windows XP machine.

© 2011 MicroStrategy, Inc. Web Farm 65

 5 Advanced Installations MicroStrategy Web Services Administration

 Be aware of the following:

• A production installation requires more consideration during
cluster configuration than this procedure presents. Considerations
include security and performance issues. See your Microsoft
documentation for a full evaluation and analysis of the applicable
issues.

• If you decide to combine a Web Farm with SSL, additional

concerns exist and are reviewed in the Microsoft documentation.

To configure the cluster and servers for load balancing

1 From your Start menu, select Settings, select Control Panel, and open
Administrative Tools. Open the Network Load Balancing tool.

2 To create a new cluster, right-click on the Network Load Balancing

Clusters tree branch and click New Cluster. The Cluster Parameters
dialog box opens.

3 In the Cluster IP Configuration panel, enter an IP address, Subnet mask,

and full Internet name.

• Leave the IGMP Multicast option cleared. However, if the cluster does
not operate you may need to return to this screen and select this
option. Consult the Network Load Balancing Service documentation
for more advanced setup details, including using two network cards
per server.

• Leave the Allow Remote Control option cleared.

Click Next. The Cluster IP Addresses dialog box opens.

4 Click Next. The Port Rules dialog box opens.

5 The default port rule is too broad for production, but works for evaluation
purposes. Consult your Microsoft documentation for various scenarios
for port rules.

Note the following:

Two key ports are port 80 for standard HTTP traffic, and port 443 for
SSL traffic.

For SSL, there are numerous issues to insure proper operation of NLB
and SSL together. Consult your Microsoft documentation for
information on resolving these issues.

66 Web Farm © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Advanced Installations 5

For non-SSL situations, MWS does not have state maintained on the
server and will not require special affinity to be defined. Affinity
insures that a specific client will always be processed by a specific
server that is maintaining its state.

6 Click Next. The Connect dialog box opens.

 Before entering host information, ensure that all servers in the

cluster have fixed IP addresses.

7 Enter a hostname or an IP address in the Host box and click Connect.

The Interfaces available list automatically populates with interface
information.

8 Select an interface to be included in the cluster and click Next. The Host
Parameters dialog box opens.

9 The Host Priority box displays a unique ID that identifies each node in
the cluster and represents the priority given to each node. The lower the
ID, the higher the priority. Node 1 is the master node and will receive
requests and act as a routing manager in most cases. When the work load
is too high, other servers perform this function. Set the priority and click
Finish to complete host definition and close all dialogs.

10 The manager configures the first host and logs results in the bottom pane.
The final message should be “End Configuration Change.”

11 To add an additional host, right-click on the tree branch for the cluster
you just added and click Add Host to Cluster. The Connect dialog box
opens. Repeat the appropriate steps above for the additional host.

12 Reconfigure your Web Services client, such as MicroStrategy Office, to

use the cluster virtual IP address. Then execute the client against the
cluster and use performance counters or the trace log to verify that each
clustered server is being used.

Web Garden
A Web Garden consists of a multi-processor Web Server on which
independent ASP.NET worker processes run on two or more of the
processors. webGarden is an attribute of the processModel that controls
whether this feature is enabled. In Windows 2003, IIS 6.0, the webGarden
and cpuMask settings are configured in the IIS Manager. Likewise, in

© 2011 MicroStrategy, Inc. Web Garden 67

 5 Advanced Installations MicroStrategy Web Services Administration

Windows 2008, IIS 7.0, Web Garden settings are configured in IIS as
advanced settings for the application pool. See Chapter 4, ASP.NET
configuration settings section for details on these settings.

If a Web Garden is configured, MWS can benefit from improved

performance. State is maintained by MicroStrategy Intelligence Server, in
the form of a session identifier. There is no state that will be maintained in an
ASP.NET worker process for a Web Service client. Therefore, request
handling from a single client can alternate between ASP.NET worker
processors in a Web Garden.

Web Garden values

If the webGarden value is true, then the cpuMask attribute is used to specify
which CPUs will run an ASP.NET process. Each bit represents a processor. A
1 indicates that a processor will run the process and a 0 indicates it will not.
If there are four processors, then the following bitmap means the 3rd and 4th
processors will run an ASP.NET worker process, as shown below:

00001100

If the webGarden value is false, the operating system configures the system
for default affinity. This default is to run one ASP.NET process. The default
webGarden value is false.

68 Web Garden © 2011 MicroStrategy, Inc.

 6
6. DIAGNOSTICS TOOLS

Introduction

As with any client-server application, troubleshooting requires an approach

that isolates the problem based on the component technologies and their
connections. Since requests travel from client to server and back again, an
approach that evaluates this path and tests in this sequence is logical. It is
possible you can receive a specific error message at the client machine, which
may help you isolate the cause of the problem. However, it also happens that
you may get no indication about where the problem occurred, and you must
break down the communications and processing paths. A useful
troubleshooting sequence is listed below and progresses in the order shown:
• Use the Web Server logs to see whether the request was received by the
server or there was some indication of a problem.

• Verify that the Web Services are available on the Web Server itself.

• View the message exchange between the client and server to make sure
the exchange occurs and to check whether there is any indication of the
error.

• Drill down to the details of a processing problem.

© 2011 MicroStrategy, Inc. 69

 6 Diagnostics Tools MicroStrategy Web Services Administration

• If the issue is related to security, use techniques to isolate the security

problem.

• For advanced technicians, use debugging tools to make use of in-depth

processing tools.

 Inbefore
most cases, it is recommended that you contact MicroStrategy
using debugging tools.

Details for many of the procedures listed above are described in the rest of
this chapter.

Using event and error logs

Windows event log

ASP.NET and IIS write entries to the event log when there are problems.
These logs should be reviewed whenever you are debugging problems.
ASP.NET writes to the application log when there are aspnet_wp process
problems. IIS 6.0 and IIS 7.0 may write to either or both the application and
system logs when the w3wp process experiences problems.

Key related tasks are described in other sections in this chapter.

Viewing the Windows event log on the local machine

Perform the following procedure to view the Windows event log on a local
machine.

To view the Windows event log

1 From your Start menu, select Settings, select Control Panel, and open
Administrative Tools.

2 Open the Event Viewer. In the left panel, you can switch between the
Application, Security, and System logs to display the log entries in the
right panel.

70 Using event and error logs © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Diagnostics Tools 6

3 Double-click a log entry to see more details in the Event Properties dialog
box.

4 Use the up and down arrows to navigate through other log entries.

5 Click OK when you are ready to close the Event Properties dialog box.

Windows Web and HTTPERR error logs

MicroStrategy Web Services (MWS) in an ASP.NET environment runs under
IIS 6.0 on Windows XP and 2003, and IIS 7.0 on Windows 2008. Since
MWS uses HTTP for transmission, errors are often in the form of HTTP
protocol errors. Information in the W3C Web logs can provide clues to
problems, especially in a distributed and heavily trafficked environment.

These logs are enabled using the Internet Information Services (IIS)
Manager. When enabled, you can configure details about the information to
be included. IIS 6.0 and IIS 7.0 have a substatus code that can aid in
debugging. See your ISS documentation for a list of status and substatus
codes.

In IIS 6.0 and IIS 7.0there is an HTTPERR log that logs information from
HTTP.SYS. For Windows 2003, HTTP.SYS replaces inetinfo.exe as the
component that processes HTTP requests.

HTTPERR can be used to get details about rejected requests. Requests can be
rejected when the request queue is full or if the application is taken offline by
the Rapid Fail Protection feature. The QueueFull log entry appears if the
queue is full, and an AppOffline entry appears if the application is taken
offline.

HTTPERR provides details of lost requests if the worker process crashes or

hangs. In the log, you can find the URL and a
Connection_Abandoned_By_appPool message for each request that is lost.
These are called in-flight requests, in other words, the requests that were
sent to be processed but did not complete before the crash. See your
Microsoft documentation for more information about detailed messages you
can find in the HTTPERR log.

Key tasks for working with these logs include the following:

• Enable the Web log

• View the Web log

© 2011 MicroStrategy, Inc. Using event and error logs 71

 6 Diagnostics Tools MicroStrategy Web Services Administration

• Configure HTTPERR log settings

• View the HTTPERR log

Enabling the Web log

Perform the following steps to enable the Web log.

To enable the Web log

1 From the Start menu, select Settings, then select Control Panel. Open
Administrative Tools, then Internet Information Services Manager.

2 In the left panel, open the branch for your computer name to open the
local computer branch.

3 Open Web Sites to view the website you want to manage. By default, this
is the Default Web Site.

4 Right-click the website you want to view and select Properties. The
Default Web Site Properties dialog box opens.

5 On the Web Site tag, select Enable Logging to turn on the W3C logs. Set
the active log format as desired.

6 Click Properties to set details of the log entries in the Extended Logging
Properties dialog box. On the General Properties tab, set the time
period, name, and location of the file.

7 Click Extended Properties to select the fields to log by.

8 Click OK to close the Extended Logging Properties dialog box, and click
OK again to close the Default Web Site Properties dialog box.

Viewing the Web log

Perform the following steps to view the Web log.

72 Using event and error logs © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Diagnostics Tools 6

To view the Web log

1 Locate the Web log. The Web log location is specified in the Web log
properties and can be viewed using the Enabling the Web Log steps,
above. By default, this location is %SYSDIR%\LogFiles\W3SVC1. In this
directory, a series of log files exists dated according to the naming format
set in the log properties.

2 Open the log file in a text editor to view the entries.

Configuring HTTPERR log settings

The HTTPERR log writes entries for the following types of errors:

• Responses to clients: These are entries for HTTP protocol errors. After
sending the error response, the connection to the client is terminated.

• Connection timeouts: HTTP API times out the connection. If there is a

pending request, the request is used to provide more information about
the connection in the HTTPERR log.

• Orphaned requests: The worker process is terminated while there are

still queued requests routed to that process. The HTTP API logs the
orphaned request in the HTTPERR log.

The HTTPERR log is only available on IIS 6.0. To change settings, you
must have Administrator/Local System credentials.

Perform the following steps to configure HTTPERR log settings.

To configure HTTPERR log settings

1 To configure the HTTPERR log, you modify registry key settings found
under the key as follows:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\
HTTP\Parameters

© 2011 MicroStrategy, Inc. Using event and error logs 73

 6 Diagnostics Tools MicroStrategy Web Services Administration

2 Make your desired changes to the following values:

Registry Value Description

EnableErrorLogging A DWORD that enables or disables error logging:

• True: (Default setting) Enables error logging.
• False: Disables error logging.

ErrorLogFileTruncateSize A DWORD specifying the maximum size of an error log file, in bytes. The
default value is 1MB. The value cannot be smaller than the default value.

ErrorLoggingDir. A string that specifies the folder into which HTTP API puts its logging files.
The HTTP API creates a subfolder HTTPERR in the specified folder and
stores the log files in this subfolder. The subfolder and files have the same
permission settings. The Administrator and Local System accounts have
full access.
The default location is %SystemRoot%\System32\LogFiles

Viewing the HTTPERR log

You must have Administrator/Local System credentials to view the

HTTPERR log files.

Perform the following steps to view the HTTPERR log file.

To view the HTTPERR log

1 Locate the HTTPERR log. The location is specified in the HTTPERR

registry entries described above in . By default, this location is
%SYSDIR%\LogFiles\HTTPERR.

2 Use a text editor to open and view a log file. Reason phrase strings
provide details for each error and appear as the last field in each entry.

Java application server error logs

Each application server, such as Tomcat or WebSphere, maintains error logs
for infrastructure messages. Check your application server documentation
for their location and application settings. The primary place to look for
errors is in the MWS Java or ASP.NET error logs.

74 Java application server error logs © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Diagnostics Tools 6

Verifying Web Services availability

To ensure that the service is running and is visible from your client, follow
the appropriate procedure in Chapter 2, in either the Verifying your
ASP.NET installation, page 13 section or the Verifying your J2EE
installation, page 16 section.

You can run the TestService and GetProjectSources methods from a remote
computer by modifying entries under the <protocols> element in your
machine.config file. Locate the element path

\configuration\system.web\webServices\protocols

By default, the following entry will be commented out:

<add name=”HttpPost”/>

Uncomment the entry for it to take effect. Note that this change affects all
services on the server.

TcpTrace for message analysis

tcpTrace cannot be used for MWS on ASP.NET.
XML Web Services use SOAP as the message format for data and datatype
definitions. SOAP messages with XML content are transmitted using HTTP.
When there are problems it is often useful to view the messages between the
client and the server.

Answer the following questions to help determine the reason for the
problem:

• Are there any communications between the client and server?

• Are there basic protocol errors before the Web Service is even invoked?

• What parameters are used?

• What are the details of an error response being sent by the server to the
client?
• Are there any HTTP header fields that are inconsistent between the client
and server?

© 2011 MicroStrategy, Inc. Verifying Web Services availability 75

 6 Diagnostics Tools MicroStrategy Web Services Administration

tcpTrace is a useful tool for answering these questions. You can download
this tool from www. pocketsoap.com. The following high-level summary
describes how to view message exchanges between MicroStrategy Office and
MicroStrategy Web Services (MWS) on J2EE platforms using tcpTrace:

• Initialize tcpTrace to intercept and forward messages. For steps, see

Initializing tcpTrace to intercept and forward messages, page 76

• Configure MicroStrategy Office to send messages to tcpTrace. For steps,

see Configuring MicroStrategy Office to send messages to tcpTrace,
page 77

• Capture and view messages. For steps, see Capturing and viewing
messages, page 77.

Initializing tcpTrace to intercept and forward messages

Perform the following steps to initialize tcpTrace to intercept and forward
messages.

To initialize tcpTrace

1 Run the tcpTrace program. You can run this utility on either the client or
the server. For this procedure it is assumed you are running tcpTrace on
your client machine, with the name client, and that the Web Services
are installed on the machine named server.

2 On your client machine, navigate to the tcpTrace install directory, for

example, C:\Program Files\pocketsoap. Double-click
tcpTrace.exe. The main tcpTrace window opens, as well as the tcpTrace
Settings dialog box.

3 Complete the following settings:

• Listen on Port #: The port to which you will send messages. Port
8008 is a good choice.
• Destination Server: The server on which MWS is installed, for this
example the machine named server.

• Destination Port: This port should be set to the port used by the
application server. For example, 8080 is the default port for Tomcat.

76 TcpTrace for message analysis © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Diagnostics Tools 6

4 Options exist to create a log file, provide a log file name, and select an
XML format. Select all these options.

Using a file slows down processing, and using XML slows

processing even more. However, the XML format is the easiest way
to view results and potentially automate processing of the results.

5 Click OK to close the tcpTrace Settings dialog box and begin the trace.

Configuring MicroStrategy Office to send messages to tcpTrace

In this procedure you configure MicroStrategy Office to use your URL
monitored by tcpTrace. Perform the following steps to configure
MicroStrategy Office to send messages to tcpTrace.

To configure MicroStrategy Office to send messages to tcpTrace

1 From the Start menu, select Programs, select MicroStrategy, then select
MicroStrategy Office. Click Configuration to start the MicroStrategy
Office configuration utility.

2 Click General to open the General Options page.

3 Enter the URL for your monitored endpoint. For this example, enter
http://client:8008/MicroStrategyWS/services/MSTRWSJ
for J2EE Web Services running on Tomcat.It is important to
include the 8008 (port), otherwise messages will not be traced.

4 Click OK and then OK again. Close all Microsoft Office applications and
restart Excel.

Capturing and viewing messages

To understand messages, you must have knowledge of HTTP, SOAP, and
XML Web Services implementations. Once you have performed the following
procedure to view trace messages, if you need additional information to
understand them, see www.w3c.org for more details on HTTP and SOAP.
Perform the following steps to capture and view messages.

© 2011 MicroStrategy, Inc. TcpTrace for message analysis 77

 6 Diagnostics Tools MicroStrategy Web Services Administration

To capture and view messages

1 Start MicroStrategy Office and perform some functions.

2 Open the tcpTrace application. In the left panel, there will be indications
of several traces. When you select a trace, you see the client request in the
upper right panel and the server response in the lower right panel. Below
is an example request for GetProjectSources from the client, followed by a
good response from the server:

Client request:

POST /MSTRWS/MSTRWS.asmx HTTP/1.1

User-Agent: Mozilla/4.0 (compatible; MSIE6.0; MS Web
Services Client Protocol 1.1.4322.573)
Content-Type: text/xml; charset=utf-8
SOAPAction: http://microstrategy.com/webservices/
GetProjectSources
Content-Length: 313
Expect: 100-continue
Host: client:8080

<?xml version=“1.0” encoding=“utf-8”?><soap:Envelope

xmlns:soap=“http://schemas.xmlsoap.org/
soap/envelope/”
xmlns:xsi=“http://www.w3.org/2001/
XMLSchema-instance”
xmlns:xsd=“http://www.w3.org/2001/
XMLSchema”><soap:Body><GetProjectSources
xmlns=“http://microstrategy.com/
webservices/” /></soap:Body>
</soap:Envelope>
Server response:

HTTP/1.1 200 OK
Server: Microsoft-IIS/6.0
Date: Sat, 08 Nov 2003 15:54:37 GMT
X-Powered-By: ASP.NET
X-AspNet-Version: 1.1.4322
Cache-Control: private, max-age=0
Content-Type: text/xml; charset=utf-8
Content-Length: 2996

<?xml version=“1.0”encoding=“utf-8”?>

78 TcpTrace for message analysis © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Diagnostics Tools 6

<soap:Envelope
xmlns:soap=“http://schemas.xmlsoap.org/
soap/envelope/”
xmlns:xsi=“http://www.w3.org/2001/
XMLSchema-instance”
xmlns:xsd=“http://www.w3.org/2001/
XMLSchema”><soap:Body>
<GetProjectSourcesResponse
xmlns=“http://microstrategy.com/
webservices/”><GetProjectSourcesResult>
<MWSProjectSourceInfo><ServerName>TEST
</ServerName><ProjSourceName>TEST
</ProjSourceName><AuthMOde>MWSStandard
</AuthMode></MWSProjectSourceInfo>

... MORE sources ...

</soap:Body></soap:Envelope>POST /MSTRWS/MSTRWS.asmx
HTTP/1.1

Web Services tracing for ASP.NET message

analysis
ASP.NET has added a Web Services tracing capability to view input and
output SOAP requests. In the web.config file, locate the <diagnostics>
element inside the <microsoft.web.services2> element. Then locate the
<trace> element inside <diagnostics>.

To turn on tracing, set the enabled attribute to true. The input and output
attributes will contain the filenames of the input and output trace files. These
files will be in the root application directory. Be sure to set the enabled
attribute to false after you are finished tracing. To understand messages, you
must have knowledge of HTTP, SOAP, and Microsoft .NET Web Services
implementations.

Configuring the Java log

The file logger.properties contains settings that control Java logging
for MWS. This file is found in the MWS directory, by default located at

© 2011 MicroStrategy, Inc. Web Services tracing for ASP.NET message analysis 79
 6 Diagnostics Tools MicroStrategy Web Services Administration

C:\Program Files\MicroStrategy\Web Services for ASP.NET and

at webapps/MicroStrategyWS for J2EE. Several settings can be modified
by the administrator.

You may want to relocate your log file (pattern), change individual log file
size (limit - # bytes), or log file instances (count). The default entries for
these settings are:

• fileH.pattern=C\:/Program Files/MicroStrategy/Web
Services/MWSJavaLog%systemdate%.log

The above setting is the default for an ASP.NET deployment.

• fileH.pattern=C\:/Tomcat5/webapps/MicroStrategyWS/
MWSJavaLog%systemdate%.log

The above setting is typical for a J2EE Tomcat deployment.

• fileH.limit=262144

• fileH.count=4

• fileH.level=SEVERE

The level setting can control how much detail is logged. For Web Services,
locate the following entry:

com.microstrategy.webservices.Log.level=SEVERE

The level can be set to one of the following values, which causes the log to
increase in detail in the following order:
• SEVERE

• WARNING

• INFO

• FINE

• FINER

• FINEST

• ALL

When controlling the amount of data to be logged, you must not only
configure the com.microstrategy.webservices.Log.level, but
must also ensure that the fileH.level element at least matches the
webservices setting so that the appropriate level of logging can occur. For

80 Configuring the Java log © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Diagnostics Tools 6

example, if the webservices setting is ALL, the fileH.level value must be

ALL as well. The level for other components in the WebObjects API can be
set in logger.properties in the same way.

Configuring the ASP.NET log

The ASP.NET tracing can be controlled from two different sections of the
web.config file, the system diagnostics section and the appSettings section.

In the system diagnostics section of the web.config file, two switches are used
to control the level of tracing that is performed:

• MicroStrategy.WebServices: Controls the tracing of Web Service front

end and bridge code.

• MicroStrategy.Web.BridgeInf: Controls the tracing of the underlying

bridge implementation layer that supports Web Services.

The default setting for both switches is 1 (ERROR), which enables tracing for
error messages only. Setting the switch values to 4 (VERBOSE) enables
tracing at the finest level. The default system diagnostics section is shown
below:
<system.diagnostics>
<switches>
<!--
Switches control what level of tracing messages you want to output. In
MicroStrategy SDK’s coding convention, switches are identified by each
bridge or application’s name space. After you change the tracing level by
changing the ‘value’ attribute, you have to restart your application to make
it effective. Any message logged at lower tracing level will be sent to the
listeners you specify.
0==>OFF
1==>ERROR
2==>WARNING
3==>INFO
4==>VERBOSE
For example, if you set the tracing level to 3, then all error, warning, and
info messages will be logged.
-->

<!-- This switch controls the bridge infrastructure logging-->

<add name=”MicroStrategy.Webservices” value=”1” />
<add name=”MicroStrategy.Web.BridgeInf” value=”1” />
</switches>
</system.diagnostics>

© 2011 MicroStrategy, Inc. Configuring the ASP.NET log 81

 6 Diagnostics Tools MicroStrategy Web Services Administration

In the appSettings section of the web.config file, some application-specific

settings allow control of the trace files. By default, TRACE is ON for errors
only. If .NET tracing is not required, set this value to OFF. Once the trace file,
MWSTraceLog.txt, reaches its max size (MAXTRACEFILESIZE), a copy of
that file is backed up, with the name MWSTraceLog0, MWSTraceLog1,
MWSTraceLog2, and so on, in sequence. This occurs until the maximum
number of backup trace files is reached (NUMBACKUPTRACEFILES). Once
the maximum number of trace files are created, tracing works in a circular
fashion, with the next backup being logged to MWSTraceLog0.txt. The
current trace log file is always kept in MWSTraceLog.txt.

The default trace setting in the appSettings section is shown below:

<appSettings>

<!-- Trace file setup.

If TRACE is set to ON, trace files will grow to the specified size
(MAXTRACEFILESIZE) before being backed up. Once the specified number of
backup files have been created (NUMBACKUPTRACEFILES), the first backup file
will be overwritten, and so on, in a circular fashion.

The trace file will be named (MWSTraceLog.txt and will be located at the Web
service root filepath, along with its backup files (ie. C:\Program
Files\MicroStrategy\Web Services.)
-->

<add key=”TRACE” value=”ON” />

<!-- Specified in K bytes -->

<add key=”MAXTRACEFILESIZE” value=”1024” />
<add key=”NUMBACKUPTRACEFILES” value=”4” />

</appSettings>

Microsoft debugging tools

Microsoft makes available the Microsoft Debugging Tools for Windows,
which can be used for debugging Web Server problems. These tools are
available at http://www.microsoft.com/whdc/ddk/debugging/
installx86.mspx.

A debugger add-on exists, sos.dll, to use with the windbg.exe or cdb.exe

debuggers for managed code debugging. Among other things, it can be used
to dump the contents of the garbase collection heap, analyze locking issues,
view thread usage, and display managed stack traces.

82 Microsoft debugging tools © 2011 MicroStrategy, Inc.

 7
7. TROUBLESHOOTING

Introduction

This chapter lists common problems you may encounter when using
MicroStrategy Web Services (MWS). The problems are organized into the
following groups:

• HTTP errors, page 84

• Key error phrases, page 85s

• Other symptoms, page 88

This chapter also presents a list of frequently asked questions, beginning on

page 89.

For each error, there is a discussion of related messages and conditions,

where applicable, as well as possible causes and possible solutions. The
display of errors depends on the client tool and how it processes errors from
MWS or the communications channels. Depending on the client tool, these
error messages may appear in different formats and different locations.
However, the HTTP error codes or key phrases should be available, no

© 2011 MicroStrategy, Inc. 83

 7 Troubleshooting MicroStrategy Web Services Administration

matter which client tool you use. For MicroStrategy Office using MWS,
consult the MicroStrategy Office online help first for information on error
messages.

HTTP errors

401 Unauthorized

This may also appear with the message “Access Denied”.

Causes: The most common reason for this error is that the user does not
have authorization to access the Web service.

Solutions: Verify the identity of the user receiving this error. Check that the
user has access to the Web service virtual directory.

403 Forbidden

There are a number of sub-status codes for this message, and you may
receive a more specific error message.

Causes: This is due to an authorization problem on some resource.

Solutions: Check that the user has access as specified in ASP.NET Web
Services security requirements, page 8 section.

404 Resource Not Found

Depending on the message, the actual resource may be identified.

Causes: This could be due to an improper installation, or one or more files

having been moved or deleted.

Solutions:

• Verify that the installation is correct and all files are present.

• Try resetting IIS.

84 HTTP errors © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Troubleshooting 7

500 Internal Server Error

There is rarely more detail with this error.

Causes: Typically this is an execution error in the Web Services application

and the cause can be varied.

Solutions: Check all of the error logs to see whether there are more details
on the problem.

503 Service Unavailable

There may be several variations for this error, as follows:

• Server unavailable

• Site unavailable

• Service unavailable

• Service is temporarily overloaded

• Server is too busy

Causes: The cause can range from an addressing issue, to server or

application queues being full and causing requests to be rejected.

Solutions: First verify that you have network access to the server and the
Web Service is operational from the host itself. Then follow the instructions
given in ASP.NET configuration settings, page 39 section to determine
whether requests are being rejected. If requests are being rejected, raise the
maxWorkerThreads, requestQueueLimit, and appRequestQueueLimit.

Key error phrases

This section lists error phrases and describes what they mean or possible
variations. It also suggests causes and presents solutions.

Access to the path

“C?\WINDOWS\Microsoft.NET\Framework\v1.1.4322\Temporary
ASP.NET Files\microstrategyws\nnnn\mmmm” is denied

The paths and file names will vary.

© 2011 MicroStrategy, Inc. Key error phrases 85

 7 Troubleshooting MicroStrategy Web Services Administration

Causes: This is due to a problem with process user permissions.

Solutions: Verify that the security requirements in httpRuntime, page 43

section have been met.

Exception calling XYZ (no inner details)

XYZ can vary in this message, and will identify where the error occurred.

Causes: This error is mostly likely evidence of a problem with the Java
Virtual Machine (JVM) used by the MWS Objects and WebObjects.

Solutions: Restart IIS and see whether the problem occurs again. Increasing
the Java heap size may help.

Method not found:<method signature>

The method may vary.

Causes: Process or the user has insufficient access to required resources.

Solutions: Verify that the security requirements in httpRuntime, page 43

section have been met.

Object reference not set to an instance of an object

This is an internal error.

Causes: There can be one or more reasons for this error, including an
internal execution error or resource constraint.

Solutions:
• Check all of the error logs to see whether there are more details on the
problem.

• Try restarting IIS or the application.

• Contact MicroStrategy with error details if the problem persists.

Request timeout

This timeout is from the MicroStrategy WebObjects.

Causes: A call to the underlying WebObjects exceeded the

REQUESTTIMEOUT setting. This is most likely due to a very large report.

86 Key error phrases © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Troubleshooting 7

Solutions: Try increasing the REQUESTTIMEOUT setting, or lowering the

MAXREPORTROWLIMIT and using incremental row fetching.

Server XYZ is busy

This refers to a MicroStrategy Intelligence Server.

Causes: This is caused by an excessive load on the Intelligence Server.

Solutions:

• Increase the SERVERBUSYTIMEOUT to reduce the occurrence of this

error.

• If the problem persists, evaluate the processing capacity of the

hardware on the Intelligence Server machine.

System.IO.FileNotFoundException: File or assembly name xxxx.dll or

one of its dependencies, was not found

Any file in the application can trigger this problem.

Causes: This can be caused by both a managed or unmanaged dependency

issue. A file needed for execution is not available.

Solutions: Make sure that all managed and unmanaged dependencies are
available. Unmanaged DLLs must be in the current directory or on the path.
Managed DLLs must be in the local bin directory or the global assembly
cache.

The underlying connection was closed: An unexpected error occurred

on a receive

This relates to HTTP communications. A related message is below.

Causes: A connection between the client and server was broken before
receiving the complete response.

Solutions: This can be due to a loss of hardware communications. If other

requests are still executing successfully, then check the IIS
connectiontimeout setting. This is not in either the web.config or
machine.config files, but rather part of the IIS Metabase. In Internet
Information Services Manager, open the Properties dialog box for your Web
site. Click the Web Site tab and set the Connection Timeout value to at least
900 seconds. Click OK to save the new setting.

© 2011 MicroStrategy, Inc. Key error phrases 87

 7 Troubleshooting MicroStrategy Web Services Administration

The underlying connection was closed: Unable to connect to the

remote server

This is an HTTP communications problem.

Causes: The client cannot find the server.

Solutions: Verify the URL for the server and communications between the
client and server.

Other symptoms
This section lists additional possible problems not directly related to error
messages, and presents causes and solutions.

Error with no message text

The application cannot properly format an error message.

Causes: This is typically due to a shortage of memory in the JVM.

Solutions: Increase the amount of memory available to the JVM using the
Java Heap Size registry entry for the MicroStrategy JNI Bridge.

User is prompted for Network Login while running client against Web

This is an HTTP communications problem.

Causes: The client cannot find the server.

Solutions: Verify the URL for the server and communications between the
client and server.

IIS is not processing MSTRWS.asmx

When browsing to MSTRWS.asmx, instead of receiving the list of methods,

you receive the following message:

<%@ WebService Language=“c#” Codebehind=“MSTRWS.asmx.cs”

Class=“MSTRWS>MSTRWS” %>

Causes: ASP.NET has not been installed or enabled for IIS.

88 Other symptoms © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Troubleshooting 7

Solutions:

• For Windows 2003, use Manage Your Server to make sure that .NET
Framework is installed and enabled, or follow .NET Framework
instructions to ensure the proper version of .NET Framework is
installed, registered, and enabled for use with IIS.

• For Windows 2008, make sure that .NET Framework is installed and
enabled, or follow .NET Framework instructions to ensure the proper
version of .NET Framework is installed, registered and enabled for
use with IIS.

Frequently asked questions

Does MicroStrategy Web Services (MWS) require Microsoft .NET
Framework?

Yes. Specifically, the most recent version of MWS requires Microsoft .NET
version 2.0. This has been tested with Microsoft Internet Information
Services version 6.0 and 7.0. This is automatically installed by MicroStrategy
installation if not present on the machine.

Can I program to the Web Services API directly?

Yes. As long as you can follow the XML Schema defined in the MWS
Definition Language schema, you can communicate with MWS. However,
the Web Services API has been deprecated; it is recommended that you use
the Web Services SDK to communicate with MicroStrategy.

Can I use any language on any platform to program the Web Services
API?

Yes. As long as your computer can communicate with HTTP to the MWS
server, you can execute the API.

Is documentation available for the MWS API?

Yes. You can view the detailed message format specifications and examples
of those messages online. More detailed documentation for the API is
available upon request.

© 2011 MicroStrategy, Inc. Frequently asked questions 89

 7 Troubleshooting MicroStrategy Web Services Administration

Does MWS require MicroStrategy Web to be installed?

No. MWS uses underlying WebObjects Java libraries to communicate with

Intelligence Server. These files are deployed during installation if you select
Web Services for installation. No other MicroStrategy software needs to be
deployed on that server.

Can MWS be run on the same server as MicroStrategy Web?

Yes. MWS and MicroStrategy Web are compatible and can be run on the
same server. In a production environment, the products will compete for
resources on the same server. It is recommended that they run on separate
servers.

Does MWS support SSL?

Yes. MWS can communicate with a client such as MicroStrategy Office using
Secure Socket Layer for security. See Setting up SSL for encryption, page 58
section.

Does MWS support WS-Security?

Yes. SSL provides complete message privacy, but does not provide the
comprehensive security that WS-Security provides. There are middleware
components that can be used to configure WS-Security for MWS. Since MWS
supports Message Transmission Optimization Mechanism for attachments,
it can be fully secured with WS-Security.

Does MWS support Web Farms and Web Gardens?

MWS’s architecture is built to run in Web Farms. State is maintained in the

Intelligence Server and not in the Web Server, which makes it suitable for
Web Farms and Web Gardens in ASP.NET. See Web Farm, page 64 section
for more details. There are many software and hardware implementations
for Web Farms, not all of which can be thoroughly tested. Consult your load
balancing software or hardware documentation for installation setup
information. In all cases, you must make sure that the MicroStrategy
portions are installed with identical settings, project sources, and virtual
directory names.

What are the best configuration settings for machine.config and

web.config?

See ASP.NET configuration settings, page 39.

90 Frequently asked questions © 2011 MicroStrategy, Inc.

GLOSSARY

.NET A technical and a marketing term. Technically, .NET is a

Microsoft environment for building, deploying, and running
Web Services and other applications. The three main parts of
.NET are the Common Language Runtime, the Framework
classes, and ASP.NET.

See also

• ASP .NET

• Common Language Runtime

ASP .NET A component of Microsoft's .NET technology. The successor

to Active Server Pages, it is a set of Web development
technologies used to build dynamic websites, Web
applications, and XML Web services.

cluster A group of computers that are configured to cooperate

together to work, and appear, as if they were a single
computer. They are usually connected through high-speed
local area networks to improve system scalability, speed, and
reliability in a cost-effective way.

Common Language Microsoft's .NET virtual machine and runtime library. It is

Runtime (CLR) designed to support any program language that conforms to
the CLR’s specifications. The runtime is primarily used on
Microsoft's operating systems.

© 2011 MicroStrategy, Inc. Glossary: .NET 91

Glossary MicroStrategy Web Services Administration

Extensible Markup A derivative of Standard Generalized Markup Language

Language (XML) (SGML), a W3C-recommended markup language for creating
other special-purpose markup languages. XML is designed to
facilitate information sharing by providing content and
meaning in a format that is universally accessible to both
software and people. Numerous related standards have been
developed as well as XML-based languages.

handler A modules that is registered to handle certain Web resources

by name or extension. In Web Services, resources ending
with asmx are handed off to the Web Services handler.

HyperText Transfer A communications request/response protocol between client

Protocol (HTTP) and server computers, typically operating over a TCP/IP
connection. It is the primary method used to convey
information on the World Wide Web. Initially developed to
publish and receive HTML pages, it has been expanded to
support the SOAP framework used for Web Services
communication.

Java Java refers to both a programming language and a platform

from Sun Microsystems. The platform consists of the Java
programming language, a set of development tools and a set
of standard libraries. The platform is technically referred to
as the Java 2 Platform and includes a Standard Edition, J2SE
or Java SE and an Enterprise Edition, J2EE or Java EE and a
Micro Edition, and J2ME or Java ME.

See also
• Java 2 Platform, Enterprise Edition (J2EE)

Java 2 Platform, A programming platform that is part of the Java platform for
Enterprise Edition developing, deploying, and executing multi-tier applications
(J2EE) based on the server components running on an application
server. Also referred to as the Java EE, the J2EE platform is
defined by a specification and vendors must adhere to
conformance requirements to declare their products as Java
EE-compliant. Key server technologies include Enterprise
Java Beans, Servlets, JavaServer Pages, and Web Services.

92 Glossary: Extensible Markup Language (XML) © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Glossary

Java Native Interface A programming framework allowing Java code running in the
(JNI) Java virtual machine to call and be called by native
applications and libraries written in other languages, such as
C or C++.

Java Virtual Machine A virtual machine that runs Java byte code usually generated
(JVM) by a Java language compiler. It is a component of the Java
platform.

See also

• Java

• Java 2 Platform, Enterprise Edition (J2EE)

project source Defines a connection to the metadata repository and is used

by various MicroStrategy products to access projects. It
identifies an Intelligence Server with a specific type of
authentication.

Secure Sockets Layer A secure communications technology succeeded by and

(SSL) sometimes used to refer to Transport Layer Security (TLS).
SSL/TLS is a communications protocol which uses
cryptography to provide secure communications between two
endpoints, in which the server and potentially the client are
authenticated and data is encrypted.

SOAP Originally an acronym for Simple Object Access Protocol,

SOAP is now a stand-alone term. SOAP is a W3C
specification for a lightweight, distributed messaging
protocol that can utilize any communications transport. The
specification defines the format for the SOAP message
framework, describes how a message should be processed,
specifies how data should be encoded, and describes a
convention for representing remote procedure calls and
responses.

© 2011 MicroStrategy, Inc. Glossary: Java Native Interface (JNI) 93

Glossary MicroStrategy Web Services Administration

Universal Description, An XML-based registry for businesses and their services.

Discovery and UDDI streamlines online transactions by enabling companies
Integration (UDDI) to find one another on the Web and make their systems
interoperable for e-commerce. It enables businesses to
quickly and dynamically discover and invoke Web Services
both internally and externally.

Web Farm A group of computers clustered together in a single location

to provide a Web facility; also referred to as a Web server
farm. A Web Farm may either use multiple computers to
implement a single website, or multiple sites as implemented
by an Internet Service Provider.

See also

• cluster

Web Garden A process model that distributes work to several processes,

one per CPU, with each process having processor affinity set
to its designated CPU.

Web Services A software system designed to support interoperable

machine-to-machine interaction over a network, according to
the W3C. The most popular standards used to implement
Web Services are SOAP, HTTP, and UDDI. Additional
standards are defined for enterprise-level services such as
security, reliable messaging, and transactions.

See also

• SOAP

• HTTP

• UDDI

Web Services .NET updates provided by Microsoft to keep its Web Services
Enhancements (WSE) implementation up to date. Due to the continual evolution of
Web Services standards, developers require more frequent
updates to Web Services than those supplied by the normal
.NET update cycle.

94 Glossary: Universal Description, Discovery and Integration (UDDI) © 2011 MicroStrategy, Inc.
MicroStrategy Web Services Administration Glossary

Web Services An XML document schema used to describe the interface of a

Description Language Web Service. It is used to specify the operations, messages,
(WSDL) data types, protocol binding, and location of the Web Service.

XML See Extensible Markup Language.

© 2011 MicroStrategy, Inc. Glossary: Web Services Description Language (WSDL) 95

Glossary MicroStrategy Web Services Administration

96 Glossary: XML © 2011 MicroStrategy, Inc.

INDEX

Symbols aspnet_wp process problems 70

authentication
.NET JNI Bridge 5
settings 45
Windows NT 8
Numerics availability of Web Services, viewing 75
401 Unauthorized error 84
403 Forbidden error 84 B
404 Resource Not Found error 84
bridge code tracing 81
500 Internal Server Error 85
bridge implementation layer tracing 81
503 Service Unavailable error 85

A C
certificate
Access Denied error 84
installing for SSL 61
access permissions 9
requesting for SSL 58
adding a counter to Performance
Monitor 46 cluster
Anonymous access 11 configuring 65
application log and aspnet_wp process Web Farms and 65
problems 70 Common Language Runtime
architecture 2 environment 47
asmx files 2 communications privacy 58
ASP.NET 2, 3 configuration settings
authorization 10 ASP.NET 39
configuration settings 39 Web Services and 22, 28
log 81 configuring a cluster 65

© 2011 MicroStrategy, Inc. 97

Index MicroStrategy Web Services Administration

counter inetinfo.exe and HTTP.SYS 71

about 45 installation 7
ASP.NET 49 verifying 13, 16
basic 47 Web Services, advanced 65
process, processor, memory, Web Services, basic 7
system 54 international support xxi
Web Service 55

J
D Java log 79
debugging
Microsoft debugging tools 82
Windows event log and 70
K
key error phrases 85

E
error
L
key phrase 85 log 36
queue 85 ASP.NET 81
request timeout 86 HTTPERR 71
with no message text 88 Java 79
event log, Windows 70 W3C Web 71
Web 71

F
frequently asked questions 89
M
messages and privacy 58
Microsoft .NET Framework 89
H MicroStrategy Office licensing
HTTP errors 84 requirement 20
HTTP.SYS and inetinfo 71
HTTPERR log 71
N
settings 73
network load balancing 65
viewing 74
Network Load Balancing Manager 65
httpRuntime 43
NT authentication 45

I
O
identify settings 45
Objects (MWS) 5
IIS versions 6

98 © 2011 MicroStrategy, Inc.

MicroStrategy Web Services Administration Index

P certificate request 58
configuring with Web Services 62
performance
installing a certificate 61
Web Farms and 65
testing 62
Web Gardens and 68
Web Farms and 66
Performance Monitor 45
state maintenance and Web Gardens 68
adding a counter to 46
support
starting 46
international xxi
permissions, access 9
support. See technical support.
privacy of communications 58
system counters 54
process counter 54
processModel 40
processor counters 54 T
project source tcpTrace
changing 22 about 75, 79
Web Farms and 65 MicroStrategy Office and 77
project source definition, adding 15, 18 technical support xxi
testing, SSL 62
Q thread pool process 43
tracing
queues error 85
bridge implementation layer 81
front end and bridge code 81
R troubleshooting
request timeout error 86 about 83
with diagnostic tools 69

S
scalability and Web Farms 65 V
security requirements 8 virtual directory, default 8
security, advanced settings 11
Server is too busy error 85 W
Server unavailable error 85
W3C Web log 71
Server XYZ is busy error 87
Web Farms
service definitions 33
about 64
Service is temporarily overloaded error 85
project source and 65
Service unavailable error 85
SSL and 66
Site unavailable error 85
Web Gardens
SSL
about 67
about 58

© 2011 MicroStrategy, Inc. 99

Index MicroStrategy Web Services Administration

state maintenance and 68

Web log 71
Web Services
about ix, 1, 7
architecture 2
authentication 8
availability 75
communications path 4
configuration settings 22, 28
configuring for SSL 62
counter 55
definition 1
front-end tracing 81
installation 7
installation, advanced 65
log 36
project sources and 22
security 8
service definition 34
Web Gardens and 67
Web Services API 89
web.config authentication settings 8
Windows event log 70
Windows NT authentication 8
worker process
starting or ending 40
state and 68

100 © 2011 MicroStrategy, Inc.