Lists Overview
Lists let you import data into Angelfish that isn't present in your log files. Lists are used in Lookup Table Filters and in Usage Costs reports (as Username Lists).
Each List gets its data from a List File: an ASCII text file which contains a #ListFields: header and one or more rows of data.
When used in a Lookup Table Filter, a List lets you customize report data. For example:
- Add GeoLocation information to your Intranet Profiles, based on IP Address or Username
- Hide Marketing Variables (External or Internal) with an id, populate during processing
- Include | Exclude groups of Usernames, IP Addresses, Organizations, or any other Dimension
- Add Page Titles to Profiles that use a log-based Tracking Method
- Attach data that will be used in a visualization tool
There are lots of other use cases for Lists - if you have questions, please open a support ticket.
List Terms
LIST FILE
Each List is populated by a List File:
- An ASCII text file, ending in .txt, .tsv, or .csv
- #ListFields: header in the first line of the file
- One or more rows of data
If the file contains other commented lines (starting with #), Angelfish will ignore them when ingesting the List File.
You can use RegEx in the data rows, which is handy when matching ranges like IP Address network IDs.
List Files can be manually uploaded from your client, local to the Angelfish Server, or accessed via a remote share (UNC, SFTP, FTP). List Files can also be automatically updated via a schedule.
#LISTFIELDS: HEADER
The #ListFields: header specifies the name and position of each field in the List File. It's conceptually similar to the #Fields: header in the W3C Log Format.
The rows of data in the List File need to match the format specified in the #ListFields: header. You can encapsulate fields in quotes or use different characters for the field delimiter, as long as the data rows match the format.
When used in a Lookup Table Filter, the first field is used as the Match Pattern. If the Filter's Action = Overwrite, the additional fields will be overwritten with the values from the matched row.
Here's an example of a #ListFields: header used in a List for a GeoLocation Lookup Table Filter:
#ListFields:ipaddress,countrycode,statecode,city,organizationHelp Article: List File Field Reference
Use Cases
USERNAME LIST (for Usage Costs Reports)
A Username List needs a simple #ListFields: header, and one Username per row:
#ListFields:usernamealfa
bravocharliedelta
Once the List is created, add it to the Profile in the Usage Costs tab. The List must be in the same Collection as the Profile.
Be sure to check the "Available to Usage Costs" checkbox in the List config settings.
GEOLOCATION LOOKUP TABLE
At most organizations, internal clients use Private IP addresses. Private IP space doesn't have GeoLocation info.
However...you can populate the GeoLocation reports with a Lookup Table Filter, based on IP Address or Username.
Here's how:
- Create List
- Create Lookup Table Filter
- Add it to the Profile
- Process data
The Lookup Table Filter should be applied at Filter Level: Session and use Action: Overwrite.
Example List File:
#ListFields:ipaddress,countrycode,statecode,city,organization^10\.60\.,GB,H9,london,global-finance^10\.70\.,CA,BC,vancouver,northamerica-sales^10\.80\.,JP,40,tokyo,asia-operationsYou must use codes for Country and State/Region, not the actual names. Use the GeoLocation Builder to create data rows with these codes.
Handy Tool: GeoLocation Builder