In the Advanced XML, it is unclear to me what an intention is. It seems to me that it is an object that modifies a search that it in it's path in the module hierarchy, and that it is created by a "ConvertToIntention" module. Possibly they can be implicitly created by other modules.
I would simply like to know how to use ConvertToIntention to modify a search. It is severely under-documented in the developer documentation, given its apparent importance.
A couple of questions:
What is being converted to an intention? It looks like it is something called "Settings". What are these? Where do they come from? How can they be created, and how might I know about which ones exist at any given time?
How to I specify an intention to convert to? It appears that an "intention" is specified as some object, but there is no documentation about what types exist (I have seen "addterm" and "stringreplace"), and more importantly, what subitems may or must be specified inside them. And of course, what the subitems mean for each intention type.
In general, while the Advanced XML module docs (e.g., http://localhost:8000/modules ) list out the names of parameters, I have not been able to find any documentation or description of:
"Intentions" and "Settings" are just two of these objects (or whatever they are). It seems that "Searches" and possibly "Results" or "Events" or something like that might be other objects. I think the Advanced XML might be rather less obscure if this information were available somewhere.
I'll step into the frying pan here. The best explanation about how to work with the 'form search' modules, aka the 'lister' modules, is in the ui_examples app which is available on splunkbase.
The fact of the matter is that the developer docs on really practical app-development topics like this (and some other topics) may be lagging behind the ui_examples app. So there are docs pages that talk about intentions, but they dont answer any of these questions of yours. ( http://www.splunk.com/base/Documentation/4.1.4/Developer/AdvancedIntro ) the ui_examples app does however.
Almost all the 60 or so dashboards and form search examples in ui_examples use splunk's internal metrics data so you'll be able to see the examples working and you can experiment with them to learn how different params work for yourself.
Alright. You knew you were stepping into something. I will note that there is hardly any documentation on intentions. Only "addterm" and "stringreplace" exist in examples, and that is the extent of the documentation of them. It seems there is no reference on the parameters or behavior of specific intentions. There are mentions in some of the example text to the existence of many more intentions, none of which are documented in any way. There is no indication (except via implication) of which modules create/modify/destroy intentions, and which create/modify/destroy settings.
The UI examples, while helpful, do not provide this information, except via example. It turns out that the XML is inconsistent and sensitive, so if you want to do something that happens to deviate from the examples in certain ways, there is no way to know how (or even whether) it can be done. It seems to me that a minimum for a development framework should at least be a complete object reference.
I completely agree. I created the ui_examples app to fill the short- and medium-term need, and while some documentation has been pulled into the docs from it, deeper layers have not. For a while now, and underneath the module-level, we have had a large and increasingly stable body of code that amounts to a splunk client-side SDK, but whether that's a good thing, what exactly splunk should do with it and how/whether to document it -- these have been unsolved and largely unaddressed problems.
So this posting is out there since August 2010, I hope there is better documentation that I am having difficulty finding. Does anyone have any documentation on the above question. I am having the same difficulty.
In the meantime, you might want to take a look at the following file:
It seems to be responsible for the transforming part on the serverside when intentions are applied and might give you some insights on what's going on in the background.
Version 5.0 is out ... its Nov 2012 ... and still there is no improvement in the quality of this documentation for intentions, it seems! I wonder when this issue will be addressed systematically! Developers are left to their own devices to figure out many things on this front ... the 1970s again ...ohh, the nostalgic state of affairs!
Well, a huge number of people have switched to using Sideview Utils, because one of the big things it does is take away the need for intentions across the board. Get the latest version (2.2.2) from the Sideview site for free (http://sideviewapps.com/apps/sideview-utils), or you might already have the really old (1.3.6) version from Splunkbase installed and not realize it. Either way the app includes its own documentation.