{= include("docs.util"); start_docs_page(docs.technical_manual.page_titles.newsletters); =}

Sawmill Newsletter

September 27, 2011

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.5.1 is now available. This is the final, production release of the new Sawmill 8.5 version, which is a major upgrade to Sawmill 8. It is also a free upgrade to Sawmill 8 (though your profiles and databases will need to be converted). You can download Sawmill 8.5.1 from http://sawmill.net/download.html . Please send your feedback about your experiences with Sawmill 8.5.

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 gives an example of the use of snapons, a new feature of Sawmill 8.5, to make edits to a profile. We create a new snapon to change the number of visible rows of every report to 100.

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: Creating a Snapon To Automate Profile Edits

Sawmill 8.5 includes a major new feature called snapons. Snapons are components which can be attached to a profile, or detached from a profile, and which add functionality to the profile. Snapons are a very general application, and can be used to make almost any change to a profile, including adding fields (log, database, or report fields), adding log filters, adding database filters (see below), adding reports, or other operations. Snapons can be attached or detached from a profile even after the database has been built, and do not require a rebuild.

Snapons can also be created by Sawmill end users with experience in Sawmill's CFG format and Salang language. In this newsletter, we create a simple snapon which changes the number of visible rows in all reports to 100. This is a very tedious edit to do by hand, but once a snapon has been created, it is just a few clicks.

The Full Snapon

Snapons are created by adding a text file with a .CFG extension to the snapons folder within the LogAnalysisInfo folder. Here is the contents of the file LogAnalysisInfo/snapons/set_all_reports_rows.cfg (this file will be included in Sawmill 8.5.2 and later):

# # set_all_reports_rows snapon # # This snapon sets the number of visible rows for all report elements of all reports, to a specified value. # # set_all_reports_rows = { label = "\$lang_admin.snapons.set_all_reports_rows.label" comment = "\$lang_admin.snapons.set_all_reports_rows.comment" config_snapon_category = "" parameters = { number_of_rows = { parameter_value = "100" validation_type = "int" min = 1 form_element_label = "\$lang_admin.snapons.set_all_reports_rows.parameters.number_of_rows.form_element_label" form_element_type = "text" form_element_width = "220" description = "" } # number_of_rows } # parameters parameters_form = { group_1 = { description = "\$lang_admin.snapons.set_all_reports_rows.parameters_form.group_1.description" parameters = { number_of_rows = true } # parameters } # group 1 } # parameters_form attach_operations = { set_rows = { type = "execute_expression" expression = ` # Get the reports node in the profile node reports = profile{"statistics"}{"reports"}; # Iterate through all reports node report; foreach report reports ( # Iterate through all report elements in this report node report_elements = report{"report_elements"}; node report_element; foreach report_element report_elements ( # If this report element has a "number_of_rows" subnode (i.e., if it's a table report), change it to the number_of_rows snapon parameter. if (report_element?{"number_of_rows"}) then @report_element{"number_of_rows"} = "{= @parameters{'number_of_rows'}{'parameter_value'} =}"; ); # foreach report_element ); # foreach report ` } # set_rows } # attach_operations } # set_all_reports_rows

all_reports_rows.cfg

This file depends on the modifications to lang_admin.cfg described below in Language, so if you're using Sawmill 8.5.1 or earlier, to use this snapon you need to (1) put the attached all_reports_rows.cfg file in LogAnalysisInfo/snapons, and (2) put the attached lang_stats.cfga file in LogAnalysisInfo/languages/english . These changes will be included in Sawmill 8.5.2 and later, so no extra installation will be required.

Using The Snapon

To use the snapon, attach it to a profile by going to the profile's Config -> Snapons in the web interface of Sawmill, clicking "Set All Report Rows," setting the number as desired, clicking Next, and clicking Finish. All reports will now show the specified number of rows.

Let's go through the parts of this snapon in order.

The CFG Header and Footer

# # set_all_reports_rows snapon # # This snapon sets the number of visible rows for all report elements of all reports, to a specified value. # # set_all_reports_rows = { ... } # set_all_reports_rows

The top and bottom of the file are the CFG header and the CFG footer. CFG files contain nodes (a node is Sawmill's main data structure, corresponding to a "map" or a "hash" or a "struct" in other languages). The first few lines are a comment. The "set_all_reports_rows = {" line is required at the top of a CFG file, and the node name specified there must match the filename (minus the .cfg extension). The final row is the closing curly bracket for the node, and a comment to help associate it with the opening bracket. By convention, closing curly brackets in CFG are tagged with this comment.

The Snapon Label and Comment

label = "\$lang_admin.snapons.set_all_reports_rows.label" comment = "\$lang_admin.snapons.set_all_reports_rows.comment" config_snapon_category = ""

The first few lines within the snapon node are the label of the snapon, or how it will appear in the list in the Snapons section of Config, the comment that will appear there, and the category which you can leave empty.

Here and elsewhere in this snapon, you will see references to \$lang_admin. These are necessary if the snapon is going to be translated into other languages. If you're just creating a quick snapon for your own use, you don't need to add this translation layer, and you can just enter text directly in the quotes. For instance, you could use this instead:

label = "Set All Report Rows" comment = "This snapon sets the number of rows of every report element to a specific value." config_snapon_category = ""

If you do use \$lang_admin, you need to add the appropriate translated text to LogAnalysisInfo/language/english/lang_admin.cfg, or to your own language file if you're not using English. See below for an example of the language information added to lang_admin.cfg.

The Parameters Node

... parameters = { number_of_rows = { parameter_value = "100" validation_type = "int" min = 1 form_element_label = "\$lang_admin.snapons.set_all_reports_rows.parameters.number_of_rows.form_element_label" form_element_type = "text" form_element_width = "220" description = "" } # number_of_rows } # parameters parameters_form = { group_1 = { description = "\$lang_admin.snapons.set_all_reports_rows.parameters_form.group_1.description" parameters = { number_of_rows = true } # parameters } # group 1 } # parameters_form ...

The "parameters" node tells Sawmill what to prompt for when the snapon is attached through the web UI. In this case, there is one parameter, the number of rows. The default parameter value is 100, it is an integer with a minimum value of 1, it is a text field with width 220, and its label is as defined in lang_admin (again, you could just enter the label here directly, like "Number of Rows").

The "parameters_form" node tells Sawmill how to lay out the forms it uses to prompt for parameters. Each group is a separate page of prompts. group_1, in this case, is the only page, and it shows a description at the top of the page, and prompts for one parameter, number_of_rows. This is a very simple snapon, with just one parameter; see the "sessions" snapon for an example with many pages of parameters, with many types.

The Attach Operations

... attach_operations = { set_rows = { type = "execute_expression" expression = ` # Get the reports node in the profile node reports = profile{"statistics"}{"reports"}; # Iterate through all reports node report; foreach report reports ( # Iterate through all report elements in this report node report_elements = report{"report_elements"}; node report_element; foreach report_element report_elements ( # If this report element has a "number_of_rows" subnode (i.e., if it's a table report), change it to the number_of_rows snapon parameter. if (report_element?{"number_of_rows"}) then @report_element{"number_of_rows"} = "{= @parameters{'number_of_rows'}{'parameter_value'} =}"; ); # foreach report_element ); # foreach report ` } # set_rows } # attach_operations ...

Finally, there's the section that does the actual work of the snapon. When it is attached, what effect does it have on the profile, the database, etc.? Most snapons add fields, install filters, etc., but this simple snapon has just one attach operation, "set_rows", which is a Salang expression (type="execute_expression"), and just runs a bit of Salang code. The code iterates through all reports in the profile, iterates through all report elements in each report, and changes the number of rows.

That's it; attaching this snapon will change all the report elements to show the specified number of rows. This is an unusual snapon in that it doesn't really need to stay attached; it has no effect when it's detached. A more advanced version of it would create a detach_operations node that would restore the number of rows to the values they had at attach time and would require saving those values in the profile during the attach stage.

Translation

If translation is required (support for this snapon in multiple languages), the \$lang_stats references shown above must be used, and a section like the following must be added to lang_stats (within the snapons node):

set_all_reports_rows = { label = "Set All Report Rows" comment = "This snapon sets the number of rows of every report element to a specific value." parameters = { number_of_rows = { form_element_label = "Number of rows" } } # parameters parameters_form = { group_1 = { description = "Please choose the number of rows. All report elements of all reports in this profile will be set to display the specified number of rows." } } # parameters_form } # set_all_reports_rows

This node simply lists the values of all the translated variables from above, so for instance "\$lang_admin.snapons.set_all_reports_rows.label" will be expanded to "Set All Report Rows" in English, or to the appropriate phrase if another language is selected. Again, translation is not necessary for simple one-off snapons; it's included here because this snapon will become a standard part of Sawmill starting in 8.5.2, so it needs to be translated.

In the email version of this newsletter, the changes above are attached as a "CFGA" (configuration group addition) file, which can be dropped into LogAnalysisInfo/language/english to dynamically add these parts to lang_admin, and the snapon itself is attached as set_all_reports_rows.cfg, which can be dropped into LogAnalysisInfo/snapons.

Professional Services

This newsletter describes the creation of a simple custom snapon. Snapon creation requires some experience with scripting and programming, and not for the new Sawmill user. If you need assistance creating a custom snapon, our Sawmill Experts can help. Contact sales@sawmill.net for more information.

[Article revision v1.0]
[ClientID: 451828]

{= end_docs_page() =}