feat: release v5.19.0 (#601)

* refactor: introduce build subcommand (#593)

This is not a breaking change.

This PR introduces a subcommand `build`. The effect from running `ucc-gen` is the same as from running `ucc-gen build`, but running `ucc-gen` without a subcommand will be deprecated in the future releases.

* docs(README): ADDON-58505 support of style property in the configuration page (#594)

* refactor: move validators validation to the build phase (#595)

* refactor: move validators validation to the build phase

Currently build phase does not have any checks for the validators.
Some of the checks are done here:
https://github.com/splunk/addonfactory-ucc-base-ui/blob/283d5abcf8f462ac10de876464bc1719fd19ff90/src/main/webapp/util/uccConfigurationValidators.js#L170-L184
and they are not unit tested and only show errors during the runtime.

* test: add tests for inputs validators as well

* build(deps): bump dunamai from 1.14.1 to 1.15.0 (#584)

Bumps [dunamai](https://github.com/mtkennerly/dunamai) from 1.14.1 to 1.15.0.
- [Release notes](https://github.com/mtkennerly/dunamai/releases)
- [Changelog](https://github.com/mtkennerly/dunamai/blob/master/CHANGELOG.md)
- [Commits](mtkennerly/dunamai@v1.14.1...v1.15.0)

---
updated-dependencies:
- dependency-name: dunamai
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* chore: add importlib-metadata (#596)

* fix: add additional new line to globalConfig file (#598)

* feat: ucc-gen init command (#599)

* feat: ucc-gen init command

* chore: update licenses

* docs: ADDON-58758: Doc changes for the multi-level menu (#600)

* docs: ADDON-58758 Doc changes for the multilevel menu

* docs: ADDON-58758 Doc changes for the multilevel menu

* docs: ADDON-58758 Changed the screenshots

* feat: bump UCC UI to 5.19.0 (#602)

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: Tushar Balar <62089106+tbalar-splunk@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.licenserc.yaml

@@ -35,3 +35,4 @@ header:
     - "mkdocs.yml"
     - ".*"
     - "example/**"
+    - "splunk_add_on_ucc_framework/commands/init_template/**"

.pre-commit-config.yaml

@@ -44,3 +44,4 @@ repos:
     rev: 4.0.1
     hooks:
     -   id: flake8
+        exclude: ^splunk_add_on_ucc_framework/commands/init_template/

docs/additional_packaging.md

@@ -0,0 +1,10 @@
+# `additional_packaging.py` file
+
+To extend the build process, you can create `additional_packaging.py` file in the same file level where you have your globalConfig file.
+
+This file should have `additional_packaging` function which accepts 1 argument: add-on name.
+
+Example of how to utilize it:
+
+* Build custom UI after `ucc-gen` finishes all its necessary steps.
+* Workaround a `ucc-gen` feature which was not implemented.

docs/custom_ui_extensions/custom_hook.md

@@ -33,6 +33,7 @@ Use hook in the tabs:
 | state             | State is an object that represents the actual state value of the components in the service/tab when the hook's constructor is called. Updating this object will not update the state of the page. Use the `util.setState` method to update the page's state. |
 | mode              | There are three possible modes: Edit, Clone and Delete. Which are used in service/tab components. |
 | util              | This is a utility object with various functions that can be used to manipulate the page UI. There are 4 methods associated : <ul><li>`clearAllErrorMsg`: ƒ (State)</li><li>`setErrorFieldMsg`: ƒ (field, msg)</li><li>`setErrorMsg`: ƒ (msg)</li><li>`setState`: ƒ setState(callback)</li></ul>|
+| groupName         | The name of the menu group from which the inputs service is called. This parameter should only be used with the multi-level menu feature. |
 
 ### Methods
 
@@ -65,19 +66,26 @@ class Hook {
      * @param {string} mode - edit,create or clone
      * @param {object} util - the utility object
      */
-    constructor(globalConfig, serviceName, state, mode, util) {
+    constructor(globalConfig, serviceName, state, mode, util, groupName) {
         this.globalConfig = globalConfig;
         this.serviceName = serviceName;
         this.state = state;
         this.mode = mode;
         this.util = util;
+        this.groupName = groupName;
         this._debouncedNameChange = this.debounce(this._nameChange.bind(this), 200);
         console.log('Inside Hook mode: ', mode);
     }
 
     onCreate() {
         if (this.mode == "create") {
             console.log('in Hook: onCreate');
+            // This is an example of how to store groupName value for a particular form field.
+            this.util.setState((prevState) => {
+                let data = { ...prevState.data };
+                data.test_field.value = this.groupName;
+                return { data };
+            });
         }
     }
 

docs/index.md

@@ -13,6 +13,9 @@ action templates.
 Available as a GitHub action here:
 <https://github.com/splunk/addonfactory-ucc-generator-action>
 
+You can use [Splunk Extension for VSCode](https://marketplace.visualstudio.com/items?itemName=Splunk.splunk) 
+as well.
+
 ## What is UCC?
 
 UCC stands for Universal Configuration Console. The purpose of having a

docs/how_to_use.md → docs/quickstart.md

@@ -1,10 +1,10 @@
-# How To Use
+# Quickstart
 
 ## Prerequisites
 
 You need to have Python 3.7+ and Git available in the machine to be able to utilize `ucc-gen` command.
 
-> Git is used to generate the add-on version from Git tags. Alternatively you can use `--ta-version` parameter. More info [here](#parameters).
+> Git is used to generate the add-on version from Git tags. Alternatively you can use `--ta-version` parameter. More info below.
 
 To be able to create an add-on using UCC framework, you need to have at least:
 
@@ -14,13 +14,7 @@ To be able to create an add-on using UCC framework, you need to have at least:
 
 > If both globalConfig.json and globalConfig.yaml files are present, then the globalConfig.json file will take precedence.
 
-An example of creating a basic add-on can be found [here](example.md).
-
-### VSCode extension
-
-You can use [Splunk Extension for VSCode](https://marketplace.visualstudio.com/items?itemName=Splunk.splunk) as well.
-
-### JSON schema for globalConfig
+An example of creating a basic add-on from scratch can be found [here](example.md).
 
 The JSON schema for the `globalConfig` file can be found
 [here](https://github.com/splunk/addonfactory-ucc-base-ui/blob/main/src/main/webapp/schema/schema.json).
@@ -31,7 +25,9 @@ Refer to Splunkbase documentation
 [here](https://dev.splunk.com/enterprise/docs/releaseapps/splunkbase/namingguidelines/) 
 to figure out what should be the name of your add-on.
 
-## Steps to generate the add-on
+## Initialize new add-on
+
+> Initialization of the new add-on is available from `5.19.0` version of `ucc-gen`.
 
 Commands below are macOS and Linux specific.
 
@@ -42,7 +38,33 @@ python3 -m venv .venv
 source .venv/bin/activate
 ```
 
-* Install `splunk-add-on-ucc-framework` and `splunk-packaging-toolkit`
+* Install `splunk-add-on-ucc-framework`
+
+```bash
+pip install splunk-add-on-ucc-framework
+```
+
+* Initialize new add-on
+
+```bash
+ucc-gen init --addon-name "demo_addon_for_splunk" --addon-display-name "Demo Add-on for Splunk" --addon-input-name demo_input
+```
+
+The new add-on is located in `demo_addon_for_splunk` folder and can be built using 
+the commands [below](#steps-to-build-already-existing-add-on).
+
+## Build already existing add-on
+
+Commands below are macOS and Linux specific.
+
+* Set up and activate Python virtual environment (skip if you already have an environment)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+* Install `splunk-add-on-ucc-framework` and `splunk-packaging-toolkit` (skip if you already installed libraries)
 
 ```bash
 pip install splunk-add-on-ucc-framework splunk-packaging-toolkit
@@ -57,6 +79,8 @@ ucc-gen
 slim package output/<add-on-name>
 ```
 
+> Please use `ucc-gen build` instead of `ucc-gen` if you are using UCC `v5.19.0` and higher.
+
 Now you should see an archive created in the same level as your 
 `globalConfig.json` is located.
 
@@ -70,19 +94,42 @@ folder and extending their functionality. The generated inputs are using
 update the modular input code, you can run `ucc-gen` again and `ucc-gen` will 
 use updated modular inputs from `package/bin` instead of generating new ones.
 
-## Parameters
+## Commands
+
+As of now, running `ucc-gen` does the same thing as running `ucc-gen build`, 
+but eventually calling `ucc-gen` without specifying a subcommand will be 
+deprecated. 
+
+* `build` - build the add-on.
 
-`ucc-gen` supports the following params:
+    * `--source` - [optional] folder containing the `app.manifest` and app 
+        source.
+    * `--config` - [optional] path to the configuration file, defaults to
+        globalConfig file in the parent directory of source provided.
+    * `--ta-version` - [optional] override current version of TA, default
+        version is version specified in `globalConfig.json` or `globalConfig.yaml`. 
+        Splunkbase compatible version of SEMVER will be used by default.
+    * `--python-binary-name` - [optional] Python binary name to use when
+        installing Python libraries.
 
-* `source` - [optional] folder containing the `app.manifest` and app 
-    source.
-* `config` - [optional] path to the configuration file, defaults to
-    globalConfig file in the parent directory of source provided.
-* `ta-version` - [optional] override current version of TA, default
-    version is version specified in `globalConfig.json` or `globalConfig.yaml`. 
-    Splunkbase compatible version of SEMVER will be used by default.
-* `python-binary-name` - [optional] Python binary name to use when
-    installing Python libraries.
+* `init` - initialize the add-on (available from `v5.19.0`).
+
+    * `--addon-name` - [required] add-on name. Consult with 
+        [official naming convention guide](https://dev.splunk.com/enterprise/docs/releaseapps/splunkbase/namingguidelines/).
+    * `--addon-display-name` - [required] add-on "official" name.
+    * `--addon-input-name` - [required] name of the generated input. 
+    * `--addon-version` - [optional] version of the generated add-on, `0.0.1` by default.
+    * `--overwrite` - [optional] overwrites already existing folder if used, 
+        by default you can't generate a new add-on to already existing folder.
+
+`ucc-gen init` command initializes the add-on and bootstraps some code in the 
+modular input which you, as a developer, can extend for your needs.
+
+Apart from standard files needed for the add-on, it also adds search head 
+clustering files in `default/server.conf` file and reload triggers in 
+`default/app.conf` file. Those files will be generated automatically soon by 
+`ucc-gen build` command itself, for now you need to include them manually 
+during the add-on development.
 
 ## What `ucc-gen` does
 
@@ -104,14 +151,3 @@ use updated modular inputs from `package/bin` instead of generating new ones.
 * Copies addon's `package/*` to `output/<package_ID>/*` directory.
 * If an addon requires some additional configurations in packaging
     then `ucc-gen` runs the code in the `additional_packaging.py` file as well.
-
-## `additional_packaging.py` file
-
-To extend the build process, you can create `additional_packaging.py` file in the same file level where you have your globalConfig file.
-
-This file should have `additional_packaging` function which accepts 1 argument: add-on name.
-
-Example of how to utilize it:
-
-* Build custom UI after `ucc-gen` finishes all its necessary steps.
-* Workaround a `ucc-gen` feature which was not implemented.

docs/tabs.md

@@ -6,12 +6,18 @@ UCC currently supports 2 different types of tabs: "Configuration" and "Inputs".
 ## Configuration
 
 "Configuration" tab can have multiple different subtabs, for example, a tab
-for account configuration (name and API key), proxy configuration and logging 
+for account configuration (name and API key), proxy configuration and logging
 level configuration.
 
+### Tabs Properties
+
+| Property | Description |
+| -------- | ----------- |
+| style    | By specifying this property in the global config file, the forms can either be opened as a new page or in a dialog. <p>Supported values are "page" or "dialog".</p> <p> Default value is **dialog**. </p> |
+
 ## Inputs
 
-Holds input configuration information for data collection. 
+Holds input configuration information for data collection.
 If we have a variety of input configurations, we can create more than one input service under the input page.
 
 If there are multiple services in the globalConfig file, a dropdown will appear on the Input page.
@@ -21,7 +27,7 @@ If there is only one service, a button will be displayed instead of a dropdown l
 | ----------------- | ----------- |
 | style             | It is used to open the input service form in a page or dialog. The value of the style property can be `page` or `dialog`. <p> Default value is **dialog**. </p>  |
 
-This is how globalConfig looks like without tabs in the inputs page:
+This is how globalConfig looks like without tabs on the inputs page:
 ```
 "pages": {
     "inputs": {
@@ -108,6 +114,67 @@ Title and Description would change when changing the tab (If provided in the glo
 
 > Note:
 >
-> If the `table` property is provided in both the `inputs` and the `services`, the following error will be shown. ```instance.pages.inputs is not exactly one from [subschema 0],[subschema 1]```
+> When using the Tabs feature, if the `table`  or `description` property is provided in the `inputs`, the error ```instance.pages.inputs is not one of [subschema 0], [subschema 1]``` will be displayed.
 >
 > [Custom menu](https://splunk.github.io/addonfactory-ucc-generator/custom_ui_extensions/custom_menu/) is not supported in the tabs feature.
+
+### Multi-level Menu
+
+This feature allows you to organize the input services into different categories. As a result, each group/category will have a separate sub-menu that can include numerous types of input services. Inputs services can also belong to multiple groups/categories.
+
+Using the [Custom Hook](https://splunk.github.io/addonfactory-ucc-generator/custom_ui_extensions/custom_hook/), `groupName` can be saved in any form field for a specific inputs service stanza.
+
+> `Tabs` and the `multi-level menu` cannot be used together.
+
+#### Usage
+```
+"inputs": {
+    "title": "Inputs",
+    "table": {},
+    "groupsMenu": [
+        {
+            "groupName": "group_one",
+            "groupTitle": "Group One",
+            "groupServices": ["example_input_one", "example_input_two"]
+        },
+        {
+            "groupName": "example_input_three", 
+            "groupTitle": "Example Input Three"
+        },
+        {
+            "groupName": "group_two",
+            "groupTitle": "Group Two",
+            "groupServices": ["example_input_two", "example_input_four"]
+        }
+    ]
+    "services": [
+        {
+            "name": "example_input_one",
+            "title": "Distinct Input One"
+            "entity": []
+        },
+        {
+            "name": "example_input_two",
+            "title": "Common Input Service"
+            "entity": []
+        },
+        {
+            "name": "example_input_three",
+            "title": "Example Input Three"
+            "entity": []
+        },
+        {
+            "name": "example_input_four",
+            "title": "Distinct Input Two"
+            "entity": []
+        }
+    ]
+}
+```
+> Note: If `groupServices` is provided under a group, then all services listed in the array will be displayed in the subMenu. If it is not provided, then that group will be considered as a service.
+
+#### Output
+This is how the Multi-level Menu will look:
+
+![image](images/Main_Menu_on_inputs_page.png)
+![image](images/Sub_Menu_on_inputs_page.png)

example/globalConfig.json

@@ -15,8 +15,8 @@
                                 {
                                     "type": "string",
                                     "maxLength": 80,
-                                    "errorMsg": "Maximum length allowed for index is 80",
-                                    "minLength": 1
+                                    "minLength": 1,
+                                    "errorMsg": "Maximum length allowed for index is 80"
                                 }
                             ],
                             "field": "index",
@@ -161,8 +161,8 @@
     "meta": {
         "name": "Splunk_TA_dummy_data",
         "restRoot": "Splunk_TA_dummy_data",
-        "version": "5.18.0R204e10cd",
+        "version": "5.18.0R05a4667a",
         "displayName": "Splunk_TA_dummy_data",
         "schemaVersion": "0.0.3"
     }
-}
+}

example/package/bin/dummy_input.py

@@ -45,7 +45,7 @@ def stream_events(self, inputs, ew):
                 {"dummy": "data"},
             ]
             event = smi.Event(
-                data=json.dumps(dummy_data_to_ingest),
+                data=json.dumps(dummy_data_to_ingest, ensure_ascii=False, default=str),
                 sourcetype='dummy_input',
             )
             ew.write_event(event)

get-ucc-ui.sh

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-wget https://github.com/splunk/addonfactory-ucc-base-ui/releases/download/v1.18.0/splunk-ucc-ui.tgz
+wget https://github.com/splunk/addonfactory-ucc-base-ui/releases/download/v1.19.0/splunk-ucc-ui.tgz

mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: Splunk Add-on UCC Framework
+site_name: UCC Framework
 site_author: Splunk
 site_url: "https://splunk.github.io/addonfactory-ucc-generator/"
 edit_uri: "tree/main/docs/"
@@ -23,10 +23,11 @@ theme:
 
 nav:
   - Home: "index.md"
-  - How to use: "how_to_use.md"
+  - Quickstart: "quickstart.md"
   - Example: "example.md"
   - Components: "components.md"
   - Tabs: "tabs.md"
+  - Additional packaging: "additional_packaging.md"
   - Custom UI Extensions:
     - Custom Hook: "custom_ui_extensions/custom_hook.md"
     - Custom Control: "custom_ui_extensions/custom_control.md"