Auditing FT Historian SE Server

AUDITING THE FACTORYTALK HISTORIAN SE SERVER

Rockwell Automation Publication HSEPISA-RM031A-EN-E–September 2013

Supersedes Publication HSEPISA-RM030A-EN-E

Customer Support Telephone — 1.440.646.3434 Online Support — http://www.rockwellautomation.com/support/overview.page

© 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.

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.

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.

This product is warranted in accordance with the product license. The product’s 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 product’s 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.

Contacting Rockwell

Copyright Notice

Trademark Notices

Other Trademarks

Warranty

Auditing the FactoryTalk Historian SE Server iii

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

Table of Contents

iv

Time Range 16 Unique Audit Record ID 17 Audit Database Mask 17 Schema 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

Auditing the FactoryTalk Historian SE Server 1

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)

Chapter 1

The Historian Audit Database


2

• 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.



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.


4

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).



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.


6

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 re-opened, 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


8

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:31-07:00

PIPoints 14 NewPoint OSI\jsmith Add



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:


DB RecordID

DB RecordName

PI Username Action

2009-09-27 16:39:06-07:00

PIPoints 14 NewPoint OSI\jsmith Remove

Changes


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.


DB RecordID

DB RecordName

PI UserName Action

13:00:00 11-Oct-01

PIPoints 9 Ba:temp.1 OSI\jsmith Edit

Changes


Compmin 10 0

Compdev 2.0 1.25

Compmax 5000 6000


10

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


DB RecordID

TimeStamp PI UserName Action

2009-09-25 11:59:28-07:00

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

OSI\jsmith Remove Attempt

Changes


Value Null or value (128.2149)

Null

Removal: Historian Archive Subsystem


DB RecordID


2009-09-25 11:59:28-07:00

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

0 Remove

Changes


Value 128.2149 Null



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


DB RecordID


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

PIArchive 3 2009-09-25 11:23:25-07:00

OSI\jsmith Edit Attempt

Changes


Value Null 159

Edit: Historian Archive Subsystem


DB RecordID


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

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

0 Edit

Changes


Value 150 159

Flags Null S

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.


12

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-499e-b6e3-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\Prop-106"

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, sub-batches 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 Subsystem Value

Hexadecimal Decimal

Point Historian Base

0x1 1

Digital State 0x2 2


14

Attribute Set (Point database schema)

0x4 4

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

Transfer Records Historian Archive 0x400 1024

Campaign 0x800 2048

Batches 0x1000 4096

Unit Batches 0x2000 8192

Snapshot Historian Snapshot 0x10000000 268435456

Archive Historian Snapshot and Historian Archive

0x30000000 536870912

All Databases 0xFFFFFFFF -1

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

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.


16

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.

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-4992-8BBF-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\""


18

Note: Double quote characters (") embedded in command-line parameters must be preceded with a backslash (\)character.


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:

Appendix A

Configuring Audit Logging

Configuring Audit Logging

20

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:

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

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

Technical Support and Resources

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

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 1.440.646.3434 Outside United States or Canada

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 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. Outside United States 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/.



http://www.rockwellautomation.com/support/americas/phone_en.html

http://www.rockwellautomation.com/literature/

Documents

Auditing FT Historian SE Server