Newsletters
 |
Sawmill Newsletter November 15, 2009 |
Welcome to the Sawmill Newsletter!
You’re receiving this newsletter because during the downloading or purchase of Sawmill, you checked the box to join our mailing list. If you wish to be removed from this list, please send an email, with the subject line of “UNSUBSCRIBE” to newsletter@sawmill.net (please include the entire message, as the identifying information is at the bottom).
News
Sawmill 8.1.1 shipped on October 6, 2009. This is an bug-fix release--it fixes a number of bugs. This release is free to existing Sawmill 8 users. It is recommended for anyone who is experiencing problems with Sawmill 8.1.0 or earlier. You can download it from http://sawmill.net/download.html .
Sawmill 7 users can upgrade to Sawmill 8 for half of the license price; or if you have Premium Support, the upgrade is free. Major features of Sawmill 8 include support for Oracle and Microsoft SQL Server databases, real-time reporting, a completely redesigned web interface, better multi-processor and multi-core support, and role-based authentication control.
This issue of the Sawmill Newsletter describes how to use the new network API feature.
Get The Most Out Of Sawmill With Professional Services
Looking to get more out of your statistics from Sawmill? Running short on time, but need the information now to make critical business decisions? Our Professional Service Experts are available for just this situation and many others. We will assist in the initial installation of Sawmill using best practices; work with you to integrate and configure Sawmill to generate reports in the shortest possible time. We will tailor Sawmill to your environment, create a customized solution, be sensitive to your requirements and stay focused on what your business needs are. We will show you areas of Sawmill you may not even be aware of, demonstrating these methods will provide you with many streamlined methods to get you the information more quickly. Often you'll find that Sawmill's deep analysis can even provide you with information you've been after but never knew how to reach, or possibly never realized was readily available in reports. Sawmill is an extremely powerful tool for your business, and most users only exercise a fraction of this power. That's where our experts really can make the difference. Our Sawmill experts have many years of experience with Sawmill and with a large cross section of devices and business sectors. Our promise is to very quickly come up with a cost effective solution that fits your business, and greatly expand your ROI with only a few hours of fee based Sawmill Professional Services. For more information, a quote, or to speak directly with a Professional services expert contact consulting@flowerfire.com.
Tips & Techniques: Using The Network API
Sawmill 8.1.1 introduces a Network API feature, which can be used to remotely control a Sawmill installation via HTTP (or HTTPS). This is useful for automating Sawmill as part of a larger environment; the Network API can be called by external scripts to perform various actions.
The initial implementation of the Network API does not provide full access to all features of Sawmill, but rather provides a mechanism by with remote actions can be implemented (potentially, by anyone); a few basic API actions are included in 8.1.1, and more will be added as they are implemented.
The Network API feature builds on the existing Custom Actions (a.k.a. Plug-in Actions) feature, which allows custom actions to be created and installed as CFG files in the "actions" folder of the LogAnalysisInfo folder. Network actions are special cases of Custom Actions; they are implemented using CFG files in the "actions" folder, and they can also be run from the command line with the "-a" option like any other custom action; but they have the added ability to be invoked through the web server, and to return an XML result.
All actions are documented in the Actions chapter of the Sawmill Technical Manual; the parameters listed there can be used either as command-line parameters, or as URL parameters (name=value, separated by &) to a network API call (which is indicated by a dp=action parameter in the URL).
Example: Creating A User
For instance, the network API can be used to create a new Sawmill user without using the web interface. Sawmill includes a standard custom action create_user, which takes the following parameters:
- uname (-u): the username of the new user to create
- pass (-pw): the password of the new user
- roles (-r): a comma-separated list of internal role names for the user (e.g., role_2 for Statistics Viewer)
- profiles_allowed (-pa): a comma-separate list of internal profile names for the user
sawmill -a create_user -u bob -pw bobspass -r role_2 -pa bobsprofile |
to create a user "bob" with password "bobspass" who is a Statistics Viewer allowed to view the profile "bobsprofile".
The Network API equivalent of this is this URL:
http://sawmill-server:8988/dp=action&a=create_user&u=bob&pw=bobspass&r=role_2&pa=bobsprofile&lun=admin&lpw=adminpass |
This is similar to the command line, except it's a URL (with the scheme, hostname, and port at the beginning), uses URL syntax for parameters, and includes the lun and lpw options to provide root administrator authentication. When this URL is accessed, either through a standard web browser or (more typically) from a script using HTTP, it will create the specified user.
The response to a properly-formed request will be XML, and will indicate the success or failure of the action, e.g.
<SawmillActionResponse> <Action>create_user</Action> <Result>Success</Result> <User>bob</User> <Roles>role_2</Roles> </SawmillActionResponse> |
Any custom action can be invoked in this way.
Advanced Topic: Extending The Network API
Because Sawmill's Network API is built on top of the existing Custom Actions feature, which is extensible, the network API itself is extensible. To create a new custom action, you can add a new CFG file to the actions folder of LogAnalysisInfo. For instance, the create_user API action is implemented with the following CFG file, create_user.cfg:
create_user = { label = "Create User" shortcut = "cu" parameters = { uname = { shortcut = "u" required = true } pass = { shortcut = "pw" required = true } roles = { shortcut = "r" required = true } profiles_allowed = { shortcut = "pa" required = false } } expression = ` # Create a new subnode of users, named after the username node users = 'users'; string uname_nodename = uname; uname_nodename = replace_all(uname_nodename, '-', '_'); node user = users{uname}; # Set the "username" subnode to the username @user{'username'} = uname; # Set the password checksum @user{'password_checksum'} = md5_digest(pass); # If the -pa option was specified, set which profiles this user can access if (profiles_allowed ne "(unspecified)") then ( # Build the "access.0.profiles" node from the profiles_allowed option (which is comma-separated profile names) split(profiles_allowed, ',', 'v.profiles_allowed_split'); node profile; foreach profile 'v.profiles_allowed_split' @user{'access'}{'0'}{'profiles'}{@profile} = @profile; ); # if profiles_allowed # Build the "access.0.roles" node from the roles option (which is comma-separated node names) split(roles, ',', 'v.roles_split'); node role; foreach role 'v.roles_split' @user{'access'}{'0'}{'roles'}{@role} = @role; # Save the users.cfg file save_node(users); # Generate the XML result, for use in network action node result = new_action_result(command_line.action); @result{"Result"} = "Success"; @result{"User"} = uname; @result{"Roles"} = roles; string xml_result = action_result_to_xml(result); xml_result; ` # expression } # create_user |
The CFG node format is documented in the Technical Manual under the Custom Actions chapter.
Professional Services
This newsletter describes a specific use of Sawmill's Network API feature. This functionality can be used to remotely control Sawmill, to remotely administrate it, query it, and integrate it into any environment. If you need assistance with creating custom API actions, or using the standard ones, or with any other Sawmill tasks, our Sawmill Experts can help. Contact sales@sawmill.net for more information.
[Article revision v1.0]
[ClientID: 43726]