# The rule structure
This section describes the XML rule structure in ELOas. Normally, this structure is maintained using a graphical user interface or GUI. If you have to make manual changes, you can use this description as a reference. At the same time, this description serves as a reference for implementing the GUI.
# General structure
The complete structure is embedded in the <ruleset> tag. This consists of two parts: a <base> entry at the beginning, followed by any number of <rule> entries.
The <base> entry contains the information to search for the entries to be processed. These include the search rows, the search term, forms, and date restrictions.
The <rule> entries contain one processing instruction each. You can assign each rule a condition, change the filing target, or change the contents of the fields. Additionally, a rule can also have JavaScript contents. If defined as such, the other entries are ignored, but they can have values.
If the condition of a rule is "OnError", this rule is processed as an error handling rule. An error handling process can take place after every rule, and at the very end an error handling rule must be entered. These final error rules are called if an error occurs when moving or saving a file. If an error occurs during processing within a normal rule, the next possible error handling rule is called and processing is canceled.
Example of a simple ruleset:
<ruleset>
<base>
<name>Name of the ruleset</name>
<search>
<name>Metadata field name in JavaScript code</name>
<value>Search term in JavaScript code.</value>
<mask>Number of the metadata form for the search.</mask>
</search>
<interval>5M</interval>
</base>
<rule>
<name>Name of the rule</name>
<destination mask="Folder form"> New target in JavaScript Code</destination>
<index>
<name>Metadata field name in JavaScript code</name>
<value>New contents of the metadata field in JavaScript code</value>
</index>
</rule>
<rule>
<name>Name of the error handling rule</name>
<condition>OnError</condition>
</rule>
</ruleset>
# All entries in the <base> section
| Tag | Function | Example |
|---|---|---|
| name | Name of the ruleset. This name is displayed on the status page, but is not processed further. | SAP processing |
| search | Parameter for searching for the documents to be processed. For a description, see the following section All entries in the '<search>' section | |
| masks | If you have to switch to another metadata form during the course of processing, all possible target form (mask) numbers have to be listed here. Each form number is framed with a <mask> tag. | <mask>3</mask><mask>4</mask> |
| interval | Repetition interval for processing the search. This interval can be entered in minutes (5M) or hours (1H). Further, it can also be run once a day at a specific time (15:30), once per week (17:20/SA), or once a month (22:00/31). If a day is specified for monthly execution that does not exist for the current month (e.g. the 31st of February), the last day of the month is used instead. | 5M1H15:3017:20/SA22:00/31 |
# All entries in the '<search>' section
The entries in the <search> section determine which documents are processed. At the start of each pass, a search is performed with these parameters. The list of results is processed according to the rules.
<search>
<name>Metadata field name in JavaScript code</name>
<value>Search term in JavaScript code</value>
<mask>Number of the metadata form for the search.</mask>
<max>Maximum number of documents per pass</max>
</search>
| Day | Function | Example |
|---|---|---|
| name | Metadata field name in JavaScript code If the name is fixed, text can be entered directly in quotation marks. However, any JavaScript expression can be used as well. | "ELOOUTL2" |
| value | Search term in JavaScript code. If the value is fixed, text can be entered directly in quotation marks. However, any JavaScript expression can be used as well. | "ELO*" |
| mask | Number of the metadata form for the search. Only a metadata form can be used here, and not a pure search form, as it is assumed that all matches have the same form definition during read-in. | 2 |
| max | Maximum number of documents per pass sending a search query to the ELO Indexserver. If more matches exist, they are processed in a later pass after all other rulesets have been run. This prevents an extensive ruleset from suppressing the processing of all other rulesets. A maximum of 1000 documents per pass are allowed. | 200 |
idatexdate | The list of results can be restricted through a date range in the filing date (idate) or document date (xdate). This date can either be entered in absolute values in the ISO date format (YYYYMMDD) or in values relative to the current day (-5). The range consists of a start date in a <from> tag, and an end date in a <to> tag. | <idate><from>-5</from><to>+0</to></idate> |
# All entries in the '<rule>' section
After the <base> section, any number of <rule\> sections can follow. These are run in the order of the definition during processing.
A rule can exist in two different forms: as a normal rule and as an error rule. Such an error rule is simply skipped in the normal course of events. The next available error rule is only called in case of an error, and afterwards the processing of this document is canceled. This means that after an error rule is processed, no further rules will be processed.
The last rule in the <rule\> chain must always be an error rule. This ensures that error handling is always available in every case. Additionally, this rule is called if an error occurs while moving or saving a file.
| Tag | Function | Example |
|---|---|---|
| name | Name of the rule, only be used for documentation and to better understand its function. | Additional indexing |
| condition | Processing condition for the rule. If this is an error rule, the fixed text "OnError" is entered here. Note that it must be written exactly in this way, as otherwise the rule will not be recognized as an error rule. | KDNR == "123" |
| The execution condition is provided in the form of JavaScript code. The rule is only run if the condition is "true". | ||
| destination | New filing target of the document as the repository path. This entry is optional and can remain empty. In this case, the document remains in its original position. If there are multiple destination rules, the first target is used as a new filing location, and all additional targets are entered as references to the first. | <destination mask="1"> ¶ELO¶Mails¶" + ELOOUTL1</destination> |
| If a filing target does not yet exist, it is created automatically. | ||
| The destination tag can also contain an additional "mask" attribute with the number of the folder metadata form for newly created folders. If this attribute is not available, "1" is used by default, which is the number of the folder form in a standard repository. | ||
| mask | New document metadata form If this entry is not available or the form number is -1, the original metadata form is retained. | <mask>20</mask> |
| If the form is changed, all entries are automatically applied with the same group name. This is also executed correctly if the metadata fields are divided up differently between forms. | ||
| If the original metadata form contained fields that the new form does not have, this data is automatically discarded without returning an error message. | ||
| ELOas cannot process documents with metadata forms that use the same group names for multiple entries, as the internal processing and structure of the rules assume a unique assignment. | ||
| index | Any number of index entries can exist within a rule Each index entry contains the name of the relevant field and a JavaScript expression with the new value. | <index><name>DOCDATE</name> <value>"20070930"</value></index> |
| Fields with an ISO date and fields for the filing and document date also require the in ISO date format. | ||
| In addition to the fields with the group names of the search form, all group names of the alternative metadata forms are available, as well as a number of pseudo-fields with standard values for metadata: | ||
| NAME: Short name | ||
| DOCDATE: Document date | ||
| ABLDATE: Filing date | ||
| ARCHIVINGMODE: Document status 0, 1, or 2 for "Version control disabled", "Version control enabled", or "Non-modifiable". | ||
ACL: With "PARENT", apply the ACL of the new filing target. With <rights>:<name>, define any number of group rights. | ||
| OBJCOLOR: Color number of the entry | ||
| OBJDESC: Extra text | ||
| OBJTYPE: Document or folder type of the entry. Information: An incorrect assignment can lead to disruptions in further processing. Documents can only have an OBJTYPE between 254 and 286. | ||
| script | A rule can also contain JavaScript code to be run. In this case, all other parameters of this rule are ignored, but they can be retained, e.g. for documentation purposes. |
# Changing permissions
Changed permissions can be configured in the ACL pseudo-metadata field. In the simplest case, enter "PARENT" here, which will then apply the rights of the target folder to this entry when it is saved. However, a complete list of rights can also be configured here. This list consists of a sequence of individual rights that are separated by a pilcrow symbol. Each individual right consists of the rights form (RWDELP - read, write, delete, edit, list, permissions), followed by a colon and the group name. For AND groups, enter a sequence of names, each separated by a colon, instead of the simple group name.
R:Everyone¶RW:Controlling¶RWDELP:Administration:Stuttgart:Management
In the example, the Everyone group has read access, the Controlling group has read and write access, and the AND group Administration and Stuttgart and Management has full access to the document.
If you want to set rights for a user instead of for a group, add "U" to the list of rights as well.
UR:Administrator
# Notes
When generating the JavaScript code, all group names of the search form and the alternative metadata forms are entered as variables in all caps. This method minimizes the risk of group names overlapping with standard identifiers from JavaScript or the ELO runtime environment. In principle, however, it can lead to problems if one of the group names is identical to a standard identifier or one of the translation lists.
var NAME;
var ARCDATE;
var DOCDATE;
var OBJCOLOR;
var OBJDESC;
var OBJTYPE;
var ARCHIVINGMODE;
var ACL;
var EM_PARENT_ID;
var EM_PARENT_ACL;
var EM_SEARCHNAME;
var EM_SEARCHVALUE;
var EM_SEARCHCOUNT;
var EM_SEARCHMASK;
var EM_IDATEFROM;
var EM_IDATETO;
var EM_XDATEFROM;
var EM_XDATETO;
var EM_FOLDERMASK = "1";
Information
This list may be expanded in the course of project process. In particular, it can be expanded with additional entries through local customizing.
The number of the metadata form for the current document can be changed using a rule. However, if this results in an invalid form number or a number that does not exist in the list of alternative target forms, this will cause a runtime error when saving the document, and not when assigning the form.
If an error rule is called due to a runtime error, it will delete all already allocated filing targets of the previously processed rules. If the error rule does not have its own <destination>, the document remains at its original position. Otherwise, the target of the error rule is used.
Changed metadata is moved and saved at the end, after the last rule is processed. If this leads to an error, the last error rule is called, and not the error rule that belongs to the rule defining the target (which is, indeed, identical to what occurs when there is only a single error rule).
# Sample structure
The following provides a sample definition, along with a list of the code generated from it. This information is for orientation purposes only.
<ruleset>
<base>
<name>Thiele e-mail form</name>
<search>
<name>"ELOOUTL2"</name>
<value>"Thiele*"</value>
<mask>2</mask>
<max>2</max>
<idate>
<from>"-35"</from>
<to>"+1"</to>
</idate>
</search>
<masks>
<mask>12</mask>
<mask>13</mask>
<mask>20</mask>
</masks>
<interval>1M</interval>
</base>
<rule>
<name>Rule 1</name>
<destination mask="5">"¶Thiele¶E-mails¶" + ELOOUTL1</destination>
<mask>20</mask>
<index>
<name>ADDENTRY</name>
<value>getObjShort(2)</value>
</index>
<index>
<name>ELOOUTL2</name>
<value>"!!" + ELOOUTL2</value>
</index>
<index>
<name>DOCDATE</name>
<value>"20070930"</value>
</index>
<index>
<name>ARCHIVINGMODE</name>
<value>2</value>
</index>
<index>
<name>ACL</name>
<value>"PARENT"</value>
</index>
</rule>
<rule>
<name>Journal copy</name>
<destination mask="1">"¶Thiele¶Journals¶" + ELOOUTL1</destination>
</rule>
<rule>
<name>Script rule</name>
<script>
moveTo(Sord, "¶Repository¶Targets1¶" + ELOOUTL1);
moveTo(Sord, "¶Repository¶Targets2¶" + ELOOUTL2);
moveTo(Sord, "¶Repository¶Targets3¶" + ELOOUTL3);
</script>
</rule>
<rule>
<name>Global Error Rule</name>
<condition>OnError</condition>
<destination>"¶Thiele¶Error"</destination>
<index>
<name>ELOOUTL2</name>
<value>"!!" + ELOOUTL2</value>
</index>
<index>
<name>ARCHIVINGMODE</name>
<value>0</value>
</index>
</rule>
</ruleset>