feat: provide support for custom search command #1534

hetangmodi-crest · 2025-01-20T15:47:07Z

Issue number:
ADDON-76780

PR Type

What kind of change does this PR introduce?

Summary

Added support for custom search command

Changes

customSearchCommand tag has been added to the global configuration, allowing users to generate their custom search commands using ucc-gen build. Users only need to define the logic for their command and update the customSearchCommand in globalConfig.

User experience

Users can now generate custom search commands using the ucc-gen build command. To do so, they need to define the command logic and update the globalConfig accordingly.

Checklist

If an item doesn't apply to your changes, leave it unchecked.

I have performed a self-review of this change according to the development guidelines
Tests have been added/modified to cover the changes (testing doc)
Changes are documented
PR title and description follows the contributing principles

kkedziak-splunk · 2025-02-06T10:46:33Z

Let me review this extensive pull request that adds support for custom search commands.

Suggested pull request title: feat: add custom search command support

The pull request demonstrates high quality and introduces significant enhancements to the add-on UCC framework. Here's what I appreciate about it:

Well-structured implementation of custom search command support with proper templates and validation
Comprehensive test coverage with unit and smoke tests
Documentation updates explaining the new feature and its configuration
UI improvements including:
- New CheckboxTree component
- Better form control styling and accessibility
- Updated dependencies and build system

Here are a few specific suggestions for improvement:

For better mutation test coverage, consider adding more edge cases to test error handling in the custom search command generation
The documentation could benefit from more code examples showing common custom search command use cases
Consider adding validation to ensure command names follow Splunk's naming conventions

The changes appear suitable for merging once any testing feedback has been addressed. The commits are cleanly organized and the changes ready for review.

The best feature of this PR is its comprehensive approach - not just implementing the core functionality but also adding proper tests, documentation and sample code.

Great job on the PR organization and quality of implementation. Feel free to merge once CI passes and any testing feedback has been addressed.

This comment was added by our PR Review Assistant Bot. Please kindly acknowledge that
while we're doing our best to keep these comments up to very high standards, they may occasionally be
incorrect. Suggestions offered by the Bot are only intended as points for consideration and no statements
by this bot alone can be considered grounds for merging of any pull request. Remember to seek a review
from a human co-worker.

To reply to the review and engage Review Bot in further conversation, start your comment with the words Review bot:

kkedziak-splunk · 2025-02-06T10:49:41Z

Just tested the PR review bot

docs/custom_search_commands.md

splunk_add_on_ucc_framework/schema/schema.json

splunk_add_on_ucc_framework/commands/build.py

splunk_add_on_ucc_framework/templates/custom_command/eventing.template

kkedziak-splunk · 2025-02-06T14:47:27Z

splunk_add_on_ucc_framework/templates/custom_command/eventing.template

+    , require=False
+    {%- endif -%}
+
+    {%- if arg.validate -%}


This is a very complicated IF. Maybe it should be done outside of the template?

It could be passed as a string.

It is a nested if-else ladder, but yes the conditions are seem long due to the Jinja2 template.
Doing it outside in the Python scripts would work, but I don't think it would be a patch, as the templates should be providing the skeleton and the values then fill in the muscles and organs.

splunk_add_on_ucc_framework/commands/build.py

mkdocs.yml

docs/generated_files.md

artemrys · 2025-02-17T19:35:57Z

splunk_add_on_ucc_framework/commands/build.py

+                if (command["requireSeachAssistant"] is False) and (
+                    command.get("description")
+                    or command.get("usage")
+                    or command.get("syntax")
+                ):


Can you please check is it possible to have this logic in the schema.json? Or would it be too complicated for the JSON schema to handle?

Yes, it is possible to implement the above logic in JSON schema the reason I think we shouldn't go with schema.json approach is because,

JSON Schema validators typically reject invalid data, rather than logging a warning, and in this case I don't think we should stop the build process.

JSON Schema library does not support custom error messages directly. It is better to validate and raise warning through above logic.

splunk_add_on_ucc_framework/commands/build.py

artemrys · 2025-02-17T19:38:18Z

splunk_add_on_ucc_framework/commands/build.py

+                        " is not been defined in globalConfig. Defined them as requireSeachAssistant is set to True. "
+                    )
+                    sys.exit(1)
+                if command["version"] == 1:


Should we not support version 1? We mention in this PR that it is deprecated.

Though version 1 is deprecated, we should support it as add-ons like ServiceNow and BMC Remedy uses version 1 for their custom search commands, hence I kept it.

Let's remove it from UCC, I'll create a Jira for the team to move to the version 2.

Btw, I checked both those add-ons and I can't find version in commands.conf. Is there another way to figure out which version do they use?

The determination of version is can be seen based on this description.

Okay, I'll remove the support of version 1 from this PR.

Removed the support of version 1.

artemrys · 2025-02-17T19:39:02Z

splunk_add_on_ucc_framework/generators/conf_files/create_commands_conf.py

+            for command in kwargs["custom_search_commands"]:
+                self.command_names.append(command["commandName"])
+
+    def generate_conf(self) -> Union[Dict[str, str], None]:


What happens if there is a commands.conf file already in the package folder?

If the commands.conf is present in the package folder, it would overwrite the one we generated, as it is done for the other conf files (except app.conf). Do we want to merge the generated and source content of the conf files?

artemrys · 2025-02-17T19:41:50Z

splunk_add_on_ucc_framework/generators/python_files/create_custom_command_python.py

+                    src_pkg_bin = os.path.realpath(os.path.join(self._input_dir, "bin"))
+                    sys.path.insert(0, src_pkg_bin)
+                    if hasattr(import_module(command["fileName"]), "map"):
+                        import_map = True
+                    sys.path.pop(0)


Can you please explain what are we trying to achieve here?

For reporting type of custom search command, map method is optional, hence we check whether the developer has implemented this map method or not.

kkedziak-splunk · 2025-02-20T08:12:57Z

splunk_add_on_ucc_framework/templates/custom_command/reporting.template

+
+    {% if import_map %}
+    @Configuration()
+    def map(self, events):


Can't we always add this method, without this check with importing the command? Would it have any drawbacks?

map is an optional method which is used for streaming preop, if there is no need of pre-operation then we can remove this method.
(reference)

kkedziak-splunk

I copied the minimal definition from the docs to splunk-example-ta, created an empty mycommandlogic.py file and built it. I got the following exception:

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/Users/kkedziak/PycharmProjects/addonfactory-ucc-generator/splunk_add_on_ucc_framework/main.py", line 244, in main
    build.generate(
  File "/Users/kkedziak/PycharmProjects/addonfactory-ucc-generator/splunk_add_on_ucc_framework/commands/build.py", line 519, in generate
    if (command["requireSeachAssistant"] is False) and (
KeyError: 'requireSeachAssistant'

kkedziak-splunk · 2025-03-04T16:05:53Z

splunk_add_on_ucc_framework/commands/build.py

+                )
+                sys.exit(1)
+
+            if (command["requireSeachAssistant"] is False) and (


Suggested change

if (command["requireSeachAssistant"] is False) and (

if (command["requiredSearchAssistant"] is False) and (

and typos in other occurences of this phrase (compared with docs)

Thank you for pointing it out, I have made the respective changes in all files.

artemrys · 2025-03-05T09:40:14Z

Let's wait with merging this one, I'd like to discuss @kkedziak-splunk's document first and find consensus in the team.

splunk_add_on_ucc_framework/commands/build.py

splunk_add_on_ucc_framework/generators/conf_files/create_searchbnf_conf.py

sgoral-splunk · 2025-03-05T13:22:10Z

tests/testdata/test_addons/package_global_config_everything/additional_packaging.py

    files_to_delete.append(sep.join([output_path, ta_name, "bin", "template_rest_handler_script.py"]))
    files_to_delete.append(sep.join([output_path, ta_name, "bin", "file_does_not_exist.py"]))
    files_to_delete.append(sep.join([output_path, ta_name, "default", "nav", "views", "file_copied_from_source_code.xml"]))
+    files_to_delete.append(sep.join([output_path, ta_name, "bin", "__pycache__", "sum_without_map.cpython-37.pyc"]))


I don't think we should keep this (or TA devs). Maybe we should clean this up?
EDIT: my mistake. Ignore this comment.

github-actions · 2025-03-21T12:18:24Z

Code Coverage ⚠️

Type	PR	Develop	Change	Status
Line Coverage	86.84%	86.90%	0.05%	🔴 Decreased
Branch Coverage	79.83%	80.12%	0.29%	🔴 Decreased

sgoral-splunk · 2025-04-10T10:51:23Z

splunk_add_on_ucc_framework/templates/custom_command/eventing.template

+        {%- if (arg.validate.type == "Integer" or arg.validate.type == "Float") -%}
+            {%- if (arg.validate.minimum and arg.validate.maximum) -%}
+            , validate=validators.{{ arg.validate.type }}(minimum={{ arg.validate.minimum }}, maximum={{ arg.validate.maximum }})
+            {%- elif (arg.validate.minimum and not arg.validate.maximum) -%}
+            , validate=validators.{{ arg.validate.type }}(minimum={{ arg.validate.minimum }})
+            {%- elif (not arg.validate.minimum and arg.validate.maximum) -%}
+            , validate=validators.{{ arg.validate.type }}(maximum={{ arg.validate.maximum }})
+            {%- else -%}
+            , validate=validators.{{ arg.validate.type }}()
+            {%- endif -%}
+        {%- else -%}
+        , validate=validators.{{ arg.validate.type }}()
+        {%- endif -%}
+    {%- endif -%}


Are we going to move this logic out of the template? I think we agreed to do that in a meeting two weeks ago, but maybe something has changed

hetangmodi-crest · 2025-05-07T10:02:12Z

Closing the PR as it has been broken down into new PRs.

hetangmodi-crest added 4 commits January 20, 2025 21:01

feat: custom seach command feature

84c9d33

feat: template files for custom search command feature

b5989f6

tests(unit): add unit test cases

039fe0d

tests(smoke): add files for smoke test case

7432330

hetangmodi-crest added the enhancement New feature or request label Jan 20, 2025

hetangmodi-crest self-assigned this Jan 20, 2025

pull-request-size bot added the size/XXL label Jan 20, 2025

hetangmodi-crest and others added 3 commits January 20, 2025 21:21

Merge branch 'develop' into feat/custom-search-command

3802847

doc: update docs, fix lint

fda2c7f

ci: fix app_inspect failure

85be57e

hetangmodi-crest marked this pull request as ready for review January 23, 2025 11:58

hetangmodi-crest requested review from a team as code owners January 23, 2025 11:58

hetangmodi-crest and others added 3 commits January 24, 2025 16:56

test(smoke): update smoke tests, add better handling

d73930c

chore: resolve merge conflict

d4e3f3e

Merge branch 'develop' into feat/custom-search-command

181da69

hetangmodi-crest requested review from artemrys, kkedziak-splunk and sgoral-splunk January 30, 2025 05:24

hetangmodi-crest and others added 2 commits February 4, 2025 12:05

fix: update schema.json

2e288e7

Merge branch 'develop' into feat/custom-search-command

d90a475

kkedziak-splunk reviewed Feb 6, 2025

View reviewed changes

hetangmodi-crest and others added 6 commits February 7, 2025 12:04

chore: merge branch 'develop' into feat/custom-search-command

f8d6ce3

feat: generate files using FileGenerator class

1425f9b

tests: add unit and smoke test cases

1ef0399

doc: update documentation

b68d9a6

Merge branch 'develop' into feat/custom-search-command

3951671

docs: updated docs regarding generated conf, xml and html files

b3a42b6

artemrys requested changes Feb 17, 2025

View reviewed changes

hetangmodi-crest and others added 2 commits February 19, 2025 11:31

docs: resolve typos

8119835

Merge branch 'develop' into feat/custom-search-command

afc6bbb

hetangmodi-crest requested a review from artemrys February 19, 2025 12:44

Merge branch 'develop' into feat/custom-search-command

5f44b3a

kkedziak-splunk approved these changes Mar 4, 2025

View reviewed changes

kkedziak-splunk self-requested a review March 4, 2025 13:15

kkedziak-splunk requested changes Mar 4, 2025

View reviewed changes

kkedziak-splunk reviewed Mar 4, 2025

View reviewed changes

hetangmodi-crest added 2 commits March 5, 2025 13:16

chore: fix typos in source code

4f0a32f

ci: fix globalConfig everything

8823338

sgoral-splunk reviewed Mar 5, 2025

View reviewed changes

hetangmodi-crest and others added 6 commits March 10, 2025 14:51

feat: added check for Splunk built-in commands

a7ec116

chore: merge branch 'develop' into feat/custom-search-command

9986ec3

chore: add license headers

e47b2cd

refactor: removed version 1 support

1adadbb

tests: updated unit test cases

ff8da5b

Merge branch 'develop' into feat/custom-search-command

24d9860

hetangmodi-crest requested review from kkedziak-splunk and sgoral-splunk March 17, 2025 06:05

hetangmodi-crest and others added 3 commits March 17, 2025 11:35

Merge branch 'develop' into feat/custom-search-command

b9a73e3

chore: Merge branch 'develop' into feat/custom-search-command

80d43e6

chore: merge branch 'develop' into feat/custom-search-command

d9c8229

sgoral-splunk reviewed Apr 10, 2025

View reviewed changes

hetangmodi-crest closed this May 7, 2025

github-actions bot locked and limited conversation to collaborators May 7, 2025

hetangmodi-crest deleted the feat/custom-search-command branch May 7, 2025 10:02

	if (command["requireSeachAssistant"] is False) and (
	if (command["requiredSearchAssistant"] is False) and (

feat: provide support for custom search command #1534

feat: provide support for custom search command #1534

Uh oh!

Conversation

hetangmodi-crest commented Jan 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Type

Summary

Changes

User experience

Checklist

Uh oh!

kkedziak-splunk commented Feb 6, 2025

Uh oh!

kkedziak-splunk commented Feb 6, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkedziak-splunk left a comment

Choose a reason for hiding this comment

Uh oh!

kkedziak-splunk Mar 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

artemrys commented Mar 5, 2025

Uh oh!

Uh oh!

Uh oh!

sgoral-splunk Mar 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 21, 2025

Code Coverage ⚠️

Uh oh!

Choose a reason for hiding this comment

hetangmodi-crest commented Jan 20, 2025 •

edited

Loading

kkedziak-splunk Mar 4, 2025 •

edited

Loading

sgoral-splunk Mar 5, 2025 •

edited

Loading