Unica Web Analytics - Genemco Inc

Unica Web Analytics

Data Conduit for ODBC

Copyright

© Copyright Unica Corporation 1999 - 2007. All Rights Reserved.

Unica CorporationReservoir Place North170 Tracer LaneWaltham, MA 02451-1379

Examples and Data

All software and related documentation is subject to restrictions on use and disclosure as set forth in the applicableUnica Software License and Services Agreement or End User License Agreement, with restricted rights for U.S.government users and applicable export regulations.

Companies, names, and data used in examples herein are ficticious unless otherwise noted.

Trademarks and Patents

Unica®, the Unica Logo, Affinium®, NetTracker®, My NetTracker®, and Ask NetTracker® are registered trademarksof Unica Corporation with the U.S. Patent and Trademark Office. Affinium Campaign™, Affinium CampaignCollaborate™, Affinium Campaign eMessage™, Affinium Campaign Interact™, Affinium Campaign Optimize™,Affinium Detect™, Affinium NetInsight™, Affinuim Leads™, Affinium Leads Referral™, Affinium Leads Contact™,Affinium Model™, Affinium Plan™, Affinium Mart™, Universal Dynamic Interconnect™, Interconnect Modules™,Marketic™, Powering Marketing Success™, Customer Value Maximization™, MAP™, One-to-One Optimization™,and Right-time Marketing™ are trademarks of Unica Corporation. All other trademarks are the property of theirrespective owners.

Portions of the software described in this document are covered by U.S. Patent Numbers: 6,317,752, 6,269,325,6,542,894, and 6,782,390.

The NetTracker and Affinium NetInsight products are licensed under the following patents and patent publications:US5,675,510, US6,115,680, US6,108,637, US5,796,952, US6,138,155, US6,653,696, US6,763,386, AU0701813,BR9609217, CA2223919, EP0843946, JP03317705, MX193614, NO09705728, AU735285, CA2246746, CN1174316,CN1547123, CN1547124, DK870234, DE69720186, ES2195170, AU727170, BR9808033, CA2284530, CN1251669,IL131871, JP2000514942, KR341110, NZ337756, WO9641495, EP0870234, EP1130526, EP1168196,US20040078292, WO9810349, US20050114511, US20040221033, WO9843380.

Markup functionality in Affinium Plan is enabled through use of third-party software components from AdLib™eDocument Solutions and Adobe® Acrobat®. "Powered by AdLib™."

NOTICE: This document contians confidential and proprietary information of Unica Corporation ("Unica"). Use,duplication, or disclosure without the express written consent of Unica Corporation is prohibited.

Document Information

Unica Web Analytics Data Conduit for ODBC

Table of ContentsChapter 1 Getting Started 5

About NetInsight/NetTracker naming conventions .........................................................5Introduction to the NetInsight data conduit .....................................................................5How to install the data conduit on a Windows system ................................................... 7How to install the Data Conduit on a UNIX system ........................................................7About configuring the data conduit .................................................................................8

Chapter 2 Directives 9

Database connection string directive ............................................................................. 9About the clip, cookie, host, user, and visitor lookup directives ................................... 11About parameter lookup directives ...............................................................................13About department lookup directives .............................................................................14About page title lookup directives ................................................................................ 14About product directives ...............................................................................................15About rewrite directives ................................................................................................16User information directive ............................................................................................ 17User authentication directive ........................................................................................18Debug directive ............................................................................................................ 18Unloadme directive ...................................................................................................... 19

Chapter 3 Testing the Data Conduit's Configuration 21

How to use the APITest utility ...................................................................................... 21Command-Line usage examples ................................................................................. 22

Chapter 4 Telling NetInsight to Use the Data Conduit 25

How to tell NetInsight to use the data conduit ..............................................................25How to tell NetInsight to use the data conduit for user authentication ......................... 27How to tell NetInsight to use the data conduit for user information ..............................28How to set environment variables ................................................................................ 29How to configure the data conduit example ................................................................. 29How to regenerate summaries for a profile .................................................................. 33How to configure the cookie lookup example ...............................................................34

Index 39

Unica Web Analytics Data Conduit for ODBC iii

Table of Contents

iv Unica Web Analytics Data Conduit for ODBC

1 GETTING STARTED

Key topics in this chapter include:

❏ About NetInsight/NetTracker naming conventions (Page 5)

❏ Introduction to the NetInsight data conduit (Page 5)

❏ How to install the data conduit on a Windows system (Page 7)

❏ How to install the Data Conduit on a UNIX system (Page 7)

❏ About configuring the data conduit (Page 8)

About NetInsight/NetTracker naming conventionsThis document applies to both NetInsight and NetTracker.

However, throughout this document, "NetInsight" is used to refer to both products. Unless otherwisenoted, the information in this document applies to both products.

Introduction to the NetInsight data conduitYou can use the data conduit to:

• Pull information from a database into reports. For example, you can replace each cookie in aCookie Summary with a company, contact name, and phone number pulled from a database ofcustomers.

Information is pulled into reports when they are generated. You generate reports by clicking theUpdate icon (the left-most icon in the group of icons in the upper-right-hand corner of theinterface] or use the -update command-line option.) The values from the database appear in thereports, but they are not written to the database. The database still contains the values that camefrom the log files.

Unica Web Analytics Data Conduit for ODBC 5

You can use the data conduit to look up the following information in a database:

❍ Clip data (for media profiles)

❍ Cookie data (for Web profiles)

❍ Department data

❍ Host data

❍ Information about parameter values

❍ Page title data (for Web profiles)

❍ User data

❍ Visitor data (for Web profiles)

• Rewrite page, file, clip, and parameter data based on data stored in a database.

Information is pulled into NetInsight when the log files are processed. (NetInsight processes logfiles when you click the Update icon in NetInsight or run NetInsight with the -updatecommand-line option.) The values from the database are stored in the NetInsight database andreplace the values that came from the log files.

Note that the method you choose (that is, looking up data in a database or rewriting data) dependson whether you want to replace values in the NetInsight database and how you want to filterreports. To help you decide, this document contains a table that lists the difference betweenlooking up a value and rewriting a value (Page 18).

• Authenticate users by verifying that the username and password the user enters are valid.

• Retrieve a user's full name and e-mail address instead of manually entering this information in theadministrative options.

For NetInsight to use external data, you must specify the path and filename for the data conduit. Youmust also specify the path and filename of the configuration file that specifies which information thedata conduit is to retrieve from the database. (NetInsight passes the path and filename of theconfiguration file to the data conduit.)

For user authentication and user information (the user's full name and e-mail address), you specify thedata conduit and configuration file on the Authentication page in the administrative options.

For all other data, you specify the data conduit and configuration file on the Data Conduits page ofthe profile options for the NetInsight profile in which you want to use the data. You must set up thesedata conduits on a profile-by-profile basis. You can use different data conduits with different profiles.

Following are details on installing and configuring the data conduit and configuring NetInsight to useit. This document also contains step-by-step examples of how to use a parameter lookup data conduitto look up content type data stored in an external database, and how to use a cookie lookup dataconduit to replace cookie values with customer data stored in an external database.

Chapter 1 : Getting Started

6 Unica Web Analytics Data Conduit for ODBC

We recommend that you read the entire document before you install, configure, and use the dataconduit.

How to install the data conduit on a Windows systemThe following task describes how to install the data conduit for ODBC on a Windows system.

1. Double-click ntdiodbc-{Release-Number}.exe.

2. Click Next.

3. Specify the temporary directory in which you want to place the data conduit files. Make note ofthis directory, as you will need to move the files.

4. Click Next.

5. Open the directory that contains the data conduit files.

6. Copy the following files to the NetInsight program directory (the default program directory isC:\Program Files\NetInsight):

• apitest.exe

• ntdiodbc.conf

• ntdiodbc.dll

You can now configure the data conduit (Page 8) .

How to install the Data Conduit on a UNIX systemThe following task describes how to install the Data Conduit for ODBC on a UNIX system.

1. Unpack the archive into a temporary directory. For example:

• gunzip ntdiodbc-{Release-Number}.tar.gz

• tar xvf ntdiodbc-{Release-Number}.tar

2. Change directories into the unpacked directory. The configuration file is in that directory, butapitest and ntdiodbc.so are in a subdirectory specific to your platform.

3. Copy the following files to the NetInsight program directory (the default program directory is/usr/local/NetInsight):

• apitest

• ntdiodbc.conf

How to install the data conduit on a Windows system

7

• ntdiodbc.so

About configuring the data conduitThe data conduit's configuration file contains "directives" for each piece of information you want toretrieve from the database. Directives tell the data conduit what kind of data (for example, host dataor information about a parameter value) to retrieve and in some cases how to format it. Theconfiguration file also contains the information the data conduit needs to connect to the database.Note that the name of each directive varies according to the operation to which it relates.

The configuration file is located in the same directory in which you installed the data conduit, and isnamed ntdiDB_NAME.conf. Each line in the configuration file is composed of a case-sensitivedirective followed by any amount of white space and then the value to be associated with thedirective. Note that:

• A line beginning with a pound sign (#) is considered a comment.

• Comments and blank lines are ignored.

• You do not need to use quotation marks to group values that contain spaces.

• Anything after the directive and before the end of the line is considered the value for the directive.

The first directive or set of directives contains the information the data conduit needs to connect tothe database. The remaining directives (for example, lookup directives) tell the data conduit whatkind of information to retrieve and how to process the information.

Chapter 1 : Getting Started


2 DIRECTIVES


❏ Database connection string directive (Page 9)

❏ About the clip, cookie, host, user, and visitor lookup directives (Page 11)

❏ About parameter lookup directives (Page 13)

❏ About department lookup directives (Page 14)

❏ About page title lookup directives (Page 14)

❏ About product directives (Page 15)

❏ About rewrite directives (Page 16)

❏ User information directive (Page 17)

❏ User authentication directive (Page 18)

❏ Debug directive (Page 18)

❏ Unloadme directive (Page 19)

Database connection string directiveThis topic describes the database connection string directive for connecting to an ODBC database.

ConnectString

The ODBC connect string is necessary to connect to the database from which the user desires toretrieve data.


Example (Windows and UNIX

To connect to a data source using a previously defined Data Source Name (DSN):ConnectString DSN=DSNName;

Example (Windows

To connect to a SQL Server database without using a previously defined DSN:ConnectString DRIVER={SQLServer};UID=username;PWD=password;SERVER=servername;DATABASE=dbname;

To connect to a Microsoft Access database without using a previously defined DSN:ConnectString DRIVER={Microsoft Access Driver(*.mdb)};DBQ=C:\path\to\db.mdb;

Example (UNIX

To connect to a SQL Server database:DRIVER=./libtdsodbc.so;Port=1433;TDS_Version=7.0;UID=username;PWD=password;Server=servername;Database=dbname

To connect to a Sybase database:DRIVER=./libtdsodbc.so;Port=5000;TDS_Version=5.0;UID=username;PWD=password;Server=servername;Database=dbname

DriverPrompt (Windows Systems Only)

Specifies how you would like to be prompted for database connection information. The following listshows the DriverPrompt values and the results.

• 1 - Prompt for database connection information if no DSN or DRIVER keyword is found in theConnectString directive.

• 2 or 3 - Prompt for database connection information, using the value of the ConnectStringdirective for default values.

• Any other value - Provides the user with no prompt, even if the connection fails (default).

When the Debug directive is set to a value of 1 (on), the data conduit will print, to the console, theconnection string both before and after attempting to connect to the database. This is particularlyuseful in combination with the DriverPrompt directive; supplying a value for theDriverPrompt directive and turning on the Debug directive provides a simple way to connect to adatabase and retrieve the resulting connect string. This connect string can in turn be used as the valuefor the ConnectString directive, simplifying the editing of the configuration file.

Chapter 2 : Directives


About the clip, cookie, host, user, and visitor lookupdirectives

In the names of the lookup directives described below, replace {Type} with the lookup type. Thepossible values for {Type} are:

• Clip

• Cookie

• Host

• User

• Visitor

Lookup types are case sensitive.

{Type}DataSource

The SQL query to be executed to retrieve the desired value. The supplied value should contain thetoken %VALUE%, which will be replaced by the data conduit during each lookup with the value to bereplaced. For example:HostDataSource SELECT Contact, Name, Phone, EMail FROM HostLookupWHERE Host = '%VALUE%'

In this example, %VALUE% will be replaced with the host name or IP address from the log files.

{Type}DataFormatHTML

The string to be used to format the values retrieved from the database when generating reports inHTML. The supplied value should contain the following:

• Any necessary HTML format strings.

• The tokens %FIELD1%, %FIELD2%, ..., %FIELDn%, which will be replaced by the data conduitduring each lookup with the value of column N contained in the result set retrieved from thedatabase.

About the clip, cookie, host, user, and visitor lookup directives

11

• %FIELDn% tokens may appear in any order, and multiple tokens for a single field may be usedmultiple times within the same format string.

• Any links should use the CSS class dataTableRows (see the example below). Otherwise, thelinks will not be visible in the reports.

Example value:HostDataFormatHTML %FIELD1% from %FIELD2% <a class="dataTableRows" href="mailto:%FIELD4%">%FIELD4%</a> or%FIELD3%

Example result:J. Doe from doe.com <a class="dataTableRows" href "mailto:[email protected]">[email protected]</a>or 1(800)123-4567

{Type}DataFormatRTF

The string to be used to format the values retrieved from thedatabase when generating reports in RTF.The supplied value should contain the following:

• Any necessary RTF format strings.

• The tokens %FIELD1%, %FIELD2%, ..., %FIELDn%, which will be replaced by the data conduitduring each lookup with the value of column N contained in the result set retrieved from thedatabase.

%FIELDn% tokens may appear in any order, and multiple tokens for a single field may be usedmultiple times within the same format string.

Example value:HostDataFormatHTML %FIELD1% from %FIELD2% HostDataFormatRTF \sa0\sb120{%FIELD1%\par}\sa0\sb0{%FIELD2%\par}\sa0\sb0{%FIELD4%\par}\sa120\sb0{%FIELD3%}

Example result:\sa0\sb120{J. Doe\par}\sa0\sb0{doe.com\par}\sa0\sb0{[email protected]\par}\sa120\sb0{1(800)123-4567}7

{Type}DataFormatCSV

The string to be used to format the values retrieved from the database when generating reportsrequiring plain text — this includes not only reports exported in CSV format, but also graph labelswithin NetInsight reports.



The supplied value should contain the tokens %FIELD1%, %FIELD2%, ..., %FIELDn%, which will bereplaced by the data conduit during each lookup with the value of column N contained in the result setretrieved from the database. You do not need to supply enclosing quotes in the CSV format;NetInsight will supply these when the CSV data file is created.

%FIELDn% tokens may appear in any order, and multiple tokens for a single field may be usedmultiple times within the same format string.

Example value:HostDataFormatCSV %FIELD1% from %FIELD2%

Example result:J. Doe from doe.com

About parameter lookup directivesTo facilitate lookups for multiple parameters, parameter lookup directives are defined on aparameter-by-parameter basis. Lookup directives for parameters begin with the keyword Param.

To differentiate between directives for different parameters, the identifiers for parameter lookupsshould end with an underscore, followed by the name of the parameter exactly as it has been enteredin the Name text box on the Parameters page in the NetInsight profile options, including the case.(Do not use the entry in the Parameter text box on the Parameters page.)

For example, to configure lookups for the parameter product, you would configure the followingdirectives:

• ParamDataSource_product

• ParamDataFormatHTML_product

• ParamDataFormatRTF_product

• ParamDataFormatCSV_product

For example, to configure lookups for the parameter category, you would configure the followingdirectives:

• ParamDataSource_category

• ParamDataFormatHTML_category

• ParamDataFormatRTF_category

• ParamDataFormatCSV_category

The directives for looking up data for parameters function the same as the directives for looking up

About parameter lookup directives

13

clips, cookies, hosts, users, and visitors (Page 10) .

About department lookup directivesFollowing are descriptions of the DepartmentDataSource and DepartmentFallBackdirectives.

Department lookup directives are case sensitive.

DepartmentDataSource

The SQL query to be executed to determine the department grouping to which a user or host belongs.The supplied value should contain the token %VALUE%, which will be replaced by the data conduitduring each lookup with the user name or host name from the log files.

If the Departments defined primarily by option in the Departments profile options is set to Hosts,NetInsight provides the host name to the data conduit. If the option is set to Users, NetInsightprovides the user name to the data conduit.

Examples:DepartmentDataSource SELECT Department FROM DepartmentLookup WHEREUserName = ‘%VALUE%’

DepartmentDataSource SELECT Department FROM DepartmentLookup WHEREHostName = ‘%VALUE%

DepartmentFallBack

When the DepartmentFallBack directive is set to 1 (the default), NetInsight falls back to the listof departments specified for the Departments profile option to determine a department if the queryspecified by DepartmentDataSource does not return data. Set DepartmentFallBack to 0to prevent NetInsight from using the internal list if the query URL does not return data.

About page title lookup directivesFollowing are descriptions of the PageTitleDataSource and PageTitleFallBackdirectives.



Page title lookup directives are case sensitive.

PageTitleDataSource

The SQL query to be executed to retrieve the desired page title. The supplied value should contain thetoken %VALUE%, which will be replaced by the data conduit during each lookup with the page forwhich a title is needed. NetInsight will replace %VALUE% with the page that it reads from the logfiles.

Examples:PageTitleDataSource SELECT PageTitle FROM TitleLookup WHEREPageLocation = ‘%VALUE%’okup WHERE UserName = ‘%VALUE%’

PageTitleFallBack

When the PageTitleFallBack directive is set to 1 (the default), NetInsight falls back to HTTPto resolve page titles if the query specified by PageTitleDataSource does not return data. IfNetInsight cannot resolve a page title through the data conduit, it will attempt to retrieve the page titlefrom the actual page. Set PageTitleFallBack to 0 to prevent page title resolution via HTTP ifthe query does not return data.

About product directivesFollowing are descriptions of the ProductLookup and ProductRewrite directives.

Product directives are case sensitive.

ProductLookup

The SQL query to be executed to lookup a SKU and display information in reports.

Example:ProductLookup SELECT ProductName FROM Products WHERE SKU = ‘%VALUE%’

ProductRewrite

The SQL query to be executed to lookup a SKU and store information in the database.

Example:

About product directives

15

ProductLookup SELECT ProductName FROM Products WHERE SKU = ‘%VALUE%’

About rewrite directivesFollowing are descriptions of the RewritePageDataSource andRewriteParamDataSource_paramname directives.

Rewrite directives are case sensitive.

RewritePageDataSource

The SQL query to be executed to retrieve the desired page, file, or clip value. The supplied valueshould contain the token %VALUE%, which will be replaced by the data conduit during each lookupwith the page, file, or clip value to be replaced. NetInsight will replace %VALUE% with the page, file,or clip that it reads from the log files.

Example:RewritePageDataSource SELECT NewPageLocation FROM PageRewrite WHEREPageLocation = '%VALUE%'

If the %VALUE2% token is present, it will be replaced with the query string associated with therequest (if one exists).

Example:RewritePageDataSource SELECT NewPageLocation FROM PageRewrite WHEREPageLocation = ‘%VALUE%’ AND PageQueryString = ‘%VALUE2%’

RewriteParamDataSource_paramname

The SQL query to be executed to rewrite the desired parameter value. To facilitate directives formultiple parameters, parameter rewrite directives are defined on a parameter-by-parameter basis.Rewrite directives for parameters begin with the keyword RewriteParam.

To differentiate between directives for different parameters, the identifiers for parameter rewritesshould end with an underscore, followed by the name of the parameter exactly as it has been enteredin the Name text box on the Parameters page in the NetInsight profile options, including the case.(Do not use the entry in the Parameter text box on the Parameters page.)

For example, to configure rewrites for two parameters named product and category, you wouldconfigure the following directives:

• For the product parameter, RewriteParamDataSource_product

• For the category parameter, RewriteParamDataSource_category



The supplied value should contain the token %VALUE%, which will be replaced by the data conduitduring each rewrite with the value to be replaced.

Example:RewriteParamDataSource_paramname SELECT NewParamValue FROMParamLookup WHERE ParamValue = ‘%VALUE%’

Differences Between a Parameter Lookup and a Parameter Rewrite

The following table lists the difference between a parameter lookup directive and a parameter rewritedirective.

Parameter lookup directive Parameter rewrite directive

The external database is queried for the value correspondingto the parameter you specified. Only the value that appearson the reports is replaced.

The external database is queried forthe value corresponding to theparameter you specified. The valuethat is stored in the NetInsightdatabase and the value that appearson the reports are replaced.

Using this directive may slow thespeed at which a profile updatesbecause each occurrence of theparameter in the log file may result ina query to the database for thereplacement value.

If you choose to filter a report based on the parameter youspecified, you must use the original parameter value asNetInsight read it from your Web server's log files.

If you choose to filter a report basedon the parameter you specified, youmust use the new (replaced)parameter value.

User information directiveFollowing is the description of the EmailDataSource directive.

EmailDataSource

The SQL query to be executed to retrieve a user's full name and e-mail address. The supplied valueshould contain the token %VALUE%, which is replaced by the data conduit during each lookup withthe user's user name.

User information directive

17

To look up e-mail addresses in Microsoft Active Directory Server, you should use a filter similar to"userPrincipalName=%VALUE%@example.com" # instead of "uid=%VALUE%".

ExampleEmailDataSource SELECT Email, FullName FROM UserAuth WHERELOWER(UserName) = LOWER('%VALUE%')

User authentication directiveFollowing is the description of the AuthenticationDataSource.

The user authentication directive is case sensitive.

AuthenticationDataSource

The SQL query to be executed to authenticate a user. The supplied value should contain the tokens%VALUE% and %VALUE2%, which will be replaced by the data conduit during each lookup with theuser name and password entered by the user. The authentication will be considered successful if thequery returns one or more rows of data.

Example:AuthenticationDataSource SELECT UserName FROM UserAuth WHEREUserName = '%VALUE%' AND Password = '%VALUE2%'

Debug directiveWhen the Debug directive is set to 1, the data conduit outputs debugging information. Note that thismay be problematic when NetInsight is run through a Web browser. Therefore, this option should beturned on only when you are performing tests through the command-line interface.

The Debug directive may be commented out in the data conduit's configuration file. If you want tochange the directive's default setting and the directive is commented out, remove the pound sign (#)from the line and change the value if necessary.



Unloadme directiveWhen the UnloadMe directive is set to 1, NetInsight attempts to unload the data conduit when it is nolonger needed. Unloading a dynamically loaded library may cause problems on some systems. If thisis the case, set this directive to 0 to instruct NetInsight not to unload the data conduit, leaving it to beunloaded by the system when the process exits.

The UnloadMe directive may be commented out in the data conduit's configuration file. If you wantto change the directive's default setting and the directive is commented out, remove the pound sign(#) from the line and change the value if necessary.

Unloadme directive

19



3 TESTING THE DATACONDUIT'S CONFIGURATION


❏ How to use the APITest utility (Page 21)

❏ Command-Line usage examples (Page 22)

How to use the APITest utilityThe following task describes how to use the APITest utility to test the data conduit's configuration.

The APITest utility is a command-line program that loads a data conduit, calls an individual functionwithin the data conduit, displays any results or error messages, and then unloads the data conduit. Usethe utility to ensure that you have properly installed and configured the data conduit before you use iton your NetInsight data. It is essential that you test the configuration before you use it with your data.

You must provide the utility with the following command-line arguments in the order in which theyare listed. (For examples, see Command-Line Usage Examples.)

1. Specify both of the following arguments in the order in which they are listed:

• Path specifying the location of the data conduit to be used. For example:

❍ On Windows: .\ntdiodbc.dll

❍ On UNIX: ./ntdiodbc.so

• Path specifying the location of the configuration file to be used by the data conduit. If the pathcontains one or more spaces, enclose the entire path in quotation marks. For example:

❍ On Windows: "C:\Program Files\NetInsight\ntdiodbc.conf"


❍ On UNIX: /usr/local/NetInsight/ntdiodbc.conf

2. Specify the operation (lookup, rewrite, or user authentication) to be performed by the dataconduit, and the values necessary to perform that operation:

• For a lookup, specify the lookup type and value. The lookup type is the type of data to beretrieved by the data conduit. Following are the possible types and the value to be provided tothe data conduit. (The lookup value is the value to be resolved by the data conduit.) Thefollowing list shows the lookup types and values:

❍ clip: Clip filename as read from the log files

❍ cookie: Cookie as read from the log files

❍ department: User name or host name as read from the log files

❍ host: Host name or IP address as read from the log files

❍ email: NetInsight user name

❍ lookupparam: Parameter value as read from the log files

❍ title: Page as read from the log files

❍ user: User name as read from the log files

❍ visitor: Visitor name as read from the log files

If the lookup type is lookupparam, you must also supply the name of the parameter. Notethat the parameter name must be lowercase to be properly recognized.

• For a rewrite, specify the rewrite type and value. The rewrite type is the type of data to berewritten by the data conduit. Following are the possible types and the value to be replaced.

❍ rwpage: Page, file, or clip name

❍ rwparam: Parameter value

If the rewrite type is rwparam, you must also supply the name of the parameter. Note thatthe parameter name must be lowercase to be properly recognized.

The rewrite value is the value to be rewritten by the data conduit.

• For user authentication, specify auth followed by the user name and password to be verified.

Command-Line usage examplesThe following command-line usage examples assume that the data conduit and its configuration fileare both located in the current directory.

Chapter 3 : Testing the Data Conduit's Configuration


Clip lookup

To test the data conduit with a clip lookup on a UNIX system, the correct usage is:./apitest ./ntdildap.so ./ntdildap.conf clip audioclip.asf

Cookie lookup

To test the data conduit with a cookie lookup on a Windows system, the correct usage is:apitest.exe .\ntdiodbc.dll .\ntdiodbc.conf cookie24.123.154.115-999914303691

Department lookup

To test the data conduit with a department lookup by user name on a UNIX system, the correct usageis:./apitest ./ntdiodbc.so ./ntdiodbc.conf department jane

To test the data conduit with a department lookup by host name on a UNIX system, the correct usageis:./apitest ./ntdiodbc.so ./ntdiodbc.conf department unica.com

Host lookup

To test the data conduit with a host lookup on a Windows system, the correct usage is:./apitest ./ntdiodbc.so ./ntdiodbc.conf department unica.com

NetInsight user information lookup

To test the data conduit with a NetInsight user information lookup on a Windows system, the correctusage is:apitest.exe .\ntdiodbc.dll .\ntdiodbc.conf email jane

Parameter lookup

To test a lookup for a parameter named "product" on a UNIX system, the correct usage is:./apitest ./ntdiodbc.so ./ntdiodbc.conf lookupparam product 123-4

Page title lookup

To find a page title in the databaseon a Windows system, the correct usage is:apitest.exe .\ntdiodbc.dll .\ntdiodbc.conf title/site/store/products/aq-101.html

Command-Line usage examples

23

Page rewrite

To test the data conduit to rewrite a page on a Windows system, the correct usage is:apitest.exe .\ntdiodbc.dll .\ntdiodbc.conf rwpage/site/store/products/aq-101.html

Parameter rewrite

To rewrite a parameter value on a UNIX system, the correct usage is:./apitest ./ntdiodbc.so ./ntdiodbc.conf rwparam ProductID aq-101

User lookup

To test the data conduit with a user lookup on a UNIX system, the correct usage is:./apitest ./ntdiodbc.so ./ntdiodbc.conf user jane

User authentication

To test the data conduit to authenticate a user on a Windows system, the correct usage is:apitest.exe .\ntdiodbc.dll .\ntdiodbc.conf auth janedoe a0s9d8

Chapter 3 : Testing the Data Conduit's Configuration


4 TELLING NETINSIGHT TO USETHE DATA CONDUIT


❏ How to tell NetInsight to use the data conduit (Page 25)

❏ How to tell NetInsight to use the data conduit for user authentication (Page 27)

❏ How to tell NetInsight to use the data conduit for user information (Page 28)

❏ How to set environment variables (Page 29)

❏ How to configure the data conduit example (Page 29)

❏ How to regenerate summaries for a profile (Page 33)

❏ How to configure the cookie lookup example (Page 34)

How to tell NetInsight to use the data conduitThis topic describes how to tell NetInsight how to use the data conduit for a clip, cookie, department,host, page title, parameter, user, visitor, and rewrites.

For rewrites and all types except user authentication and NetInsight user information, you tellNetInsight to use the data conduit by configuring the Data Conduits options for the profile in whichyou want to use the external data.

If you are tracking a value that is being passed as a parameter, you must define the parameter inNetInsight before you can configure NetInsight to use a data conduit for that parameter.

1. View the profile in which you want to use the data conduit.


2. Click the Options tab.

3. In the left-hand panel, under Dynamic Conent, click Data Conduits.

4. Click Add.

The Data conduit description dialog box opens.

This screen also lists the task for a previously-defined parameter named ContentTyp.

5. In the Name of data conduit box, enter the name you want to use for the data conduit.

6. In the Full path to conduit box, enter the full path (including the filename) to the .dll(Windows) or .so (UNIX) file for the conduit.

7. In the Full path to conduit config box, enter the full path (including the filename) to theconfiguration file for the conduit.

8. In the Conduit tasks box, select the tasks for which you want to use this data conduit.

To select multiple adjacent tasks, select the first task and then hold down the Shift key whileclicking the last task. To select multiple nonadjacent tasks, click the first task and then hold downthe Ctrl key (Option key on the Macintosh) while clicking the other tasks.

Chapter 4 : Telling NetInsight to Use the Data Conduit


You should only select the tasks that match the operations you configured for this data conduit.

9. When all the tasks you want are selected, click Save Options and then click Continue.

NetInsight will begin using the data conduit as soon as the profile is updated.

How to tell NetInsight to use the data conduit for userauthentication

If you are using a data conduit to authenticate users, you tell NetInsight to use the data conduit bysetting the Authentication options in the administrative options.

The plug-in configured for user authentication can also retrieve a user's full name and e-mail address;to retrieve this information, you need only configure the user information directive (Page 18) .

1. Display the Profile Manager.


3. In the left-hand panel, under Users click Authentication.

4. In the Authenticate using list, select External database.

The Authentication Options dialog box opens.

How to tell NetInsight to use the data conduit for user authentication

27

5. From the Logins expire list, select Never to have the authenticated users stay logged in untilthey manually log out. To have their logins expire when their browsers close, select When thebrowser is closed.




NetInsight begins using the data conduit immediately.

How to tell NetInsight to use the data conduit for userinformation

If you are using a data conduit to look up a user's full name and e-mail address, you configureNetInsight to use the data conduit by setting the Authentication options in the administrative options.

This plug-in can be used only with external database and Web server authentication. If you are usingan external database to authenticate users, no additional configuration is necessary.

1. Display the Profile Manager.


3. In the left-hand panel, under Users click Authentication.

4. In the Authenticate using list, select External database.

If you are using Web server authentication, the Authentication Options dialog box opens.






NetInsight begins using the data conduit immediately.

How to set environment variablesIf you are using an ODBC Driver Manager on UNIX, you may need to tell NetInsight to set one ormore environment variables. For example, if you are using the iODBC Driver Manager, you need totell NetInsight to set the ODBCINI environment variable. You may also need to tell NetInsight to setenvironment variables if you are using other third-party ODBC drivers.

You specify environment variable options in the administrative options in NetInsight. The optionsdefine the environment variables that should be set when NetInsight is started.

1. Open the Profile Manager.


3. In the left-hand panel, click Main, then click Environment Variables.

4. Click Add.

5. In the Name of variable box, enter the name of the environment variable you want to set.

6. In the Value of variable box, enter the value to which the environment variable should be set.

7. Click Save Options.

How to configure the data conduit exampleThis topic shows an example of using a data conduit for and describes how to configure this example.

The data conduit example in this section looks up a "content type" URL parameter in a database andretrieves the content type name, class, and format. This information appears on a custom ParameterSummary. It may also appear on View Breakdowns, Visit Breakdowns, Download Breakdowns,Session Breakdowns, and crosstab reports.

The following figure shows how a portion of the data would appear on the summary before the dataconduit is configured. Note that the first column displays the parameter's values:

How to set environment variables

29

The following figure shows how a portion of the data would appear on the summary after the dataconduit is configured. Note that the parameter values in the first column have been replaced with thecontent type name, class, and format pulled from an external database.

1. Create a database that contains the content type name, class, and format items entered into alookup table.

The table must contain a key column with the same ContentTyp IDs that occur in the URLs ofthe Web site. For help with creating a database, contact your database administrator.

2. Install the data conduit into your NetInsight program directory.

3. In NetInsight, view the profile in which you want to track the "content type" URL parameter.


5. In the left-hand panel, under Dynamic Content click Parameters .

6. Click Add.

7. Configure the parameter options as shown below:

8. Click Save Options, then click Continue.

9. In the Parameters to be analyzed list, select ContentTyp and then click Pages.



10. Click Add.

11. Enter a filter that describes the page(s) whose query strings you want NetInsight to check for thisparameter.

In this example, you could enter the filter as shown:

12. Click Add.

13. Indicate whether you want the query strings that are passed to this page to be searched for thecontenttypeid parameter in all new data you import from now on.

• If this is what you want, or if you have other pages to enter at this time, click Continue.

• If you want to search the query strings in this page for the ContentTyp parameter in datayou have already imported, you must delete all the data in your profile and reimport your logfiles. Note: If you do not still have all the log files you have imported into this profile, youwill lose data permanently by choosing this option.

14. In the left-hand panel, under Dynamic Content, click Data Conduits.

15. Click Add.

16. Configure the data conduit (Page 8) options as shown:

How to configure the data conduit example

31


18. Click Update (the left-most icon in the group).

19. If necessary, set environment variables in NetInsight.

20. In a text editor, open ntdiodbc.conf.

21. Configure the ConnectString connection directive the data conduit needs to connect to thedatabase.

An example for Windows is shown below.ConnectString DRIVER={SQLServer};UID=jane;PWD=a0s9d8;SERVER=server1;

DATABASE=testdb1;

22. Configure the parameter lookup directives.

An example is shown below. (This example is wrapped for readability; each directive shouldappear in the data conduit’s configuration file on a single line.)ParamDataSource_ContentTyp SELECT ContentTypeID,ContentType, ContentClass,

ContentFormat FROMreports_ContentTypeID WHERE

ContentTypeID ='%VALUE%'ParamDataFormatHTML_ContentTyp Content type:%FIELD1%, %FIELD2% Content class:

%FIELD3% Contentformat: %FIELD4%ParamDataFormatRTF_ContentTypContent type: %FIELD1%,%FIELD2%\line Content class:

%FIELD3% \lineContent format: %FIELD4%



ParamDataFormatCSV_ContentTypContent type: %FIELD1%, %FIELD2%

ContentTyp — the parameter name for the ParamDataSource_paramname directive —exactly matches the entry in the Name text box in the profile options for the parameter inNetInsight, including the case.

23. Save your changes to ntdiodbc.conf.

24. Test the data conduit's configuration.

To test the configuration, open a command-line prompt and enter the correct usage. If the dataconduit and its configuration file are both in the current directory on a Windows system, anexample of the command-line usage would be:apitest.exe .\ntdiodbc.conf lookupparam ContentTyp 103

If the parameter lookup is successful, the content type name, class, and format will appear. (If theparameter lookup is unsuccessful, an error message will appear. To resolve the error, check yoursettings for the connection directive and parameter lookup directives in ntdiodbc.conf.)

25. For the data from the data conduit to appear on the Parameter Summary, you must regeneratethe profile.

26. Do one of the following:

• Click the Custom tab and then select the Parameter Summary for ContentTyp report inthe list of available reports. To display the summary, click Run Report.

• Click the Reports tab, click Custom Analysis, and then select the Parameter Summaryfor ContentTyp report.

How to regenerate summaries for a profileFollow the instructions below to regenerate summaries for a profile.

1. Open the command prompt.

2. Change to the NetInsight program directory.

3. To regenerate the summaries for a specific profile, execute:

nettracker short_profile_name -regen

The term short_profile_name refers to the profile name that appears in parentheses in theAvailable profiles list in the Profile Manager. You can also display a list of the short profilenames by executing:

How to regenerate summaries for a profile

33

nettracker admin -list

How to configure the cookie lookup exampleThe data conduit example in this section replaces customers' cookie IDs with their names, addresses,telephone numbers, and e-mail addresses from a table in a database. This information appears on theCookie Summary.

Your Web server must be generating visitor identification cookies that NetInsight can use forsessionization before they can be replaced with visitor data. You can use the Unica Web ServerPlug-in to allow your Web server to generate and log visitor identification cookies.

The following figure shows how a portion of the data would appear on the summary before the dataconduit is configured. Note that the first column displays customer cookie IDs.

The following figure shows how a portion of the data would appear on the summary after the dataconduit is configured. Note that the cookie IDs in the first column have been replaced with the names,addresses, telephone numbers, and e-mail addresses pulled from an external customer database.

1. Create a database that contains your customers' names, addresses, telephone numbers, and e-mailaddresses entered into a lookup table.

The database table must contain a key column with the cookie values for each customer.

The following screen shows an example of data entered into a Microsoft Access database table.



Note that this sample database contains a key column with the Web site cookie values for eachcustomer in addition to the contact information and CustomerID. When visitors complete anonline form on the Web site, the data they enter is captured in the database as well as theirpersistent, unique cookie. (Your Web site will need to be configured to capture the data.)NetInsight will identify a returning visitor by that cookie in future, repeat visits. The data conduitwill use the cookie to retrieve the correct customer record from the database table for each cookieon the NetInsight side.

To configure and test the data conduit, you can manually enter your customer data into thedatabase; however, for long-term use, you should configure your Web site to automaticallycapture the data. For help, contact your Web site administrator.

2. Install the data conduit into your NetInsight program directory (the default program directory isC:\Program Files\NetInsight).

3. In NetInsight, view the profile in which you want to look up cookie data.

4. Turn the Cookie Summary on. To turn the summary on:

a. Click the Options tab.

b. In the left-hand panel, under Main, click Summaries.

c. Select the Cookie Summary in the list of available summaries and then click Add report.

d. Click Save Options and then click Continue.

e. Click Update (the left-most icon in the group of icons).

How to configure the cookie lookup example

35


6. In the left-hand panel, under Dynamic Content, click Data Conduits .

7. Click Add.

8. Configure the data conduit options.

In this example, you would set the options on a Windows system as shown.


10. Click Update (the left-most icon in the group).

11. Set the necessary environment variables in NetInsight.

12. In a text editor, open ntdiodbc.conf.

13. Configure the ConnectString connection directive the data conduit needs to connect to thedatabase.

An example for Windows is shown:ConnectString DRIVER={SQLServer};UID=jane;PWD=a0s9d8;SERVER=server1;

DATABASE=testdb1;

14. Configure the cookie lookup directives.

An example is shown. (This example is wrapped for readability; each directive should appear inthe data conduit's configuration file on a single line.)CookieDataSource SELECT SUBSTRING(FirstName,1,1),LastName, City, State, HomePhone,

EMail, SUBSTRING(LastName,1,1) FROMreports_CustomerID WHERE



Cookie = '%VALUE%'CookieDataFormatHTML <a class="dataTableRows"href="/SampleCustomerAccount.asp?fn=%FIELD1%&ln=%FIELD2%&c=%FIELD3%&s=%FIELD4%&p=%FIELD5%&e=

%FIELD6%">%FIELD1%.%FIELD2%</a> %FIELD7%J-%FIELD2% Inc.,

%FIELD3%,%FIELD4% Tel. %FIELD5%E-mail: %FIELD6%CookieDataFormatRTF %FIELD1%. %FIELD2%\line%FIELD7%J-%FIELD2% Inc., %FIELD3%,

%FIELD4%\line Tel. %FIELD5%\line E-mail:%FIELD6%CookieDataFormatCSV %FIELD1%. %FIELD2% from %FIELD3%

15. Save your changes to ntdiodbc.conf.

16. Test the data conduit's configuration.

To test the configuration, open a command-line prompt and enter the correct usage. If the dataconduit and its configuration file are both in the current directory on a Windows system, anexample of the command-line usage would be:apitest.exe .\ntdiodbc.dll .\ntdiodbc.conf cookie24.123.154.115-999914303691

If the cookie lookup is successful, the customer's name, address, telephone number, and e-mailaddress will appear. (If the cookie lookup is unsuccessful, an error message will appear. Toresolve the error, check your settings for the connection directive and cookie lookup directives inntdiodbc.conf.)

17. For the data from the data conduit to appear on the Cookie Summary, you must regenerate theprofile (Page 33) .

18. Display the Cookie Summary in NetInsight by selecting the summary in the Visitor Analysiscategory on the Reports tab.

How to configure the cookie lookup example

37



AAuthenticationDataSource

about, 18

Ddata conduit

AuthenticationDataSource, 18debug directive, 18introduction, 5unloadme directive, 19user authentication directive, 18user information directive, 17using user authentication directive, 27using user information directive, 28

debug directive, 18

EEmailDataSource

about, 17

Uunloadme directive, 19user authentication directive

about, 18using, 27

user information directiveabout, 17using, 28

Index

Documents

Unica Web Analytics - Genemco Inc