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 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
Step 2. Create the Simple XML view
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.
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.
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 firstname.lastname@example.org.
Thank you to Shilpa Bijam, Senior Software Engineer, for providing code samples.