From e80d16157f7bd3d6c3efc38008f5c1379fa09da3 Mon Sep 17 00:00:00 2001
From: "j.goderbauer" <j.goderbauer@adito.de>
Date: Fri, 17 May 2019 10:49:00 +0200
Subject: [PATCH] added Loghistory-guide

---
 others/guide/Loghistory.adoc | 87 ++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 others/guide/Loghistory.adoc

diff --git a/others/guide/Loghistory.adoc b/others/guide/Loghistory.adoc
new file mode 100644
index 0000000000..6a2f284bf8
--- /dev/null
+++ b/others/guide/Loghistory.adoc
@@ -0,0 +1,87 @@
+configure Loghistory
+====================
+:DATA_ALIAS: Data_alias
+:EDITOR_ALIAS_DEFINITION: AliasDefinition-Editor
+
+== the concept ==
+//TODO: extend the concept description
+Stoarge: Database-table: `AB_LOGHISTORY`
+
+Collecting Data:
+----
+Audit -> process_audit -> Loghistory_lib: LogHistoryExecutor 
+----
+
+Data is collected and pre-translated. Therefor only one Language can be applied for logging.
+Because the loghistory is written via the auditing, only changes that are done with the proper Jdito-Methods will be logged.
+
+== prerequisites ==
+
+Auditing has to be activated for all tables you want to log.
+
+.prerequisites of enabling Audit in general
+* Auditing has to be enabled in your Server
+* Auditing has to be enabled for your alias (default: +{DATA_ALIAS}+)
+* Tables that shall be logged need some configs in the _{EDITOR_ALIAS_DEFINITION}_
+** property `idColumn` has to be set (a primary key is needed therefore)
+** `auditMode` has to be set -Standard, -CLOB, or -BLOB (chosse the one you really need)
+
+
+== activate writing into loghistory ==
+
+Assuming that the 
+
+* required database-tables exist 
+* JDito-processes already exist
+* audit has been activated in general
+
+you are ready to configure _which_ column shall be logged and _how_.
+
+=== configure columns for logging ===
+
+There are several properties (custom and pre-exisiting) that can be set for configuring the logging:
+
+.configuration options per column
+[options="header"]
+|=======
+|property |purpose |property-type
+|+title+ |text that is used to display which column has been modified|pre-exisiting
+|+log+ |defines whether a column needs to be logged or not; not exisisting equals `false` |custom: Booelan
+|+tableRef+ |references table for automatically grouping data. This is usefull for ForeignKeys, e.g. a +OFFERITEM.OFFER_ID+ column could have a +tableRef+ "OFFER"|custom: String
+|+primaryKey+ |this is not only used to enable auditing generally, but it's used to resolve +tableRef+ values correctly|pre-exisiting
+|+keyword+ |defines a keyword contianer that should be used to transform a +KEYID+ into a display value|custom: String
+|+autoMapTrueFalse4Log+ |if `true` the loghistory-executor tries to automatically translate a value into a "yes"/"no"-display value|custom: Booelan
+|+translate4Log+ |defines a process to transform a technical value into a display value |custom: JDito
+|=======
+
++translate4Log+ is a mighty possibility to translate a ID-value into a displayvalue. However, you should keep several important things in mind:
+
+* translate text if necessary via the locale-parameter
+* the process is called each time a change to that column is applied - keep it fast and simple
+
+.translate4Log example (skip imports for better readability)
+[source,javascript]
+----
+var params = Translate4LogParams.load();// <1>
+var countryName = CountryUtils.getLatinNameByIso2(params.value, params.locale); // <2>
+result.string(countryName);// <3>
+----
+<1> load the parameters in a easy and fail-proof way
+<2> locale is passed to the resolving function and in that function a translation is applied
+<3> always return a string
+
+=== configure a consumer for retrieving the loghistory ===
+
+.Exampel for the +tablenames_param+ process
+----
+import("system.vars");
+import("system.result");
+import("Context_lib");
+
+var res = [];
+res.push({id: vars.get("$field.CONTACTID"), tableNames: ["CONTACT", "COMMUNICATION", "ADDRESS", "AB_ATTRIBUTERELATION"]});
+res.push({id: vars.get("$field.PERSONID"), tableNames: ["PERSON"]});
+
+res = JSON.stringify(res);//currently only strings  can be passed as param
+result.object(res);
+----
\ No newline at end of file
-- 
GitLab