AUDITING THE FACTORYTALK HISTORIAN SE SERVER

Rockwell Automation Publication HSEPISA-RM031A-EN-ESeptember 2013

Supersedes Publication HSEPISA-RM030A-EN-E

Contacting Rockwell

Customer Support Telephone 1.440.646.3434

Online Support http://www.rockwellautomation.com/support/overview.page

Copyright Notice

2013 Rockwell Automation, Inc. All rights reserved. Printed in the USA.
This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation,
Inc. Any reproduction and/or distribution without prior written consent from Rockwell Automation, Inc. is
strictly prohibited. Please refer to the license agreement for details.

Trademark Notices

FactoryTalk, FactoryTalk Historian Machine Edition (ME), FactoryTalk Historian Site Edition (SE), FactoryTalk
Live Data, FactoryTalk Services Platform, FactoryTalk VantagePoint, FactoryTalk View, FactoryTalk ViewStudio,
Rockwell, Rockwell Automation, Rockwell Software, RSView, RSView Machine Edition, RSView ME Station,
RSView Studio, and RSLinx Enterprise are trademarks of Rockwell Automation, Inc.
Any Rockwell Automation logo, software or hardware not mentioned herein is also a trademark, registered or
otherwise, of Rockwell Automation, Inc.
For a complete list of products and their respective trademarks, go to
http://www.rockwellautomation.com/rockwellautomation/legal-notices/overview.page?%23tab4#/tab4.

Other Trademarks

ActiveX, Microsoft, Microsoft Access, SQL Server, Visual Basic, Visual C++, Visual SourceSafe, Windows,
Windows ME, Windows NT, Windows 2000, Windows Server-, Windows XP, Windows 7, and Vista are either
registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Adobe, Acrobat, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in
the United States and/or other countries.
ControlNet is a registered trademark of ControlNet International.
DeviceNet is a trademark of the Open DeviceNet Vendor Association, Inc. (ODVA)
OLE for Process Control (OPC) is a registered trademark of the OPC Foundation.
Oracle, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation.
All other trademarks are the property of their respective holders and are hereby acknowledged.

Warranty

This product is warranted in accordance with the product license. The products performance may be affected
by system configuration, the application being performed, operator control, maintenance, and other related
factors. Rockwell Automation is not responsible for these intervening factors. The instructions in this
document do not cover all the details or variations in the equipment, procedure, or process described, nor do
they provide directions for meeting every possible contingency during installation, operation, or
maintenance. This products implementation may vary among users.
This document is current as of the time of release of the product; however, the accompanying software may
have changed since the release. Rockwell Automation, Inc. reserves the right to change any information
contained in this document or the software at any time without prior notice. It is your responsibility to obtain
the most current information available from Rockwell when installing or using this product.

Table of Contents
The Historian Audit Database ....................................................................................................... 1
Principles of Operation ....................................................................................................... 1
Maintenance Procedures for the Historian Audit Database ............................................... 1
Edit Historian Server Tuning Parameters ................................................................ 2
Use Historian AuditViewer to Manage Historian Audit Records .............................. 2
Enable Auditing ........................................................................................................ 4
Disable Auditing ....................................................................................................... 4
Specify Tuning Parameters for Audit File Shift ........................................................ 5
AuditMaxKBytes Tuning Parameter............................................................ 5
AuditMaxRecords Tuning Parameter.......................................................... 5
Create New Audit Database Files............................................................................ 5
Closing Audit Database Files for Maintenance........................................... 6
Close Audit Database Files
6
Re-open Audit Database Files
6
Replace Audit Database Files .................................................................... 7
Audit Database File Contents ............................................................................................ 7
Audit Record Definition ............................................................................................ 7
Change Record Definition ........................................................................................ 8
Example Audit Records ...................................................................................................... 8
Historian Points ........................................................................................................ 8
Create ......................................................................................................... 8
Delete .......................................................................................................... 9
Edit .............................................................................................................. 9
Historian Archive .................................................................................................... 10
Remove Archive Event ............................................................................. 10
Edit ............................................................................................................ 11
Module Database and Batch Database ................................................................. 11
Modules .................................................................................................... 12
Module Hierarchy ...................................................................................... 12
Historian Properties .................................................................................. 12
Historian Batches ...................................................................................... 13
Historian Unit Batches .............................................................................. 13
Audit Records Suppressed when End Time is Not Set ............................13
Reference ......................................................................................................................... 13
EnableAudit Tuning Parameter .............................................................................. 13
Audit Database File Open Failure.......................................................................... 15
Historian Snapshot Subsystem Considerations ....................................................15
Data Buffering and the Audit Database ....................................................15
Historian Snapshot Audit Database Exceptions .......................................16
The -xa Option for the pidiag Utility ....................................................................... 16
Export Procedure ...................................................................................... 16
Optional Arguments .................................................................................. 16
Auditing the FactoryTalk Historian SE Server

iii

Table of Contents

Time Range
Unique Audit Record ID
Audit Database Mask
Schema

16
17
17
17

Configuring Audit Logging .......................................................................................................... 19

Enabling Audit Logging .................................................................................................... 19
Content of Audit Log Messages for Archive and Snapshot Changes ..............................19
Content of Audit Log Messages for Historian Batch Database/SDK Object Changes ....20

iv

Chapter 1

The Historian Audit Database

The Historian Audit Database records the data that is added, edited, or removed from specific
Historian Server database files, as well as other events or changes to configuration that occur
in the Historian Server. The Historian Audit Database satisfies FDA Title 21 CFR Part 11
auditing requirements.
In addition to the methods described in this guide that you can use to store, export, and
review audit records, Rockwell Automation provides the Historian AuditViewer (page 2)
utility, which enables you to view and manage Audit Database records. Historian
AuditViewer is available as a separate package with its own documentation.

Principles of Operation
The Historian Audit Database contains records of changes made to Historian Server data. The
following changes are recorded:

Editing and deleting time-series data, such as values in the Historian Archive.

Creating, deleting, and editing configuration information on time-series data. Examples

include Historian point configuration data and access permissions for secure objects
within the Historian Server.

The Historian Audit Database consists of three distinct files. Each file represents a Historian
Subsystem:

Base Subsystem: pibasessAudit.dat

Archive Subsystem: piarchssAudit.dat

Snapshot Subsystem: pisnapssAudit.dat

All files for the online Audit Database are stored in the PI\log directory of the Historian
Server.
For more information on the structure of the Audit Database, see Audit Database File
Contents (page 7).

Maintenance Procedures for the Historian Audit Database

This section describes the following maintenance procedures for the Historian Audit
Database:

Edit Historian Server Tuning Parameters (page 2)

Auditing the FactoryTalk Historian SE Server

The Historian Audit Database

Use Historian AuditViewer to Manage Audit Records (page 2)

Enable Auditing (page 4)

Disable Auditing (page 4)

Specify Tuning Parameters for Audit File Shift (page 5)

Create New Audit Database Files (page 5)

Edit Historian Server Tuning Parameters

Some Audit Database maintenance procedures require editing of Historian Server tuning
parameters. To edit tuning parameters, follow these steps:
1. Click Start > Programs > Rockwell Software > FactoryTalk Historian SE > System
Management Tools.
2. On the System Management pane on the left, expand the Operation entry, and then
select Tuning Parameters.
3. Select the General tab.
4. Double-click the tuning parameter that you want to change. You see a dialog for the
tuning parameter.
5. Enter your edits onto the dialog.
6. Click Apply.
7. Click OK to close the dialog.
Note: On Historian Server 3.x, you need read/write access to the PITUNING entry in the
Database Security editor (Security > Database Security) to edit tuning
parameters. For earlier versions of the Historian Server, read/write access to the
DBSECURITY entry is required.

Use Historian AuditViewer to Manage Historian Audit Records

Historian AuditViewer is a Microsoft Windows-based application that allows you to view
records from the Audit Database, select them, examine them, print them, or export them to a
new file.

Maintenance Procedures for the Historian Audit Database

Note: Historian AuditViewer satisfies the Title 21 CFR Part 11 FDA regulatory
requirements for generating accurate and complete copies of Audit Records in
both human-readable and electronic form suitable for inspection, review, and
copy.

Historian AuditViewer allows you to search for and view audit records in the Historian
Audit Database. It is an essential tool for analyzing and validating a FactoryTalk Historian
System for compliance with an implementation of cGMP. It facilitates the generation of
selected reports in Windows file formats, to comply with FDA audit requests.
Because AuditViewer can change auditing status and control the execution of FactoryTalk
Historian System processes, certain restrictions are in place:

AuditViewer must run on the same computer as the Historian Server.

The user must be a member of the Windows Administrator User Group.

For FactoryTalk Historian 3.0 and later, the user must have read access to the PIAUDIT
entry in the Historian DBSecurity table and read/write access to the PITUNING entry.
For earlier versions of the Historian Server, the user must log on to the Historian Server
as the piadmin user.

Note: Earlier versions of Historian AuditViewer are not compatible with Historian
Server 2.x.

Auditing the FactoryTalk Historian SE Server

The Historian Audit Database

Enable Auditing
Caution: If the Historian Server is installed on Microsoft Cluster Services (MSCS), do
not use Historian AuditViewer to enable auditing. Historian AuditViewer
automatically restarts the Base, Archive, and Snapshot Subsystems when it
enables auditing, which might trigger failover to the other cluster node. On
clustered systems, use SMT to change the EnableAudit tuning parameter to 0,
and then restart the subsystems manually using the cluster administration tool for
your operating system: Microsoft Cluster Administrator for Windows 2000 and
2003, or Failover Cluster Administrator for Windows 2008.

Historian Server auditing is disabled by default. To enable Historian Server auditing, follow
these steps:
1. Start Historian AuditViewer: Click Start > All Programs > Rockwell Software >
FactoryTalk Historian SE > Historian AuditViewer.
2. If auditing is disabled, you see the following dialog:

Click Yes to enable auditing.

Note: When you enable auditing, Historian AuditViewer changes the value of the
EnableAudit tuning parameter from 0 to -1. On Historian Server versions 3.0 and
later, you need read/write access to the PITUNING entry in the Database Security
tool in SMT (Security > Database Security) to edit tuning parameters. For earlier
versions of the Historian Server, you need read/write access to the DBSECURITY
entry.

Disable Auditing
To disable auditing, use SMT to set the EnableAudit tuning parameter (page 2) to its default
value of 0. You must restart the Base, Archive, and Snapshot Subsystems for changes to take
effect.
Note: You can enable or disable auditing for individual Historian Server subsystems or
Historian Server databases by specifying a different value for EnableAudit. For
details, see EnableAudit Tuning Parameter (page 13).

Maintenance Procedures for the Historian Audit Database

Specify Tuning Parameters for Audit File Shift

Over time, Audit Database files can grow large, which can cause performance problems when
the files are re-opened after viewing or other maintenance operations. You can configure the
maximum size of your audit files based on audit file size, number of audit records, or both.
When an audit file reaches the maximum size setting, the Historian Server automatically
closes the audit file, appends the date and time to the name of the file, and opens a new file.
This is called an audit file shift.
Use the following tuning parameters to control audit file shifts:

AuditMaxKBytes

AuditMaxRecords

Use SMT to edit (page 2) these parameters.

Note: Audit file shift parameters are not available for Historian Server 2.x. For these
versions of the Historian Server, you must periodically create new audit database
files (page 5).

AuditMaxKBytes Tuning Parameter

This parameter causes the Historian Server to perform an audit file shift when the size of the
audit file in KB exceeds the parameter value. The default AuditMaxKBytes setting is
256000.
To disable audit file shifts based on file size, set AuditMaxKBytes=0.
AuditMaxRecords Tuning Parameter
This parameter causes the Historian Server to perform an audit file shift when the number of
audit records exceeds the parameter value. Set AuditMaxRecords to a non-zero value that
corresponds to the number of audit records.
To disable audit file shifts based on file size, set AuditMaxRecords to its default value of 0.

Create New Audit Database Files

FactoryTalk Historian 2.x automatically perform an audit file shift (page 5) based on the
values that you set for the tuning parameters AuditMaxKBytes and AuditMaxRecords. If
you are using an earlier version of Historian Server, or choose not to shift audit files
automatically, use the procedures in this section to periodically remove, safely store, and
create new Audit Database files.
Rockwell Automation recommends that you create Audit Database files for all the Archive,
Base, and Snapshot Subsystems simultaneously, so that you can maintain complete audit
records for a specific time period.

Auditing the FactoryTalk Historian SE Server

The Historian Audit Database

Closing Audit Database Files for Maintenance

The three Audit Database files and the records within them cannot be accessed except by the
associated Historian Server subsystem. To access these files to perform maintenance
activities, you must close the database files. The Audit Database files can remain closed for
limited periods, after which they automatically are re-opened. To change this time period,
change the value of the audit file shift tuning parameter for the associated subsystem:
Historian Subsystem

Tuning Parameter

Default

Snapshot

pisnapss_AuditBackupTimeout

5 minutes

Archive

piarchss_AuditBackupTimeout

60 minutes

Base

pibasess_AuditBackupTimeout

60 minutes

While an Audit Database file is closed, the associated subsystem accepts new, edited, and
deletion requests and caches them for the Audit Database. When the database file is reopened, the cache is processed and audit records are written to the Audit Database. Caching
activity is written to the Message Log.
Several FactoryTalk Historian System features are unavailable when the Audit Database files
are closed. For example, you cannot create or edit points. To copy, delete, export, or move an
Audit Database file, you must close the file, perform the required activity, and then promptly
re-open the file. The schedule for removing and creating new Audit Database files depends
on the frequency and number of audit records that are created. For example, AutoPointSynch
(APS) modifies a property of a module to indicate the latest scan, which results in two audit
records. If APS scans every five minutes, then hundreds of audit records are generated every
day.
Note: On Historian Server 2 and later, it is not necessary to close audit files for backup.

Close Audit Database Files

To close the Audit Database files, follow these steps:
1. Open a Command Prompt window: Click Start > Run, type cmd, and then click OK.
2. Navigate to the directory PI\adm.
3. Enter the following at the command prompt:
piartool -systembackup start -subsystem piarchss
piartool -systembackup start -subsystem pisnapss
piartool -systembackup start -subsystem pibasess

Re-open Audit Database Files

To re-open Audit Database files, follow these steps:
1. Open a Command Prompt window: Click Start > Run, type cmd, and then click OK.
2. Navigate to the directory PI\adm.
3. Enter the following at the command prompt:
piartool -systembackup end -subsystem piarchss

Audit Database File Contents

piartool -systembackup end -subsystem pisnapss

piartool -systembackup end -subsystem pibasess

Replace Audit Database Files

To replace Audit Database files, follow these steps:
1. Close Audit Database files (page 6).
2. Copy the Audit Database files from the PI\log directory to a safe location. Because
storage of the file may be part of site validation, take care to ensure safe and accountable
storage.
For example, to copy the files to a directory named PI\MyAuditFiles, enter these
commands:
copy ..\log\pibasessAudit.dat ..\MyAuditFiles
copy ..\log\piarchssAudit.dat ..\MyAuditFiles
copy ..\log\pisnapssAudit.dat ..\MyAuditFiles

3. Delete the original Audit Database files from the PI\log directory. For example:
del ..\log\pibasessAudit.dat
del ..\log\piarchssAudit.dat
del ..\log\pisnapssAudit.dat

4. Re-open Audit Database files (page 6). The Historian Server automatically creates new
audit files in the PI\log directory.

Audit Database File Contents

Each Audit Database file is comprised of a header followed by the audit records. The header
states file path and name used during creation, the creation date, and EnableAudit mask
value. An audit record is created for each of the action types: Add, Edit, and Remove. On Add
or Remove, the record contains the entire object definition. On Edit, only the changes appear.
Each database that supports auditing utilizes a general audit record format. The following are
table views of the generalized audit record.

Audit Record Definition

Field

Description

PIUser

User who made the change. Exception: In audit records from the PI Archive
subsystem, ID=0.
For FactoryTalk Historian 3.0 and later with Windows authentication, the name
of the Windows user who made the change.

PITime

Time and date of the change

Database

Database affected by the change.

Action

Change action: Add, Remove, or Edit

Auditing the FactoryTalk Historian SE Server

The Historian Audit Database

Field

Description

AuditRecordID

Unique ID assigned to the audit record

Name

Affected Record Name

ID

Affected Record ID

Changes

Table of specific changes. On Add and Remove, the change indicates each
attribute setting. On Edit, the change shows the before and after value of
changed attributes.

Change Record Definition

Field

Description

Property

Property that was edited

Before

Value before edit

After

Value after edit

On Adds, the current property setting is shown in the After field. The Before field is empty.
On Removes, each property is shown in the Before field. The After field is empty.

Example Audit Records

The following sections show examples of audit records for selected Historian Server
databases.
Note: The examples in this section assume that the Historian Server has been
configured to use FactoryTalk Historian 3.0 security settings, in which user
accounts in Windows are mapped to PI Identities. For these servers the Windows
user name displays in the PI Username field. For more information, see
Configuring FT Historian SE Server Security.

Historian Points
Create
The following table shows the audit record that results when a user called OSI\jsmith creates
a point called NewPoint:

Date

FactoryTalk
Historian
database

DB
RecordID

DB
RecordName

PI Username

Action

2009-09-27
16:37:3107:00

PIPoints

14

NewPoint

OSI\jsmith

Add

Example Audit Records

Changes
Property

Before

After

PointClass

null

classic

Compdev

null

2.0

Compmax

null

28800

Delete
The following table shows the audit record that results when a user called OSI\jsmith deletes
a point called NewPoint:
Date

FactoryTalk
Historian
database

DB
RecordID

DB
RecordName

PI Username

Action

2009-09-27
16:39:0607:00

PIPoints

14

NewPoint

OSI\jsmith

Remove

Changes
Property

Before

After

PointClass

classic

null

Compdev

2.0

null

Compmax

28800

null

Edit
The following table shows the audit record that results when a PI user called OSI\jsmith
modifies the compression specifications of the point with an ID of 9.
Date

FactoryTalk
Historian
database

DB
RecordID

DB
RecordName

PI UserName

Action

13:00:00
11-Oct-01

PIPoints

Ba:temp.1

OSI\jsmith

Edit

Changes
Property

Before

After

Compmin

10

Compdev

2.0

1.25

Compmax

5000

6000

Auditing the FactoryTalk Historian SE Server

The Historian Audit Database

Historian Archive
Attempts to modify the Historian Archive are posted by the Snapshot Subsystem. The
Snapshot Subsystem performs some validation. On successful validation, it creates an audit
record indicating it is a removal attempt or an edit attempt.
The attempt is then forwarded to the Archive Subsystem for completion. If the modification
is successful, the Archive Subsystem creates a corresponding audit record.
Remove Archive Event
When an event is removed from the Archive, passing the value is optional. If it is passed, it is
displayed in the Snapshot audit record.
The user is identified through the Snapshot audit record but is shown as 0 in the Archive audit
record.
The following show examples of audit records generated by the Historian Snapshot
Subsystem and Historian Archive Subsystem when an event is deleted from the Archive:
Removal: Historian Snapshot Subsystem
Date

FactoryTalk
Historian
database

DB
RecordID

TimeStamp

PI UserName

Action

2009-09-25
11:59:2807:00

PIArchive

2009-09-25
11:41:25-07:00

OSI\jsmith

Remove
Attempt

Changes
Property

Before

After

Value

Null or value
(128.2149)

Null

Removal: Historian Archive Subsystem

Date

FactoryTalk
Historian
database

DB
RecordID

TimeStamp

PI UserName

Action

2009-09-25
11:59:2807:00

PIArchive

2009-09-25
11:41:25-07:00

Remove

Changes

10

Property

Before

After

Value

128.2149

Null

Example Audit Records

Edit
For an Edit call, the Before value is not displayed in the Historian Snapshot Subsystem audit
record. The corresponding archive record does pass and displays the old value. The user
name is displayed only in the Snapshot record. User ID is shown as 0 in the Archive audit
record.
The following are the audit records generated by the Historian Snapshot Subsystem and the
Historian Archive Subsystem when an event is edited in the Archive:
Edit: Historian Snapshot Subsystem
Date

FactoryTalk
Historian
database

DB
RecordID

TimeStamp

PI UserName

Action

2009-09-25
11:58:5607:00

PIArchive

2009-09-25
11:23:2507:00

OSI\jsmith

Edit
Attempt

Changes
Property

Before

After

Value

Null

159

Edit: Historian Archive Subsystem

Date

FactoryTalk
Historian
database

DB
RecordID

TimeStamp

PI UserName

Action

2009-09-25
11:58:5607:00

PIArchive

2009-09-25
11:58:56-07:00

Edit

Changes
Property

Before

After

Value

150

159

Flags

Null

Flags has changed from empty to S. S is the Substituted flag that Historian Server sets when
an event is edited.

Module Database and Batch Database

The Module Database and Batch Database objects pose a more difficult auditing issue. For
the most part, audit records are similar to the examples for the other databases.

Auditing the FactoryTalk Historian SE Server

11

The Historian Audit Database

Modules
A module is an array of module values. Modules support change over time. Each module
value represents the module that was in effect for a given time period. Therefore, a module
audit record is actually a module value change record.
A module value is uniquely identified by the module unique ID and the module effective
date. This is different from most audit records that require only the record ID for unique
identification. For example, the Point Database needs only the Point ID to identify the record.
The following is an example of a module record identification. It consists of the unique ID,
effective date, and name:
UniqueID="e9f0a8cb-bb08-44b5-8b50-899a8813d09e, 31-Dec-69
16:00:01" Name="Child Module 01"

Module Hierarchy
Modules are hierarchical. A module may have parent modules and child modules. Although,
inserting a module into a parent module is effectively an edit of both parent and child module,
the Audit Database only shows this modification as a change to the parent.
Child modules are inserted into a specific value of the parent. This is an explicit edit of a
module value. The parent references of a child are not assigned to a specific value. All
module values that represent this child implicitly acquire the link to the parent. Since it is
implied a child module was edited and to avoid clutter and confusion in the Audit Database,
only the change to the parent is shown. The inserting of a child into a module is shown as a
change to the module's Children attribute.
The following represents the change to that attribute when adding a child. Notice the after
value has the additional unique ID of the child that was inserted.
PIModuleAttribute Name="Children"
Before=12e0e168-4ec6-499e-b6e3-271489893442
After=6895acf1-d177-4efd-a5fa-eeaf9c115bd9, 12e0e168-4ec6-499eb6e3-271489893442

Historian Properties
Historian Properties are hierarchical. Properties can have properties, which can have
properties, and so on. Since properties do not have unique identifiers, a rename is
indistinguishable from a deletion followed by an addition.
Adding a Historian Property is shown as an edit to the module by showing the parent
property to which the property was added. All modules have an implicit root property called
\\PIProperties.
The following are details of adding a root property with a value of 106.
PIProperty Name="Prop-106" ParentUNC_Name="\\PIProperties"
Value=106

Here are details of adding a sub-property to the above property.

PIProperty Name="Sub-Prop" ParentUNC_Name="\\PIProperties\Prop106"

12

Reference

Value=99

These examples focus only on the attribute that changed. The audit record contains
information that completely identifies the modified module. Also, renaming a property is
shown as a deletion followed by an addition in a single audit record.
Historian Batches
Historian Batch audit records are similar to Module audit records. PIProperties are handled
identically as Module properties. Inserting a PIUnitBatch is similar to inserting a child
module: the PIUnitBatches property shows the list of Unique IDs that represent the
PIUnitBatches. The reference to the PIUnitBatch gains to the PIBatch is also shown as an
edit to the PIUnitBatch.
Historian Unit Batches
PIUnitBatches only have one unique issue, which is showing changes to the PISubbatches
collection. This is handled similarly to PIProperties. Unlike PIProperties, however, subbatches are uniquely identified, so a rename is not the same as a deletion followed by an
addition.
Audit Records Suppressed when End Time is Not Set
Audit records are only generated for batches if the End Time is set. This prevents the
creation and modification of PIBatches, PIUnitBatches, and PITransferRecords through
automated processes such as Batch Event File Monitor (EVTintf) and the Historian Batch
Generator (PIBaGen). Automatic generation of audit records for each modification
indefinitely would quickly overwhelm the Audit Database.
Deletions of batches are an exception. All deletions create an audit record when auditing is
enabled.

Reference
EnableAudit Tuning Parameter
You can enable auditing on individual database tables. Auditing is controlled through the
EnableAudit tuning parameter. The value is a bitmask where each bit controls auditing to a
specific database. A bit value of 1 enables auditing for the corresponding database. The
following table lists the Historian Server databases and the controlling bitmask value in
hexadecimal and decimal format.
Database Table

Point

Subsystem

Historian Base

Digital State

Auditing the FactoryTalk Historian SE Server

Value
Hexadecimal

Decimal

0x1

0x2

13

The Historian Audit Database

Attribute Set (Point

database schema)

0x4

Point Class (Point

database schema)

0x10

16

User

0x20

32

Group

0x40

64

Trust

0x80

128

Modules

0x100

256

Headings and
HeadingSets

0x200

512

Server

0x4000

16384

Collective

0x8000

32768

Identity

0x10000

65536

Identity Mapping

0x20000

131072

Database Security

0x40000000

1073741824

0x400

1024

Campaign

0x800

2048

Batches

0x1000

4096

Unit Batches

0x2000

8192

Transfer Records

Historian Archive

Snapshot

Historian Snapshot

0x10000000

268435456

Archive

Historian Snapshot and

Historian Archive

0x30000000

536870912

0xFFFFFFFF

-1

All Databases

For example, to enable auditing for the Point Database (which has a bitmask value of 1) and
Digital State Table (which has a bitmask value of 2) set the EnableAudit parameter to 3 (= 1
+ 2.) Similarly, set the EnableAudit parameter to 131 (= 1 + 2 + 128) to enable Point, Digital
State, and Trust Table auditing.
Enter numeric values into the Timeout Table as decimal numbers. Hexadecimal (base 16)
notation is more convenient for creating or examining the bitmask value entered into the
EnableAudit parameter. It is easier to use hexadecimal notation to create the desired bitmask
and convert to decimal for entry into the Timeout Table. Conversely, it is easier to read a
decimal entry from the Timeout Table and convert to hexadecimal to interpret the value as a
bitmask.
To change the value of EnableAudit, use SMT as described in Edit Historian Server Tuning
Parameters (page 2).
Alternatively, use the piconfig utility. For example, enter the following commands in the
PI\adm directory to enable auditing on all databases:
piconfig
(Ls - ) Piconfig> @table pi_gen,pitimeout
* (Ls - PI_GEN) Piconfig> @mode create,t
* (Cr - PI_GEN) Piconfig> @istr name,value

14

Reference

* (Cr - PI_GEN) Piconfig> EnableAudit,-1

*> EnableAudit,-1
* (Cr - PI_GEN) Piconfig>

Changes to EnableAudit do not take effect until you restart the affected subsystem.

Audit Database File Open Failure

If an Audit Database file cannot be re-opened or created, the associated Historian Server
subsystem creates an alternate Audit Database file named
pisubsystemAudit~UTCSeconds.dat, where pisubsystem is the name of the
associated subsystem and UTCSeconds is the current time expressed in UTC seconds. For
example: pisnapssAudit~1003043789.dat.
The subsystem once again attempts to open or create pisubsystemAudit.dat. If this
fails again, a new file, using the same format above, is created and used for auditing.
Note: The pisubsystemAudit~UTCSeconds.dat files in the PI\log directory
contain valid audit records that are not included in the primary defined Audit
Database file. There is no merge function available. To maintain a complete audit
trail, you need to store and back up these alternate files.

To avoid creating alternate Audit Database files during Audit Database maintenance:
1. Close the audit files (page 6).
2. Immediately copy or move the audit files to a different directory.
3. Re-open the audit files (page 6).

Historian Snapshot Subsystem Considerations

Data Buffering and the Audit Database
If the Historian Snapshot Subsystem is not running, data from non-buffered API and PINet
nodes can be lost. However, because it plays a key role in preventing data loss, the Historian
Snapshot Subsystem buffers all events until they can be successfully written to the Historian
Archive Subsystem.
Likewise, when the Audit Database file for the Historian Snapshot Subsystem is closed, the
subsystem continues to accept new audit record values in an internal buffer. These records are
cached until the file is re-opened and the cached records are transferred to the Audit
Database.

Auditing the FactoryTalk Historian SE Server

15

The Historian Audit Database

Historian Snapshot Audit Database Exceptions

Only data that is replaced or changed is audited. However, some interfaces use editing
operations even when the data is new or unchanged. Such interfaces trigger the creation of
audit records.

The -xa Option for the pidiag Utility

The pidiag utility is a collection of tools for diagnostics, information, and simple repairs. You
can use the -xa option of pidiag to export Audit Database records to XML format text. The
exported XML text allows you to view and analyze records with applications such as
Microsoft Access, Microsoft Excel, or a Web browser.
For more information on pidiag, see the FT Historian Server SE Reference Guide.
Export Procedure
To export audit records from an Audit Database file to XML:
1. Close (page 6) the Audit Database file.
2. Copy the Audit File from the PI\log directory to another directory.
3. Re-open (page 6) the Audit Database file.
4. Use pidiag to export the Audit Database file.
The following is the minimum syntax, which exports all records in the specified file:
pidiag -xa AuditFilePath

For example:
pidiag -xa ..\temp\pibasessAudit.dat > ..\temp\BaseAudit.xml

Optional Arguments
Use the following arguments to control output.
Time Range
To constrain output to audit records during a time range, specify the start time and end time.
Use the -st and -et arguments to specify the time range in Historian Time Format. For details
on Historian Time Format, see the FT Historian Server SE Reference Guide.
The first audit record on or before the start time through the last record on or after the end
time is displayed. For example:
pidiag -xa ..\temp\pibasessAudit.dat -st "21-Feb-99 13:00:00" -et
"*"

This displays the first audit record on or before 1:00 PM, February 21, 1999, through the
current time.

16

Reference

Note: To avoid confusion in the command-line interpretation, enclose the time

arguments in double quotes (") as shown in the example.

Unique Audit Record ID

To specify an audit record to export, include the audit record ID. Start time and end time
options are ignored when you use this option. For example:
pidiag -xa ..\temp\pibasessAudit.dat -uid "1A027C7F-3B82-49928BBF-B20C2EA66FD1"

Audit Database Mask

To specify one or more Audit Databases to export to XML, use the pidiag -xa dbmask
mask option. See Enable Auditing (page 4) for a list of database mask values. The mask is a
decimal integer sum of the values corresponding to the databases to export. For example, the
mask for the User database is 32, and the mask for the Group database is 64. You can export
Audit records for these two databases by specifying a -dbmask value of 96:
pidiag -xa ..\temp\pibasessAudit.dat -dbmask 96

Schema
The exported XML includes a reference to URLs for XSD (XML Schema Definition) files.
The XSD files are a formal declaration of the schema. The schema describes and constrains
the content of the Audit Database output.
Rockwell Automation specifies the URL of a default Historian Audit Database schema that is
W3C-compliant. The default Rockwell Automation schema reference included in the
exported XML is:
<PIAudit xmlns="xml.rockwellautomation.com-schemas-piaudit"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="xml.rockwellautomation.com-schemas-piaudit
http://xml.rockwellautomation.com/Schemas/PIAudit">

In certain cases it may be advantageous to specify a different reference for a schema. For
example, an application running on a computer behind a firewall may not have access to XSD
files on the Internet.
The schema may be specified on the command line by the -xh export header option. The
schema specified replaces everything inside the PIAudit tag in the default PIAudit schema
reference. Specifying this argument has no other effect.
For example, use the following command to refer to the schema located at
http://xml.yourcompany.com/Schemas/PIAudit:
pidiag -xa ..\temp\pibasessAudit.dat -xh
"xmlns=\"xml.rockwellautomation.com-schemas-piaudit\"
xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
xsi:schemaLocation=\"xml.rockwellautomation.com-schemas-piaudit
http://xml.yourcompany.com/Schemas/PIAudit\""

Auditing the FactoryTalk Historian SE Server

17

The Historian Audit Database

Note: Double quote characters (") embedded in command-line parameters must be

preceded with a backslash (\)character.

18

Appendix A

Configuring Audit Logging

The Archive and Snapshot Subsystems can be configured to report audit information to the
Historian Server Message Log. This audit logging can be useful for testing and
troubleshooting or for other custom monitoring applications, but it is not a sufficient
alternative to the Historian Audit Database for compliance with regulations such as FDA
Title 21 CFR Part 11. Audit logging is independent of the Historian Audit Database and
does not interfere with its operation.
To monitor the Historian Server Message Log, use the SMT Message Log tool (Operation >
Message Logs). For details on managing and monitoring the Historian Server Message Log,
see the SMT help for the Message Log tool or the FT Historian SE System Management
Guide.
Note: To view the message logs on Historian Server versions 3.0 and later, you need
read permissions to the PIMSGSS entry in the Database Security tool in SMT
(Security > Database Security).

Enabling Audit Logging

To enable the Message Log audit trail, use the following tuning parameters:
Parameter

Tracked Actions

Notes

ArchiveEditLogging

Deletions and edits to

Historian Archive and
Historian Snapshot events

For changes to take effect, restart the

Archive and Snapshot Subsystems

BatchDbEditLogging

Changes and deletions in

PIBatch and PIUnitBatch

For changes to take effect, restart the

Archive Subsystem

These tuning parameters are not available in SMT by default; to enable logging, you must
add the parameters to the General tab in the Tuning Parameters tool (Operation > Tuning
Parameters).
To enable logging, add these entries to the list of tuning parameters. Set the value to 1 to
enable and 0 to disable.

Content of Audit Log Messages for Archive and Snapshot Changes

The audit log messages for changes to Archive and Snapshot events contain the following
information:
Auditing the FactoryTalk Historian SE Server

19

Configuring Audit Logging

Field

Description

Message source

The message source is Archive Edit

Edit date

Edit date

Edit type

Delete or Replace

Point ID

Point ID

Connection ID

Connection ID

User

Only in message from the Historian Snapshot

Subsystem

Event time

Edit time

New value

Only in message from the Historian Snapshot

Subsystem

Old value

Only in message from Historian Archive.

Content of Audit Log Messages for Historian Batch Database/SDK

Object Changes
The audit log messages for changes to Historian Batch Database objects contain the following
information:

20

Field

Description

Source

PIBatchDb Edit Always included

Edit Time

Always included

Edit type

Edit or Delete

Batch ID

Pre-edit Batch ID Always included

Unique ID

Always included

Start time

New and old, if changed

End time

Initial setting of the end time is not recorded.

Subsequent changes are recorded

Product

New and old, if changed

Recipe

This attribute only applies to PIBatch objects

ProcedureName

This attribute only applies to PIUnitBatch objects

Technical Support and Resources

Rockwell provides dedicated technical support internationally, 24 hours a day, 7 days a week.
You can read complete information about technical support options, and access all of the
following resources at the Rockwell Automation Support Web site:

http://www.rockwellautomation.com/support/

Before You Call or Write for Help

When you contact Rockwell Technical Support, please provide:

Product name, version, and/or build numbers

Computer platform (CPU type, operating system, and version number)

The time that the difficulty started

The message log(s) at that time

Help Desk and Telephone Support

Telephone support is available 24 hours a day, 7 days a week.

North America: 1-440-646-3434

Outside of North America: http://www.rockwellautomation.com/locations/

Knowledgebase
The KnowledgeBase provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers.

http://www.rockwellautomation.com/knowledgebase/

Find the Version and Build Numbers

To find version and build numbers for each Historian Server subsystem (which vary
depending on installed upgrades, updates or patches) use either of the following methods:
If you have System Management Tools (SMT) installed, choose Start > Programs > Rockwell
Software > FactoryTalk Historian SE > System Management Tools. In SMT, select the server
name, then under System Management Plug-Ins, open Operation > PI Version. The Version
tree lists all versions.
If you do not have SMT installed, open a command prompt, change to the pi\adm
directory, and enter piversion -v. To see individual version numbers for each

Rockwell Automation Support

Rockwell Automation provides technical information on the Web to assist you in using its products. At
http://www.rockwellautomation.com/support/, you can find technical manuals, a knowledge base of FAQs,
technical and application notes, sample code and links to software service packs, and a MySupport feature that
you can customize to make the best use of these tools.
For an additional level of technical phone support for installation, configuration, and troubleshooting, we offer
TechConnect support programs. For more information, contact your local distributor or Rockwell Automation
representative, or visit http://www.rockwellautomation.com/support/.

Installation Assistance
If you experience a problem within the first 24 hours of installation, review the information that is contained in
this manual. You can contact Customer Support for initial help in getting your product up and running.
United States or Canada
Outside United States or
Canada

1.440.646.3434
Use the Worldwide Locator at http://www.rockwellautomation.com/support/americas/phone_en.html, or contact your
local Rockwell Automation representative.

New Product Satisfaction Return

Rockwell Automation tests all of its products to ensure that they are fully operational when shipped from the
manufacturing facility. However, if your product is not functioning and needs to be returned, follow these
procedures.
United States
Outside United States

Contact your distributor. You must provide a Customer Support case number (call the phone number above to obtain
one) to your distributor to complete the return process.
Please contact your local Rockwell Automation representative for the return procedure.

Documentation Feedback
Your comments will help us serve your documentation needs better. If you have any suggestions on how to
improve this document, complete this form, publication RA-DU002, available at
http://www.rockwellautomation.com/literature/.

Copyright 2013 Rockwell Automation, Inc. All rights reserved. Printed in the U.S.A.