Enable First-Run App Configuration With Setup Pages

Does your Splunk app require user-provided configurations to run? If so, you can use a setup page to collect and store this information.

A setup page is a page in a Splunk app that displays the first time a user launches the app. Setup pages allow your app’s users to input custom app configurations and settings through the Splunk Web user interface.

Key Uses for Setup Pages

So, what can you accomplish with setup pages? Here are the key uses:

• Checking for app dependencies: You can create a setup page to verify whether your users have installed all of the apps and add-ons that your app relies on before they start using your app.
• Storing user-provided configurations: You can create a setup page to capture user input and save this information in a configuration (.conf) file.
• Integrating with an external service: You can create a setup page to authenticate your app’s users with a third-party service so that they can retrieve and use data from an external API.
   

How Setup Pages Work

When a user launches an app for the first time, Splunk software checks the app.conf file to determine whether the app is configured. If the app is configured, the user is directed to the app’s home page. If the app is not configured, the user is directed to the app’s setup page, a Simple XML view that you specify in the app.conf file.

This Simple XML view uses a Simple XML extension written in JavaScript that contains the logic to configure the app. After the user completes the setup process, the setup page updates the app.conf file to mark the configuration as complete and redirects the user to the app’s home page.

This diagram shows how a user interacts with a setup page to configure a Splunk app.

Why Use a Setup Page?

Using a setup page for app configuration simplifies the setup process for end users. Setup pages enable users to store custom settings and configurations using Splunk Web, without the need to manually update configuration files. The ability to configure an app through the front end is especially important in Splunk Cloud because customers do not have access to the command-line or file system.

You might be familiar with using setup.xml for app configuration. Setup.xml is a deprecated feature that is not supported in Splunk Cloud. To pass Splunk AppInspect, you must use a setup page if your app requires user-provided configurations.

Create a Setup Page

Now, let’s walk through how to create a setup page. In this example, we’ll take a look at a setup page that verifies whether a user has installed and configured a second, dependent app.

Step 1. Code the setup process for the app

First, we’ll write the JavaScript code to check for app dependencies, as shown in the following image. We can use any JavaScript libraries and tools that we want to code the app’s setup process. 

We’ll save this setup_page.js file as a Simple XML extension in the $SPLUNK_HOME/etc/apps/APP_NAME/appserver/static/javascript directory.

For the complete example code, see setup_page.js in the splunk-app-examples repository on GitHub.

Step 2. Create the Simple XML view

Next, we’ll create the Simple XML view that exposes our JavaScript code on a setup page in Splunk Web. The following image shows an example Simple XML view, setup_page_dashboard.xml.

In this example, we import the javascript/setup_page.js file, the Simple XML extension that we created in Step 1. We also import the styles/setup_page.css file, a stylesheet located in the $SPLUNK_HOME/etc/apps/APP_NAME/appserver/static/styles directory.

Next, we’ll create a <div> element with an id attribute set to “main_container”. This element defines the space in the Simple XML view in which to render the JavaScript code.

We’ll save this file in the $SPLUNK_HOME/etc/apps/APP_NAME/default/data/ui/views directory.

Step 3. Configure the app.conf file

Finally, we’ll configure the app.conf file, as shown in the following image. We’ll configure the app.conf file to map the Simple XML view to the app’s configuration and direct users to this page the first time they launch the app.

In this example, the [install] stanza contains “is_configured = 0”. This setting indicates that the app is not yet configured and redirects the user to complete the setup process.

The [ui] stanza contains “setup_view = setup_view_dashboard”. This setting maps the setup_page_dashboard.xml file we created in Step 2 to the app’s setup process.

Result

Now, when the app’s users launch the app for the first time, they’ll see a message redirecting them to the app’s setup page, as shown in the following image.

The setup page prompts the user to check whether the app’s dependency is installed and configured, as illustrated in the following image.

If the app dependency is installed, the setup page updates the app.conf file to mark configuration as complete and redirects the user to the app home page.

If the app dependency is not installed, the setup page prompts the user to install and configure the dependent app to complete the setup process.

Manage Configurations After an App Update

What happens to an app’s custom configurations after an app update? You can manage how configurations reload in the [triggers] stanza of the app.conf file.

For more information about managing configurations after an update, see Reload custom configurations after a Splunk Cloud or Splunk Enterprise app update on the Splunk Developer Portal.

More Resources

Check out the following resources to learn more about setup pages:

• For newly released documentation on setup pages, see Enable first-run configuration with setup pages in Splunk Cloud or Splunk Enterprise on the Splunk Developer Portal.
• For a breakout session on setup pages featured at Splunk’s .conf20 event, see Extend the Splunk Platform with Custom Search Commands and Setup Pages at .conf Online!
• For end-to-end examples of setup pages, including the example featured in this post, see setup_pages in the splunk-app-examples repository on GitHub.
   

As always, if you have any questions or feedback, reach out at devfeedback@splunk.com.

Thank you to Shilpa Bijam, Senior Software Engineer, for providing code samples.