Developing Views and Apps for Splunk Web

About files and directories for apps and add-ons

You can share any extension to Splunk Enterprise - not just the views and navigation you find in an app, but saved searches, scripted inputs, and 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 Enterprise

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.

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 following files may show up:

Path	App	Add-on	Comments
$SPLUNK_HOME/etc/apps/<app_name> ($APP_HOME)	required	required	dedicated directory under $SPLUNK_HOME/etc/apps/
$APP_HOME/static/			Directory for web resources - such as images, CSS, or HTML - used by your app or add-on
$APP_HOME/static/appIcon*.png $APP_HOME/static/appLogo*.png	recommended	recommended	Icon for app or add-on that displays on Splunk Enterprise home page, Splunk Bar, and the Search Bar. See Add app icon images for details.
$APP_HOME/appserver/static/[UploadedIconFile].png	n/a	n/a	When you upload icon files using Splunk Web, Splunk Web places the icons in the appserver directory. From the command line, move uploaded icons that appear in the appserver directory to $APP_HOME/static/. Uploaded icons appear in the appserver directory because of legacy behavior. See Add app icon images for details.
$APP_HOME/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 a dashboard using advanced XML, Build a form search using advanced XML 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 Splunk Apps. 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

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 Splunk Apps, make sure that the version number in app.conf matches the version number on Splunk Apps.

Example app.conf for an app with updated images

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