splunk-soar-sdk 2.1.0__tar.gz → 2.2.0__tar.gz

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: splunk-soar-sdk
-Version: 2.1.0
+Version: 2.2.0
 Summary: The official framework for developing and testing Splunk SOAR Apps
 Project-URL: Homepage, https://github.com/phantomcyber/splunk-soar-sdk
 Project-URL: Documentation, https://github.com/phantomcyber/splunk-soar-sdk

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "splunk-soar-sdk"
-version = "2.1.0"
+version = "2.2.0"
 description = "The official framework for developing and testing Splunk SOAR Apps"
 readme = "README.md"
 requires-python = ">=3.9, <3.14"

splunk_soar_sdk-2.2.0/release_notes.txt

@@ -0,0 +1,21 @@
+# [2.2.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/2.1.1...2.2.0) (2025-10-01)
+
+
+### Features
+
+* render as option ([08405b5](https://github.com/phantomcyber/splunk-soar-sdk/commit/08405b5b38d3df1239fecf7ddc8175727c9b2827))
+
+
+
+
+
+# [2.2.0](https://github.com/phantomcyber/splunk-soar-sdk/compare/2.1.1...2.2.0) (2025-10-01)
+
+
+### Features
+
+* render as option ([08405b5](https://github.com/phantomcyber/splunk-soar-sdk/commit/08405b5b38d3df1239fecf7ddc8175727c9b2827))
+
+
+
+

splunk_soar_sdk-2.2.0/release_version.txt

@@ -0,0 +1 @@
+2.2.0

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/src/soar_sdk/action_results.py

@@ -83,12 +83,16 @@ class OutputFieldSpecification(TypedDict):
     data_type: str
     contains: NotRequired[list[str]]
     example_values: NotRequired[list[Union[str, float, bool]]]
+    column_name: NotRequired[str]
+    column_order: NotRequired[int]
 
 
 def OutputField(
     cef_types: Optional[list[str]] = None,
     example_values: Optional[list[Union[str, float, bool]]] = None,
     alias: Optional[str] = None,
+    column_name: Optional[str] = None,
+    column_order: Optional[int] = None,
 ) -> Any:  # noqa: ANN401
     """Define metadata for an action output field.
 
@@ -102,6 +106,11 @@ def OutputField(
         example_values: Optional list of example values for this field, used
             in documentation and for testing/validation purposes.
         alias: Optional alternative name for the field when serialized.
+        column_name: Optional name for the field when displayed in a table.
+        column_order: Optional order for the field when displayed in a table (0-indexed).
+
+    Note:
+        Column name and order must be set together, if one is set but the other is not, an error will be raised.
 
     Returns:
         A Pydantic Field object with the specified metadata.
@@ -116,8 +125,10 @@ def OutputField(
     """
     return Field(
         examples=example_values,
-        cef_types=cef_types,
         alias=alias,
+        cef_types=cef_types,
+        column_name=column_name,
+        column_order=column_order,
     )
 
 
@@ -230,6 +241,21 @@ class ActionOutput(BaseModel):
             if field_type is bool:
                 schema_field["example_values"] = [True, False]
 
+            # Validate column metadata - both column_name and column_order must be present together
+            column_name = field.field_info.extra.get("column_name")
+            column_order = field.field_info.extra.get("column_order")
+
+            # Check if exactly one is set (XOR condition - invalid)
+            if (column_name is None) != (column_order is None):
+                raise ValueError(
+                    f"Field '{field_name}' must have both 'column_name' and 'column_order' "
+                    f"or neither. Found: column_name={column_name}, column_order={column_order}"
+                )
+
+            if column_name is not None and column_order is not None:
+                schema_field["column_name"] = column_name
+                schema_field["column_order"] = column_order
+
             yield schema_field
 
 

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/src/soar_sdk/app.py

@@ -237,6 +237,7 @@ class App:
         read_only: bool = True,
         params_class: Optional[type[Params]] = None,
         output_class: Optional[type[ActionOutput]] = None,
+        render_as: Optional[str] = None,
         view_handler: Union[str, Callable, None] = None,
         view_template: Optional[str] = None,
         versions: str = "EQ(*)",
@@ -355,6 +356,7 @@ class App:
             read_only=read_only,
             params_class=params_class,
             output_class=output_class,
+            render_as=render_as,
             view_handler=view_handler,
             versions=versions,
             summary_type=summary_type,
@@ -421,6 +423,7 @@ class App:
         read_only: bool = True,
         params_class: Optional[type[Params]] = None,
         output_class: Optional[type[ActionOutput]] = None,
+        render_as: Optional[str] = None,
         view_handler: Optional[Callable] = None,
         versions: str = "EQ(*)",
         summary_type: Optional[type[ActionOutput]] = None,
@@ -440,6 +443,7 @@ class App:
             read_only=read_only,
             params_class=params_class,
             output_class=output_class,
+            render_as=render_as,
             view_handler=view_handler,
             versions=versions,
             summary_type=summary_type,
@@ -647,9 +651,17 @@ class App:
             statuses = []
             for item in result:
                 statuses.append(
-                    App._adapt_action_result(item, actions_manager, action_params)
+                    App._adapt_action_result(
+                        item, actions_manager, action_params, message, summary
+                    )
+                )
+            # Handle empty list/iterator case
+            if not statuses:
+                result = ActionOutput(
+                    status=True, message=message or "Action completed successfully"
                 )
-            return all(statuses)
+            else:
+                return all(statuses)
 
         if isinstance(result, ActionOutput):
             output_dict = result.dict(by_alias=True)

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/src/soar_sdk/decorators/action.py

@@ -39,6 +39,7 @@ class ActionDecorator:
             AsyncGenerator[type[ActionOutput]],
             list[type[ActionOutput]],
         ] = None,
+        render_as: Optional[str] = None,
         view_handler: Optional[Callable] = None,
         versions: str = "EQ(*)",
         summary_type: Optional[type[ActionOutput]] = None,
@@ -53,6 +54,7 @@ class ActionDecorator:
         self.read_only = read_only
         self.params_class = params_class
         self.output_class = output_class
+        self.render_as = render_as
         self.view_handler = view_handler
         self.versions = versions
         self.summary_type = summary_type
@@ -100,6 +102,14 @@ class ActionDecorator:
                 "Return type for action function must be derived from ActionOutput class."
             )
 
+        if self.view_handler:
+            self.render_as = "custom"
+
+        if self.render_as and self.render_as not in ("table", "json", "custom"):
+            raise ValueError(
+                "Please only specify render_as as 'table' or 'json' or 'custom'."
+            )
+
         @action_protocol
         @wraps(function)
         def inner(
@@ -152,6 +162,7 @@ class ActionDecorator:
             parameters=validated_params_class,
             output=validated_output_class,
             versions=self.versions,
+            render_as=self.render_as,
             view_handler=self.view_handler,
             summary_type=self.summary_type,
             enable_concurrency_lock=self.enable_concurrency_lock,

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/src/soar_sdk/meta/actions.py

@@ -20,6 +20,7 @@ class ActionMeta(BaseModel):
     verbose: str = ""
     parameters: Type[Params] = Field(default=Params)  # noqa: UP006
     output: Type[ActionOutput] = Field(default=ActionOutput)  # noqa: UP006
+    render_as: Optional[str] = None
     view_handler: Optional[Callable] = None
     summary_type: Optional[Type[ActionOutput]] = Field(default=None, exclude=True)  # noqa: UP006
     enable_concurrency_lock: bool = False
@@ -31,6 +32,13 @@ class ActionMeta(BaseModel):
         data["output"] = OutputsSerializer.serialize_datapaths(
             self.parameters, self.output, summary_class=self.summary_type
         )
+        if self.view_handler:
+            self.render_as = "custom"
+
+        if self.render_as:
+            data["render"] = {
+                "type": self.render_as,
+            }
 
         if self.view_handler:
             remove_when_soar_newer_than("6.4.1")
@@ -45,13 +53,11 @@ class ActionMeta(BaseModel):
             else:
                 relative_module = module
 
-            data["render"] = {
-                "type": "custom",
-                "view": f"{relative_module}.{self.view_handler.__name__}",
-            }
+            data["render"]["view"] = f"{relative_module}.{self.view_handler.__name__}"
 
         # Remove view_handler from the output since in render
         data.pop("view_handler", None)
+        data.pop("render_as", None)
 
         if self.enable_concurrency_lock:
             data["lock"] = {"enabled": True}

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/tests/cli/test_deserializers.py

@@ -438,7 +438,11 @@ def test_from_action_json_with_parameters_and_output(mock_action_deserializer):
             },
         },
         "output": [
-            {"data_path": "action_result.data.*.result"},
+            {
+                "data_path": "action_result.data.*.result",
+                "column_name": "Result",
+                "column_order": 0,
+            },
             {"data_path": "action_result.summary.total_items"},
         ],
     }

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/tests/cli/test_serializers.py

@@ -153,13 +153,18 @@ def test_outputs_serialize_with_defaults():
 
 def test_outputs_serialize_output_class():
     class SampleNestedOutput(ActionOutput):
-        bool_value: bool
+        bool_value: bool = OutputField(column_name="Nested Value", column_order=1)
 
     class SampleOutput(ActionOutput):
         string_value: str
         int_value: int
         list_value: list[str]
-        cef_value: str = OutputField(cef_types=["ip"], example_values=["1.1.1.1"])
+        cef_value: str = OutputField(
+            cef_types=["ip"],
+            example_values=["1.1.1.1"],
+            column_name="CEF Value",
+            column_order=0,
+        )
         nested_value: SampleNestedOutput
         underscored_value: str = OutputField(alias="_underscored_value")
 
@@ -192,11 +197,15 @@ def test_outputs_serialize_output_class():
             "data_type": "string",
             "contains": ["ip"],
             "example_values": ["1.1.1.1"],
+            "column_name": "CEF Value",
+            "column_order": 0,
         },
         {
             "data_path": "action_result.data.*.nested_value.bool_value",
             "data_type": "boolean",
             "example_values": [True, False],
+            "column_name": "Nested Value",
+            "column_order": 1,
         },
         {
             "data_path": "action_result.data.*._underscored_value",

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/tests/example_app/app.json

@@ -99,6 +99,208 @@
                 }
             ]
         },
+        {
+            "action": "test summary with list output",
+            "description": "test summary with list output",
+            "identifier": "test_summary_with_list_output",
+            "output": [
+                {
+                    "data_path": "action_result.status",
+                    "data_type": "string",
+                    "example_values": [
+                        "success",
+                        "failure"
+                    ]
+                },
+                {
+                    "data_path": "action_result.message",
+                    "data_type": "string"
+                },
+                {
+                    "data_path": "summary.total_objects",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                },
+                {
+                    "data_path": "summary.total_objects_successful",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                }
+            ],
+            "parameters": {},
+            "read_only": true,
+            "type": "generic",
+            "verbose": "",
+            "versions": "EQ(*)"
+        },
+        {
+            "action": "test empty list output",
+            "description": "test empty list output",
+            "identifier": "test_empty_list_output",
+            "output": [
+                {
+                    "data_path": "action_result.status",
+                    "data_type": "string",
+                    "example_values": [
+                        "success",
+                        "failure"
+                    ]
+                },
+                {
+                    "data_path": "action_result.message",
+                    "data_type": "string"
+                },
+                {
+                    "data_path": "summary.total_objects",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                },
+                {
+                    "data_path": "summary.total_objects_successful",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                }
+            ],
+            "parameters": {},
+            "read_only": true,
+            "type": "generic",
+            "verbose": "",
+            "versions": "EQ(*)"
+        },
+        {
+            "action": "test json output",
+            "identifier": "test_json_output",
+            "description": "test json output",
+            "type": "generic",
+            "read_only": true,
+            "versions": "EQ(*)",
+            "verbose": "",
+            "parameters": {},
+            "output": [
+                {
+                    "data_path": "action_result.status",
+                    "data_type": "string",
+                    "example_values": [
+                        "success",
+                        "failure"
+                    ]
+                },
+                {
+                    "data_path": "action_result.message",
+                    "data_type": "string"
+                },
+                {
+                    "data_path": "action_result.data.*.name",
+                    "data_type": "string",
+                    "example_values": [
+                        "John",
+                        "Jane",
+                        "Jim"
+                    ],
+                    "column_name": "Name",
+                    "column_order": 0
+                },
+                {
+                    "data_path": "action_result.data.*.age",
+                    "data_type": "numeric",
+                    "example_values": [
+                        25,
+                        30,
+                        35
+                    ],
+                    "column_name": "Age",
+                    "column_order": 1
+                },
+                {
+                    "data_path": "summary.total_objects",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                },
+                {
+                    "data_path": "summary.total_objects_successful",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                }
+            ],
+            "render": {
+                "type": "json"
+            }
+        },
+        {
+            "action": "test table output",
+            "identifier": "test_table_output",
+            "description": "test table output",
+            "type": "generic",
+            "read_only": true,
+            "versions": "EQ(*)",
+            "verbose": "",
+            "parameters": {},
+            "output": [
+                {
+                    "data_path": "action_result.status",
+                    "data_type": "string",
+                    "example_values": [
+                        "success",
+                        "failure"
+                    ]
+                },
+                {
+                    "data_path": "action_result.message",
+                    "data_type": "string"
+                },
+                {
+                    "data_path": "action_result.data.*.name",
+                    "data_type": "string",
+                    "example_values": [
+                        "John",
+                        "Jane",
+                        "Jim"
+                    ],
+                    "column_name": "Name",
+                    "column_order": 0
+                },
+                {
+                    "data_path": "action_result.data.*.age",
+                    "data_type": "numeric",
+                    "example_values": [
+                        25,
+                        30,
+                        35
+                    ],
+                    "column_name": "Age",
+                    "column_order": 1
+                },
+                {
+                    "data_path": "summary.total_objects",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                },
+                {
+                    "data_path": "summary.total_objects_successful",
+                    "data_type": "numeric",
+                    "example_values": [
+                        1
+                    ]
+                }
+            ],
+            "render": {
+                "type": "table"
+            }
+        },
         {
             "action": "reverse string",
             "identifier": "reverse_string",

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/tests/example_app/src/app.py

@@ -8,7 +8,7 @@ from soar_sdk.asset import AssetField, BaseAsset
 from soar_sdk.params import OnPollParams, MakeRequestParams, Params
 from soar_sdk.models.container import Container
 from soar_sdk.models.artifact import Artifact
-from soar_sdk.action_results import ActionOutput, MakeRequestOutput
+from soar_sdk.action_results import ActionOutput, MakeRequestOutput, OutputField
 from soar_sdk.logging import getLogger
 
 logger = getLogger()
@@ -53,6 +53,44 @@ def test_connectivity(soar: SOARClient, asset: Asset) -> None:
     logger.progress("this is a progress message")
 
 
+class ActionOutputSummary(ActionOutput):
+    is_success: bool
+
+
+@app.action()
+def test_summary_with_list_output(
+    params: Params, asset: Asset, soar: SOARClient
+) -> list[ActionOutput]:
+    soar.set_summary(ActionOutputSummary(is_success=True))
+    return [ActionOutput(), ActionOutput()]
+
+
+@app.action()
+def test_empty_list_output(
+    params: Params, asset: Asset, soar: SOARClient
+) -> list[ActionOutput]:
+    return []
+
+
+class JsonOutput(ActionOutput):
+    name: str = OutputField(
+        example_values=["John", "Jane", "Jim"], column_name="Name", column_order=0
+    )
+    age: int = OutputField(
+        example_values=[25, 30, 35], column_name="Age", column_order=1
+    )
+
+
+@app.action(render_as="json")
+def test_json_output(params: Params, asset: Asset, soar: SOARClient) -> JsonOutput:
+    return JsonOutput(name="John", age=25)
+
+
+@app.action(render_as="table")
+def test_table_output(params: Params, asset: Asset, soar: SOARClient) -> JsonOutput:
+    return JsonOutput(name="John", age=25)
+
+
 app.register_action(
     "actions.reverse_string:reverse_string",
     action_type="investigate",

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/tests/meta/test_actions.py

@@ -23,7 +23,8 @@ def test_action_meta_dict_with_view_handler():
 
     result = meta.dict()
 
-    assert result["render"]["view"] == "single_module.mock_view"
+    assert "render" in result
+    assert result["render"]["type"] == "custom"
     assert "view_handler" not in result
 
 
@@ -49,7 +50,7 @@ def test_action_meta_dict_with_view_handler_multi_part_module():
 
     result = meta.dict()
 
-    assert result["render"]["view"] == "src.app.mock_view"
+    assert result["render"]["type"] == "custom"
     assert "view_handler" not in result
 
 

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/tests/test_action_results.py

@@ -153,3 +153,28 @@ def test_action_output_to_dict():
         "optional_list_of_types": None,
     }
     assert action_output.dict(by_alias=True) == expected_dict
+
+
+def test_action_output_to_json_schema_with_column_name_and_column_order():
+    class ExampleActionOutputWithColumnNames(ActionOutput):
+        stringy_field: str = OutputField(column_name="Stringy Field", column_order=0)
+
+    schema = list(ExampleActionOutputWithColumnNames._to_json_schema())
+    assert schema == [
+        {
+            "data_path": "action_result.data.*.stringy_field",
+            "data_type": "string",
+            "column_name": "Stringy Field",
+            "column_order": 0,
+        }
+    ]
+
+
+def test_action_output_to_json_schema_with_column_name_and_column_order_missing():
+    class ExampleActionOutputWithColumnNames(ActionOutput):
+        stringy_field: str = OutputField(column_name="Stringy Field")
+
+    with pytest.raises(
+        ValueError, match="must have both 'column_name' and 'column_order'"
+    ):
+        list(ExampleActionOutputWithColumnNames._to_json_schema())

{splunk_soar_sdk-2.1.0 → splunk_soar_sdk-2.2.0}/tests/test_app_action.py

@@ -184,6 +184,49 @@ def test_action_decoration_with_meta(simple_app: App):
     assert simple_app.actions_manager.get_action("test_function_id") == foo
 
 
+def test_action_decoration_with_render_as(simple_app: App):
+    @simple_app.action(
+        name="Test Function", identifier="test_function_id", render_as="table"
+    )
+    def foo(params: Params) -> ActionOutput:
+        """
+        This action does nothing for now.
+        """
+        pass
+
+    assert sorted(foo.meta.dict().keys()) == sorted(
+        [
+            "action",
+            "identifier",
+            "description",
+            "verbose",
+            "type",
+            "parameters",
+            "read_only",
+            "output",
+            "versions",
+            "render",
+        ]
+    )
+
+    assert foo.meta.action == "Test Function"
+    assert foo.meta.description == "This action does nothing for now."
+    assert simple_app.actions_manager.get_action("test_function_id") == foo
+
+
+def test_action_with_bad_render_as(simple_app: App):
+    with pytest.raises(
+        ValueError,
+        match="Please only specify render_as as 'table' or 'json' or 'custom'.",
+    ):
+
+        @simple_app.action(
+            name="Test Function", identifier="test_function_id", render_as="bad"
+        )
+        def foo(params: Params) -> ActionOutput:
+            pass
+
+
 def test_action_decoration_uses_function_name_for_action_name(simple_app):
     @simple_app.action()
     def action_function(params: Params) -> ActionOutput:
@@ -506,3 +549,26 @@ def test_register_action_with_view_handler_module_not_in_sys_modules(simple_app:
             view_handler=fake_module_view_handler,
             view_template="sample_template.html",
         )
+
+
+def test_empty_list_output(simple_app: App, mocker: pytest_mock.MockerFixture):
+    @simple_app.action()
+    def action_example(params: Params, soar: SOARClient) -> list[ActionOutput]:
+        return []
+
+    add_result_mock = mocker.patch.object(simple_app.actions_manager, "add_result")
+    result = action_example(Params(), soar=simple_app.soar_client)
+    assert result is True
+    assert add_result_mock.call_count == 1
+
+
+def test_list_output_with_summary(simple_app: App, mocker: pytest_mock.MockerFixture):
+    @simple_app.action()
+    def action_example(params: Params, soar: SOARClient) -> list[ActionOutput]:
+        soar.set_summary(ActionOutput())
+        return [ActionOutput()]
+
+    set_summary_mock = mocker.patch.object(simple_app.soar_client, "set_summary")
+    result = action_example(Params(), soar=simple_app.soar_client)
+    assert result is True
+    assert set_summary_mock.call_count == 1