View source for HowTos/Auto Actions

[[Scalix Wiki]] -> [[How-Tos]] -> '''Auto Actions'''
== Introduction ==
Auto Actions are the Scalix method of representing server-based rules. They are linked to a users personal mailbox as a whole and are usually applied to incoming messages as they are received.

''Note: This is work in progress and incomplete. Currently, for the first release of Scalix Wiki, it is an example of how things will look like here.''

== Setting up Auto Actions ==
Auto Actions can be setup in multiple ways. Commonly used are to explicitly setup Auto Actions are:
* The Outlook Out of Office Assistant
* The Scalix Rules Wizard in Outlook
* The Web-based server rules wizard
* The sxaa tool 
In some cases, they are also setup implicitly:
* When setting up delegate access for a Outlook user, including forward of calendar items

== Auto Actions Implementation on the server ==

=== The 3d file ===
Within Scalix you can set up quite a number of Auto Actions for a user. We are all used to
auto answer messages and the auto forward facility. Indeed, we can set these from within most of the Scalix clients. There are other Auto Actions offered by Scalix that are not directly accessible from some (if any) of the clients. These are facilities like auto print, auto file, auto notify ...

When Auto Actions are setup for a user, a file is built in this user’s "home" directory, specifying what AutoActions are to be performed, that is, whether you want auto reply and/or auto forward and/or auto print, etc... All this is specified in one Auto Actions file - the 3d file in the user’s so-called "g" directory.

The 3d file is in Transaction File format. This is one of some Scalix-specific binary file formats. As it is a binary format, the 3d file cannot be edited directly. However, Transaction File format files can be converted to/from plaintext using the tf.browse tool provided by Scalix.

=== The User's "g" directory ===
This is a place where a lot of mailbox-specific information is stored. For a given user, it can be found using the -f option to the omshowu command. See the following example:

 [root@demo root]# omshowu -n sxadmin -f
 Authentication ID: sxadmin
 User Name : sxadmin /CN=sxadmin
 MailNode : scalix,demo
 Internet Address : sxadmin@demo.scalix.com
 System Login : sxadmin
 Password : set
 Admin Capabilities : YES
 Mailbox Admin Capabilities : NO
 Language : C
 Virtual Vault : Enabled (default)
 Mail Account: Unlocked
 Last Signon : Never.
 Receipt of mail : ENABLED
 Service level : 0
 Excluded from Tidying : NO
 User Folder : ~/user/g000035/00000v8:1
 User Class : Full

Note the ''User Folder'' line. The directory, in which the user folder is contained, is the user's home - or "g" - directory. The ~ represents the Scalix main data directory for your Scalix instance, so for the example user here the g directory would normally be /var/opt/scalix/user/g000035.

The "3d" file containing the Auto Actions will be called 000003d and is located in this directory.

=== 3d file Example ===
You can display the 3d transaction file by using the tf.browse command with the -i option, e.g.:

 [root@demo g000035]# tf.browse -i 000003d
 HEADER            (DN)  1  0  2  1002  0x0  0x0  0  0x0  0x0  0x0  0x0  0x0  ""
 AA_NO             ()  0x0  500  0  0  0  0  "SXAA FORWARD:500"  ""  ""  ""  ""
 AA_SIMPLE_FORWARD ()  0x0  0x1  1167  0  0  ""  "ISO8859_1"  ""  ""  ""  ""  "\
 "  ""  ""  ""

This shows a "forward" Auto Action as created by the sxaa command from the Scalix Admin Resource Kit.

==== Elements of the 3d file ====
Each transaction file is made of records. In the example above, there are 3 records, one HEADER record (1 per file), 1 AA_NO record (one per Auto Action; there can be any number of Auto Actions in a single 3d file) and the actual action record, in this case a forward record.<br><br>

* The '''HEADER''' record:<pre>HEADER (DN) 1 0 2 1002 0x0 0x0 0 0x0 0x0 0x0 0x0 0x0 ""</pre>This will be the same for every 3d file, so if you create your own 3d file from scratch, you would just copy/paste this record. It consists of multiple fields, each separated by spaces in the ASCII version. The first and second field indicate that this is a Scalix Transaction File ("1") and the default version ("0") of that. The most important fields will be the 3rd and 4th field - the 3rd field ("2") indicates that this is a Class-2 transaction file, used to store "basic" information (such as Auto Actions. Class-0 and Class-1 transaction files are actually used to transfer messages through the system - which is the main application of transaction files; the 4th field ("1002") is the transaction file type, with 1002 indicating that this is an Auto Action file. The remaining fields are set to empty/default values because they have no meaning for Class-2 Transaction Files.<br><br>
* The '''AA_NO''' record:<pre>AA_NO () 0x0 500 0 0 0 0 "SXAA FORWARD:500" "" "" "" ""</pre>This is the header for the one Auto Action we have in the file. Again, it consists of multiple fields. Most of the "0" or "" values denote empty fields and default values and would be left as such for most examples. However, a few a relevant: The first field ("0x0") indicates that the Auto Action is enabled. If set to "0x1", it would be disabled. The second field ("500") is the Auto Action sequence number; each action must have a unique number within the file. Some methods of creating Auto Actions (e.g. the Outlook Out Of Office assistant) always use the same number so that they can recognize Auto Actions created by them. The 7th field ("SXAA FORWARD:500") is a comment describing the Auto Action. This was put in there by the sxaa command to denote that very fact.<br><br>''Note: The command used to create this Auto Action was:''<pre>sxaa --user sxadmin --forward demo@scalix.com</pre><br>
* The '''AA_SIMPLE_FORWARD''' record:<pre>AA_SIMPLE_FORWARD () 0x0 0x1 1167 0 0 "" "ISO8859_1" ""  "" "" "" "" "" "" ""</pre>This indicates the actual forward action. For the time being, we just treat this as a command that must be left this way.<br><br>
In the example, some important piece of information seems to be missing. The Auto Action file contains no record whatsoever about where the message is to be forwarded to. (demo@scalix.com). This is where other files come in. Depending on the type of Auto Action, further information might be required. In this specific case, it is a distribution list (list of recipients). The distribution list for a "forward" Auto Action is stored in another file in the user's g directory; the filename for this would be '''000003e.XXX''' where XXX is the sequence number of the action that this file belongs to. In the example, this would be 500 as per the second field of the AA_NO record. The distribution list is kept in Transaction File format as well:

 [root@demo g000035]# tf.browse -i 000003e.500
 HEADER            (DN)  1  0  2  1000  0x0  0x0  0  0x0  0x0  0x0  0x0  0x0  ""
 DL_COUNTS         (DN)  0x0  1  0  1  0  0  0  0  0  0
 TO       (0x1000 + DN)  70/1/1 00:00.00  0x0  "S=demo/OU1=internet/DDT1=RFC-822/\
 DDV1=demo@scalix.com/CN=demo/INTERNET-ADDR=demo@scalix.com"  ""  ""  0x2  ""

This transaction file has 3 records. The '''HEADER''' record has only one difference to the Auto Action file header; the Transaction File Type is 1000 (Distribution List). The other records are to be interpreted as follows:<br><br>

* The '''DL_COUNTS''' record:<pre>DL_COUNTS (DN) 0x0 1 0 1 0 0 0 0 0 0</pre>The record is mandatory for distribution list Transaction Files. The second field ("1") has to total number of recipients in the TF. The fourth field ("1") is the number of "TO:" recipients; the fifth and sixth field would indicate "CC:" and "BCC:" recipients. The other fields are used to track errors; this is only used in Class-0 and Class-1 situations where a DL TF contains the actual routing information for a message in transport.<br><br>
* The '''TO''' record has the actual recipient information. The first two fields are not used in this case and indicate last date, time and timezone for acknowledgements received. The third field contains flags; this is set to the default. The fourth field contains the recipient in X.400 format. The last set of flags ("0x2") indicate that this is a "normal" recipient (not a distribution list, etc.)

=== Possible Action types ===
The '''AA_SIMPLE_FORWARD''' action type has been demonstrated in the example. Other action types are possible as well:

==== AA_REDIRECT ====
The '''AA_SIMPLE_FORWARD''' action type wraps the message into another message as an attachment, so the forwarded message will appear as coming from the mailbox owner. the '''AA_REDIRECT''' action type actually retains the original sender and redirects the message to another recipient. A sample '''AA_REDIRECT''' action record looks like this:
 AA_REDIRECT () 0x0 0x0 0 "S=demo/OU1=internet/DDT1=RFC-822/DDV1=demo@scalix.com/\
 CN=blah/INTERNET-ADDR=demo@scalix.com"
Note that because a redirect can only ever go to one recipient, the recipient X.400 address is kept right in the action and not in a separate DL TF.

==== AA_SIMPLE_REPLY ====
The '''AA_SIMPLE_REPLY''' action type sends a reply to the sender of the message triggering the Auto Action. A sample record looks like this:
 AA_SIMPLE_REPLY () 0x0 0x8 1167 0 0 "" "ISO8859_1" "Auto-Reply: " "" "" "" ""
Here, the flags value ("0x8") indicates that the subject supplied within the rule should be prefixing the subject of the original message. The 1167 is the filetype of the reply message; 1167 stands for plain text. The character set of the plain text message must be identified - in most cases this will be "ISO8859_1". The next field after that is the subject (or subject prefix as indicated by the flags value; if the flags value is set to "0x1" instead, the subject is actually replaced instead of prefixed). 
The actual text of the auto reply is kept in a separate file. The filename for this is 000003g.XXX where again XXX is the sequence number from the '''AA_NO''' record.

==== AA_FILE ====
The '''AA_FILE''' action type moves the message to a specified folder. A sample record looks like this:
 AA_FILE () 0x0 0x0 0 0 "Demo Folder" "" "" "" ""
Using this action, the message is moved to a folder called "Demo Folder" automatically on arrival. If the folder does not exist, it is created.


=== Combining multiple Auto Actions ===
t.b.d.

=== Setting up Filters===
t.b.d.

== Interoperability ==
t.b.d.

== Logging and Troubleshooting ==
t.b.d.