History

Principle

A component's history is made up of a set of facts. Each fact logs an action performed by a user on a component and stores the following information:

Name	Automatic	Description
id	yes	Unique identifier
creationDate	yes	Completion date
user	yes	Identifier of the user who performed the operation
requestId	yes	Identifier of the request at the origin of the action
technical	yes	Determines whether the fact is technical or business
action	no	Action performed
objectId	no	Object identifier in question
objectType	no	Object type in question

Technical facts

Technical facts are generated automatically by FlowerDocs Core when a historical operation is executed. For each component category, fact logging for a given action can be enabled or disabled.

Documents

Action	Default	Description
create	yes	Creation
read	no	Access
get_content	no	Content access
update	yes	Update
add_content	no	Adding content
delete_content	no	Deleting content
revert	yes	Restoring a version
delete	yes	Physical removal

Tasks

Action	Default	Description
create	yes	Creation
read	no	Access
update	yes	Update
assign	yes	Assignment
add_content	yes	Add attachment(s)
delete_content	yes	Deleting attachments
answer	yes	Application of an answer
delete	yes	Physical removal

Folders

Action	Default	Description
create	yes	Creation
read	no	Access
update	yes	Update
add_content	yes	Adding component(s)
delete_content	yes	Deleting component(s)
delete	yes	Physical removal

Virtual folders

Action	Default	Description
create	yes	Creation
read	no	Access
update	yes	Update
delete	yes	Physical removal

To modify historical actions, the core.properties file must be modified using the default configuration:

fact.registrations.document=create,update,delete,version,revert
fact.registrations.folder=create,update,add_content,delete_content,delete
fact.registrations.virtual.folder=create,update,delete
fact.registrations.task=create,update,delete,answer,assign,add_content,delete_content

Business facts

A business fact is generated programmatically to record a particular state or action for a component. This generation must be configured or developed specifically for the situations concerned thanks to:

• APIs exposed for each component category
• the ContextUtil object

The user responsible for generating a business fact must have the ADMIN role.

In the graphical user interface, a technical fact is linked to a business fact if they have the same request identifier (requestId). Technical facts generated before and linked to a business fact are displayed in detail.

HTTP

POST {core}/rest/documents/{id}/facts HTTP/1.1
token: {token}
Content-Type: application/json

{
    "action": "CUSTOM",
    "description": "Generated by REST API.",
    "updatedFields": [
        {
            "name": "tag",
            "value": "text"
        }
    ]
}

Script

//ScriptOperationHandler
var builder = com.flower.docs.common.fact.FactBuilder.objectId(component.getId()).type("DOCUMENT");
builder.action("CUSTOM").description("Generated by script operation handler.").field("tag", "text");
util.createFact(builder.build());

The endpoint depends on the component category: documents, tasks, folders or virtualFolders. The objectId and objectType of the fact are taken from the endpoint, so they do not need to be provided in the payload. Since technical defaults to false, a fact created this way is a business fact.

warning

The action of a fact is compared to the values of the Action enumeration (CREATE, READ, UPDATE, DELETE, SEARCH, LOCK, UNLOCK, ADD_CONTENT, DELETE_CONTENT, GET_CONTENT, ANSWER, ASSIGN, PROMOTE, REVERT, VERSION) and this comparison is case sensitive. Always declare the action in upper case: an action written answer is not recognised as ANSWER, and the fact loses the display associated with the action. The lower case forms used by the fact.registrations.* properties are configuration values, they do not apply to the action carried by a fact.

Custom Facts

A custom fact is created outside the product's native historical logs. It can be used by integrators to trace specific actions based on their needs. It can be:

• A business fact : Traces a business action (e.g., creating a letter).
• A technical fact : Traces a technical operation (e.g., integration with a CRM).

The distinction is made via a boolean, but the underlying Java object is the same. When creating custom facts via an OperationHandler, the user logged in the fact will, by default, be the administrator executing the OH. This is due to administrative privileges that ensure security and prevent unauthorized manipulation.

If you want to log the actual user who initiated the action, you can customize the description.

Example using FactBuilder:

var builder = FactBuilder.objectId(component.getId()).type('DOCUMENT');
var userDisplayName = util.getUserService().get(...).getDisplayName();
builder.action('CREATE').description(userDisplayName + ' created the document.');
util.createFact(builder.build());

Fact icons

In the history view, every fact is displayed with an icon. Facts using one of the following actions always get the icon of that action.

Action	Icon
CREATE	fa fa-plus
UPDATE	far fa-edit
ADD_CONTENT	far fa-file-alt
DELETE_CONTENT	far fa-file-alt
VERSION	far fa-file-alt fa-inverse
REVERT	fas fa-undo

For any other action, including ANSWER, SEARCH and the custom actions carried by business facts, a fact has no icon of its own: the icon is resolved from the fields declared in updatedFields, in this order.

Order	Source	Scope
1	The fd_icon field	All categories
2	Icon Resolver registered in the JavaScript API	All categories
3	The icon of the class referenced by the classid field	Tasks only
4	The default icon fas fa-thumbtack	All categories

warning

A business fact created without fd_icon and without classid is displayed with the default thumbtack icon, whatever the action it records.

Referencing the component class

Setting classid is the recommended approach for tasks. The icon is then read from the task class, so updating the class icon updates every fact referencing it, and the behaviour is aligned with the technical facts generated by FlowerDocs Core.

Script

var builder = FactBuilder.with(component).action("ANSWER").description("Answer applied.");
if (component.getClassId() != null) {
    builder.field("classid", component.getClassId().getValue());
}
util.createFact(builder.build());

HTTP

POST {core}/rest/tasks/{id}/facts HTTP/1.1
token: {token}
Content-Type: application/json

{
    "action": "ANSWER",
    "description": "Answer applied.",
    "updatedFields": [
        {
            "name": "classid",
            "value": "IncomingMailProcessing"
        }
    ]
}

Setting the icon explicitly

The fd_icon field holds a Font Awesome class and takes precedence over both the Icon Resolvers and classid. Use it for documents, folders and virtual folders, whose class icon is not resolved, or when the icon must not follow the class.

Script

var builder = FactBuilder.with(component).action("SEARCH").description("Search performed.");
builder.field("fd_icon", "fas fa-search");
util.createFact(builder.build());

HTTP

POST {core}/rest/documents/{id}/facts HTTP/1.1
token: {token}
Content-Type: application/json

{
    "action": "SEARCH",
    "description": "Search performed.",
    "updatedFields": [
        {
            "name": "fd_icon",
            "value": "fas fa-search"
        }
    ]
}

Resolving the icon from tags

An Icon Resolver is evaluated against a component rebuilt from the fact's updatedFields alone, not from the component the fact is attached to. Every tag the resolver reads must therefore be present in updatedFields, including classid when the resolver reads the class.

var builder = FactBuilder.with(component).action("VALIDATION").description("Mail validated.");
builder.field("MailType", RuleUtil.getTagValue(component, "MailType"));
util.createFact(builder.build());

warning

An Icon Resolver applied to a fact must answer synchronously, by calling callback.onSuccess() before returning. The resolved icon is read immediately after the resolver is invoked, so a resolver that answers later, for example after a search, arrives too late and the fact falls back to classid or to the default icon.

info

Icons are resolved when the fact is displayed, but from the fields stored on the fact. Adding fd_icon or classid to a fact creation only affects the facts created afterwards: facts already stored keep the default icon.

History configuration

FlowerDocs provides a document class FactFieldsConfiguration that lets you simply define the tags to be historised on generated facts.

This document allows you to define:

• the object type: DOCUMENT, TASK, VIRTUAL_FOLDER, FOLDER
• component class identifiers
• tag identifiers

This configuration document is accessible from the FlowerDocs administration interface: Configuration > Historical facts.