Blog

 

So you’d like to… convert a simplified XML dashboard to Sideview Utils



Intro: There are two flavors of simple XML,  the <dashboard> and the <form>.   With both flavors, in terms of interface functionality they are both just limited shorthand forms of the “advanced XML”, which I just mention to reassure you that the conversion process is relatively reliable and you won’t necessarily lose anything.   And once you’re in the advanced XML, the steps to upgrade to Sideview Utils modules are each relatively simple.

Why Would I Do This? Although the range of user interfaces that you can achieve in the <form> and <dashboard> views is often enough to do what you need, you often hit limitations.  As you get more use cases, more drilldown requests and more team members involved,  Splunk users often feel constrained by one or more of these many limitations.   Often users will first convert to Advanced XML, and then suffer at that level for quite some time before finding out about the Sideview Utils modules.   I wrote this post because I believe if you’re going to convert to advanced XML,  you should just jump right then and there to Sideview Utils.

Prerequisites: 

Sideview Utils has a page “Key Techniques > Overview of the Advanced XML”.    Even if you’ve read that page already, go back now and read it again.    To really be able to comfortably convert the actual syntax for individual modules you should probably read through that module’s documentation in Sideview Utils…  Nonetheless quite possibly you’re about to read on without having done so and that’s fine.

Here’s How:

Step 1>  Convert the view to advanced XML.  You do this by simply going to the simplified <dashboard> or <form> view in your browser and tacking on ?showsource=true   to the URL in your browser’s location bar.   Then on the resulting page scroll down to the very bottom.   You’ll see a big textarea full of XML.   Copy and paste this XML out into a text editor, or Notepad or vi or whatever floats your boat.  This is the corresponding advanced XML for that simplified XML view.

Step 2> Save the raw converted view in Splunk.  You can save it in etc/apps/search/local/data/ui/views/my_converted_view.xml,  and use the FreshMaker to reload from disk,  or if you don’t know what the heck I’m talking about,   from the Search app, go to “Manager > User Interface > Views > Create”,  and paste the XML into the big texarea and give it a name like “my_converted_view” .

Step 3> View the converted view in the Splunk UI.  This step is easy.   Just go to  http://host:port/app/search/my_converted_view.   You’ll see an exact copy of the dashboard or form you just converted.    This is just a sanity check.  On we go.  Now that we have a working base view in advanced XML we’ll convert to Sideview Utils.

Step 4> Put a SideviewUtils module into the view.

Put it at the top, just underneath AppBar and AccountBar. We need this because all Sideview modules use shared code from the “SideviewUtils” module, and that shared module also patches a lot of the code in the core Splunk systems.

<module name="SideviewUtils" layoutPanel="appHeader" />

(after this step and each succeeding step, you should verify afterwards that the view still loads properly, that you don’t have a typo in the XML, and that it functions as expected.  Paranoia is good here because having to retrace your steps is bad.)

Step 5> clean out all the noise.  Unfortunately Splunk’s simplified XML does a lot of strange things that make no sense, or that almost always make no sense.  This step is optional but it will make your view a lot shorter, a lot less nested, and that will mean it is easier to read.

– remove all “groupLabel” param tags.

– remove all “HiddenFieldPicker” modules, and de-nest all the modules that were contained within.

– “de-nest” all of the modules inside all “EnablePreview” modules.  In other words, for each EnablePreview module, make it’s one child,  into a sibling, and have the EnablePreview module be closed like this:

<module name="EnablePreview">
  <param name="enable">True</param>
  <param name="display">False</param>
</module>

– if you have modules nested inside any JobProgressIndicator modules, do the same with those – denest all those modules,  such that the child of JobProgressIndicator ends up being a following sibling instead.

– you can almost certainly remove all “allowTransformedFieldSelect” params.

– you can almost certainly remove all “ViewStateAdapter” modules and de-nest all the modules that were contained within.

– remove all “Gimp” modules.

Wow. We just removed quite a lot.    reload/refresh and test.  Make sure you still have well-formed XML.

OK.  Now we start with the good stuff.

Step 6> replace all “HiddenSearch” modules with “Search” modules. 

First just replace the module names. The param values in Simplified XML will be the same.

Next though, you’ll have to cut the module XML out of the view,  and move it deeper into the nesting,  so that it is below all of the form-field modules that contribute to the search.   It pays to keep your indentation clean although you don’t have to listen to me.

And leave the layoutPanel attribute and autoRun attribute on whatever module is left behind as the topmost <module>.

Step 7> Delete each and every “ConvertToIntention” module. 

This one will feel good.  After doing it, the view will mysteriously work just fine without them.   =)

NOTE: well ok fine, if you have some complex views with more than one SearchSelectLister modules, then you *might* need to replace all the lister modules with equivalents first.   Technically the listers *may* in some cases expect the intentions to still be there.

Step 8> replace all ExtendedFieldSearch modules with TextField

You’ll want to be a little familiar with TextField, and you’ll want to have read the docs pages in Sideview Utils.  However TextField is VASTLY SIMPLER than ExtendedFieldSearch so you’ll be fine.

For example, you would take this beast:

<module name="ExtendedFieldSearch">
  <param name="replacementMap">
    <param name="arg">
      <param name="series"/>
    </param>
  </param>
  <param name="field">sourcetype</param>
  <param name="q">splunkd</param>
  <param name="intention">
    <param name="name">stringreplace</param>
    <param name="arg">
      <param name="series">
        <param name="fillOnEmpty">True</param>
      </param>
    </param>
   </param>

and replace it with this:

<module name="TextField"> 
  <param name="name">sourcetype</param> 
  <param name="label">Sourcetype</param>

It’s quite a bit simpler isn’t it!

Step 9> replace all “SearchSelectLister” code with “Pulldown”.

Same rules apply.  You’ll want to have read the pages about Pulldown.  However Pulldown is VASTLY simpler and more intuitive than SearchSelectLister.   For example you would replace this:

<module name="SearchSelectLister">
  <param name="staticFieldsToDisplay">
    <list>
      <param name="value">*</param>
      <param name="label">Any</param>
    </list>
  </param>
  <param name="search">index=_internal source=*metrics.log group="per_sourcetype_thruput" | top series</param>
  <param name="label">Select series</param>
  <param name="settingToCreate">series_setting</param>
  <param name="searchFieldsToDisplay">
    <list>
      <param name="value">series</param>
      <param name="label">series</param>
    </list>
  </param>
  <param name="searchWhenChanged">False</param>

with this:

<module name="Search">
  <param name="search">index=_internal source=*metrics.log group="per_sourcetype_thruput" | top series</param>
  <module name="Pulldown">
    <param name="name">selectedSourcetype</param>
    <param name="label">Sourcetype</param>
    <param name="valueField">series</param>

This is a hard oen though so there are some things to note carefully.

First, note that the param in the SearchSelectLister was called “series_setting”,  but in the Pulldown and the Search module we have lost the “_setting” part.  This is part of the conversion to bypass all the intention stuff.

Secondly, note that we’re replacing one incredibly complicated ‘SearchSelectLister’ module with two modules — ‘Search’ and ‘Pulldown’.    The listers all have these special “internal” searches, but the Sideview equivalents just use the main search from the module system.  As such you now can put “earliest” and “latest” params on that Search module so you can limit your search in time.    And there are many other benefits.  Fortunately this is the only time we will replace one module with two.

Thirdly, note that if there was not an autoRun attribute on the SearchSelectLister, and there was not an autoRun attribute on any direct ancestor of the SearchSelectLister, then you will have to put an autoRun attribute on the Search module.

Note: if you’re on the older Sideview Utils 1.3.X,  you’ll have to use the older searchFieldsToDisplay param instead of the “valueField” param shown here.  Consult the Pulldown docs appropriate to your Sideview Utils version though and you’ll be fine.


Step 10> replace all StaticSelect with Pulldown

This one’s pretty simple.  Change the “StaticSelect” module name to “Pulldown”,   create a “name” param that has the same value as the “settingToCreate” param,   delete the “settingToCreate” param.  Now go back and delete the “_setting” suffix from the settingToCreate value.

Step 11> replace all ServerSideInclude and StaticContentSample modules with HTML modules. 

This is pretty straightforward, but I’ll say that with the HTML module you can either specify a “src” param in which case it works like ServerSideInclude, or an “html” param, in which case it works like StaticContentSample.

Step 12> replace all Paginator modules with Pager modules

In addition to being a better module and supporting postProcess,   if the “entityName” param is set to “results”, which it will be 99% of the time, you can delete the param entirely because that is the default for Pager.

 

How did we do?

It’s quite possible that your view XML now is about half the size it was right after the conversion to advanced XML.

What next?

remember that page I told you to read at the beginning?   “Key Techniques > Overview of the Advanced XML”.

Even if you’re in the 10 percent of people who actually stopped and read it,   now go back and read it again.

Having just spent some time mucking about in an actual view, now the modules may make more sense.   There is an ‘aha’ moment in the module system, generally when people realize that the XML format is really just a little markup language for functional-description, and that it has nothing to do with “layout”.     But you have to just stare at examples and read the framework docs a few times before the light appears.

 



Read more posts in the Sideview Utils category