From Splunk Wiki

Use setup.xml with custom endpoints

This topic describes how to create a setup screen that POSTs user-entered input to your custom Splunk endpoint. To do this, you need to put a bunch of little pieces together:

• Create the stanza(s) in restmap.conf that map your endpoint(s) to the script that defines them.
• Write setup.xml.
• Create the initial values for your setup screen.
• Write a skeleton python script that initializes your setup screen and handles the user-entered values.

Warning: Splunk's REST endpoints are not regularly tested and are subject to developer drift. The examples here worked at the time this page was written, but they are not supported and there is no guarantee that they will continue to work.

The exciting result of all this work is a simple setup screen:

Name your endpoint with restmap.conf

[admin_external:customendpoint]
handlertype = python
handlerfile = MyApp_python_handler.py
handleractions = list, edit

The following stanza in restmap.conf sets up a custom endpoint at .../admin/<endpoint_name>

• [admin_external:<endpoint_name>]: names the endpoint
• handlertype: specifies the language of the REST endpoint script; must be set to python
• handlerfile: name of the python script in <app_name>/bin/
• handleractions: REST actions supported by the script. list takes the initial field values and displays them on the setup screen. edit handles the POSTed values from the saved setup screen.

Implement your endpoint with EAI

You write custom endpoints in Python, using Splunk's undocumented and unofficial Extensible Administration Interface (EAI).

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)

Initialize your field values

You can initialize your parameters in your python script, or you can use a custom configuration file. This example uses a file, myappsetup.conf. The stanza name in the file defines the name of the entity, setupentity.

[setupentity]
field_1 = 
field_3 = 60
field_2_boolean = 0

Create setup.xml

Once you have your endpoints, entities, and fields all figured out, you can put them in setup.xml.

<setup>
	<block title="Configure This App" endpoint="admin/customendpoint/" entity="setupentity">
		<text>
			Setup screen with custom endpoints
		</text>
		</block>
		<block title="A text input" endpoint="admin/customendpoint/" entity="setupentity">
		  <input field="field_1">
			<label>Enter your text</label>
			<type>text</type>
		  </input>
	</block>
	<block title="Enable this and set a numeric value" endpoint="admin/customendpoint/" entity="setupentity">
		<input field="field_2_boolean">
			<label>Enable This Input</label>
			<type>bool</type>
		</input>
		<input field="field_3" endpoint="admin/customendpoint/" entity="setupentity">
			<label>Set this number (minimum value=60)</label>
			<type>text</type>
			<validation>\d+</validation>
		</input>
	</block>
	<block title="Warning">
		<text>Please be patient and wait for this form to complete before navigating away from this page.</text>
	</block>
</setup>