How do I create a Splunk setup view?

[lknecht_splunk]

My goal is to create a setup page that users will be forced to configure on the installation of my Splunk App.

I know that Splunk has setup.xml pages, but I want to use the setup view that was released around Splunk 6.4.0.

The only documentation I can find for it is here in the app.conf file. It's listed in the ui stanza as a setup_view property and that it allows you to specify the setup view.

However, that's it! I can't find anymore information on this!

Can anyone help me find out how to use this?

[lknecht_splunk · Accepted solution]

@lknecht that is a fantastic question!

Setup views could do with some better documentation (which we're working on as we speak!)

In the mean time, I would suggest you take a look at the talk from .conf 2017 call "Friction Free Splunk Application Certification"

You can find the link here

That session has a video, and some slides that can be used to help guide this discussion about setup views by explaining what it looks like, and how its implemented from a high-level.

Additionally there is a Splunk App that was built by myself and uploaded to Splunkbase called "Developer Guidance - Setup View Example For Splunk". And, in this Splunk App you can see an incredibly simple implementation of a setup view.

If anything, take the time to look at the app on Splunkbase, and then using that you can implement a setup view for your own app so that users can configure your Splunk App as needed!

---

Now, if you're a little lazy (just like me) you may not want to look at all this information. That's totally fair. So I'm going to break down how to implement a setup view here, and if you have any questions feel free to ask for more information.

First a setup view starts in the app.conf file.

1. app.conf - [install] stanza - is_configured property
   • This property is what tells Splunk if the Splunk App has already been configured
   • If false, it will ALWAYS redirect to a page prompting the Splunk User to perform the setup configuration
   • If true, it will not show that page, and instead run the Splunk App as normal execution
2. app.conf - [ui] stanza - setup_view property
   • After the Splunk App has determined that a setup is required it will determine which dashboard should be redirected to
   • The dashboard that will be redirected to is determined by the "app.conf - [ui] - setup_view" property
   • This property will point to a dashboard that exists in $SPLUNK_HOME/etc/apps/{APP_NAME}/default/data/ui/views/{DASHBOARD_FILE_NAME}.xml
   • I have not tested this, but I believe you can use relative pathing to specify files in nested directories
3. $SPLUNK_HOME/etc/apps/{APP_NAME}/default/data/ui/views/{DASHBOARD_FILE_NAME}.xml
   • This is essentially a simple xml view
   • This dashboard should be very simple
   • It should use the {dashboard} element's stylesheet attribute to specify a CSS file for the styling of the page
   • It should use the {dashboard} element's script attribute to specify a JavaScript file for the logic of the page
   • The CSS and JavaScript will be searched for in $SPLUNK_HOME/etc/apps/{APP_NAME}/appserver/static/
   • This can use relative pathing to specify files nested in sub-directories of that path
   • Suggested: The {html} element should be used inside the {dashboard} element to create a {div} for the purpose of hooking in a Backbone View to render the view
4. $SPLUNK_HOME/etc/apps/{APP_NAME}/appserver/static/{JAVASCRIPT_FILE_NAME}.js
   • This will be where the logic of your setup page can be performed
   • This page can import other JavaScript files to simplify logic management
   • This JavaScript logic will be implemented using the Splunk Web Framework and its respective Splunk Web Framework API
   • From here you'll have to configure the custom render and input logic yourself!

---

And here is all that information in picture form!

app.conf

XML Dashboard

JavaScript Setup Pages

Again, I would definitely suggest looking at the demo application and the .conf 2017 session in order to see how the implementation looks for yourself!

Good luck!

[christoffertoft]

Hi lknecht,

There isn't much information on the difference between this method and using the setup.xml approach. Can you elaborate on why to use this or setup.xml, and when and why one should use one over the other?

[thellmann]

Sorry for the delayed response! We recommend using a setup view instead of setup.xml because setup views are more compatible with distributed Splunk Enterprise and Splunk Cloud deployments. In fact, if you intend for your app to be used in Splunk Cloud, we require that you use a setup view if your app requires configuration (this, and other checks that are part of the Cloud Vetting process, are documented here). 

You can learn more about setup views in our new manual on app configuration available on dev.splunk.com: https://dev.splunk.com/enterprise/docs/developapps/manageknowledge/setuppage/

[breid1313]

Thank you to all at Splunk for the helpful Developer Guidance - Setup View app. The concise and simple example is extremely helpful.

I am converting an app from using default/setup.xml to using a setup view. When I make changes to the HTML template in the example app and restart splunk, the changes do not appear in the setup page. Am I missing a step to get the HTML template to render with the new content?

Changes to the xml dashboard do take as soon as a restart splunk though 🙂

Thanks in advance.

@thellmann @lknecht_splunk 

[thellmann]

@breid1313  I would recommend referencing this example: https://github.com/splunk/splunk-app-examples/tree/master/case_studies/weather_app_example (don't forget the configuration steps specified in the root README file) 

You might be hitting a promisify bug in the JS code - we've fixed that in the weather_app_example, so please refer to that until we can roll out a fix for the Developer Guidance - Setup View app. 

[breid1313]

Awesome, thank you.

[ohbuckeyeio]

This is an old thread, but +1 on this question if anyone cares to answer.

[mbachhav]

Hi lknecht,

This code creates "local/setup_view_example.conf" file.

How to fetch the stored values from setup_view_example.conf file and display them in setup_view form when user opens setup form next time?

Also, How to show default value for input type if custom value for it is not available in "local/setup_view_example.conf" file?

Thanks in advance.

[thellmann]

Hi @mbachhav - there is a more detailed example with some additional functionality for checking the values of different configuration stanzas available in this example app: https://github.com/splunk/splunk-app-examples/blob/master/case_studies/weather_app_example/appserver...

Because the logic in setup pages is controlled by JS, you can use that code to determine whether a configuration parameter has already been set and if so display the existing setting or a default. 

[spayneort]

You could use the add-on builder.

http://docs.splunk.com/Documentation/AddonBuilder/2.2.0/UserGuide/Createasetuppage
https://splunkbase.splunk.com/app/2962/