When the standard options in KIC can’t offer what you need, you’ll resort to scripts. As of KIC 2.4, there are three different scripts you can utilize: a batch renaming script, an advanced batch/document script, and a reroute script. From these three, you’ll probably use the advanced document script the most. It has access to all messages and their attachments, allowing you to manipulate then, change the import sequence, extract data from embedded files, and so on. The biggest shortcomings of these scripts is the documentation, however. That’s what I’d like to change with this post: understanding the script’s sequence is vital to understand of what they really are capable of.

Let’s start with some general background knowledge. While I constantly refer to them as scripts, technically that is incorrect. It’s true that you write text files, but contrary to scripts these files will be compiled into a DLL during runtime, while normal scripts such as php are just interpreted. Compilation happens when you start the service out of KCPlugin – should you have a syntax error in your code, compilation and thus start up of the service will fail. This also means that you’ll have to restart the service every time you make changes to your code. Now, when any rule applies to the destination your script is being assigned to, a concrete instance of your class will be created. That is also important to know: this instance seems to be held in memory until you restart the service. So, when using properties in your script, keep in mind that all messages processes share them, even across multiple instances of batches created!

And while I will focus on the sequence in the advanced batch/document script, the general sequence of scripts is also important to know:

First comes rerouting, a feature introduced with KIC v2.4. This powerful script allows you to reroute a batch to another destination. Thereafter batch renaming takes place, and finally, the advanced batch/document script is executed. Remember, as I said earlier, when I say “executed”, what I really mean is that the respective methods are called. The instance of your script is held in memory! In the advanced document script, there’s another sequence of actions that you have to memorize. There are three events only, but they are called in a distinctive sequence.

First, there’s the ManageMessageFiles method. This method will be called for each message that’s being assigned to the current batch to be created (as you can group messages together). The method will be called once for each message, right after one other. For example, when you process emails and your destination allows grouping messages of up to 3, this method will be called 3 times in a row – once per message (not considering timeouts and potentially smaller batched here). You may modify the messages’ content here. Then, the BeforeMessageImport method is called, followed by the BeforeDocumentImport. Here’s the tricky part, so I rely on images instead of words:

As you can see, the BeforeDocumentImport method is called directly after BeforeMessageImport. If you checked the option “create document per attachment” in your destination, BeforeDocumentImport will be called multiple times! Then, after all respective documents were imported, BeforeDocumentImport is called again (for the next message), followed by BeforeDocumentImport, and so on.

Knowing the sequence of action is vital to understanding what you can change and where exactly you should do that. For example, KIC does not include an attachment index. And while the BeforeDocumentImport method will be called once per attachment (in our case, 3 times for message 2), you have no clue which attachment currently is being imported. All you have is a list of attachments – so you’d need an index. Naturally, you want to reset the attachment index in the BeforeDocumentImport method.