feat: add support for shortdesc, tags and examples in searchbnf.conf

docs/custom_search_commands.md

@@ -63,7 +63,10 @@ python.version = python3
 | requiredSearchAssistant                               | boolean | Specifies whether search assistance is required for the custom search command. Default: false. |
 | usage                                                 | string  | Defines the usage of custom search command. It can be one of `public`, `private` and `deprecated`.  |
 | description                                           | string  | Provide description of the custom search command.   |
+| shortdesc                                             | string  | A one sentence description of the search command, used for searchbnf.conf |
 | syntax                                                | string  | Provide syntax for custom search command   |
+| tags                                                  | string  | One or more words that users might type into the search bar which are similar to the command name. |
+| examples                                              | array[objects]  | List of example search strings, used for searchbnf.conf |
 
 To generate a custom search command, the following attributes must be defined in globalConfig: `commandName`, `commandType`, `fileName`, and `arguments`. Based on the provided commandType, UCC will generate a template Python file and integrate the user-defined logic into it.
 
@@ -133,6 +136,26 @@ For example:
 
 ```
 
+## Examples (for search command usage)
+
+| Property                                         | Type   | Description                                      |
+| ------------------------------------------------ | ------ | ------------------------------------------------ |
+| search<span class="required-asterisk">\*</span>  | string | Example search command                           |
+| comment<span class="required-asterisk">\*</span> | string | Provide description of the example search string |
+
+Each search command can have multiple examples, which are shown displayed in the search assistant. The Compact mode, only shows the first example. In the Full mode, the top three examples are displayed.
+
+For example:
+
+```json
+"examples": [
+    {
+        "search": "generatetextcommand count=5 text=\"Hallo There\"",
+        "comment": "Generates 5 \"Hallo There\" events enumerated starting by 1"
+    }
+]
+```
+
 ## Example
 
 ``` json
@@ -161,6 +184,12 @@ For example:
                     "name": "text",
                     "required": true
                 }
+            ],
+            "examples": [
+                {
+                    "search": "generatetextcommand count=5 text=\"Hallo There\"",
+                    "comment": "Generates 5 \"Hallo There\" events enumerated starting by 1"
+                }
             ]
         },
     ],

splunk_add_on_ucc_framework/generators/conf_files/create_searchbnf_conf.py

@@ -34,8 +34,11 @@ def __init__(
                     searchbnf_dict = {
                         "command_name": command["commandName"],
                         "description": command["description"],
+                        "shortdesc": command.get("shortdesc", None),
                         "syntax": command["syntax"],
                         "usage": command["usage"],
+                        "tags": command.get("tags", None),
+                        "examples": command.get("examples", []),
                     }
                     self.searchbnf_info.append(searchbnf_dict)
 

splunk_add_on_ucc_framework/global_config_validator.py

@@ -730,8 +730,11 @@ def _validate_custom_search_commands(self) -> None:
 
             if (command.get("requiredSearchAssistant", False) is False) and (
                 command.get("description")
+                or command.get("shortdesc")
                 or command.get("usage")
                 or command.get("syntax")
+                or command.get("tags")
+                or command.get("examples")
             ):
                 logger.warning(
                     "requiredSearchAssistant is set to false "

splunk_add_on_ucc_framework/schema/schema.json

@@ -461,6 +461,10 @@
           "type": "string",
           "description": "Description of the custom search command. It is an required attribute for searchbnf.conf."
         },
+        "shortdesc": {
+          "type": "string",
+          "description": "Short description or the custom search command, used as shortdesc in searchbnf.conf"
+        },
         "syntax": {
           "type": "string",
           "maxLength": 100,
@@ -475,12 +479,23 @@
             "deprecated"
           ]
         },
+        "tags": {
+          "type": "string",
+          "description": "One or more words that users might type into the search bar which are similar to the command name."
+        },
         "arguments": {
           "type": "array",
           "items": {
             "$ref": "#/definitions/arguments"
           },
           "minItems": 1
+        },
+        "examples": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/searchExample"
+          },
+          "minItems": 1
         }
       },
       "required": [
@@ -526,6 +541,25 @@
       ],
       "additionalProperties": false
     },
+    "searchExample": {
+      "type": "object",
+      "description": "Search example used for searchbnf.conf",
+      "properties": {
+        "search": {
+          "type": "string",
+          "description": "Example search string"
+        },
+        "comment": {
+          "type": "string",
+          "description": "Comment for the search string which is used for searchbnf.conf"
+        }
+      },
+      "required": [
+        "search",
+        "comment"
+      ],
+      "additionalProperties": false
+    },
     "CustomSearchCommandValidator": {
       "type": "object",
       "description": "It is used to validate the values of arguments for custom search command",

splunk_add_on_ucc_framework/templates/conf_files/searchbnf_conf.template

@@ -2,5 +2,15 @@
 [{{info["command_name"]}}-command]
 syntax = {{info["syntax"]}}
 description = {{info["description"]}}
+{% if info["shortdesc"]%}
+shortdesc = {{info["shortdesc"]}}
+{% endif %}
 usage = {{info["usage"]}}
+{% if info["tags"]%}
+tags = {{info["tags"]}}
+{% endif %}
+{% for example in info["examples"] %}
+example{{ loop.index }} = {{ example["search"] }}
+comment{{ loop.index }} = {{ example["comment"] }}
+{% endfor -%}
 {% endfor -%}

tests/unit/generators/conf_files/test_create_searchbnf_conf.py

@@ -14,6 +14,21 @@ def custom_search_command_without_search_assistance():
     ]
 
 
+@fixture
+def custom_search_command_without_optional_search_assistance_params():
+    return [
+        {
+            "commandName": "generatetextcommand",
+            "commandType": "generating",
+            "fileName": "generatetext.py",
+            "requiredSearchAssistant": True,
+            "description": "This command generates COUNT occurrences of a TEXT string.",
+            "syntax": "generatetextcommand count=<event_count> text=<string>",
+            "usage": "public",
+        }
+    ]
+
+
 def test_init_without_custom_command(
     global_config_only_configuration,
     input_dir,
@@ -42,8 +57,20 @@ def test_init(
         {
             "command_name": "generatetextcommand",
             "description": "This command generates COUNT occurrences of a TEXT string.",
+            "shortdesc": "Command for generating string events.",
             "syntax": "generatetextcommand count=<event_count> text=<string>",
             "usage": "public",
+            "tags": "text generator",
+            "examples": [
+                {
+                    "search": '| generatetextcommand count=5 text="example string"',
+                    "comment": 'Generates 5 events with text="example string"',
+                },
+                {
+                    "search": '| generatetextcommand count=10 text="another example string"',
+                    "comment": 'Generates 10 events with text="another example string"',
+                },
+            ],
         }
     ]
 
@@ -65,6 +92,33 @@ def test_init_without_search_assistance(
     assert searchbnf_conf.searchbnf_info == []
 
 
+def test_init_without_optional_search_assistance_params(
+    global_config_all_json,
+    input_dir,
+    output_dir,
+    custom_search_command_without_optional_search_assistance_params,
+):
+    global_config_all_json._content["customSearchCommand"] = (
+        custom_search_command_without_optional_search_assistance_params
+    )
+    searchbnf_conf = SearchbnfConf(
+        global_config_all_json,
+        input_dir,
+        output_dir,
+    )
+    assert searchbnf_conf.searchbnf_info == [
+        {
+            "command_name": "generatetextcommand",
+            "description": "This command generates COUNT occurrences of a TEXT string.",
+            "syntax": "generatetextcommand count=<event_count> text=<string>",
+            "usage": "public",
+            "examples": [],
+            "shortdesc": None,
+            "tags": None,
+        }
+    ]
+
+
 def test_generate_conf_without_custom_command(
     global_config_only_configuration,
     input_dir,
@@ -82,6 +136,46 @@ def test_generate_conf_without_custom_command(
 
 
 def test_generate_conf(global_config_all_json, input_dir, output_dir):
+    ta_name = global_config_all_json.product
+    searchbnf_conf = SearchbnfConf(
+        global_config_all_json,
+        input_dir,
+        output_dir,
+    )
+    output = searchbnf_conf.generate()
+    exp_fname = "searchbnf.conf"
+    expected_content = dedent(
+        """
+        [generatetextcommand-command]
+        syntax = generatetextcommand count=<event_count> text=<string>
+        description = This command generates COUNT occurrences of a TEXT string.
+        shortdesc = Command for generating string events.
+        usage = public
+        tags = text generator
+        example1 = | generatetextcommand count=5 text="example string"
+        comment1 = Generates 5 events with text="example string"
+        example2 = | generatetextcommand count=10 text="another example string"
+        comment2 = Generates 10 events with text="another example string"
+        """
+    ).lstrip()
+    assert output == [
+        {
+            "file_name": exp_fname,
+            "file_path": f"{output_dir}/{ta_name}/default/{exp_fname}",
+            "content": expected_content,
+        }
+    ]
+
+
+def test_generate_conf_without_optional_search_assistance_params(
+    global_config_all_json,
+    input_dir,
+    output_dir,
+    custom_search_command_without_optional_search_assistance_params,
+):
+    global_config_all_json._content["customSearchCommand"] = (
+        custom_search_command_without_optional_search_assistance_params
+    )
     ta_name = global_config_all_json.product
     searchbnf_conf = SearchbnfConf(
         global_config_all_json,

tests/unit/test_global_config.py

@@ -76,8 +76,10 @@ def test_global_config_custom_search_commands(global_config_all_json):
             "commandType": "generating",
             "requiredSearchAssistant": True,
             "description": "This command generates COUNT occurrences of a TEXT string.",
+            "shortdesc": "Command for generating string events.",
             "syntax": "generatetextcommand count=<event_count> text=<string>",
             "usage": "public",
+            "tags": "text generator",
             "arguments": [
                 {
                     "name": "count",
@@ -86,6 +88,16 @@ def test_global_config_custom_search_commands(global_config_all_json):
                 },
                 {"name": "text", "required": True},
             ],
+            "examples": [
+                {
+                    "search": '| generatetextcommand count=5 text="example string"',
+                    "comment": 'Generates 5 events with text="example string"',
+                },
+                {
+                    "search": '| generatetextcommand count=10 text="another example string"',
+                    "comment": 'Generates 10 events with text="another example string"',
+                },
+            ],
         }
     ]
     assert expected_result == custom_search_commands

tests/unit/testdata/valid_config.json

@@ -1377,8 +1377,10 @@
             "commandType": "generating",
             "requiredSearchAssistant": true,
             "description": "This command generates COUNT occurrences of a TEXT string.",
+            "shortdesc": "Command for generating string events.",
             "syntax": "generatetextcommand count=<event_count> text=<string>",
             "usage": "public",
+            "tags": "text generator",
             "arguments": [
                 {
                     "name": "count",
@@ -1393,6 +1395,16 @@
                     "name": "text",
                     "required": true
                 }
+            ],
+            "examples": [
+                {
+                    "search": "| generatetextcommand count=5 text=\"example string\"",
+                    "comment": "Generates 5 events with text=\"example string\""
+                },
+                {
+                    "search": "| generatetextcommand count=10 text=\"another example string\"",
+                    "comment": "Generates 10 events with text=\"another example string\""
+                }
             ]
         }
     ]