Setup screen example using a custom endpoint

This example shows how to create a setup screen that use the Splunk Enterprise 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:

1. Create your custom configuration file with the initial values for your setup screen.
2. Create a stanza in restmap.conf that maps your endpoint to your custom configuration file.
3. Write a python script that initializes your setup screen and handles the user-entered values.
4. 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, the Splunk platform 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>