Ad Hoc: Software Integration Guide

Logi Ad Hoc Reporting
Software Integration Guide
Version 9.6
Last Updated: August 2009
Page 2
Table of Contents
INTRODUCTION .................................................................................................. 3
CHAPTER 1 Branding the Application .................................................................. 4
Customizing Images and Colors ................................................................ 5
Hiding the Menu Bar .................................................................................. 7
Customizing the User Interface .................................................................. 8
Customizing Report Component Templates............................................. 10
CHAPTER 2 Branding the Database Administration Utility ................................. 11
Customizing Images and Icons ................................................................ 12
CHAPTER 3 Bypassing Application Authentication ............................................ 14
Bypassing the Login Screen..................................................................... 15
Creating a Custom Login Page ................................................................ 16
Enabling Direct Access to Reports ........................................................... 17
Establishing Seamless Integration ........................................................... 18
CHAPTER 4 Integrating Proprietary Authentication ............................................ 20
NT Authentication and Authorization ........................................................ 21
Configuring Database Authentication ....................................................... 26
Configuring Session Authentication ......................................................... 31
Configuring SecureKey Authentication ..................................................... 35
CHAPTER 5 Using Session Variables to Filter Data........................................... 38
CHAPTER 6 Customizing Error Handling ........................................................... 41
CONTACT US..................................................................................................... 42
Page 3
INTRODUCTION
The application's Software Integration Guide provides information about
integrating the application with existing web applications.
The following information is included in this guide:







Introduction to integration
Creating a customized “look and feel”
Integrating proprietary authentication
Bypassing application authentication
Using session variables for column-level security
Customizing error handling and culture settings
Contact information
Note:
This guide includes detailed information to integrate and customize the
application with existing applications and security schemas. Refer to the
Installation Guide for help installing the application and to the System
Administration Guide and Database Administration Guide for help
configuring the application.
Target Audience
This guide is intended for the system administrator and/or database
administrator. The successful integration of the application with existing web
applications requires knowledge of networking, web development and database
technologies. For additional technical documentation or support for this or any
other Logi Analytics product, please visit our web site at
http://www.logianalytics.com/support/.
Page 4
CHAPTER 1
Branding the Application
The appearance of the application can be customized by incorporating custom
images, font types and styles to give the user interface a “look and feel”
consistent with other internal company applications. Application styles are
controlled by the AdHoc.css cascading style sheet located in the
App_Themes/Original folder where the application is installed. Custom
application themes must reside in separate folders under the App_Themes
folder.
To create a new application theme:
1. Create a new folder in the App_Themes directory.
2. Copy the application style sheet from the App_Themes\Original directory
to the new folder.
3. Rename this directory to your desired theme name.
4. Open the AdHoc.css file with any cascading stylesheet editor (or a text
editor) and change styles as needed. Images in Images folder can also be
replaced by your desired images as long as they retain the same names.
All themes in App_Themes folder are available to be assigned to any User Group
in the application. If no attempt is made to assign a theme to a User Group, the
default theme, Green, will be assigned to any new User Group by default.
The application depends on the naming scheme of the classes present in the
AdHoc.css style sheet. Customize the application’s appearance by modifying the
implementation for each of these classes. The following example web.config
code points to a custom theme called Northwind:
<pages styleSheetTheme="Northwind" enableEventValidation="false">
<controls>
//
</controls>
<tagMapping>
//
</tagMapping
</pages>
Note:
Do not modify the application provided themes, because they will get replaced
with each upgrade.
Page 5
Customizing Images and Colors
The possibilities for customizing the “look and feel” are limitless. Customers can
change the color scheme, icons, logos and the positioning of various user
interface components. Branding the logo and color scheme is the simplest and
most common form of customization.
Figure 1.1: The three main areas of the user interface are easy to customize.
To create a customized application theme, copy one of the existing themes in the
App_Themes folder, uniquely name it and save it in the App_Themes folder and
modify the theme. Do not modify the application provided themes.
Colors for the Menu Bar, Submenu Bar, and Navigation Bar are controlled by the
AdHoc.css cascading style sheet (CSS) in each App_Themes subfolder. The
following CSS class groups control the appearance and style of these
components:



Menu Bar
Submenu Bar
Navigation Bar
#menu
#submenu
#navtrail
Page 6
Each CSS class group contains one or more individual classes with several
properties. Colors are controlled by a six-digit hexadecimal number or a named
color.
Figure 1.2: The background and padding-bottom properties are applied to the menu tags.
For example, the hexadecimal code for the Menu Bar background color is
#4A719C. Image editors such as Adobe Photoshop make it easy to choose
colors and find the corresponding hexadecimal code.
Complete the customization of the main user interface by adding your company's
logo and modifying the menu icons to match the background color. Image files
are located in the App_Themes subfolders where the application is installed. The
four image files customers will want to change are:

logo.gif

iconReport.gif

iconUserProfile.gif

iconConfiguration.gif
After creating new icon images and a company logo, overwrite the existing
images and refresh the browser. Consult the following image specification
guidelines to achieve the best visual results:
Image Name
Width
Height
Resolution
logo.gif
iconConfiguration.gif
iconUserProfile.gif
iconReport.gif
279px
37px
37px
37px
54px
33px
33px
33px
72px/in
72px/in
72px/in
72px/in
Figure 1.3: A sample branding for the NorthWind Traders Company.
Page 7
Hiding the Menu Bar
Some customers who integrate Ad Hoc inside of their own web application may
choose to hide the Menu Bar. Hiding the Menu Bar gives customers the ability to
provide a seamless user interface for end-users building reports within the
application.
Figure 1.4: The application Menu Bar.
To hide the Menu Bar: Click on Configuration/Application Settings to display the
application settings page. Uncheck the “Show application menu and submenu
bars” checkbox, save the change, and logout/login to see the changes. Refer to
the System Administration Guide, chapter 4's Application Settings section for
additional information and warnings related to changing this setting.
Note:
Users cannot switch databases when the Menu Bar is hidden. The database
available for reporting is the first database assigned to a user’s role when the role
was first defined. See the System Administration Guide for more details.
Page 8
Customizing the User Interface
Customers who use certain methods of authentication may find certain links on
the Menu Bar obsolete. For instance, when using a proprietary authentication
scheme or NT authentication, Profile and Logout links may need to be removed
from the screen.
The following HTML code creates the links contained within the Menu Bar:
<span id="functions">
<a id="menu_Help" href="/AdHocReportBuilder/Help.aspx"
target="help">Help</a>
<span class="separator">|</span>
<a id="menu_Logout"
href="/AdHocReportBuilder/Logout.aspx">Logout</a>
</span>
<div id="menu">
<img id="menu_SiteLogo" src="../Images/logo.gif" alt=""
align="Middle" border="0" />
<span id="links">
<a id="menu_Reports"
href="/AdHocReportBuilder/ahReport/ReportListFolderView.aspx?ParentFold
erID=0&amp;FolderType=1"><img class="menubutton" alt="Report Icon"
title="Reports" src="../Images/iconReport.gif" />Reports</a>
<a id="menu_UserProfile"
href="/AdHocReportBuilder/ahReport/UserProfile.aspx"><img
class="menubutton" alt="Profile Icon" title="Profile"
src="../Images/iconUserProfile.gif" />Profile</a>
<a id="menu_Configuration"
href="/AdHocReportBuilder/ahConfiguration/Configuration.aspx"><img
class="menubutton" alt="Configuration Icon" title="Configuration"
src="../Images/iconConfiguration.gif" />Configuration</a>
</span>
</div>
The id parameters highlighted in blue encapsulate a specific region of the HTML
code. The id parameters highlighted in red apply to a single HTML construct. Add
the following CSS classes to the customized AdHoc.css style sheet:
/* Hide the Profile link */
#menu span#links a#menu_UserProfile
{
display: none;
}
/* Hide the Logout link */
#functions a#menu_Logout
{
display: none;
}
Page 9
Figure 1.5: The Menu Bar for administrator users.
Users assigned the Admin role will see the Reports, Configuration and Help links.
The User Group and Database drop-down menus are available if more than one
user group or database is configured for reporting.
Figure 1.6: The Menu Bar for end-users.
End-users without administrative rights will see the Reports and Help links. The
Database drop-down menu is available if more than one database is configured
for reporting.
Page 10
Customizing Report Component Templates
The application allows for the customization of the reporting components
available to end users building reports with the Report Builder interface.
Modifying the XML component templates requires knowledge of the Logi Info
managed reporting tool. Elements can be added and removed from the
templates to modify their appearance in reports created within the application.
To customize a report component template:
1. Copy the template file to be edited from App_Data folder into the
ahCustom\DefinitionTemplate folder.
2. Make the changes and restart the application. XML can be cut and pasted
directly from Logi Studio.
As an example, a company name can be added to the header of every report
created within the application. After copying the HeaderInfo.xml template to the
ahCustom\DefinitionTemplate folder, modify the template as follows:
<Rows ID="Header" Width="100" WidthScale="%">
<Row ID="companyHeader">
<Column ID="colCompanyName" Width="100" WidthScale="%"
Class="pageTitle" >
<Label Caption="Northwind Traders, Inc." ID="CompanyName" />
</Column>
</Row>
<Row ID="rowHeader">
<Column ID="colReportTitle" Width="50" WidthScale="%"
Class="pageTitle" ahFeature="ShowTitle">
<Label Caption="" ID="ReportTitle" ahFeature="ReportTitle"/>
</Column>
<Column ID="colDateTime" Width="50" WidthScale="%"
Class="pageTitle" ahFeature="ShowDateTime">
<Label ID="lblDate" Caption="Date:" ahFeature="ShowDate" />
<Spaces Size="2" ahFeature="ShowDate" />
<Label ID="Date" Caption="@Function.DateTime~" Format="Long
Date" ahFeature="ShowDate"/>
<LineBreak ahFeature="ShowDate"/>
<Label ID="lblTime" Caption="Time:" ahFeature="ShowTime" />
<Spaces Size="1" ahFeature="ShowTime" />
<Label ID="Time" Caption="@Function.DateTime~" Format="Long
Time" ahFeature="ShowTime"/>
</Column>
</Row>
</Rows>
Page 11
CHAPTER 2
Branding the Database Administration Utility
System administrators can customize the Database Administration utility in two
steps. The first is to replace the program images with customized branded
company images and logos. The second step is to modify the default Product
Name value with the name of their product. Thus, the text Logi 9 Ad Hoc
Reporting is replaced by their product’s name.
Figure 2.1: Administrators can customize the areas highlighted in red.
To set the Product Name: In the application, click on Configuration/Application
Settings to display the application settings page. Edit the Product Name
information, save the change, and logout/login to see the changes. Refer to the
System Administration Guide, Chapter 4's Application Settings section for
additional information.
Page 12
Customizing Images and Icons
Administrators can customize the Database Administration utility further by
adding customized company logos. Image files are located in the ahImages
folder within the main application directory.
The three image files customers will want to change are:

ahAnimatedLogo.gif

ahSmallLogo.gif

ahWelcomeScreen.gif
Logi Analytics was formerly known as LogiXML
The ahAnimatedLogo.gif image is used by the progress indicator for the Schema
Wizard and during report generation. As the indicator progresses it cycles
through the frames contained in the image file. Customers must replace this
image with an animated GIF.
The ahSmallLogo.gif image is used on the Database Administration form, Activity
Log Settings form, Report Database Settings form, Database Wizards forms,
Publisher Wizard form and Synchronization Settings form.
The ahWelcomeScreen.gif image is used by the first screen of the Schema
Wizard and Publisher Wizard.
Page 13
Consult the following image specification guidelines to achieve the best visual
results:
Image Name
Width
Height
Resolution
ahAnimatedLogo.gif
ahSmallLogo.gif
ahWelcomeScreen.gif
35px
35px
299px
32px
32px
477px
72px/in
72px/in
72px/in
After constructing the images to the specifications noted above, simply replace
the default images with custom images. Make sure to use the same file names.
Figure 2.2: A sample branding for Northwind Reporting.
Page 14
CHAPTER 3
Bypassing Application Authentication
Customers with existing authentication schemas can bypass the application login
screen and bring users directly to their reports. If users are authenticated from a
company database, a customized login screen can be designed for the
application.
Some scenarios require a more simplified authentication scheme. Organizations
can create an anonymous user account for their entire user-base by passing the
login information using query string parameters. Users can also link directly to
reports without using the application interface.
Note:
Roles must always be configured within the application.
Page 15
Bypassing the Login Screen
Bypassing the login screen is useful when authentication is performed by the
operating system or a web application integrated with the application. In this case
Ad Hoc’s default login page (Default.aspx) can be bypassed by adding a custom
page in the root directory of Ad Hoc web, setting Ad Hoc’s required username
session variable, and redirecting to Ad Hoc’s “gateway”, Gateway.aspx.
Session("rdUsername") = <user_name>
Response.Redirect("Gateway.aspx")
See Chapter 4 for more details on this method.
The passed username must exist in Ad Hoc’s Users table in metadata database,
but a password is not required, since authentication is handled elsewhere.
Note:
User accounts must be created within the application to successfully use session
variables. Creating user accounts is not necessary when using NT
authentication.
Page 16
Creating a Custom Login Page
Many organizations want to replace the default application login screen with a
customized login screen. Although possible, it is recommended that the contents
of Default.aspx are not modified because the page is part of the standard
installation package and will be overwritten with the next upgrade. HTML code in
Default.aspx can be used as a sample to create your own page or use a form
template similar to the following HTML code:
<form name="form1" method="post" action="Gateway.aspx">
<h2>Login to Logi Ad Hoc Reporting</h2>
<p>Username: <input type="text" id="username"></p>
<p>Password: <input type="text" id="password"></p>
<input type="submit" id="submitInfo" value="Submit">
</form>
The portions of the code highlighted in red are required. The id parameters of the
text input types must be called username and password. The form must post the
login information to the Gateway.aspx page.
You must remember to replace the values of LogonPage and LogonFailPage
attributes of Security element in _Settings.lgx file if you use this method. The
LogonPage parameter specifies where users are taken after clicking the Logout
link. The LogonFailPage parameter specifies the web page users are directed to
if the login process is unsuccessful or the user session expires. The same web
page can be used for both parameters.
See Chapter 4 for more details on editing the Settings file.
Note:
The application's virtual directory is configured to load Default.aspx as the
default document. Change the default document to correspond with the custom
login page.
Page 17
Enabling Direct Access to Reports
The application prevents users from linking to reports directly, for security
purposes. A plug-in call is made at the time a report is requested, to ensure the
requesting user’s permissions to view the report. If it is required for users to link
to reports directly without using the application interface, turn off this plug-in. In
order to do this, open _Settings.lgx with a text editor and remark or remove the
following element:
<PluginCall PluginName="ahPlugin" PluginTypeName="ahPlugin.ahPlugin"
PluginMethod="CheckPermission" EngineEvent="LoadDefinition"
ID="CheckPermission"/>
Reports are stored in the _Definitions/_Reports folder within the main application
directory.
Replace the contents of rdPage.aspx with the following code:
‘--------------- rdPage.aspx -------------------------------------<%@ Page Language="vb" AutoEventWireup="false"
Codebehind="rdPage.aspx.vb" Inherits="rdWeb.rdPage" Trace="False"%>
<%
IF Session("rdUsername") = Nothing THEN
Session("rdUsername") = "Anonymous"
Else
'do nothing
END IF
%>
<%
Dim rb as new rdServer.ResponseBuilder
Call rb.BuildResponse()
%>
<head runat="server" visible=false/>
Replace Anonymous with the name of the global account created within the
application. The following external link example brings users to a report stored as
ahReport1.lgx on a server called webserver:
http://webserver/AdHocReportBuilder/rdPage.aspx?rdReport=ahReport1
&FirstTime=True
The value of the rdReport parameter is the targeted report. If the targeted report
has one or more parameters defined at runtime, set the &FirstTime parameter
equal to True.
Page 18
Establishing Seamless Integration
Creating a hook to the application from an existing web application makes the
application transparent to users building reports from the database. There are a
number of ways to accomplish seamless integration with existing web
applications, and there is no single scenario that is perfect for every organization.
Nevertheless, many organizations share some common requirements for
seamless integration.
The example scenario presented in this section accomplishes the following
integration goals:



Bypass the application login screen and use proprietary authentication.
Hide the Menu Bar to provide seamless integration.
Give users the ability to switch databases and configure the application
without the Menu Bar links.
Note:
This section focuses on the process of establishing seamless integration. See
the Branding the Application chapter for help hiding the application Menu Bar,
and the Integrating Proprietary Authentication chapter for help using existing
authentication schemas.
The integration scenario presented in this section requires that the rdUsername
session variable is set. Users must first navigate to Gateway.aspx (the page
listing all reports) before access is granted to other areas of the application such
as the Report Builder, Profile and Configuration.
Users assigned to the System Admin or adHocAdmin roles have administrative
access to the application. The calling web application must provide a link to the
Configuration area when hiding the Menu Bar. Use the following URL to redirect
users to the Configuration area:
http://yourserver/AdHocReportBuilder/ahConfiguration/Configuration.aspx
Hint:
If the above link redirects users to the login screen, it means that authentication
has failed. Ensure that users first visit Gateway.aspx before any other web page
within the application.
Page 19
If multiple databases are configured for use with the application, the calling web
application must provide a drop-down menu control to perform the database
switch. Each database connected to the application has a unique ID number
located in the _Settings.lgx file. The values for each menu item must correspond
with the ID attribute values for each Connection element.
For example, the following sample _Settings.lgx file has two connected source
databases:
<Connections>
<Connection Type="Application" ID="ahMetadata"
ConnectionString="Provider=Microsoft.Jet.OLEDB.4.0;Data
Source=C:\Program Files\lgxAdHocCopy\Database\ahData.mdb" />
<Connection ID="1" Label="NorthWind"
ConnectionString="Provider=SQLOLEDB.1;Persist Security Info=False;User
ID=sa;Initial Catalog=Northwind;Data Source=localhost"
Type="Application" />
<Connection ID="2" Label="AdventureWorks"
ConnectionString="Provider=SQLOLEDB;Persist Security Info=False;User
ID=sa;Initial Catalog=AdventureWorks;Data Source=lgxserver"
Type="Application" />
</Connections>
The following two lines of C# code populate an ASP.NET drop-down menu
control with the appropriate values:
// dbSwitch = DropDownList web control
dbSwitch.Items.Add(new ListItem("NorthWind", "1"));
dbSwitch.Items.Add(new ListItem("AdventureWorks", "2"));
Define an event handler that fires when the selected index is changed within the
control. Use one of the following links to switch the current database:
// Bring users to their reports
AdHocReportBuilder/Switch.aspx?Switch=DB&ID=<dbase_ID>&Go=Reports
// Bring users to the Configuration page
AdHocReportBuilder/Switch.aspx?Switch=DB&ID=<dbase_ID>&Go=Configuration
Replace <dbase_ID> with a numeric value that corresponds to a particular
source database.
Note:
A Connection element with a non-numeric ID attribute is not a valid source
database in Ad Hoc. Only use numeric values when targeting the Switch.aspx
web page.
Page 20
CHAPTER 4
Integrating Proprietary Authentication
The application is designed to support a role-based security schema. Each user
belongs to one user group and is required to have a username, password, and
one or more assigned roles. A user’s role defines the access rights to specific
objects within a database. Most organizations have already created users and
roles and wish to integrate the application with an existing security schema.
Usernames and passwords provide a means for authentication. Roles provide a
means for authorization. The application supports alternative means of
authentication. Administrators can use NT authentication, query a database to
authenticate their users, or use session variables to pass in information of a user
who has already been authenticated by other means. The application can also
use the Logi SecureKey feature to seamlessly integrate with an existing
application. The application can work with existing roles, provided those roles are
also configured within the application.
For the application to function properly for a particular user, three pieces of
information must be known: 1) the user via an authentication method, 2) the
role(s) via an authorization method and 3) the user’s group.
Notes:
1. Distinct user groups are not a requirement of the application. All users could
be members of the “Default Group”. User groups simply provide another
method to categorize users.
2. The application provides an API that allows customers to programmatically
synchronize the application metadata database with the security schema from
another database. The sample application and accompanying documentation
are located in the ahInterfaceSample folder.
3. User Names, Group Names, Passwords, and Role Names may contain any
uppercase or lowercase characters except for the following: / \ [ ] : . | = , + * ?
< >. Leading and trailing spaces should also be avoided.
Page 21
NT Authentication and Authorization
This section provides assistance for system administrators that want to use NT
authentication and authorization with the application. Following are the
configuration steps required:
1.
2.
3.
4.
Create and configure roles within the application.
Update _Settings.lgx to use NT authentication.
Disable anonymous access for the application virtual directory.
Set the ahUserGroupID session variable to the ID of a valid application
user group.
Configure roles within the application
The application supports users and groups on networks with or without a domain
name. Make a list of the NT user groups that require access to the application
and create a role for each group within the application.
With NT authentication, the application matches the NT user group name for the
user with a role name defined in the application to determine the user’s role.
Note:
To avoid confusion, “NT user groups” are equivalent to “Roles” in the application.
“Groups” in the application are independent of the “NT user groups”. The System
Administrator may still organize users within the application into groups similar to
the “NT user group” designations, but it is not required.
To create roles in the application:
1.
2.
3.
4.
5.
Login to the application as an administrator.
Click Configuration to enter the configuration page.
Click Roles to access the role configuration screen.
Click Add a New Role to begin creating a new role.
Type a name for the role and configure the access rights. The name of the
role must exactly match the name of the Windows NT user group.
6. Click Save to commit all the changes.
7. Repeat steps 4 through 6 for any additional Windows NT user group.
Page 22
To create an “administrator” role in the application:
1.
2.
3.
4.
5.
Login to the application as an administrator.
Click Configuration to enter the configuration page.
Click Roles to access the role configuration screen.
Click Add a New Role to begin creating a new role.
Type adHocAdmin as the role name. Assign Administration permissions
and all databases to the role.
6. Click Save to commit all the changes.
Notes:
1. Give users administrative privileges by creating a Windows NT user group
called adHocAdmin. Members of the NT adHocAdmin group have the same
access rights as users assigned to the System Admin role in the application.
2. The application always maintains a list of user groups, users and roles within
the application. If using NT authentication, it is not necessary to create user
accounts within the application. User accounts are automatically created
when a new user logs in for the first time.
3. The initial default username for the application is admin and the password is
password. Administrators should change the default password after installing
the application.
Figure 4.1: The domain Windows NT user groups adHocAdmin, Guests, HelpServicesGroup and
Users have access to the application.
Page 23
Update the _Settings.lgx file to use NT authentication
The application uses the _Settings.lgx file to obtain a variety of configuration
information, including security parameters.
The _Settings.lgx file is located in the _Definitions folder under the root folder
specified during installation (e.g., C:\Program Files\LogiXML Ad Hoc Report
Builder\_Definitions). To update the _Settings.lgx file for NT Authentication:
1. Make a backup of this file
2. Disable Read-only access to _Settings.lgx
a. Right click on the file
b. Click on Properties
c. Uncheck the Read-only check box
d. Click on OK
3. Open the file in a text editor (e.g., Notepad)
4. Replace the content of the <Security> element with the following code:
<Security NTAuthenticationDomain="<domain_name>" SecurityEnabled="True"
AuthenticationSource="AuthNT" AnonymousUserID="1"
LogonFailPage="Default.aspx" LogonPage="Default.aspx"
SchedulerUsername="Admin">
<Rights>
<Right Type="SQL" ID="Admin" Source="Select RoleID from Role where
RoleID=1"/>
<Right Type="SQL" ID="NonAdmin" Source="Select RoleID from Role where
RoleID&lt;&gt;1"/>
</Rights>
<UserRoles Type="NT" ID="UserRoles.NT"/>
</Security>
5. Modify the NTAuthenticationDomain attribute. Organizations running a
domain-based network must include the NTAuthenticationDomain
attribute to the Security element. Replace <domain_name> with the
name of the company’s domain (e.g., LogiAnalytics).
6. Save the file
Page 24
Disable anonymous access for the application virtual directory
A virtual directory for the application is created and configured during the initial
installation of the application. The installation program configures the virtual
directory for anonymous access to support the built-in security features.
Administrators must disable anonymous access to use NT authentication. To
disable anonymous access to the application:
1. Launch IIS, for Windows click on the Start button and either:
a. Click Settings/Control Panel/Administrative Tools/Internet
Information Services, or
b. Click Run/type “cmd” in the “Open:” text box/click OK and type
mmc %systemroot%\system32\inetsrv\iis.msc
2. Locate the virtual directory specified during installation of the application
(AdHocReportBuilder by default) under the Default Web Site group.
3. Right-click the directory and choose Properties.
4. Click the Directory Security tab
5. Click Edit to modify the Authentication and access control method.
6. Uncheck the Enable anonymous access checkbox
7. Click OK to dismiss the dialog
8. Click OK to save the changes
Figure 4.2: Uncheck the Enable anonymous access checkbox. The Integrated Windows
authentication checkbox is checked by default.
Page 25
Set the ahUserGroupID session variable
For the application to function properly, an application defined user group must
be determined for each user. With NT authentication, this must be passed to the
application as the ahUserGroupID session variable.
One technique to set this session variable is to code it into the Default.aspx file.
The Default.aspx file is found in the root folder specified during installation. To
set the ahUserGroupID through the Default.aspx file:
1. Make a backup of the Default.aspx file
2. Edit the Default.aspx file
3. Insert the following XML: <% Session("ahUserGroupID") = 1 %> just before the
<html> element to select the application’s Default Group
4. Save the file
There are other techniques available to set the ahUserGroupID session variable,
some of which are covered in Chapter 4. These include, but are not limited to,
passing the session variable from a parent application, including the parameter in
the URL, and setting the session variable from a login script.
Test NT authentication
After following the instructions outlined above, to test the NT authentication:
1. Launch the application
2. Do not enter user or password information on the login page
3. Click the Login button
The application should present the logged-in user with an interface that reflects
the permissions defined by the role associated with the NT user. The user should
be a member of the “Default Group” in the examples outlined above.
Notes:
1. On any error on login the user is redirected to the page specified in the
LogonFailPage attribute of the <Security> element. An aspx page called
LoginError.aspx has been included in the installation package which can be
set as the LogonFailPage.
2. For NT Authentication, the LogonFailPage attribute should not be set to
Default.aspx if Default.aspx has a Response.Redirect in it. In this case login
errors may cause an infinite loop. Using the provided LoginError.aspx page or
a custom designed page may avoid this. The LoginError.aspx page simply
displays the error message thrown by Gateway.aspx from a session variable
called "rdLogonFailMessage".
Page 26
Configuring Database Authentication
This section provides assistance for system administrators that want to
authenticate users from a database with the application. The following five steps
are required to configure the application for database authentication:
1.
2.
3.
4.
Create and configure the user groups and roles within the application.
Create an authentication database.
Create a connection in _Settings.lgx to the new authentication database.
Modify _Settings.lgx to retrieve user and role information from the new
authentication database.
5. Set the ahUserGroupID session variable to the ID of a valid application
user group.
Ad Hoc’s standard authentication is, in fact, Database Authentication and the
database used is Ad Hoc’s metadata database.
Create user groups and roles
Creating appropriate roles and permissions in the application is fundamental to
enforcement of the security scheme. The application is designed to provide rolebased security.
The basic steps to create a new role in the application are:
1.
2.
3.
4.
Login to the application with administrator rights
Click on the Roles tab
Click on the Add a New Role button
Provide the new role name and set the permissions, groups, and
databases for the new role
5. Click on Save button
6. Repeat the process until all of the roles have been defined. Refer to the
System Administration Guide or the previous section of this chapter for
additional help creating and configuring roles within the application.
Creating User Groups within the application is optional. All users may be
assigned to the Default Group. Administrators may create user groups to
organize and categorize users.
Page 27
The basic steps to create a new user group in the application are:
1.
2.
3.
4.
5.
6.
Login to the application with administrator rights
Click on the User Groups tab
Click on Add a New Group button
Provide the new group name
Click on the Save button
Repeat the process until all of the groups have been defined. The newly
defined user groups must be related to existing roles. Refer to the System
Administration Guide for additional help creating and configuring user
groups within the application.
Create an authentication database
The application can connect to any supported database to retrieve authentication
information. The application is compatible with Microsoft SQL Server, Oracle,
Sybase, MySQL, Access, Caché, Informix, DB2, PostgreSQL, and MSDE. There
are no restrictions in terms of how users and roles are stored in the database;
however, every user must have a role to successfully login to the application. The
following example uses a Microsoft Access database with the following three
tables:



Users – user profile information (username, password, etc.)
Roles – role information (role names)
UserRoles – user/role assignment information
Figure 4.3: The UserRole table assigns each user from the Users table a role from the Role
table.
The application requires Username, and one or more RoleID’s be returned from
the security database. These field names are required by the application.
Page 28
Create the connection to the new authentication database
The application uses the _Settings.lgx file to obtain a variety of configuration
information, including security parameters.
The _Settings.lgx file is located in the _Definitions folder under the root folder
specified during installation (e.g., C:\Program Files\LogiXML Ad Hoc Report
Builder\_Definitions).
To create a connection to the new authentication database:
1. Make a backup of this file
2. Disable Read-only access to _Settings.lgx
a. Right click on the file
b. Click on Properties
c. Uncheck the Read-only check box
d. Click on OK
3. Open the file in a text editor (eg. Notepad)
4. Insert the following text into the <Connections> element
<Connection Type="Application" ID="<database_name>"
ConnectionString="<connection_string>"/>
5. Replace <database_name> with a unique, one-word identifier for the
database
6. Replace <connection_string> with a valid connection string to the
database. Do not remove any additional Connection elements present.
Figure 4.4: The application will authenticate Users from the ahUserRoles database.
Page 29
Retrieve User and Role information
The next step involves building two SQL queries necessary to authenticate the
user; one to verify the user’s authentication information (usually by comparing
her username/password with the records in the database) and one to retrieve the
corresponding role. In the _Settings.lgx file, the Security element contains an
AuthenticationRule element and a UserRoles element.
To configure these two elements:
1. Locate the AuthenticationRule element
2. Modify the Source attribute of the AuthenticationRule element with a SQL
query that retrieves the username and password from the database.
Continuing with our example in Figure 4.4, the SQL query might be:
SELECT UserName, UserID FROM Users WHERE
UserName={*apos;*}@Request.username~{*apos;*} AND
Password={*apos;*}@Request.password~{*apos;*}
3. Change the ConnectionID attribute of the element to the identifier of your
database connection. In our example, it would be Users.
4. Locate the UserRoles element
5. Modify the Source attribute of the UserRoles element with a SQL query
that retrieves the current user’s role from the database Continuing with our
example in Figure 4.4, the SQL query might be:
SELECT RoleID FROM Role, UserRole, Users WHERE
Role.RoleID=UserRole.RoleID AND UserRole.UserID = Users.UserID AND
Users.UserName={*apos;*}@Functions.UserName~{*apos;*}
6. Change the ConnectionID attribute of the element to the identifier of your
database connection. In our example, it would be Users.
7. Save the file
In our example, the content of the Security element in the _Settings.lgx file
should appear similar to Figure 4.5.
Figure 4.5: The AuthenticationRule element retrieves the username and password, and the
UserRoles element retrieves the corresponding role.
Page 30
1. SQL queries will differ depending on the names of tables and columns within
the source database. The SQL code highlighted in red in the instructions
indicates a required syntax interpreted by the Logi framework.
2. The example above demonstrates SQL queries to retrieve information. The
AuthenticationRule element could also have been a stored procedure. The
UserRoles element could have been a stored procedure, a static query, or an
XML query.
3. The same Username and Role(s) must exists in Ad Hoc’s metadata
database for the application to function properly. However a password is not
needed if authentication is done from an external source.
Hint:
Consult the Logi Analytics Developer Network at
http://devnet.logianalytics.com to learn more about the Logi framework.
Test Database authentication
After following the instructions outlined above, to test the database
authentication:
1. Launch the application
2. Enter user and password information on the login page
3. Click the Login button
The application should present the logged-in user with an interface that reflects
the permissions defined by the role configured for the user.
Page 31
Configuring Session Authentication
Some organizations have existing web applications built with the .NET
Framework, complete with a login page and custom authentication routines. Ad
Hoc can be integrated with an existing web application, and organizations can
maintain their own security.
This section provides assistance for systems administrators that want to
authenticate users outside of Ad Hoc and somehow communicate with Ad Hoc
the user’s identity and bypass Ad Hoc’s login page. This is normally achieved by
use of session variables. The following three steps are required to configure the
application to rely on session variables for its authentication information:
1. Create and configure the user groups, roles and users within the
application
2. Modify Security method in _Settings.lgx to support session authentication
3. Set the required session variables
Create user groups, roles and users
Groups - Creating User Groups within the application is optional. All users may
be assigned to the Default Group. Administrators may create user groups to
organize and categorize users.
The basic steps to create a new user group in the application are:
1.
2.
3.
4.
5.
6.
Login to the application with administrator rights
Click on the User Groups tab
Click on Add a New Group button
Provide the new group name
Click on the Save button
Repeat the process until all of the groups have been defined. The newly
defined user groups must be related to existing roles. See the System
Administration Guide for additional help creating and configuring user
groups within the application.
Page 32
Roles - Creating appropriate roles and permissions in the application is
fundamental to enforcement of the security scheme. The application is designed
to provide role-based security.
The basic steps to create a new role in the application are:
1.
2.
3.
4.
Login to the application with administrator rights
Click on the Roles tab
Click on the Add a New Role button
Provide the new role name and set the permissions, groups, and
databases for the new role
5. Click on Save button
6. Repeat the process until all of the roles have been defined. See the
System Administration Guide or the previous section of this chapter for
additional help creating and configuring roles within the application.
Users - The Users defined in the application are used to verify the user
information passed into the application and determine the appropriate roles and
permissions.
The basic steps to create a new user in the application are:
1.
2.
3.
4.
5.
6.
7.
8.
Login to the application with administrator rights
Click on the Users tab
Click on Add a New User button
Provide the new user name
Select a group. By default the “Default Group” will be selected
Assign one or more roles to the user
Click on the Save button
Repeat the process until all of the users have been defined. See the
System Administration Guide or the previous section of this chapter for
additional help creating and configuring users within the application.
Page 33
Modify the _Settings.lgx file for Session authentication
The application uses the _Settings.lgx file to obtain a variety of configuration
information, including security parameters.
The _Settings.lgx file is located in the _Definitions folder under the root folder
specified during installation (e.g., C:\Program Files\LogiXML Ad Hoc Report
Builder\_Definitions). To configure the application to use Session authentication:
1. Make a backup of this file
2. Disable Read-only access to _Settings.lgx
a. Right click on the file
b. Click on Properties
c. Uncheck the Read-only check box
d. Click on OK
3. Open the file in a text editor (eg. Notepad)
4. Replace the <Security> element with the following text:
<Security SecurityEnabled='True' AuthenticationSource='AuthSession'
AnonymousUserID='1' LogonFailPage='Default.aspx' LogonPage='Default.aspx'>
<UserRoles Type='SQL' ID='UserRole' Source='SELECT RoleID FROM UserRole, Users
WHERE Users.UserName={*apos;*}@Functions.UserName~{*apos;*} AND UserRole.UserID
= Users.UserID'/>
</Security>
5. Save the file
Set the session variables
For the application to function properly, an application defined user name, their
role(s) and user group must be determined. Roles are determined by the query
above, and User Group is determined inside Ad Hoc, once the user is identified.
With session authentication, user’s identity is the only thing that needs to be
passed to the application as rdUsername session variable and the rest can be
left to the application. Please note that with Session Authentication, Ad Hoc is no
longer in the business of “authenticating” the user and it assumes that you have
done that prior to entering Ad Hoc.
Within the existing .NET web application, define a session variable called
rdUsername and set it to the current username. Define a session variable called
ahUserGroupID and set it to a valid application group ID. A value of “1” refers to
the “Default Group”. Redirect the current user to the Gateway.aspx page and the
user is taken to a list of their reports.
Notes:
1. On any error on login the user is redirected to the page specified in the
LogonFailPage attribute of the <Security> element. An aspx page called
Page 34
LoginError.aspx has been included in the installation package which can be
set as the LogonFailPage.
2. For Session Authentication, the LogonFailPage attribute should not be set to
Default.aspx if Default.aspx has a Response.Redirect in it. In this case login
errors may cause an infinite loop. Using the provided LoginError.aspx page or
a custom designed page may avoid this. The LoginError.aspx page simply
displays the error message thrown by Gateway.aspx from a session variable
called "rdLogonFailMessage".
Page 35
Configuring SecureKey Authentication
The Logi SecureKey authentication method is another method that can be used
to move the authentication code outside of Ad Hoc and into a “parent”
application. It provides improved integration for applications requiring secure
access to a Logi application. It supports the "single sign-on" model while
enhancing security because user credentials do not need to be exposed in a
query string or otherwise passed to Ad Hoc in order to authenticate the user.
In this method, like with Session authentication, users are authenticated in a
parent application. When the parent application gets a request for services from
the Logi Ad Hoc application, a “key” is generated within a background service
and exchanged between the two applications. Once established, the “key’ is valid
for the life of the session.
This section provides assistance for systems administrators who want to
authenticate users with the Logi SecureKey methodology. There are basically
two steps required to configure the application to authenticate via SecureKey:
1. Configure the application’s _Settings.lgx file for SecureKey authentication
2. Code the SecureKey processing in the parent application
Configure the _Settings.lgx file
To configure the application to use SecureKey authentication:
1. Make a backup of this file
2. Disable Read-only access to _Settings.lgx
a. Right click on the file
b. Click on Properties
c. Uncheck the Read-only check box
d. Click on OK
3. Open the file in a text editor (eg. Notepad)
4. Locate the <Security> element
a. Change the “AuthenticationSource” attribute value to “SecureKey”
b. Add the “CacheRights” attribute to the <Security> element and set
the value to “Session”
c. Add the “AuthenticationClientAddresses” attribute to the <Security>
element and set the value to the IP address of the parent
application’s server. This value can be determined by "pinging" the
application server from the web server hosting your Ad Hoc
application. If one computer serves both purposes and Ad Hoc is
Page 36
being called using localhost in the URL, enter 127.0.0.1 for this
value. Multiple IP addresses must be separated by commas.
d. Remove the <AuthenticationRule> element
5. Save the file
When these edits are complete, the _Settings.lgx file <Security> element should
appear as follows:
<Security SecurityEnabled="True" AuthenticationSource="SecureKey"
CacheRights="Session" AuthenticationClientAddresses="10.10.10.1" …>
…
</Security>
Note:
Editing of the _Settings.lgx file may also be accomplished using Logi Web
Studio. See the Web Studio section in Chapter 12 of the System Administration
Guide for additional details.
The examples given on our web site demonstrate how to configure the
_Settings.lgx file using Web Studio. The examples can be found at
http://devnet.logianalytics.com and click on the Using Logi SecureKey
Authentication link.
Configure the Parent Application
The parent application is responsible for authenticating the user, establishing the
link to Ad Hoc, and controlling the request redirects. The authentication process
should produce a valid username that exists in Ad Hoc.
When the user first requests a report or web page from the Ad Hoc, the parent
application issues a request to the Ad Hoc's AuthenticationService using this
format:
http://myServer/myAdHoc/rdTemplate/rdGetSecureKey.aspx?Username=bob
&ClientBrowserAddress=10.10.10.1
The AuthenticationService returns a secure key to the parent application, which
then redirects the user's request back to Ad Hoc’s URL, passing the secure key
as REQUEST or POST parameter. For example,
http://myServer/myAdHoc/Gateway.aspx?rdSecureKey=ABC123456789
Ad Hoc then verifies the incoming key to make sure that the request has been
initiated by a valid client and lets the user in.
For additional details and a coding example, visit
http://devnet.logianalytics.com/rdPage.aspx?rdReport=Article&dnDocID=1126
Page 37
and click the Configuring a Parent Application link.
Page 38
CHAPTER 5
Using Session Variables to Filter Data
The application is designed to obtain more than just authentication information
from existing applications. Session variables give developers the ability to filter
data at the row-level from the source database. Application Service Providers
find it useful to maintain one copy of the application, and use session variables to
filter data for each client, defined as a separate User Group.
Note:
There is no limit to the number of session variables that can be set or used within
the application.
Hint:
The application simplifies setting session variables by providing the Session
Parameters configuration page. Remember to log out and log back in after
setting new session parameters. See the System Administration Guide for
more details.
If session variables have to be set according to a process that is part of an
application other than Ad Hoc, they need to somehow be passed to Ad Hoc by
use of a custom .jsp file that is added to Ad Hoc’s web and is called before
Gateway.aspx.
For example, pass the ClientID variable in a URL and establish the session
variable within the application. The following example sets the ClientID session
variable from the login page:
http://yourserver/AdHocReportBuilder/Default.aspx?ClientID=15
' ------------- Default.aspx ---------------------------------------<% Response.Expires = -2000 %>
<% Session("ClientID") = Request("ClientID").ToString %>
<% Response.Redirect("Gateway.aspx?username=admin&password=password")
%>
Reference session variables defined in the application with the following syntax:
@Session.<variable_name>~
Replace <variable_name> with the name of the session variable defined earlier.
For example, if the value of ClientID is 15, then @Session.ClientID~ returns 15.
Note:
All variables in the application are case-sensitive. The @Session token must
Page 39
exactly match the name of the variable set and it must be terminated with a tilde
(~).
The application provides fixed parameters for administrators to apply row-level
data filtering on objects in the data source. For example, an Application Service
Provider would want to create a different result set for each client logged in. In
Figure 5.1 below, the CstmrID and StrDt session variables are defined within the
application. The Orders table is filtered by the values of the CstmrID and StrDt
session variables.
Figure 5.1: Assigning a fixed parameter to the CustomerID and OrderDate columns using
session variables.
Hint:
Session variables can also be used within report titles, column headers and
runtime parameters.
The following internal session variables are always set and are available for use:









ahUserGroupID – numeric ID of the current user’s group
ahUserGroupName – name of the current user’s group
ahUserName – the current user’s username
ahUserID – the current user’s numeric ID
ahSessionID – a unique identifier assigned to each session
ahShowMenu – a flag that determines if the Menu Bar is visible
ahSelectedDatabase – numeric ID of the currently selected database
ahSessionStartTime – the current session’s start time
ahUserRolesString – a comma-separated list of the current user’s role
IDs
Page 40
System administrators reference internal session variables the same way custom
session variables are referenced. For example, to filter a data object based on
the current user’s group ID, use the value @Session.ahUserGroupID~.
Page 41
CHAPTER 6
Customizing Error Handling
Customizing the error handling process gives administrators the ability to log
errors and redirect end-users to helpful troubleshooting pages. Since the
application is designed for deployment on company web servers with multiple
users in mind, it is helpful to redirect users to a web page containing contact
information and/or troubleshooting tips. Logging any errors encountered by users
is also helpful when assistance is needed from customer support. Enable error
logging to create individual HTML logs in a designated folder.
The application uses _Settings.lgx to obtain configuration information relating to
error handling. The _Settings.lgx file is located in the _Definitions folder. Disable
Read-only access to _Settings.lgx and open the file in any text editor to make
changes.
To redirect users to a custom error page and enable error logging:
1. Add the rdDebuggerStyle attribute to the General element and set it equal
to Redirect.
2. Add the RedirectErrorUrl attribute and set it to the URL where the custom
error page is located.
3. Add the LogErrors attribute and set it equal to True.
<General DataCacheLocation="@Function.AppPhysicalPath~\rdDataCache"
rdDebuggerStyle="Redirect" RedirectErrorUrl="http://YourCustomPage"
LogErrors="True"/>
Note:
Errors are logged in HTML format and saved to the rdErrorLog folder located in
the main program folder for the application.
Page 42
CONTACT US
For more information about other Logi Analytics products or assistance beyond
this user manual, please contact Logi Analytics in the following ways:
Corporate Headquarters
Phone:
1-888-564-4965
(703) 752-9700
Fax:
(703) 995-4811
Email:
[email protected]
Address:
7900 Westpark Drive, Suite A200
McLean, VA 22102
Web Site:
www.logianalytics.com
Sales Department
Phone:
1-888-564-4965
(703) 752-9700
Email:
[email protected]
Customer Support
Phone:
1-888-564-4965
(703) 752-9700
Link:
[email protected]