Splunk® Enterprise

Developing Dashboards, Views, and Apps for Splunk Web

Download manual as PDF

Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF

Files and directories for apps and add-ons

You can share any extension to Splunk - not just the views and navigation you find in an app, but saved searches, scripted inputs, and Splunk knowledge. To do this, place the necessary files in a directory for distribution to the recipient's $SPLUNK_HOME/etc/apps directory. You can share an extension even if it doesn't have a UI environment of its own.

Apps vs. add-ons

You can add views and navigation along with other extensions to make a separate app, but this is not necessary. Extensions such as field extractions or scripted inputs may not necessarily benefit from a separate UI with a distinct URL and a collection of views and dashboards. You can provide the benefits without creating a full-blown app that shows up on the App menu. In this case, you package the extension as an add-on. An add-on is essentially an app that has no UI of its own and exists only as a container for other things (such as saved searches or scripted inputs) that are shared globally.

What can an app or add-on do?

Apps and add-ons can both include:

  • scripted inputs or other input types
  • field extractions for a specific source type (often implemented with an input method)
  • scripted lookups or searches
  • saved searches that can be accessed from the Search app
  • views and navigation
  • event types
  • tags
  • workflow actions

What is the difference?

  • apps are set to Visible and must have a navigation file. Apps have a separate URL and appear on the App menu. Apps are not restricted to dashboards and searches, although in practice, they are often view-intensive.
  • add-ons are set to Not Visible. They do not have a separate URL and do not show up on the App menu. An add-on can have views, but they show up under an existing app (for example, the Search app). Every object in an add-on -- views, saved searches, navigations, etc. -- must be globally available in order to be accessible. See App architecture and object ownership in the Admin manual.

Apps vs. add-ons are something of a marketing distinction. From the point of view of the code, apps and add-ons are created and administered as apps. All apps and add-on have a separate folder in $SPLUNK_HOME/etc/apps/ and an app.conf file. The following table summarizes the difference between apps and add-ons:

app add-on
visible not visible
navigation file required (see Build navigation for your app) navigation file optional
appears on App menu does not appear on App menu
has dedicated URL does not have dedicated URL
objects accessed using app objects accessed using other apps; must be globally available

For another view of apps and add-ons, see What are apps and add-ons? in the Admin manual.

Set visibility

The visibility setting determines whether an extension can be considered an app and appear on the App menu. To set visibility:

1. Create a directory under $SPLUNK_HOME/etc/apps (or %SPLUNK_HOME%\etc\apps on Windows), for example $SPLUNK_HOME/etc/apps/<addon_name>. This is called $APP_HOME for the rest of this topic.

2. Restart Splunk

3. Go to Manager > Apps and navigate to the configuration screen for your app or add-on by clicking on the name of your directory.

4. Select whether you want to make the extension Visible.

DevNotVisible.png

Note: You can also set app visibility using the app.conf file in the $APP_HOME/default/ directory. To do this, open or create app.conf in a text editor and edit or create the ui stanza. For example, to set an add-on to be not Visible:

[ui]
is_visible = false

Files and directories for apps and add-ons

If you are sharing your app or add-on, make sure you have all the files you need in the correct location under the home directory for your app ($APP_HOME). To allow users to make their own customizations without being clobbered by later updates of your app, you move all the files in $APP_HOME/local/ to $APP_HOME/default/. Also check for files and stanzas that may be scattered around the system outside of the app's directory. Depending on the functionality you have implemented, the followings file may show up:

file or directory app add-on comments
$SPLUNK_HOME/etc/apps/<app_directory> ($APP_HOME) required required dedicated directory under $SPLUNK_HOME/etc/apps/
$APP_HOME/appserver/static/ Directory for web resources - such as images, CSS, or HTML - used by your app or add-on
$APP_HOME/appserver/static/appIcon.png recommended recommended Icon for app or add-on displayed in Launcher and Splunkbase. Icon should be in PNG format and 36px x 36px in size. NB: Note the punctuation of appIcon.png. Specifically, the capital "I".
$APP_HOME/appserver/static/screenshot.png recommended not required Screenshot or splash screen for app or add-on displayed in Launcher. Image must be in PNG format. Display dimensions are 623px x 350px - will be extended with white if smaller, scaled if larger. For best results, make sure the image size is in the 98:55 ratio and do not include browser chrome in your image.
$APP_HOME/appserver/static/documentation.pdf optional optional Downloadable PDF documentation for your app or add-on.
$APP_HOME/bin/ Directory for custom scripts for searches or scripted inputs.
$APP_HOME/bin/*.sh, *.bat, *.py, *.pl, etc. optional optional
$APP_HOME/default/ Directory for configuration files specific to your app or add-on
$APP_HOME/default/app.conf required required File that sets app name, author, description; app visibility (app vs. add-on); and any custom configuration file settings for the app. See configure app.conf in the Developer manual and app.conf in the Admin manual for more information.
[ui]
is_visible=true
[ui]
is_visible=false
Visibility setting in app.conf that determines whether package has a separate UI (app) or not (add-on).
$APP_HOME/default/*.conf optional optional Additional configuration files required by your app or add-on. Pretty much any .conf can show up here, except for those files that define global settings. See Step 3: add configurations in the Developer manual and About configuration files in the Admin manual for more information about configuration files.
$APP_HOME/default/setup.xml optional optional File for custom setup window for your app or add-on.
$APP_HOME/default/data/ui/ Directory for navigation and views
$APP_HOME/default/data/ui/nav/default.xml optional optional Navigation specific to your app or add-on. See build navigation for your app in the Developer manual for more information.
$APP_HOME/default/data/ui/views/*.xml required optional Views specific to your app or add-on; an app must have one or more views. See build dashboards, form searches and advanced views in the Developer manual for more information.
$APP_HOME/local/ Directory for user-generated configuration files
required required Include an empty local directory when you distribute your app or add-on. If the user makes any configuration changes via Manager, they will be stored here. The developer of an app or add/on should never place any shipping configurations in local, as subsequent revisions would end up clobbering the user's customizations.
$APP_HOME/lookups/ Directory for lookup tables
$APP_HOME/lookups/*.csv optional optional CSV file for lookups
$APP_HOME/metadata/ Directory for permissions
$APP_HOME/metadata/default.meta required optional File that sets default permissions for the app or add-on; when file is missing, permissions are private. Users set permission overrides in $APP_HOME/metadata/local.meta. See Step 5 Set permissions in the Developer manual for more information.
$APP_HOME/README.txt recommended recommended Readme that contains instructions on installing and configuring your app or add-on, as well as any hints for troubleshooting.

Set up app.conf

When you use app builder to create an app, it automatically creates an app.conf file and enables a UI context for your app. You still need to define the launcher stanza before you share your app on Splunkbase. If you have built an add-on directly, you may need to create your own app.conf using a text editor.

To instrument the difference between an app and an add-on, set the Visible setting for the app in Manager. You can also set the is_visible setting in the [ui] stanza in the app.conf file.

Example app.conf for an add-on

DeveloperPackageAddonDir.png Here is a sample directory and app.conf file for a simple add-on that provides a scripted input:
[ui]
is_visible = false
label = My Add-on

[launcher]
author=me
description=My Add-on provides scripted inputs that allow you to index your Specific Third-party Application in Splunk 4.0 or later.  
version="1.0" 

Note: author and version do not actually show in the Launcher app, but it's a good idea to include them.

  • author lets you get credit for your work; it appears in the app details in Manager > Apps.
  • version allows users to check the current version of their app.
    If you are uploading your app to Splunkbase, make sure that the version number in app.conf matches the version number on Splunkbase.

Example app.conf for an app with updated images

DeveloperPackageAppDir.png This example shows an app with the following:
  • UI context enabled
  • a launcher description
  • a build specification to ensure static web assets (such as images, CSS and Javascript) are updated for users.
[ui]
is_visible = true
label = My App

[launcher]
author=me
description=My App provides pre-built data inputs, searches, reports, alerts, and dashboards. This update provides a new user interface with flashier, more exciting icons.  
version="2.1"

[install]
build = 3 
PREVIOUS
Step 8: Package your app or add-on
  NEXT
Setup screen example

This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.1, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters