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 Bots editor, under Stages > User.

To create a User Stage

Go to Main menu > Bots.
The Botshomepage 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
Credentials

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 singles, and toggle off if you want the results to appear in multiples.

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. When a user stage is cloned, the user who performs the clone becomes the owner of the cloned stage. Any existing schedule configuration is preserved; however, the schedule trigger is disabled until it is reviewed and reactivated by the owner.

Delete: Select one or more user stages, select Actions > Delete. The Delete stages dialog displays. User stages can be deleted only by the owner or an administrator. Unassigned user stages can be deleted only by an administrator. 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.
Ownership: To assign or transfer ownership of a user stage, select the stage, then choose Actions > Ownership. The Ownership dialog is displayed. Enter the name of the user responsible for managing the stage. A stage without an assigned owner is displayed as Unassigned. An administrator can take ownership of an unassigned stage or assign it to another user, allowing them to manage the stage and its access settings.
Sharing: To configure sharing for a user stage, select the stage, then choose Actions > Sharing. The Sharing dialog is displayed. Choose an access level to specify who can view or edit the stage. Sharing determines the stage's visibility and the level of access granted to other users. You can make a user stage public, restrict access to specific users, or grant view or edit permissions as needed.

A stage can be:
- Public: The user stage is visible to all Neurons Platform users in your organization.
- Private: The user stage is visible only to the stage owner.
- Shared: The stage owner can share the user stage with selected users or groups.
Users can view and add only the User Stages that they have permission to access. User Stages that users cannot access are hidden from the stage selection pane and are unavailable for use in new bots.

If a bot contains a restricted User Stage, the stage remains visible, but its settings cannot be viewed. A warning message identifies who can grant access, and the bot cannot be validated or saved until the required permissions are granted. Users must obtain the necessary access before they can modify and save the bot.

User Stages

To create a User Stage

Actions

Related topics