Using the Script Native Action

overview the script native action executes python code within a sandboxed environment it provides access to standard python libraries and pre configured global variables for accessing inputs, setting outputs, and handling errors scripts run in isolated containers to ensure security and resource management key benefits of the script action flexibility with python leverage python 3 to manipulate data and handle edge cases efficiency reduces complexity compared to jsonata for simpler tasks preloaded libraries access standard python libraries including json , datetime , math , csv , base64 , hashlib , itertools , statistics , and more sandboxed execution scripts run in isolated containers for security and resource management global variables pre configured variables ( action inputs , action outputs , action error ) simplify script development attachment support built in support for handling file attachments as inputs and outputs available global variables the script native action provides three global variables action inputs a dictionary containing all input values passed to the script access inputs using action inputs\["propertyname"] or action inputs get("propertyname") action outputs a dictionary used to set output values assign values using action outputs\["outputname"] = value action error a dictionary that, when populated, will fail the action with the corresponding error payload set error information using action error\["message"] = "error description" example setting up the script native action here’s how to configure a script action in your playbook from the add panel, drag and drop the script action onto the playbook canvas click configure , then add property to define input data types (string, number, boolean, object, array, or attachment) write your python script in the provided field or select upstream playbook inputs using the property drawer script inputs define static and dynamic inputs using the following supported types string text values number numeric values (integers or floats) boolean true/false values object json objects/dictionaries array json arrays/lists attachment file attachments configuring script inputs follow these steps to set up your inputs click add property in the inputs pane to define your inputs rename properties as needed using the pencil icon set input values by entering static values directly selecting properties from upstream actions using the property drawer using expressions to reference playbook data write or paste your python code in the script pane access inputs in your script using action inputs\["propertyname"] example in this example, a script evaluates a last malicious score to determine if it meets the malicious score threshold outputs tab the outputs tab enables promotion of action outputs for downstream use view outputs see all outputs provided by the script action promote outputs select outputs to make them available to downstream actions in the playbook mark sensitive click the ellipsis button (⋯) next to an output and select mark sensitive to mark sensitive data delete outputs remove outputs that are not needed note outputs are set in your python script using action outputs\["outputname"] = value the outputs tab allows you to manage which outputs are promoted and marked as sensitive script testing want to test your script action before continuing to build your playbook? in the script action, from the test tab view inputs see all configured inputs on the left side of the test panel view script see your python code on the right side of the test panel modify test inputs change input values to test different scenarios run test execute the script with the test inputs view results see the output in the results pane at the bottom important notes attachment limitations attachment fields are not shown in the test tab inputs attachments cannot be used in test runs of the action you must perform a full playbook test to test attachment inputs discovered outputs just like discovered outputs in an http action, results vary in addition to the base property types, depending on the inputs you select, the action outputs may return additional properties these are the discovered outputs, which you can promote and/or delete from the outputs tab error handling if your script encounters an error during testing, error details will be displayed in the results pane see a script test use case for an example on testing the script native action handling attachments in scripts if you need to return an attachment or use an attachment as an input in the script native action, follow the instructions below output attachment in your playbook, follow the instructions below to configure an output attachment input attachment you can use an attachment input in a python script using a script native action testing the script test your script in the test tab before full integration the results appear in the results pane this is useful for debugging and validating output see the script test use case for detailed examples use cases for more examples and detailed use cases, see the script test use case available python libraries the script native action provides access to standard python libraries some commonly used libraries include json json encoding and decoding datetime date and time manipulation math mathematical functions csv csv file processing base64 base64 encoding/decoding hashlib hash algorithms (md5, sha256, etc ) itertools iterator functions statistics statistical functions string string utilities time time related functions decimal decimal arithmetic fractions rational numbers ipaddress ip address manipulation html html utilities email email parsing zlib compression note custom package imports are not allowed only preloaded standard python libraries are available error handling you can handle errors in your script using the action error global variable when action error is populated, the action will fail with the error message you provide troubleshooting script fails with import error custom package imports are not allowed use only standard python libraries that are preloaded input not found use action inputs get("propertyname", default value) to provide default values for optional inputs, or check if keys exist before accessing them output not appearing ensure you're setting outputs using action outputs\["outputname"] = value outputs must be set before the script completes attachment not working attachments cannot be tested in the test tab use a full playbook test to verify attachment handling boolean/null values for boolean and null data types, use json loads() to ensure proper data loading type errors ensure you're using the correct data types use type conversion functions ( int() , str() , float() , bool() ) when needed best practices start simple begin with straightforward scripts before moving to more complex logic use comments comment your code for clarity and easier debugging the script editor includes helpful comments about available global variables test frequently use the test tab to validate your script iteratively with different input values handle errors gracefully use try except blocks to catch and handle errors use action error to provide meaningful error messages validate inputs before processing them validate inputs check that required inputs exist and have valid values before using them use default values use get() method with default values for optional inputs keep scripts focused write scripts that do one thing well break complex logic into multiple script actions if needed document your scripts add comments explaining what the script does, especially for complex logic or business rules