Migrate custom alert action HTML for ITSI

Choose a migration path

There are two approaches to making a custom alert action compatible with ITSI. Choose the approach that matches the scope of change you can make to your app.

Option 1: Generate the alert action with UCC

Use the Splunk Add-on UCC Framework when you can adopt a generated build process. Define the alert action and its fields in globalConfig.json; UCC generates the alert action HTML, alert_actions.conf, and Python entry-point wrapper.

This is the preferred approach for new alert actions and for apps already undergoing modernization. It avoids maintaining alert action HTML by hand and provides a consistent Splunk UI. Adopting UCC is broader than an HTML change: it also affects the app's source layout, build, packaging, configuration, and Python execution wrapper.

Public examples and documentation:

• UCC Framework
• Define alert actions with UCC
• UCC build and packaging commands
• Slack Alerts reference implementation

The UCC command ucc-gen import-from-aob is intended only for apps exported from Add-on Builder and is experimental. It is not a general migration command for arbitrary existing apps.

Option 2: Migrate the HTML manually

Use the remaining instructions in this guide when you need to preserve the existing app structure or make the smallest possible compatibility change.

Manual migration replaces legacy HTML controls with supported Splunk elements. It does not introduce UCC-generated configuration, packaging, or Python wrappers.

In this topic

• 1. Locate the alert action files
• 2. Inventory the legacy controls
• 3. Replace the legacy form structure
• 4. Replace native controls
• 5. Move labels, help text, and required state
• 6. Move defaults into alert_actions.conf
• 7. Remove unsupported styling and markup
• 8. Add stable test hooks when needed
• 9. Deploy and restart Splunk
• 10. Validate the migrated action

1. Locate the alert action files

Find the action's stanza in:

$SPLUNK_HOME/etc/apps/<app_name>/default/alert_actions.conf

Find its configuration UI in:

$SPLUNK_HOME/etc/apps/<app_name>/default/data/ui/alerts/<action_name>.html

The HTML filename must match the alert_actions.conf stanza name. Input names must use this format:

action.<action_name>.param.<parameter_name>

For example:

[my_ticket_action]
param.summary =
param.priority = medium

<splunk-text-input
    name="action.my_ticket_action.param.summary">
</splunk-text-input>

This naming contract ensures that values are saved correctly.

2. Inventory the legacy controls

Record each control's:

• Parameter name
• Label and help text
• Required or optional status
• Default value
• Static options or dynamic search
• Disabled state

Look for legacy constructs such as:

<div class="control-group">
<label class="control-label">
<div class="controls">
<span class="help-block">
<input>
<textarea>
<select>

Do not change the name attributes during migration unless you also intend to change the alert action's parameter contract.

3. Replace the legacy form structure

Convert each legacy control group into a direct child of <form> using <splunk-control-group>.

Before:

<form class="form-horizontal form-complex">
    <div class="control-group">
        <label class="control-label">
            Summary
            <span class="required">*</span>
        </label>
        <div class="controls">
            <textarea
                name="action.my_ticket_action.param.summary"
                rows="4"
                style="width: 400px;">
            </textarea>
            <span class="help-block">
                Describe the issue.
            </span>
        </div>
    </div>
</form>

After:

<form>
    <splunk-control-group
        label="Summary"
        help="Describe the issue."
        required="true">
        <splunk-text-area
            name="action.my_ticket_action.param.summary">
        </splunk-text-area>
    </splunk-control-group>
</form>

Each input must be a direct child of its splunk-control-group. Use one input per control group.

4. Replace native controls

Use this mapping:

Static selection example:

<splunk-control-group
    label="Priority"
    required="true"
    help="Select the incident priority.">
    <splunk-select
        name="action.my_ticket_action.param.priority">
        <option value="high">High</option>
        <option value="medium">Medium</option>
        <option value="low">Low</option>
    </splunk-select>
</splunk-control-group>

Dynamic selection example:

<splunk-control-group
    label="Primary detector"
    required="true"
    help="Select the detector associated with the incident.">
    <splunk-search-dropdown
        name="action.my_ticket_action.param.detector"
        search="| inputlookup detectors.csv"
        label-field="detector_name"
        value-field="detector_id">
    </splunk-search-dropdown>
</splunk-control-group>

Dynamic searches run with the current user's permissions. They should return only the fields and rows needed by the control. Do not put static <option> elements inside splunk-search-dropdown.

5. Move labels, help text, and required state

Move legacy metadata onto splunk-control-group:

<splunk-control-group
    label="Incident name"
    help="Enter a short description of the customer-impacting issue."
    required="true">

Remove the corresponding legacy elements:

<label>
<span class="required">
<span class="help-block">

required="true" displays the required state. It does not replace validation in the alert action implementation.

6. Move defaults into alert_actions.conf

Do not rely on:

• An input's value attribute
• <option selected>
• Placeholder text as a default value

The ITSI renderer does not reliably use these values to initialize form state. Put defaults in alert_actions.conf instead:

[my_ticket_action]
param.summary =
param.priority = medium

Keep the corresponding option in the HTML:

<option value="medium">Medium</option>

7. Remove unsupported styling and markup

Do not depend on:

• Bootstrap classes such as form-horizontal, control-group, or controls
• Inline style declarations
• width, height, rows, or cols
• CSS classes or element IDs for layout
• <style> or <script> elements
• HTML pattern validation

ITSI generates Splunk UI components from the form rather than rendering the HTML directly. Validate formats such as URLs in your alert action implementation.

Keep standalone informational paragraphs and links as direct children of <form>:

<form>
    <p>This action creates a ticket for the selected episode.</p>
    <splunk-control-group label="Summary">
        <splunk-text-input
            name="action.my_ticket_action.param.summary">
        </splunk-text-input>
    </splunk-control-group>
    <a href="https://example.com/runbook">Open the runbook</a>
</form>

For maximum compatibility, do not nest links inside splunk-control-group. Keep paragraph and link text plain rather than embedding headings, icons, or other formatting elements.

Use {{ SPLUNKWEB_URL_PREFIX }} when linking to resources served by Splunk Web.

8. Add stable test hooks when needed

Use data-test for automated UI tests:

<splunk-text-input
    data-test="my-ticket-summary-text"
    name="action.my_ticket_action.param.summary">
</splunk-text-input>

Treat data-test as a test hook, not a styling interface.

9. Deploy and restart Splunk

Package and deploy the updated app through your normal process. For Splunk Enterprise, restart Splunk Enterprise so that changes to the alert-action UI and configuration are loaded. For Splunk Cloud Platform, use the approved private-app deployment process and coordinate any required restart or ITSI upgrade activity with Splunk Support.

10. Validate the migrated action

Test the action on an ITSI development instance:

1. Open an episode in Episode Review.
2. Select the custom action.
3. Confirm every label, control, help message, and required indicator appears.
4. Confirm defaults from alert_actions.conf are selected.
5. Enter values, save the action, and reopen it to confirm persistence.
6. Verify search-driven dropdowns as both an administrator and the intended user role.
7. Run the action and verify the submitted parameter values.
8. Test empty, malformed, and unexpected input.
9. Check the browser console and Splunk logs for parsing or execution errors.

Troubleshooting