Xtraction v15.

1
Installation Guide

January 2015

Copyright 2015 Xtraction Technologies

Xtraction Installation Guide

January 2015

Copyright Notice
This documentation is proprietary information belonging to Xtraction Technologies and is protected
by the copyright laws of Australia and international treaties. This material may not be copied,
transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written
consent of Xtraction Technologies.
This documentation and related computer software programs are provided to users for
informational purposes only and are subject to change or withdrawal by Xtraction Technologies at
any time and without prior notice. The use of this documentation and any product referred to in this
documentation is governed by the applicable software licence agreement. Licensed users may print
a reasonable number of copies of this documentation for their own internal use, provided that
Xtraction Technologies copyright notices and legends are affixed to each copy. Only authorised
employees, consultants and agents of the user who are bound by the confidentiality provisions of
the licence for the software are permitted to have access to such copies.
The creator of this documentation is Xtraction Technologies. To the extent permitted by applicable
law, Xtraction Technologies provides this documentation as is without warranty of any kind;
including (without limitation) any implied warranties of merchantability, fitness for a particular
purpose, or non-infringement. In no event will Xtraction Technologies be liable to the end user or
any third party for any loss or damage, direct or indirect, from the use of this documentation,
including (without limitation) lost profits, business interruption, goodwill, or lost data, even if
Xtraction Technologies is expressly advised of such loss or damage.
All trademarks, trade names, service marks and logos referenced herein belong to their respective
owners.

Page 2 of 35

Xtraction Installation Guide

January 2015

CONTENTS
Overview ................................................................................................................................................. 5
System Requirements ......................................................................................................................... 5
Xtraction Server .............................................................................................................................. 5
Web Server (IIS) Features on Windows 2008 or above .................................................................. 6
Xtraction Database.......................................................................................................................... 6
Xtraction Clients .............................................................................................................................. 6
Installation ...................................................................................................................................... 6
Security Requirements ........................................................................................................................ 6
MS SQL Considerations ................................................................................................................... 6
Pre-Installation Steps .............................................................................................................................. 8
Database/Database User Creation ..................................................................................................... 8
Xtraction Database Setup ................................................................................................................... 8
Installation Instructions .......................................................................................................................... 9
Installing Xtraction .............................................................................................................................. 9
Configuring Xtraction ........................................................................................................................ 12
Settings Editor ................................................................................................................................... 14
Xtraction Database Settings .......................................................................................................... 14
Time Zone Settings ........................................................................................................................ 15
Other Settings ............................................................................................................................... 15
Authentication Settings ................................................................................................................ 15
Email Settings ................................................................................................................................ 17
Alert Settings ................................................................................................................................. 18
Xtraction Dates.............................................................................................................................. 19
Excel Dates .................................................................................................................................... 20
Data Model Settings.......................................................................................................................... 21
Connection Strings ........................................................................................................................ 21
Schema or Table Owner ................................................................................................................ 22
Target Application URLs ................................................................................................................ 22
Post Installation Steps ........................................................................................................................... 24
Confirm IIS Settings ........................................................................................................................... 24
Windows 2003 .............................................................................................................................. 24
Page 3 of 35

Xtraction Installation Guide

January 2015

Windows 2008 or above ............................................................................................................... 24

Integrated Security Connecting to Xtraction Database .................................................................... 24
Windows Server 2003 ................................................................................................................... 24
Windows Server 2008 or above .................................................................................................... 25
Configure Xtraction Task Manager ................................................................................................... 25
Configure Xtraction Alerts................................................................................................................. 25
iPad Client Access.............................................................................................................................. 26
General Settings ............................................................................................................................ 26
FIPS Compliance ................................................................................................................................ 26
Running the Application........................................................................................................................ 28
Initial Administrative Tasks ................................................................................................................... 29
Change Admin Password .................................................................................................................. 29
Create Users ...................................................................................................................................... 29
Create Filters ..................................................................................................................................... 29
Create Public Folders ........................................................................................................................ 29
Appendix A: Pre-Installation Checklist .................................................................................................. 30
Appendix B: Active Directory Integration ............................................................................................. 31
Settings.............................................................................................................................................. 31
xtractionAuth ................................................................................................................................ 31
directoryLocations ........................................................................................................................ 32
groupMap...................................................................................................................................... 32
Sample............................................................................................................................................... 33
Examples ........................................................................................................................................... 33
Directory ....................................................................................................................................... 33
Group Mapping ............................................................................................................................. 34

Page 4 of 35

Xtraction Installation Guide

January 2015

Overview
Xtraction is a status reporting tool designed to visualize and present data from within your
applications databases, in easily accessible and rich visual form. The main goals of Xtraction are to:

Enable easier access to more concise data for staff and management
Remove the dependence of specialized reporting staff and tools
Provide a visually rich interface and interactive end-user experience
Increase service management capabilities with increased access to data and reduced time-to-decision

Output can be produced in many forms, from an interactive real time dashboard to information
exported in various formats and pre-defined templates. Dashboards and status reports can be setup
for one or more of your databases and can be displayed within a single view.

System Requirements
Xtraction architecture is very simple and demand for hardware and software minimal. Installed on a
Windows server (2003 or greater), the application requires little more resources than what the
operating system requires. Xtraction can connect to one or more target application databases and
present the information back to the web browser.

Connected application
databases are referred to as
Data Sources.

Xtraction Server
The server housing the Xtraction application.

The Xtraction Windows server

provides access via a web
browser

Recommended hardware:

RAM: 2GB
Hard Drive: Xtraction has a very small footprint (150MB). 20GB-32GB drive size should be ample.
CPU: There is not a high demand on the CPUs of the Xtraction server. Fortunately, with a virtual
machine, you should be able to allocate more or less resources to the virtual machine based on the
performance you observe.

Required software:

Windows Server (2003, 2003 R2, 2008, 2008 R2, 2012, 2012 R2)
Microsoft .Net Framework (4.0, 4.5)
IIS
Oracle Client (8.1.7 or greater) if Xtraction is reporting against Oracle databases (64bit Oracle Client if
running on Windows x64)

Page 5 of 35

Xtraction Installation Guide

January 2015

Web Server (IIS) Features on Windows 2008 or above

The following Web Server (IIS) role features are required on Windows Server 2008 or above:

Common HTTP Features

o Static Content
o Default Document
o HTTP Errors
Application Development
o ASP.NET
o .NET Extensibility
o ISAPI Extensions
o ISAPI Filters
Health and Diagnostics
o HTTP Logging
Security
o Windows Authentication (if using AD)
Management Tools
o IIS Management Console

Xtraction Database
Server housing Xtraction SQL database

Can be on same, or different, server as Xtraction

Microsoft SQL Server (2000, 2005, 2008, 2012)

Xtraction Clients
Client machines accessing Xtraction via web browser

Web browser (Internet Explorer 6, 7, 8, 9, 10, 11)

Adobe Flash Player (10.2, 11, 12, 13, 14)

Installation
The install process needs to run using an Administrator privilege account that has administrative
rights on the Xtraction server. This access is only required for installation.

Security Requirements
During installation, you will specify connection details for accessing both the Xtraction database as
well as the target database (the database being reported on). For accessing the target database, a
user with read-only permissions is sufficient.

MS SQL Considerations

Xtraction needs access to two databases

o Its own database - Xtraction
o The application database that Xtraction will report against
Access to these databases is via user account(s) and can be either defined solely in the databases or
ADS/Windows (MSSQL)
It is easiest to use database-only accounts
Page 6 of 35

Xtraction Installation Guide

January 2015

If the Xtraction database and the application database are on the same server, a single SQL user
account can be used to access both databases
If ADS or Windows accounts are required for access to both databases, the same account must be
used for both

Page 7 of 35

Xtraction Installation Guide

January 2015

Pre-Installation Steps
Use the checklist found in Appendix A to document the information needed for installation.

Database/Database User Creation

1.
2.

3.

4.

Print the checklist table below to allow all environment details to be tracked.
Manually create an account, or ascertain if a suitable account already exists, with read-only
permissions to the target database. The user name can be any valid name; however, for consistency,
it is recommended to name it Xtraction. Log this user in the checklist. If this account uses Windows
authentication, be sure to include the domain name (e.g., MYDOMAIN\myuser)
a. For MSSQL, it should be sufficient to grant db_data_reader access
Manually create the Xtraction database on an MSSQL server to store the Xtraction data. The
database name can be any valid name; however, for consistency, it is recommended to name it
Xtraction. Log the database name in the checklist.
Manually create a user to allow Xtraction to connect to the Xtraction database, with read and write
permissions. The user name can be any valid name; however, for consistency, it is recommended to
name it Xtraction. Log this user name in the checklist. If the account uses Windows authentication,
be sure to also include the domain name (MYDOMAIN\myuser).
a. For MSSQL, it should be sufficient to grant db_data_reader and db_data_writer access

NOTE: If the accounts in step 2 and 4 both use Windows authentication, they MUST be the same
account.

Xtraction Database Setup

1.
2.

Extract the Build.sql file from the Xtraction installation package (Xtraction (VERSION).zip)
Run the Build.sql file on the Xtraction database to create the structure and populate the database

Page 8 of 35

Xtraction Installation Guide

January 2015

Installation Instructions
Installing Xtraction
After completing the pre-installation steps in the previous section, run the installation program,
Xtraction.msi, to install the Xtraction application.

After reading the welcome message, click Next to continue.

After reading the software license, select I accept the terms in the License Agreement and click
Next to continue.

Page 9 of 35

Xtraction Installation Guide

January 2015

Designate the folder where Xtraction is to be installed. The default folder is Xtraction
Software\Xtraction within the systems Program Files folder.

When ready to install the files, click Install.

Page 10 of 35

Xtraction Installation Guide

January 2015

The installer will step through a number of tasks, such as copy the files, registering components, and
configuring Internet Information Server (IIS).

Once the installation steps are complete, the configuration tool will run. Click the Setup wizards
Finish button at any time to close the installer.

Page 11 of 35

Xtraction Installation Guide

January 2015

Configuring Xtraction
When the configuration tool first runs at the completion of the installer, either step through the
wizard to configure Xtraction or cancel the wizard and run the configuration at a later time.

IMPORTANT: If the configuration tool is cancelled, Xtraction will not work until configuration is run
again and successfully completed. To rerun the configuration, run Tools\XtractionInstaller.exe
located in the installation folder for Xtraction.

Select the appropriate Data Model and click Install. You will get a message to say that is has been
installed, click OK on the message to move to the next screen.

Page 12 of 35

Xtraction Installation Guide

January 2015

You will be provided with two license files, one for Xtraction and the other for the data model editor.
Locate both those files using the buttons and then click Install to set them up within the
Xtraction installation.

Clicking Finish will load the settings editor.

Page 13 of 35

Xtraction Installation Guide

January 2015

Settings Editor

Xtraction Database Settings

To configure the connection settings to the Xtraction database created prior to installation, click on
the button in the Xtraction Database section.

Server

The name of the database server where the Xtraction database resides. If a non-standard
port is used, place a comma (,) after the server name, followed by the port number.

Database

The name of the Xtraction database created as part of the pre-installation steps.

User Id

The User ID that Xtraction should use when connecting to this database. This field is not
required if Integrated Security is being used.

Password

The password (displayed as a series of asterisks) for the User ID specified above. This field
is not required if Integrated Security is being used.

Integrated
Security

If the account used by Xtraction to access the Xtraction database is a Windows account
instead of a SQL Server account, select Integrated Security, and leave User ID and
Password fields blank.

Additional

Any additional parameters necessary for connecting to the database (usually blank)

After you have entered the details or your database, you can use the Test button to attempt a
database connection to make sure the details provided are correct.

Page 14 of 35

Xtraction Installation Guide

January 2015

Time Zone Settings

Xtraction adjusts date/time values to the appropriate time zone. This default time zone setting in
the configuration settings will be the default time zone applied to all users unless their accounts
have been individually updated to reflect a different time zone. Xtraction automatically adjusts for
daylight savings if the selected time zone observes Daylight Savings.

Other Settings
Mobile access
permitted

Should mobile devices be permitted to logon to the Xtraction application.

Support URL

Within Xtraction a support button is located in the footer. Setting this URL will
control the action to be performed after a user clicks it and can be customised for
your own support process ie. send Xtraction users to the internal help desk. This
will support both HTTP/S and MAILTO configurations. Eg.
http://support.xtractionsolutions.com/
mailto:support@xtractionsolutions.com
When using MAILTO, the end users default mail client will be displayed allowing an
email to be sent to the correct location.

Authentication Settings
A single instance of Xtraction allows multiple methods of authentication by specifying one or more
providers. You must have at least one authentication provider for Xtraction to function correctly.
The types of authentication supported by Xtraction are:
Windows - The Xtraction user accounts are tied to the corresponding Windows user accounts. User
passwords are not maintained within Xtraction. Xtraction verifies the users identity via IIS.
Xtraction Local - The Xtraction user accounts are created and maintained within Xtraction. All
account information, including passwords, are maintained in Xtraction.
Custom - The Xtraction user accounts are tied to the corresponding user accounts in an external
system. User passwords are not maintained within Xtraction and users are authenticated by the
external system.

Page 15 of 35

Xtraction Installation Guide

January 2015

Providers

The list of the authentication providers setup within your Xtraction instance. You
can add/edit/remove these via the right click context menu or by double clicking
on a listed provider.

Token Key

The key to use for secure communication between Xtraction and the
authentication providers. This must match the key stored at the authentication
provider. This can be thought of as a password and can be changed to something
unique for your organisation. The only requirement is that the same password
needs to set at each of the authentication providers. See secretKey in Appendix
B. A default key is provided but it should be updated during installation.

Token Timeout (mins)

The number of minutes a token from an authentication provider is valid for. Any
token received by Xtraction that is older than this value will be rejected.

Default Roles

When the Automatically Create Users option is checked, any users created will
get the roles selected here by default.

Default Features

When the Automatically Create Users option is checked, any users created will
get the designer features selected here by default.

Note: Xtraction has a default Token Key but this should be changed during the installation process.
This is used to encrypt the authentication messages between the different authentication providers
and should be set to a character string of 10 20 characters. If using Windows authentication, this
value needs to be changed in the web.config file of the WinAuth web application as well, see
Appendix B.

Page 16 of 35

Xtraction Installation Guide

January 2015

Provider Details

Id

A unique id for this authentication provider instance.

Name

A display name for the provider.

Authentication Type

The type of authentication provider this instance refers to.

Url

The URL that unauthenticated users should be redirected to for authentication.

Mobile Url

The URL that unauthenticated mobile users should use to authenticate.

Automatically create
users

If Xtraction should automatically create a user who has been authenticated by the
provider, but doesnt exist within Xtraction.

Mobile access
permitted

If this authentication provider is allowed to be used from mobile devices.

Active

If this authentication provider is active within Xtraction.

NOTE: Please see Appendix B for information about configuration of Active Directory integration.

Email Settings
If you want the Xtraction task scheduler to send email, you need to provide email settings which can
be done from the Email tab.

Page 17 of 35

Xtraction Installation Guide

January 2015

Server

The name of the email server to send via

Port

The port to use when sending email to the email server

Username

The username to use to connect to the email server

Password

The password to use to connect to the email server

Sender

The sender to use when sending email from Xtraction. This must be a valid email address

Subject Prefix

Text entered here will be shown on the e-mail subject line before the document name.

Use SSL

Whether the connection to the email server needs to be made via SSL

Test Email

If you want to test the settings provided, enter an email address in the Test Email section
and then click the Test Email button.

Alert Settings
The alert settings tab is used to configure the Xtraction Alert service. The Alert service does share
email configuration with the Xtraction Scheduler service so settings on the Email tab will be used
with both the Alert and Scheduler services.

Page 18 of 35

Xtraction Installation Guide

January 2015

Xtraction URL

When notification emails are sent, there is an option to link to Xtraction content. This is
the base URL of your Xtraction installation to be used when building the Xtraction URL
sent in the notification email.

Notification
Subject Prefix

All notification emails will be sent with this prefix in the email subject.

Maximum Alerts
Allowed

The maximum number of alerts allowed to be defined in Xtraction. Once this number has
been reached, no more alerts can be defined.

Errors before
alert failure

The number of errors an alert can encounter before it is flagged as failed.

Worker Count

Once an alert is triggered to be checked, it will be placed in a queued for checking. This
value defines the number of worker processes that pull alerts from the queue to perform
alert checking and actioning if necessary.

Xtraction Dates
If you want to change the format for dates that are displayed in Xtraction, you can set them here.

Page 19 of 35

Xtraction Installation Guide

January 2015

Short Date Format

The short date format contained within the Xtraction configuration file settings.dat
is displayed here. This value can be changed and when the OK button is clicked will
save back to the settings.dat file.

Long Date Format

The long date format contained within the Xtraction configuration file settings.dat
is displayed here. This value can be changed and when the OK button is clicked will
save back to the settings.dat file.
The Long Date Format affects the way the date is shown in most presentations.

Test

Test buttons will display todays date and time in the format entered in the Short
Date Format or Long Date Format text boxes

Locale

The current locale is shown in parentheses next to Format Help. In this screen shot
the locale is (en-AU)

Format Help

This is a list of known formats for your locale.

Excel Dates
Documents that are exported to Excel will format date columns in accordance with the Excel Date
format shown below. The Excel date format is separated from the Xtraction Date formats because
Xtraction uses Windows Operating System locale date/time formats and not all these formats are
valid in Excel.

Page 20 of 35

Xtraction Installation Guide

Excel Date Format

January 2015

The date format used for columns containing dates. It is recommended that you
test the format in Excel before exporting documents to excel to be sure your
format is compatible with Excel. The Settings application does not validate the
format you save.

Data Model Settings

Before running Xtraction, you need to setup the data model selected earlier for your environment.
In the Tools folder, locate DataModelEditor.exe and run it. There are a number of settings you
will need to change to get the data model up and running.

You will then need to open your data model file using File > Open. For a default installation it is
located at C:\Program Files\Xtraction Software\Xtraction\Data\Configuration\.

Connection Strings
For each data source in your data model, a connection string must be provided so that Xtraction can
connect to that data source. You can open the connection string editor via Tools > Connection
String Editor.

Page 21 of 35

Xtraction Installation Guide

January 2015

This dialog will display all of the data sources within your data model. To edit a connection string,
click the appropriate Connection item and then click the button.
If your data model contains data sources that connect to the same physical database, after you have
setup the first connection string you can copy them by checking the appropriate items, right clicking
on the connection to copy and select Copy to selected from the context menu.

Schema or Table Owner

Depending on your database setup, it may be necessary to set the Schema/Owner that the tables
are located in. To update the schema/owner, click Tools > Schema/Owner Editor. This dialog
displays the entire data model and allows you to check the appropriate tables to update.

Simply enter the name of the schema/owner and click on the Update button. Repeat this process
for each set of tables.

Target Application URLs

In Xtraction, when displaying lists of records, the user can double-click on a record and it will launch
the associated applications website to display that record in the native application. For this to work,
Page 22 of 35

Xtraction Installation Guide

January 2015

Xtraction has to know the URL for the web site. To update the URLs within the data model, select the
Tools > Url Editor menu item.

By default the [WEBSERVER] placeholder will be included with the URLs and you will need to update
this based on your environment. URLs can be edited in the grid or you can click the Find & Replace
button to edit multiple URLs at once.

Use the Url Find and Replace dialog to replace these placeholders with the correct address.
Below are some example search & replace strings based on different scenarios:
Scenario

Sample URL

Search For

Replace With

Standard URL

http://appserver/CAisd/...

[WEBSERVER]

appserver

HTTPS

https://appserver/CAisd/...

https://[WEBSERVER]

https://appserver

Alternate Port

http://appserver:8080/CAisd/

[WEBSERVER]

appserver:8080
Page 23 of 35

Xtraction Installation Guide

January 2015

Post Installation Steps

After the installation and configuration of Xtraction is complete, there are a few additional postinstallation steps necessary.

Confirm IIS Settings

Below is a checklist of IIS settings that should be confirmed before running Xtraction for the first
time:

Windows 2003
These settings only apply if Xtraction is installed on a Windows 2003 server:
1.

Confirm that ASP.NET v4.0.30319 exists under Web Service Extensions and is set to Allowed
a. If it does not exist, try running the following command to register ASP.NET

C:\Windows\Microsoft.NET\Framework\v4.0.30319\aspnet_regi
is.exe I -enable
2.

Confirm settings in the Properties dialog for the Xtraction virtual directory located under the Default
Web Site
a. Home tab: Xtraction should run within its own Application Pool. The Xtraction application
pool should be created during the installation.
b. ASP.NET tab: ASP.NET version should be set to 4.0.30319

Windows 2008 or above

These settings only apply if Xtraction is installed on a Windows 2008 server or above:
1.

Confirm settings for the web site

a. Basic Settings: Xtraction should run within its own Application Pool. The Xtraction
application pool should be created during the installation.

Integrated Security Connecting to Xtraction Database

NOTE: This section is only required if any of the database connections use Integrated Security
If any of the database connections use Integrated Security, follow these steps:

Windows Server 2003

1.
2.
3.

In IIS, locate the Xtraction application pool

Right click -> Properties
On the Identity tab, setup the user account used to access the database.
Note: the user account needs to be part of the IIS_WPG group and also be included Log on as a
service security policy. This may need a server restart to pick up.
Page 24 of 35

Xtraction Installation Guide

January 2015

Windows Server 2008 or above

1.
2.
3.

In IIS, locate the Xtraction application pool

Open Advanced Settings
Change the Identity setting to the user account used to access the database.

Note: The Xtraction web application will now execute as the user account specified. This account
will need the correct permission to the file system in order to read the Xtraction web files (located at
C:\Program Files\Xtraction Software\Xtraction\Web\Server\ by default).

Configure Xtraction Task Manager

The Xtraction Task Manager is a Windows Service used to run scheduled exports of Documents and
Custom Reports. This will have been installed into Windows Services by default but may need to be
configured for your environment. Follow these steps below to configure:
1.

2.
3.
4.

5.

Make sure the file is not blocked.

a. Navigate to the Tools folder
b. Locate the Xtraction.SchedulerService.exe file
c. Right click -> Properties
d. Check to see if there is an Unblock button on the General tab (Windows Server 2008 R2)

e. Click Unblock, then Apply, then OK

f. Right click -> Properties again to make sure it has disappeared
Open the Services manager
Scroll to the bottom where you should see Xtraction Task Manager
Setup the appropriate settings
a. Startup type
b. Logon
Start the Xtraction Task Manager service

Configure Xtraction Alerts

Xtraction Alerts is a Windows Service used to run the alert checks defined within Xtraction. This will
have been installed into Windows Services by default but may need to be configured for your
environment. Follow these steps below to configure:
1.

Make sure the file is not blocked.

a. Navigate to the Tools folder
Page 25 of 35

Xtraction Installation Guide

b.
c.
d.

2.
3.
4.

5.

January 2015

Locate the Xtraction.AlertService.exe file

Right click -> Properties
Check to see if there is an Unblock button on the General tab (Windows Server 2008 R2)

e. Click Unblock, then Apply, then OK

f. Right click -> Properties again to make sure it has disappeared
Open the Services manager
Scroll to the bottom where you should see Xtraction Alerts
Setup the appropriate settings
a. Startup type
b. Logon
Start the Xtraction Alerts service

iPad Client Access

If you have iPad clients connecting to your Xtraction server, changes need to be made depending on
the authentication method used to connect to Xtraction.
NOTE: Logon details are passed to the Xtraction server in plain text. It would be best to setup SSL
on the Xtraction server and connect iPad clients using HTTPS.

General Settings
1.

Ensure the Mobile access permitted checkbox is selected in the Xtraction settings tool. This needs
to be checked on only the authentication providers that should be displayed to iPad users for
authentication.

FIPS Compliance
NOTE: This section is only required if the Xtraction server requires applications to be FIPScompliant
Xtraction uses FIPS-compliant encryption algorithms. If the Xtraction server requires all applications
be FIPS-compliant, the web.config file needs to be edited. This file is found in the Web\Server
subfolder of the installation folder for Xtraction. The following text needs to be added after the line
<system.web>:
<machineKey validationKey=AutoGenerate,IsolateApps
decryptionKey=AutoGenerate,IsolateApps validation=3DES
decryption=3DES/>
Page 26 of 35

Xtraction Installation Guide

January 2015

This is required so that ASP.NET uses a FIPS-compliant algorithm for certain actions.

Page 27 of 35

Xtraction Installation Guide

January 2015

Running the Application

If all of the above steps have been completed, you are now ready to run the application by pointing a web
browser at:

http://[SERVER]/xtraction/
replacing [SERVER] with the name of the server you installed the application on.
The initial user in Xtraction has administrator and enterprise designer rights. What account is
created as the initial user is based on the Application Logon Type selected during configuration.
Windows Integrated

The first person to access Xtraction will have an account automatically created

Local Database

An account with username admin and password password

Page 28 of 35

Xtraction Installation Guide

January 2015

Initial Administrative Tasks

Change Admin Password
If Xtraction was configured to use Dashboard Local Users for authentication, then the default
password for the admin account should be changed immediately. (See Changing Users Password
in the Administration Guide)

Create Users
Create accounts for the initial users of Xtraction. If the Auto Create option was selected during
installation, the accounts will be created the first time the users access Xtraction; however, their
accounts can be created ahead of time to allow their roles to be assigned beforehand. (See Creating
a User in the Administration Guide)

Create Filters
A discovery can run to create filters for the top 10 values most used during the previous 30 days.
You can access this via the Administration > Filter Builder menu option within Xtraction. A filter is
not automatically created for every possible value. This is not practical and not necessary. After this
has been run, it is convenient to have existing filters for key values. For this reason, it is good idea to
review the initial filters created for each field in each data view to determine if any filters for key
values are missing and add them. (See Designing and Managing Filters in the User Guide)

Create Public Folders

It is helpful for designers and enterprise designers if an initial set of public folders exists for
organizing dashboards. How the dashboards are organized will vary from one installation to
another. One example is to have top level folders for each organizational unit with subfolders for
different types of dashboards, such as Daily, Weekly, Monthly, and Annual. (See Managing Xtraction
Folders in the User Guide)

Page 29 of 35

Xtraction Installation Guide

January 2015

Appendix A: Pre-Installation Checklist

Xtraction Server Name
Xtraction Database Name
Xtraction Database Username
Xtraction Database Password
Application Server Name
Application Database Name
Application Database read-only Username
Application Database read-only Password
Application Database Table Owner (if not dbo)
URL to access Application web interface:
(i.e.: http://myserver/Caisd/pdmweb.exe)

Page 30 of 35

Xtraction Installation Guide

January 2015

Appendix B: Active Directory Integration

You can use Xtraction Active Directory Integration to manage Xtraction users from Active Directory,
rather than managing Xtraction user accounts from within Xtraction itself. Some examples of how
this can be used include:
-

Only authenticating users who are a member of a particular Active Directory group (AD
group)
Mapping users of a particular AD group to Xtraction user attributes
o Members of AD group X-NetworkOps should have the Xtraction Designer role, have
access to Xtraction Dashboards and Documents, be placed in the Network
Operations Xtraction group and have the Network Operations Xtraction data policy.

Active Directory integration is handled via the WinAuth application located at

Xtraction\Web\WinAuth. When you have enabled Windows Authentication within Xtraction, all
authentication requests are sent to this application where authentication will occur. After a user has
been authenticated their details will be queried from the directory (if enabled, see below) and
return to Xtraction. The users Xtraction account will then be updated with these details.
Once settings have been configured, a page is available to test the configuration. For a default
installation, this can be accessed at:
http://[SERVER]/XtractionWinAuth/UserInfo.aspx

Settings
All settings for this authentication provider are setup via its Web.config file
(Xtraction\Web\WinAuth\Web.config). A configuration element is available xtractionAuth that is
used to configure all parameters. See the sample section below along with these definitions:

xtractionAuth
secretKey

The key to use for secure communication between Xtraction and the
authentication providers. This must match the Token Key on the
Authentication tab in Xtraction Settings.

userAttributeSource

The source of where user attributes will be queried from

DIRECTORY User attributes should be queried from a directory based on
the directory locations setup.

queryAdditionalUserAttributes

Should attribute user attributes (full name, email) be queried from the user
attribute source. Valid values are true or false.

updateXtraction

Should Xtraction be updated based on the values from the queried from the
user attribute source and the group mappings defined. Valid values are
true or false.
Note: If this value is set to true, Xtraction user accounts will be updated
based on the users AD groups and the associated group mapping. Any
manual changes to the roles, features, groups or data policy of an Xtraction
user account will be replaced.
Page 31 of 35

Xtraction Installation Guide

authenticatedGroups

January 2015

The list of group names (| delimited) that a user must be a member of to

be able to access Xtraction. No check on group membership will be made if
this value is empty.

directoryLocations
The directoryLocations section defines the user repositories to query. At least one directoryLocation
is required.
name

A unique name for the directory location.

contextType

The type of directory

MACHINE Search the local machine to find users access Xtraction
DOMAIN - Search a domain to find users accessing Xtraction

connectionConfig

Additional configuration information required to query the directory. For

MACHINE this can be left empty. For DOMAIN, this needs to be a |
delimited list of configuration information. Some example configurations:
HOST/DOMAIN
HOST/DOMAIN|CONTAINER
HOST/DOMAIN|CONTAINER|USERID|PASSWORD

groupMap
The groupMap is used to map Windows group members to Xtraction user attributes. This allows you
to manage Xtraction users from Active Directory and have user attributes pushed into Xtraction. If
multiple group mappings apply based on the users AD group membership, the actual group mapping
will be a product of the matching mappings.
Note: If multiple group mappings are matched based on the AD group membership and multiple
security policies are in use across those mappings, Xtraction will not authenticate the user.
name

A unique name for this group mapping.

windowsGroupName

The AD group that this group mapping relates to.

roleIds

The Xtraction roles members of this group should be assigned

1 Administrator
2 Enterprise Designer
3 Private Designer
4 Designer
5 Scheduler

featureIds

The Xtraction designer features members of this AD group should be

assigned
1 Dashboards
2 Documents
3 SQL Reports

xtractionGroupNames

The Xtraction group names members of this AD group should be assigned.

This is a | delimited list.
Page 32 of 35

Xtraction Installation Guide

securityPolicyName

January 2015

The Xtraction data policy members of this AD group should be assigned.

This can be left blank for users who dont need a data policy assigned.

Sample
A sample of the xtractionAuth section can be seen below:
<xtractionAuth
secretKey="abc123"
userAttributeSource="DIRECTORY"
queryAdditionalUserAttributes="true"
updateXtraction="true"
authenticatedGroups="X-Administrators|X-PrivateDesigners|X-Viewers"
>
<directoryLocations>
<add name="domain" contextType="DOMAIN" connectionConfig="corp.domain.com" />
</directoryLocations>
<groupMap>
<add
name="administrators"
windowsGroupName="X-Administrators"
roleIds="1,2"
featureIds="1,2,3"
xtractionGroupNames=""
securityPolicyName="" />
<add
name="private-designers"
windowsGroupName="X-PrivateDesigners"
roleIds="3"
featureIds="1,2"
xtractionGroupNames="Network Operations"
securityPolicyName="Network Operations" />
<add
name="viewers"
windowsGroupName="X-Viewers"
roleIds=""
featureIds=""
xtractionGroupNames="Service Desk"
securityPolicyName="Service Desk" />
</groupMap>
</xtractionAuth>

Examples
Directory
1.

Connect to the corporate Active Directory using the currently executing user (from the
Application Pool XtractionWinAuth).
<add
name=domain
contextType=DOMAIN
connectionConfig=corp.domain.com
Page 33 of 35

Xtraction Installation Guide

January 2015

/>
2.

Connect to a container within the corporate Active Directory using the currently executing
user.
<add
name=domain
contextType=DOMAIN
connectionConfig=corp.domain.com|CN=mydirectory,O=corp,C=au
/>

3.

Connect to the corporate Active Directory using a specified user.

<add
name=domain
contextType=DOMAIN
connectionConfig=corp.domain.com|USERNAME|PASSWORD
/>

Group Mapping
1.

Users who are members of the Xtraction-Administrators AD group need to be Xtraction

Administrators, Xtraction Enterprise Designers with access to Dashboards, Documents and
SQL Reports.
<add name="administrators"
windowsGroupName="Xtraction-Administrators"
roleIds="1,2"
featureIds="1,2,3"
xtractionGroupNames=""
securityPolicyName="" />

2.

Users who are members of the Xtraction-Enterprise-Designers AD group need to be

Xtraction Enterprise Designers with access to Dashboards and Documents and assigned the
Xtraction Standard User data policy.
<add name="enterprise-designers"
windowsGroupName="Xtraction-Enterprise-Designers"
roleIds="2"
featureIds="1,2"
xtractionGroupNames=" "
securityPolicyName="Standard User" />

3.

Users who are members of the Service Desk AD group need to be Xtraction Private
Designers with access to Dashboards, be placed into the Xtraction Service Desk 1 group
and assigned the Xtraction Standard User data policy.
Page 34 of 35

Xtraction Installation Guide

January 2015

<add name="service-desk"
windowsGroupName="Service Desk"
roleIds="3"
featureIds="1"
xtractionGroupNames="Service Desk 1"
securityPolicyName="Standard User" />
4.

Users who are members of the Xtraction-Read-Only AD group need to be assigned the
Xtraction Restricted User data policy.
<add name="viewers"
windowsGroupName="Xtraction-Read-Only"
roleIds=""
featureIds=""
xtractionGroupNames=" "
securityPolicyName="Restricted User" />

Page 35 of 35