Step 7: Configure a setup screen in setup.xml
This topic covers creating a setup screen using setup.xml. You can also create a setup experience in HTML or Simple XML.
You can make life easier for your users by creating a setup screen for your app or add-on. Setup screens make it easier to distribute apps to different environments, or to customize an app for a particular usage. When the user first runs the app, the setup screen displays that allows the user to specify configurations for the app without having to edit the configuration files directly. The user can later run the setup screen from Splunk > Manager > Apps > Actions.
A setup screen uses the Splunk Enterprise REST API to manage the app’s configuration. For example, you can use the setup screen to enable or disable a scripted input or set the frequency and alerting for a saved search. The setup screen can configure Splunk Enterprise REST endpoints or custom endpoints that you create for your app.
This topic walks you through creating a setup screen. You can jump ahead to view the following examples:
Create a setup screen
To create a setup screen:
- Create a
setup.xmlfile in your app's default directory:
- Supply initial values for the fields in your app's configuration files. The setup screen uses these values to populate the input fields in the setup screen.
See setup.xml syntax below for information on creating
View the setup.xml spec file.
Endpoints, entities, and fields
Uses the REST API to update configurations specified in a setup screen. In
setup.xml, you specify the endpoints, entities, and fields to access when updating a configuration.
Here are summary descriptions of endpoint, entities and fields to help you understand how they are used in
|endpoint||Directly or indirectly indicates which configuration file to update. Most of the configuration files within Splunk software have one or more corresponding endpoints. For example, |
Navigate to the following location to see the endpoints available to all apps in your Splunk installation.
|entity||The object ID listed by the endpoint. Typically maps to a stanza in a configuration file.
Use URI encoding to specify paths to entities.
|field||Maps to an attribute of an entity. Typically, this is a setting in the stanza of a configuration files. The user specifies values for the attribute in the setup screen.|
See About configuration files to learn more about how to use configuration files to manage apps and Splunk Enterprise.
See the REST API Reference Manual to learn more about the REST API.
REST endpoints and configuration file settings
Splunk Enterprise uses REST endpoints to interact with other resources, both in memory and on disk. For setup screens, you typically access configuration files to allow a user to easily configure an app for their specific circumstances without having to manually update the configuration files.
The name of REST endpoint parameters usually, but not always, map directly to the name of the setting in a configuration file. For example, the following stanza in
savedsearches.conf enables a scheduled search:
[MySearch] search = sourcetype=access_combined ( 404 OR 500 OR 503 ) dispatch.earliest_time = -1d cron_schedule = */5 * * * * enableSched = 1
You can view the corresponding REST endpoints here:
At this REST endpoint, the names
cron_schedule match the names of the attributes in
savedsearches.conf. But the REST endpoint parameter for
is_scheduled. In the
setup.xml, you reference
is_scheduled to modify the setting for
Example settings for endpoint, entity, and field
For example, in
setup.xml for an app called sampleApp:
- Maps to the configuration file
savedsearches.conf. You can view the REST destination from a web browser at:
savedsearches.conf, refers to the stanza,
- Maps to the setting in
[sample_scheduled_search]to update. In the setup screen, the user could specify a value, such as
*/5 * * * *.
Providing credentials to access scripts
If your app contains scripted inputs that require a user name and password, you can capture the credentials for the script in your setup screen. In <code.xml>setup.xml</code.xml>, you can provide username and password fields to capture the user credentials.
See Setup screen example with user credentials for an example on how to provide fields for user credentials.
The password field masks input with a ‘*’ character. Splunk software encrypts the credentials and stores them in a stanza in the app’s
app.conf configuration file.
app.conf is at:
Here is the stanza, which is generated by splunkd, that contains the encrypted credentials. <realm> is optional:
[credential:<realm>:<username>] password = $1$<encrypted-password>
- Caution: security implications
- Splunk software stores the encrypted password and encryption key on the same machine. This is because the script needs access to the decrypted password from your Splunk deployment.
For more information see:
Running the setup screen
If your app contains a
setup.xml file, when the user first runs the app the setup screen opens, displaying default configuration values for items listed on the setup screen. The user can choose to accept the default configuration, or specify new values.
The user can later run the setup screen from Settings > Apps > Actions. Click the Set up link for your app to open the setup screen.
Note: The setup screen writes changes made to the app’s configuration to the
$SPLUNK_HOME/etc/apps/<app>/local directory. The local directory overrides any settings in the app’s default directory.
Creating setup screens for custom endpoints
For more complex setups, you can write your own Python scripts.
To use a custom endpoint in your setup:
- Create your custom configuration file with the initial values for the fields in the stanzas. (Alternately, you could initialize the values for the fields in a python script.)
- Create a stanza in
$SPLUNK_HOME/etc/apps/<AppName>/default/restmap.confthat maps your endpoint to your custom configuration file.
- Write a python script for your endpoint and place it in:
See Setup screen example using a custom endpoint for a detailed example.
setup.xml defines the setup screen that prompts users for configuration settings. You place
setup.xml in your app’s default directory:
The base element of a setup screen. It contains any number of block elements. Block elements cannot be nested inside other block elements.
The block element defines the UI for the setup screen. A block element can contain one or more of the following:
- text element
- input element
A block element can declare the following attributes:
|title||(Required) Displays a header for the block.|
|endpoint||(optional) Specifies a Splunk REST endpoint for your app. The endpoint attribute is inherited by all input child elements.
Splunk Enterprise uses its REST API to access specified endpoints. Each endpoint is relative to: |
https://hostname:port/servicesNS/nobody/<AppName>For example, the endpoint:
https://localhost:8089/servicesNS/nobody/<appName>/saved/searchesThis endpoint maps to the
|entity||(optional) Specifies the object at the endpoint to modify. Typically, entity maps to a stanza in a configuration file.
This attribute can only be set for a block that specifies an endpoint. The entity attribute is inherited by all input child elements.
|mode||(optional) Sets how to process an entity attribute when you define the entity with a regex, such as *. All entities matching the regex are configured. Note: Splunk software interprets '*' as '.*'.
The value of mode can be either
An optional element that provides descriptive text for the setup screen.
The text element can only be used inside block elements.
The input element collects input from the user. It associates the input with the specified field. The type element within an input element defines the user interface control to display.
When the user clicks Save on the setup screen, Splunk software uses the POST method to update the fields for the specified endpoint/entity pair.
The input element can contains the following child elements:
- <label> (required)
- <type> (required)
|endpoint||(required) Specifies the REST endpoint. See the description of endpoint for the <block> element.
Each input element has one (and only one) endpoint. The endpoint can be inherited from a parent block.
|entity||(required) Specifies the object at the endpoint to modify. Typically, entity maps to a stanza in a configuration file.
The entity can be inherited from a parent block.
|field||Specifies the setting to be configured in the stanza specified by entity.
When used with
|mode||(optional) Sets how to process an entity attribute when you define the entity with a regex, such as *. All entities matching the regex are configured. '*' is interpreted as '.*'.
The value of mode can be either
Required element in an <input> element. The description of the input field which is displayed on the setup screen.
$name$ to display the name of the entity. Specify
$field_name$ to specify the value of a specified field.
For example, if iterating through a list of entities (
mode = "iter"), use
$name$ to display the name of each entity to the user. Use
$search$ to display the value of the search field defined in each entity.
Required element in an <input> element. Specifies the UI control for capturing user input.
Allowed values for the type element:
- bool: Displays a checkbox that allows the user to choose true or false values.
- text: Displays a text field to input string values.
- password: Creates a password text field that masks passwords with the ‘*’ character. The UI displays a second password text field to ensure that the user types the same password twice.
- list: Displays values from a comma separated list, allowing the user to select a single value.
Step 6: Build navigation for your app
Step 8: Package your app or add-on
This documentation applies to the following versions of Splunk® Enterprise: 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.4.11