Skip to main content

Badge Swipe Data Requirements

Eptura Knowledge Center

Badge Swipe Data Requirements

This section outlines details around how Badge Swipe data is gathered and processed.

There are three key pieces of information required by the Badge Swipe module:

  • Building
  • Date
  • Person (Employee# and/or Full Name and/or Card#)

All access types (e.g. entry, exit, passback) must be provided (i.e. do not filter on entry records only). This is due to the fact that entry/exit records may span days, and/or some entry records may be missing due to tailgating or other anomalies.

File Format

Badge Swipe files, commonly referred to as "activity data", are commonly generated by third-party security staff who use a dedicated computer to run a report from their access card system. They run this report for a given date range and then save it to disk. From here they will copy the file to another server from where it can be uploaded using Serraview's File Upload tool located on the Landing Page.

The preferred file format is Comma Separated Values (.csv) or plain text (.txt). Serraview can process Excel and PDF files, however, they are not recommended. Serraview will not accept any other binary format.

For example, Cardax uses the following data format:

1/01/2016 6:30:00 PM,"Card Event","Door Access Granted","Citizen, John was granted entry ...","Card number (31492)"

File Naming Convention

Ideally, each building will have its own file that contains the access card data for a given date range. Each file name will match the building and all files are placed in a single zip file. Both the individual building files and the zip file should also indicate the month/year the data relates to.

Activity Data Frequency

We recommend you send the previous month's data in the first few business days of the following month.

Identify Buildings

If your Badge Swipe data relates to multiple buildings, then a spreadsheet must be provided to Serraview that maps your building codes to building names as they are displayed in the Serraview. For example, 385BSM will map to 385 Bourke Street Melbourne.

Identify People

If your Badge Swipe system records employee numbers against security card numbers, then we recommend this information be provided (either embedded in the activity data or as a separate spreadsheet). Alternatively, if this information is being collected as part of another activity (e.g. churn sheets with a Security# column) Serraview can work with you to collate and extract this information.

CardNo and EmployeeNo Match

When a Badge Swipe file is imported each unique CardNo and CardName is matched to an EmployeeNo in the following priority order:

If the Badge Swipe system records a unique staff identifier against each card this is used. For example, Cardax can produce both an activity report and a card holder report that lists each CardNo and its associated StaffID (in Serraview this is referred to as 'EmployeeNo'). Other systems have the StaffID in the activity data.

  1. If the CardNo matches one stored against a person's CardNo custom field, then the CardName is ignored and the assigned EmployeeNo is used. This is a handy way of overriding an incorrect match from the following steps.
  2. If the CardName exactly matches the name of someone located in the same building (based on VBS location) then this is used.
  3. If the CardName exactly matches the name of anyone else, regardless of their location, then this is used.
  4. If the CardName contains a keyword (e.g. "Visitor", "Cleaner", "Contractor", etc.) then the card is assigned to a generic "visitor" user.
  5. If the Card Name is 95% similar to another name (using a name matching algorithm) then the name is matched to the name that is most similar.
  6. If none of the above are true, then the CardNo is matched to a generic "unknown" user.

In the above steps a single "name" can be matched in any one of four forms:

  1. LastName and FirstName
  2. FirstName and LastName
  3. LastName and PreferredName (if PreferredName provided in people data)
  4. PreferredName and LastName (if PreferredName provided in people data)

If you want to check for unidentified people (represented by a CardNo and "unknown" user), you can run the 231 Badge Swipe Card Audit Report and provide it to the business' security team. They can use the data to correct the unknown card numbers in their system, improving the accuracy of the next data load. Refer to 231 Badge Swipe Card Audit Report.

Field Summary

The table below displays the types of field data processes.

Field

Required?

Comment

Date

Yes

Must include day, month, and year.

Date2

Optional

Some systems include both an entry and exit date on the same row.

Time

Optional

Optional Must include hours and minutes. Often included in the date field.

Time2

Optional

Optional Some systems include both an entry and exit time on the same row.

Event

Optional

Optional Text describing what the date/time relate to (e.g. Entry Granted)

Event2

Optional

Optional Text describing what the date2 / time2 relate to (e.g. Exit Granted)

Card#

Recommended

Informational, displays on many reports.

Name

Yes

This is the employee name. This is what we match on if the Employee# is not provided or is not valid. This is often referred to as 'CardName'.

Location

Optional

Text that associates the activity row with a specific floor and/or zone.

Employee#

Recommended

Reduces or eliminates dependency on name matching (which increases accuracy).

Sample Data and Analysis

Before commencing a full implementation Serraview will require a sample set of activity data from each different badge swipe system in use.

You will need to obtain the following:

  • One complete weekday of activity data.
  • For one building that is in Serraview.
  • For each different badge swipe system.

This is sensitive information so do not email it to us, refer to Upload Sample Data below.

Card Numbers and Employees Mapping File

If you can provide a file that maps the access card numbers to specific employees (typically via an Employee# or LAN ID) then use the File Upload to securely upload it to Serraview. This file will be used to improve the confidence (a measure of how well Serraview has 'matched' activity data to specific employees) will be significantly improved.

Upload Sample Data

After the required sample data has been collected you will need to securely upload it via the File Upload.

Make sure you have a Serraview user with the General - Can Upload Files and File Upload - Badge Swipe secured actions.

From Serraview, complete the following.

  1. Navigate to Admin Settings > Data Imports.
  2. Select File Upload.
  3. From the Select a Category drop-down, select Badge / Speedgate.
  4. Click the Add files... button.
  5. Select the file(s) to upload.
  6. Click the Start upload button.

Serraview Analysis

After receiving your sample data Serraview will analyze it for reporting suitability.

If no card# to employee# mapping has been provided to Serraview we aim to achieve 80%+ confidence using a range of name matching algorithms. The results are totally dependent on the quality of the data entry (e.g. how accurately building security has entered first and last names, and/or how well maintained this information is). It is during this initial analysis that Serraview determines how best to 'clean' the data and what algorithms best match card names to actual employees. An import preprocessor must be written for each Badge Swipe system in use (and potentially individual buildings if site specific data issues arise).