Background for writing your own Actions

Although Xinet has supplied a set of simple, common Actions, you are not limited to using those to automate your workflow. Depending upon your skill-set, writing Actions for use with Xinet is not a difficult task. If you are comfortable scripting or coding in any language that is executable on the server of your choice, then writing Actions should be within your grasp.

Before you start to write an Action, have a specific workflow task in mind. Just as you must carefully plan how to implement Xinet Trigger Sets in a workflow, you must also carefully consider what task your new Action will accomplish in that workflow. In the ideal case, you should divide your workflow into discrete pieces that can be easily coded individually. Then, you can link them together in the proper order when you add these Actions to a Trigger Set.

Be certain you have a clear understanding of how Actions function. Examine the Actions supplied with Xinet carefully before you embark on writing your first custom Action. Consider how the settings affect the outcome of the Action when it executes.

To create predictable workflows using Actions, each Action should have only one success case. Because of the way Actions and Trigger Sets are constructed, you will have more success writing Actions that perform simple tasks rather than one monolithic Action that performs an elaborate series of tasks. Using several small Actions not only gives you flexibility, but also the opportunity to triangulate failures and troubleshoot effectively.

When an Action exits with status 0, Xinet considers the Action to have exited successfully. Any non-zero exit status signals to Xinet that the Action failed, and the failure case associated with that Action/Trigger rule will be executed. Examining the supplied copy Action, note that there are two different non-zero exit statuses: -1 if the Action is called with incorrect syntax, and -2 if there is a file-system state that disallows the action to continue (for example., the destination is missing). Although you may have several non-zero exits to assist you in troubleshooting the Action in case of future failure, the Trigger rule will only notice whether or not the exit status of the Action was non-zero and behave as configured. Take this into account when planning your Trigger and Action workflow.

Consider also how your configuration file should be structured to provide both a useful interface to the administrator and correct data to the Action itself. Will you require a .buildconfig file to generate your .conf file? Will your user be able to type in settings, or will they be limited to a pull-down menu?

Finally, you should evaluate any security issues that may be introduced by this Action. Remember that all Xinet Actions run with rootly powers (SYSTEM on Windows), and therefore should be written carefully and deliberately to prevent accidental data deletion or damage. Because Actions are powerful, they can also be dangerous. Verify that any script-based Actions you write are neither readable or writable to non-root users. Further, examine your Actions to ensure they do not use any inherently dangerous commands. For example, if you have a script Action that will remove a directory ($dir) using the command rm –rf $dir, and for some reason $dir is incorrectly set to /mount/point/of/raid by error or accident, executing the Action will have a catastrophic result. Consider the most damaging thing that could happen when running your Action, and try to prevent those possibilities inside your code.

Syntax and execution

The syntax for an Action’s execution is determined by the settings file and configuration as described above. Also, you should review the List of Actions for a discussion of environment variables that you can use within your Action. You are not limited by which language to use when writing Actions, but you are limited by what name your Action may have. On Windows, Actions may either be named name_of_action.exe or name_of_action.bat. On Unix, Actions must be named without any extension.

For an example of an Action that is neither compiled nor written in csh, you may wish to review the file /usr/etc/webnative/actions/transfer/transfer.zsh. A cousin to ksh, zsh is included with all OS X systems while ksh is not. If you are familiar with ksh, then syntactically, this version should be familiar to you. Compare it to the csh version of the transfer Action — /usr/etc/webnative/actions/transfer/transfer. You may prefer to write the Action in Perl, C, or C++. So long as it is executable and runs following the execution syntax described in the settings/configuration files, any programming language is acceptable for an Action.

Refer to Xinet TechNote 0297, Adding a custom Action to apply metadata inheritance, available at www.northplains.com/xinet for an example of a custom Action.