Audit Trail DELMIA Apriso 2018 Technical Guide 2017 Dassault Systèmes. Apriso, 3DEXPERIENCE, the Compass logo and the 3DS logo, CATIA, SOLIDWORKS, ENOVIA, DELMIA, SIMULIA, GEOVIA, EXALEAD, 3D VIA, BIOVIA, NETVIBES, and 3DXCITE are commercial trademarks or registered trademarks of Dassault Systèmes or its subsidiaries in the U.S. and/or other countries. All other trademarks are owned by their respective owners. Use of any Dassault Systèmes or its subsidiaries trademarks is subject to their express written approval.
Audit Trail DELMIA Apriso 2018 Technical Guide 2 Contents 1 Introduction 3 1.1 Purpose 3 1.2 Scope 3 1.3 Intended Audience 3 2 Audit Trail Overview 4 2.1 The Purpose of Audit Trail 4 2.2 Key Audit Trail Terms 4 2.3 How Audit Trail Works 4 2.4 Central Configuration 4 3 Audit Configuration Overview 6 3.1 Audit Configuration Overview 6 3.2 Audit Configuration Browser 6 4 Audit Configuration Properties 7 4.1 Header Tab 7 4.2 Roles Tab 7 4.3 Audited Tables Tab 8 4.3.1 Main Table 8 4.3.2 Additional Tables 8 4.4 Audited Fields Tab 10 4.4.1 Audited Fields 10 4.4.2 Audited Field Properties 11 4.5 Audit Conditions Tab 12 4.6 Key Values Tab 13 4.7 Common Configuration Mistakes 14 5 Audit Trail Usage 15 6 References 16 Figures Figure 1 Audit Configurations browser 6 Figure 2 Header tab 7 Figure 3 Roles tab 8 Figure 4 Audited Tables tab 8 Figure 5 Additional Table properties screen Header tab 9 Figure 6 Additional Table properties screen Additional Table Properties tab 10 Figure 7 Audited Fields tab Audited Field Properties screen 11 Figure 8 Audit Conditions tab 13 Figure 9 Key Values tab 13 Figure 10 Audit Configurations browser 15 Figure 11 Audit Trail main screen 15
Audit Trail DELMIA Apriso 2018 Technical Guide 3 1 Introduction 1.1 Purpose The purpose of this Technical Guide is to provide an overview of the Audit Trail framework in DELMIA Apriso, which is used for configuring and tracking database changes within the DELMIA Apriso system. All of the necessary information on using the framework to its full potential will be presented here. How to perform a common configuration and complete the administration tasks will also be described in detail. 1.2 Scope The scope of this document includes these core areas: Audit Trail architecture and key terms How Audit Trail works Configuration of Audit Trail Comprehensive explanation of how to create and maintain Audit Configurations Examples of how to create an Audit Trail based on business requirements Usage of Audit Trail An overview from the perspective of the end-user who is not involved in administrative tasks, but rather is focused on viewing and filtering Audit Trail 1.3 Intended Audience This guide is intended for people who are trained in using and administering DELMIA Apriso Audit Trail to perform basic, day-to-day procedures.
Audit Trail DELMIA Apriso 2018 Technical Guide 4 2 Audit Trail Overview 2.1 The Purpose of Audit Trail Audit Trail is used to track changes in the database. It enables traceability by logging changes on specified DELMIA Apriso tables and tracking what changes a specific user has made. This historical data is stored for comparison and backup purposes. The purpose of Audit Trail is to maintain control over all of the changes that have been made to DELMIA Apriso data over time. 2.2 Key Audit Trail Terms Audit Configuration a configuration that defines which changes to data are monitored and tracked The database table AUDIT_CONFIGURATION is used to store Audit Configurations (for more information, please see Database Documentation) Audit Entity represents a set of data that is consistent, has business meaning, and has been changed An Audit Entity is built using a definition from the Audit Configuration The database table AUDIT_EVENT is used to store Audit Events (for more information, see Database Documentation) Audit Event represents a single database operation on a set of data Audit Trail a record showing what database operations the user has performed during a given period of time An Audit Trail consists of Audit Events 2.3 How Audit Trail Works After DELMIA Apriso has been installed, Audit Trail is disabled by default. It is possible to enable Audit Trail on a table-by-table basis, as there is often the need to only track several specific tables rather than all existing DELMIA Apriso tables (which would severely impede the performance of DELMIA Apriso). When a specific DELMIA Apriso table has been configured for an audit, all of the changes made to this table by specific users will be stored in the Audit Trail Log. Only changes made after Audit Trail has been enabled will be stored. 2.4 Central Configuration Audit Trail must be enabled in Central Configuration.
Audit Trail DELMIA Apriso 2018 Technical Guide 5 There are two settings for Audit Trail that can be set in the DELMIA Apriso Central Configuration. The settings are system-wide and can be overridden on the application level. The settings are not accessible through DELMIA Apriso Configuration Manager, but they can be edited manually in the Central Configuration file using AuditEnabled and AuditConfigurationAbsouleLifetime keys located in the Framework section of the Central Configuration file (for detail, see Central Configuration Documentation). An audit generates considerable performance overhead, so it should be enabled only when it is necessary. (When Audit Trail is enabled, the UpdateBatchSize flag located in the DataServices section is disabled.)
Audit Trail DELMIA Apriso 2018 Technical Guide 6 3 Audit Configuration Overview 3.1 Audit Configuration Overview An Audit Trail is created based on an Audit Configuration. There can be many Audit Configurations in the system. An Audit Configuration is a user-defined object consisting of fields that are mapped to columns in database tables. One of the tables is considered the Main Table, and value changes in that table can trigger an audit. During runtime, the Audit Trail uses Audit Configurations to create Audit Entities when data in the database is changed and these changes are supposed to be tracked. An Audit Entity is an instance of an Audit Configuration that has values for its defined fields. An Audit Configuration may span several tables, and loading additional data from a database may be required before the Audit Trail for a specified Audit Configuration can be persisted. Finally, an Audit Event that contains an Audit Entity is persisted in the database. Audit Configurations are maintained using a set of screens that can be accessed in the DELMIA Apriso Desktop Client. 3.2 Audit Configuration Browser The Audit Configurations browser allows the user to browse, add, and remove Audit Configurations as well as select Audit Configurations for editing (see Figure 1). Figure 1 Audit Configurations browser An Audit Configuration can only be removed if no events were recorded by this configuration.
Audit Trail DELMIA Apriso 2018 Technical Guide 7 4 Audit Configuration Properties The Audit Configuration properties screen is displayed when the user chooses to add a new Audit Configuration or selects an existing one from the browser (see Figure 1). The properties of the Audit Configuration are divided into several tabs that will be discussed in the following sections. 4.1 Header Tab The Header tab (see Figure 2) contains the general properties of an Audit Configuration. The following items can be defined: Name the name of the Audit Configuration Description the description of the Audit Configuration Status the Audit Configuration can be enabled or disabled, and the status can be changed using the Enable/Disable button on the right side of the screen Figure 2 Header tab 4.2 Roles Tab The Roles tab (see Figure 3) defines the roles of the employees for which the Audit Trail will be generated. If there are no roles configured, then the Audit Trail will be generated for all employees. For example, an employee with the employee number of 997xy is assigned the Production User and Warehouse User roles. There is an Audit Configuration defined to track changes in the ATTENDANCE table. Employee 997xy clocks in and out. The behavior will be the following: If there are no roles configured, the Audit Trail will be created (for all employees) If there is a Process Author role configured, the Audit Trail will not be created (because employee 997xy has not been assigned this role) If there are Production User and Process Author roles configured, the Audit Trail will be created (because employee 997xy has been assigned one of these configured roles)
Audit Trail DELMIA Apriso 2018 Technical Guide 8 Figure 3 Roles tab 4.3 Audited Tables Tab The Audited Tables tab defines the tables that will be used to build an Audit Entity. 4.3.1 Main Table Figure 4 Audited Tables tab For each Audit Configuration, a Main Table must be selected. Only the Main Table is monitored for changes. The Main Table selected for this scenario is ATTENDANCE. 4.3.2 Additional Tables Additional Tables can be used to feed the Audit Entity additional reference data (e.g., the number of an employee taken from the EMPLOYEE table). The Audit Configuration can have multiple Additional Tables, but they are not required.
Audit Trail DELMIA Apriso 2018 Technical Guide 9 For example, an administrator wants to track changes in the attendance records. The ATTENDANCE table contains the EmployeeID column, which specifies an employee s unique ID and which is linked to the EMPLOYEE table. However, it would be more useful for the enduser to see the employee number that is stored in the EmployeeNo column of the EMPLOYEE table, so the administrator adds the EMPLOYEE table as an Additional Table. To add an Additional Table, click (Add). This will bring you to the Additional Table properties screen, which can also be accessed by clicking (Properties) after highlighting an existing Additional Table. The Additional Table properties screen has two tabs (see Figure 5) Header and Additional Table Properties and allows the user to configure and edit the properties of an Additional Table. For the purposes of this scenario, the following Additional Tables have been added: Header Tab Table Alias Required EMPLOYEE EMPLOYEEE WORK_CENTER WORK_CENTER EMPLOYEE On this tab, the following items can be defined: EMPLOYEE_CREATEDBY Name the name of the Additional Table, which must be linked by clicking (Link) Required this check-box indicates if data from the Additional Table is required when building an Audit Entity If the Additional Table is marked as Required, then during runtime the Audit Trail will not persist an Audit Event if data does not exist in the Additional Table Alias the alias of the Additional Table, which needs to be unique within the scope of the Audit Configuration Description the description of the Additional Table Figure 5 Additional Table properties screen Header tab
Audit Trail DELMIA Apriso 2018 Technical Guide 10 Additional Table Properties Tab This tab defines the links between the tables (which is very similar to the concept of joins in the world of SQL). A link is based on an Audited Field (see 4.4 Audited Fields Tab) and describes which value of a field from the parent table will be used to retrieve a record from the Additional Table. To add a link, click (Add), and select a Field Name and Parent Field Name. Figure 6 Additional Table properties screen Additional Table Properties tab It is also possible to define the link between an Additional Table and parent table based on a constant value (as with the Facility Field Name in the table below). The value of a field in the Additional Table is filtered using the constant value specified in the grid. For this scenario, the fields in the table below have been configured in the Additional Table Properties tab. Additional Table Field Name Parent Field name Constant Value EMPLOYEE EmployeeID AttendanceEmployeeID WORK_CENTER WorkCenter AttendanceWorkCenter Facility Constant C1P1 EMPLOYEE CreatedByEmployee AttendanceCreatedBy 4.4 Audited Fields Tab 4.4.1 Audited Fields The Audited Fields tab defines the fields that comprise the Audit Entity. All Audit Trail features are built around Audited Fields. Audited Fields are used to define triggering criteria, filtering conditions, and links between Audited Tables so that they can be persisted in the Audit Trail. This section allows the user to add, edit, and remove fields. The properties of Audited Fields are discussed further in the document. It is important to note that the Audit Configuration must have a set of unique fields defined. A set of unique fields constitutes the "primary key" of the Audit Entity. During runtime, Audit Trail uses the unique fields to differentiate between two objects instantiated using the same Audit Configuration. If the unique fields are not defined, it is possible that changes to two different objects (e.g., two EMPLOYEE records) will be recognized as one change, and the data will be mixed (which is clearly undesirable).
Audit Trail DELMIA Apriso 2018 Technical Guide 11 In continuation of the previous example, the administrator wants to display employee numbers in the Audit Trail. To do this, the administrator can add an audited field that is mapped to the EmployeeNo column in the EMPLOYEE table. 4.4.2 Audited Field Properties The Audited Field Properties screen appears after an Audited Field has been added, or it can be accessed by clicking (Properties) after highlighting an existing Audited Field. The screen (see Figure 7) allows the user to edit the properties of the Audited Field. The following items can be defined: Name the name of the Audited Field Description the description of the Audited Field Table Alias the alias of the table that contains the column to which the field is mapped This table must already be in the collection of Audited Tables (see 4.3 Audited Tables Tab) Table Field the database column to which the field is mapped Change Triggers Audit indicates if a change of value should trigger the creation of the Audit Trail Please note that this option is available only for the fields that come from the Main Table Persisted in Audit Trail indicates if a value of the field should be persisted in the Audit Trail Please note that the fields do not necessarily have to be persisted in the Audit Trail, as they can be used for other purposes also (e.g., to link other tables or define conditions for other tables) Unique indicates if a field is part of the unique key that, during runtime, allows the Audit Trail to differentiate between objects instantiated from the same Audit Configuration Figure 7 Audited Fields tab Audited Field Properties screen For our scenario, we have added the Audited Fields in the image below: Field Name Table Alias Table Field Triggers Audit Persisted Unique AttendanceCreatedby ATTENDANCE CreatedBy AttendanceEmployeeID ATTENDANCE EmployeeID
Audit Trail DELMIA Apriso 2018 Technical Guide 12 AttendanceEndTime ATTENDANCE EndTime AttendanceID ATTENDANCE ID AttendanceStartTime ATTENDANCE StartTime AttendanceWorkCenter ATTENDANCE WorkCenter EmployeeID EMPLOYEE ID EmployeeName EMPLOYEE Name EmployeeNo EMLPOYEE EmployeeNo CreatedBy EMPLOYEE_CREAT Name EDBY CreatedByEmployee EMPLOYEE_CREAT EmployeeNo EDBY WORK_CENTER WorkCenter Faclilty WORK_CENTER Facility WorkCenter WORK_CENTER WorkCenter 4.5 Audit Conditions Tab The Audit Conditions tab (see Figure 8) defines conditions that will be evaluated to determine if an Audit Entity should be persisted in the Audit Trail. The conditions can be established for all Audited Fields and for all available standard DELMIA Apriso operators. Additionally, a database action can be defined on which the Audit Entity will be persisted. For example, an administrator wants to create an Audit Trail that will consist of all additions and all edits performed by users. Additionally, the administrator wants to exclude two users from the Audit Trail: ADMIN and SYSTEM. To configure these conditions, the administrator: 1 Unselects the Delete checkbox in order to indicate that the Audit Trail shall not be persisted when the user deletes data from the database. 2 Adds the following Advanced Filter: EmployeeNo NOT IN Admin,System (see Figure 8). This means that the value of the EmployeeNo field should not be in the ADMIN or SYSTEM sets of values
Audit Trail DELMIA Apriso 2018 Technical Guide 13 Figure 8 Audit Conditions tab 4.6 Key Values Tab During runtime, Audit Trail keeps all the values of the Audited Fields as serialized properties of the Audit Event. The Key Values tab (see Figure 9) defines as Audited Fields which values will be stored in regular columns. The fields defined as Key Values can be used in search conditions both in DELMIA Apriso and in custom SQL queries. For example, an administrator defines an Audit Configuration on the ATTENDANCE and EMPLOYEE tables and sets EmployeeID as Key Value 1. The users of the Audit Trail request to be able to search the Audit Events by EmployeeNo and AttendanceEndTime, which are both fields of the Audit Configuration. The administrator defines that Key Value 2 will contain the value of the EmployeeNo field, while Key Value 3 will contain the value of the AttendanceEndTime field. Figure 9 Key Values tab
Audit Trail DELMIA Apriso 2018 Technical Guide 14 4.7 Common Configuration Mistakes Defining Audit Configurations and designing Audit Trails may require deep functional and technical knowledge of DELMIA Apriso data models. Invalid configuration can dramatically destabilize the system, and, though it may not affect (i.e., modify) DELMIA Apriso data, it may lead the system to an unexpected stop. These are some common mistakes made when configuring Audit Trail and their resolutions: The application was not restarted after the Central Configuration had been changed Changes in the Central Configuration require the application to be restarted for the changes to take effect (see 2.4 Central Configuration) This concerns both the ASP.NET runtime engine and DELMIA Apriso services The link between tables is not defined properly Tables cannot be linked to invalid columns (e.g., the EmployeeID column in the EMPLOYEE table cannot be mapped to AttendanceStatus) (see 4.3 Audited Tables Tab) An error message (with this icon: ) will appear for any incorrect links on the Additional Table Properties tab of the Additional Table properties screen The fields are mapped to the wrong columns A field cannot have a name that suggests a different mapping than actually exists (e.g., the EmployeeNo field cannot be mapped to the GivenName column) (see 4.4 Audited Fields Tab) The unique fields have not been defined The Audit Configuration must have fields that are unique and they need to be marked as such (see 4.4 Audited Fields Tab
Audit Trail DELMIA Apriso 2018 Technical Guide 15 5 Audit Trail Usage The Audit Configurations browser (see Figure 10) allows the user to select the Audit Configuration for which the Audit Trail should be presented. To do this, select the desired Audit Configuration and press (Audit Trail). Figure 10 Audit Configurations browser The Audit Trail main screen consists of two sections (see Figure 11): 1 The Audit Trail section is a standard DELMIA Apriso grid that presents Audit Events persisted for the selected Audit Configuration. The list of Audit Events can be filtered and sorted by Action, Employee, Date, and various Key Values. 2 When a specific Audit Event is selected, the Audit Event Details list is filled with the values of all of the fields that are defined in the selected Audit Configuration. Figure 11 Audit Trail main screen For detailed information on enabling and using (Signature) in Audit Trail, please refer to the 21 CFR Part 11 Compliance Implementation Guide.
Audit Trail DELMIA Apriso 2018 Technical Guide 16 6 References All the documents referenced below are available from the DELMIA Apriso Start page, which can be accessed on your DELMIA Apriso server (<server name>/apriso/start). The newest versions of all the documents are available from the 3DS Support. 1 Dassault Systèmes, 21 CFR Part 11 Compliance Implementation Guide This guide describes how the FDA s 21 Code of Federal Regulations (21 CFR Part 11) on Electronic Records/Electronic Signatures is incorporated in the DELMIA Apriso solution. The guide also presents what modules are enhanced with the electronic signature-related functionality as well as how DELMIA Apriso (as a set of those modules) should be configured to support this. 2 Dassault Systèmes, Central Configuration Documentation This documentation describes in detail all the keys of the Central Configuration (CC) file for DELMIA Apriso. Various sections group the keys for individual modules or distinct functional areas. 3 Dassault Systèmes, Database Documentation This documentation enables viewing DELMIA Apriso database (DB) tables (organized into groups), their descriptions, and the relations between them.