Implementing the AuditControl Pattern

Introduction    Implementing     Other Uses    Parts

This implementation guide shows how to use the AuditControl pattern in a Websydian application. Use the Audit Control Menu in this module to dynamically customize the level of Audit Control for your application.

Inherit from the AuditControl Pattern

First, you must create a local Audit entity in your application model that inherits from the AuditControl pattern in the WSYAUDIT library.

Example:

The local MyAudit entity will now scope the pattern to implement Audit Control.

Inherit from RelationalTable

Each entity scoped under the Data entity of the inherited AuditControl entity must inherit from RelationalTable.

Example:

Redirect Reference to Implemented Session Entity

The inherited Log entity is related to the Session entity in the WSYSESS library.  This reference must be redirected to the implemented Session entity in the application:

Example:

Inherit from Abstract Audit Patterns

The web server function in the application to include Audit Control must inherit from the abstract Audit patterns.  If Audit Control is needed for the Dispatcher function and for all the Page Generators and Event Handlers in the application, the inheritance triples may be specified for the abstract Session patterns.

If Audit logging is needed for all events received as well as for the System Errors encountered, two inheritance triples are needed for the Dispatcher function:

Example:

If the Dispatcher function and all Event Handlers and Page Generators in the application inherit through the abstract Session patterns then it is enough to specify Audit Control for those.  If Audit Control is needed for selected functions only, the inheritance triples can be defined for those functions one-by-one.

Replacing the LogTypeID Field

In the Audit module, new Audit Log messages are defined by adding values to the LogTypeID field.  Values cannot be added to a library field, so a new field must be defined in the model replacing the LogTypeID field.

Example:

In the example above, new log message values can now be added for the MyLogTypeID field.  You will also notice that the values for the System Error messages already have been defined as values for the field.

Defining Application Specific Error Messages

The Audit Module will by default create Log records for System Errors encountered by any of the web server functions.

You will also be able to use the Audit functionality for logging application specific errors, like "Credit max exceeded" or "Product not on stock".  In order to add a new message, you need to do the following.

Add Value for New Error Log Type

Add a new value for the Error Message to the LogTypeID field defined in the model

Assign a literal to the value equal to or above 1000 (the first 1000 values are reserved for Websydian use)

Specify the value APPERR as the narrative for the value.  This value will refer to the kind of Log Message (LogTypeKind)

Example:

Insert article failed is specified as a new Log Type by declaring a new value for the MyLogTypeID field.  The associated LogTypeKind is specified by the Narrative description.

Specify Code in Action Diagram

The next thing to do is to specify the correct error logging code in the action diagram of the web server function to log the error.

Add code in the action diagram to log the application error:

• Identify the edit point in which the application specific error is caught
• Set the AuditLog<SessionID> to the current Session
• Set the AuditLog<LogTypeKind> field to Application error
• Set the local LogTypeID field to the value created for the application specific error to log
• Initialize the AuditLog<LogDescription> field.  Set to *Blank if no value should be specified.
• Go sub the Audit logging sub routine

Example:

Logging an Application Specific Error each time a user tries to insert an Article record which already exists in the database.

Defining Information Messages

Another kind of Log messages is Information Messages.  Information Messages typically will be used to log that specific actions have been performed succesfully by the application, e.g. that an Article record has been succesfully updated.

Information Messages are specified similar to the Application Specific Error messages, now setting the value of the AuditLog<LogTypeKind> field to Information - in the narrative field of the new Log Type value defined as well as in the action diagram code.

Example:

Article inserted is specified as a new Log Type by declaring a new value for the MyLogTypeID field.  The literal value of the associated LogTypeKind is specified by the Narrative description.

Logging an Information Message each time an Article record has been inserted succesfully in the database.

Before defining your Information Messages, remember that system messages by default will be logged for each Event Handler called by the Dispatcher function.

If the Application Error Message values (scoped under your local LogTypeID field) have ID's starting from 1000, you may choose to let the Information Messages start with values from 2000.

Generate and Build

In order to implement the Audit Control functionality, the following objects must be generated and built:

• All objects scoped under the Data entity.
• The two service functions InitializeLogTypes and AuditControlMenu.
• All web server functions in the model for which Audit Control has been specified

Initialize Values for Event Types and Log Types

Two functions are included to initialize the tables of the EventType entity and the LogType entity.   The Event Types table is loaded from the Event Handler functions implemented in the application, while the Log Types table is loaded from the values defined by LogTypeID field or the local field replacing the LogTypeID field.

These functions should be run every time new Event Handlers or Log Types are added to the model.

Run the InitializeEventTypes Function

Run the InitializeEventTypes function scoped under the Dispatcher implemented in the model.

Example:

An InitializeEventTypes function will be scoped under the Dispatcher function of the application.

Run the InitializeLogTypes Function

Run the InitializeLogTypes service function.

Example:

The InitializeLogTypes service function will initialize the table for the LogType entity.

Specify Settings for Event Types and Log Types

Finally, run the AuditControlMenu Windows application.  This function comprises a small application where Audit Log records can be viewed and control options can be set for the auditing process.