1C:Enterprise 8.3. Developer Guide. Contents

THE EVENT LOG

Administrative tasks often require you to find out what events have occurred at a particular time or what actions various users have executed.

The event log is used for this purpose. Various events are recorded in this log. An administrator can use it to obtain a history of users' interactions with the system.

The event log is not stored in the database and is not saved when an infobase is restored/dumped.

When users work in 1C:Enterprise, the software registers major user actions involving infobase data modifications, data access granting/denying scheduled operations, connection and disconnection, etc.

Besides interactive tools to work with the log provided in the designer, you can also work with the log programmatically.

This chapter describes the software tools available for working with the event log.

21.1. DETAILS MANAGEMENT

It is possible to manage message detail level for messages in the event log. The GetEventLogUsing() and SetEventLogUsing() methods are used for this purpose.

//  set registration of all events of the log
Levels  = New Array;
Levels.Add(EventLogLevel.Error);
Levels.Add(EventLogLevel.Information);
Levels.Add(EventLogLevel.DoMessageBox);
Levels.Add(EventLogLevel.Comment);

SetEventLogUsing(Levels);

21.2. WRITING EVENTS

When different operations are executed, you need to register actions for further analysis. You can use the event log to do this. Events are written to the log using the WriteLogEvent() method.

NOTE

You can't use this method to write system events to the log.

User event names can contain a period, thus forming user event groups.

21.3. EVENT LOGGING MANAGEMENT

You can enable/disable any event logging. The GetEventLogEventUsing() and SetEventLogEventUsing() methods and the EventLogEventUsing object are used for this purprose. The example below shows how to disable Performance error event logging (_$PerformError$_):

EventUse  = New EventLogEventUse();
EventUse.Use  = False;

SetEventLogEventUse("_$PerformError$_",  EventUse);

Note that there are two events that have additional abilities for event logging configuration. These are the Access (_$Access$_.Access) and Access denied (_$Access$_.AccessDenied) events. Let's discuss these events in more detail.

NOTE

Transaction related events (_$Transaction$_.Begin, _$Transaction$_.Commit, _$Transaction$_.Rollback) cannot be disabled via SetEventLogEventUse method.

21.3.1. The Access Event Parameters Configuration

The Access event is used to log facts of user access to certain data. You should set the following to configure the Access event:

„ the necessity of logging this event

„ a list of metadata objects, access to which should be logged

„ a list of metadata object fields, reading of which should be logged (access fields)

„ a list of metadata object fields, values of which should be logged (logging fields)

The general mechanism looks as follows (if the event is logged): if in the process of data (selected metadata object) handling one of the set access fields was read, logging fields are written to the event log according to the set rules.

The amount of data written to the event log depends on the event logging configuration:

Use	Access fields	Logging fields	Result
Not set			Event is not logged
Set	Not set	Not set	Event is not logged
Set	Set	Not set	Event is logged without details
Set	Set	Set	Event is logged with the logging fields specified

An event is generated only if data are successfully read.

Let's look at an example of parameters configuration:

SetupCatalog  = New EventLogAccessEventUseDescription();

//  Set object, access to which will be registered
SetupCatalog.Object  = "Catalog.Individuals";

//  Set access fields
SetupCatalog.AccessFields.Add("PassportData");
SetupCatalog.AccessFields.Add("Kids.BirthCertificate");

//  Set registration fields
SetupCatalog.LoggedFields.Add("PassportData");
SetupCatalog.LoggedFields.Add("Kids.KidName");
FieldAlternatives  = New Array();
FieldAlternatives.Add("LastName");
FieldAlternatives.Add("Name");
SetupCatalog.LoggedFields.Add(FieldAlternatives);

SetupMetadataObjects  = New Array();
SetupMetadataObjects.Add(SetupCatalog);

This example registers access to Persons catalog items.

Event log events are automatically generated if a request to Persons catalog data includes:

„ The PassportData field.

„ The BirthCertificate field of the Children tabular section.

If a data request lacks these fields, the data access event will not be written to the event log.

When the system determines access to the controlled fields, the following information about the Persons catalog will be written to the event log:

„ The PassportData field.

„ The ChildName field of the Children tabular section.

„ The LastName or Name fields. The field that is written to the event log is determined by the presence of this data in the data request. If all specified fields are used, the field with the least index is written to the event log (this

is LastName in the example). If only one field of the two is used in the request, this field goes to the event log.

Let's look at another example of Access event configuration:

SetupInformationRegister  = New EventLogAccessEventUseDescription();

//  Set object, access to which will be registers
SetupInformationRegister.Object  = "InformationRegister.EmployeeSalaries";

//  Set access fields
SetupInformationRegister.AccessFields.Add("Salary");

//  Set registration fields
SetupInformationRegister.LoggedFields.Add("Employee");

SetupMetadataObjects.Add(SetupInformationRegister);

In this example, when the InformationRegister.EmployeeSalary.Salary field is accessed, the Access event will be logged with the following Data.Data field:

„ If the request results in receiving the InformationRegister.EmployeeSa- lary.Employee (and the Reference field is set in the logging fields configuration of the Persons catalog to which the Employee field is referencing), the event log will include:

○     A value table with the CatalogPersonsReference column with reference values for Persons catalog objects will be written in the Data field.

○ An array with the InformationRegister.EmployeeSalary row, i.e., the name of the object that triggered logging this access event, will be written to the Metadata field.

○ The MetadataRepresentation field will contain an array with the InformationRegister row. Employee salaries is a metadata object representation.

„ If the Reference field is not included in Persons catalog logging fields, it will not be registered in the information register request.

„ If the request gets data using a Catalog.Persons-type reference stored in the information register, only fields received via a reference in the Person catalog field will be logged:

○     For example, if the Name, LastName and PassportData fields are the result of the request (all received via a reference in the Person catalog field), the event log will include the PassportData and LastName fields (see the description for the Employees catalog in the previous example).

21.3.2. Access Denied Event Parameters Configuration

The Access denied event is used to log user access denied events for certain data. You should set the following to configure the Access denied event:

„ the necessity for logging this event

„ a list of metadata objects, for which logging events should be logged in case of denied access (for all other objects denied access will be logged without details)

„ a list of metadata object fields, values of which should be logged (logging fields) when access is denied.

The general mechanism looks as follows (if the event is logged): if in the process of data (selected metadata object) handling access was denied, logging fields are written to the event log according to the set rules.

The amount of data written to the event log depends on event logging configuration:

Use	Logging fields	Result
Not set		Event is not logged
Set	Not set	Event is logged without details (the Data field is not populated)
Set	Set	Event is logged with specifying logging fields in the Data field

The event is generated in the following cases:

„ When access to the whole data object is checked:

○     If access rights are violated when accessing application object methods or properties in 1C:Enterprise script or standard interface functions (forms, commands).

○ If access is denied when configuration access rights are checked.

○ If an event is triggered, the Data field of the log record will contain a structure with the Right property containing the action for which access was denied.

„ When data access restrictions are checked: ○ If data access restrictions are breached.

○     If an event is triggered, the Data field of the log record will contain a structure with two following properties:

□ Action – the action for which access was denied.

□ Data – contains information about logging fields (if configured).

NOTE

When data are read to a temporary table, the Data.Data field of the event log is not populated.

Let's see an example of parameters configuration:

SetupCatalog  = New EventLogAccessDeniedEventUseDescription();

//  Set object, access to which will be registered
SetupCatalog.Object  = "Catalog.Individuals";

//  Set registration fields
SetupCatalog.LoggedFields.Add("PassportData");
SetupCatalog.LoggedFields.Add("Kids.KidName");
FieldAlternatives  = New Array();
FieldAlternatives.Add("LastName");
FieldAlternatives.Add("Name");
SetupCatalog.LoggedFields.Add(FieldAlternatives);

If access to data are violated in a Reading operation, the Access denied event will be logged and the logging field will be written according to the rules for Access event logging fields. For other actions (Change, Delete, Add) an event is triggered, but no data are written.

21.4. GETTING EVENT LOG RECORDS

When an application is used, a situation may arise that requires you to programmatically analyze the event log, such as get event log events per some criteria (filters). You should use the UnloadEventLog()global context method to get event log records programmatically. Programmatically, you can obtain the event log records of an infobase where the script code is executed or another infobase (even if other 1C:Enterprise instances use this base) if the UnloadEventLog() method has the InputFileName parameter set. Please note that this reading operation is only recommended if the event log files of another infobase are available locally for the 1C:Enterprise instance that reads the log. If such access is not granted, you need to think of other ways of accessing the event log.

To set selection criteria, use the Filter parameter of the UnloadEventLog() method. This parameter can contain a single filter value set with the Structure object of a special format (this format is described in the Syntax Assistant:

Global context – Procedures and functions for working with the event log – UnloadEventLog) or an array of such structures.

If the filter is set by one Structure-type item, all records will be put into the result selection that fulfills all conditions set in the structure (conditions are joined with the "OR" operator). If the filter is set by an array, the result selection will include records that fulfill at least one condition listed in the array items (conditions are joined with the "OR" operator).

We should emphasize that you can set a filter based on the Data field of an event log record. String, Count, Data, Reference, Structure types of values can be used as a filter for this field (for Access, Access denied, Authentication, Authentication error, Add user, Update user and Delete user), as well as a structure array.

The value of a structure item passed in the Filter parameter can be a specific value, Structure or Array. Event log data are checked for consistence with filter parameters as follows:

„ If a specific value is passed, record data and filter values are compared.

„ If a value array is passed, event log record data values and all values of the array passed as the filter value are compared. The condition is considered fulfilled if the value set in the log record matches at least one value in the passed array.

„ If a structure is passed as the value, the condition is considered fulfilled if event log record data are matched for all items of the passed structure.

Let's discuss it in more detail.

1.     If the Data field of the event log record contains a structure, the filter Data field also contains a structure. In this case the record satisfies the condition if the log Data field includes all keys from the filter field with the same name and the values of these keys match.

2.     If the Data field of the event log record contains a value table, the filter Data field contains a structure. In this case the record satisfies the condition if the value table contains all the columns with names equal to filter structure key names and rows where the corresponding column values match filter structure values.

3.     If the Data field of the event log record contains a Structure, Array or ValueTable type of value, the filter Data field contains an array. In this case the record satisfies the condition if at least one value from the passed array is found in the log record data.

4.     If the Data field of the event log record contains any value (not a structure, array or a value table), the filter Data field contains an array. In this case the record satisfies the condition if the log record value is equal to any value from the passed array.

5.     The log record Data field contains a ValueTable-type value item, the filter Data field contains an Array-type item and item keys match. In this case the record satisfies the condition if at least one table cell is equal to any value from the passed array.

6.     If the Data field of the event log record contains a Structure, Array or ValueTable type of value, the filter Data field contains the Structure or Array type. The log record will satisfy the condition if a record in the nested data fulfills p. 1 and p. 5 conditions. But if a structure is set in the filter, a search for items in the structure or event log value table columns corresponding to structure items will be performed only for a specified nesting level that corresponds to the filter nesting level. Thus, separate values and values from arrays in the filter are searched in full depth, and filter structure items are searched only at the specified level.

When a value table in the event log Data field is generated and it contains columns with the same name, these columns are merged into a single column. The number of rows in this table is increased, so the result column includes all unique values from the columns with the same name. Values in other columns are duplicated in rows generated.

Let’s illustrate this using an example. Suppose an application contains a query that returns a table with the following columns:

„ CatalogRef.Products

„ CatalogRef.Products

„ Row

When an event log record is generated, the following transformation is performed:

„ The first two columns will be merged into a single column.

„ For every row where Products.Reference and Nomenclature.Reference values are not equal, another row will be generated.

„ Rows will have a different value of the merged column with reference values. Other column values will be the same.

Source table:

Reference	Reference	Article
Sausages	Pepper	16-AÂ-1675

Result table:

Reference	Article
Sausages	16-AÂ-1675
Pepper	16-AÂ-1675

Let's show some examples showing how filters work when event log records are received.

Example 1:

„ Event log Data field value for the Authentication event:

○     type: Structure

□ key: OSUser, value: Johnson

„ Filter Data field value of the UnloadEventLog() method:

○     type: Structure

□ key: OSUser, value: Johnson

„ Result: record matches Example 2:

„ Event log Data field value for the Access event:

○     type: Structure

□ key: Data, value: ValueTable

Last Name	City	Phone
Peterson	Philadelphia	111-22-33
Johnson	Washington	222-33-44

„ Filter the Data field value of the UnloadEventLog() method:

○     type: array.

□ item 1: Structure type

§  key: OSUser, value: Johnson

□ item 2: Structure type

§  key: Data, value: Structure

§  key: LastName, value: Johnson

§  key: City, value: Washington

„ Result: record matches the filter, since when array item 2 was compared a match with record data was found (row 2). The event log record contains a value table with the Name and City columns in which both values are equal to corresponding values in the filter structure.

Example 3:

„ Event log Data field value for the Add user event:

○     type: Structure

□ key: Roles, value: Array

§  value 1: Roles.Administrator

§  value 2: Roles.Storekeeper

§  value 3: Roles. SalesManager

„ Filter Data field value of the UnloadEventLog() method:

○     type: Structure

□ key: Roles, value: Roles.Storekeeper

„ Result: record matches the filter, since the Data field contains an Roles item that has a Roles.Storekeeper value.

Example 4:

„ Event log Data field value for the Add user event:

○     type: Structure

□ key: Roles, value: Array

§  value 1: Roles.Administrator

§  value 2: Roles.Storekeeper

§  value 3: Roles.SalesManager

„ Filter Data field value of the UnloadEventLog() method:

○     type: Structure

□ key: Roles, value: Array

§  value 1: Roles.SalesManager

§  value 2: Roles.Accountant

„ Result: record matches the filter, since the Data field contains a Roles item that has a value listed in the filter array (Roles.SalesManager value).

Example 5:

„ Event log Data field value for the Access event:

○     type: Structure

□ key: Data, value: ValueTable

Last Name	City
Peterson	Philadelphia
Johnson	Washington

„ Filter the Data field value of the UnloadEventLog() method:

○     type: array

□ type: Structure

§  key: Data, value: Philadelphia

„ Result: record matches the filter, since the target value (Philadelphia) is found in one of the value table cells in the Data field of the event log record Data field.

When the event log record Metadata field contains metadata array, the record matches the filter if at least one array item from the filter Metadata field is equal to any log record array item.

21.5. ADDITIONAL METHODS

To simplify interactive event log filtering you can use the GetEventLogFilterValues() method. With this method you can get available filter values for the following filter parameters: User, Computer, AppName, Event, Metadata, ServerName, Port, SyncPort. Thus, if you need to set a filter for an event log event, you can get a list of events that are actually present in the log and then select items from the list.

The EventLogEventRepresentation() method is used to generate event log event representations.