Adroit Technologies
Auditing the Agent Server
Agent Server auditing is enabled by default, which logs the Agent Server’s sessions and selected activities
performed during these sessions to an OLE DB compatible database.
In addition, by using the Audit agent you can log the changes of values that are important to the running
of your process, such as set point values and/or alarm limits.
Generally, you will audit the Agent Server to provide a means of recourse in the event of a problem occurring to your process. Examining the audit logs you can determine any of the following user actions:
l
when the Agent Server was stopped and started;
l
what agents have been added or removed from your Adroit installation;
l
which audited tags (as specified in the Audit agent) have changed in value;
l
which Analog agents have had their alarm limits adjusted
l
which DBLog agents have had their queues dumped
l
who the logged on user was, when these audited events occurred, since each activity records the
currently logged on user, as follows:
Agent Server events and tag value change events indicate the Windows logged on user
Agent creation/deletion events
Tip: If you want to analyze your audited data then, we recommend that you install the Adroit Report
Suite and specifically the Audit Reports report pack, which provides you with the necessary tools you
need to analyze both your Agent Server auditing and tag auditing, where Agent Server auditing
includes any activities on the Agent Server, while the tag auditing is concerned specifically with data
logged by any Audit agents.
- 1 of 12 -
Adroit Technologies
Configuring Agent Server Auditing
The configuration settings that enable the auditing of the Agent Server and that specify the required
OLE DB compatible database are located in the Server auditing group section of the Advanced Agent
Server Configuration dialog.
To display the auditing configuration settings:
This displays a page of grouped advanced Agent Server settings.
To specify the auditing database: to select the OLE DB compatible database that will store the audit records
for this Agent Server. By default an MS Access database file is used.
1. If necessary, display the auditing configuration settings (see above).
l
By default, if the Custom OLE DB connection field is left blank and the Agent Server is started
then a MS Access database file, called adroit_audit.MDB, is created in the Work subfolder of the designated project folder, which is typically C:\ProgramData\Adroit Technologies\Adroit\Configurations\Default\Work.
Tip1: It is recommended to use this default database, since this is a single file that can easily be
backed up elsewhere.
Tip2: If necessary, you can secure this Access database and provide the user/password details in
the connection string.
l
Click the browse button
to the left of the Custom OLE DB connection field to specify another
OLE DB compatible database. For details, see Connecting to an OLE DB database.
For instance, you can use a central SQL database for all the Agent Servers on your network, since the
identification (Session ID) used for the logged events contain the name of the computer and Agent
Server. In this case, if you do not have SQL installed then you can install MS SQL EXPRESS.
To stop auditing the Agent Server: this prevents additional records from being added to the auditing database
1. If necessary, display the auditing configuration settings (see above).
2. Clear the Enable checkbox, which is enabled by default.
Tip: If you want to analyze your audited data then, we recommend that you install the Adroit Report
Suite and specifically the Audit Reports report pack, which provides you with the necessary tools you
need to analyze both your Agent Server auditing and tag auditing, where Agent Server auditing
includes any activities on the Agent Server, while the tag auditing is concerned specifically with data
logged by any Audit agents.
- 2 of 12 -
Adroit Technologies
The Auditing OLE DB database
The OLE DB compatible database used to audit the Agent Server contains the following tables:
Tip: If you want to analyze your audited data then, we recommend that you install the Adroit Report
Suite and specifically the Audit Reports report pack, which provides you with the necessary tools you
need to analyze both your Agent Server auditing and tag auditing, where Agent Server auditing
includes any activities on the Agent Server, while the tag auditing is concerned specifically with data
logged by any Audit agents.
Adr_Audit_Sessions table: these records provide the details of each Agent Server session.
This table contains the following fields:
1. Idx: A consecutive index for each session logged to this table.
2. dt: The date and time at which this session was started. The format of this field depends upon your
Regional Settings.
3. Session ID: A unique session identification number generated by Adroit that the Adroit_Activity_
Audit table uses to identify the session in which each activity is performed.
Tip: Since the Session ID contains the name of the computer and Agent Server, you can create a
central database for all Agent Servers on your network.
4. Computer: The name of the computer on which the Agent Server is running.
5. AS name: The name of the Agent Server, this is the name specified in the Agent Server Name
field of the Agent Server tab in the Adroit Setup utility.
6. Cluster: The name of the cluster that this Agent Server is part of, if any, so that you can identify
which Agent Servers are clustered pairs.
7. Shutdown: The date and time at which this session was stopped.
Note: If there is no entry, this means that the session was forcibly closed, for instance via the Task
Manager or due to a power failure.
Adr_Audit_Activity table: these records provide the details of the activities performed within these Agent
Server sessions.
This table contains the following fields:
1. Idx: A consecutive index for each session logged to this table.
2. dt : The date and time at which this activity was LOGGED by the Agent Server and NOT the date and
time at which this activity was PERFORMED.
In other words this data and time relates this activity to everything else that is being audited for this
Agent Server. This, in effect, does away with time synchronization problems as only the time of the
Agent Server is recorded.
3. Session ID: The unique identification number (located in the Adroit_Session_Audit table) that identifies the Agent Server session[glossary] in which this action occurred.
Tip: Use this field to link both tables when performing queries, to obtain the details of each Agent
Server session.
4. Action: A standard textual description of the action of the activity that is being logged. Since these
descriptions are standard they can be used to sort this table or used by a query to only display certain activities. Common actions include:
This is an alphabetic list of some common actions:
l
Agent Server shutdown
l
Agent Server startup
l
Create agent
l
Loaded WGP file
l
Remove agent
l
Saved WGP file
- 3 of 12 -
Adroit Technologies
5. Adroit version: This specifies the version of Adroit
6. Category: This field allows one to query this table, by providing numeric values to indicate when
specific actions occur. Available Categories:
l
1 = Agent Server startup/shutdown
l
2 = WGP file loading/saving
l
100 = Agent creation/deletion
l
101 = Tag value changes
7. Object name: The content of this field varies depending upon the Action that is being performed.
Object names logged for common actions:
The following table indicates the Object name entries that are logged for some common actions:
Action
Object name
Agent Server shutdown
Agent Server startup
Create agent
Actual agent name e.g. ANA004
Path and name of the agent database (.WGP) file e.g. C:\PLoaded WGP file
rogramData\Adroit Technologies\Adroit\Configurations\Default\Data\WG.WGP
Remove agent
Actual agent name e.g. B$SIMPLC-@200-1
Path and name of the agent database (.WGP) file e.g. C:\PSaved WGP file
rogramData\Adroit Technologies\Adroit\Configurations\Default\Data\WG.WGP
8. Slot name: This is ONLY used when using an Audit agent to audit changes to tag values.
9. Object value: The content of this field varies depending upon the Action that is being performed.
Object values logged for common actions:
The following table indicates the Object value entries that are logged for some common actions:
Action
Object name
Agent Server shutdown
Agent Server startup
Create agent
Agent type e.g. Analog
A single number indicating the sequential save file version (FVER=) value
in the 3rd line of the WGP file.
Loaded WGP file
Remove agent
Saved WGP file
Note: -1 means that the WGP file did not exist.
Agent type e.g. Scan
A single number indicating the sequential save file version (FVER=) value
in the 3rd line of the WGP file.
Note: -1 means that the WGP file did not exist.
10. Remarks configuration option is enabled"WGP version description entries" This is the description entered by the user if the of this agent database (.WGP) file. (DVER=) name Description
Actions use this field to specify the Saved WGP file and Loaded WGP file : This field could be
used for post processing comments when using 3rd party client connections to the database. By
default, only the.
Note: This DVER= field has "(Auto-saved)" appended when this .WGP file is saved via the systeminfo.savenow slot.
11. Computer: The name of the computer that generated the event.
12. Username : The name of the user associated with this event, as follows:
l
Agent Server events and tag value change events indicate the Windows logged on user.
l
Agent creation/deletion events indicate the Adroit user.
Note: Use the Session ID field to link both tables when performing queries per Agent Server session.
Tip: Use the Category field to perform queries on this table as this provides numeric values to indicate
when specific actions occur.
- 4 of 12 -
Adroit Technologies
Adr_Audit_Categories table: this provides descriptions of the ID numbers used by the Category field of
the Adr_Audit_Activity table.
- 5 of 12 -
Adroit Technologies
The Audit Agent
This agent supplements the auditing or logging of the Agent Server sessions and selected activities performed during these sessions to an OLE DB database.
Use the Audit agent to specify one or more tags that you want to monitor for ANY change in value. When a
value changes, for any reason, the agent logs this change of value to the audit database.
In other words, EVERY value change for EVERY specified tag is logged, regardless of whether Adroit or a
PLC or something else causes this change in value.
For this reason, it is essential that you ONLY specify the process tags whose EVERY change in
value is important to the running of the process. Typically you will audit set points or alarm levels,
but not temperature or level values.
In other words, do not specify process tags whose values that are required to change frequently as part of
the normal operation, as these will simply flood your database with unnecessary records.
Tip: If you want to analyze your audited data then, we recommend that you install the Adroit Report
Suite and specifically the Audit Reports report pack, which provides you with the necessary tools you
need to analyze both your Agent Server auditing and tag auditing, where Agent Server auditing
includes any activities on the Agent Server, while the tag auditing is concerned specifically with data
logged by any Audit agents.
Each changed value is logged to the Activity table of the audit database, which records the following:
l
The action i.e. Tag value change
l
The process tag that is changed i.e. agentName.slotName
l
The change in value i.e. oldValue to newValue
l
Information common to all the other records, such as the date and time of this action, the Agent
Server computer and the currently logged on username.
To audit the changes of one or more process tags:
1. Ensure that the Agent Server is being audited.
2. Edit an agent of type: Audit.
If necessary, add an agent of the required type, as follows:
In the Smart UI Designer:
Select the required Smart UI Server in the Enterprise Manager, as follows:
1. Open the Enterprise Manager.
2. If necessary, expand
Servers.
3. If necessary, expand the name of the required Server connection
.
Tip: The connection name is prefaced by the Smart UI Server computer name.
4. If necessary, expand the Datasources category.
5. If necessary, expand the required Adroit datasource or its icon
6. If necessary, expand the AgentGroup
7. Right click the required agent type
Tag.
.
tree.
, which are listed alphabetically, and select Create
8. Specify the required Tag Name or agent name.
The following rules apply when naming agents:
a. Agent names have a maximum of 27 characters.
b. Agent names cannot be the same as the names used for Agent Types or for Agent
Groups.
c. Agent names cannot use the following characters:
- 6 of 12 -
Adroit Technologies
Space
Percent
% Comma ,
Period . back slash \ Dollar
$
9. If necessary, provide an optional Description that describes the purpose or describes the
value of this tag (agent) for ease of reference.
10. Click the Finish button.
If necessary, locate the required agent, as follows:
In the Smart UI Designer:
Select the required Smart UI Server in the Enterprise Manager, as follows:
1. Open the Enterprise Manager.
2. If necessary, expand
Servers.
3. If necessary, expand the name of the required Server connection
.
Tip: The connection name is prefaced by the Smart UI Server computer name.
4. If necessary, expand the Datasources category.
5. If necessary, expand the required Adroit datasource or its icon
6. If necessary, expand the AgentGroup
tree.
7. If necessary, expand the required agent type
8. Locate the required agent
agent type.
.
, which are listed alphabetically.
, which is also listed alphabetically beneath their applicable
In the Enterprise Manager window: right click this agent and select Configure.
In the Edit Audit Agent dialog:
3. Check the Enable checkbox (the enabled slot).
4. Add the process tags that you want to audit, using one of the following methods:
l
Click the Import… button to add ALL your tags that have been output enabled i.e. so that
they can be configured by your front-end devices. Since these tags are typically your
alarm limits or set point values that you need to audit.
This method can save you time when you have a large number of these tags and you want
to audit all or most of these.
Note: You need to ensure that all the added tags are necessary to be audited.
l
Click the Browse a tag… button to display the Classic UI tag browser dialog to specify
the required agent and slot of this tag. For details, see Selecting a Tag Using the Agent
Explorer.
This method ensures that both the agent and slot name are correctly spelt and is the
standard method for selecting tags.
l
Click the Manually add a tag… button and type in the name of this tag in the Add audit
tag dialog.
This method is only recommended if you know the tag name and can type quicker than
you can browse.
Note : Please ensure that the name of both the agent and the slot of this tag are correctly specified, as these cannot be checked by the agent.
To remove a tag from the list of audited tags:
1. Edit an agent of type: Audit.
- 7 of 12 -
Adroit Technologies
If necessary, add an agent of the required type, as follows:
In the Smart UI Designer:
Select the required Smart UI Server in the Enterprise Manager, as follows:
1. Open the Enterprise Manager.
2. If necessary, expand
Servers.
3. If necessary, expand the name of the required Server connection
.
Tip: The connection name is prefaced by the Smart UI Server computer name.
4. If necessary, expand the Datasources category.
5. If necessary, expand the required Adroit datasource or its icon
6. If necessary, expand the AgentGroup
7. Right click the required agent type
Tag.
.
tree.
, which are listed alphabetically, and select Create
8. Specify the required Tag Name or agent name.
The following rules apply when naming agents:
a. Agent names have a maximum of 27 characters.
b. Agent names cannot be the same as the names used for Agent Types or for Agent
Groups.
c. Agent names cannot use the following characters:
Space
Percent
% Comma ,
Period . back slash \ Dollar
$
9. If necessary, provide an optional Description that describes the purpose or describes the
value of this tag (agent) for ease of reference.
10. Click the Finish button.
If necessary, locate the required agent, as follows:
In the Smart UI Designer:
Select the required Smart UI Server in the Enterprise Manager, as follows:
1. Open the Enterprise Manager.
2. If necessary, expand
Servers.
3. If necessary, expand the name of the required Server connection
.
Tip: The connection name is prefaced by the Smart UI Server computer name.
4. If necessary, expand the Datasources category.
5. If necessary, expand the required Adroit datasource or its icon
6. If necessary, expand the AgentGroup
tree.
7. If necessary, expand the required agent type
8. Locate the required agent
agent type.
.
, which are listed alphabetically.
, which is also listed alphabetically beneath their applicable
In the Enterprise Manager window: right click this agent and select Configure.
In the Edit Audit Agent dialog:
- 8 of 12 -
Adroit Technologies
2. Click the tag in the list that you do not want to audit.
3. Click the Delete selected tag button to delete this tag.
To allow an operator (user) to add a tag to be audited: this allows an operator to simply click a button on a
mimic and to type in the required tag (agent.slot).
1. Add a Button to the required mimic.
2. Label this button, as required.
3. Add an Operator Action behavior to this Button.
4. Specify the required Audit agent and select its addTag slot in the Tag field of this behavior.
5. Select Data Entry as the required Action.
- 9 of 12 -
Adroit Technologies
Related information
Creating a SQL database connection string
Click the browse button
to the right of this field and use the Data Link Properties dialog to create
the required connection string to your SQL Server database, as follows:
This Data Link Properties dialog specifies the location and the security credentials required to connect
to this database.
Note: If you need to configure or view this database and its data from other computers, like remote
User Interfaces, then use a UNC path and not a local file system path to specify the location of this database.
A. Double click the Microsoft OLE DB Provider for SQL Server item in the Provider tab of the
Data Link Properties dialog.
l
Either type in the computer name of the SQL Server that you want to connect to, in the Select or
enter a server name field.
Tip: This is the fastest method, if you know the name of the SQL Server.
l
Or click the button to the left of the Select or enter a server name list box and select the name of
the required SQL Server from the list.
B. Specify the required security credentials to connect to this SQL Server, as follows:
IMPORTANT1: If you need to connect to a remote SQL database and want to run the Agent Server
service using the Local System account, then use SQL Server Authentication.
IMPORTANT2: If you need to connect to a remote SQL database and want to Use Windows NT
Integrated security, then ensure that the user profile that the Agent Server service uses to log
onto the computer HAS the necessary rights to browse the network and connect to the remote database. This should NOT be the default Local System account.
l
Use Windows NT Integrated security: this option uses the username and password of the
currently logged on Windows user.
Tip: We recommend that you configure your SQL Servers to use this option to avoid requiring
additional database security.
l
SQL Server Authentication: this option uses the User name and Password configured
within the SQL Server you are attempting to connect to.
Note: In this case it is recommended to check the Allow saving password checkbox.
C. Select the name of the required database from the Select the database on the server list box.
D. Click the Test Connection button to ensure that you are able to connect to this database using
these details. Only proceed once 'Test connection succeeded' is displayed.
E. Click the OK button.
Your connection string will be created.
Note1: The Advanced tab of this dialog allows you to specify access permissions for this connection
string. If you are unsure about these settings NEVER set these permissions to Read otherwise this connection string will fail.
Note2: These security credentials are database specific and should not be confused with application
security.
Note3: You can edit this string directly, once it has been created, if necessary.
Selecting a Tag Using the Agent Explorer
Select a tag using the Select Agent dialog, as follows:
A. Select (click on) the required list of agent types in the left pane, from the following options:
- 10 of 12 -
Adroit Technologies
l
AgentGroup: This lists EVERY agent type in the Agent Server - only use this if you cannot find the required agent type in the other categories.
l
Advanced: A list of the more advanced agent types that typically advanced users will
use.
l
Basic: A list of the more common agent types that most users will use.
l
System: A list of agent types that are created by Adroit.
B. Select the required type of agent that you require from this list.
Note: To also display remote agents on other Agent Servers associated with your project, then
open the View menu and ensure that the Remote Agents option is ticked.
l
If the required agent exists, in this agent type, then select it.
Example:
This shows how to locate an Analog agent.
l
If the required agent does not exist, in this agent type then click the Add... button to create it,
as follows:
a. Type in the required Agent Name in the Add Agent dialog.
b. If required, specify an Agent Description which provides additional information
about this agent.
c. Click OK when finished.
To save any newly-created agents, open the Options menu and click the Save Agents Now
menu item.
C. If necessary, select the required slot for this agent in the right pane.
By default, this browser:
l
Selects the most commonly used slot for each agent type.
l
Does not display the slots from the header of an agent. To display these open the View menu
and ensure that the Header slots option is ticked.
l
ONLY displays the slots types than can be used in the specified field. To display ALL the available slots, open the View menu and ensure that the Filtered Slot Types option is not ticked.
The available slot types are indicated by the following icons:
In addition to displaying the relevant slot type, these icons ALSO indicate whether the slot belongs to
the header or the body of the agent, as follows:
- 11 of 12 -
Adroit Technologies
Example:
This shows how a slot will appear in the right pane, display its slot type icon, its name and a textual
description:
D. Click the OK button to insert the selected agent and slot into the required field.
- 12 of 12 -