administrator guide - magnitudesupport.noetix.com/.../noetixplatformadministratorguide.pdf ·...

Administrator Guide

®

Noetix Platform Administrator GuideNoetix Platform 5.8

This document was released on April 07, 2010. Please go to Answer ID 648 (INFO: Documentation for Noetix Platform) on the Noetix online knowledge base; an updated version of this document might be available.

Copyright © 2001–2010 Noetix Corporation. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from Noetix Corporation.

The information in this document is subject to change without notice. Noetix Corporation strives to keep this information accurate but does not warrant that this document is error-free.

Noetix, NoetixViews, Noetix QueryServer, Noetix WebQuery, and the Noetix logo are registered trademarks of Noetix Corporation. Other “Noetix” marks are trademarks of Noetix Corporation.

Noetix QueryServer is protected by United States Patent 6,178,418.

Oracle, JD Edwards, PeopleSoft, Retek, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Oracle E-Business Suite, Oracle Database, Oracle Discoverer, Oracle Business Intelligence, SQL*Plus, SQL*Net, SQL*Loader, PeopleSoft Enterprise, Siebel Business Applications, and other Oracle, PeopleSoft, and/or Siebel product names referenced herein are trademarks or registered trademarks of Oracle Corporation. Sun, Java, Java Runtime Environment, and other Sun product names referenced herein are trademarks or registered trademarks of Sun Microsystems, Inc. Microsoft, Microsoft Excel, Microsoft Internet Explorer, Windows, Microsoft SQL Server, Microsoft SQL Server Reporting Services, Internet Information Services, Microsoft .NET Framework, Microsoft ASP.NET, Microsoft Data Access Components, and other Microsoft product names referenced herein are trademarks or registered trademarks of Microsoft Corporation. Adobe, Acrobat, the Adobe PDF logo, Adobe Flash Player, and Adobe Reader are trademarks or registered trademarks of Adobe Systems Incorporated. IBM, Cognos, Cognos Framework Manager, Cognos Configuration, Cognos Query Studio, Cognos Report Studio, Cognos Connection, and other Cognos server or modeling product names mentioned herein are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. SAP is a registered trademark of SAP AG. BusinessObjects is a trademark of Business Objects, an SAP company. Web Intelligence and Xcelsius are trademarks or registered trademarks of Business Objects, an SAP company. All other company and product names mentioned herein are used for identification purposes only and may be trademarks or registered trademarks of their respective owners.

http://noetix.custhelp.com/cgi-bin/noetix.cfg/php/enduser/std_adp.php?p_faqid=648

The log4cpp library has been modified by Noetix and is distributed with Noetix QueryServer under the GNU Lesser General Public License. Noetix hereby offers to give any third party, for a charge no more than our cost of physically performing the distribution, a complete, machine-readable copy of the log4cpp library, which shall be distributed under the GNU Lesser General Public License and supplied on a medium customarily used for software interchange. Requests for source code must be submitted within three years of this offer and should be directed to Noetix Corporation, 5010 148th Ave NE, Suite 100, Redmond, WA 98052-5119, USA.

Contents v

ContentsPreface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiAbout This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiNoetix Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Chapter 1 About Noetix Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2About NQS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

NQS Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5NQS Administrator Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About NWQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7NWQ Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8NWQ Administrator Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

About Noetix Delivery Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Noetix DeliveryManager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Noetix DeliveryServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Noetix Add-in for Microsoft Excel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11About Noetix Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12About NoetixViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13About NoetixAnswers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13About Noetix Logging Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Components of Noetix Logging Service . . . . . . . . . . . . . . . . . . . . . . 14About Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Types of Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Location of Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

How a Query is Processed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Setting Up Noetix Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19About the Use of E-Mail in Noetix Platform . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2 Administrator Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24NQS Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25NQS Service Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27NQS Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28NQS Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32NWQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36NWQ Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

vi Noetix Platform Administrator Guide

Chapter 3 VTables and Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46VTables and VViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Creating a Simple VTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Creating a Complex VTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Creating a VView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Modifying a VTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Granting Permissions to a VTable . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Organizing VTables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Creating a Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Creating a Subfolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Moving a VTable to Another Subfolder . . . . . . . . . . . . . . . 62Granting a Default Subfolder . . . . . . . . . . . . . . . . . . . . . . . 63

Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Viewing a VTable’s Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Creating a Custom Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Creating a Heterogeneous Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 74Granting Permissions to Heterogeneous Mappings . . . . . . . . . . . . . . 76Examples of Custom Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 4 Servers and Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Creating a Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Creating a Server Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Creating a Server Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Comparison of Connection Types. . . . . . . . . . . . . . . . . . . . . . . . . . . 98Creating a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Chapter 5 Web Queries and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

NWQ Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Web Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Exposing VTables in NWQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Adding a VTable to a User’s Personal Folder . . . . . . . . . . 109Adding a Group of VTables to VTables Folder . . . . . . . . . 110

Customizing or Formatting the Web Query . . . . . . . . . . . . . . . . . . 111Viewing Query Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Changing Query Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Taking Ownership of a Query . . . . . . . . . . . . . . . . . . . . . 116

Contents vii

Giving Ownership to Another User . . . . . . . . . . . . . . . . . 117Redirecting Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Rebasing a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Migrating a Query to a Different System . . . . . . . . . . . . . 120

Sharing Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Granting Access to a Query. . . . . . . . . . . . . . . . . . . . . . . . 123Giving a Copy of a Query. . . . . . . . . . . . . . . . . . . . . . . . . 123Publishing a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Querying in Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Querying in Excel for Oracle E-Business Suite Users . . . . 126

Managing Query Deliveries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Managing Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . . . 127Managing Subscription Schedules . . . . . . . . . . . . . . . . . . . 127Managing Subscription Profiles . . . . . . . . . . . . . . . . . . . . 127

Folder Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Adding a Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Editing a Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Granting Public Folder Permissions . . . . . . . . . . . . . . . . . . . . . . . . 130

Chapter 6 Users and Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

External Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Steps for Setting Up Noetix Users . . . . . . . . . . . . . . . . . . . . . . . . . . 136

Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Importing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Creating Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Administrative Users and Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

The SysAdmin User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Administrative Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Changing Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Organizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Grouping Users into Organizations . . . . . . . . . . . . . . . . . . . . . . . . . 145

Chapter 7 Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150Scaling Noetix Platform for Better Performance . . . . . . . . . . . . . . . . . . . . . . 150

Scaling NQS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151The Server’s Processor. . . . . . . . . . . . . . . . . . . . . . . . . . . . 152The Server’s NIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Scaling Heterogeneous Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . 153Scaling the Noetix Cache Maintenance Server. . . . . . . . . . . . . . . . . 155

viii Noetix Platform Administrator Guide

Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Creating Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Noetix Logging Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Noetix Add-in for Microsoft Excel . . . . . . . . . . . . . . . . . . 158Noetix QueryServer Service . . . . . . . . . . . . . . . . . . . . . . . 158

Managing Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Noetix Logging Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Noetix Add-in for Microsoft Excel . . . . . . . . . . . . . . . . . . 160Noetix QueryServer Service . . . . . . . . . . . . . . . . . . . . . . . 160

Noetix Agent Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Setting Up an E-Mail Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Creating Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Creating Agent Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Creating a Data Alert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Creating a Validation Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169About the Cache Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Caching VViews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171About Caching Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

One-Copy Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Two-Copy Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

About Cache Indexes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173About Routing Queries to Cached Mappings . . . . . . . . . . . . . . . . . 173Caching a Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Creating a Cache for a Mapping . . . . . . . . . . . . . . . . . . . . 174Scheduling a Cache for a Mapping . . . . . . . . . . . . . . . . . . 176

Using Your Cached Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Managing Cached Mappings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178Caching Limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Backing Up and Restoring Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Backing Up Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Restoring Repositories from Backup Files . . . . . . . . . . . . . . . . . . . . 180

Restoring Repositories Without Uninstalling Noetix Platform . . . . . . . . . . . . . . . . . . . . . . 181Restoring Repositories on a Fresh Installation of Noetix Platform . . . . . . . . . . . . . . . . 181

Support for Unicode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Setting the Locale of Noetix QueryServer Service . . . . . . . . . . . . . . 182

Noetix Delivery Services Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . 183Noetix DeliveryManager.exe.config. . . . . . . . . . . . . . . . . . . . . . . . . 183

Contents ix

Noetix DeliveryServer.exe.config . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Time-Outs in NWQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Data Polling in NWQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Settings for Time-Outs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

NWQ Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Data Drills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Drill Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Supported Variables in Drill Rules . . . . . . . . . . . . . . . . . . 197Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Creating Drill Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Deleting Drill Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Restoring Connections Between NQS and NQS Repository . . . . . . . . . . . . . 202

Chapter 8 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Granting, Revoking, and Inheriting . . . . . . . . . . . . . . . . . . . . . . . . 206Explicit, Implicit, and Effective Permissions . . . . . . . . . . . . . . . . . . 207How NQS Determines Object Permissions. . . . . . . . . . . . . . . . . . . 207Permission Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Creating Roles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Creating Role Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Granting Permission to a Role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Determining Role Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Granting Permission to an NWQ Folder . . . . . . . . . . . . . . . . . . . . 215

Profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Types of Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217Steps for Setting Up Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Reviewing the Default Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Creating Custom Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219Granting or Revoking Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Copying Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Granting Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Resolving Profile Conflicts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Using Standard Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Deleting Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

Appendix Legal Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Third-Party License Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Preface

This preface is an introduction to the Noetix Platform Administrator Guide. It discusses the guide’s content and assumptions, as well as how to contact Noetix Corporation.

xii Noetix Platform Administrator Guide

About This GuideThe Noetix Platform Administrator Guide provides administrators of Noetix Platform with a general reference for managing and optimizing the Noetix products within an enterprise.

This guide assumes that Noetix Platform has been purchased from Noetix Corporation and that the reader is primarily responsible for the installation and maintenance of Noetix Platform. This guide requires a general knowledge about the system environment, client/server architecture, databases used within the enterprise (including Oracle databases), Oracle E-Business Suite or Siebel Business Applications configuration, and using common graphical user interfaces.

This guide also assumes that the reader has a basic knowledge of the query tools that may be used to access information through Noetix QueryServer (NQS).

Noetix Technical SupportThe Noetix Technical Support Web site is available if you have any questions or encounter a problem during installation or operation of your Noetix software. This site is updated regularly with the latest information on Noetix products.

http://support.noetix.com

Chapter 1

About Noetix Platform

This chapter provides an overview of Noetix Platform and its core components.

2 Noetix Platform Administrator Guide

OverviewThe Noetix solution includes the integrated set of Noetix products, including Noetix QueryServer (NQS), Noetix WebQuery (NWQ), NoetixViews for Oracle E-Business Suite (NoetixViews for Oracle), NoetixViews for PeopleSoft Enterprise (NoetixViews for PeopleSoft), NoetixViews for Siebel Business Applications (NoetixViews for Siebel), Noetix Analytics for Oracle E-Business Suite (Noetix Analytics), and NoetixAnswers. Noetix provides a unique software infrastructure to improve the usability and accessibility of business data in a secure environment.

The Noetix solution is available for Oracle E-Business Suite, PeopleSoft Enterprise, and Siebel Business Applications.

Features of Noetix include:

• Immediate answers to business questions: Noetix automatically generates an extensive library of customizable reports from your Oracle, PeopleSoft, and Siebel applications. Decision makers are able to access and use a reporting platform specific to your unique business with click-on answers to hundreds of business questions.

• Unmatched ease of use: Requiring little or no user training, decision makers are able to access business information, create custom reports, and securely share their reports with other internal and external users. Further simplifying information sharing, the Noetix open architecture provides seamless integration with Microsoft Excel in addition to other popular query and reporting tools.

• Low cost of ownership, high return on investment: By eliminating the necessity to manually map data to create or re-create reports, Noetix dramatically reduces the costs associated with report development. Further protecting your investment, Noetix shields your reports during upgrades. With a reporting platform to securely manage user access, Noetix lowers the cost of sharing information across your organization.

Chapter 1: About Noetix Platform 3

The Noetix solution comprises the Noetix Platform and NoetixViews (see Figure 1.1).

The Noetix Platform includes the following main components that work together to create an enterprise architecture for reporting:

• NQS serves as a central repository for storing and managing metadata that describes data from disparate sources.

• NWQ provides an easy Web-based access to create and run reports.

• NoetixViews are customized views of your Siebel Business Applications, Oracle E-Business Suite, or PeopleSoft Enterprise data. For more information about NoetixViews, see the NoetixViews for Siebel Business Applications Administrator Guide, NoetixViews for Oracle E-Business Suite Administrator Guide, or NoetixViews for PeopleSoft Enterprise Administrator Guide respectively.

As Noetix is extensible, third-party query tools can also be used with it.

Figure 1.1 Noetix Architecture


About NQSNoetix QueryServer (NQS) acts as a central repository for storing and managing metadata that describes data from disparate sources, creating a powerful library of virtual tables (VTables) and views. Across departments, enterprises, or suppliers, NQS securely manages data access and query activity by providing a single point of query maintenance—regardless of the number of data sources or structure complexity.

Today, when your users want to retrieve data from a database, they log on to the database, run a query (SQL command), and then view the results. If the user wants to access different data in a different database, they must also log on to this database and then run a query.

With NQS, the user can access all data through NQS. When the user (or the query tool that the user is running) runs a query, the SQL command is transparently routed by NQS to the correct physical database. The way that a query is routed is completely configurable by the Noetix administrator. If the user wants to access a different set of data, they can simply issue the new query against NQS without having to log on again.

From CRM and HR to ERP applications, NQS bridges the gap between heterogeneous data sources, delivering easily accessible information without the time and expense associated with other data integration solutions. NQS’s patented query routing technology intelligently ensures reporting efficiency, reducing bottlenecks and improving performance while effectively scaling to meet and deliver information when and where needed.

Benefits of NQS include:

• Patented routing technology: Using the power of metadata, NQS optimizes query performance, improving data access efficiency and report generation.

• Data integration: NQS integrates multiple, disparate data sources to provide centralized query and data access management.

• Flexibility: NQS delivers secure, reliable data access control across departments, enterprises, and business partner operations.

• Speed: NQS presents a single query repository of business-oriented views to speed report generation and development.


NQS consists of the components and tools, which are shown in Figure 1.2. The sections following the diagram give a brief overview of the components and tools.

Figure 1.2 NQS Architecture

NQS Components• Noetix QueryServer service: A Windows server application (that is a Windows

Service) that includes metadata management and intelligent routing capabilities. Noetix QueryServer service is the heart of Noetix QueryServer (NQS) and acts as a logical layer to isolate client applications from changes in the physical servers.

• NQS repository: A Microsoft SQL Server database used to store all NQS metadata. This database can exist on the same computer as the Noetix QueryServer service or on a separate computer for scalability. NQS communicates with the repository database through the SQL Server ODBC driver.


• NQS Monitor repository: A SQL Server database used to store logs of NQS activity. This database can exist on the same computer as the Noetix QueryServer service or on a separate computer for scalability.

• NQS Connect: Connectivity software, in the form of an ODBC driver, that enables client/server applications, report servers and Web servers that use ODBC and OLE DB to directly connect to RDBMS data sources. Through ongoing communication with the Noetix QueryServer service, NQS Connect obtains information for the client directly from the RDBMS. This component is installed on each server and client computer that communicates directly with NQS.

• Noetix Cache Maintenance Server (optional): A Windows server application (that is, a Windows Service) responsible for caching data for better query performance. The Noetix Cache Maintenance Server component (CMS) can be installed on the same computer as the Noetix QueryServer service or on a separate computer for scalability.

CMS does the real work of caching the data from the source to the defined cache connection, that is, the target. You can install and configure one or more Cache Maintenance Servers for your enterprise, and easily add more servers in the future as your performance needs grows.

• Noetix agent tools (optional): The Noetix agent tools allow you to schedule recurring tasks and automatic alerts. Agent jobs can be set up to inform you about specific conditions in your data (for example, sales exceed 5,000 orders) or scan your metadata looking for problems. Agent jobs can also be set up to schedule backups of NQS. The agent tools are installed on the same server as your NQS repository. NQS Administrator provides easy access to setting up Agent jobs and alerts.

• Heterogeneous mapping server (optional): The heterogeneous mapping server (HMS) feature allows you to set up heterogeneous mappings for virtual tables (VTables). Heterogeneous mappings are used to bring together data from different servers, or from different database types.


NQS Administrator ToolsThere are four main tools to administer the Noetix QueryServer (NQS) components. These administrator tools are installed along with the Noetix QueryServer service, but can also be installed on administrator computers for easier access. For more information about these tools, see Administrator Tools.

• NQS Administrator: A Windows-based application used by administrators to set up, manage, control and optimize the enterprise DSS architecture. Manages the metadata in the NQS repository, as well as the Noetix Cache Maintenance Server.

• NQS Monitor: A Windows-based application used to track and analyze query and resource usage. Manages the NQS Monitor repository.

• NQS Query: A Windows-based application used to run ad hoc queries against the NQS repository.

• NQS Service Manager: A Windows-based application used to start and stop the Noetix QueryServer service, as well as configure NQS to auto-start.

About NWQNoetix WebQuery (NWQ) is a Web-based query tool for exclusive use with Noetix QueryServer (NQS). With NWQ, users can create, run, and share ad hoc reports based on data exposed by NQS.

With a user-friendly interface, NWQ gets information where it is needed, without extensive training or consulting. From corporate intranet/portal use to wireless report generation, NWQ requires no client-side installation, dramatically simplifying deployment and management concerns. Like all Noetix products, NWQ’s open architecture is ideal for use in a complete business intelligence solution.


Benefits of NWQ include:

• Internet-ready reports: Web-enabled capability delivers information when and where needed.

• Quick installation: Easy-to-use interface assures fast deployment, eliminating extensive training.

• Flexibility: Open architecture uses XML standards to provide powerful compatibility with most Web-enabled systems.

NWQ consists of the components and tools, which are shown in Figure 1.3. The sections following the diagram give a brief overview of each.

Figure 1.3 NWQ Architecture

NWQ Components• Noetix Gateway: The Noetix Gateway (gateway) is a Microsoft Windows Web

service that is used to manage and run ad hoc reports and deliver subscriptions.

The gateway communicates with the Noetix QueryServer service through NQS Connect to authenticate users, save reports, create folders, and perform other tasks.

• NWQ repository: The NWQ repository is used to store the ad hoc reports, folders, and so on, that are created by end users. This repository is housed within the NQS repository.


NWQ Administrator ToolsNoetix WebQuery (NWQ) and NWQ Administrator allow you to use and administer NWQ. More information about these tools can be found in this guide and in the online help files for NWQ and NWQ Administrator.

• NWQ: NWQ client is a browser-based interface that interacts with the Noetix Gateway (gateway). Since it is completely Web-based, there is no software to install on the end user’s computer. The only requirement is Microsoft Internet Explorer 6 or later. From this interface, end users can build and run reports for use in the browser or in Microsoft Excel.

• NWQ Administrator: NWQ Administrator is a browser-based administrative tool that manages NWQ profiles, customizing which features and tools in NWQ each end user can access. Using NWQ Administrator, you can also generate a list of all queries a user owns or take ownership of any NWQ query. NWQ Administrator also allows you to view a listing of queries, subscriptions, and subscription schedules. In addition, NWQ Administrator allows you to view query usage in two ways: by user and by query.

About Noetix Delivery ServicesNoetix Delivery Services comprises Noetix DeliveryManager and Noetix DeliveryServer, which are Microsoft Windows services used for subscription delivery. The two services are used to deliver subscriptions to printers, e-mail addresses, and network locations.


Noetix DeliveryManagerNoetix DeliveryManager hosts a central queue for all scheduled subscriptions and delegates the deliveries to one or more instances of Noetix DeliveryServer.

On receiving a subscription, Noetix DeliveryManager:

1. Makes calls to Noetix Gateway (gateway) to retrieve delivery settings for the subscription, and then places it in the central queue.

2. Waits for Noetix DeliveryServer to request a subscription, and then sends it.

3. Receives delivery status from Noetix DeliveryServer.

If Noetix DeliveryServer fails to deliver a subscription or stops responding, an error will be logged for the subscription in Noetix WebQuery (NWQ). The settings for Noetix DeliveryManager are configured in the Noetix DeliveryManager.exe.config file, which is located in <hard disk drive>:\Program Files\ Noetix\NWQ\Delivery. For more information about the configuration file, see Noetix DeliveryManager.exe.config in “Maintenance.”

Noetix DeliveryServerNoetix DeliveryServer delivers a subscription to a printer, e-mail address, or network location. For example, subscriptions can be delivered to Noetix Dashboard. Microsoft SQL Server Reporting Services is used for rendering the query in various file formats, such as PDF and HTML.

Noetix DeliveryServer requests a subscription from Noetix DeliveryManager, which hosts a central queue for all the subscriptions. Then, Noetix DeliveryServer delivers the subscription to its destination.

On receiving the subscription from Noetix DeliveryManager, Noetix DeliveryServer:

1. Runs and renders the subscription through SQL Server Reporting Services.

2. Delivers the subscription to a printer, e-mail address, or network location.

3. Sends delivery status to Noetix DeliveryManager.


If Noetix DeliveryServer fails to deliver a subscription or stops responding, an error will be logged for the subscription in Noetix WebQuery (NWQ). The settings for Noetix DeliveryServer are configured in the Noetix DeliveryServer.exe.config file, which is located in <hard disk drive>:\Program Files\Noetix\NWQ\Delivery. For more information about the configuration file, see Noetix DeliveryServer.exe.config in “Maintenance.”

Noetix Add-in for Microsoft Excel

Noetix Add-in for Microsoft Excel (add-in) provides you an alternative approach to access and run the queries available in your instance of Noetix WebQuery (NWQ) from Microsoft Excel. The Report Browser of the add-in displays the queries that are available in the Public and Personal folders of NWQ. Any change made to the queries in NWQ is reflected in the add-in reports after the report is refreshed in the add-in.

The benefits of the add-in are the following:

• Run reports from several servers in one workbook.

• Convert the Query in Excel embedded queries to add-in reports.

• Access NWQ from the add-in.


About Noetix GeneratorThe Noetix generators for Noetix Platform are as follows:

• Noetix Generator for Noetix Platform—Oracle E-Business Suite Edition (Noetix Generator)

• Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator)

• Noetix Generator for Noetix Platform—Noetix Analytics Edition (Noetix Generator)

Noetix Generator for Noetix Platform—Oracle E-Business Suite Edition (Noetix Generator) exports the base views, user data, and security structure from your Noetix_Sys schema in the Oracle database to Noetix QueryServer (NQS) and Noetix WebQuery (NWQ) in Noetix Platform. This helps you to not only access your NoetixViews for Oracle E-Business Suite (NoetixViews) data in NQS and NWQ, but it also ensures that proper security is applied. Noetix Generator also generates prebuilt reports created by NoetixViews for Oracle E-Business Suite Administrator (NoetixViews Administrator). These reports provide immediate answers to many common business questions. For more information, see the Noetix Generator for Noetix Platform Administrator Guide for Oracle E-Business Suite.

Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator) exports the Noetix answers, the Noetix views on which the answers are based, and the security structure from your NOETIX_PS schema in the Oracle database to NQS and NWQ in Noetix Platform. This helps you to not only access your NoetixViews for PeopleSoft Enterprise (NoetixViews) metadata in NQS and NWQ, but it also ensures that proper security is applied to the generated users. Noetix answers provide immediate answers to many common business questions. For more information, see the Noetix Generator for Noetix Platform Administrator Guide for PeopleSoft Enterprise.

Noetix Generator for Noetix Platform—Noetix Analytics Edition (Noetix Generator) exports the base views, table information, and related folder information from your Active Mata Data Repository (AMDR) schema to NQS and NWQ in Noetix Platform. For more information, see the Noetix Generator for Noetix Platform Administrator Guide for Noetix Analytics.


About NoetixViewsNoetixViews unlocks the data hidden in corporate databases by providing user-friendly, plug-and-play business views of data, helping speed the flow of information throughout the enterprise. Customized to each unique database configuration, the automated install process cuts weeks off typical custom installations. NoetixViews provides the fast track to delivering familiar business terminology right to employees, partners, and customers.

By hiding complexity within metadata, NoetixViews simplifies and greatly accelerates report generation and ad hoc query creation, empowering decision-makers and front-line employees with timely and accurate access to critical information. Designed with integration in mind, the Noetix Platform extends the power of NoetixViews information to a myriad of third-party reporting and analytical tools.

NoetixViews is available for both Oracle E-Business Suite, PeopleSoft Enterprise, and Siebel Business Applications. For information on installing and managing NoetixViews, see your NoetixViews for Oracle E-Business Suite Administrator Guide, NoetixViews for PeopleSoft Enterprise Administrator Guide, or NoetixViews for Siebel Business Applications Administrator Guide respectively.

About NoetixAnswersNoetixAnswers immediately enhances the Noetix solution by providing instant answers to common business questions without complicated query development. NoetixAnswers uses the access and translation capability of installed Noetix products to deliver custom answers without the need to define data locations or write query code.

Available for NoetixViews modules, NoetixAnswers enables the power within the Noetix metadata to automatically map and create application-specific queries customized to each unique application configuration. With NoetixAnswers, Noetix delivers more than business views – it provides instant access to business information without taxing IT resources.

For more information about installing and managing NoetixViews, see the NoetixViews for Oracle E-Business Suite Administrator Guide, NoetixViews for PeopleSoft Enterprise Administrator Guide, or NoetixViews for Siebel Business Applications Administrator Guide.


About Noetix Logging ServiceNoetix Logging Service records the user actions and results of the prerequisites check done using the Noetix Platform Prerequisite Checker (Prerequisite Checker) standalone client or the prerequisites check done during the Noetix Platform installation. Noetix Logging Service also tracks the state of the installation on different computers in a typical multi-computer installation. A typical multi-computer installation involves installing Noetix Platform components on two, three or four computers. For more information, see the Noetix Platform Installation Guide.

The information recorded or tracked by Noetix Logging Service is stored in a log file. For more information about the log file, see About Log File.

Noetix Logging Service is installed on the computer on which you have installed Noetix QueryServer (NQS). This will be the first computer in a typical multi-computer installation.

Components of Noetix Logging ServiceNoetix Logging Service comprises the following components:

• RepositoryStateService: This service runs on the Noetix QueryServer (NQS) computer. It keeps track of the current installation state in a multi-computer installation and responds to requests from other computers (involved in a multi-computer installation) for the current installation state.

• ClientStateProxy: This is a proxy for RepositoryStateService and runs on computers other than the NQS computer in a multi-computer installation. Before the installation is started on the second, third, or fourth computer, ClientStateProxy remotely connects to the NQS computer (first computer) and requests the RepositoryStateService for the current installation state. Based on the current installation state, the installation wizard proceeds with the next component’s installation on the computer.


• RepositoryLoggingService: This service runs on the NQS computer. In a typical multi-computer installation, RepositoryLoggingService manages the synchronization of log files on other computers with the log files on the NQS computer. RepositoryLoggingService will continually run on NQS computer after installation because it is critical for the synchronization of log files.

• ClientLoggingProxy: This is a proxy for RepositoryLoggingService. In a multi-computer installation, it runs on computers other than the NQS computer. It synchronizes the log files on different computers with the log files on the central repository (NQS computer).

About Log FileLog files are created each time you run the Noetix Platform installation wizard or Noetix Platform Prerequisite Checker (Prerequisite Checker). You can distinguish the log files based on the time specified in the log file name. For more information about the naming convention of the log files, see Naming Convention of Log Files in “Maintenance.”

The information is immediately written to the log files on the local computer to prevent loss of any data. The log files created for the Noetix Platform typical multi-computer installation are periodically synchronized with the log files on the Noetix QueryServer (NQS) computer. Any non-public information is stored in an encrypted form in the log file.

A log file is complete or well-formed when a full run of the Noetix Platform installation wizard or Prerequisite Checker is completed. In a typical multi-computer installation, the log files can be used by Noetix administrators to have detailed information about the user selections and actions during installation, prerequisite checks, and installation state of a computer. The user can also send the log files to Noetix Technical Support for troubleshooting by attaching them to an e-mail message.



Types of Log FilesThe following types of log files are created by Noetix Logging Service:

• The .XML file is created during the installation or prerequisite checks. In a typical multi-computer installation, the .XML file on the NQS computer is synchronized with the .XML files on the other computers. This file records the user actions and components selected during installation and also the prerequisite check results.

• The .LOG file is created during the installation. However, in a typical multi-computer installation, the .LOG file on the NQS computer is not synchronized with the .LOG files on the other computers. This file has the information that is available when you click Show Details on the Installing page during the installation of Noetix Platform.

Location of Log FilesThe log files are created in <hard disk drive>:\Program Files\Common Files\Noetix\Logs on the local computer.

NOTE: If you have a Program Files folder in multiple hard disk drives (C, D, and E), the primary Program Files folder will be considered for storing the log files. To locate the primary Program Files folder, type %ProgramFiles% in the Address bar of Windows Explorer, and press ENTER.


How a Query is ProcessedWhen a user runs a query in Noetix WebQuery (NWQ), the request is sent through the Noetix components to be processed, translated, and returned to the user as data, as described in this section and the following diagram:

Figure 1.4 Query Flow Through the Noetix Platform


The logical query run by the user is sent to the Noetix Gateway (gateway) through HTTP GET and POST requests over TCP/IP (step 1 in Figure 1.4). The gateway sends the query to the NQS Connect ODBC driver (step 2). This driver sends the query to the Noetix QueryServer service (step 3). When NQS Connect and the Noetix QueryServer service are on separate servers, this is done using a series of DCOM calls using the network protocol available on the NWQ and Noetix QueryServer (NQS) servers (usually TCP/IP).

NOTE: When using a third-party query tool, the tool would send the query straight to NQS Connect without passing through the gateway.

The query is next processed and transformed by the NQS (step 4). NQS uses the metadata in the NQS repository and cost-based optimization algorithms to determine the optimal mapping of the logical query to a physical server. After NQS determines which physical server should handle the query, it transforms the query so that it is executable by this server. The transformed query, as well as connection information for the server, is sent back to NQS Connect (step 5), which sends the query through an RDBMS-specific ODBC driver (step 6) to the physical server (step 7). The physical server returns the query results through NQS Connect to the gateway (Step 8). The gateway transforms the query result set into an XML document, which it sends to NWQ through HTTP (step 9).


To the person using NWQ, it appears that a query has been run against the target database and their data has been returned, as in Figure 1.5. The query routing and other technical details are completely invisible.

Figure 1.5 Query Flow from a User’s Perspective

Setting Up Noetix PlatformAfter installing the Noetix Platform software and generating NoetixViews, it is recommended that you perform the following tasks to finish setting up your Noetix Platform environment:

1. Change SysAdmin password. For information, see Changing Passwords in “Users and Organizations.”

2. Start NQS Monitor. For information, see NQS Monitor in “Administrator Tools.”


3. Create administrative users. For information, see Administrative Users and Roles in “Users and Organizations.”

4. Configure other data sources and/or security structures in Noetix QueryServer (NQS). For information, see Servers and Connections and VTables and Mappings.

5. Review or customize Noetix WebQuery (NWQ) profiles. For information, see Profiles in “Security.”

6. Grant NWQ folder permissions. For information, see Granting Permission to an NWQ Folder in “Security.”

About the Use of E-Mail in Noetix Platform

Noetix Platform uses e-mail to deliver subscriptions to an e-mail address, send notifications about the success or failure of subscriptions and agent jobs, send alerts for the agent jobs, and send information related to a build in Noetix Generator Manager. This section provides information about how and when Noetix Platform uses the e-mail feature.

NOTE: To use e-mail in Noetix Platform, you must configure a Simple Mail Transfer Protocol (SMTP) server. For information about configuring an SMTP server, see the Microsoft documentation.

Noetix Platform uses e-mail to accomplish the following tasks:

• To deliver subscriptions to e-mail addresses using its e-mail delivery cartridge. Noetix Platform uses its e-mail delivery cartridge to perform this task. For information about delivering subscriptions to one or more e-mail addresses, see “Delivering a Query to One or More E-Mail Addresses” in the section “Creating and Customizing Queries” in the NWQ User Help.

• To send notifications about the success or failure of subscription deliveries and agent jobs using Microsoft SQL Server’s SQL Server Agent Mail, which uses Database Mail. For information about how Noetix Platform uses SQL Server Agent Mail for this task, see Setting Up an E-Mail Profile in “Maintenance.”


• To send alerts for the agent job using SQL Server’s SQL Server Agent Mail, which uses Database Mail. For information about how Noetix Platform uses SQL Server Agent Mail for this task, see Setting Up an E-Mail Profile in “Maintenance.”

• To send information related to a build in Noetix Generator Manager. Noetix Generator Manager, a Web-based tool of Noetix generators for Noetix Platform and NoetixViews for Siebel Business Applications (NoetixViews for Siebel), sends an e-mail message when a conversation in a build is waiting for user input for more than 15 minutes and when a build is completed, failed, or stopped. For more information, refer to the respective documentation of Noetix generators for Noetix Platform and NoetixViews for Siebel.

Chapter 2

Administrator Tools

This chapter provides an introduction to the administrative tools that are available for the Noetix Platform.


OverviewYou will use the following applications to administer your Noetix solution. To run these applications, you must have administrative privileges for each computer on which they are installed. To do this, add your user account to the Administrators group on each server or client computer. If you need assistance with this task, contact your system administrator.

• NQS Administrator: This is the primary tool you will use to administer the Noetix solution. Use this tool to administer users, security, Noetix QueryServer (NQS) servers and connections, and virtual tables (VTables) and mappings. You will also use this tool to access the Noetix Cache Maintenance Server and Noetix agent tools.

• NQS Service Manager: This tool allows you to start and stop Noetix QueryServer service.

• NQS Monitor: This tool allows you to track NQS and Noetix WebQuery (NWQ).

• NQS Query: This tool allows you to test queries built against the NQS VTables.

• NWQ: Within NWQ, you grant permissions to access NWQ folders and add/modify/delete NWQ folders. Users can also manage queries they own within their Personal folder, including publishing queries to the Public folder.

• NWQ Administrator: This tool allows you to grant or revoke permissions to NWQ features. Additionally, you can view a list of NWQ queries that a user owns and take ownership of a query.

Chapter 2: Administrator Tools 25

NQS AdministratorThe majority of administrative tasks can be accomplished using NQS Administrator. This application allows administrators to set up, optimize, and centrally manage your Noetix solution. Initial configuration should be done through this application.

You will also use NQS Administrator for Noetix WebQuery (NWQ) administrative tasks.

To open NQS Administrator:

1. Click Start > All Programs > Noetix Platform > Noetix QueryServer.

2. The logon window will be displayed. Log on initially as SysAdmin. This user is created automatically during installation. The name of the server on which the Noetix QueryServer service was installed should be entered in the Hub field. Click OK to log on.

NOTE: For security, it is recommended you change the SysAdmin password during your first session. For information about how to change the password, see Administrative Users and Roles in “Users and Organizations.”


3. NQS Administrator will open.

NOTE: Initially, the Administrator Wizards dialog box will display the setup tasks you will need to complete to configure Noetix QueryServer (NQS). Specific instructions on completing each of these tasks are listed throughout this guide.

Using NQS AdministratorThe administrator wizards are the easiest way to set up much of NQS. The wizard dialog opens automatically when you open NQS Administrator. You can also access the wizards by selecting Administrator Wizards from the Tools menu.

To make changes to objects or to set them up manually, you will use the property sheets in the main window of NQS Administrator. To open an object’s property sheets, first browse to the object using the left-hand menu (the Navigator) (1). When you select an object in the Navigator, the object’s path displays in the description bar (2) at the top right-hand side of the page. Under the description bar, the detail view (3) displays the child objects of the object selected in the Navigator. Objects that do not have children, (for example, users, connections, mappings) do not show up in the Navigator but are displayed in the detail view.


Below the detailed view, the property sheets (4) display the properties of the currently selected object. If you lose track of which object’s properties you are viewing, refer to the property sheet description (5).

The hierarchy of reporting objects and security objects you create in NQS is shown in the left-hand Navigator (1). These objects are explained throughout this guide.

NQS Service ManagerThe NQS Service Manager is used to start and stop the Noetix QueryServer service from the desktop, as well as well as configure Noetix QueryServer (NQS) to auto-start. The NQS Service Manager also displays whether NQS is running, and shows its progress as it starts.


To open the NQS Service Manager:

• Click Start > All Programs > Noetix Platform > Noetix QueryServer > NQS Service Manager.

The NQS Service Manager will open.

NOTE: Once the server is rebooted after the initial software installation, an NQS

Service Manager icon ( ) will show up in your system tray (located at the bottom right-hand corner of the page). You can also open NQS Service Manager by double-clicking this icon.The NQS Service Manager does not need to be open for NQS to run.

NQS MonitorNQS Monitor is a tool for the Noetix administrator to determine the frequency and the type of information that is being queried from the Noetix QueryServer service. Based on the statistical output, queries can be optimized by creating mappings to retrieve the data from the database more efficiently, caching the data, or by creating a reporting server that takes the load away from the production system.

You can use NQS Monitor for the following tasks:

• Tracking Noetix QueryServer service and Noetix WebQuery (NWQ) usage.

• Tracking user activity.

• Tracking virtual tables (VTables), mappings, connections, servers, and query times.


• Tracking physical server response time.

• Accessing statistical counters, charts, and graphs for analysis and tracking.

For detailed information about the tool, see the NQS Help.

NOTE: When first installed, the NQS Monitor will be turned off (not tracking or logging). You will need to turn on NQS Monitor to begin collecting data.

To open the NQS Monitor:

1. Click Start > All Programs > Noetix Platform > Noetix QueryServer > NQS Monitor.

- OR -

In NQS Administrator, on the Tools menu, click Monitoring.

2. The Log On window appears. Log on as sysadmin with the sysadmin’s password or as a user assigned the N$QueryAnalyzers role. The name of the server on which the Noetix QueryServer service was installed should be entered in the Hub field.

Click OK to log on.


3. NQS Monitor will open. To start tracking, click on the toolbar.


4. The Monitor Control dialog appears. Do one or both of the following:

• To begin tracking Noetix QueryServer (NQS), click Start in the Noetix QueryServer area.

• To begin tracking NWQ, click Start in the Noetix WebQuery area.

5. Once you have collected data, you can use the following NQS Monitor features to help you analyze and troubleshoot the system:

• Query Log: Displays detailed information about queries that have been processed by NQS, such as user, organization, VTable, mapping, processing times, curser times, and so on. This information is extremely valuable when troubleshooting.

• DDL Log: Displays entries of the NQS Data Definition Language (DDL) calls that are used to create objects in NQS, such as users, VTables, roles, and so on.

You can save the DDL calls and later run the file in NQS Query. That script will then create all of those objects from the DDL.


• NQS Usage Analysis: Displays summary information, such as total rows returned in queries and the average query time. You can easily group the data by user, server, VTable, mapping, and so on.

Using this feature, you can also export a subset of the NQS Monitor data to Microsoft Excel and automatically generate a pivot table. The data can then be manipulated further, or saved for future reference.

This information can be useful when troubleshooting performance issues.

• NQS Real-Time Monitoring: Displays dynamic information on current NQS usage, such as total number of cursors currently opened against the database, the total number of users logged on to the system, and a list of all users currently logged on to the system.

NQS QueryNQS Query enables administrators to construct ad hoc queries against any RDBMS data source through the Noetix QueryServer service for diagnostic and testing purposes. You may use this tool to assist you in common setup or troubleshooting tasks.

For detailed information about using the tool, see the NQS Help.

To open NQS Query:

1. Click Start > All Programs > Noetix Platform > Noetix QueryServer > NQS Query.

- OR -

In NQS Administrator, click on the toolbar.


2. The Log On window appears. Log on as an administrative user, or as sysadmin with the sysadmin’s password. The name of the server on which the Noetix QueryServer service was installed should be entered in the Hub field.

Click OK to log on.

3. NQS Query will open. To run a query, enter the query on the Query tab, and then

click .


4. The results will be displayed on the Results tab. You can sort or filter the results, or search for specific data. For more information, see the NQS Help.


5. You can also open NQS Query by executing a query directly against a virtual table (VTable) within NQS Administrator. The results will be displayed on the Results tab in NQS Query.

To do this, right-click the VTable in NQS Administrator, and then select one of the following:

• If you want to return all rows, select Return All Rows.

• If you want to limit the rows returned, select Return Top. When prompted, enter the number of rows to return, and then click OK.


NWQThe Noetix WebQuery (NWQ) application is where most end users will access NoetixViews, NoetixAnswers, and other data. Management features such as granting or revoking access to Public folders and publishing reports to other users can also be done in NWQ.

NOTE: When a user is authenticated against Oracle E-Business Suite, NWQ will prompt the user to choose what Oracle responsibility he or she wants to log on with. To switch between responsibilities, a user can log off, and then log on again with another responsibility.

Browse and Manage ModesYou can use NWQ in two different modes—Browse and Manage.

• The Browse mode supports most options to find, view, and run queries. You will always be in the Browse mode when using queries from the VTables folder. When you are in the Browse mode, a switch to manage link displays.

• You can switch to the Manage mode to create, rename, edit, or delete Public or Personal subfolders, as well as grant permissions to Public folders. In Manage mode, you can also delete, copy, move, or publish (from the Personal folder only) groups of queries at once, instead of one-by-one. When you are in Manage mode, a switch to browse link displays.

To start NWQ:

1. Open your Web browser.

2. Type http://<computer name>/nwq/login.htm, where computer name is the name of the computer on which NWQ is installed. If your organization policy requires the use of Secure Sockets Layer (SSL) for encryption of user credentials and data, type https://<computer name>/nwq/login.htm.


3. The logon page will be displayed. Enter your Noetix QueryServer (NQS) user name and password. (For administrative purposes, log on as a user who has been granted the N$WebQueryAdmin and N$WebQueryProfileAdmin roles in NQS.)

NOTE: Using the SysAdmin account to log on to NWQ is not recommended. Some query features, such as sharing, behave differently for the SysAdmin user. Create a new user account for each individual who needs to use NWQ, and grant these accounts administrative privileges as appropriate.


4. The My Web Queries page will appear. When administering NWQ, you will use the following features:

• Navigator menu: Use the Navigator Menu to help you get around NWQ. Simply click the Navigator button to activate the menu, then click again to close it. You can pin the Navigator open by clicking the pushpin icon in the corner of the Navigator menu.

The menu will contain different options, such as Change Password, NWQ Administrator, and Save, depending on the page you are viewing.

• Modes link: Use this link to switch between the manage and browse modes. To manage folders and folder permissions, you need to be in manage mode.

• Folder management links: These links are displayed when in the manage mode. These links allow you to rename, edit, or delete a folder, add a new subfolder, or modify the current folder’s permissions.


NWQ AdministratorNWQ Administrator provides access to the NWQ Profiles feature of Noetix WebQuery (NWQ). The tasks that can be handled through NWQ Administrator are in addition to those managed within Noetix QueryServer (NQS).

To start NWQ Administrator:

1. Open your Web browser.

2. Type http://<computer name>/nwqadmin/login.aspx, where computer name is the name of the computer on which NWQ is installed. If your organization policy requires the use of Secure Sockets Layer (SSL) for encryption of user credentials and data, type https://<computer name>/nwqadmin/login.aspx.

The application can also be opened from the Navigator menu within NWQ or from NWQ Administrator (on the Tools menu, click NWQ Administrator).

3. The logon page will be displayed. Type the NQS user name and password for a user granted the N$WebQueryProfileAdmin role.


4. The NWQ Administrator Queries tab will display. On this tab, you can view all NWQ queries, generate a list of queries a specific user owns, or delete or take ownership of a query.


5. To view a list of NWQ subscriptions, click the Subscriptions tab. On this tab, you can search for or delete a subscription and also filter subscriptions by a user or all users. To navigate to the Subscription Schedules page to view the delivery schedules

for a query, click the button.

6. To view NWQ subscription schedules, click the Subscription Schedules tab. On this tab, you can search, delete, and enable subscription schedules.


7. To manage NWQ profiles, click the Profiles tab. From this tab, you can manage the profile permissions to control access to NWQ features.

8. To view a query’s usage by a user or all users, click the Usage by User tab. On this tab, you can type a word or phrase to retrieve queries that match the search criteria or you can type a date range to retrieve the queries used in that range.


9. To view the summary of usage of a query, click the Usage by Query tab. On this tab, you can type a word or phrase of the query that you want to search for or you can type a date range to retrieve the queries used in that date range.

Chapter 3

VTables and Mappings

The building blocks of Noetix QueryServer (NQS)—virtual tables (VTables) and mappings—are explained in this chapter, along with a high-level overview of working with these objects.


OverviewOne of the key benefits of Noetix QueryServer (NQS) is that it provides a single point of access to multiple data sources, both for reporting and for maintenance. The flexible reporting model, based on the idea of virtual tables (VTables), makes this possible.

This section explains the NQS reporting model, how queries are handled by NQS, and how to manage enterprise data at the table level.

VTable ArchitectureVirtual table (VTable) is the core of reporting against NQS. You can use VTables to map information in columns from physical database tables to NQS and create an optimal configuration of enterprise information. Any tables in your databases that you want to report against through Noetix are defined in NQS by using VTables.

A VTable is similar to a view in Oracle or Microsoft SQL Server. A view is an out-facing set of columns that are filled by a SQL statement retrieving data from one or more tables. The view doesn’t store any information; it just provides the user with a specific view of the data. If you want to create a view, the basic syntax looks like the following:

CREATE VIEW (column1, column2, column3)AS (SELECT a_column, another_column, yet_another_columnFROM table1, table2WHERE table1.column = table2.another_column)

A VTable works in the same way. A VTable starts as a list of out-facing columns, just like the column list (column1, column2, column3) from the CREATE VIEW statement above. When a user queries the VTable, they see these out-facing columns. These columns can be given any name and don’t have to be the same as the columns from the underlying database.

Once you have defined your column set, you need to define a query to fill the columns. This is done with the VTable’s mapping. A mapping links the columns in the VTable to data in a physical database, just like the SQL statement portion of the CREATE VIEW statement above (select a_column, another_column, yet_another_column from table1, table2 where table1.column = table2.another_column) links actual data to the columns defined in the view.

Chapter 3: VTables and Mappings 47

When you run a query against a VTable, NQS in turn runs the query defined in the mapping against the physical database to return data to the user, just like querying a database view. Also just like a database view, a VTable doesn’t store any data. It just provides a way to view it.

The separation of the column list and mapping in NQS makes VTables much more powerful than database views. A database view can only have one SQL statement to fill the out-facing columns. However, a VTable can have multiple mappings for this purpose. When a query is run, NQS uses a complex algorithm that determines which mapping should be used based on criteria such as permissions, as well as the structure of the SQL statement. This provides administrators with a way to redirect a user’s query to different tables or even a different database. This can be used to direct users to local copies of their data to minimize network traffic, direct users to pre-aggregated versions of their data to minimize query time, and so on. Creating multiple mappings in this way is optional, and an advanced task. For more information about mappings, see Mappings.

Simplified Data AccessThis flexible architecture of virtual tables (VTables) and mappings gives the administrator the power to manage enterprise data access in a variety of ways to best suit the reporting needs of the company. Individuals in the company who need access to this data, however, do not need to be bothered by structural information (servers, connections, tables, and stored procedures) and technical details (network paths and protocols, server names, and cryptic formulas).

When end users access NQS using a query tool or Noetix WebQuery (NWQ), they see the VTables available to them, with names and columns the administrator has set up using business terminology, and none of the technical details. Users can write reports against these VTables without regard to where the data is stored or what mapping is being used to retrieve the data for the report.


Before You BeginDetermine reporting needs: It is a good idea to do some planning before you start creating virtual tables (VTables) in NQS. While you have a lot of flexibility in that you can rename folders, subfolders, and VTables, or move these objects around, once your users start building reports based on these objects, any changes you make can break these reports.

Before creating VTables, decide what folders and subfolders will make sense to your users, as well as which database objects should be imported into NQS. Decide whether you will create VTables to act as views, which users can create their own queries against, or to correspond directly to reports, which will require more maintenance by the system administrator or report developer.

If a database object is too complex for your users (for example, too many columns) you should consider creating a Complex VTable that does not have all of the columns of the physical object or that joins multiple tables or views together. If your database is highly normalized, you will probably want to use the Complex Virtual Table Wizard and denormalize any IDs or lookups.

VTables and VViewsVirtual tables (VTables) and virtual views (VViews) are the reporting objects your users will base their queries on in Noetix WebQuery (NWQ) or other query tools. VTables are based on tables or views that already exist in a database in your enterprise. VTables are closely related to database views in that they do not store any data but instead reference other tables or views using SQL. The advantage of VTables in Noetix QueryServer (NQS) over database views that live in a particular database is that VTables can be configured to intelligently span multiple databases.

VViews give you more options to join and configure these VTables in NQS. A VView is a special kind of VTable that is based on other VTables you have already created in NQS. VViews enable you to build more and more Complex VTables on top of those VTables that you have already defined.


If a report needs to be created against multiple VTables, they can be joined into a VView using NQS Administrator. Creating VViews requires advanced knowledge of SQL and joining tables from your particular data sources.

NOTE: In NWQ, users can be granted permission to create VTable joins in addition to those created in NQS. For more information about VTable joins in NWQ, see the NWQ User Help.

VViews can join VTables that point to different physical databases. To do this, each VTable first needs a heterogeneous mapping against the same heterogeneous mapping server. For more information about heterogeneous mappings, see Creating a Heterogeneous Mapping.

After you set up these reporting objects in NQS Administrator and grant permissions to them, users can run them as queries from NWQ.

It is a good idea to do some planning before you get started creating VTables in NQS. You may want to list all the sources you need to import tables and views from, as well as how to effectively organize them into folders and subfolders. While you have a lot of flexibility in that you can rename folders, subfolders, and VTables, as well as move these objects around, once your users start building reports based on these objects, changes you make will break these reports.

Simple VTablesA simple virtual table (VTable) is a one-to-one reference to an existing database table or view definition. To access an existing database view or report in NQS, set it up as a simple VTable.

Create a simple VTable to:

• Import a table already in a database in your enterprise.

• Create a VTable from a custom view in your database.

• Import a table or view so you can then create more complex objects from it.


Complex VTablesA complex virtual table (VTable) also imports table or view definitions from existing data sources, but can join multiple tables or views together and uses a complex SQL statement. Complex VTables allow you to join tables so they can be queried against in NWQ.

NOTE: In NWQ, users can be granted permission to create VTable joins in addition to those created in NQS. For more information about VTable joins in NWQ, see the NWQ User Help.

Create a complex VTable to:

• Import and join multiple tables and views for users to build reports against.

• Build complex SQL statements against multiple tables.

• Build a SQL statement to limit the number of columns included in a VTable.

VViewsA virtual view (VView) is a virtual table (VTable) that is based on other VTables you have already created in NQS. This is very similar to creating a view based on one or more existing views.

Create a VView to:

• Join simple or complex VTables that you've already created or imported in NQS.

• Build more complex VTables on top of those VTables that you have already defined.

Creating a Simple VTableBefore you begin:

• Make sure you have set up a server in Noetix QueryServer (NQS) corresponding to the data source or database from which you want to import the table or view.

• Make sure the connection to this server has access to the table or view.

To create a virtual table (VTable), use the Simple Virtual Table Wizard. The wizard walks you through each step of creating simple VTables from existing database tables or views. If you need more information about any of the steps involved, click the Help button.


To create a simple VTable:

1. In NQS Administrator, click on the toolbar.

2. The Administrator Wizards dialog box appears. On the Basic Setup tab, double-click Simple Virtual Tables Wizard.

3. After the introductory pages, the wizard prompts you to select a server. Select the server from the list, and click Next. (If the server you want to import from is not in the list, click the Add new server button to set it up.)

4. Select the connection to use to connect to your database. (If an appropriate connection has not yet been set up, click Add new connection to create one.) Click Next.

On clicking Next, the Which tables to setup page appears.

5. Select the tables to import. When you reach this page, the wizard will connect to your database (using the default user and password of the connection chosen) and fetch the objects owned by this database user.

NOTE: Before the Which tables to setup page appears, you might see the Loading dialog box depending on the size of the metadata in the selected database. You can click Abort or Cancel to stop loading the metadata if you have selected a wrong data source or if the metadata is taking a long time to load. Clicking Abort stops the loading process immediately and might leave some traces of incomplete data. Clicking Cancel stops the loading process at a logical point, and it might take longer. However, clicking Abort or Cancel does not close the wizard.

On the left-hand side of the page, you will see a schema tree and object types. On the right-hand side, you will see a list of the objects owned by the node that is currently selected in the tree. By default, this page displays the tables owned by the database user.

A simple VTable is created for each table or view you select in this page. You can quickly select all objects of the current type under a node by selecting its check box. You can also quickly select all or none of the items in the right-hand list by selecting the Select All or Select None buttons. Click Next when you are finished.

6. (Optional) The next page allows you to create descriptions for the new VTables. You may change these later as well. Click Next to continue.


7. Next, select the folder or subfolder in which to put this new VTable. You may create a new folder or subfolder or select existing ones. Click Next to continue.

For more information about folders and subfolders, see Organizing VTables.

8. The Processing Duplicates page asks you what NQS should do if a VTable of the same name already exists in the subfolder you selected. Select an option, then click Next to continue.

9. (Optional) Select a log file or accept the default. This page also prompts you for whether to use heterogeneous mappings. If there is a chance you might want to join this VTable to another VTable in the future, ensure that this check box is selected. Click Next to continue.

10. (Optional) The Initial Security page allows you to grant permission to this VTable. You can do this later or choose to do it now if you have already set up users and roles in NQS. Click Next when you are finished.

11. (Optional) Next, select any custom name options you want to use, and then click Next to continue.

12. (Optional) Select any category you want to add to this table, and then click Next to continue.

NOTE: Categories are currently used within NQS only, but may have additional functionality for NWQ in an upcoming version.

13. The last page shows you an overview of what you are importing. Click Finish to import the tables or views.

Creating a Complex VTableBefore you begin:

• Decide which objects you want to import and how you want to join or limit them.

• Ensure you have set up a server in Noetix QueryServer (NQS) corresponding to the data source or database from which you want to import the table or view.

• Ensure that the connection to this server has access to the table or view.


The Complex VTable Wizard helps you in creating a complex virtual table (VTable) from existing database tables or views. If you need more information about any of the steps involved, click the Help button.

To create a complex VTable:

1. In NQS Administrator, click the on the toolbar.

2. The Administrator Wizards dialog box appears. On the Maintenance tab, double-click Simple Virtual Tables Wizard.

3. Click the Maintenance tab, then double-click the Complex Virtual View Wizard.

4. After the introductory pages, the wizard prompts you to select the folder and subfolder in which to put this new VTable. You may create a new folder and subfolder or select existing ones. Click Next to continue.

For more information about folders and subfolders, see Organizing VTables.

5. Enter a name for the new VTable. You may customize the name of the mapping and add a description if you want. Click Next to continue.

6. The wizard prompts you to pick a server. Select a server from the list and click Next. (If the server you want to import from is not in the list, click the Add new server button to set it up.)

7. Select the connection to use to connect to your database. (If an appropriate connection has not yet been set up, click the Add new connection button to create one.)

8. Next, build the SQL code for the complex VTable. You may write the SQL code from scratch or click the Build SQL button to use the Query Builder tool.

If using Query Builder, first select the tables, expanding and dragging each window until they are easy to work with. Specify the columns (by double-clicking them) and criteria (by typing in the appropriate SQL code). To join tables, drag a column from one table onto a column in another that can be joined (for instance, the same Z$ column in each view). Click Close and keep changes when finished with Query Builder.

Click Next to continue.


9. The Virtual View Structure page displays the columns for your VTable that are returned by the SQL you entered in the previous page. The wizard detects the columns' data types, length, scale, and so on. If you want, you can add a description for these columns.

10. This page lets you make the association between the columns that are being returned from the Record Source SQL (on the left) and the columns in the new VTable (on the right).

The wizard should have these matched up one-to-one between the two column sets.

To manually make an association, select the Record Source column from the list in the left-hand cell. Then, in the right-hand cell, either type the VTable expression or open the Expression Editor. Click Next to continue.

11. This page prompts you for whether to use heterogeneous mappings. If there is a chance you might want to join this VTable to another VTable or virtual view (VView) in the future, ensure this check box is checked. Click Next to continue.

12. (Optional) The Initial Security page allows you to grant permission to this VTable. You can do this later or choose to do it now. Click Next when you are finished.

For more information about permissions, see Granting Permission to a Role in “Security.”

13. (Optional) Select any category you want to add to this VTable, and then click Next to continue.

NOTE: Categories are currently used within NQS only, but will have additional functionality for NWQ in an upcoming version.

14. The last page shows you an overview of what you are importing. Click Finish to import the table or view.


Creating a VViewTo create a virtual view (VView), use the Virtual View Wizard. The wizard walks you through each step of creating a VView from existing virtual tables (VTables). If you need more information about any of the steps involved, click the Help button.

To create a VView:

1. In the NQS Administrator, click the on the toolbar.

2. The Administrator Wizards dialog box appears. On the Maintenance tab, double-click Virtual View Wizard.

3. After the introductory pages, the wizard prompts you to select the folder or subfolder in which to put this new VView. You may create a new folder or subfolder or select existing ones. Click Next to continue.

4. Enter a name for the new VView. You may customize the name of the mapping and add a description if you want. Click Next to continue.

5. Build the SQL code for the VView. You may write the SQL code from scratch or click the Build SQL button to use the Query Builder tool.

If using Query Builder, first select the tables, expanding and dragging each window until they are easy to work with. Select the columns (by double-clicking them) and criteria (by typing in the appropriate SQL code). To join tables, drag a column from one table onto a column in another that can be joined (for instance, the same Z$ column in each view). Click Close and keep changes when finished with Query Builder.


6. The Virtual View Structure page displays the columns that are returned by the SQL you entered in the previous page. The wizard detects the columns' data types, length, scale, and so on. If you want, you can add a description for these columns.


7. This page lets you make the association between the columns that are being returned from the Record Source SQL (on the left) and the columns to be created in the VTable (on the right).

The wizard should have these matched up one-to-one between the two column sets.

To manually make an association, select the Record Source column from the list in the left-hand cell. Then, in the right-hand cell, either type the VTable expression or open the Expression Editor. Click Next to continue.

8. (Optional) The Initial Security page allows you to grant permission to this VView. You can do this later or choose to do it now. Click Next when you are finished.

9. (Optional) Select any category (see below) you want to add to this VView, and then click Next to continue.

NOTE: Categories are currently used within Noetix QueryServer (NQS) only, but will have additional functionality for Noetix WebQuery (NWQ) in an upcoming version.

10. The last page shows you an overview of the VView you are creating. Click Finish.

Modifying a VTableThe Table Change Wizard walks you through the steps necessary to change a virtual table (VTable) in Noetix QueryServer (NQS).

NOTE: If there is no mapping defined for a VTable and you run the Table Change Wizard for the VTable, then an error message is displayed.

The wizard helps you do the following:

• Add a new column to a VTable

• Rename a column

• Delete a column

NOTE: When a complex VTable or virtual view (VView) is deleted, the obsolete change alerts remain in all the VTables that the deleted complex VTable or VView used as the data sources. If you see such change alerts and find the referenced complex VTable orVView deleted, you can either ignore the change alerts or manually delete them from the repository. The change alerts are stored in the IM_Notes table of the nqsdb database in Microsoft SQL Server.


To add a column to a VTable:

1. Right-click on the VTable you want to modify, and on the shortcut menu, click Table Change Wizard. The welcome page appears.

2. Select Add new columns, and click Next. The Choose the Mapping page appears.

3. In the Choose the Mapping page:

• If the VTable has a single mapping, then the mapping is selected by default.

• If the VTable has multiple mappings, then select the mapping you want to modify.

Click Next. The Modify the column mappings page appears. The new columns that are available to be added from the source table in the database will be displayed.

NOTE: For simple VTables, if a mapping maps all of the columns in the underlying database table or view, the wizard will detect this and display a message to the user stating that no additional columns can be added. However, if a simple VTable contains a mapping that does not map all of the columns in the underlying database table or view, the wizard will allow additional columns to be added to the mapping and the VTable, or just the mapping.

4. Select the check boxes next to the columns you want to add to the VTable. By default, the column name in the VTable Column list is the same as the column name of the base table. You can change the column name in the VTable Column list. Click Next. The Completing the Table Change Wizard page appears. The page provides information about the columns that will be added to the VTable.

5. Click Finish. The selected columns will be added to the VTable.


To rename or delete an existing VTable column:

1. Right-click on the VTable you want to modify, and on the shortcut menu, click Table Change Wizard. The welcome page appears.

2. On the welcome page, select one of the following:

• Rename columns: If you want to rename a column in the VTable.

• Delete virtual table columns: If you want to delete a column in the VTable.

Click Next. The Modify the virtual table columns page appears.

3. In the Modify the virtual table columns page, do one of the following:

• If you selected Rename columns in step 2, then the Name field will be editable. Edit the column names as required. After you edit a column name, the font color changes to blue and font style changes to italic.

• If you selected Delete virtual table columns in step 2, then select the check box next to each column you want to delete.

Click Next. The Completing the Table Change Wizard page appears. The page provides information about the changes that will be made to the VTable.

4. Click Finish.

IMPORTANT: If the object you are modifying or deleting is created by Noetix Generator for Noetix Platform—Oracle E-Business Suite Edition (Noetix Generator), Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator), or NoetixViews for Siebel Business Applications (NoetixViews for Siebel), the Change Alert dialog box appears. Changing these objects manually might result in loss of information during regeneration. Click OK to proceed with the change (renaming or deleting the column) or click Cancel to abort the change and close the Table Change wizard.


Granting Permissions to a VTableA user must have certain permissions to query a virtual table (VTable) or virtual view (VView) from either Noetix WebQuery (NWQ) or a third-party reporting tool.

To allow the users to run queries against a VTable, ensure the following permissions have been granted:

• Grant the users permission to the VTable or View and Mappings: This can be done implicitly (through organizations or roles) or explicitly (directly granting permissions to specific users), using NQS Administrator. For more information about permissions, see Granting Permission to a Role in “Security.” For more information about accessing mappings, see Mappings.

• Grant the users permission to the necessary connections: When a query is run against a VTable, it uses one of the connections you created for that data source. The user will need permission to this connection as well, either implicitly (through organizations or roles) or explicitly (directly granting permissions to specific users), using NQS Administrator. For more information about permissions, see Granting Permission to a Role in “Security.” For more information about connections, see Connections in “Servers and Connections.”

For information about making a VTable display in NWQ, see Exposing VTables in NWQ in “Web Queries and Folders.” For information about making a VTable display in a third-party tool, see Granting a Default Subfolder.

NOTE: Although you can grant an object explicit permission to a server, Noetix recommends granting permission to a role, and then assigning users and/or organizations to that role.


Organizing VTablesThe reporting objects you create or import in Noetix QueryServer (NQS) are organized into folders and subfolders under the VTables folder. When querying a virtual table (VTable), the “path” of that object reflects the folder and subfolder hierarchy. For example, if you create a folder named NY, and within it, a subfolder named sales and then save a VTable named invoices within that subfolder, you could query the table from NQS Query or a query tool using the syntax SELECT * FROM ny.sales.invoices. In Noetix WebQuery (NWQ), this full path also displays in the properties of a query.

Since the names of folders and subfolders will be displayed to end users, choose a folder structure and names that not only make them manageable but also have meaning to users in your enterprise.

FoldersVirtual tables (VTables) and virtual views (VViews) are grouped into folders and subfolders. You decide what to name these folders to help your users find the information they are looking for, as well as to make it easier to grant permission to groups of like objects at once.

Reporting objects cannot be stored directly in a folder; they must be stored in a subfolder. However, you can grant permissions at the folder level if you choose. For more information about permissions, see Granting Permission to a Role in “Security.”

Create a folder to:

• Organize VTables so they are easy to manage.

• Be able to grant permission to a set of VTables at once, instead of granting each individually.

SubfoldersA subfolder is a folder within a folder, which can be used to organize reports by subject, task, or other manageable units. More importantly, a subfolder can be set as a default subfolder for a user or role, which makes the contents of the subfolder show up in query tools and NWQ (under the VTables folder) for that user or members of that role.


Create a subfolder to:

• Organize queries into a detailed folder structure.

• Give a user access to the virtual tables (VTables) in a certain subfolder (by granting it as a default subfolder).

Creating a FolderTo create a folder:

1. In NQS Administrator, right-click on VTables in the left-hand pane.

2. From the menu, select New Folder. The New Folder properties page displays to the right.

3. On the General tab, type the name of the new folder, as well as a description and maximum number of rows to return in a query, if required.

4. (Optional) On the Notes tab, you may add notes to this folder. (You must click Save before adding a note.)

5. On the Permissions tab, specify any required permissions to users or roles.


6. Click Save when finished.

Folders can also be created when you are importing or building virtual tables (VTables). You can name the new folder and later specify any other required properties for the folder.


Creating a SubfolderTo create a subfolder:

1. In the NQS Administrator, right-click on VTables in the left-hand pane.

2. From the menu, select New Subfolder. The New Subfolder properties page displays to the right.

3. On the General tab, type the name of the new subfolder, as well as a description and maximum number of rows to return, if required.

4. (Optional) On the Notes tab, you may add notes to this subfolder. (You must click Save before adding a note.)

5. On the Permissions tab, specify any required permissions to users or roles.


6. Click Save when finished.

Subfolders can also be created when you are importing or building virtual tables (VTables) and virtual views (VViews). You can name the new subfolder and later specify any other properties for the subfolder.

NOTE: To prevent a reduction in performance while opening the subfolder in NWQ, take care to not add too many reporting objects to a single subfolder.

Moving a VTable to Another SubfolderYou can move a virtual table (VTable) or virtual view (VView) to another subfolder by selecting it, then dragging and dropping into the required subfolder. You may also right-click on the VTable, choose Cut from the menu, right-click on the destination, and choose Paste.

CAUTION: Be aware that if users have built reports from these objects, the reports may break if you move the underlying VTables.


Granting a Default SubfolderA subfolder is displayed in NWQ (in the VTables folder) or a third-party query tool when the logged-on user has been granted the subfolder as a “default subfolder,” either implicitly (through organizations or roles) or explicitly (directly granting permissions to specific users). A user will only be able to access an object that is within one of these default subfolders.

For information about making a reporting object display for a user in NWQ, see Web Queries in “Web Queries and Folders.”

To grant a default subfolder:

1. In NQS Administrator, double-click the user, organization, or role to which you want to grant the default subfolder.

2. Click the Default Subfolders tab.

3. Click within the white text area to display the ellipses button ( ).

4. Click the ellipses button to open the Locate Subfolder window. A tree of current folders and subfolders appears.

5. Browse to and select the required subfolder, and then click OK.

6. The subfolder is listed in the text area. Select the ellipses button in the empty text area below to add more default subfolders, or click Save to finish.

The user should now have access to the subfolder and its contents in NWQ or a third-party query tool.

To be able to run the virtual table (VTable) or any reports against it, ensure the user has permission to query the underlying VTable. For more information about permissions, see Granting Permissions to a VTable.

If a user has permission to an item that is not in one of his or her default subfolders, the item will not display in the VTables folder of NWQ. If a user has been granted a default subfolder but not granted permission to the object, the object will display, but the user will not be able to open or run it.


MappingsEvery virtual table (VTable) in Noetix QueryServer (NQS) has a mapping, which is the SQL that maps the VTable to the physical tables in your database. Users only interact with VTables, but the data they request is returned by a mapping. This can be a 1:1 mapping against a particular table in the database, or can be highly customized for security or performance improvements. A VTable can have multiple mappings, each tuned for a specific purpose.

When you create a VTable using the NQS Administrator wizards, a 1:1 mapping is created by default. This means that any query against this VTable uses the same mapping, and the mapping retrieves every column included in the VTable. Most of the time, these 1:1 mappings are sufficient.

In Figure 3.1, the Customers VTable and its 1:1 mapping in NQS point to a data source called US Customers. The VTable shows the columns and the mapping shows the SQL sent to the data source.

Figure 3.1 VTable with a Default 1:1 mapping


You can create additional mappings as required to route certain users or queries to different physical tables, or to simply use different SQL. In Figure 3.2, a custom mapping has been added that points to a different data source, CA Customers Only. Queries against the Customers VTable can now be routed to either of these data sources.

Figure 3.2 VTable with Custom and Default 1:1 mappings

The following sections describe how to set up these custom mappings in NQS. For information about the reasons why you may choose to create a custom mapping, see Examples of Custom Mappings.

Creating custom mappings requires an understanding of your data and how it is structured in the database. Most of the examples listed require additional (non-NQS) activity on the database. Creating and maintaining aggregations, partitions, and so on, is not an easy task and should be relegated to an ETL tool.


MappingsA mapping describes where and how data should be found in the physical database when a user queries against a virtual table (VTable). Multiple mappings can be created for a single VTable, each tuned for a specific purpose or based on a specific expression in the query.

When you create a mapping, you define the server; the connection (or schema) that owns the tables; the Record Source (which is the SQL used to query the database); a list of the columns the mapping can retrieve; and the mapping's cost, or order of priority. Optionally, a mapping can include a virtual dimension (VDimension), a virtual filter (VFilter), and/or a heterogeneous mapping, described below.

Create a mapping to:

• Speed up lookups by routing queries against a single column (for instance, to populate a list of values (LoV)) to a targeted physical table.

• Create column-level security by restricting access to sensitive columns of a VTable (such as Salary).

• Optimize access by location, routing queries against regional servers or reporting servers when appropriate.

• Route users to specific servers (for instance, routing users who need up-to-the-minute data to an OLTP server and other users to a reporting server).

NOTE: Mappings use the vertical partitioning concept. For more information about vertical partitioning, refer to your database documentation.

VDimensionsVirtual dimensions (VDimensions) can be added to a mapping to specify an aggregation (such as sum, avg, min, or max) that must be present in the query in order for the mapping to be used.

Create a VDimension to:

• Route queries based on an aggregation that you set up.

• Point queries that summarize detailed data to summary tables instead, for better performance.

NOTE: VDimensions use the aggregate partitioning concept. For more information about aggregate partitioning, refer to your database documentation.


VFilterA virtual filter (VFilter) can be added to a mapping to specify a condition that must be present in the query in order for the mapping to be used. That is, the query must be filtered by particular criteria.

Create a VFilter to:

• Cause a mapping to be chosen based on a portion of the WHERE clause in the query.

• Point queries against a limited result set to a different table or server that can more efficiently retrieve them.

NOTE: VFilters use the horizontal partitioning concept. For more information about horizontal partitioning, see your database documentation.

Heterogeneous MappingsA heterogeneous mapping can be added to a mapping to allow the virtual table (VTable) to be used in cross-database reporting. Heterogeneous mappings bring together data from different servers, or even different database types (for instance, joining a table in an Oracle database to a table in a Microsoft SQL Server database). By creating a heterogeneous mapping, you are defining an alternative route, through the heterogeneous mapping server (HMS), that Noetix QueryServer (NQS) can use to retrieve data. When multiple VTables are defined that use the same alternative route, these tables can be combined into a single query or SQL statement.

A heterogeneous mapping gets its data the same way, and from the same place, as the regular mapping it is based on, but it takes an alternative route through the HMS.

Create a heterogeneous mapping to:

• Provide a mapping to allow a single report to get data from different databases or database types.

• Allow VTables using data from different servers to be joined together.


Which Mapping Will NQS Use?When a given user sends a query or SQL statement to NQS, the Noetix QueryServer service must pick the best mapping for the job from the list of mappings for that virtual table (VTable). The mapping is then used to determine where to retrieve the data from. NQS chooses which mapping to use by evaluating the following three criteria:

• Permissions: First, the user running a query must have permissions to the mapping and to the connections the mapping uses. If the user executing the query does not have these permissions, NQS will not allow the mapping to be used; it will evaluate the next mapping, until one is found that the user can access. If the user does not have permissions to any of the existing mappings, NQS will return an error message instead of the query results.

• Completeness: A mapping doesn't need to include every column in the VTable; it can include a subset of the columns instead. Because each mapping can be different in this way, NQS evaluates the mapping to ensure it satisfies the requirements of the query. If the mapping does not include everything needed in a query (for example, a column is missing), NQS will not use the mapping. It will move on to the next mapping, evaluating it in the same way until an appropriate mapping is found. NQS can only use a mapping that can return at least the columns asked for in the SELECT clause of the query.

• Cost: Every mapping has a cost value from 0 (the lowest) to 100 (the highest). If a user has permissions to multiple mappings that all meet the criteria of the query, then NQS chooses the lowest-cost mapping possible and use this mapping to send the query to the data source. By ranking each mapping associated with a particular VTable using its cost, you determine which mapping you would prefer NQS to use if this happens. The default cost, which is used in the 1:1 mapping when you create a VTable using the NQS administrator wizards, is 50.

When virtual filters (VFilters) and/or virtual dimensions (VDimensions) are used in a mapping, NQS will also determine whether the WHERE clause or expression specified in the mapping exists in the query.

If you need to troubleshoot a query or simply determine which mapping it used, the NQS Monitor's Query Log displays which mapping each query was routed to. For information about using the Query Log, see the NQS Help.


Viewing a VTable’s MappingsNQS Administrator displays a list of mappings associated with each virtual table (VTable).

To view the mappings for a VTable:

1. In the left-hand pane of NQS Administrator, navigate to the VTable.

2. Click the VTable to see its property pages. The top right-hand pane displays the mappings associated with the VTable.

This list allows you to quickly see what mappings exist for a VTable and what cost they have each been given. In this example, the VTable has a 1:1 mapping, and in addition, has two mappings created for optimizing lists of values (LoVs) for specific columns. These custom mappings have a lower cost (25) than the 1:1 mapping (50).

3. Click a mapping to view its properties in the property sheets below. These properties include the mapping's Record Source, column list, whether any heterogeneous mappings, virtual dimensions (VDimensions), or a virtual filter (VFilter) exist for the mapping, and whether the mapping is cached.

4. Click the Heterogeneous tab to view the heterogeneous mappings that exist for the mapping. This list displays the heterogeneous mappings and what cost they have each been given.

5. Double-click a heterogeneous mapping (or select it and click the Edit button) to view its properties. These properties include permissions to the heterogeneous mapping and the server and connection associated with it.


Creating a Custom MappingYou need to know connection information for the data source that the mapping will point to. If this data source has not been created as a server and connection in Noetix QueryServer (NQS), you can create them during this process.

Use the Custom Mapping Wizard to create a custom mapping. The wizard walks you through each step of creating your mapping. If you need more information about any of the steps involved, click the Help button on any wizard page.

NOTE: To create a mapping that is similar to an existing mapping, you can instead create a copy of the existing mapping, then edit the copy as you want. To do this, in NQS Administrator, navigate to the virtual table (VTable) and mapping. Right-click the mapping you want to copy and select Copy. Right-click on an empty row and select Paste. You can now edit properties of the copy, such as the columns retrieved, server, and so on. You can copy and paste mappings between VTables as long as the columns in the mapping are compatible with the columns in the VTable.

To create a custom mapping:

1. Run the Custom Mapping Wizard in any of the following ways:

• In NQS Administrator, click on the toolbar. The Administrator Wizards dialog box appears. Click the Maintenance tab, then double-click the Custom Mapping Wizard.

• In NQS Administrator, on the Tools menu, click Administrator Wizards (Begin Here!). The Administrator Wizards dialog box appears. Click the Maintenance tab, then double-click the Custom Mapping Wizard.

• Click on the required VTable, and, on the shortcut menu, click New mapping using the Custom Mapping Wizard. If you run Custom Mapping Wizard from a VTable's shortcut menu, then the Assign a Virtual Table page (step 3) will not appear.

2. Click Next on the Welcome to the Custom Mapping Wizard page.

3. On the Assign a Virtual Table page, select the VTable or virtual view (VView) for which you want to create this mapping, then click Next.


4. On the Name the Mapping page, enter a name for the new mapping. This name must be unique among the mappings of the selected VTable. End users will generally not see this name, but it will display in the administrative tools. You can add a description for these columns if you want. Click Next when you are finished.

5. The Mapping Cost page is where you indicate how NQS should choose which mapping to use when more than one mapping satisfies the requirements of a query. NQS uses the mapping with the lowest cost percentage in this case. Using the slider on the left-hand side of the page, drag the arrow to the required percentage. Click Next when you are finished.

For more information about costs and routing queries with mappings, see Which Mapping Will NQS Use?

6. On the Pick Server page, select the server containing the table information you want to use. If an appropriate server doesn't exist, you can create one by clicking the Add new server button above the Servers list. Click Next to continue.

7. On the Pick Connections page, select the connection (schema) that owns or has access to the tables or views you want to use. You may select more than one connection.

If you add multiple connections, the first connection you check displays with a check mark over the icon. This indicates that it is the Reference connection, the one that Query Builder and the Expression Editor tools will use to access and validate against the underlying RDBMS when helping you build your Record Source (SQL) in the next page. To change which connection is used, right-click the required connection in the list and choose Set as Reference Connection.

If an appropriate connection doesn't exist, you can create one by clicking the Add new connection button above the Servers list.



8. On the Enter SQL Source page, enter the SQL that will form this mapping. To do this, you can either write or paste your SQL directly into the entry box or click the Build SQL button above the box to use the Query Builder tool. For information about using Query Builder, click the Help button on the Query Builder page.

Your mapping does not need to contain all columns in the VTable, but should not contain more columns than the VTable.

If your SQL is complex or does not correspond directly to a physical table or view, you may want to select the Maintain Record Source as a View check box. This will create a view in the database schema of the connection you selected, using the SQL you enter in the Record Source. You must select this option if your database does not support SELECT statements in the FROM clause of a query (which is not an issue if using NoetixViews or an Oracle, Microsoft SQL Server, or DB2 database).

When you are finished, click Next to continue.

9. The Relate Physical Data to the Virtual Table page displays the columns in the new mapping (in the Record Source Column column) and the columns in the VTable (in the VTable Expression column). The columns will be initially related based on their names, if NQS can match them. Ensure that the columns are related correctly, and relate any columns that NQS could not automatically relate. You can make changes directly on this page or by clicking the Back button and editing your SQL.

If you want this mapping to be used only when a specific expression or aggregation is used, you can modify the VTable expression for the appropriate column. For example, if the mapping points to a physical table that aggregates total sales, you would change the “Sales_Total” column’s VTable expression to SUM(“Sales_Total”). In step 10, you must remember to create a virtual dimension (VDimension) for any aggregations. For an example of creating a VDimension, see Routing a Query Based on an Aggregation.

Click Next when you are finished.


10. On the Advanced Needs Analysis page, answer the two questions below, then click Next to continue.

• Does the physical record set contain the complete set of rows that the VTable will ever return?

a. Answer Yes if your mapping will point to a table containing all rows the VTable could return.

b. Answer No if your mapping will point to a table with a subset of the data that could be queried using the VTable, and you want to create a virtual filter (VFilter). (For example, your mapping points to a table that contains California orders only, whereas the VTable in NQS can return orders from any state.)

If you answer No, then after clicking Next, you are prompted with the Virtual Filter page. To create the VFilter, enter the condition that must be present in a query's WHERE clause in order for this mapping to be used. (For this example, you would enter “SHIP_TO_STATE”=‘CA’) Click Next when you are finished. For an example of creating a VFilter, see Optimizing Data Access by Location.

• Are any of the physical record set columns aggregates of VTable columns (SUM, AVG, MIN, and so on.)?

a. Answer No if your mapping is not pointing to an aggregated result set.

b. Answer Yes if your mapping will point to a table where one or more columns are aggregates of the columns in the VTable, and you want to create a VDimension. (For example, your mapping points to a table where sales are summarized by state, whereas the VTable in NQS can return non-summarized sales.)

If you answer Yes, then after clicking Next, you are prompted with the Virtual Dimensions page. On this page, select which columns must be included in a query's GROUP BY clause for the mapping to be used. (For this example, you would check the box next to the “SHIP_TO_STATE” column.) Make sure you adjusted the VTable Expression in 9 as well; you can click the Back button if you need to return to do this now.

Click Next when you are finished. For an example of creating a VDimension, see Routing a Query Based on an Aggregation.


11. The last page shows you an overview of the mapping you are about to create. Click Finish to create the mapping and exit the wizard.

After creating your mapping, verify or set the permissions that users have to the mapping. A user sending a query to NQS must have permissions to the mapping, as well as the connection it uses, before a mapping can be used. For more information about permissions, see Granting Permission to a Role in “Security.”

Creating a Heterogeneous MappingA heterogeneous mapping can be added to an existing mapping to enable cross-database reporting (that is, to allow users to join virtual tables (VTables) from different databases in a single query).

When initially creating a VTable using the administrator wizards, you have to select the I want to join this table with other tables from different servers check box (on the Log File page) and an additional mapping, called a heterogeneous mapping, will be created for the new VTables. To add cross-database support to an existing mapping, follow the steps below to use the New Heterogeneous Mapping Wizard.

To add a heterogeneous mapping to an existing mapping:

1. In NQS Administrator, navigate to the VTable and mapping to which you want to add the heterogeneous mapping.

2. Right-click on the mapping and select New Heterogeneous Mapping Wizard.

3. Click Next on the Welcome to the New Heterogeneous Mapping Wizard page.

4. On the Name the Heterogeneous Map page, enter a name for the new mapping. This name must be unique among the mappings of the selected VTable. End users will generally not see this name, but it will display in the administrative tools. You can add a description for these columns if required. Click Next when you are finished.


5. The Heterogeneous Map Cost page is where you indicate how Noetix QueryServer (NQS) should choose which mapping to use when more than one mapping satisfies the requirements of a query. NQS uses the mapping with the lowest cost percentage that fulfills the requirements of the query. Using the slider on the left-hand side of the page, drag the arrow to the required percentage:

• If you assign a higher cost than the normal mapping, NQS will use only this new heterogeneous mapping when a user sends in a query joining this VTable to a VTable in a different database. One reason to set this mapping's cost higher is because a heterogeneous mapping may have slower performance than a regular mapping.

• If you assign a lower cost than the normal mapping, NQS will always use this mapping over the normal mapping. One reason you may want to assign a lower cost to the heterogeneous mapping is if you use third-party reporting tools and you don't want to install numerous ODBC drivers on a client computer. If you set all of the heterogeneous mappings' costs to be lower than the normal mappings, a client computer will need only the NQS ODBC Driver installed on it.

For more information about mapping costs and how NQS routes queries to mappings, see Which Mapping Will NQS Use?

Click Next when you are finished.

6. On the Pick Server page, select the heterogeneous mapping server (HMS) you want to use. The default server, HMServer, can be found in the “N$System” server group. Cross-database VTables can only be joined when they point to the same HMS.

If an appropriate server doesn't exist, you can create one by clicking the Add new server button above the Servers list. Click Next to continue.


7. On the Pick connections page, select the connections you want to use. You may select more than one connection. If an appropriate connection does not exist, you can create one by clicking the Add new connection button above the Servers list.

If you add multiple connections, the first connection you select displays with a check mark over the icon. This indicates that it is the Reference connection, the one that Query Builder and the Expression Editor tools will use to access and validate against the underlying RDBMS when helping you build your Record Source (SQL) in the next page. To change which connection is used, right-click the required connection in the list, and choose Set reference connection.


8. The last page shows you an overview of the mapping you are about to create. Click Finish to create the mapping and exit the wizard.

Granting Permissions to Heterogeneous MappingsA user sending a query to Noetix QueryServer (NQS) can only use a heterogeneous mapping if the user has permission to the heterogeneous mapping, as well as the connection it uses. While you can use the same procedure for granting permission to a mapping, you can also use the following procedure specifically for granting permission to a heterogeneous mapping.

To grant permissions to a heterogeneous mapping:

1. In the left-hand pane of NQS Administrator, navigate to the virtual table (VTable).

2. Click the VTable so its property pages are displayed. The top right-hand pane displays the mappings associated with the VTable.

3. Click the mapping to view its properties in the property sheets below.

4. Click the Heterogeneous tab.

5. Select the required heterogeneous mapping, then click the Edit button.

6. Click the Permissions tab. The tab displays the users and roles trees—users, organizations, and roles can all be granted permissions to this heterogeneous mapping.


7. Grant permissions to the required users, organizations, and roles. For more information about granting permissions, see Granting Permission to a Role in “Security.”

8. Click Save.

Examples of Custom MappingsThe examples in this section illustrate problems that can be creatively solved using custom mappings.

Speeding Up Lookups (LoVs)This example shows how to create a custom mapping to minimize the performance hit of users doing lookups when running queries.

Problem:

The Sales department has come to you with a problem with the “Orders” virtual table (VTable), which returns order information along with the salesperson's name. Each salesperson regularly runs a query against this VTable and filters the query using the “Salesperson” column, to retrieve only those orders where he or she is listed as the salesperson. When the salespeople run this query in Noetix WebQuery (NWQ), they can click the List of Values button, so that instead of having to type in their name, they can select it from a list of all salespeople.

Retrieving this list of values (LoV) usually takes a long time. The Sales department asks if you can help.


You look at the “Orders” VTable in Noetix QueryServer (NQS) and see that it has only one mapping, the default 1:1 mapping. When a salesperson wants to filter by the “Salesperson” column, and then chooses to get an LoV, a SQL statement is sent to the back-end database asking for the distinct values found in the column. The SQL looks like this:

SELECT DISTINCT salespersonFROM OrdersORDER BY salesperson

Assuming the “Orders” table was imported by the Simple Virtual Table Wizard, NQS sends this SQL along to the back-end database and it chugs through all of the records, finding the distinct salespeople. This can be time consuming if the table involved has many rows.

Solution:

The answer to this performance problem lies in creating a specialized mapping for this lookup column. The mapping will point to a different table in the database, one that is devoted to the column being filtered on.

Luckily, since you are working with a normalized database, you already have a table devoted to salespeople – called “Salespeople” – where each salesperson is represented in a single row, in the “Salesperson” column.


In NQS Administrator, you create a new mapping for the “Orders” VTable using the Custom mapping Wizard. You name the mapping “LOV_Salespeople.” You select the appropriate server and a connection that has access to the “Salespeople” table. You give this mapping a lower cost than the default 1:1 mapping and set the mapping's Record Source to:

SELECT salespersonFROM SalespeopleORDER BY salesperson

You don’t need a DISTINCT in the mapping’s SQL, since the data is already set up this way. However, you still only want the mapping to be used if a user is retrieving an LoV or otherwise looking for distinct values only – you wouldn’t want the mapping to be used if a user wrote a query against all rows in this column. To enforce this in the mapping, you must create a virtual dimension (VDimension). On the Advanced Needs Analysis page, you select Yes to the second question to create a VDimension. After this, on the VDimensions page, you select the check box labeled No GROUP BY can be used, this is a fully aggregated recordset, which will enforce the DISTINCT rule.

You verify the “Salesperson” column in the mapping is associated to the “salesperson” column in the VTable, then click Finish to create the mapping.

Result:

Now, when a salesperson clicks the List of Values button and the initial SQL statement above is sent from the query tool, NQS chooses the new “LOV_Salespeople” mapping (because of the lower cost and the fact that the mapping returns the column asked for in the query) and the query is routed to the “Salespeople” table in the database. Performance greatly improves. But, if the user sends a query that includes more than the “salesperson” column in the SELECT clause, then NQS has no choice but to use the default mapping.

NOTE: NQS can only use a mapping whose Record Source returns at least the columns asked for in the SELECT clause of the query.


Creating Column-Level SecurityThis example shows one way to create column-level security for a virtual table (VTable), using mappings.

Problem:

Your company uses NoetixViews for Oracle E-Business Suite in conjunction with NQS. When Oracle E-Business Suite users run queries against NQS (through NWQ), their Oracle security is checked and they can only access the data they have been granted access to through Oracle responsibilities.

You have set up other users in NQS by importing their accounts from the directory. These users do not have security to Oracle E-Business Suite. However, one of these users, Jack Smith, needs to set up a mailing list for the finance department. You need to give him access to this information in the “AR_Customer_Addresses” VTable, but need to restrict the columns he can access from the VTable.

Solution:

To give this user access to the VTable, you create a new mapping that includes only the columns you want the user to access and then set permissions so the user can only access this new mapping.

The first step is to create a new mapping with fewer columns than the VTable's 1:1 mapping. This mapping points to the same physical table as the 1:1 mapping, so no changes need to be made in the physical database.

Instead of creating this mapping from scratch, you make a copy of the existing mapping and delete the unnecessary columns from the copy. To do this, in NQS Administrator, you navigate to the AR_Customer_Addresses VTable and select it, displaying its mappings in the right-hand pane. You copy the existing 1:1 mapping, and paste it into a blank row. Using the Properties tabs, you first change the name of the new mapping to “Mailing List Columns Only.” You click the Columns tab and delete all the columns except the columns needed for the mailing list (Customer, Address1, Address2, City, State, and Postal_Code), then click Save.

Jack Smith needs access to a valid server and connection the mapping can use as well. In this case, he doesn’t yet have access to any of the existing servers or connections. You create a new default type connection on the server that uses a valid Oracle user name and password instead of Jack Smith’s user name and password. Then, you return to the Mailing List Columns Only mapping and add this new connection.


Next, you need to assign Jack Smith the proper permissions to access this new mapping. You create a new role called “Mailing List Access” that grants access to the new “Mailing List Columns Only” mapping, the new server, and the new connection, and revokes access to the 1:1 mapping. You navigate to Jack Smith under users and make him a member of this new role. (In the future, if another employee needs this same access, you can quickly set up the permissions by making that employee a member of the role as well.) You also check the Permissions tab for his user account and ensure he does not have access to the 1:1 mapping.

Finally, you log on to NWQ and create a quick query from the AR_Customer_Addresses view, including the mailing list columns above, and give a copy of the query to Jack.

Result:

Jack Smith can now log on to NWQ and run a query that returns all the mailing list information he needs. When the query is run, NQS sees that Jack only has permissions to the “Mailing List Columns Only” mapping and always routes the query to that mapping. Because he does not have access to a mapping that would return other columns from the underlying VTable, he cannot add any of the other columns in the VTable to his query or the query will fail. He now has access to the columns he needs but not to any others.

Routing a Query Based on an ExpressionThis example shows how a mapping can be created and used when a specific expression is present in a query.

Problem:

The sales manager wants to know how much money the company could be making if they increased prices by 150%. She has access to a virtual table (VTable), Order Lines, that can return the current order details and prices. This table was imported with the Simple Virtual Table Wizard, so it uses a 1:1 mapping to the physical table, order_lines. The sales manager is planning to run a number of queries against this VTable, each time performing a calculation to multiply the selling_price column value by 1.5.

You know from performance statistics that this VTable is very heavily used within the sales department, and you worry that performance for both the sales manager and the rest of the department will be poor when all these calculations are being done.


Solution:

You create a new table in the physical database that pre-calculates the 150% increase, then point queries that include this calculation to this new table to improve performance.

First you create another table in the physical database that is batch loaded with the data from order_lines, and each selling_price column value is multiplied by 1.5. This new table is called order_lines_price_increase.

You use the Custom Mapping Wizard to add a new mapping to the order_lines VTable. The Record Source is SELECT * FROM order_lines_price_increase. The information on the columns page is changed to look like the following:

Notice that the right side of the page has an expression, (“selling_price”*1.5). This mapping is also given a lower cost than the normal 1:1 mapping.

Result:

Now, if the sales manager sends a query, such as SELECT selling_price * 1.5 as increase FROM order_lines, she is directed to this new database table using the new mapping. This mapping is chosen because the expression sent in the SQL statement matches the VTable Expression in the mapping.

The advantage of this is that the data has been pre-calculated and the performance of the query should be better than before, when the calculation was done as the query was run.

This method can also be used to route queries with commonly used expressions such as FirstName + ' ' + LastName, or queries with very complex calculations that could be pre-calculated for performance improvements. This feature is particularly powerful when combined with an aggregation. For an example, see Routing a Query Based on an Aggregation.


Optimizing Data Access by LocationThis example shows how queries can be routed to different mappings based on a portion of the WHERE clause.

Problem:

Your company has all its data in a server in New York. The company also has a regional office in California. You notice that the users in California are complaining of poor performance when they do queries against customer data, especially the Customers virtual table (VTable).

After some quick analysis, you realize that most of the queries done by California users deal with California customers, and their slow response is due to the time it takes to send large amounts of data across the country.

Solution:

You decide that a local source for this data would solve the California users’ performance problems.

You create a separate reporting server and place it in the regional office. The reporting server is set up to take a periodic snapshot of the California customer data.

In NQS, you create a new mapping for the Customers VTable using the Custom Mapping Wizard. This mapping is identical to the 1:1 mapping, but points to the new reporting server and has a lower cost than the 1:1 mapping. You only want this mapping to be used when a user's query is fetching only California data, so in the wizard, you also create a virtual filter (VFilter). A VFilter causes a mapping to be chosen based on a portion of the WHERE clause found in the incoming SQL.

Choose No to the question in the wizard, Does the Physical Recordset contain the complete set of rows that the VTable will ever return. You are then prompted to create a VFilter.

You enter the condition that must be present in the WHERE clause in order for a query to be routed to this mapping: “STATE”=‘CA,’ then save the new mapping.


Result:

Now, if a user sends a SQL statement like SELECT * FROM Customers WHERE STATE = ‘CA,’ NQS uses this new mapping and routes the query to the reporting server in California. NQS chooses this new mapping because it is able to give the user the information they are looking for and because it was given a lower cost than the default 1:1 mapping.

See Figure 3.2 for a diagram of the mappings that now exist for this VTable.

NQS immediately starts routing these queries to this local server, without any query modification needed from users.

If you needed to solve the same problem without creating a VFilter based on the WHERE clause, you could instead use permissions, granting only the California users access to the new mapping against the California data and giving the mapping a lower cost.

Routing a Query Based on an AggregationThis example shows how to use a mapping to overcome the performance hit of aggregations, by pointing queries with aggregations to pre-aggregated data.

Problem:

The DBA, using the NQS Monitor, has discovered that many users are interested in knowing the total sales that happen by state. These users are writing queries against the order_lines virtual table (VTable), which was imported using the Simple Virtual Table Wizard from a physical database table also named order_lines. In the queries, users are summarizing the order details (using a SUM on the Line_Total column) in accordance with Ship_To_State. All these users doing aggregations are hurting the performance of the database.


Solution:

You decide to use a mapping with a virtual dimension (VDimension) to point these queries to pre-aggregated data. A VDimension is used to route a query based on an aggregation that you have set up.

On the back end, you create a table that sums all of the sales by state. This table is called order_lines_by_state and has only the columns ship_to_state and total.

Using the Custom Mapping Wizard, you create a new mapping with a lower cost than the 1:1 mapping. This new mapping’s Record Source is: SELECT ship_to_state, total FROM order_lines_by_state. The columns page looks like:

Note the second line and the association between the total column in the Record Source and the VTable Expression. If the table had been pre-aggregated using an operator other than SUM, there would be a different VTable Expression.

On the Advanced Needs Analysis page, you select Yes to the second question to create a VDimension. After this, you see a page similar to below, where you select the grouped columns. You select the columns that must display in the group by clause of any incoming SQL:


Result:

Now, if a user sends a query such as SELECT ship_to_state, SUM(line_total) FROM order_lines GROUP BY ship_to_state, NQS routes that query to this new mapping and the aggregated table. Note that in this case, because this mapping only includes two VTable columns, any SQL statement that has more columns in it is routed to the 1:1 mapping.

Chapter 4

Servers and Connections

This chapter provides an introduction to the Noetix QueryServer (NQS) servers and connections, along with a high-level overview of working with these objects.


OverviewWhen Noetix QueryServer (NQS) connects to a physical database or other data source to retrieve the data for a query, it must locate and log on to the server using valid credentials. NQS connects to the database using the location and credentials you supply as a server and connection. A server is simply a pointer to a particular physical database or other data source (for example, an Oracle or a Microsoft SQL Server database, or even an Excel spreadsheet), set up in NQS to let NQS know the data source exists. A server can point to a server pool as well as a single server.

To log on to a data source, NQS uses a connection. The connection contains logon credentials for the database and determines how NQS connects to the physical database. To create a connection, you can manually enter a user name and password into NQS, or use a more flexible method of determining the credentials based on the logged-on user, a User Lookup Map, or by prompting the user for the user name and password at run-time. For information about these options, see Comparison of Connection Types.

The Servers and Connections Wizard walks you through the task of setting up servers and connections. You need to have at least one server set up before you move on to other wizards.

NOTE: Unless otherwise specified, the tasks in this chapter are performed using NQS Administrator.

ServersA server tells NQS about a particular data source on your network. A server usually corresponds to a physical server unless you have multiple databases on a single computer. Server information consists of a directory path or database instance name, and the ODBC driver to be used to interact with the source.

A server can also correspond to more than one physical server; this is called a server pool.

Create a server to:

• Set up a server, database, or other data source so you can then start working with its contents in NQS.

Chapter 4: Servers and Connections 89

Server GroupsA server group is a collection of servers—you define how you want to group your servers to make them more manageable.

Create a server group to:

• Logically organize your servers for easier administration.

• Grant access to a server group, effectively granting access to every server and connection in the group, instead of manually to each individual server.

Server PoolsA server pool points to multiple data sources for load balancing purposes. Any server in NQS can be set up to behave as a server pool by adding multiple driver configurations. When queries are run against a server pool, NQS alternates between the enabled driver configurations, balancing the query requests in a round-robin fashion.

Each driver configuration must point to a physical server or instance with identical data for all objects referenced in NQS.

IMPORTANT: Server pools cannot contain databases of different types and versions. Otherwise, some queries might not work when routed to certain servers.

Create a server pool to:

• Scale a server in NQS.

• Utilize an offline data source (ODS) or backup server already maintained in your enterprise.

• Provide an alternative for servers during down-time to keep queries from failing.

• Help lessen the load on a server that is currently overutilized.

NOTE: The NQS Monitor, as well as the performance statistics on the physical database, can help you determine how much query traffic a data source is getting. For more information about using the NQS Monitor, see the NQS Help.


ConnectionsA connection is set up to define the database user account with which NQS will log on to a particular server. A server can have multiple connections, for instance, one for each table owner within a database.

Create a connection to:

• Define how NQS should log on to a server you set up.

Before You BeginInstall ODBC drivers: Any ODBC driver that will be used to connect to an RDBMS must be installed and configured on the computer where the Noetix QueryServer service is running before setting up any objects from that data source. You should validate that the ODBC driver is working properly prior to using it within NQS. This will help isolate any potential issues you may encounter while setting up NQS.

Determine server and table setup: Talk to your network or database administrator and gather information about the database servers in your environment. You may need to know database names (for example, for SQL Server). NQS has quick setup routines for IBM DB2, SQL Server, and Oracle Database. Other ODBC-compatible databases may require additional connectivity data to set up.

You will also need to determine a naming convention for the servers and server groups. Your users will never see the servers and connections that you define in NQS, so you should name servers and server Groups in a way that helps you organize the data sources in your enterprise. If any of the servers you plan to connect to have a corresponding backup server or ODS that you would like to utilize, note this as well.

Obtain account information: Since a connection requires a valid user name and password for the target database, you will need to talk to the associated DBA to get this connection information for each server. This includes user names and passwords of database logons that have access to the tables you want to import into NQS.


Servers

Creating a ServerTo set up a server, use the Servers and Connections Wizard in NQS Administrator. The wizard will walk you through each step of setting up your data source. If you need more information about any of the steps involved, click the Help button on any wizard page.

You will need to know connection information for this server. The ODBC driver that will be used must be installed and configured on the computer where the Noetix QueryServer service is running, and must support the SQLBrowseConnect function. For information about checking for the function’s support, see the NQS Help.

To create a server:

1. In NQS Administrator, click on the toolbar.

2. The Administrator Wizards dialog box appears. On the Basic Setup tab, double-click Setup Servers and Connections.

3. The Servers and Connections Wizard will begin and the welcome page appears. Click Next.

4. The Definitions page appears with definitions of Noetix QueryServer (NQS) servers and connections. Click Next to continue.

5. The Options page appears. Select Add new server, and then click Next.

6. The Pick a Server Group page appears. Do one of the following:

• If there is an existing server group that you want to add the new server to, click the server group. Click Next to continue.

• If you want to create a new server group, click Add a new group. A new node will appear. Type the new name for the group, and then click Next to continue.

For more information about server groups, see Creating a Server Group.


7. The Server Name page appears. Enter the following information, and then click Next:

• Server Name: Enter a name for the new server.

• Connection: Defaults to a new connection. The name is created from the Server Name followed by _conn1. You can change this default information if you want.

• Description: Enter a description for the new server.

• Enable Server: To make this new server available, check this box.

8. The Choose RDBMS page appears. Select one of the following options:

• If your data source is a Microsoft SQL Server, IBM DB2, or Oracle Database, select the type from the Quick Set-up Databases drop-down list. Click Next, and then continue on to step 10.

• If your data source is something other than those in the drop-down list and is ODBC-compliant, select Other. Click Next, and then continue on to step 9.

9. If not using a quick setup database, the Choose ODBC Driver page appears. All ODBC drivers running on the NQS computer that support the SQLBrowseConnect function will be listed. Note that the NQS computer is not necessarily the computer from which you are running NQS Administrator.

Select a driver, and then click Next to continue.

NOTE: If you do not see an ODBC driver listed here, it likely is not installed on the NQS computer or does not support the SQLBrowseConnect function. You will need to exit the wizard and set up the server manually. From the left-hand list in NQS, right-click the Servers item and click New > Server. Use the property sheet to define the new server.


10. The Get Connection Information page appears. Enter the following information, and then click Next. The fields will be marked Required if needed.

• Server: The name of the data source server.

• Login ID: The logon ID for the data source.

• Password: The password associated with the Login ID.

• AppName: The name of the application.

• WorkStation ID: The workstation ID.

11. A second Get Connection Information page may appear. Enter the information, and then click Next to continue. The fields will be marked Required if needed.

12. The Driver Configurations page appears, displaying the default Driver Configuration. If you want to set up this server as a server pool, you can add additional Driver Configurations on this page.

To add a driver configuration, click on a blank line, then enter a name and the server-specific section of the ODBC connect string used to connect to the RDBMS (for example: SERVER=myserver; or SERVER=myserver/instance;).


13. The last wizard page appears, displaying an overview of the server and connection you are creating. Review the information, and then click Finish. The new server and connection will now be created.

14. After the wizard completes setting up the new server and connection, you can verify the new objects were created as expected.

a. Navigate to the new server group (if created) and server under the Server root.

b. You can view the new connection information by clicking the connection in the upper right-hand of the page.


Creating a Server GroupYou may want to organize your servers for easier maintenance or to more efficiently grant permissions. You can create as many server groups (collections of servers) as you would like, although each server can belong to only one group.

Create a server group to:

• Logically organize your servers for easier administration.

• Grant permission to a server group, effectively granting permission to every server and connection in the group, instead of manually to each individual server.

To create a server group:

1. In NQS Administrator, right-click the Servers item in the left-hand list, then click New > Server Group. The New Server Group property sheet will display.

2. On the General tab, type a name for the new server group and a description, if required.

3. Click Save.

You can also create a server group using the Servers and Connections Wizard, during the process of creating a server.

Creating a Server PoolSetting up a server pool is done by creating a server with multiple driver configurations. You can add these configurations while creating the server or at any time afterward.

IMPORTANT: Server pools cannot contain databases of different types and versions. Otherwise, some queries might not work when routed to certain servers.


Create a server pool to:

• Scale a server in Noetix QueryServer (NQS).

• Utilize an offline data source (ODS) or backup server already maintained in your enterprise.

• Provide an alternative for servers during down-time to keep queries from failing.

• Help lessen the load on a server that is currently overutilized.

NOTE: The NQS Monitor, as well as the performance statistics on the physical database, can help you determine how much query traffic a data source is getting. For more information about using the NQS Monitor, see the NQS Help.

To create a server pool:

1. In NQS Administrator, navigate to an existing server, double-clicking it in the Navigator window so its property pages are displayed.

2. Click the Driver Configurations tab to open it.

3. In a blank line in the list of driver configurations, click the Name field. Enter a name for the driver configuration.

4. Click the Driver Configuration field, then enter the driver configuration. The format of this should be the server-specific section of the ODBC connect string used to connect to the RDBMS (for example: SERVER=myserver; or SERVER=myserver/instance;).

5. Check the Enabled box to make this server available.

6. Click the Save button.

You can also add multiple driver configurations when first creating a server using the Servers and Connections Wizard. On the Driver Configurations page, click on a blank line, then enter a name and the server-specific section of the ODBC connect string used to connect to the RDBMS (for example: SERVER=myserver; or SERVER=myserver/instance;).


ConnectionsAt run-time, after the Noetix QueryServer service has transformed an end user’s logical

query into a physical query, it connects to the physical database and runs the query. The type of connection being used determines how Noetix QueryServer (NQS) connects to the physical database. For a comparison of the connection types, see Comparison of Connection Types.

• The Default Connection: The first type of connection is called a general or default, connection. To create any connection, you must provide the default user information. This is a valid user name and password combination for the server you are creating this connection for. This user will also typically be the user that owns the tables, views, procedures, and so on.

If you leave the Use Default User Information button selected, NQS will connect to the physical database using the Default User Information. From the database's point of view, this means that this will be the only user connected to the database regardless of how many NQS users employ this connection.

• The Pass Through Connection: When you choose the Pass Through option for a connection, NQS sends the exact information that the end user used to log on to NQS to the database. This can be helpful if you already have a database application developed that uses the native database security.


• The Prompt Connection: When you choose the Prompt option for a connection, NQS will prompt end users for connection information whenever they use a virtual table (VTable) that uses this connection. A window is displayed prompting for a valid user name and password.

This connection type should be used sparingly because of the added burden on the end user.

CAUTION: Do not use this connection type in conjunction with NWQ or any other Web-based reporting tool. You also should not use this connection type if you are accessing NQS from within the code of a custom application, for example, Visual Basic and Active Server Pages.

• The Lookup Connection: When you choose the Lookup option for a connection, you must build a User Lookup Map that maps an NQS user to a database user. When this connection is used, NQS attempts to look up the information it should use to connect to the physical database.

Each server can have a User Lookup Map that can be used by all of its connections. You provide the DB User Name and DB Password that you want NQS to use if a particular user uses any connection of the lookup type. If you do not want to store the DB Password in the NQS Repository or if you do not know it, you can check the box Prompt User. Every time the user accesses the connection, he or she will be prompted for a password. You can also set this up as a pass through connection, and the password the user entered at logon will be passed to the connection being used.

This type of connection can be useful if NQS Administrator wants users to log on to the corporate databases using different database user accounts. If the Prompt User option is not used, this can be completely transparent to the end user.

NOTE: All passwords are encrypted before they are stored in the NQS Repository.


Comparison of Connection TypesThe following table discusses the different connection types and lists the pros and cons of each:

Table 4.1 Comparing the Four Connection Types

Connection Description Pros Cons

Default

Always logs on to the RDBMS with the same user name and password.

Enables RDBMS logon accounts to be shared by multiple Noetix QueryServer (NQS) users. Allows for easy maintenance and quick setup.

Cannot differentiate at RDBMS level between different NQS users. Provides same security access to multiple NQS users.

Pass Through Logs on to the RDBMS with the NQS user's NQS user name and password.

Can fully utilize RDBMS security. Very easy setup.

Requires that the RDBMS logon names and passwords be identical to the NQS ones.

Prompt

Prompts the NQS user for the RDBMS logon user and password when connecting to the RDBMS.

Provides easy setup and low maintenance. Fully utilizes RDBMS security. Can differentiate at RDBMS level between different NQS users.

Cannot be used with Noetix WebQuery (NWQ). NQS users must log on separately to each RDBMS that they access. Loss of single-logon facility.

Lookup Logs on to the RDBMS with RDBMS account that the user has been mapped to.

Fully utilizes RDBMS security. Can differentiate at RDBMS level between different NQS users.

Higher setup and maintenance costs, especially if passwords need to be synchronized occasionally.


Creating a ConnectionWhen you set up a server using the Servers and Connections Wizard, you set up a default connection as well. If you want to create additional connections to the server, you can run the wizard again, using the following procedure.

Create a connection to:

• Define how Noetix QueryServer (NQS) should log on to a server you set up.

To create an additional connection:

1. In NQS Administrator, click on the toolbar. The Administrator Wizards dialog box appears.

2. On the Basic Setup tab, double-click Setup Servers and Connections. The Servers and Connections Wizard will begin.

3. After the introductory pages, the wizard will ask you whether you want to add a new server or add a connection to an existing server. Select the button next to Add a connection to an existing server. Click Next to continue.

4. Select the server group, then the server you want to add a connection to. Click Next to continue.

5. For a quick setup, select the Typical option and enter the user name and password. Click Next, then skip to the last step of these instructions (step 8).

If you want to specify a certain ODBC driver or language for the connection, instead click Custom, then click Next to continue.

6. For a custom setup, enter the required information, then click Next.

7. Enter any other required connection information, then click Next. The required information will depend on the type of data source.

8. The last page shows you an overview of the connection you are creating. Click Finish.

Chapter 5

Web Queries and Folders

This chapter describes how to work with and manage queries in Noetix WebQuery (NWQ).


OverviewComplete the following tasks to set up Noetix WebQuery (NWQ):

• Install all components of Noetix QueryServer (NQS) and NWQ. For information, see the Noetix Platform Installation Guide.

• Set up your data sources in NQS, either manually (For information, see VTables and Mappings.) or automatically using Noetix Generator for Noetix Platform—Oracle E-Business Suite Edition (Noetix Generator), Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator), or NoetixViews for Siebel Business Applications (NoetixViews for Siebel).

• Set up users and roles in NQS, either manually (For information, see Security.) or automatically using Noetix generators or NoetixViews for Siebel.

• Verify your Web browser meets the NWQ system requirements. For information, see the Noetix Platform Release Notes available with the product software.

Helping Users Get StartedAdministrators may want to use the following steps to help users get started with NWQ:

1. Ensure users have access to a Web browser meeting the NWQ system requirements (see the NQS/NWQ Release Notes available with the product software).

2. Provide the URL for accessing NWQ through browser to query users in your enterprise. The URL is http://<computer name>/nwq/login.htm, where computer name is the name of the computer on which NWQ is installed. If your organization policy requires the use of Secure Sockets Layer (SSL) for encryption of user credentials and data, the URL must be https://<computer name>/nwq/login.htm.

3. Inform users of their user names and passwords as set up in NQS.

Refer new users to the NWQ User Help for instructions on navigating NWQ. To access the NWQ User Help, click the help link in the top right-hand corner of any NWQ page. Help topics can be printed for reference.

Chapter 5: Web Queries and Folders 103

NWQ SecurityThe Noetix WebQuery (NWQ) security model works in conjunction with the security model in Noetix QueryServer (NQS), using the users, authentication, and other security objects of NQS. NWQ also adds its own layer of security to the Noetix Platform.

Four main types of security are used in NWQ:

• Logon security

• Folder security

• Query security

• Feature security

These types of security are each discussed in the following sections.

Logon SecurityLogging on to NWQ requires that a user is set up in NQS. Each user logs on with an NQS user name and password. The user and password is authenticated using the authentication method defined for that user (for example, against a network server or Siebel application), which tells NWQ whether the user should be admitted.

When a user is authenticated against Oracle E-Business Suite, NWQ will also prompt the user to choose what Oracle responsibility he or she wants to log on with. To switch between responsibilities, a user can log off and then log on again with another responsibility.

Folder SecurityQueries in NWQ can be organized into three different types of folders—Personal, Public, and VTables. The following sections describe these folders and how users can be granted access to them.

NOTE: There is also the Subscriptions folder that contains query delivery subscriptions. For information about granting users access to susbscription management and this folder, see the NWQ Administrator Help.

Folder security determines whether a user can see and open a folder and view the queries it contains. A user still may not have permissions to run each of these queries and return data. For more information about query security, see Query Security.


Personal folder: Each user has his or her own Personal folder, where queries he or she creates or customizes can be accessed. Users have full access to their own Personal folder, and are the owners of their Personal queries. Users have permission to create subfolders within their Personal folder to organize their queries. Users can also move, rename, copy, delete, and create queries within their Personal folder.

Users can choose to share their own queries with other users. For more information about sharing queries, see Sharing Queries.

Public folder: Public folder provides a way to share access to a query throughout an organization, to multiple users at once. As described in the “Personal Folder” section, queries themselves always exist in the Personal folder of a user and so can never actually live in a Public folder. Instead, a link can be created in the Public folder that points back to the actual query. This is similar to how shortcuts work in Microsoft Windows. Other users can open this link and work with the query, but to save changes, they must save the modified query to their own Personal folder.

Folder permissions allow you to determine who can access a certain Public folder and its contents. To do this, you can grant an NQS role certain access to an NWQ folder. By granting access to an NWQ folder, you are giving anyone who is a member of that role the permission to view this folder and its contents. This will include any user that is a member of the role explicitly or implicitly.

There are five different permissions that can be granted to determine how a user can use and modify a folder—Select, Drop, Alter, Create, and Change Permissions (For information, see Permissions in “Security.”). You can grant or revoke each permission, or allow users to inherit the permissions from permissions set elsewhere. Revoking a permission will disallow that permission even if a user is granted that permission through a conflicting role.


Let’s continue the following example. Given our setup of users, organizations and roles, the Noetix administrator now starts creating Public folder in NWQ.

Figure 5.1 NWQ Folder Permissions

Immediately below the root of Public, we create a folder called “Western US Reporting.” Below that, we create a folder called “Sales Reports,” and then “Commission Reports.” We then go through the process of publishing our sales and commission reports into these last two folders.

When Sally logs on to NWQ, what will she see? Since she has been granted the “High Tech Sales” role, which has Select permission to the “Sales Reports” folder, we expect that she will be able to see the “Sales Reports” folder. But what about the “Western US Reporting” folder? When Sally browses to the Public folder root, she will indeed see this folder, and will be able to continue navigating into the “Sales Reports” folder.

The reason that Sally can see the “Western US Reporting” folder is that she has been implicitly granted a Browse permission (You cannot explicitly grant a user this permission). A user is granted this permission when they have explicit select access to a child folder, but not the parent. The browse permission lets the user navigate into the folder, but not view any contents except for the folder they have access to. If queries had been linked directly into the “Western US Reporting” folder, then Sally would not be able to see them.


Folder permissions flow down to child folders. Thus, since Sally has select access to the “Sales Reports” folder, she will also have select access to the “Commission Reports” folder and its contents.

For more information about setting permissions on NWQ folders, see Granting Public Folder Permissions.

VTables folder: VTables folder allows users to access the virtual tables (VTables) in NQS. These VTables are exposed as VTables queries in NWQ. VTables queries allow users to run SELECT statements against the VTables only, and should be considered starting points for custom queries. Users cannot modify or save queries in the VTables folder, but can create new custom queries from the VTables folder queries, then save them to their Personal folder.

Access to contents of the VTables folder is determined by granting default subfolders in NQS Administrator. A subfolder will appear in NWQ when the logged-on user has been granted the subfolder as a default subfolder, either implicitly (through organizations or roles) or explicitly (directly granting permissions to specific users). A user will only be able to access an object that is within one of these default subfolders.

NOTE: If a user has permission to an item that is not in one of his or her default subfolders, the item will not show up at all in the VTables folder. If a user has been granted a default subfolder but not granted permission to the connection, the object will show up but the user will not be able to run it.

Query SecurityIn many cases, a user may end up with security to view all queries within a specific folder, such as a default subfolder in the VTables folder. A user may also be given a copy of a query they did not originally have permissions to. When this happens, the security of the data is not in jeopardy. To run the query and return data, a user must have been granted permissions to the following:

• The virtual table (VTable) the query is based on.

• At least one mapping that can return the data.

• A connection that can be used to log on to the target database.

A user will receive an error if he or she attempts to run a query without having these permissions.


For more information about these permissions, see Granting Permissions to a VTable in “VTables and Mappings.”

Users can send links to queries or run queries in Excel as well. When distributing a query to other individuals this way, a user can choose to embed their logon and password, allowing the recipient to run the query without logging on with their own credentials. If these features pose a security risk, you can use NWQ profiles to allow only certain users access to these features. For more information, see the following section.

Feature SecurityFeatures in NWQ are made available to users based on the NWQ profiles they are assigned. NWQ profiles are sets of rights that allow administrators greater flexibility in controlling which NWQ features are available to users. When certain NWQ features are not needed or recommended within your enterprise, you can simply revoke access to those features. For example, you can revoke access to sharing queries, or executing a query in Excel.

NOTE: For clarity sake, it is important when talking about security issues in NWQ to distinguish between profiles that grant and revoke features, and folder permissions that grant and revoke access.

NWQ profiles do not control users’ access data; NWQ profiles determine what users can do with the data once they log on to NWQ (for example, can they export to Excel or customize queries). These profiles are used in NWQ only (since they deal with access to NWQ features) and are not applied to third-party reporting tools that may be used to retrieve data from NQS.

NWQ profiles are optional; you can allow all users to access the default NWQ features without any additional setup steps. If you choose to customize your NWQ profiles, you can either modify and grant a single NWQ profile to all users in your enterprise or create multiple profiles based on different levels of access.

For more information about creating and assigning NWQ profiles, see Profiles in “Security.”


Web QueriesWeb queries are built on one or more base tables, much as traditional reports or queries are written against tables in a database. These base tables are defined in Noetix QueryServer (NQS) as virtual tables (VTables), and each base table is associated with one or more database tables. The Properties page for a query shows which VTables serve as its base tables.

A Web query can contain all of the columns in its base tables, or simply a subset of those columns. Many Web queries can share base tables, and yet each query can be built so as to return and display data to meet different needs.

After VTables are set up in NQS (For information, see VTables and VViews in “VTables and Mappings.”), you must perform a few steps to make them available to users to query from Noetix WebQuery (NWQ). Understanding all the options for making VTables available to users can help you in planning what VTables you will need to satisfy users’ reporting requirements.

You can use the following steps to make VTables available to users in NWQ:

1. Expose the VTable in NWQ. (You can also expose a whole subfolder of VTables at once.)

2. Customize or format the Web query (if needed).

3. Share the query with users.


Exposing VTables in NWQA virtual table (VTable) created in Noetix QueryServer (NQS) does not automatically display in Noetix WebQuery (NWQ) for users to work with. An administrator or report developer needs to make the VTable available in NWQ before queries can be written against it. This process enables a Web query based on the VTable to be created in NWQ, with all the columns of the VTable initially included in the query.

There are two ways to make VTables available in NWQ:

• Exposing a single VTable: This method makes a single VTable display in the Personal folder of a single user.

• Exposing a group of VTables: This method makes an NQS subfolder and all the VTables within it display in NWQ in the VTables folder.

Adding a VTable to a User’s Personal FolderIf you need to make a single virtual table (VTable) available in NWQ or need to expose it for only one user, you can use a shortcut and bypass using the VTables folder. This method creates the VTable as a Web query in a Personal folder (for yourself or another user), and you can modify and/or publish the query from there without needing access to the VTables folder.

This method is ideal for making a VTable available for a user without access to the VTables folder, or if you plan to publish VTables to users using the Public folder rather than the VTables folder.

The following procedure explains how to make a single VTable available in the Personal folder for yourself or another user. The query will have the same name as the VTable and will be saved in the Personal root folder of the user.


To expose a single VTable:

1. Using NQS Administrator, navigate to the VTable you want to make available in NWQ.

2. Verify that you (or the user you will create the query for) have Select permission to the VTable. For more information about permissions, see Permissions in “Security.”

3. Right-click the VTable, then select one of the following:

a. To make the VTable available for yourself, click Create Web Query > For Yourself (user name).

b. To make the VTable available for another user, click Create Web Query > For Another User, navigate to the required user, and click OK.

4. A message will display stating the query was created successfully, and will list the name and location of the query that was created.

After performing these steps, the VTable will display as a Web query in the Personal folder. The query can be run as-is, or further customized and formatted.

Adding a Group of VTables to VTables FolderYou can make a subfolder of virtual table (VTable) in NQS display for select users in the NWQ VTables folder. The VTables folder provides read-only access to the VTables in NQS, arranged and named the same as in NQS. These VTables can be customized and saved as Web queries in a user’s Personal folder, then subsequently shared with other users if required.

Access to VTables within this folder is set in NQS. For each user, a subfolder will appear in NWQ when the user has been granted the subfolder as a default subfolder in NQS, either implicitly (through organizations or roles) or explicitly (directly granting permissions to specific users). The user will then see all VTables within one of these default subfolders.

The VTables folder is best used when a whole subfolder of VTables needs to be exposed to users (for example, when connecting to other data sources through NQS/NWQ). Most users may not need access to the VTables folder, especially if the majority of their reporting is done against NoetixViews or NoetixAnswers.


For information about making a subfolder of VTables available in the VTables folder for users, see Granting a Default Subfolder in “VTables and Mappings.”

After performing these steps, the subfolder and all VTables within will display for the user in the VTables folder area, as a Web query. The object can be run as a query, or further customized and formatted.

Customizing or Formatting the Web QueryWhen a virtual table (VTable) has been made available in Noetix WebQuery (NWQ), you can run the resulting Web query as-is. However, the query will not yet contain many properties of a Web query, such as a title, until you customize and/or format the query in NWQ.

For example, you will want to:

• Remove any unneeded columns from the query

• Add a title and subtitle for the query

• Modify the default description

• Sort the results

When customizing a query in the VTables folder, the new query will be saved to your personal folder. You can then publish or share it to other users as needed, but you cannot save the customized query to the VTables folder.

For more information about customizing and formatting a query, see the NWQ User Help.


Viewing Query DetailsYou can view detailed information about the Noetix WebQuery (NWQ) query components on the query specifications page in NWQ Administrator.

To view NWQ query details:

• On the Queries tab, click the name of the query. The query specifications are displayed in a new browser window.

The following query components will be displayed on the query specifications page.

Answers: The following are the specifications for answers. You can customize them in the Options page when creating or customizing a query.

• Description: The description of the answer.

• Report Title: The title of the report that is displayed in the query results page.

• Report Subtitle: The subtitle of the report that is displayed in the query results page.

• Parameter Page Title: The title of the parameter page if the query has parameters. The parameter page is displayed when you run the query.

Query Distinct: Specifies whether unique rows of a query are displayed. If you have selected the Hide Duplicate Rows (choosing a RED column will disable this option) check box on the Columns page, Yes is displayed, and you can view only the unique rows of the query. If the check box is not selected, No is displayed, and you can view all the rows of the query (including duplicates).

VTables: The following is the specification for virtual tables (VTables):

• Base VTable: Lists a virtual table (VTable) or related VTables based on which a query is created. You can customize the VTables, such as change the base tables, add columns to the VTables, and join the VTables based on related VTables on the VTables page when customizing or creating a query.


Joins: The following are the specifications for VTable joins. You can customize them on the VTables page when creating or customizing a query.

• Left VTable: The name of the left VTable in a join.

• Right VTable: The name of the right VTable in a join.

• Relationship: The relationship defined for the VTables that are joined.

• Join Type: The type of join used in a query.

Columns: The following are the specifications for columns:

• Col: The column name or column alias of a query.

• Expr: An SQL statement that represents a column or a calculated column with a complex SQL expression.

• Sort Pos: If you have defined sort rules for multiple columns, each sort option is given a sort position number automatically, starting from sort position 0.

• Sort: The sort rule defined for the column, either Ascending or Descending.

• Group Sort: If the Group Sort check box is selected for the column in the Sorting page, Yes is displayed. Otherwise, No is displayed.

• Disp Width: The width of the column. You can customize it in the query results page and save the query.

• Format Mask: The format mask specified for a column based on the format class to which the column belongs. For example, the format mask of a column belonging to Date format class can be specified in any of the formats available in the query results page, like <MM-DD-YY>. You can customize it in the query results page.

• Format Class: The format class to which the column belongs (for example, data types like String, Date with or without Time, Numbers, and Currency). You can customize it in the query results page.

• Aggregation: The aggregation type defined for the column.


• Agg Distinct?: Specifies whether unique rows of a query are displayed. If you have not selected the Aggregate All? check box on the Edit Column page, Yes is displayed, and you can view only the unique rows of the query. If the check box is selected, No is displayed, and you can view all the rows of the query (including duplicates).

• Page Item: If a column of a query is added to the filter bar as a page item on the query results page, Yes is displayed. Otherwise, No is displayed. You can customize it in the query results page.

• Page Item Pos: If you have selected multiple columns as page items on the query results page, each page item is given a page item number automatically in the order they appear on the page, starting from page item position 0.

Filters: The following are the specifications for filters. You can customize them in the Filters page when creating or customizing a query.

• Filter: If you have defined multiple filter conditions for a query, each filter condition is given a filter number automatically, starting from filter number 0.

• Column: The column name to which the filter condition is applied.

• Aggregate Filter?: If a column of a query is defined as an aggregate or a calculated column, Yes is displayed. Otherwise, No is displayed. You will see an Aggregation Filter option in the Filters page when you customize the query.

• Operator: The condition defined for the filter.

• Value(s): The value provided for the filter criteria.

• Include Null Values?: If the Include Null Values check box is selected in the Filters page, Yes is displayed. Otherwise, No is displayed. Selecting the check box will retrieve even the columns with null value.

• Boolean: The boolean operator that is defined if there are multiple filters for a query, either AND or OR.


Parameters: The following are the specifications for parameters. You can customize them in the Parameters page when creating or customizing a query.

• Parameter: If you have defined multiple parameters for a query, each parameter condition is given a parameter number automatically, starting from parameter number 0.

• Prompt: The descriptive prompt defined for the parameter.

• Column: The column name for which the parameter condition is defined.

• Aggregate Parameter?: If a column of a query is defined as an aggregate or a calculated column, Yes is displayed. Otherwise, No is displayed. You will see an Aggregation Parameter option in the Parameters page when you customize the query.

• Operator: The condition defined for the parameter.

• Default Value(s): The default value provided for the parameter.

• Include Null Values?: If the Include Null Values check box is selected in the Parameters page, Yes is displayed. Otherwise, No is displayed. Selecting the check box will retrieve even the columns with null value.

• Is Optional?: If the Optional check box is selected in the Parameters page, Yes is displayed. Otherwise, No is displayed. Selecting the check box will make the parameter optional. You can choose to provide or not provide the parameter value when running the query.

• Boolean: The boolean operator that is defined if there are multiple filters for a query, either AND or OR.

Totals:The following are the specifications for totals. You can customize them in the Totals page when creating or customizing a query.

• Total: If you have defined grand totals or subtotals for multiple columns, each total is given a total number automatically, starting from total number 0.

• Column: The column for which the total condition is defined.

• Aggregation: The aggregation type defined for a total.


• Total Label: The descriptive label provided for a grand total or subtotal.

• Total Type: The type of the total, either Grand Total or Sub total.

• Break Col: If the Page break check box is selected for subtotals in the Totals page, Yes is displayed. Otherwise, No is displayed. Selecting the check box will insert a page break in the printed report at each change in the column value at subtotal level.

• Break on Group Sort: If the Page break check box is selected for grand totals in the Totals page, Yes is displayed. Otherwise, No is displayed. Selecting the check box will insert a page break in the printed report at each change in the column value at grand total level.

Changing Query OwnershipWhen a user customizes and saves a Noetix WebQuery (NWQ) query, the query lives in their Personal folder and that user is the query owner. You can use the following procedures to change the query ownership.

Taking Ownership of a QueryUse the following procedure to take ownership of a query from a user. You will now own the query and it will appear in your Personal folder.

To take ownership of a query:

1. Log on to NWQ Administrator, and open the Queries tab.

2. From the Show queries owned by drop-down list, select All Users or the specific user that owns the query to delete.

- OR -

Search for the query by entering a word or phrase in the Find Queries field, and then clicking Go.

3. A list of Web queries will be displayed. Check the box next to each query you want to take ownership of.

4. Click Take Ownership. You will now own the query and it will appear in your Personal folder.


Giving Ownership to Another UserIf for some reason you need to give the ownership to another user, use the following procedure.

To change a query's owner:

1. In NWQ, navigate to your Personal folder, and then check the box next to the required query.

2. Click the Give link.

NOTE: If you do not see this link, you may need to modify the NWQ feature permissions for the profile you are currently logged on with.

3. The Give Query Ownership page appears. Do one of the following, and then click Next:

a. Enter the user name of the person you want to give the query ownership to.

- OR -

b. If you do not know the name, click Next to display a list of users. Double-click the required user.

4. A confirmation page appears. Verify the information is correct, and then click OK.

5. The query will be deleted from your Personal folder, and will be added to the other user’s Personal folder.

6. The Give Query Ownership: Status page appears, confirming the ownership has been transferred successfully.

Redirecting QueriesWhen a query is created, it is based on a single virtual table (VTable) or related VTables (the base VTables) in Noetix QueryServer (NQS). If a base table is deleted, made obsolete, or replaced with a different VTable, you will need to rebase the queries that were created against it. Rebasing a query involves changing the base VTable of the query and pointing the query to a new one.

NOTE: Two or more VTables are related if foreign-key relationships have been defined in NQS between each VTable and at least one of the other VTables.


It is also possible to migrate a query that has been created in a different instance of Noetix WebQuery (NWQ) (for instance, in a test or development instance). The query can be migrated to another system and based on a corresponding VTable or related VTables. Migrating a query to a different system requires that you have logon information for each system.

Rebasing a QueryWhen a query is created, it is based on one or more base tables, that is a single virtual table (VTable) or related VTables, located in NQS and exposed in NWQ. If a base table is deleted, obsolete, or replaced with a different table, you must rebase the queries that were created against that base table.

Rebasing a query means:

• If the query is based on a single VTable, then that VTable (base table) is replaced.

• If the query is based on related VTables, then one or more of those VTables (base tables) are replaced.

You may need to rebase a query if:

• A query is no longer usable because its base VTable was deleted or corrupted.

• Due to a regeneration, an obsolete base VTable has been deleted and replaced with a new VTable.

To rebase a query, a replacement VTable must exist in NQS. This replacement must meet the following criteria:

• The VTable contains every column the current base table contained. (It is okay if the new VTable contains other columns in addition.)

• Each corresponding column in the current and new VTables have the same datatype.

IMPORTANT: If a query is based on related VTables, then it is built on base tables with a particular join relationship. If any of these base tables are deleted or replaced, then the join relationship changes. Once the query is rebased, you need to restore the original join relationship by creating joins between the replaced VTables and the unchanged VTables to equal the joins that originally existed. For information about creating joins, see the NWQ User Help.


Only queries in your Personal folder can be rebased. To rebase a query, you must be granted the Rebase profile and have Select permissions on the new base VTables. You will also need to be in Manage mode.

You will only be able to browse to VTables exposed in the VTables folder in NWQ. If the target VTable is not displayed in the VTables folder, you can do either of the following:

• Add the subfolder containing the VTable to your user account’s default subfolders list in NQS, and ensure you have Select permission to it;

- OR -

• Write down the name of the NQS folder and subfolder containing the VTable, and type the location instead of browsing to it in step 4 below.

You may be able to rebase a query to a base table yet not have permission to run the query after it is rebased. Check your NQS permissions to the VTable, connection, and so on, to manually ensure you have the appropriate permissions.

To rebase a query:

1. Navigate to the folder that contains the query you would like to rebase.

2. Check the box in front of the query's name. You can select multiple queries if required.

3. Click the Rebase link.


4. For each query you have chosen to rebase, specify the new destination VTable using one of the following methods:

• For each of the query’s VTables that must be replaced, click the Browse button to browse to and select the replacement VTable. To browse to a VTable, it must be exposed in NWQ under the VTables folder. For that, the VTable must be in one of your NQS default subfolders.

- OR -

• Type the name and path to the target VTable in the text box next to the query. The syntax should be <Folder>.<Subfolder>.<VTable>.

- OR -

• If you want to migrate all selected queries to VTables in the same subfolder, type the names of the folder and subfolder in the text boxes in the upper right-hand corner and click Apply All. Then, verify or enter the VTable names for each query.

5. When the new VTables have been specified for each query listed, click OK.

6. A Finished page displays with a message that the queries were rebased successfully, or that errors were encountered. Click OK to go back to NWQ.

Migrating a Query to a Different SystemTo migrate a query that has been created in a different instance of NWQ (for instance, in a test or development version of NWQ), the query can be migrated to another system (for instance, the production instance) and based on a corresponding virtual table (VTable) or related VTables. Migrating a query to a different system requires that you have logon information for each system, and a valid VTable (or related VTables) exists in the system you are migrating to (the target system).

You may need to migrate a query if:

• You have more than one NQS and want to pass Web queries from one to another.

• You write queries on a test or development version of NWQ and then need to copy them to users in production.


You select a VTable or related VTables in the target system to be the base table for your migrated query. This new base table must meet the following criteria:

• The target VTable contains every column the original VTable contained. (It is okay if the target VTable also contains other columns.)

• Each corresponding column in the target and original VTables have the same datatype.

• You can browse to the target VTables in the VTables folder in NWQ (the base table is in a subfolder in your default subfolders list in Noetix QueryServer (NQS)).

Only queries in your Personal folder can be migrated. To migrate a query, you must be granted the Migrate profile and have Select permissions on the new base VTables. You will also need to be in Manage mode.

You will only be able to browse to VTables exposed in the VTables folder in NWQ. If any of the target VTables are not displayed in the VTables folder, you have two options:

• Add the subfolder containing the VTable to your user account’s default subfolders list in NQS, and ensure you have Select permission to it; or

• Write down the name of the NQS folder and subfolder containing the VTable, and type the location instead of browsing to it in step 4 below.

You may be able to migrate a query to a base table yet not have permission to run the query after it is migrated. Check your NQS permissions to the VTables, connection, and so on, to manually ensure you have the appropriate permissions.

Migrating a query does not automatically share it to other users or give users permissions on the query after it has been copied over. You will need to manually publish or share the query and verify that users have the correct permissions to view and run it. The original query's related queries and publications to the Public folder also are not copied over.

To migrate a query:

1. Navigate to the folder that contains the query you would like to migrate.

2. Check the box in front of the query’s name. You can select multiple queries if required.

3. Click the Migrate link.


4. Enter the logon information for the target Noetix Gateway (gateway). This includes a user name and password of a user on the target system that has Select permissions on the target VTables, the name of the server on which NWQ is installed, and the port your gateway uses, if this has been set up to be different than the default, “80.”

NOTE: The user you enter will be the owner of these queries on the target system, and the queries will be saved in this user's Personal folder.

5. If prompted for a responsibility, select an Oracle E-Business Suite responsibility from the list, then click Continue.

6. For each query you have chosen to migrate, specify the new destination VTable using one of the following methods:

• Click the Browse button to browse to and select the VTables. To browse to a VTable, it must be exposed in NWQ under the VTable folder. That is, the VTable must be in one of your NQS default subfolders.

• Type the name and path to the target VTable in the text box next to the query. The syntax should be <Folder>.<Subfolder>.<VTable>.

• If you want to migrate all selected queries to VTables in the same subfolder, type the names of the folder and subfolder in the text boxes in the upper right-hand corner and click Apply All. Then, verify or enter the VTable names for each query.

7. After VTables have been specified for each query listed, click OK.

A Finished page displays with a message that the queries were migrated successfully, or that errors were encountered. Click OK to go back to NWQ.

Sharing QueriesYou may share customized queries with users by granting them access to a query, giving them a copy of a query, or publishing a query to the Public folder.

Sharing queries with users does not give them access to the Noetix QueryServer (NQS) virtual table (VTable) the query is based on. If a user has trouble executing a query you have shared, check their permissions in NQS.


You can only share queries that you own – that is, queries in your Personal folder. To share, you must also have a Noetix WebQuery (NWQ) profile that grants access to the “Sharing” features. This is not granted by default in the default profile. For more information about NWQ profiles, see Profiles in “Security.”

To share a query that has been created in a different instance of NWQ (a development or test instance, for example), you will first need to migrate the query to the required NWQ system. For information about sharing a query, see Migrating a Query to a Different System.

Granting Access to a QueryWhen you grant a user access to a query, the user can run the query, but cannot change or delete the query. Subsequent changes you make to the query will affect all users granted access to the query. The query will display in the user’s Personal folder in a subfolder called “Queries shared by: [Your user name].”

To grant access to a query:

1. In your Personal folder, browse to the query you want to grant access, then click the query name.

2. A menu will display to the right of the query. Click Sharing.

3. On the Sharing page, click Grant this query to someone.

4. Select the user from the left-hand list. Using the –> button, move this user to the right-hand list.

To grant access to all users listed, use the >> button.

5. Click the Grant Now button.

To revoke access to a query:

• On the Sharing page, select the user, and then click the Remove All Grants button.

Giving a Copy of a QueryWhen you give a copy of a custom query to another user, the user may change, delete, or otherwise customize the query copy without affecting your original query. The query will display in the user’s Personal folder.


To give a copy of a query:

1. In your Personal folder, browse to the query you want to copy, and then click the query name. A menu will display to the right of the query.

2. From the menu, click Sharing.

3. From the Sharing page, click Give a copy of this query to someone.

4. Select a user from the left-hand list.

5. Click the Copy To button.

6. Repeat the steps previous steps for each user who needs a copy.

Publishing a QueryPublishing a query will save a link to your query within the Public folder. When you publish a query to the Public folder, any users with the proper folder permissions can access it. Other users can run the query, but cannot change or delete the query. Any time you make changes to your query, they will be reflected in this published query as well.

For more information about Public folder permissions, see Granting Public Folder Permissions.

To publish a query:

1. In your Personal folder, browse to the query you want to publish, and then click the query name. A menu displays to the right of the query.

2. From the menu, click Sharing.

3. On the Sharing page, click Publish this query to a public folder.

4. Click the Browse button.

5. Navigate to the Public folder where you would like to publish this query.

6. Click OK. The Publish page appears.

7. Click Publish. The Publish page displays the new folder where the query is published, as well as any folders where the query has already been published.


To publish a query within Manage mode only:

1. In your Personal folder, confirm that you are in Manage mode. If not, click the switch to manage link.

2. Browse to the query you want to publish, and select the check box.

3. Click the Sharing:Publish link.

4. Navigate to the Public folder and subfolder where you would like to publish this query.

5. Click OK. A dialog box informs you that the query has been published.

6. Click OK. You are returned to the My Web Queries page.

7. To confirm the publishing of the query, click the query name. A menu displays to the right of the query.

8. Click Sharing.

9. On the Sharing page, click Publish this query to a public folder. The Publish page should display the new folder where the query is published, as well as any folders where the query has already been published.

To delete a published query:

• On the Publish page, select the published query, then click the Remove button.

This will delete the query from the Public folder, but will not delete the original from your Personal folder.

Querying in ExcelNoetix WebQuery (NWQ) allows you to run Web queries in Microsoft® Excel, embedding the query logic directly into the spreadsheet. The resultant data can be easily saved within Excel and refreshed for up-to-date results.

IMPORTANT: When you run a query in Excel in NWQ, only 65,535 rows and 256 columns will be returned regardless of the version of Excel that you use. If you have to run queries that have more than 65,535 rows and 256 columns, then use Noetix Add-in for Microsoft Excel (add-in) with Excel 2007 or 2010. For information about the add-in, see the Noetix Add-in for Microsoft Excel Help.


This feature is enabled by default for all users, except in the following cases:

• You have set up Noetix Platform to use Oracle E-Business Suite security.

• You need to run long-running queries.

Instructions for setting up NWQ to query in Excel in these cases are listed in the following sections.

Querying in Excel for Oracle E-Business Suite UsersThe Query in Excel feature of NWQ does not automatically include the Oracle E-Business Suite responsibility prompt when running queries. To enable the Oracle E-Business Suite prompt for all querying in Excel, you will need to set the value of the ExcelQueryPromptResponsibility element to “Yes” in the Noetix.Gateway.Service.exe.config file. After making the change, all users executing queries in Excel will be prompted for a responsibility. Users who are not configured with Oracle E-Business Suite responsibilities can simply type % at the prompt and click OK. For more information about the Noetix.Gateway.Service.exe.config file, see Noetix.Gateway.Service.exe.config in “Maintenance.”

Managing Query DeliveriesIn NWQ Administrator, you can manage query deliveries by updating the respective subscriptions and their schedules.

IMPORTANT: To be notified about the success or failure of the subscription deliveries through e-mail messages, you must configure Database Mail in Microsoft SQL Server, and then configure SQL Server Agent Mail to use Database Mail. For information about configuring Database Mail, see Setting Up an E-Mail Profile in “Maintenance.” For information about configuring SQL Server Agent Mail to use Database Mail, see the Microsoft documentation.


Managing SubscriptionsThe Subscriptions tab lists the details of a given subscription and lets you delete subscriptions. The system displays subscriptions by their name, query name, user, delivery method, next run (as determined by the schedule), schedules, and last run. You can update the subscriptions list by clicking Refresh.

If you click the link under Next Run for a particular schedule, you will be taken to the Subscription Schedules tab and shown the details of that schedule. You can see the entire schedule list by clicking Show all.

Managing Subscription SchedulesThe Subscription Schedules tab shows you the schedule details for each subscription, including the next run and whether the schedule is enabled. On this tab, you can delete, disable, or enable schedules. You can see the current schedules by clicking Refresh.

Managing Subscription ProfilesTo control the use of query delivery in NWQ Administrator, you can turn subscriptions completely on or off by updating the Subscriptions feature in the Profile Properties:Query feature list.

For more information about query deliveries and query delivery subscriptions, see the NWQ User Help and the NWQ Administrator Help.

Folder ManagementIn Noetix WebQuery (NWQ), queries are organized into three main folders:

• Personal folder: Each user has his or her own Personal folder, where queries he or she creates or customizes can be accessed. Queries that users share directly with other users can also be found in the Personal folder.

• Public folder: NoetixViews and NoetixAnswers can be accessed in this folder. You can also “publish” any queries you want to the Public folder to allow other users to access them.


• VTables folder: The virtual tables (VTables) created in Noetix QueryServer (NQS) that have been exposed in NWQ can be found in this folder. These can be run as queries or copied, to customize and format them further. The queries are grouped into subfolders based on how you have set up folders and subfolders in NQS.

Within the Personal and Public folders, you have the ability to manage the folder structure and where queries are saved. Additional folders can be created, modified, renamed, and deleted, and you can manage the permissions for Public folders as well.

To manage folders, you need to be the owner of the folder, or have permissions to the folder. Users will have control over their Personal folders, which contain queries they have customized or that have been granted to them. You can set permissions on the Public folder and any subfolders to determine who can manage the same features in the Public folder.

Adding a FolderYou can add subfolders to help organize your queries in a manageable fashion. To add folders or to make changes to existing folders, you will need to be in Manage mode.

To add a folder:

1. In Noetix WebQuery (NWQ), confirm you are in Manage mode. (If you are not, click the switch to manage link.)

2. Navigate to the folder under which you would like to add a new folder.

3. Click the Add Subfolder link.

4. Enter the name and description of the new folder. Each subfolder needs a name that is unique within the folder. Adding a description to the folder will make it easier to manage your folders as more and more folders are created.


5. Enter the business value for the new folder. The business value determines in which position (order) the folder will display.

You must enter numbers for the business value. For instance, if you want the folder to display at the top (first), enter “1”. If you want the folder to display at the bottom (last), enter a large value, such as “9999.” To allow the contents of the folder to sort by name, check the box next to Use Default Business Value.

NOTE: If a folder contains both subfolders using defined business values and subfolders using default business values, the subfolders using default values will display at the bottom of the list, sorted by name, below those whose positions were defined. Folders with the same position will also sort by name.

6. Click the OK button.

Editing a FolderTo edit a folder:

1. In Noetix WebQuery (NWQ), confirm you are in Manage mode. (If you are not, click the switch to manage link.)

2. Navigate into the folder itself; you should see the name of the folder at the top of the page and all its contents below.

3. Click the Edit link.

4. Edit the name and description of the folder as required. Each subfolder needs a name that is unique within the folder. Adding a description to the folder will make it easier to manage your folders as more and more are created.


5. Edit the business value of the folder as required. The business value determines in which position (order) the folder will display.

You must enter numbers for the business value. For instance, if you want the folder to display at the top (first), enter “1”. If you want the folder to display at the bottom (last), enter a large value, such as “9999.” To allow the contents of the folder to sort by name, check the box next to Use Default Business Value.

NOTE: If a folder contains both subfolders using defined business values and subfolders using default business values, the subfolders using default values will display at the bottom of the list, sorted by name, below those whose positions were defined. Folders with the same position will also sort by name.

6. Click the OK button to save changes.

You can also delete or rename a folder from within the folder itself using the links displayed at the top of the page.

Granting Public Folder PermissionsFolder permissions allow you to determine who can access a certain Public folder or subfolder in Noetix WebQuery (NWQ). You set up folder permissions by granting a folder to a role, and then setting the permission level. Then any user granted this role will have access to the folder at the specified permission level.

For example, say you create a new folder called “Sales Reports” in the Public folder that the sales managers need to access. You also have a Noetix QueryServer (NQS) role named “Sales Manager” that has already been granted to all sales managers.

So, to grant all the sales managers access to the new folder, what you would do is grant the “Sales Reports” folder to the “Sales Manager” role. Assuming all sales managers have already been granted access to the underlying data, the managers would now be able to access the “Sales Reports” folder and run the queries.

Folder permissions do not grant users permission to run queries, only to view, publish, or delete them. For more information about permissions to run a query, see Granting Permissions to a VTable in “VTables and Mappings.”


To grant a folder permission to a role:

1. In NWQ, confirm you are in Manage mode. If you are not, click the switch to manage link.


3. Click the Permission link.

4. On the Folder Permissions page, select a role type (group of roles) from the list at the top of the page. The roles available under this role type will display.

5. Click the required roles to select them. To select more than one role, hold down the CTRL key as you click each role.

6. Click the Grant button. This will add the roles to the Granted Roles list.

7. Click a single role from the Granted Roles list. The permissions assigned to this role display in the Permission area.

8. For each granted role, Grant, Inherit, or Revoke each permission level as required. For more information about permissions, see Permissions in “Security.”

9. Click Apply.

You can change or remove the permissions granted to a role using the Folder Permissions page as well. Select the required role from the Granted Roles list, and then make the required changes to the permissions or click Remove.

Chapter 6

Users and Organizations

This chapter explains how to set up and organize Noetix users.


OverviewIn most businesses, access to data is granted to groups of individuals because of their department or job. For instance, the entire sales department may have access to some pieces of data, but only the sales managers can access other pieces of data. Generally, the number of individuals who need special access to data is limited.

Noetix QueryServer (NQS) provides additional security objects beyond simple user accounts, called organizations and roles. Providing an easy way to grant permissions to large numbers of users greatly simplifies security administration.

NOTE: Unless otherwise specified, the tasks in this chapter are performed using NQS Administrator.

UsersUsers of Noetix are set up with a user name and password in NQS Administrator. User accounts can be quickly imported from existing database or directory sources, like an e-mail server, or new accounts can be created manually. The user name (what the user types into the logon window) must be unique within all of NQS; the full name (first and last name) must be unique within a particular organization.

When an end user attempts to log on to NQS, or to access NQS data through Noetix WebQuery (NWQ) or a reporting tool, he or she must know a user name and password combination that is valid for that particular NQS. Once logged on, the end user can access virtual tables (VTables) on that NQS based on the permissions that has been explicitly or implicitly granted to this user.

For more information about creating user accounts, see Users.

Create a user to:

• Create logons for end users who will access data through NQS or NWQ.

• Set up additional user accounts for specific administrative tasks.

Chapter 6: Users and Organizations 135

OrganizationsAn organization is a group of users, usually arranged by department or job functions (Sales, Development, Finance, and so on). Since individuals in a specific department or function usually have similar data access needs, organizations can make it easy to grant permissions to groups of users at a time.

Each user account must belong to one and only one organization, either the default Users root or a custom organization you create.

An organization is hierarchical, and there is no limit to the number of levels you can create in your hierarchy. A user account always belongs to one and only one organization. This, again, reflects back to the model of a business organization chart: Typically, an employee does not belong to multiple organizations in a business.

For more information about creating organizations, see Grouping Users into Organizations.

Create an organization to:

• Organize your users into a logical, manageable structure (for example, departments or job duties).

• Be able to grant permissions to a group of users instead of manually to each individual user.

• Reduce the administrative tasks involved in tracking users’ access to data.

External AuthenticationThe “External Authentication” feature can be enabled to help manage the passwords associated with Noetix QueryServer (NQS) users. When this feature is enabled for a user, NQS does not store the password for the user account. Instead, it stores the path back to the authority from which the user account was imported. Then, when the user logs on to NQS, the password he or she enters is simply passed on to the directory or database for authentication. Based on the return from the authority, NQS either accepts or denies the user’s logon.


Steps for Setting Up Noetix UsersFollow these steps to set up users and organizations:

1. Create and/or import organizations/groups.

2. Create and/or import user accounts.

3. Place your users into meaningful organizations based on your organization chart.

4. Create roles that map closely to job functions.

5. Grant these roles permission to the necessary servers, connections, virtual tables (VTables), and mappings.

6. Assign organizations and/or users to these roles.

7. Grant or revoke permissions at a user level (if any exceptions to inherited permissions are needed). To minimize maintenance tasks, limit the number of exceptions whenever possible.

Before You BeginGather user information: Decide which users should have access to NQS. In NQS Administrator, users can be set up individually or they can be imported in bulk from an external directory or from a database (for example, Microsoft SQL Server or Oracle Database). If required, users can be placed into an organizational hierarchy.

Most businesses have many directories already in their enterprise, found in their e-mail system, network operating system (NOS), Web site, databases, and so on. Most of the time, the NOS has the most comprehensive directory and is the best candidate to be used with the Users and Roles Wizard. Importing from an NOS has an added advantage in that it is generic and not tied to any specific resource. You can configure NQS so that the same logon that gives users access to the network gives them access to their data.


When configuring NQS as part of your Noetix solution, you will also need to decide whether you have a need for separate users within NQS than in NoetixViews. If the same set of users will be using each product, you will want to set up users within NoetixViews and then run Noetix Generator for Noetix Platform—Oracle E-Business Suite Edition (Noetix Generator), Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator), or NoetixViews for Siebel Business Applications (NoetixViews for Siebel) to generate the users into NQS.

NOTE: Users set up or modified directly in NQS will not be exported back to the original source. Noetix recommends that you use the source of these users as the “master,” and make any key changes there, then synchronize or regenerate the users into NQS.

Determine security needs: Security issues can be dealt with either during or after importing users. For example, permissions on various objects within NQS can be granted to organizations and/or users explicitly or through the creation and assignment of roles. Permissions flow down an organizational hierarchy.

For an overview of Noetix security, see Security.

UsersEmployees within your enterprise will access Noetix QueryServer (NQS) and Noetix WebQuery (NWQ) using accounts you set up and permissions you grant them. The procedures in this section will help you create and maintain these accounts with minimal effort.

Importing UsersUsers can be imported from databases, e-mail servers, or other data sources in your enterprise. By importing users from existing sources, you can allow them to use the same user names and passwords they are accustomed to.

You can import users using the Users and Roles Wizard as described in the following procedure.


To import users:

1. In NQS Administrator, click on the toolbar. The Administrator Wizards dialog box appears.

2. On the Basic Setup tab, double-click Setup Users and Roles.

3. The Users and Roles Wizard begins, and the welcome page appears. Click Next.

4. The Definitions page appears with definitions of NQS users, organizations, roles, and role types. Click Next to continue.

5. You have two import options:

• If importing from a directory, select a Directory Type. If required, select a Host Name. Click Next.

NOTE: If you select as directory type a generic LDAP provider, Microsoft Exchange Server, or Active Directory, you must specify a host name.

-OR-

• If importing from a database, select a server and connection. The connection you select needs to be based on a database user with administrative rights. (You can create this server and/or connection now if you haven't already.) Click Next.

6. Select the NQS password options for these users. The Use External Authentication option will allow users to log on with the passwords used in this source, and NQS will pass the logon credentials entered to this source for authentication. Click Next.

7. NQS will load the users it has found in the selected source. Select which user accounts to import by checking the boxes next to each account or group. Click Next.


8. Select an organization in which to put the users you import. You may selectively move users or groups from the left-hand pane into organizations you select in the right-hand pane. The default option is to put the users in the Users root organization. To select a different organization or create a new one, click the ellipses button [...]. Browse to an existing organization or click the New button to add an organization.

Click the Preview button to see an overview of your organization structure, then click Next.

For more information about organizations, see Grouping Users into Organizations.

9. Select any default subfolders you want to grant these users. Click Next to continue.

10. For more information about default subfolders, see Granting a Default Subfolder in “VTables and Mappings.”

NOTE: Since granting default subfolders to organizations or roles is more efficient than granting them directly to users, you may want to accept the defaults on this page and grant default subfolders later.

11. Select how NQS should handle any duplicate role names that may be found when importing new users, if you have existing roles. Click Next.

12. Select how NQS should handle any duplicate user names that may be found when importing new users, if you have existing users. Click Next.

13. Select a log file for errors to be written to. Click Next.

14. The last page shows you an overview of what you are importing. Click Finish to import the user accounts.


Creating UsersUser accounts can also be set up manually in Noetix QueryServer (NQS). These user accounts can be externally authenticated just as imported user accounts, if required.

To create new users:

1. Right-click on the organization to which you will add this user (or the Users root item if required) and click New > User. The User property sheet will display.

2. On the General tab, enter the new user’s full name (for example, “Jack Jones”) and user name (for example “jjones”). Select one of the following authentication types:

• Password: If you choose this option, the password for the user will be stored in NQS. In the Password box, enter the password the user should use when logging on, then type it again in the Confirm box.

Select one of the following options:

• Password never expires: The password will stay in effect until an administrator or the user changes it.

• User must change password at first logon: When this is checked, the user is prompted to change their password the next time they log on to NQS or Noetix WebQuery (NWQ).

• Password expires on: This allows you to select the date and time that the password will expire. The user will be prompted to change their password the first time they log on to NQS or NWQ after this date and time. You can type in the new date and/or time, or use the arrows next to each box.

• External Directory: If you choose this option, you must map this NQS user to a user in a directory. When the user logs on, NQS will use external authentication to validate the user’s credentials.

In the Auth Path field, enter the path to the authority or click the ellipses [ ... ] to browse to the authority. Select a Directory Type. If required, select a Host Name.

NOTE: If you select as directory type a generic LDAP provider, Microsoft Exchange Server, or Active Directory, you must specify a host name.


• External Database: If you choose this option, you must map this NQS user to a database user account. When the user logs on, NQS will use external authentication to validate the user’s credentials.In the Ext. User field, type the name of the database user you will authenticate against. Select the button in front of RDBMS to authenticate against a database or Oracle Apps to authenticate against Oracle E-Business Suite.Click the ellipses [ ... ] on the connection field to browse to the authority you will use. The database must already be set up as a server in NQS, with the connection you want to use.

You may also limit the number of rows this user can retrieve in a single query to prevent runaway queries (long-running queries that tax the database).

3. On the Default Subfolders tab, select which subfolders this user needs to access through NWQ. This should only be done on a user-level if not inheriting these from a granted role or parent organization.For more information about default subfolders, see Granting a Default Subfolder in “VTables and Mappings.”

4. On the Roles tab, specify any roles you want to assign this user, unless they will be inherited from the parent organization. You may also do this later when setting up your roles.

5. On the Permissions tab, if necessary, specify any permissions this user should or should not have. Click Save to finish.

NOTE: It is more manageable to grant permissions through roles than directly through the Permissions tab. However, if you want to bar this user from accessing certain objects they may otherwise inherit from a role or organization, you may want to revoke their permissions to those items.


Administrative Users and RolesUsers within Noetix QueryServer (NQS) can be given administrative privileges by granting them administrative roles and permissions. If you have more than one person who will be functioning as a Noetix administrator, Noetix recommends that you create unique user accounts for each individual and then grant each the appropriate administrative roles, instead of performing all administrative tasks by logging on as SysAdmin. This will provide an accurate paper trail in your tracking logs and ensure everyone’s activities will not show up as being performed by a single user.

You may grant other administrative users the same permissions as the default SysAdmin user by granting them the N$SysAdmin role. You may also want to grant NQS administrators the N$BackupOperators and/or N$QueryAnalyzers roles, and Noetix WebQuery (NWQ) administrators the N$WebQueryAdmin and N$WebQueryProfileAdmin roles. These administrative roles are found under the N$System folder in NQS Administrator.

The SysAdmin UserThe SysAdmin user is created automatically during the NQS installation and has full permission to all objects in NQS. This user is the all-powerful user within NQS, equivalent to the Administrator user in Microsoft Windows or the Root user in UNIX. This user account cannot be deleted.

The SysAdmin user account should not be used to log on to NWQ or other query tools because some user options (such as sharing queries) will not be available. Noetix recommends that you create new users for both administrative purposes and end-user tasks.

After installing NQS, Noetix recommends that you change the SysAdmin’s password to something very difficult to decipher, then keep this information safe and secure. For information about changing SysAdmin’s password, see Changing Passwords.

For more information about roles and role types, see Roles in “Security.”


Administrative RolesThe administrative roles below are created automatically during installation.

• N$SysAdmin: Most of the SysAdmin user’s power comes from the fact that it has been granted the N$SysAdmin role. This role has been granted full permission to all objects in the system, excluding those within the N$System server group and folder. A user must be granted the N$SysAdmin role to run the Setup Wizards.

• N$BackupOperators: A user must be granted this role to back up or restore the repository.

• N$QueryAnalyzers: A user must be granted this role to select from the virtual tables (VTables) in the N$System.Monitor subfolder. Without this, a user cannot effectively use the NQS Monitor application (that is, they will not see any data). In addition, a user with this role has been granted all NQS Monitor permissions and can further grant these permissions as well.

To grant these permissions, on the Tools menu, click Monitor Permissions. The NQS Monitor permissions are:

• Flush cache/Change monitor settings: Users with this permission can flush the NQS Monitor cache from the Monitor Control dialog box. Also, they can change the NQS Monitor settings through the Monitor Settings dialog box.

• Start/Stop the monitor: Users with this permission can start or stop NQS Monitor from the Monitor Control dialog box. When NQS Monitor is stopped, all query monitoring is stopped, but any changes to the NQS metadata using NQS Administrator or DDL will be logged.

• Purge the monitor log: Users with this permission can purge the NQS Monitor log using the Purge Log dialog box. Once the log has been purged, the data cannot be retrieved.

• Query monitor status: Users with this permission can use the Monitor Control dialog box to view the current status of NQS Monitor.


• N$AgentOperators: Users with this role can schedule back-end jobs using the Noetix agent tools and manage these jobs and operators.

• N$WebQueryAdmin: Users with this role can fully administer the Public folder structure in NWQ. Users must have this role to create new folders in the Public folder area of NWQ.

• N$WebQueryProfileAdmin: Users with this role can create NWQ profiles through the NWQ Administrator application and then grant them to users through NQS Administrator.

• N$CategoryAdmin: A user must be granted this role to create a category or add, modify, or delete a category in a VTable. The SysAdmin user is initially granted this role; however, the N$SysAdmin role does not automatically grant a user this role.

NOTE: To add, modify, or delete a category from a VTable, a user must also be granted Alter permission on the category and all of the objects that currently have the selected category.

Changing PasswordsUsers and administrators can change their passwords in either NQS Administrator or in Noetix WebQuery (NWQ).

The SysAdmin user in Noetix QueryServer (NQS) and the NQS administrative users in Microsoft SQL Server require special steps to change their passwords.

To change the SysAdmin user’s password:

1. Open NQS Administrator and log on as SysAdmin.

2. Change the SysAdmin user’s password:

a. Select the Users node in the tree, then select the SysAdmin user in the list in the upper right.

b. Select the General tab.

c. Type the new password twice in the provided boxes.

d. Click the Save button.


3. If the LoopBack Server connection’s user is SysAdmin, you will want to change the password there as well. To update the LoopBack Server Connection:

a. Expand the Servers object in the tree and select the LoopBackServer.

b. Select the LoopBackServer_conn1 connection in the list to the right.

c. Select the Type tab.

d. Re-type the SysAdmin’s new password in the Password text box.

e. Click the Save button. The connection should still be in a validated state. (If the connection is not valid, it will have a red “X” through it in the left-hand navigator pane. If this happens, try re-typing the password and saving again.)

4. Update the Agent connection:

a. Select the Agent object in the tree.

b. Re-type the SysAdmin's new password in the Password text box.

c. Click the Recreate Agent Connection button.

To change passwords for the NQS administrative users in SQL Server:

If you want to change the passwords of the NQS administrative users in Microsoft SQL Server, you must use Noetix Platform Change Repository Password Wizard. For information about changing the NQS administrative users, see “Changing Database Users’ Passwords” in the section “Working with Users” in the NQS Help.

OrganizationsThis section provides information about organizations in NQS Administrator.

Grouping Users into OrganizationsAn organization is a group of users, usually arranged by department or job functions (Sales, Development, Finance, and so on). Since individuals in a specific department or function usually have similar data access needs, organizations can make it easy to grant roles and permissions to groups of users at a time.


Each user must be in one and only one organization, either the default Users root or a custom organization you create.

TIP: To avoid confusing organizations and roles, think of an organization as the office an employee works in and roles as keys to the building. Each employee works in one and only one building at a time (since you can’t be in two places at once). But employees may have a number of different keys to use within that building—the front door, their office, the supply closet, and so on—depending on the permissions the employee has been given.

To create an organization:

1. Right-click on the Users root item and click New > Organization. The Organization property sheet will display.

2. On the General tab, enter the new organization name and a description. You may also limit the number of rows users in this organization can retrieve in a single query to prevent runaway queries (long-running queries that tax the database).

3. Click the Default Subfolders tab. Add any default subfolders you want to grant to all members of this organization. You may grant these later if required.

For more information about default subfolders, see Granting a Default Subfolder in “VTables and Mappings.”

4. On the Roles tab, assign any roles you want members of this organization to inherit. You may also do this later when setting up your roles.

5. (Optional) Use the Notes tab to add notes about this organization, if required. (You will need to click Save before adding a note.)

6. On the Permissions tab, if necessary, grant any permissions members of this organization should or should not have. Click Save to finish.

NOTE: It is more manageable to grant permissions through roles than directly through the Permissions tab. However, if you want to bar this organization from accessing certain items members may otherwise inherit, you may want to revoke their permissions to those items here. For more information about permissions, see Permissions in “Security.”


To move users into an organization:

When creating a new user, the user is added to the organization you specified in the Users and Roles Wizard, or the organization you right-clicked when clicking New > User. You may move users from one organization to another simply by selecting the user and dragging and dropping into the required organization.

Note that the user will now implicitly inherit all permissions granted to the new organization and will lose any permissions inherited implicitly from the old organization. After this move, you should inspect the user’s effective permissions to ensure they are correct. To do this, browse to the user and double-click the user’s name. Then, on the Permissions tab of the property sheet, click the Show Effective button and examine the user's effective permission to servers, virtual tables (VTables), and other objects.

Chapter 7

Maintenance

This chapter explains the maintenance and configuration tasks for Noetix Platform.


OverviewUse the procedures in this chapter to configure your Noetix Platform and to perform periodic maintenance tasks.

Unless otherwise specified, the tasks in this chapter are performed using NQS Administrator.

Scaling Noetix Platform for Better Performance

The Noetix Platform software has been designed to be modular, giving you the ability to scale your solution as the number of users and/or data sources increases. You can start with a small deployment for a limited number of users and data sources and later scale the solution to fit your needs. The components that will interest you most when deciding how to scale Noetix Platform are the Noetix QueryServer service, your heterogeneous mapping configuration, and your caching setup.

Noetix Technical Support strictly recommends that you routinely check for the latest updates and patches for Noetix Platform and install them to get the best performance. The updates and patches address a wide range of topics from obvious bugs to performance issues.

Contact Noetix Technical Support for additional assistance with the tasks described in this section.

Also, periodic maintenance of the operating system and third-party software, such as Microsoft SQL Server, Microsoft SQL Server Reporting Services, Internet Information Services (IIS), Microsoft .NET Framework, and Microsoft Data Access Components (MDAC), improves the performance of Noetix Platform. For information about the maintenance tasks for the operating system and third-party software, see the respective product documentation.

http://www.support.noetix.com

http://www.support.noetix.com


Chapter 7: Maintenance 151

Scaling NQSThe techniques outlined in this section will help you to scale Noetix QueryServer (NQS) within your enterprise. In some cases, you might get the best performance by using multiple NQS computers.

For information about installing NQS components, see the Noetix Platform Installation Guide.

Memory UsageThe performance of Noetix Platform is dependent on the memory used by the Microsoft Windows Server, Microsoft SQL Server, and Noetix QueryServer service.

The memory used by Windows Server, SQL Server, and Noetix QueryServer service can be monitored through the Windows Server operating system's Performance tool (click Start > Control Panel > Administrative Tools > Performance). For information about working with the Performance tool, see your Windows Server documentation.

Windows ServerTo determine whether the Windows Server has sufficient memory for all its tasks (including NQS), you must monitor the server for excessive virtual memory paging in the Performance tool.

You can do that through the Pages/sec counter associated with the Memory object and the Avg. Disk sec/Transfer counter associated with the LogicalDisk object, where the LogicalDisk instance is the disk that contains the Pagefile.sys file.

Multiply the values of these two counters. If the product of these values is greater than 10 percent (0.1) of the total memory on a recurrent basis, then the system needs more RAM.

SQL ServerYou can monitor and record the amount of memory that SQL Server uses through the Total Server Memory (KB) counter associated with the SQLServer:Memory Manager object in the Performance tool.

If the amount of memory used by SQL Server exceeds 50 percent of the server’s physical memory, then you should consider either increasing the amount of RAM on your server (recommended) or moving the NQS repository to a different server.


Noetix QueryServer ServiceTo deliver the highest performance, the Noetix QueryServer service keeps a majority of its metadata in a memory cache. During normal query activity, the Noetix QueryServer service has little interaction with the repository database. The Noetix QueryServer service operates using the information cached in the memory. Thus, as the amount of metadata increases, the amount of memory that the Noetix QueryServer service needs increases.

Another key indicator on the server is the amount of memory being used by the Noetix QueryServer service. You can also track the memory used by the Noetix QueryServer service through the Working Set counter of the Comconnection instance associated with the Process object in the Performance tool.

If you have SQL Server on the same server as NQS, then the combined memory used by both SQL Server and the Noetix QueryServer service should not exceed 75 percent of your server's physical memory. If it does, you must increase the amount of RAM on your server.

IMPORTANT: If the memory usage of Noetix Platform is more than 1.7 GB, then the Noetix QueryServer service stops responding. For better performance in scenarios that require large-scale memory usage, Noetix Platform is compiled with the /LARGEADDRESSAWARE linker option set to YES. Therefore, the /3GB and /userva switches in the Boot.ini file of the server can be modified for allocation of more memory to the Noetix QueryServer service. For information about the linker option and switches, see the Windows Server documentation.

The Server’s ProcessorBesides memory, the other important server resource is the CPU. The CPU on your server is adequate as long as the %Processor Time counter associated with the Processor object stays consistently below 80 percent and the Processor Queue Length counter associated with the System object stays at or below 2. If these thresholds are exceeded on a regular basis, you should upgrade the server to one with a faster CPU, or one with multiple CPUs.


The Server’s NICMost scalability issues can be resolved by increasing either the memory or processing power. But, with a very high amount of query traffic you may run into a situation where the techniques mentioned earlier no longer produce results. In most cases, the bottleneck to further scalability will be due to the fact that most servers have a single network interface card (NIC). Every request for data must be routed through the NQS computer, and a large number of requests may be bottlenecked trying to enter or leave the server through your NIC. There are two solutions to this problem:

• Verify that you are using a NIC with the maximum bandwidth available on your network. If you have an old 8-bit NIC in your server, you should upgrade to the fastest NIC possible for your network. If your company is running a 100-MB network, you must verify that your server has a 100-MB NIC and that it is truly running close to this speed. If most of the NQS activity is coming from Noetix WebQuery (NWQ) and you have installed the Web server on a separate computer, then you should consider creating a fast backbone connecting these two servers using the Fiber Distributed Data Interface (FDDI) technology or fiber optics.

• Add additional NICs or a specialized NIC that has multiple ports, and set up adapter teaming. Adapter teaming is set up to maximize performance in and out of a server. This lets the server assign a single IP address to multiple cards. Traffic is then distributed among these NICs, providing increased bandwidth and performance. This configuration is analogous to the gains realized when multiple Integrated Drive Electronics (IDE) or Small Computer System Interface (SCSI) controllers are used to maximize the I/O performance of hard drives.

For information about installing the NQS components, see the chapter “Installing Noetix Platform” in the Noetix Platform Installation Guide.

Scaling Heterogeneous MappingsNoetix QueryServer (NQS) uses the heterogeneous join functionality in Microsoft SQL Server to provide heterogeneous mappings. Heterogeneous joins are required when the data needs to be pulled from more than one database and joined together to produce a single report. If you have defined heterogeneous mappings for your virtual tables (VTables), and a query spans databases, then NQS will use this functionality of SQL Server to combine the data into a single result set.


The job of processing a heterogeneous query is processor-intensive and consumes a lot of memory. These processor and memory requirements increase as the amount and complexity of the data increases. You should monitor the amount of resources used by the repository instance of SQL Server if you are performing heterogeneous queries or if these queries return considerable data.

Within NQS, your heterogeneous mappings will point to a heterogeneous mapping server (HMS). This is an instance of SQL Server. By default, your NQS repository server is also setup as an HMS (with the name HMServer), and this server is located in the N$System server group. This is the default HMS, and all heterogeneous mappings built by the administration wizards use it.

If the processing of your heterogeneous queries seems to be slowing down your system, you should consider moving this functionality from your NQS computer to a different server.

Adding a New HMSTo add a new HMS, use the Servers and Connections Wizard in NQS Administrator (on the Tools menu, click Administrator Wizards > Setup Servers and Connections) to define this new server. For more information about creating a server using the Servers and Connections Wizard, see Creating a Server in “Servers and Connections.”

After you have created the server, select it in the right pane of the NQS Administrator window, and click the General tab in the lower-right pane. Next, select the Can be used for Heterogeneous Mappings check box.

Changing the Default HMSThere are different wizards within NQS Administrator that help you set up your virtual tables (VTables) and mappings. Most of them have the ability to automatically set up heterogeneous mappings for you. To change the default HMS in NQS Administrator:

1. On the Tools menu, click Options. The Options dialog box is displayed.

2. The Default Heterogeneous Server box displays the server to which the

heterogeneous mapping points to. Click next to the Default Heterogeneous Server box, browse to your newly added server (in the previous section), and select it.


3. Click OK or Apply to save your changes.

Now, whenever one of the wizards adds a heterogeneous mapping, it will point to this HMS.

Load BalancingYou can define additional HMSs without changing any mapping definitions. To do this:

1. In NQS Administrator, navigate to and select the required mapping in a virtual table (VTable).

2. In the lower pane, click the Heterogeneous tab in the Map Properties dialog box.

3. Select the heterogeneous mapping that you want to change, and click Edit.

4. Click next to the Server box, browse to the required HMS, and select it.

5. Click Save.

Scaling the Noetix Cache Maintenance ServerThe Noetix Cache Maintenance Server (CMS) or report server is another memory and processor-intensive component. If you have installed CMS on the same computer as your Noetix QueryServer service and you are caching a lot of mappings, then you must watch its resource usage. If this usage starts to interfere with Noetix QueryServer (NQS) performance, you must increase the RAM of your server or move CMS to a new computer (recommended). For more information about caching and CMS, see Caching.

If you have moved CMS to a new computer, you can also watch its resource usage to determine when you should add a second CMS.


Removing CMS from the NQS ComputerBefore you start the process of removing CMS from your NQS computer, you must prevent cache refresh jobs from starting. The easiest way to do this is to stop the Agent process. To do this, right-click the Agent node in the left pane of the NQS Administrator window, and click Stop Agent in the shortcut menu. Depending on how long it takes you to set up the new CMS computer, you should make sure you know which of your mappings (if any) would have been refreshed while the CMS was being switched. After the new CMS computer is functional, you can manually refresh these mappings.

To remove CMS from your NQS computer, you must uninstall Noetix Platform.

Installing CMS on a New ComputerCMS can be installed on multiple computers that are running on Microsoft Windows in your network. This lets you easily scale your caching capabilities by installing CMS on additional servers. After this is done, NQS will immediately start using the new server.

During the installation process, CMS is installed as a Windows service and connects to the specified Noetix QueryServer service. For more information about the CMS installation, see the chapter “Installing Noetix Platform” in the Noetix Platform Installation Guide.

You should install CMS on multiple servers as your needs increase. After you have more than one CMS up and running, NQS will automatically balance the load between them. For information about how NQS handles load balancing among different CMSs, see Architecture.

Log FilesThis section provides information about the log files created by Noetix Logging Service, Noetix Add-in for Microsoft Excel (add-in), and the Noetix QueryServer service. It also provides information about how the log files must be removed.

Creating Log FilesThe creation of log files and the ways to identify the log files are discussed in the following sections.


Noetix Logging ServiceNoetix Logging Service creates two types of log files as part of running the Noetix Platform installation wizard or Noetix Platform Prerequisite Checker (Prerequisite Checker). These files store valuable information about the Noetix Platform environment in your organization. For more information about the log files, see About Log File in “About Noetix Platform.”

Types of Log FilesThere are two types of log files created by Noetix Logging Service. For information about the types of log files, see Types of Log Files in “About Noetix Platform.”

Location of Log FilesFor information about the location of log files, see Location of Log Files in “About Noetix Platform.”

Naming Convention of Log FilesThe log file name indicates the name of the computer on which the application (installation wizard or Prerequisite Checker) was run, the name of the application, and the date and time when the application was run.

Depending on the type of the log file, the file name extension is either .log or .xml.

The log file name comprises three parts, which are as follows:

• Part 1: The computer on which the application was run. In this case, the computer name is TESTSRV.

• Part 2: The application that created the log file. In this case, it has been created using the Noetix Platform 5.5 SP1 installation wizard.

• Part 3: The date and time (session) when the application was run. In this case, the application was run on February 15, 2007, at 18:32:54.

In addition to these three parts, the .log file name is suffixed with “Details.”


Noetix Add-in for Microsoft ExcelErrors that occur while performing a task in the add-in are saved in a file for future reference. This file is created when an error occurs for the first time in the add-in. Information about the subsequent errors are saved in the same file.

The log file is a .txt file. By default, the name is Error Log.txt. The name should be changed only if you want to archive the file. The error messages are saved only to a file that is named Error Log.txt. When the file name is changed, another .txt file with the name Error Log.txt is created to save the subsequent errors.

Information in Log FileThe log file provides the following information:

• The date when the error occurred. The date is specified in the mm/dd/yyyy format.

• The time when the error occurred. The time is specified in the hh:mm:ss AM or PM format.

• The error message as displayed in the application.

• Information about how to track the error that occurred.

Location of Log FileThe log file is created on the computer on which the Noetix Add-in for Microsoft Excel (add-in) is installed.

It is created in <hard disk drive>:\Documents and Settings\<user name>\Application Data\Noetix\Noetix Add-In for Microsoft Excel <version of Microsoft Excel>.

If the Noetix folder does not exist at this location, then a folder named Noetix is created when the first error occurs.

Noetix QueryServer ServiceThe Noetix QueryServer service creates log files to trace the information relating to the tasks performed in Noetix QueryServer (NQS).


Types of Information Logged by Noetix QueryServer ServiceThe Noetix QueryServer service logs the following types of information:

• Fatal: Includes errors that make the application unstable or unusable.

• Error: Includes errors that occur in the application. These are expected errors, such as a user attempting to run a virtual table (VTable) without having permissions on it.

• Warning: Includes conditions that do not cause errors or prevent functionality but that point to potential problems.

• Debug: Includes information that is used for debugging purposes. This may include information about parameters, functions, or other programmatic levels of detail.

• Information: Includes information at the most detailed level about every task performed in Noetix Platform.

IMPORTANT: By default, the log file logs only the fatal errors. To log any other type of information, contact Noetix Technical Support.

Naming Convention of Log FileThe name for the log file is ComConnection<process ID>.log, where process ID is a numeric value that is assigned by the operating system when the Noetix QueryServer service is started.

Each time the Noetix QueryServer service is restarted, a new process ID is assigned, and therefore, a separate log file is created.

Location of Log FileThe log file is created in <hard disk drive>:/Program Files/Noetix/Log of the NQS computer.

This folder is created when the log file is created for the first time. Otherwise, this folder is not available.



Managing Log FilesThis section provides information about what happens to the log files when the respective program is uninstalled and how to manage and remove the log files.

Noetix Logging ServiceUninstalling Noetix Platform does not delete the log files from your computer. If you want to remove the log files from your computer, you must manually delete or archive them. Deleting the log files from your computer helps you track them more efficiently, especially when there are too many log files on your computer.

Noetix Add-in for Microsoft ExcelUninstalling Noetix Add-in for Microsoft Excel (add-in) does not delete the log file. If you want to remove it, you must delete it manually.

If you want to have separate log files for each installation of the add-in, you must archive the log file of each installation by changing the file name from Error Log.txt to an intuitive name. It is recommended to archive the file, otherwise all the messages will be displayed in one file making the maintenance and tracking of error messages difficult.

Noetix QueryServer ServiceUninstalling Noetix Platform deletes the log files. If you want to retain the log files pertaining to one instance of Noetix Platform, then you must save them in a different location before uninstalling Noetix Platform.


Noetix Agent ToolsThe Noetix agent tools allow you to schedule recurring tasks and automatic alerts. You can set up agent jobs to periodically scan your metadata for issues or to receive alerts about specific conditions in your data (for example, sales exceeds 5,000 orders).

To send notifications about the success or failure of agent jobs and alerts for the agent jobs to operators by e-mail and pager, you must configure the agent tools as follows:

1. Set up an e-mail profile in Microsoft SQL Server2. Create operators in NQS Administrator3. Create agent jobs with notifications or create data alerts and validation alerts for

agent jobs in NQS Administrator

Setting Up an E-Mail ProfileNoetix Platform uses Microsoft SQL Server’s SQL Server Agent Mail feature to send e-mail notifications about the success or failure of agent jobs and e-mail alerts for agent jobs. SQL Server Agent Mail uses Database Mail to send e-mail notifications and alerts. Therefore, you must configure Database Mail, and then configure SQL Server Agent Mail to use Database Mail. Then, you must configure the Noetix agent tools with the mail profile created while configuring Database Mail. For information about configuring Database Mail and Noetix agent tools, see the information provided below. For information about configuring SQL Server Agent Mail to use Database Mail, see the Microsoft documentation.


The first task in configuring the agent tools is to set up a Database Mail profile with administrative privileges. You can set up a Database Mail profile in SQL Server in one of the following ways:

• By using the Database Mail Configuration Wizard: You can use the Database Mail Configuration Wizard to accomplish the first six steps in the procedure. For more information about using the Database Mail Configuration Wizard, see the SQL Server documentation.

• By using Transact-SQL: You can configure a Database Mail profile by running Transact-SQL statements in the query window of SQL Server Management Studio. Transact-SQL statements to perform the first six steps listed in the following procedure are tabulated after the procedure. For more information about using Transact-SQL, see the SQL Server documentation.

To set up a Database Mail profile for agent jobs:

1. Enable the Database Mail feature on the SQL Server computer.

2. Create a Database Mail account.

3. Create a Database Mail profile.

4. Add the Database Mail account that you created in step 2 to the Database Mail profile you created in step 3.

5. Grant the Database Mail profile access to the msdb public database role and make the profile the default Database Mail profile.

6. Send a test e-mail from SQL Server.

7. Change the mail properties for SQL Server Agent to use Database Mail. Specify the Database Mail profile that was created in step 3.

8. Run the Agent Configuration Utility in NQS Administrator, and provide the default Database Mail profile as your new Database Mail profile.


Transact-SQL statements for the first six steps of the above procedure are as follows:

Step No. Transact-SQL statements

1

beginexec sp_configure 'show advanced options', 1RECONFIGURE WITH OVERRIDEexec sp_configure 'Database Mail XPs', 1RECONFIGURE WITH OVERRIDEexec sp_configure 'Agent XPs',1RECONFIGURE WITH OVERRIDE

2

EXECUTEmsdb.dbo.sysmail_add_account_sp@account_name = 'MyMailAccount',@description = 'Mail account for Database Mail',@email_address = '[email protected]', @display_name = 'xxxxxxxx',@username = 'xxxxxxxx',@password = 'xxxxxxxx',@mailserver_name = 'xxxx.xxxxxxx.xxx' ;

3

msdb.dbo.sysmail_add_profile_sp@profile_name = 'MyMailProfile',@description = 'Profile used for Database Mail' ;

4

EXECUTEmsdb.dbo.sysmail_add_profileaccount_sp@profile_name = 'MyMailProfile',@account_name = 'MyMailAccount',@sequence_number = 1 ;

5

EXECUTEmsdb.dbo.sysmail_add_principalprofile_sp@profile_name = 'MyMailProfile',@principal_name = 'public',@is_default = 1 ;


Table 7.1 Transact-SQL statements to configure a Database Mail profile.

NOTE: Provide appropriate values for account name, description, e-mail address, profile name, user name, password, mail server name, and recipients.

Creating OperatorsThe next step is to create operators, the users who want to receive notifications about the success or failure of agent jobs and agent job alerts through e-mail messages. After setting up Noetix QueryServer (NQS), operators are added using NQS Administrator. Ensure that your NQS is running before starting this task.

Additional operators can be created at any time.

To create an operator:

1. On the left-hand side of the main window (the Navigator area) of NQS Administrator, expand the Agent node listing to show its submenus.

2. Right-click Operators and choose New Operator. The New Operator properties sheet appears in the main window. For more information about any of the tabs, click the tab and press F1.

3. Type the operator's unique full name along with a destination for the notifications and alerts. The destination for the notifications and alerts can be an e-mail address,

pager address, or workstation on the network. Click to select the e-mail or pager address from your system’s address book.

When using a pager as a destination, you may specify the on-duty days and hours during which a message can be sent.

4. Click Save.

6

declare @body1 varchar(100)set @body1 = 'Server:'+@@servername+ ' My First Database Email 'EXEC msdb.dbo.sp_send_dbmail@recipients='[email protected]',@subject = 'My Mail Test',@body = @body1,@body_format = 'HTML' ;

Step No. Transact-SQL statements


Creating Agent JobsThe final step is to create the agent jobs that you want to run. Jobs are created using NQS Administrator. If you want to send notifications about the success or failure of agent jobs and the agent job alerts through e-mail messages to the operators, the operators must first be created using the steps mentioned in Creating Operators.

The Agent Job Wizard helps you create a validation agent job or a data alert job. A validation agent job alerts if any of the mappings are no longer valid, and a data alert job informs when a certain condition occurs in the data.

Agent jobs can also be created manually using the New Job property sheet.

To create a job using the Agent Job Wizard:


2. Right-click on Jobs, and choose:

• New Auto-Job > New Validation Agent Job to create a validation agent job

• New Auto-Job > New Data Alert Job to create a data alert.

To create a job manually:


2. Right-click on Jobs, and choose New Job.

For more information about the tabs in the Job properties sheet, press F1 in the selected tab.

Creating a Data AlertA data alert alerts you when certain conditions are met in your data. You define an SQL statement using the virtual tables (VTables) you have defined in Noetix QueryServer (NQS) that returns one row and one column of data.


Then, you define what conditions need to be met for an alert to be sent. For example, you can write an SQL statement that returns the current number of orders for today. You can then define a condition that alerts you when that number exceeds 5,000.

To create a data alert using the SQL page:

1. On the left-hand side of the NQS Administrator window, click Agent. The submenus are displayed.

2. Right-click on Jobs, and in the New Auto-Job menu, click New Data Alert Job. The Create a New Agent Job wizard appears.

3. Click Next. The Instructions page for creating an agent job appears.

4. Click Next. The Query Builder wizard appears. You have to use the standard Query Builder to build an SQL statement that uses VTables in your NQS. The Query Builder only lets you add tables from your local NQS repository.

Remember that the SQL you build can only return one column and one row of data.

5. Click . The Add Table page appears. Under the From box, select a server and a database you want to use. All the tables for the selected database are displayed in the Tables/Views box.

6. Select a table, and then click Add. Click the Close button to close the Add Table page. The table and its columns are displayed in the Table area.

7. Double-click the column for which you want to set the criteria. The column details are displayed in the Column area.

8. Type the filter conditions for the column in the Criteria field. These criteria relate to the WHERE clause in a query and restrict the data returned by the query. If the criteria (WHERE clause) contains an "OR" operator, use the additional "Or ..." fields.


9. Click Close and Keep Changes to save the column criteria and quit the Query Builder wizard. The Data Alert Condition page appears.

10. To add a condition in the Data Alert Condition page, select an operator from the list, then type an appropriate value. Some operators (like “equals”) require one value, some operators (like “between”) require two values, and some (like “exists”) do not require any value. For example, select “equals” from the drop-down list box and type 5000 in the box. A job alert will be sent to the user when the quantity reaches 5,000. Click Next.

You can combine up to three different conditions with AND or OR. To add more conditions, select the check box of the next row.

11. In the Edit Job Properties page, create or edit the schedule properties and select the operators to be notified from the Notify via E-mail list. Click Next. The job alert is created.

12. Click Finish to exit the Create a New Agent Job wizard.

To send a job alert manually (other than at the scheduled time), right-click the job that you want to send in the NQS Administrator window’s detail view area, and then click Start Job. Click View History to view the status of the job.

Creating a Validation JobThe Validation Agent is a separate application that runs on the computer on which you installed your Noetix QueryServer (NQS) repository.

NOTE: If you have installed your NQS repository on the same computer as NQS then the Validation Agent would already be installed for you. If your NQS repository is on a separate computer than your NQS then you will need to install the agent tools on the repository computer.

When the agent is opened, it scans the metadata to detect any issues. This includes most errors that might prevent a particular virtual table (VTable) or mapping from being used. Any errors or warnings that are discovered are written to a table called N$System.Base.IM_JobLog, and can be viewed in NQS Administrator under the \Agent\Logs item in the Navigator. Note that you will have to refresh the Navigator (using the F5 key) to view any new logs if you run a validation agent job from NQS Administrator.


You can also specify the objects that should be checked by the agent. You can pick a

particular folder, subfolder or VTable to validate by clicking . All VTables and mappings under this chosen object will be validated.

To create a validation agent job:

1. On the left-hand side of the NQS Administrator window, click Agent. The submenus are displayed.

2. Right-click on Jobs, and in the New Auto-Job menu, click New Validation Agent Job. The Create a New Agent Job wizard appears.

3. Click Next. The Instructions page for creating a validation job appears.

4. Click Next. The Validation Agent Options page appears.

5. Type the name and password to connect to and validate your VTables and mappings.

6. Select one of the following options to indicate the object that the validation agent must validate:

• All of them: Validates all the objects in the server.

• Starting at: Validates only the objects that you select to validate. To select

specific objects for validation, click . The Locate Folder, Subfolder or VTable dialog box appears. You can select the object you want to validate, and then click OK. The selected object and its children will be validated. Click Next.

7. In the Edit Job Properties page, create or edit the schedule properties, and select the operators to be notified from the Notify via E-mail list. Click Next. The Validation Agent Job alert is created.

8. Click Finish to exit the Create a New Agent Job wizard.

To send a job alert manually (other than at the scheduled time), right-click the job that you want to run in the NQS Administrator window's detail view area, and click Start Job. Click View History to view the status of the job.


CachingWhen implementing any decision support system, all administrators are eventually faced with the problem of performance. Relational databases store information in a very efficient manner, especially if the database is highly normalized. But they do not always retrieve this information efficiently for reporting and other operations.

If queries take longer than a few seconds to return their first row of data, most users get restless. If queries take longer than a few minutes, users complain.

The caching feature in Noetix QueryServer (NQS) has been designed to handle this issue. Noetix administrators can configure a mapping to be cached, as well as define a schedule for its caching. After this is done, the Noetix QueryServer service does the work of maintaining the cache tables and then redirecting user requests to the cached data.

Architecture


NQS is able to cache data with the help of Noetix Cache Maintenance Server (CMS). This component does the real work of caching the data from the source to the defined cache connection, that is, the target.

CMS can be installed on multiple computers in your network as long as they meet the minimum system requirements. This can include the computer on which you are running NQS. CMS is installed as a Windows service (CacheMaintenanceServer) on a computer and connects to NQS. If CMS must connect to a database other than Microsoft SQL Server (source or target), you must also install and configure the vendor's database connectivity software on the CMS computer.

When NQS determines that a cache should be refreshed from either a scheduled or manual launch, it queries all CMSs that have been connected and determines which one is the least active. It then passes the cache request to the chosen CMS, which loads the data from the source system and inserts the data into the cache table. More specifically, CMS runs the mapping's Record Source against the source database and then inserts the results of this query into the cache table on the target system.

After the cache has been refreshed, CMS reports the results back to NQS. If the cache refresh is completed successfully, NQS will automatically reroute all subsequent user requests to the cache table.

RecommendationYou might consider installing CMS on a dedicated cache computer to reduce network traffic.

About the Cache ConnectionCMS has the ability to cache a mapping's data to either a Microsoft SQL Server database or an Oracle (7.3.4 or later) database. This means that you could cache from a DB2 database to an Oracle database, or from Oracle to SQL Server, and so on.

If possible, Noetix recommends that you set up a cache-enabled mapping connection back to the same database instance as the source data. This will let you join cached and non-cached virtual tables (VTables) with greater ease without having to use heterogeneous mappings. You will experience better performance with this configuration. For more information about heterogeneous mappings, see Heterogeneous Mappings in “VTables and Mappings.”


Caching VViewsTo cache a virtual view (VView), the connection type must be the default connection. The default Loopback Server is configured with a pass through connection. So to cache a VView, you need to create a new Loopback Server and a connection configured with the default connection. Then use that new server and connection with the VView mapping you want to cache.

Things to Consider• You must first define the connection to the cache destination either manually or

with the Servers and Connections Wizard.

• A connection can only be used as a cache connection if it has been set to the default type (not prompt, pass through, or lookup).

• Consider the amount of information you may be moving over the network. You might want to have the CMS computer as well as the source and target database computers on a fast network backbone.

• If you are caching to a computer other than the source, remember that if you join this virtual table (VTable) to any other VTable on a different connection (cached or non-cached), heterogeneous mappings will be used.

• If the source data and the CMS are from different database vendors, some vendor-specific data types may not work properly (that is, Unicode data types).


About Caching ModesYou can configure a cache-enabled mapping in either of the two modes: one-copy or two-copy.

One-Copy ModeIn one-copy mode, CMS creates and maintains only one cache table on the cache database. This is ideal if you want to minimize the space required for this mapping's cache. The disadvantage is that, while the cache is being refreshed, this mapping will not be accessible to users, that is, it will be offline.

Table 7.2 Advantage and Disadvantage of One-Copy Mode

Two-Copy ModeIn two-copy mode, CMS creates and maintains two different tables on the cache database. The first time the mapping's cache is refreshed, CMS creates a table and loads the data into it. The next time that the mapping's cache is refreshed, CMS creates a second table and loads the current data into it. During refresh, any user requests is routed to the first table. When the refresh is finished, CMS instructs Noetix QueryServer (NQS) to cut over to the second table and any new requests from users is redirected to the second table. This occurs as each new refresh is completed.

In NQS Administrator, these two tables are referred to as the Active and the Inactive Tables.

Table 7.3 Advantage and Disadvantage of Two-Copy Mode

Advantage Disadvatage

Minimizes space used Data is offline during refresh

Advantage Disadvantage

Data is always available Requires enough space for two copies of the cached data


About Cache IndexesIndexes help relational databases return your queries faster. This is also true for cache tables, so Noetix QueryServer (NQS) lets you define indexes for your cache tables.

You should define indexes that include the fields that will most likely be filtered on by your end users. Any index that you define is created and maintained by CMS. If you make changes to the indexes you have defined for a cache-enabled mapping, the following changes will take effect the next time the cache is refreshed:

• You can create multiple indexes for a cache-enabled mapping.

• An index can contain one or more columns.

• Some databases can be affected by the order of the columns in the index. Please check with your database vendor's documentation for more information.

When caching to a Microsoft SQL Server database, CMS creates cache table indexes that are non-unique and non-clustered.

When caching to Oracle, CMS creates cache table indexes that use the default storage parameters for the user defined in the chosen cache connection.

About Routing Queries to Cached MappingsWhen choosing a cache connection, you should take into consideration the other virtual tables (VTables) and mappings that may be used in conjunction with (or joined to) this cached mapping.

For example, let us say that you have four VTables (each with one mapping) that use the same connection. You enable caching on one of the mappings and choose a different cache connection for it. Now, if a user sends a query that joins one or more of the non-cached mappings to the cached-mapping, Noetix QueryServer (NQS) will be forced to route the query to a common heterogeneous mapping (if one exists). The down side to this is that using a heterogeneous mapping usually results in poorer performance.


Another thing to remember is that you can have multiple mappings on a VTable where some are cached and some are not. By adjusting the cost or access to these mappings, you can route certain queries or users to live or cached data.

Caching a MappingYou cannot cache a mapping if it has more than one connection. For more information about connection, see Connections in “Servers and Connections.”

Creating a Cache for a MappingTo create a cache for a virtual table (VTable) mapping:

1. In NQS Administrator, navigate to and select the required mapping in a VTable for which you want to create a cache.

2. In the lower pane, click the Cache tab in the Map Properties dialog box.


3. Select the Enable check box. Enter the following information, and then click Save:

• Connection to cache to: Select the connection you want to cache to.

• Mode: Click one of the following caching modes:

• If you need to minimize the space required to cache the VTable, then click One Copy. The cached table will not be available when refreshing.

• If space is not an issue and you want to ensure that the cached VTable is available when refreshing the cache, click Two Copy. If a cache job fails, the old cache will still be accessible to the end users.

• Refresh Timeout: Type the hours and minutes for the time-out.

• Indexes: Click in the Index area, select the required columns from the Build Index dialog box, and then click OK.

• Refresh Properties: Click this to create the cache. The Refresh Mapping Job dialog box is displayed.


4. To create the cache immediately, click Start Refresh in the General tab.

When the cache is completed, you can click the Logs tab to view any error messages that might have occurred during the caching process.

Scheduling a Cache for a MappingTo create a cache schedule job for a virtual table (VTable) mapping:

1. Create a cache for the VTable by performing steps 1 through 3 in “Creating a Cache for a Mapping.”

2. When you reach the Refresh Mapping Job dialog box, click the Schedules tab.

3. Click Add in the Schedules tab to add a caching schedule. The Schedule - New Properties dialog box is displayed.


4. In the Schedule - New Properties dialog box:

• Enter the name for the caching schedule in the Name box.

• Select the Enabled check box. To run a scheduled cache job, it must be enabled and the Agent must be started.

NOTE: If you want to create a scheduled cache job but not run it, save the information in the Schedule - New Properties dialog box without selecting the Enabled check box.

• Select a schedule for the caching job by clicking the required option button in the Schedule Type area.

5. Click Save.

Using Your Cached MappingsBefore users can use a cached mapping, it must be refreshed at least once. If it is not refreshed, an alert is displayed stating that the cached data is not available. Hence, for the first time you must manually refresh the caching. For information about refreshing a caching, see Managing Cached Mappings.

NOTE: After you enable caching on a mapping, Noetix QueryServer (NQS) attempts to route users to the cache. If the cache is not refreshed even once, an alert is displayed when they try to use this mapping.

It is recommended that you schedule your cache to be refreshed periodically. The frequency of your cache refresh will depend on the data that you are caching and your user needs. You will want to schedule your cache to be refreshed during off-peak hours so that the refresh process does not interfere with other work.

The General tab of the Refresh Mapping Job dialog box displays information about the latest refresh of a cache. Use this information to help you plan out the refresh schedule for the cache. For example, if it is taking 2 hours to refresh a cache, make sure that you schedule the cache refresh to run at least 2 hours before the first user accesses the updated data.


Managing Cached MappingsTo view all the cached mappings in NQS Administrator, click Cache Status on the Tools menu. The Cache Status dialog box displays all the cache-enabled mappings in Noetix QueryServer (NQS) and their current status.

In the Cache Status dialog box:

• To refresh the status, click Update Display.

• To manually start the process of refreshing a mapping’s cache, then select the mapping in the Cache enabled maps list and click Refresh Now.

• To view a mapping’s property page, double-click the mapping in the Cache enabled maps list or select the mapping and click Properties.

Caching LimitationIf your Oracle database (source) contains data prior to January 1, 1753, then you will not be able to cache this data to Microsoft SQL Server. This is because SQL Server datetime data type cannot accept date values below January 1, 1753. If you attempt to cache data prior to January 1, 1753, an alert will be displayed and the caching will fail.

As a workaround, you can cache the data to another Oracle database.

Cached virtual table (VTable) mappings of Unicode data must use connections that employ the native Oracle ODBC driver. Unicode data should not be cached from an Oracle database to a SQL Server database because Unicode characters are not converted correctly.


Backing Up and Restoring Repositories

Noetix recommends backing up your Noetix environment regularly. If a problem occurs, this will allow you to restore your system to the state it was in at the time of the backup. Performing a backup is also recommended before upgrading to a new version of the Noetix Platform.

Backing Up RepositoriesThe Backup Repository Wizard in NQS Administrator lets you back up your Noetix QueryServer (NQS) and Noetix WebQuery (NWQ) configuration and data. This tool is based on Microsoft SQL Server’s robust backup tool and lets you create a backup file of your NQS/NWQ repository, NQS Monitor repository, and/or SQL Server Reporting Services database.

You can also use this wizard to back up repositories used by Noetix Generator for Noetix Platform—Oracle E-Business Suite (Noetix Generator), Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator), and NoetixViews for Siebel Business Applications (NoetixViews for Siebel), if available.

You can choose to create your backup file immediately or schedule the backup for a later date.

NOTE: This process does not back up the NQS/NWQ file system, including configuration files. Backing up your Noetix servers on a regular basis is also recommended.

For information about the procedure of backing up the repositories, see “Backing Up NQS” in the NQS Help.


Restoring Repositories from Backup FilesThe NQS Restore Repository Wizard lets you restore the Noetix QueryServer (NQS) and NQS Monitor repositories and Microsoft SQL Server Reporting Services database from a previous backup.

You can also use this wizard to restore repositories used by Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator), Noetix Generator for Noetix Platform—Oracle E-Business Suite (Noetix Generator), and NoetixViews for Siebel Business Applications (NoetixViews for Siebel), if available.

Before you begin, you must complete the following tasks:

• Verify that NQS is installed and the Noetix QueryServer service is running. If you need to reinstall NQS, use the setup file that was used during installation.

• Locate the backup file on your file system. If the backup file exists on a different computer or tape device, copy the file to this computer (the computer on which NQS and/or client software are installed).

• Verify that your version of Microsoft SQL Server has not changed since the backup was created.

• While restoring the repository, the Noetix QueryServer service will be stopped temporarily. You may want to notify the users that NQS or Noetix WebQuery (NWQ) will not be available during the restore process.

• Ensure that the SQL Server Reporting Services and Noetix WebQuery Gateway services are stopped. These services can be stopped using the Services snap-in.

• Ensure that you have exited NQS Administrator and all the applications that use SQL Server.

• Obtain the user name and password of an NQS user who has been assigned the N$BackupOperators and N$AgentOperators roles.


Restoring Repositories Without Uninstalling Noetix PlatformThis section provides the procedure for restoring the repositories without uninstalling Noetix Platform. For information about the procedure of restoring the repositories without uninstalling Noetix Platform, see “Restoring Noetix Repositories from Backup Files” in the NQS Help.

Restoring Repositories on a Fresh Installation of Noetix PlatformThis section provides the procedure for restoring the repositories on a computer on which you have installed Noetix Platform, taken a backup of the repository, uninstalled Noetix Platform, and then installed it. When the repositories are restored in such a scenario, the NWQSystem user's password is not restored in the Noetix.Gateway.Service.exe.config file. Therefore, there will be problem in logging on to NWQ. For information about the procedure of restoring the repositories on a fresh installation of Noetix Platform, see “Restoring Noetix Repositories from Backup Files” in the NQS Help.

Support for UnicodeUnicode characters are supported in Noetix Platform. Unicode characters allow you to generate reports in multiple languages.

PrerequisitesTo ensure complete support for Unicode characters in Noetix Platform, you must take care of the following:

• The native Oracle ODBC driver must be used instead of Microsoft ODBC for Oracle driver to return Unicode data because the latter is not completely Unicode-compliant.

• The character set of the Oracle Home's must be set to “UTF8” using the NLS_LANG subkey. You can find the NLS_LANG subkey in the Windows registry at HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\.


• Cached virtual table (VTable) mappings of Unicode data must use connections that employ the native Oracle ODBC driver. Unicode data should not be cached from an Oracle database to a SQL Server database because Unicode characters are not converted correctly.

• The computer running Microsoft SQL Server Reporting Services must be configured with all the relevant language code pages and fonts to properly render files for subscription delivery. Otherwise, some file formats, such as CSV and PDF will return incorrect characters instead of Unicode characters.

• The computers running Noetix WebQuery (NWQ), Microsoft Excel or any other data client must have the proper language code pages and fonts installed to display Unicode characters correctly.

Setting the Locale of Noetix QueryServer ServiceOn the computer on which you have installed the Noetix QueryServer service, you can modify certain registry keys to specify a different locale for the Noetix QueryServer service so that it supports string comparison of Unicode characters.

After you have installed the Noetix QueryServer service on a computer, the following registry keys are created in HKEY_LOCAL_MACHINE\SOFTWARE\Noetix\QueryServer\CurrentVersion\Locale:

• LC_ALL: Sets all locale settings.

• LC_COLLATE: Affects string comparisons and collation.

• LC_CTYPE: Affects upper/lower case conversions, string length functions, and multi-byte to wide character conversions.

• LC_MONETARY: Affects monetary value formatting.

• LC_NUMERIC: Affects numeric value formatting.

• LC_TIME: Affects date/time formatting.


If the LC_ALL key is assigned a particular locale then all other keys will be ignored. By default, the value of this key is null.

By default, the locale is set to English for other keys if the respective key value does not exist. If you want a different locale, you should change the values of these keys after installation or upgrade and restart the Noetix QueryServer service.

Noetix Delivery Services Configuration Files

The Noetix Delivery Services rely on the configuration files for successful subscription delivery. Each service has its own configuration file with the elements that control their working.

IMPORTANT: Customizations to the elements in the Noetix DeliveryManager.exe.config and Noetix DeliveryServer.exe.config files will be effective only after the corresponding services are restarted.

Noetix DeliveryManager.exe.configThis file is located in <hard disk drive>:\Program Files\Noetix\NWQ\Delivery. The elements specified in this file regulate the working of Noetix DeliveryManager. You can customize the following elements in the file. However, to customize any other elements, you must contact Noetix Technical Support. You must use a text editor to modify this file.

• SystemPassword: Displays the password of the NWQSystem user.

• SMTP: Displays the address of the Simple Mail Transfer Protocol (SMTP) server for outgoing messages. This is the SMTP server that was specified during the installation of Noetix Platform.


• ReplyToUser: Sets a user name for the sender when delivering a subscription through e-mail. If this value is not set, Noetix DeliveryManager will use the default value, Subscriptions. The value set in ReplyToUser element will be used only if the Reply To box on the Delivery Preferences page in Noetix WebQuery (NWQ) is left blank when creating a subscription to be delivered through e-mail.

• ReplyToDomain: Sets the domain name (for example, xyz.com) when delivering a subscription through e-mail. If this value is not set, Noetix DeliveryManager will use the value set for SMTP element if available or the default value. The default domain name is set as an empty string. The domain name set in ReplyToDomain element will be used only if the Reply To box on the Delivery Preferences page in NWQ is left blank when creating a subscription to be delivered through e-mail.

NOTE: Customization to the values of the SystemPassword and SMTP elements will be lost if Noetix Platform is reinstalled.

Noetix DeliveryServer.exe.configThis file is located in <hard disk drive>:\Program Files\Noetix\NWQ\Delivery. The elements specified in this file regulate the working of Noetix DeliveryServer. You can customize the following elements in the file. However, to customize any other elements, you must contact Noetix Technical Support. You must use a text editor to modify this file.

NOTE: Customizations to the RegistrationIntervalMilliseconds and MaxRegistrationAttempts elements will not be effective. They are no longer supported by Noetix Platform.

• SleepIntervalMilliseconds: Sets the interval time, in milliseconds, for which each task processor thread waits when the central queue in Noetix DeliveryManager is empty. If this value is not set, Noetix DeliveryServer will use its own default value, 100.

• SystemPassword: Displays the password of the NWQSystem user.

• VerboseLogging: Enables you to view more descriptive and complete error messages in the event log for all the process levels. If this value is not set, Noetix DeliveryServer will use its own default value, true.


• MaxProcessorThreads: Sets the maximum number of task processor threads that can be run and managed in a thread queue. The default value is 5.

• WebRequestTimeoutMilliseconds: Sets the time, in milliseconds, for which the Web site waits for a response from Microsoft SQL Server Reporting Services. The default time-out is 15,000.

NOTE: Customization to the values of the SystemPassword and WebRequestTimeoutMilliseconds elements will be lost if Noetix Platform is reinstalled.

Time-Outs in NWQWhen running complex or long queries, Web service applications, such as Noetix WebQuery (NWQ), may face problems because the waiting time for retrieval of data may cause time-outs resulting in termination of the process at various places in the technology stack. To solve this problem, NWQ uses a process called data polling.

For more information about how a query is processed in NWQ, see How a Query is Processed in “About Noetix Platform.”

Data Polling in NWQData polling in NWQ includes two different processes. In the first process, the Noetix Gateway (gateway) connects to Noetix QueryServer (NQS) to retrieve the query header information from the schema. In the second process, the gateway connects to the database using the routing information from NQS to retrieve the rows. The gateway will wait for a specified time to return the first set of rows. If it does not return any row within that time, then the query header information from the schema is returned to NWQ, thus preventing a query time-out. Then, NWQ repeatedly polls for data until all the data is returned. Thus, the double-threaded process helps to keep the session active until all the rows are returned.


Settings for Time-OutsThe time-outs set in NWQ and in other external applications are as follows:

External Settings• Connection Timeout: Sets the maximum time (in seconds) after which the server

disconnects an inactive user. This ensures that all connections are closed if the Hypertext Transfer Protocol fails to close a connection. The default time is set to 900 seconds.

To change the Connection Timeout value, in the Internet Information Services window, navigate to Local Computer > Web Sites > Default Web Site, and then click Properties in the short-cut menu. In the Default Web Site Properties property sheet, type the value in the Connection Timeout box.

• httpRuntime/executionTimeout: Sets the maximum time (in seconds) that a query is allowed to run before it is automatically closed by Microsoft ASP.NET. The default time is set to 110 seconds.

To change the executionTimeout value, navigate to <hard disk drive>\WINDOWS\Microsoft.NET\Framework\<version number>\CONFIG\machine.config, and then type the value in the executionTimeout subelement under the httpRuntime element.


• Session timeout: Sets the maximum time to automatically end an inactive session (if the user has not used or refreshed a page of the application). The default time is set to 20 minutes.

To change the Session timeout value, in the Internet Information Services window, navigate to Local Computer > Web Sites > Default Web Site, and then click Properties in the short-cut menu. In the Default Web Site Properties property sheet, click the Configuration button on the Home Directory tab. The Application Configuration dialog box is displayed. In the Application Configuration dialog box, type the value in minutes in the Session timeout box.

• processModel/responseDeadlockInterval Timeout: Sets the time interval (in the standard process model format (HR:MM:SS)) after which the process is restarted if there are other requests in the queue or there was no response during the interval. The default time is set to three minutes.

To change the responseDeadlockInterval value, navigate to <hard disk drive>\WINDOWS\Microsoft.NET\Framework\<version number>\CONFIG\machine.config, and then type the value in the responseDeadlockInterval subelement under the processModel element.

NWQ SettingsThe time-outs for NWQ are set in the Noetix.Gateway.Service.exe.config file.

The following are the time-outs set for running a query in NWQ:

• Data polling time-out: Sets the time for which NWQ waits for schema information (columns, data types, etc.) to be returned before cancelling a query. This time-out is determined by a combination of values defined in the file. The time-out will be the lowest among the MaxDataWaitTimeout, ODBCTimeout, and recieveTimeout (a WCF setting) values. These time-out values should be modified only with the assistance of Noetix Technical Support.

• Command time-out: Sets the maximum time (in seconds) for which the gateway waits for the query to run. This value is defined in the ODBCTimeout subelement under the Execution element in the file. This time-out comes into effect only if any given operation against the ODBC driver takes longer than the set time, usually during the initial parsing and running of a query. The default value is 300.




• Repository time-out: Sets the maximum time (in seconds) that NWQ can take to interact with its own SQL server repositories. This value is defined in the SQLTimeout subelement under the Repository element in the file. The default value is 100.

The following are the time-outs set for running a query in Microsoft Excel:

• Excel link time-out: Sets the maximum time (in seconds) for which the gateway waits to retrieve all the data in one call in the IQY file format. This setting works in conjunction with ODBCTimeout. The gateway will use the lower value between the ODBCTimeout and ExcelLinkTimeout values. The default value is Infinite. This value is set in the ExcelLinkTimeout subelement under the Execution element in the file.

• Command time-out: This setting is the same as the Command time-out setting set for running a query in NWQ.

NWQ Configuration FilesYou may need to modify one of the configuration files for Noetix WebQuery (NWQ). This usually occurs when troubleshooting with Noetix Technical Support, but is also necessary for creating drill rules to allow users to drill between two queries in NWQ. This section explains how to work with these configuration files.

The Noetix Gateway (gateway) relies on configuration files, such as Noetix.Gateway.Service.exe.config, web.config, and nwqopt.xml for many of the parameters it uses when running queries. These parameters include time-out intervals and drill rules.

• Noetix.Gateway.Service.exe.config: This file contains the custom gateway settings, such as system accounts, elements for querying in Microsoft Excel, folder and computer names, and configuring drill rules. It affects NWQ and Noetix Add-in for Microsoft Excel (add-in). Some of its elements should not be customized without the assistance of Noetix Technical Support. This file is available in <hard disk drive>\Program Files\Noetix\NWQ\NoetixGateway\Server\bin. For information about the elements available in this file that can be customized by the user, see Noetix.Gateway.Service.exe.config.




• web.config: This file is used by the gateway. It is recommended that this file should not be customized without the assistance of Noetix Technical Support.

• nwqopt.xml: This file contains the settings that determine the working of NWQ. This file is available in <hard disk drive>\Program Files\Noetix\NWQ\nwq. For information about the elements in this file, see nwqopt.xml.

Noetix.Gateway.Service.exe.configThis file is found in <hard disk drive>\Program Files\Noetix\NWQ\NoetixGateway\Server\bin and contains the custom Noetix Gateway (gateway) settings. You must use a text editor to modify this file.

Gateway Settings

• NWQClientVirtualDir: Displays the virtual folder name where NWQ is installed. This folder is different from the virtual folders for the gateway or NWQ Administrator. The default value is /nwq.

• NWQClientDir: Displays the physical folder name where NWQ (client) is installed.

• InstallPath: Displays the NWQ Gateway installation path.

• GatewayUrl: Displays the NWQ Gateway URL that is used by the NWQ to determine the gateway’s URL. The default value is http://localhost/noetixgateway. If your organization policy requires the use of Secure Sockets Layer (SSL) for encryption of user credentials and data, then the URL must be https://localhost/noetixgateway. If you use a port number other than 80 (when you do not use SSL) and 443 (when you use SSL), then you must manually specify the port number after the server name with a colon. For example, if you use 3456 as the port number, then the URL must be changed to http://localhost:3456/noetixgateway.

• Query Timeout: Sets the maximum time after which an IQY file is deleted and replaced by a new one while running a query in Excel. The default value is 300.

• ExcelQueryDir: Displays the physical path to the folder where the .iqy files must be stored in the NWQ server.

• ExcelQueryUrl: Displays the virtual directory for the .iqy files. The default value is /noetixgateway/queries/.


• ExcelQueryPromptResponsibility: Determines whether the Oracle E-Business Suite responsibility prompt is displayed for the users when running a query in Excel. The valid values are Yes, No, and Inherit. The default value is Inherit, which indicates that the user will be prompted for a responsibility only if the user is an Oracle Applications user.

• ExcelQueryVer: Determines the earliest version of Microsoft Excel that users may want to run queries in. This decides whether NWQ can use the new Excel features to pass data to Excel. The default value is xp.

• SystemPassword: Displays the password for the NWQSystem user, which is used by NWQ to manage the NWQ profiles.

• Server: Displays the name of the SQL Server computer.

• Database: Displays the name of the NQS repository. The default value is nqsdb.

• User: Displays the name of the NQS repository administrator. The default value is nqsadmin.

• NQSHub: Displays the name of the NQS computer.

• SQLTimeout: Sets the time (in seconds) that NWQ takes to interact with its own SQL Server repositories. The default value is 100.

• SQLCommandTimeout: Sets the maximum time (in seconds) that Noetix repository (nqsdb) takes to return the data. The default value is 60.

• MonitorMode: Sets the initial mode of NWQ Monitor. The valid values are Stop and Start. The default value is Stop.

• Execution ODBCTimeout: Sets the maximum time (in seconds) for which the gateway waits for the query to run. Set a high value if you have to run queries that require more system resources. The default value is 300.

• ExcelLinkTimeout: Sets the maximum time (in seconds) for which the gateway waits to retrieve all the data in one call in the IQY file format. This setting works in conjunction with ODBCTimeout. The gateway will use the lower value between the ODBCTimeout and ExcelLinkTimeout values. The default value is Infinite.


• MaxDataWaitTimeout: Sets the maximum time (in seconds) for which the gateway waits for retrieving schema information and data. The gateway will use the lowest value among the MaxDataWaitTimeout, ODBCTimeout, and receiveTimeout (a WCF setting) values. The default value is 20.

• FetchBufferMultiplier: Sets the maximum fetch buffer size of the result set based on the requested fetch size. For example, if the requested fetch size set in NWQ is 200 and the fetch buffer multiplier is 4, then the maximum fetch buffer size will be 800. The default value is 4.

• FetchInactivityTimeout: Sets the maximum time (in seconds) the gateway waits between fetch calls before the query is cancelled. Pausing a query (by clicking the Pause button on the query results page of NWQ) for longer than the time set for the FetchInactivityTimeout element will cause the query to be cancelled. When you run queries in Excel, the gateway will attempt to fetch all the records in a single batch. In this case, the value of the FetchInactivityTimeout element should be set large enough so that all the records are retrieved in a single batch. Otherwise, the query might time out. The default value is 600.

• DisallowConflictResolution: Determines whether the restricted features for a user in NWQ is hidden from view or made visible, but unavailable. The default value is 1. This element can also be set in NWQ Administrator.

Drill Rule

• add RuleName: The name of the drill rule. This should be a descriptive name that will help you identify the purpose of the rule in the future. You may want to use a naming convention that helps you distinguish between the custom drill rules and the default drill rules, for example, by adding your company name as part of the rule name. This name will be displayed to the end users in NWQ when they do a drill across.

• DrillFrom > Columns > add Column: The columns specified in this field will be considered when searching for matches for the drill-from column.

• DrillFrom > Scopes > add Scope: This drill rule will be applied if the drill-from query exists in the specified folder or in one of its subfolders.

• DrillTo > Columns > add MatchOn: The columns specified in this field will be considered when searching for matches for the drill-from column.


• DrillTo > Columns > add FilterOn: The column specified in this field will be used to filter the results of the drill-to query.

• DrillTo > Scopes > add Scope: All the folders and subfolders from within the specified folder will be searched for the correlated queries.

nwqopt.xmlThis file is found in <hard disk drive>\Program Files\Noetix\NWQ\nwq. You must use a text editor to modify this file. You can edit the following elements in this file:

• gwpost: Name of the base virtual directory and the web service provider for the Noetix Gateway (gateway). This element must ideally never be changed.

• iqypost: Enables you to set up an NWQ Router which can pass through the firewalls. This element can be left blank if the firewalls are configured.

• QueryAuthor: Obsolete.

• DisplayCookieWarnings: Obsolete.

• MultipleValueDelimiter: Sets the character to be used as a delimiter when multiple values for a filter or a parameter are typed. The default delimiter used is the vertical bar (|).

• QueryPerPage: Sets the number of queries/reports to be displayed per page. The value set here is used by the Browse page in the Query Migration/Rebase wizard.

• LoadRowSize: Sets the maximum number of rows that the gateway can return per request. When you are running large queries, increasing the number of rows improves the query performance, but increases the server memory usage.

• QueryHistoryMax: Sets the maximum number of queries that are cached for an NWQ session. The value must be in the range of 1 to 20. A user can see the query history for an NWQ session by clicking My Recent Queries in NWQ.


• QueryCacheDuration: Sets the time (in minutes) for which query results are cached within a session. Within the set time, if a user runs a query more than once in a session, NWQ will fetch the stored results from the cache to improve the query performance. After the set time elapses, NWQ will go back to the server to fetch fresh results whenever a user runs the same query again. Set the query cache duration at “0” if you do not want to enable caching. Set the query cache duration at “-1” if you do not want query results to expire within a session. The user can still fetch real-time results for a query by clicking re-execute from the navigator.

NOTE: The queries are cached in the Internet Explorer process of the user’s computer. The query result cache is cleared when the user closes Internet Explorer after an NWQ session.

• AuthenticationSecurityLevel: Sets the level at which the user and domain credentials are secured. User credentials are used to log on to NWQ. Domain credentials are used to deliver subscriptions in NWQ. You use the domain credentials when you click the Deliver as this user option on the Options page of NWQ.

The values are Low, Medium, and High, and they are case-sensitive.

• Low: It is the default value. This value does not result in encryption of the user and domain credentials by NWQ.

• Medium: This value does not result in encryption of the user credentials by NWQ in the first call to the gateway. But, in subsequent calls, the user credentials will be encrypted. However, this value does not result in the encryption of the domain credentials.

• High: This value results in encryption of the user and domain credentials by NWQ with the use of SSL. Thus, for the High value to be used, SSL must be configured in IIS where the gateway resides.

If SSL is activated and users log on using the https://<computer name>/nwq/login.htm route, both data and credentials (user and domain) are encrypted. Thus, the authentication security level can be set to Low so that NWQ does not encrypt the user credentials again.

Because SSL secures both data and credentials (user and domain), it may cause performance issues. Alternatively, to improve performance, the High setting can be used and users required to log on through the http://<computer name>/nwq/login.htm route. In this case, only the credentials will be encrypted.


• DefaultDateTimeFormat: Specifies the default formatting for all columns of datetime data type that do not already have any formatting specified. The formatting specified by Noetix Generator for Noetix Platform—Oracle E-Business Suite Edition (Noetix Generator), Noetix Generator for Noetix Platform—PeopleSoft Enterprise Edition (Noetix Generator), or NoetixViews for Siebel Business Applications (NoetixViews for Siebel) for the generated reports and the ones specified in NWQ will take precedence over the value specified for this element. By default, the value is blank so that the formatting specified in NWQ for the columns of datetime data type is retained on an upgrade.

Data DrillsData drill is an advanced feature and requires an understanding of the data structure and building reports. Data drills allow you to select a column in your query result and view a detailed level of information from a summary level. In NWQ, we can do the following three types of data drills:

• Drill down: Lets you drill to a more detailed level of a query by adding other columns to the query results. Drilling down allows you to include additional columns from the query's base table, and also filter on a specific value of a column.

• Drill across: Lets you drill to a correlated query, restricting the results by a specific value. By default, correlated queries refer to any query in the Personal, Public, or VTables folders that have a column with the same name (or if you have renamed the column, with the same column alias) as the column that was selected for drill across. Drilling across is effective when other queries return additional details about the value you selected. You can only drill across to queries that you have permission to view and run.

• Drill through: Lets you drill to another query or a Web site to view related information using a column hyperlink or a URL hyperlink respectively. Drilling through is also effective when other queries return additional details about the value you have selected.

For more information about data drills, see “Data Drills” in the section “Working with Query Results” in the NWQ User Help.


Drill RulesDrill rules are specified in the Noetix.Gateway.Service.exe.config file. You must use a text editor to modify the file. There is no limit to the number of drill rules that you can create. In the file, there are four example drill rules that are created. There is one example of a static rule, two examples of dynamic drill rules, and one example of a drill rule that will use the A$ columns available in Noetix views. You must customize these drill rules to improve performance.

NOTE: After an upgrade of Noetix Platform from a version prior to 5.7, all the drill rules will be migrated from the previous version. However, the XML comments, if any, will not be migrated. If you need the XML comments, you have to manually provide them in the Noetix.Gateway.Service.exe.config file. After an upgrade of Noetix Platform from version 5.7 or later, there will be no change to the drill rules and XML comments.

Drill rules apply only to drill across. For the drill across feature to be usable, your administrator or a Noetix consultant must set up drill rules to correlate queries. The drill down and drill through features do not require any configuration and are available upon installation of Noetix Platform.

Drill rules decide which queries will be displayed when a user does a drill across (that is, which queries will be considered correlated). You can create drill rules to limit the scope of NWQ’s search for correlated queries and to define synonyms, that is, columns with different names but that can be considered equivalent, such as Customer and Account. When drilling from one query to another, NWQ runs the drilled-to query and limits the results to where the column equals the value you selected.

It is recommended that you customize or create the drill rules with the help of Noetix Technical Support.


For each drill rule you create, you will define the following:

1. Where the user is starting from:

• The folders you can drill from using the rule: This is the drill-from scope. The drill rule for which you have set this scope will be applied if the drill-from query exists in the specified folder or in one of its subfolders. You can use the static name of a specific folder (such as My Web Queries.Personal), or you can use a variable, which will be replaced with the name of the current folder.

• The columns in a query that you can drill from using the rule: This is the drill-from column. This drill rule will be applied if the user drills from a column defined in this field. You can use the column name or column alias that will be the start of the drill (such as Customer), or you can use a variable, which will be replaced with the name of the column on which you are performing the drill across.

2. Where the user can drill across to:

• The folders that should be searched for matches: This is the drill-to scope. All the folders and subfolders from within the specified folder will be searched for the correlated queries. You can use the static names of specific folders (such as My Web Queries.Public), or you can use a variable, which will be replaced with the name of the folder the user is drilling from.

NOTE: The drill-to scope should be set at the lowest level possible to improve performance. This will minimize the number of folders and subfolders that will be searched.

• The column in the drill-to query that should be considered a match: This is the match-on column. The columns specified in this field will be considered when searching for matches for the drill-from column. Queries that contain this column (and exist in an appropriate folder) will be displayed as correlated queries. You can use the column name or column alias to match (such as Account), or you can use a variable, which will be replaced with the name of the drill-from column. Other variables can also be used to either add or subtract a specific string (such as A$) from the name of the column before matching.


• The column in the drill-to query that should be filtered on: This is the filter column. The column that you specify will be used to filter the results of the drill-to query. Generally, you will want to filter the query on the same column that was used for matching. (For example, if you are drilling from the Customer column in one query to the Account column in another query, the query should be filtered by Account.) However, you can specify a different column to filter on if required. You can use the column name or column alias to filter on (such as Account), or you can use a variable, which will be replaced with the name of the column that was drilled from. Other variables can also be used to either add or subtract a specific string (such as A$) from the name of the column it filters on.

Supported Variables in Drill RulesIMPORTANT: You cannot mix variables and literals. For example, you cannot use Sales.[FOLDER].

The following table shows the context in which the various variables can be used while creating drill rules. In the table, “Y” indicates that the variable can be used for that element. Each variable is discussed in more detail after the table.

Table 7.4 Supported Characters for Drill Rules

VariableDrill-From Scope

Drill-To Scope

Drill-From

Column

Drill-To Column, Match-

On

Drill-To Column,

Filter

[FOLDER] Y Y

[PARENT] Y

[COLUMN] Y Y Y

string[COLUMN]

Y Y

{+:string} Y Y

{-:string} Y Y


• [FOLDER]: NWQ will replace this variable with the name of the current folder. When used in the drill-from scope, this means that the drilled-from query can be in any folder in NWQ. When used in the drill-to scope, this means that NWQ will search within the same folder as the one used for the drill-from scope.

• [PARENT]: NWQ will replace this variable with the name of the parent folder of the current folder. It can be used in conjunction with [FOLDER]. For example, [PARENT].[PARENT].[FOLDER] will cause NWQ to search in the folder two levels above the current folder, plus all subfolders within these folders.

• [COLUMN]: NWQ will replace this variable with the name of the drill-from column that the user selects. Only one column can be entered. Along with this variable, you can add the following:

• string[COLUMN]: This operator will always add the text specified for the string to the start of the column name. It is used in conjunction with [COLUMN].

• {+:string}: This operator will add the text specified for the string (if it is not present already) to the column name before searching. It is used before or after [COLUMN] (that is, as either {+:string}[COLUMN] or [COLUMN]{+:string}). For example, {+:A$}[COLUMN] will add A$ to the column name before searching for correlated queries. If [COLUMN] is Vendor, then the operator will add A$ to make the column A$Vendor. Queries that have the A$Vendor column will be treated as matches. If the column name already has a string added at the beginning or end (depending on where you put the operator), it will not be added.

• {-:string}: This operator will remove the text specified for the string (if it is present) from the column name before searching. It is used before or after [COLUMN] (that is, as either {-:string}[COLUMN] or [COLUMN]{-:string}). For example, {-:A$}[COLUMN] will remove A$ from the column name before searching for correlated queries. If [COLUMN] is A$Vendor, then the operator will remove A$, making the column name Vendor. Queries that have the A$Vendor column will be treated as matches. Nothing will happen if the column does not have a string.

IMPORTANT: You cannot mix more than one variable listed above. For example, you cannot enter {+:A$}[COLUMN]{-:_History}.


ExamplesThe following examples discuss the process of defining criteria for a drill rule, creating the rule, and explaining the result.

Drill Between Two Columns With Different NamesThis example shows how to create a drill rule that allows you to drill from one column to a column with a different name. This drill rule is static and does not use any variables.

Goal

Create a rule that allows users to drill from the Vendor column to the Supplier column, which are synonyms in this company. The Vendor column must be in a query located in a user’s Personal folder. The queries that they will likely want to drill to are located under the Suppliers and AP subfolders in the Public folder. For performance, we will only search within those subfolders for queries to drill to.

Creating the Rule

When creating the drill rule, you would enter the following values:

• Rule Name: “Find Suppliers from Vendors”

• Drill From Column: “Vendor”

• Drill From Scope: “My Web Queries.Personal”

• Match On Column: “Supplier”

• Filter Column: “Supplier”

• Drill To Scope: “My Web Queries.Public.AP” and “My Web Queries.Public.Suppliers”

Result

The drill rule above will be used when retrieving correlated queries if the user chooses to drill across from a column named Vendor in a query that exists in the My Web Queries.Personal folder (or any of its subfolders). When the rule is applied, it will tell NWQ to search in the My Web Queries.Public.Suppliers and My Web Queries.Public.AP subfolders (and their subfolders) for reports that have a column named Supplier. Any matching queries will show up in the Correlated Queries list when a user drills across. After the user runs one of the correlated queries, it will run the query with an added filter that states (Supplier = ‘[the value the user chose to drill from]’).


Drill Using Complex VariablesThis example shows how to create a drill rule that uses complex variables in the Columns fields. The example uses a default rule that is created upon installation.

Goal

Create a rule that allows users to drill from any column and match to Noetix indexed columns, which are prefixed with A$. For instance, a user should be able to drill from the Customer column to an A$Customer column in another query. The query should always be filtered on the column without the A$ prefix, however. The drill rule only needs to apply within the Public folder.

Creating the Rule

When creating the drill rule, you would enter the following values:

• Rule Name: “Noetix Indexed Rule”

• Drill From Column: “[COLUMN]”

• Drill From Scope: “My Web Queries.Public”

• Match On: “{+:A$}[COLUMN]”

• Filter On: “{-:A$}[COLUMN]”

• Drill To Scope: “My Web Queries.Public”

Result

The drill rule above will be used when retrieving correlated queries any time a user drills from a query in the Public folder (or any of its subfolders). When the rule is applied, it will tell NWQ to search within the Public folder and subfolders for any query containing a column of the same name as the drill-from column, but with an A$ at the beginning. If the drill-from column already has an A$ at the beginning, NWQ will ignore this rule. Any matching queries will show up in the Correlated Queries list when a user drills across. When the user runs one of the correlated queries, it will run the query with an added filter that states ([the column the user chose to drill from] = ‘[the value the user chose to drill from]’).


Creating Drill RulesTo create a drill rule:

1. Open the Noetix.Gateway.Service.exe.config file.

2. Do one of the following:

• Change the values for the elements provided in the examples in the file.

• Copy the elements that are provided in the file in the examples, paste it in the same file, and then customize the values for the elements.

For more information about the elements and how to set the drill rules, see Noetix.Gateway.Service.exe.config and Drill Rules respectively.

3. Save the file, and then close it.

After creating or editing a drill rule, it is recommended that you periodically back up these files on another server. If a problem occurs, you can restore all the files from a backup.

IMPORTANT: After creating or editing a drill rule, you must restart the Noetix WebQuery Gateway service for the drill rule to be effective.

Deleting Drill RulesTo delete the drill rules:

1. Open the Noetix.Gateway.Service.exe.config file.

2. Select the drill rules you want to delete, and delete them manually.

3. Save the file, and then close it.


Restoring Connections Between NQS and NQS Repository

If the connection between Noetix QueryServer (NQS) and the NQS repository is lost because the NQS repository is shut down, NQS will restore the connection after the NQS repository is restarted. It might take some time before the connection is restored. Therefore, you must try until the connection is restored.

NOTE: If the connection is lost between a client application and the NQS repository or physical database, then to restore the lost connection, you must log on to the client application again after the NQS repository or the physical database is restarted.

For this feature to work, ODBC connection pooling must be enabled for the Microsoft SQL Server ODBC driver in ODBC Data Source Administrator. The time for which the ODBC Driver Manager waits between attempts to restore a lost connection depends on the retry wait time set for the SQL Server ODBC driver. For example, if the connection retry wait time is set to 120 seconds, then the ODBC Driver Manager makes an attempt to reconnect to the NQS repository every 120 seconds until the connection is established successfully.

You can modify the settings for the connection pooling for the SQL Server ODBC driver using ODBC Data Source Administrator. To open ODBC Data Source Administrator, click Start > Control Panel > Administrative Tools > Data Source (ODBC). For more information about modifying the settings for the connection pooling, refer to the documentation of ODBC Data Source Administrator.

Chapter 8

Security

This chapter explains how Noetix Platform security is set up.


OverviewIn most businesses, access to data is granted to groups of individuals because of their department or job. For instance, the entire sales department may have access to some pieces of data, but only the sales managers can access other pieces of data. Generally, the number of individuals who need special access to data is limited.

PermissionsPermissions are the access rights you grant to users, roles, and organizations. These allow you to determine which permissions you want a user, role, or organization to have to an object.

You may grant permission ( ) or revoke permission ( ) to an object. Revoking a permission will deny access to the object even if the user inherits the permission from another role.

When you want to give users the ability to access a virtual table (VTable), you will need to either explicitly or implicitly grant them Select permission to the mapping and connection associated with the VTable.

The Select permission is typically the only permission that you will grant to users on your system. If you have users that also need to be able to develop new objects in Noetix QueryServer (NQS), you can grant them additional permissions.

NOTE: To move an object, you need to have the Alter permission on it. To copy an object, you need to have the Create permission on the new container you are copying the object into.

Chapter 8: Security 205

There are five different permissions that can be granted to determine how a user can use and modify a folder as shown in Table 8.1.

Table 8.1 Noetix Permissions

Permission Description

SelectAllows a user to “see” the objects. This is a read-only permission.

Drop

Allows a user to delete an object or any of its contents.NOTE: When a Noetix WebQuery (NWQ) folder is deleted, any folders or links to queries within the folder are deleted as well. When a link to an NWQ query is deleted, only the link is deleted; the query still exists in the owner’s Personal folder.

AlterAllows a user to change the attributes of an object, such as the name or description.

Create Allows a user to create objects within other objects.

Change Permissions Allows a user to adjust the permissions for an object.


Granting, Revoking, and InheritingYou can grant or revoke each permission, or allow users to inherit a permission from an organization or another role.

• Grant: Explicitly grants a permission to members of this role. When you “grant” a permission, you are directly or “explicitly” giving permission to perform an action on the object.

• Revoke: Explicitly disallows a permission to members of this role. Most of the time, administrators will grant permission to objects. Conversely, if want to make sure that a user or organization does not have access to an object, you can explicitly revoke permissions.

If Noetix QueryServer (NQS) finds a revoked permission while compiling the effective permissions of a user, this will override all other granted permissions from any source and the user will be denied access. Due to the severity of revoking permissions, Noetix recommends that administrators use this feature infrequently.

NOTE: Revoking a permission has the same overriding effect that was described for granting permissions.

• Inherit: Allows members of a role to be granted or revoked a permission from other roles or organizations. Basically, this leaves their assignment to that permission “as-is.”


Explicit, Implicit, and Effective PermissionsPermissions can be explicit or implicit:

• Explicit permissions: Granted directly to the user, role, or organization.

• Implicit permissions: Inherited from parent organizations, granted roles, and so on. A user has implicit permissions when an organization they belong to or any role granted to them or to an organization they belong to has been granted the permission.

• Effective permission: Sum of all the explicit and implicit permissions a user has been granted is called their “effective permission.” All explicit and implicit permissions are “rolled up” to determine the effective permissions that a user has, which then determines what they can and cannot access.

How NQS Determines Object PermissionsWhen determining whether a user has permission to access a virtual table (VTable), Noetix QueryServer (NQS) checks the following permissions in this order:

1. NQS first checks to see if the user has been explicitly granted the Select permission on the VTable.

2. If the Select permission has not been granted explicitly to the VTable, NQS checks the organization that the user belongs to and then the organization that this organization belongs, and so on, all the way up to the root organization.

3. Next, NQS will check the permissions on all roles that have been granted at any level in this hierarchy.


4. NQS checks the VTable, subfolder, folder, and tables root to see if the user has permission to the object.

Figure 8.1 Checking Permissions at Each Level

5. Finally, all permissions that are found during this search is “added up” and becomes the “effective permission” of that user.

NOTE: The effective permission of any object can be viewed in NQS Administrator by clicking the Show Effective button found in the Permissions tab of the object.

Permission ConflictsA user may end up being assigned more than one role, either explicitly or implicitly. When that happens, the granted and revoked permissions of each role are “totaled up” to determine the user’s “effective permissions.”

The basic rules to remember when the permissions conflict with each other:

• Revoked beats granted and inherited.

• Granted beats only inherited.

• Inherited always loses.


Roles

RolesA role is a set of permissions you can grant to a user. You can also grant roles directly to organizations or to other roles to make granting permissions easier to set up and maintain. You associate a role to a user by making an organization or a user a member of that role.

A role can be thought of as a job title, business function, or business area that one or more users share. Typical roles might include “Sales Manager,” “Administrative Assistant,” “Account Executive,” “Legal Analyst,” and “US Orders.”

For more information about creating and assigning roles, see Creating Roles.

Role TypesRole types are groups of roles, much like organizations are groups of user accounts. Role types are used to organize roles for easier maintenance. Role types are also hierarchical, with no limits to how many levels of role types you can create, as long as each has a unique name within its parent role type.

Each role can exist in only one role type. Creating a role type hierarchy is optional. You can place all of your roles into the Roles root role type if you want to do so.

Role types cannot be granted permissions the way roles can. Role types are different from organizations in this way. A role type is simply a container for the roles you create.

For more information about organizing roles, see Creating Role Types.


Creating RolesA role is a set of privileges you can grant to a user. You can also grant roles directly to organizations or to other roles to make assigning permissions easier to set up and maintain.

Roles can be easily confused with permissions. But unlike a single permission, a role can contain a number of permissions, plus default subfolders, servers, connections, and so on. roles can be set up corresponding to job functions, data sources, or other manageable units. For instance, you could create a role called “Inventory” that includes Select permissions to all of your Inventory virtual tables (VTables), to the servers and connections associated to those VTables, a default subfolder for the “Inventory” subfolder, and a maximum rows limitation appropriate for typical inventory reports. Then, you could grant this role to any user who needs access to the Inventory data through Noetix WebQuery (NWQ).

Create a role to:

• Group similar permissions to a number of objects so they can be quickly granted to users or organizations.

• Give users access to key components and features within NWQ.

• Group multiple roles into a “super role” and grant them all to specific users.

NOTE: On installation, Noetix QueryServer (NQS) gives you a number of default N$ roles that grant permissions to administrative tasks within NQS and NWQ. For more information, see Administrative Users and Roles in “Users and Organizations.”

To create a role:

1. In NQS Administrator, right-click the Roles root item in the left-hand list (or the role type under which you want to create the role) and click New > Role.

2. The role’s property sheets will display.

3. On the General tab, enter the new role name and a description.

NOTE: You may also limit the number of rows members of this role can retrieve to prevent runaway queries (long-running queries that tax the database).


4. Click the Default Subfolders tab. Add any default subfolders you want to grant to all members of this role; this is what makes the contents of the subfolders display in NWQ (in the VTables folder).

5. On the Roles tab, you can specify any roles that should be a subset of this role. For instance, if creating an “Administrators” role, you may want to include many of the N$ system roles. For more information about system roles, see Roles.

6. The Members tab is where you will grant the role to organizations and/or users. Click the Add button to add members. Browse to and select the groups or individuals who should be granted this role, then click OK.

7. (Optional) Use the Notes tab to add notes about this role, if required. (You will need to click Save before adding a note.)

8. The Permissions tab is where you will specify the permission this role should have to specific objects. For more information about efficiently granting these permissions, see Permissions. Click Save when you are finished.

To grant a role:

• To grant a role, you need to make the user or organization a member of the role. You can do this on the Members tab of a role, or on the Roles tab for a user or organization.

Creating Role TypesYou may want to organize your roles for easier maintenance. You can create as many role types (collections of roles) as you’d like, although each role can belong to only one role type.

You can move existing roles into your new role type or create new roles within the role type. For more information, see Creating Roles.

Create a role type to:

• Organize your roles into a logical, hierarchical structure.

• Group similar roles to reduce the administrative tasks involved in managing them.


To create a role type:

1. In NQS Administrator, right-click the Roles root item in the left-hand list (or the role type under which you want to create the role) and click New > Role Type.

2. The role type’s property sheet will display.

3. On the General tab, type a name for the new role type and a description, if required. Click Save.

4. The new role type will now appear under the Roles node.

Granting Permission to a RoleGrant a permission to:

• Allow Select permission to a specific virtual table (VTable), or other object.

• Allow a user to access, change, delete, and perform other administrative functions on an object.

• Expressly revoke permission to access an object.

To grant permission to a role:

1. From the left-hand menu and the detail view, select the role to which you want to grant permissions. The property sheets for that role will display.

2. Click the Permissions tab.

At the top of this tab is the Security Tree, displaying all of the Noetix QueryServer (NQS) objects that you can grant this role permissions to. This tree displays the users, roles, servers, and VTables roots; you can expand these to see the hierarchy of objects below each one. When you select a node in the Security Tree, all of the objects that belong to this node appear in the permissions list below.

The permissions list contains the objects that belong to the node selected in the Security Tree. The permissions that have already been granted this role appear to the right under the Explicit column. A plus sign ( + ) in front of one of the letters signifies the permission has been granted. A minus sign ( - ) in front of a letter signifies the permission has been revoked.

Click the Show Effective button to add a column displaying the effective (implicit) permissions as well.


3. To change this permission, double-click the entry. A Permissions dialog box will display.

4. Clear the box next to the permission you are interested in if you want the grantee not to have explicit permission to the object. Click the box again to set the Granted check, which will explicitly grant the permission to the grantee. Click the box again to set the Revoked check. Click OK.

5. Click Save to save the changes.

You can use the drop-down box on the lower left-hand corner of the Permissions tab to quickly grant a typical set of permissions:

• Admin will grant all five permissions (+SDACP).

• Creator will grant the Select and Create permissions (+SC).

• User will grant simply the Select permission (+S).

Determining Role AssignmentsA user can be a member of a role if:

• A role is explicitly granted to the user.

• A role is explicitly granted to one of the user's parent organizations (membership is thus inherited).

• Another role is granted to one of the roles above.

The many ways in which a user can be a member of a role can lead to a complex web of membership grants. A carefully planned out security model will make things easy to manage but things can easily get complicated when system administrators leave the company, new ones are hired, multiple projects are going on, and so on. NQS Administrator allows you to quickly and efficiently determine the effective members of a role and the effective role memberships of a user. It helps you troubleshoot and unravel any complexities that might arise in your organization.


Example 1: There is a virtual table (VTable) in the system that maps to sensitive financial data. An auditor wants to know who has access to the data. Using NQS Administrator, the system administrator can determine all the users that can query the VTable.

Example 2: Bob calls the help desk to complain that he cannot access a VTable, but his coworker can. The system administrator looks up the roles that has access to the VTable. The system administrator then views the list of users that have been granted this role, and interestingly finds that the role is granted to Bob. The system administrator then looks at the role memberships for Bob and finds that another role is granted to Bob that revokes his access to the VTable. The system administrator removes the role that revokes the permission, and Bob is now able to access the VTable.

To view the effective members of a role:

1. In NQS Administrator, navigate to and select the required role under the Roles tree. The property sheet for the selected role is displayed in the lower-right pane of the NQS Administrator window.

2. Click the Members tab in the property sheet. The property sheet displays the organizations, users, and roles explicitly granted to the selected role.

3. Click Effective in the property sheet. The Effective Security Viewer dialog box is displayed.

4. The Effective Security Viewer dialog box displays three sections:

a. The Current Object field displays the currently selected role. You can click to quickly change the role without closing the Effective Security Viewer dialog box.

b. The Status area displays a log that details the processing done by the system to gather the user list.

c. The Effective Security area displays the IDs and full names of the users who are the effective members of the currently selected role. To view a user’s property page, either double-click on the user or select it and click Edit.


To view the effective role memberships of a role, organization or user:

1. In NQS Administrator, navigate to and select either of the following:

• A role under the Roles tree

• An organization or user under the Users tree

The property sheet for the selected role, organization or user is displayed in the lower-right pane of the NQS Administrator window.

2. Click the Roles tab in the property sheet. The property sheet displays the roles granted to the selected role, organization or user.

3. Click Effective in the property sheet. The Effective Security Viewer dialog box is displayed.

The Effective Security Viewer dialog box displays three sections:

a. The Current Object field displays the currently selected role, organization or

user. You can click to quickly change the user without closing the Effective Security Viewer dialog box.

b. The Status area displays a log that details the processing done by the system to gather the role list.

c. The Effective Security area displays the effective role grants of the role, organization or user. To view a role’s property page, either double-click on the role or select it and click Edit.

Granting Permission to an NWQ FolderFolder permissions allow you to determine who can access Noetix WebQuery (NWQ) Public folder or a subfolder within it. To grant folder permissions, you will grant folder permission to a role. Then any user that is assigned that role will be able to access that folder and the contents within it.

Folder permissions do not grant users the permissions to run queries—folder permissions only grant permission to view, publish, or delete queries. For more information about permissions to run a query, see Granting Permissions to a VTable in “VTables and Mappings.”


To grant a folder to a role:

1. In NWQ, confirm you are in Manage mode. (If you are not, click the switch to manage link.)


3. Click the Permission link.

4. On the Folder Permissions page, select a role type (group of roles) from the drop-down list at the top of the page. The roles available under this role type will display below.

5. Click the required roles to select them. To select more than one role, hold down the Ctrl key as you click each role.

6. Click the Grant button. This will add the roles to the Granted Role list.

7. Click a single role from the Granted Roles list. The permissions assigned to this role display in the Permission area.

8. For each granted role, grant, inherit, or revoke each permission level as required.

9. Click Apply.

You can change or remove the permissions assigned to a role using the Folder Permissions page as well. Select the required role from the Granted Roles list, and then make the required changes to the permissions or click Remove.

ProfilesA Noetix WebQuery (NWQ) profile is a set of permissions that determine the NWQ features a user can access. Profiles allow Noetix administrators greater flexibility in controlling which NWQ features are available to users. When certain NWQ features are not needed or recommended within your enterprise, you can simply revoke permission to those features.


NWQ profiles do not control users’ access to corporate data itself; profiles determine what users can do with the data once they log on to NWQ. Profiles are used in NWQ only and are not applied to third-party reporting tools that may be used to retrieve data from Noetix QueryServer (NQS).

Profiles are optional; you can allow all users to access the default NWQ features without any additional setup steps. If you choose to create custom profiles, you can either modify and grant a single profile to all users in your enterprise or create multiple custom profiles with different sets of permissions.

The NWQ Administrator allows you to create, copy, and delete profiles, and determine which features should be granted and revoked for each profile. For each profile in NWQ Administrator, there is a corresponding role or “profile role” in NQS Administrator. You grant the NWQ profiles to users, organizations, and/or roles by granting the corresponding profile role using NQS Administrator.

To create and grant profiles, you must be granted the N$WebQueryProfileAdmin role. For more information about roles, see Roles.

Types of ProfilesThere are three types of profiles:

• Default profile: The default profile, which is applied to any user not granted any other profile. In NWQ Administrator on the Profiles tab, click Edit to view or edit the default profile. You may also copy this profile by clicking the Copy button. The copy you create will be listed under Custom Profiles.

• Standard profiles: The standard profiles are profiles that are installed during Noetix WebQuery (NWQ) setup. These profiles can be used as-is, or can be customized further to meet your needs.

• Custom profiles: All NWQ profiles that have been created for your enterprise are listed under Custom Profiles. Any profile created during installation as examples or starting points will be listed as well. To view or modify a custom profile, click the name of the profile. To create a custom profile, click the New button from the starting Profile List page.


Steps for Setting Up ProfilesWhen initially setting up the Noetix Platform for your enterprise, you will perform the following tasks to review and customize, if required, the Noetix WebQuery (NWQ) features that end users in your enterprise will be able to access:

1. Review and edit (if required) the default profile using the NWQ Administrator.

2. Create custom profiles using the NWQ Administrator.

3. Grant the profiles to users, organizations, or roles using NQS Administrator.

Reviewing the Default ProfileUsers who do not have a Noetix WebQuery (NWQ) profile explicitly granted to them will automatically be granted the default profile. The default profile grants permission to the most common set of NWQ features. However, you can review these settings and modify them to meet the needs of your enterprise.

If you want to grant a single profile to all users in your enterprise, simply modify the default profile as required; this profile will be applied to all users (as long as no other profiles are granted).

If you modify the default profile and want to return to the original settings at any time, simply click Restore Defaults.

Any changes you make to the default profile will take effect the next time each user logs on to NWQ.

IMPORTANT: After you grant any profile role to a user, the default profile will no longer be granted.


Creating Custom ProfilesWith custom profiles you can create multiple profiles depending on the specific needs of your enterprise.

The easiest way to create and maintain custom profiles is to use the following steps:

1. Create a Grant All profile that grants access to all Noetix WebQuery (NWQ) features. (A standard profile has been created that will work for this purpose.)

2. Using NQS Administrator, grant the corresponding profile role to the Users root organization. All users under this organization will inherit the permissions in this profile role.

3. Create additional custom profiles to revoke permission to specific NWQ features as required. These profiles should have all features marked as “Inherited” except those that you explicitly want to Revoke. (A number of standard profiles have been created for this purpose; you may use these or create your own.)

4. Grant these profile roles to users or organizations that should not have access to these features.

If your profiles also correspond directly to structures set up in Noetix QueryServer (NQS), such as roles or organizations, granting profiles will be easier to manage.

To create a profile:

1. On the Profile List tab, click the New button. This will display the Profile Properties page.

2. On the Profile Properties page, provide a unique name for this profile and a description if required. A profile is usually named for the set of features being granted (e.g., “Revoke Exporting to Excel”) or the group or job duties the profile is created for (e.g., “Sales Managers”). Adding a description of the profile will make it easier to manage your custom profiles as more and more are created.


3. Select whether each feature should be granted, inherited, or revoked. For more information about these settings, see Granting or Revoking Features.

NOTE: To quickly mark all features as grant, revoke, or inherit, use the Select All buttons at the top of each column.

4. Click the Save button.

After creating a profile in the NWQ Administrator, a new profile role (with the same name and description) will be created in NQS Administrator under Roles > NWQ Profiles.

NOTE: When upgrading from one version of NWQ to another, new features may be added. These new features will by default be marked as “Inherited” in any of your custom profiles. You may need to review and modify your custom profiles after upgrading to ensure users have access to any new features.

Granting or Revoking FeaturesThe Profile Properties page allows you to determine which Noetix WebQuery (NWQ) features are granted or revoked in a profile. Each NWQ feature that can have permissions granted or revoked are listed on this page along with a description of the feature and any dependencies. You can grant, inherit, or revoke each feature.

• When you grant permission to a feature, you are explicitly giving permission to view and use that feature.

• When you revoke permission to a feature, you are explicitly disallowing access to a feature. At the top of the page, you can specify whether these revoked features should be hidden (invisible) or disabled (grayed-out).

• When you inherit permission to a feature, you are not explicitly granting or revoking permission. Whether a user can use that feature will be determined by other profiles he or she has been granted. For example, if a user is granted permission to the “Query: Customize” feature in one profile and the feature is marked as “inherit” in another, the user will be able to use that feature.


Some NWQ features are dependent on other features being granted. For example, to be granted the “Query: Customize” feature, the “General: Personal Folder” feature must not be revoked (since without a Personal folder, a user would have nowhere to save a custom query). These dependencies are shown when checking or un-checking certain options. Error messages will tell you when you have chosen combinations of features that will not work.

When editing the default profile, only the “Grant” and “Revoke” options are available, since the default profile is only applied when a user is not granted any other profiles (and thus has no other profiles from which to inherit a feature's settings).

NOTE: Granting a user a profile with features like “Query: Execute” or “Query: Customize” does not give them permissions to the underlying data itself. Permission to the data must be granted/revoked separately, using NQS Administrator.Likewise, granting a user a profile with features like “Public Folder” does not automatically give them permissions to subfolders within the Public folder. Permissions to Public folders must be set in NWQ using the Folder Permissions page.

Any changes you make to the default profile will take effect the next time each user logs on to NWQ.

Copying ProfilesTo create a new profile based on an existing one, on the Profile List tab, check the box in front of the existing profile and click the Copy button.

When copying a profile, you may choose whether to copy over all assignments (members of the original profile role) as well.

• Copying assignments means that all users granted the original profile will also be granted to the new profile you are creating. This is an easy way to create a new profile without having to manually grant it to the same users.

For example, say you have a profile named “Customer Support” that you not only granted to the Support organization but to all individuals who work directly with customers as well. You would like to revoke a feature from those individuals not in the Support organization. You could do this in the following way:

1. In NWQ Administrator, copy the existing profile with assignments.


2. Name the new copy “Work with Customers.”

3. Revoke those few features.

4. In NQS Administrator, remove the Support organization from the profile role's assignments.

• Not copying assignments means that your new profile will have no users assigned to it (until you set them up in NQS Administrator). This is an easy way to copy only the feature settings of an existing profile.

For example, say you have a “Sales” profile and need to create a new profile for Sales Managers, who should have all the features granted to Sales plus a few more. You could do this in the following way:

1. In NWQ Administrator, copy the existing profile without assignments.

2. Name the new profile copy “Sales Managers.”

3. Grant any additional features you want the managers to have.

4. Using NQS Administrator, grant the new profile role to the sales managers.

Granting ProfilesAfter creating your custom profiles, you can grant the corresponding profile role to users using NQS Administrator.

Noetix WebQuery (NWQ) profiles can be granted to:

• An individual user

• An organization (grouping of users)

• A role, which is then granted to the appropriate users or organizations

This flexibility allows you to grant profiles in various configurations to complement your security and setup in Noetix QueryServer (NQS). An understanding of how NQS was set up within your enterprise may help you grant and maintain these profiles more efficiently.


To avoid profile conflicts, you may want to grant your profiles to organizations. If you grant profiles to roles instead, conflicts will be more likely, since each user can be granted many different roles.

NOTE: Granting a user a profile role with features like “Query: Execute” or “Query: Customize” does not give them permissions to the underlying data itself. Permission to the data must be granted/revoked separately, using NQS Administrator.Granting a user a profile role with features like “Public Folder” does not automatically give them permissions to subfolders within the Public folder. Permissions to Public folders must be set in NWQ using the Folder Permissions page.

If while creating and granting profiles and profile roles, you have both NWQ Administrator and NQS Administrator open at the same time, you will need to “refresh” NQS Administrator to see recent changes made in NWQ Administrator. For example, if you create a new profile in NWQ Administrator, you will not see the corresponding profile role in NQS Administrator until you refresh the application.

To refresh NQS Administrator, on the View menu, click Refresh or press F5 on your keyboard.

To grant a profile:

1. Navigate to Roles > NWQ Profiles, in NQS Administrator.

2. Select the profile role corresponding to the required NWQ profile. This profile role will have the same name and description as in NWQ Administrator.

3. Click the Members tab, and then click the Add button.

4. The Locate User, Role or Organization dialog appears. Select the user or organization that you want to grant this profile role, and then click OK.

5. The user or organization will now be listed on the Members tab. Click Save.


Resolving Profile ConflictsA Noetix WebQuery (NWQ) user may end up being granted more than one profile role, either explicitly or implicitly. When that happens, the granted and revoked features of each profile are “totaled up” to determine the user's effective permissions.

NOTE: The default profile is not part of this “totaling” unless a user has been granted no custom profiles. When a user has been granted one or more custom profiles, only those custom profiles are used to determine the user’s allowed feature set.

To total up these permissions, NWQ first checks which features have been revoked. If a feature is revoked in any profile, the user will not have access to it, even if another profile grants that feature. Thus “revoke” always “wins” against the other settings.

A feature will be granted if at least one of the profiles grants that feature and none of the profiles revoke it. Remember that “inherit” always defers to the features explicitly granted or revoked in other profiles.

In other words, when the feature permissions conflict with each other:

• Revoked beats Granted and Inherited.

• Granted beats only Inherited.

• Inherited always loses.

When revoking a feature in a profile, you can choose for the feature to be hidden (invisible) or simply disabled (grayed-out). These settings can also conflict when a user is granted multiple profiles. The Global Settings page lets you choose which option “wins” when more than one profile revokes a feature but in a different manner.

To set your global setting:

1. In NWQ Administrator, click the Global Settings link on the upper right-hand corner of the page.

2. Select either the Hidden or Disabled option.

3. Click OK.


Using Standard ProfilesIn addition to the default profile, a number of standard profiles are created when Noetix WebQuery (NWQ) is installed. These profiles can be granted to users as they are or simply used as starting points to create your own custom profiles.

To use these standard profiles, first, grant users the “Grant All” profile, then, if you need to revoke certain features, assign the profiles that revoke these features, such as “Revoke Customizations.” These profiles are meant to be used in conjunction with the “Grant All” profile, not on their own.

To use a standard profile simply as a starting point, copy the profile, make any required changes, and save it with a new name.

IMPORTANT: Once you grant a standard profile or custom profile to a user, the user is no longer a member of the default profile role. What this means is the user cannot inherit any permissions from the default profile; only permissions from explicitly granted profile roles will be applicable.

Deleting ProfilesWhen deleting a profile, the corresponding profile role in Noetix QueryServer (NQS) is deleted as well. Consequently, any member of this role will no longer be granted permissions to these features. After a profile is deleted, if a user has no other profile roles granted, the user will be granted the default profile.

If a user is logged on to Noetix WebQuery (NWQ) when a granted profile is deleted, the change will take effect the next time the user logs on to NWQ.

CAUTION: Always delete a profile using the NWQ Administrator; do not delete the corresponding role from NQS Administrator. Deleting the role directly will “orphan” the NWQ profile and cause issues.

Appendix

Legal Notices


Third-Party License TermsGNU LESSER GENERAL PUBLIC LICENSE

Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc.

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below.

0. Additional Definitions.

As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License.

"The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below.

An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library.

A "Combined Work" is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the "Linked Version".

The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version.

The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work.

1. Exception to Section 3 of the GNU GPL.

You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL.

http://fsf.org/

Appendix: Legal Notices 229

2. Conveying Modified Versions.

If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version:

a) Under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or

b) Under the GNU GPL, with none of the additional permissions of this License applicable to that copy.

3. Object Code Incorporating Material from Library Header Files.

The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following:

a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License.

b) Accompany the object code with a copy of the GNU GPL and this license document.

4. Combined Works.

You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following:

a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License.

b) Accompany the Combined Work with a copy of the GNU GPL and this license document.

c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document.


d) Do one of the following:

0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.

1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version.

e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.)

5. Combined Libraries.

You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following:

a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License.

b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.

Appendix: Legal Notices 231

6. Revised Versions of the GNU Lesser General Public License.

The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation.

If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library.

Index

The index provides a quick way to look up topics and keywords used in this guide.


AAdding, 128

administrator toolsadministering NQS, 25NQS, 7NQS Monitor, 28NQS Query, 32NQS Service Manager, 27NWQ, 36NWQ Administrator, 39

administrator wizards. See wizards, NQS

administrators, NQS, 142See also sysadmin account

Agent Job Wizard, 165

alerts, 161

Alter permission, 205

assigning costs, 71

assignments for NWQ profiles, 221–222

authentication, external, 135

automatic alerts, 165

Bbacking up and restoring NQS, 179

Backup Repository Wizard, 179

browse and manage modes in NWQ, 36

business value for NWQ folders, 129

Ccaching, 169

cache indexes, 173limitation, 178modes, 172scheduling a cache, 176the cache connection, 170using the cached mappings, 177virtual views, 171

categories for VTables

adding to VTables, 54adding to VViews, 56security, 144

Change Permissions permission, 205

columnsdrill-from, 196drill-to, 196equivalent, 199filter, 197in a mapping, 72in drill rules, 196–197, 199in mapping, 68, 72matc-on, 196security using mappings, 80–81

configuration files, 188–189See also drill rulesNoetix DeliveryManager.exe.config, 183Noetix DeliveryServer.exe.config, 184Noetix.Gateway.Service.exe.config, 189nwqopt.xml, 192web.config, 189

configuring Database Mail profile, 161–164

conflict of permissions, 208

connecting to physical databases or data sources, 88

connection types, NQSSee also connections, NQSdefault, 96lookup, 97pass through, 96prompt, 97

connections, 90creating, 99granting permission, 89, 94reference connection, 71requirements, 90See also connection types, NQS

cost of mappings, 68, 71, 75

Create permission, 205

creating a cache, 174

Index 235

Ddata drills, 194

See also drill rules

data sources, connecting to, 88

Database Mail profile, 161–164

database user, 90, 97, 141

default connection, 96, 98

default mappings, 64

default subfolders, 60, 63See also folders, NQS; folders, NWQgranting directly to user, 141granting permission, 63, 141granting to organizations, 139, 146granting to roles, 139, 146

drill rules, 195–197creating, 201deleting, 201drill-from columns, 196drill-from scope, 196drill-to columns (filter), 197drill-to columns (match-on), 196drill-to scope, 196dynamic, 195using variables, 197–198

driver configurationscreating, 93multiple, 94server pools, 94

Drop permission, 205

Eeffective permission, 207

encryptionof password, 97

error logs, 139, 158–160

explicit permissions, 207

Expression Editor, 54, 56, 71

external authentication, 135, 138, 140

Ffeature security, 107

folder security, 103

folders, NQSSee also default subfolders; subfolderscreating, 61displaying VTables and folders in NWQ, 110granting permission, 60

folders, NWQ, 127–131See also default subfoldersbusiness value, 129managing, 127–131

adding, 128editing, 129sorting, 129

permissions, 130, 204, 215Personal, 127Public, 127VTables, 128

Ggeneral connection. See default connection

granting permission, 206connections, 89, 94default subfolders, 61, 63mappings, 74, 76–77run a query, 59servers and server groups, 89, 94VTables, 59, 61

Hheterogeneous mapping server, 6, 67

adding a new server, 154additional, 155and heterogeneous mappings, 67changing the default, 154default, 75, 154load balancing, 155

heterogeneous mappings, 67costs, 75creating, 67, 74–76navigating, 69


permissions, 76–77properties, 69reference connection, 76

HMSadditional, 155

HMS. See heterogeneous mapping server

Iimplicit permissions, 207

importingtables, 50–52user accounts, 137–139views, 50–52

inheritpermissions, 104, 141, 146, 206

.iqy files, 189

Jjoining

complex VTables, 50VViews, 50

Llimiting rows returned by a query, 35, 61, 62, 141

list of values and mappings, 77

log files for errors, 139

logon security, 103

logonsdatabases, 90verifying credentials against database, 140

lookup connection, 97

lookups and mappings, 77

Mmanage mode in NWQ, 36

mapping NQS users to database users, 97

mappings, 66, 69See also heterogeneous mappings

1:1 or default, 64custom, 77–86

examples, 77–86reasons to create, 66route a query, 68

managingcopying, 70creating, 70–74

permissions, 68, 74properties, 66

columns, 72costs, 68viewing properties, 69

reference connections, 71

Microsoft Excelfile location, 189long-running queries in NWQ, 126Oracle E-Business Suite responsibilities, 126versions, 190

migrating queries in NWQ, 120–122

monitoring Noetix QueryServer service, 28

NN$ roles

N$AgentOperators, 144N$BackupOperators, 142, 143N$CategoryAdmin, 144N$QueryAnalyzers, 143N$SysAdmin, 142N$WebQueryAdmin, 37, 142, 144N$WebQueryProfileAdmin, 37, 39, 142,

144, 217

N$System objectsfolder, 143role, 142, 211server group, 143

New Heterogeneous Mapping Wizard. See wizards, NQS

Noetix agent tools, 161creating alerts, 165creating operators, 164scheduling new tasks, 165security, 144

Index 237

setting up Database Mail profile, 161–164

Noetix Gateway, 188

Noetix QueryServer. See NQS

Noetix.Gateway.Service.exe.config, 189

NoetixAnswers, 13, 127

NoetixViews, 13finding in NWQ, 127

NQS, 4architecture, 5backing up, 179components, 5restoring from backup, 180–181

NQS Administrator, 25–27accessing, 25–26navigating, 26–27property sheets, 26viewing NWQ Administrator changes, 223

NQS administrator toolsNQS Administrator, 25–27NQS Monitor, 28–30NQS Query, 32NQS Service Manager, 27–28

NQS Monitor, 28–30opening the tool, 29permissions, 143repository, 6, 179role, N$QueryAnalyzers, 143

NQS Query, 32opening the tool, 32using for troubleshooting, 32

NQS Restore Repository Wizard, 180

NWQ, 7administering, 36–38backing up and restoring, 179, 180–181displaying NQS VTables, 109helping users get started, 102logging on, 36–38prerequisite tasks, 102Public folder, administering, 144security, 216–225URL, 36

NWQ Administrator, 39logging on, 39managing query deliveries, 126URL, 39

NWQ featuresaccess dependencies, 221browse and manage modes, 36global settings, 224granting permission, 220hiding and disabling features, 224inheriting permission from other

profiles, 220revoking permission, 220

OODBC connect string, 95

operators, 164

Oracle E-Business Suite and Query in Excel, 126

organizations, NQS, 135creating, 139, 146–147rules and tips, 135, 146user accounts, grouping, 145–147user accounts, moving, 147

Ppass through connection, 96

password, 135changing for NQS administrators, 145encryption, 97external authentication, 135, 140modifying, 140

performance, 150–156aggregations in queries, 84–86calculations in queries, 81–82lookups, 77–79NWQ, 62

permission groupsadmin, 213creator, 213user, 213

permission types


effective, 207, 212explicit, 207implicit, 207

permissions, 204–208, 213Alter, 205and NWQ profiles, 221Change Permissions, 205conflicts, 208Create, 205Drop, 205granting, 204, 212–213granting to

a set of VTables, 60connections, 68heterogeneous mappings, 76–77mappings, 68, 74NQS folders, 60–61NWQ folders, 130, 204, 215roles, 141servers and server groups, 89, 94user, 141VTables, 52, 56, 59VViews, 56

implicit, 147, 207NQS Monitor, 143revoking, 204running a query, 59Select, 205tips for granting, 141types, 204verifying for a user, 147

Personal folder in NWQ, 127displaying VTables, 109“queries in NWQ shared by” subfolder, 123sharing queries in NWQ, 122–125

profiles, NWQ, 144, 216, 217and NQS permissions, 221assigning to users, 218, 222–223best practices, 219conflicts, 223, 224copying, 217, 221–222creating custom profiles, 217, 219–220default profile, 217, 218, 221deleting, 225

editing, 217granting or revoking feature permission, 220restoring default settings, 218standard profiles, 225

prompt connection, 97, 98

property sheets in NQS Administrator, 26

Public folder in NWQ, 127administering, 144creating folders, 144publishing queries in NWQ, 124–125security, 130, 144, 205, 215

publishing queries in NWQ, 124–125

Qqueries

displayingin NWQ and other query tools, 60

limiting rows returned, 61, 62, 141, 146mappings used, 68permissions to run, 59routing

to a data source, 68to a server pool, 89

testing, 32

queries in NWQbase tables, 108changing a query’s base tables, 118–120customizing, 111displaying, 108–125managing, 108–125migrating to another server, 120–122sharing, 122–125

giving a copy to a user, 123granting access to a user, 123publishing in the Public

folder, 124–125

Query Builder tool, 53, 55, 72

query deliveries managing in NWQ Administrator, 126

query flow in NQS, 17–19

query in Excel, 125–126, 189

Index 239

query security, 106

QueryServer, Noetix. See NQS

Rrebasing a query, 118–120

record source (SQL) for mappings, 69, 72

repositories, NQSbacking up and restoring, 179, 180–181NQS Monitor, 6, 145

revoking permissions, 204

role types, 209creating, 211N$System, 142NWQ profiles, 216

roles, administrativefor Noetix agent tools, 144to access N$System.Monitor folder, 143to administer the NWQ Public folder, 144to back up the NQS repository, 143to create NWQ profiles, 144to create VTable categories, 144

roles, NQS, 209, 210creating, 210–211determining role assignments, 213granting, 141, 211

to organizations, 211to users, 211

handling duplicates when importing, 139inheriting, 146members, 211N$BackupOperators, 142, 143N$QueryAnalyzers, 142, 143N$SysAdmin, 142, 143organizing, 211vs permissions, 210

roles, NWQN$WebQueryAdmin, 37, 142, 144N$WebQueryProfileAdmin, 39, 142, 217

routing queriesrouting queries, 68to a data source using mappings, 68to a server pool, 89

Sscaling Noetix Platform for better

performance, 150scaling heterogeneous mappings, 153scaling NQS, 151scaling the Noetix Cache Maintenance

Server, 155

scheduling tasks, 165

schema, 90

schema. See connections, NQS

security, 204–225authentication, 135feature, 107folder, 103granting permission, 212logon, 103password, 97, 144–145query, 106user accounts, 90verifying logon credentials, 96

Select permission, 205

server groups, 89, 91See also servers, NQS; server pools;

connectionscreating, 91, 94

server pools, 88, 94–95See also servers, NQS; connections; server

groups

Servers and Connections Wizard, 91

servers, NQSSee also connections; server pools; server

groupscreating, 91, 92granting permission, 89, 94organizing, 89, 91

setting up Database Mail profile, 161

sharing web queries in NWQ, 122–125

SQL Server Agent Mail, 161

SQL syntax for NQS queries, 60

subfolders


See also folders; default subfolderscreating, 62granting permission, 60, 62granting permissions, 141NWQ performance, 62

sysadmin account, 142See also administrators, NQSpassword, 142, 144permissions, 142using with

Noetix QueryServer service, 142NWQ, 37, 142query tools, 142

Ttime-outs, 185

Uuser accounts, 134, 140

administrative, 142, 145database user, 97, 141managing

configuring, 136creating, 134, 140–141duplicate accounts, 139importing, 136, 137–139modifying, 137organizing, 135, 145–147synchronizing, 137

multiple, 97NQS database user, 90, 96permissions

granting, 206, 207, 218revoking, 146, 206

security, 90assigning to roles, 141external authentication, 135password, 135

User Lookup Map, 97See also lookup connection

Users and Roles Wizard, 138–139

VVDimensions, 66

creating, 73example, 77–79, 84–86reasons to create, 66

VFilters, 67creating, 73example, 83–84reasons to create, 67

Virtual Dimensions. See VDimensions

Virtual Filters. See VFilters

Virtual Tables. See VTables

Virtual Views. See VViews

VTables, 48and multiple databases, 48and VViews, 48as reports, 111complex, 48, 50, 52–54

adding categories, 54adding SQL, 53creating, 52granting permission, 54joining, 50, 54mapping columns, 54

importing, 49–52joins in NWQ, 49, 50managing

joining, 48, 55–56limiting columns, 50modifying names, 52, 53moving to another subfolder, 62

path, 60permissions to query, 59querying in NWQ, 59, 108–110simple, 49

adding categories, 52creating, 50–52granting permission, 52heterogeneous mappings, 52joining, 50, 52modifying names, 52using to create complex VTables, 50

viewing mappings, 69

Index 241

VTables folder in NWQ, 60, 128best practices, 110displaying VTables, 110granting permission, 110

VViews, 48, 50adding categories, 56creating, 55–56granting permission, 56moving to another subfolder, 62paths to views, 60permissions to query, 59Virtual View Wizard, 55

Wwizards, NQS, 26

agent job, 165

backup repository, 179complex VTable, 53new heterogeneous mapping, 74requirements, 88restore repository, 180roles required, 143servers and connections, 91setup users and roles, 138–139VView, 55

XXML files, nwqopt.xml. See configuration files

ZZ$ columns, 53