User Stages

Create user stages to customize and save stages for use within bot creation. Once created the stages are available for reuse on the Neurons Bots editor, under Stages > User.

To create a User Stage

Go to Main menu > Neurons Bots.
The Neurons Bots homepage appears.
Select the General Bots or Survey Bots tab.
Select the Create bot or Create survey.
The Create bot or Create Survey page appears.
Select the bot trigger: Schedule or Custom action.
Select the target type: Devices or People.
Enter a Name for the bot. Optionally enter a brief description.
Click Create.
The Bots editor page appears.
The new bot is saved as an inactive draft version.
On the New bots editor page, select Manage user stages to display the User Stage Manager page.
On the User Stage Manager page, click the Create drop-down and select the desired stage from the following:
- PowerShell Query
- PowerShell Action
- Bash Action
- Command Action
- OSQuery
On the User Stage Editor page, enter the Stage name. For example, Compress File/Folder.
Optionally enter a description. The descriptive text displays when in the bot editor and Stage Information is selected from the Stage Settings panel. For example, This stage compresses source files from a specified path to a destination path to the specified compression level.
Enter the script code.
Example:
Compress-Archive -path C:\logs\file.txt
-destinationpath C:\logs\file.zip
-compressionlevel Optimal

You can make this script more flexible by replacing some of the hard code with variables. This would allow elements to be customized when using the stage.
Example:
Compress-Archive -path __Path to Source File or Folder__
-destinationpath __Destination Path__
-compressionlevel __Compression level|options:Fastest,Optimal,No Compression__

Select Ctrl + Space to insert an Options Variable or a Value Variable:

An Options Variable is displayed in the settings as a select drop-down, the options available will be the ones you enter into the script. In this example: Compression level options Fastest, Optimal, No Compression.

A Value Variable is displayed in the settings as a text box, with the label you enter in the script. In this example: Patch to Source File or Folder, Destination Path, and Compression level.

For this example the Stage Settings would look like this:

Complete the Stage Settings, the settings available depend on the type of user stage you are creating:

Powershell Query

Run As:

System
Logged-On User

Type:

PowerShell
Core
Auto

Output: Add an output for each column name returned by the PowerShell query that you want to use in a downstream filter results stage or as a variable in another stage.

Singular Result: Toggle on/off. Use single/multiple results to define whether the query will return single or multiple results per device. This determines whether variables are available as token inputs in downstream stages directly (single) or whether they are only available to stages in a for-each results block (multiple) to loop those stages for each result.

PowerShell Query example:

Use PowerShell to query your environment when the desired custom behaviors are not achievable using standard bot stages.

To run the query successfully, ensure that:

The script output is JSON (you can use the ConvertTo-JSON commandlet).
You can name each data field as an output entry in the Stage settings.

By default the script time out is 25 minutes.

PowerShell types:

If you select PowerShell type as Core, PowerShell script runs on the PowerShell Core .Net Core 3.1 Desktop Runtime, version 24.64.28315 or greater must be installed on the machine that you are running on.
If you select PowerShell type as Auto, the query searches for Net Core 3.1 Desktop Runtime, version 24.64.28315 or greater. The following are the outcomes:
- When the runtime is installed, the script will be executed against PowerShell Core.
- When the runtime is not installed, the script will be executed against PowerShell.

Output types:

Toggle on if you want the results to appear in multiples, and toggle off if you want the results to appear in singles.

Single - If the output type is specified as single, one object can be returned in JSON format.

$name = [System.Net.Dns]::GetHostName()

ConvertTo-Json @([customobject]@{Name = $name;})

Multiple - If the output type is specified as multiple, you must return the data as an array of objects in JSON format.
[{“Example Field”: “A”}, {“Example Field”: “B”}]
The objects within the array contains the primitive types. In the Output field of the Stage Inspector, you must bind the Example field and enter Name.
$processes = Get-Process | Select-Object Name
ConvertTo-Json $processes

Select Apply and Close to save the user stage.
If you have made edits to an existing user stage, a new version is created. On saving, a dialog displays to warn that any bots using the user stage will need updating to use the latest version.

Actions

You can perform the following actions to any of the user stages:

Clone: Select a user stage, select Actions > Clone. The Clone Stage dialog displays. Enter a unique name and select Clone. A pop-up message displays to inform you the stage creation was successful. The cloned stage appears in the list for you to select and edit.

Delete: Select one or more user stages, select Actions > Delete. The Delete stages dialog displays. Select Delete to confirm deletion of the stage. This action cannot be undone and will deprecate the stage from any bot that uses it. Deprecated stages are indicated by a red border.

User Stages

To create a User Stage

Actions

Related topics