Setup screen example using a custom endpoint
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Contents
Setup screen example using a custom endpoint
This example shows how to create a setup screen that uses Splunk’s REST API to configure a custom endpoint. The custom endpoint maps to a configuration file you create at $SPLUNK_HOME/etc/apps/<myApp>/default/myappsetup.conf.
To update a custom endpoint, do the following:
- Create your custom configuration file with the initial values for your setup screen.
- Create a stanza in
restmap.confthat maps your endpoint to your custom configuration file. - Write a python script that initializes your setup screen and handles the user-entered values.
- Write
setup.xml.
1. Create a custom configuration file with default values
This example uses a configuration file to initialize the default values for the stanza [setupentity]. The entity attribute in setup.xml refers to this stanza.
However, you can also initialize the default values in your python script.
myappsetup.conf
[setupentity] field_1 = field_3 = 60 field_2_boolean = 0
2. Example stanza in restmap.conf
The following example stanza in restmap.conf sets up a custom endpoint at:
https://localhost:8089/services/mycustom/customendpoint
restmap.conf
. . . [admin:myendpoint] match=/mycustom members=customendpoint [admin_external:customendpoint] handlertype = python handlerfile = MyApp_python_handler.py handleractions = list, edit . . .
[admin_external:<endpoint_name>]
Names the endpoint. Make sure you use a unique name for your endpoint.
handlertype Specifies the language of the REST endpoint script. Currently, Splunk only supports python for custom endpoints.
handlerfile
The name of the python script. Place the script here:
$SPLUNK_HOME/etc/apps/<app_name>/bin
handleractions Actions supported by the script. list displays the initial field values. edit updates the endpoint when the user saves the setup screen.
3. Example python script that implements a new endpoint
The python script looks for the configuration file, myappsetup.conf in either .../default or .../local. It also searches for values for the fields defined in the configuration file, and writes any changes to .../local.
MyApp_python_handler.py
import splunk.admin as admin
import splunk.entity as en
# import your required python modules
'''
Copyright (C) 2005 - 2010 Splunk Inc. All Rights Reserved.
Description: This skeleton python script handles the parameters in the configuration page.
handleList method: lists configurable parameters in the configuration page
corresponds to handleractions = list in restmap.conf
handleEdit method: controls the parameters and saves the values
corresponds to handleractions = edit in restmap.conf
'''
class ConfigApp(admin.MConfigHandler):
'''
Set up supported arguments
'''
def setup(self):
if self.requestedAction == admin.ACTION_EDIT:
for arg in ['field_1', 'field_2_boolean', 'field_3']:
self.supportedArgs.addOptArg(arg)
'''
Read the initial values of the parameters from the custom file
myappsetup.conf, and write them to the setup screen.
If the app has never been set up,
uses .../<appname>/default/myappsetup.conf.
If app has been set up, looks at
.../local/myappsetup.conf first, then looks at
.../default/myappsetup.conf only if there is no value for a field in
.../local/myappsetup.conf
For boolean fields, may need to switch the true/false setting.
For text fields, if the conf file says None, set to the empty string.
'''
def handleList(self, confInfo):
confDict = self.readConf("myappsetup")
if None != confDict:
for stanza, settings in confDict.items():
for key, val in settings.items():
if key in ['field_2_boolean']:
if int(val) == 1:
val = '0'
else:
val = '1'
if key in ['field_1'] and val in [None, '']:
val = ''
confInfo[stanza].append(key, val)
'''
After user clicks Save on setup screen, take updated parameters,
normalize them, and save them somewhere
'''
def handleEdit(self, confInfo):
name = self.callerArgs.id
args = self.callerArgs
if int(self.callerArgs.data['field_3'][0]) < 60:
self.callerArgs.data['field_3'][0] = '60'
if int(self.callerArgs.data['field_2_boolean'][0]) == 1:
self.callerArgs.data['field_2_boolean'][0] = '0'
else:
self.callerArgs.data['field_2_boolean'][0] = '1'
if self.callerArgs.data['field_1'][0] in [None, '']:
self.callerArgs.data['field_1'][0] = ''
'''
Since we are using a conf file to store parameters,
write them to the [setupentity] stanza
in <appname>/local/myappsetup.conf
'''
self.writeConf('myappsetup', 'setupentity', self.callerArgs.data)
# initialize the handler
admin.init(ConfigApp, admin.CONTEXT_NONE)4. Create setup.xml
Here is the setup.xml file that creates the setup screen for the custom endpoint.
<setup>
<block title="Configure This App">
<text>Setup screen with custom endpoints</text>
</block>
<block title="A text input"
endpoint="mycustom/customendpoint" entity="setupentity">
<input field="field_1">
<label>Enter your text</label>
<type>text</type>
</input>
</block>
<block title="Enable and set a numeric value"
endpoint="mycustom/customendpoint" entity="setupentity">
<input field="field_2_boolean">
<label>Enable This Input</label>
<type>bool</type>
</input>
<input field="field_3" endpoint="mycustom/customendpoint" entity="setupentity">
<label>Set this number (minimum value=60)</label>
<type>text</type>
</input>
</block>
</setup>This documentation applies to the following versions of Splunk: 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 View the Article History for its revisions.