Configure a setup screen for your app

Configure a setup screen for your app

You can make life easier for your users by creating a setup screen for your app or add-on. A setup screen takes strings entered by the user and POSTs each one to a specified REST endpoint/entity pair. You can configure a setup screen to write directly to your app's configuration files -- for example, to enable or disable a scripted input or set frequency and alerting for a saved search. You can also write your own Python scripts to handle more complex setups. For example, the WebSphere® app on Splunkbase takes a single user input -- the path to profileRegistry.xml for a WebSphere Application Server instance -- and extracts the locations of the WAS log files and sets up inputs.conf to monitor all of them.

Warning: Setup screens in Splunk use the REST API. The REST API is not regularly tested and is subject to developer drift.

Create a setup screen

You can use a setup screen to directly modify Splunk's configuration files via their associated endpoints and/or to access custom endpoints. To learn more about endpoints, see the topic Splunk's API is RESTful in this manual.

To create and instrument a setup screen, you need to do the following:

• Create a setup.xml file in your app's default directory: $SPLUNK_HOME/etc/<app_name>/default/setup.xml.
• Supply initial values for the fields you use in setup.xml. The setup machinery uses the initial values to create the setup screen to the user.

In addition, to use a custom endpoint in your setup, you must also:

• Create a Python script for your endpoint and place it in $SPLUNK_HOME/etc/<app_name>/bin/
• Create a stanza in $SPLUNK_HOME/etc/<app_name>/default/restmap.conf that associates the Python script with your endpoint.

For examples of how to create setup screens, see Create a setup screen to modify conf files and Create a setup screen using a custom endpoint on the Community Wiki.

Understand setup.xml syntax

The setup.xml file in your app's default directory ($SPLUNK_HOME/etc/<app_name>/default/setup.xml) defines the mapping between user inputs and the objects that are posted to the REST endpoints.

setup

A setup element represents the setup. It must be the single outermost element in the setup.xml configuration file.

block

The block element is used to group input. A block can include an optional endpoint and/or entity attribute, which is inherited by all input elements contained in the block.

You can use blocks to:

• group inputs that have a common endpoint and/or entity.
• display explanatory text on the screen using a block that does not contain any inputs.

Attributes

attribute	description
title	String that contains a title for the block; displayed on the setup screen. Required.
endpoint	(optional) String that specifies a REST endpoint relative to your Splunk host and management port (for example, https://localhost:8089/servicesNS/nobody/<app_name>/). If set, endpoint is inherited by all input child elements. Each input must have only one endpoint defined directly for the input.
entity	(optional) String that specifies an entity method under the REST endpoint. Cannot be specified unless an endpoint attribute has been specified for this block. If set, endpoint is inherited by all input child elements. entity="_new" creates a new entity for endpoint. When endpoint is one of Splunk's REST endpoints for configuration files, corresponds to a new stanza.
mode	(optional) sets how to process the entity attribute when entity is expressed as a regex. Use * to configure all entities at a specific endpoint. mode="iter": if entity is a regex, iter iterates through all matching entities at that endpoint, displays separate input(s) for each matching entity, and saves the results separately. For example, lets the user set the polling interval separately for a number of scripted inputs. mode="bulk": if entity is a regex, modedisplays a single input for all matching entites, and sets the result in bulk. For example, lets the user set a single polling interval for a number of scripted inputs.

Nested elements

A block has a choice between the following types of elements:

• input: one or more input elements

• text: zero or more text elements; each text element is a string that contains descriptive text which is displayed on the setup screen.

input

The input element is used to collect input from the user via an entry box or radio button and associate it with a field. When the user clicks Save on the setup screen, the field value is POSTed to the endpoint/entity pair specified in the block that contains the input.

Attributes

attribute	description
endpoint	(required - can be set here, or inherited from a parent block) String that specifies a REST endpoint relative to your Splunk host and management port (for example, https://localhost:8089/servicesNS/nobody/<app_name>/). If set, endpoint is inherited by all input child elements. Each input must have only one endpoint, which it can inherit from a containing block or which can be defined directly for the input.
entity	(required - can be set here, or inherited from a parent block) String that specifies an entity method under the REST endpoint. Cannot be specified unless an endpoint attribute has been specified for this block. If set, endpoint is inherited by all input child elements. entity="_new" creates a new entity for endpoint. When endpoint is one of Splunk's REST endpoints for configuration files, corresponds to a new stanza.
field	String that specifies the object to be configured using the endpoint/entity pair specified for this input; when used with entity=_new, string that specifies the attribute to create within the new stanza.
mode	(optional) sets how to process the entity attribute when entity is expressed as a regex. Use * to configure all entities at a specific endpoint. mode="iter": if entity is a regex, iter iterates through all matching entities at that endpoint, displays separate input(s) for each matching entity, and saves the results separately. For example, lets the user set the polling interval separately for a number of scripted inputs. mode="bulk": if entity is a regex, modedisplays a single input for all matching entites, and sets the result in bulk. For example, lets the user set a single polling interval for a number of scripted inputs.

Nested elements

• label: (required) String description of the input field, displayed on the setup screen. Use $field_name$ to display the name of the field to the user. If you are iterating through a list of entities (mode="iter"), use $name$ to display the name of the current entity to the user.
• type: (required) Specifies the type of input:
  • bool: displays a radio button that allows the user to choose true/false values
  • text: displays an entry box for freeform (string) text input
  • list: displays a comma separated list and allows the user to choose a value
• validation: (optional) validates the user input against a specified regex; for example <validation>\d+<\validation> verifies that the input is numeric

• Was this topic useful?
• Post a comment