User Management - ARCAD-Software/AFS GitHub Wiki

User Metadata-Entities

AFS bundle com.arcadsoftware.server.metadata.user declare the following entities and their relations:

User Actions Log

Introduction

The User Actions Log is a special log usable to record the users' actions into a dedicated file or in a the database. This service is implemented into the bundle com.arcadsoftware.server.action.log. It is based on the OSGi Event service and listen the event topic: com/arcadsoftware/user/action.

According to the configuration of this bundle the event are recorded into a CSV file or into the database in the table USERACTIONS. This table must be created into the database, according to the following SQL DDL. Note that versions of AFS starting from 2022.4.22 automatically generate this table.

USERACTIONS table declaration

-- User Action record log.
-- (This table is ussed only if the User Action log is stored into tha database)

create table USERACTIONS (
    UAC_ID integer generated by default as identity primary key,
    UAC_USER integer,
    UAC_LOGIN varchar(50),
    UAC_CODE varchar(50),
    UAC_MESSAGE varchar(255),
    UAC_OCCURENCE integer default 1,
    UAC_DATE timestamp default current_timestamp);

create index UAC_CODE_INDEX on USERACTIONS (UAC_CODE);
create index USR_USERCODE_INDEX on USERACTIONS (UAC_CODE, UAC_USER);

alter table USERACTIONS add constraint UAC_USER_FK foreign key (UAC_USER) references USERS (USR_ID) on delete set null;

--
-- End of User Action record log.

If the log is recorded into the database, and only in that case, a corresponding MetaData entity is declared with the type "useraction". This entity may be used to browse the event log.

If the log is recorded into CSV files a size limit and a rolling of files may be configured to limit the size of the log. In the database recording there is no automatic deletion of the old recorded events.

Both records are done asynchronously, according to the delay given in the configuration.

Declare User Action event

AFS generate some events, as described bellow, but any bundle can add any kind of new events into the log.

User Action API

The ActionBroadcast class from the package com.arcadsoftware.server.action.log allow to declare the user action event with a simple call of the method broadcast (see javadoc for details).

But even without this API sending an User Action event is quite simple, you have to post an OSGi Event, with the topic "com/arcadsoftware/user/action" and the following properties:

  • uid (Integer): for the User internal ID corresponding to the user which cause this event.
  • login (String): the login of this user, may be null, this information is useful if the user ID is unknown or not applicable.
  • code (String): the event code (should be used to identify a category of messages), you should take care to use a non already used code.
  • message (String): the event message itself.
  • date (Date): the original date, this parameter is optional as the date of the treatment of this event will be used as a date by default.

Administrative Console

The AFS administrative console automatically record all actions run from it. The event message present the localized (with the server Locale) name of the Console Section and the Action ID. The event code is "console".

The consultation of the section is not logged.

MetaData Entities

In the MetaData entities declaration files you can use the following metadata to declare the corresponding User Action Events:

  • logCreate: This Entity metadata will generate a User Action Event each time a data will be created through the AFS web-services.
  • logUpdate: This Entity metadata will generate a User Action Event each time a data will be updated through the AFS web-services.
  • logDelete: This Entity metadata will generate a User Action Event each time a data will be deleted (hard or soft deletion) through the AFS web-services.
  • logLink: This Link metadata will generate a User Action Event each time an instance of this link is created.
  • logUnlink: This Link metadata will generate a User Action Event each time an instance of this link is created.

The value of these metadata is the event message to generate. The code of the event will be equal to the Entity type. These messages may use tag which will be replaced by the attributes values of the corresponding data. The MetaDataFormater class is used to replace the attributes reference by their values. This class use format string as described in the javadoc:

The MetaDataFormater can be used to format a String according to values of a BeanMap.

Format are string with %attribute% keys, if the "attribute" is not found in the associated MetaDataEntity then the text "attribute" will stay in the final text.

If you want to use the % character place %% in the format string.

Parameters can be used with "|" (pipe) character. Some parameters can be repeated into the same key :

    - %att1|att2% if the attribute "att1" is not defined then the attribute "att2" will be used.
    - %att|100% represent the maximal string length of the attribute representation. If it is longer it will be truncated.
    - %att|-100% will add white spaces at the end of the attribute if its string representation is lower than 100 characters.
    - %att|a text% will use "a text" as place holder if the given attribute does not exist. Note: "a text" must not be a potential attribute text.
    - %|% will be replaced by the pipe character.

For instance theses strings are valid formats :

    - "[%code%] %name%"
    - "[%code%] %name|text|80%"
    - "[%code%] %name|text|80|Default String%"
    - "%this is not an% attribute% but there% is invisible %% everywhere."

The Link events are thrown only if the link is exploited in the corresponding direction, e.g if two entities A and B are linked together it may be 2 links definitions, one in the entity A and another into the entity B, to properly generate the log relative to this association you have to declare it in the 2 links definitions. These events use a formater called MetaDataLinkFormater, derived from the one above, which allow to use the attributes of the both entities into the format string, to avoid name conflict you can prefix the attributes codes with "source." or the type of the current entity, or with "target." or the type of the referenced entitiy.

Notes:

  • These events are thrown by the Web-service, so server side modification will be not recorded... If a server operation must generate a User Action Event please use the ActionBroadcast class.

AFS bundles declares such events for the Creation, Update and Deletion of the following entities:

  • user (in the AFS version 2022.4.22 and above).
  • profile (in the AFS version 2022.4.22 and above).
  • localauch
  • ldapauth
  • ibmauth
  • winauth

HTTP Authentication

The Rest authentification bundle will automatically generate an User Action event each time a web-service call pass through it, in other words, for all resources connected to the /secure branch. this event is thrown with the code "http_auth" if the authentication is successful, if the login or password is wrong or if the user is locked, each time with a different message.

Note that is case of an unsuccessful authentication event message then the User Id is not defined, obviously.

Moreover the web-service /currentuser broadcat a "chg_pwd" event when a user change its own password.

Recap AFS defined user action codes

AFS wil generate the following User Actions events, according the the used version and the currently installed bundles. These event code must be considered as reserver codes:

  • http_auth: thrown when an HTTP authentication is requested.
  • chg_pwd: thrown when a user change its own password through /currentuser service.
  • console: thrown when an action is performed into the Administrative console.
  • user: thrown when a user record is modified.
  • profile: thrown when a user profile record is modified.
  • localauth: thrown when a user local identification record is modified.
  • ldapauth: thrown when a user LDAP identification is modified.
  • ibmauth: thrown when an IBM i user identification is modified.
  • winauth: thrown when a MS Windows user identification is modified.

Configuration

Configuration located in the file com.arcadsoftware.server.action.log.cfg or in the section [ Server Action Log ] of the file osgi.cm.ini.

This section manages the user action logging facility, which can be used to store critical user actions into the application database or into a log file (in CSV format).

cache.delay

Parameter Type Default value
cache.delay Integer 30

This parameter define the delay, in seconds, used to cache the log message before to store them.

storage

Parameter Type Default value
storage String

Define kind of storage used for the log, there is two options:

  • database: The log will be stored into the application Database into the table USERACTIONS.
  • file: The log will be stored into a CSV file on the server file system. The file name and other parameters relative to the file storage are defined by the following parameters.

En Empty value disable the log.

storage.file.size

Parameter Type Default value
storage.file.size Integer 1000

Define the maximal of row in a file, once the file is full a new one is created. A value of zero disable this limit, only one file will be used to store the log.

storage.file.roll

Parameter Type Default value
storage.file.roll Integer 0

If different from zero and higher than one, this parameter define the number of different files will be keep. This parameter is usable only if a storage.file.size is defined,; once a corresponding number of file is created, the file counter restart from zero, overwriting the oldest file.

storage.file.name

Parameter Type Default value
storage.file.name String ./log/useractions.csv

Define log file name. if the parameters storage.file.size and storage.file.roll are defined this file name may include a placeholder "%d" which will be replaced by the current number of the file. Ifd not present the placeholder will be automatically added at the end of the file name (e.g. "./log/useractions%d.csv")

Different placeholder may be use. For instance "%o" and "%x" will respectively present the file number in base eight or in base sixteen. "%3d" will pad the number with spaces to at least 3 characters, while "%03d" will do the same but with "0" (zeros).

ignore

Parameter Type Default value
ignore String

This parameter allow to ignore some messages codes. The value of this parameter is a space separated list of codes. Any user action message with the corresponding code will not be stored.