Working with DataExplorer rules

To create a new rule, start by creating a new workspace. The new workspace contains the Data item block. Use the toolbox to add other blocks to the workspace and connect the blocks to the Data item block to build the query expression for retrieving the data from your endpoints.

To create a new rule:

1. Open DataExplorer Builder.

2. Go to File, and then select New Workspace.

   A new workspace containing a Data item block opens.

3. In the Data item block, enter a unique name in untitled. When adding the rule to the Secure Endpoint Console, this is the name that is assigned to the data point. However, a friendlier display name can be configured.

   The name you enter must be unique.

   Optionally, you can set this field later.

4. Use the with type drop-down to select the type of data that the rule returns.

   Optionally, you can set this field later.

5. Add blocks from the toolbox to the workspace.
   1. In the toolbox, click the block category containing the block you want to add.
   2. Click a block or drag it to add it to the workspace.
6. Configure the blocks to build the logic.
7. Connect blocks to the Data item block or to other blocks by aligning the tab on an input block to the slot on the output block.
8. Evaluate and test the logic. Use the results to fine-tune the rule by adding, removing, and configuring blocks.
9. View the performance report. Use the results to troubleshoot rules that are expensive to evaluate.
10. Save the workspace.
11. Export the rule.

Once the rule is complete, and you have exported it, you can add the resulting file as a data point to the Custom Data policy in the Secure Endpoint Console.

Each workspace contains the logic to collect a single data point. For that reason, you are likely going to work on multiple workspaces. You can save each workspace as an XML file.

To save a workspace

1. Go to File, and select Save Workspace or Save Workspace As.
2. If this is the first time you've save the workspace or you used Save Workspace As:
   1. Navigate to the location where you want to save the workspace.
   2. Enter a name for the workspace and click Save.

The workspace is saved as a XML file. This file contains all of the blocks that are a part of the workspace, including blocks that are disconnected and comments that you have added to the blocks.

You can open a saved workspace to continue working on it. If you currently have a workspace open, make sure to save any changes before opening another workspace.

To open a saved workspace

1. Go to File, and select Open Workspace.
2. Navigate to the location of the saved workspace and click Open.
3. If the current workspace has unsaved changes, the Workspace Modified warning appears. Do one of the following:
   • Click Yes to open the workspace without saving the changes.
   • Click No to quit the operation. Save the current workspace and repeat step 1 and step 2.

The workspace file opens in the workspace.

DataExplorer Builder allows you to test the logic of the rule or of a group of blocks. Evaluate the logic as you build the rule to make sure each step in the logic works as expected.

To evaluate logic

1. Do one of the following:
   To evaluate a rule:

   1. Go to Rule, and select Evaluate or Evaluate to File.
   2. If you selected Evaluate to File:
      1. Navigate to the location you want to save the output.
      2. Enter a name for the file and click Save.
   To evaluate blocks:

   • Right-click the block where you want the evaluation to start, and then select Evaluate Here. The block can be connected to or disconnected from the Data item block.

     You can't start the evaluation from a custom block.

2. View the result in the Output tab.

3. [Optional] To view the output in a window, double-click the last item in the Output tab.

   The last message in the Output tab opens in the View Message window.

The rule returns a key/value pair for your device in the Output tab. If you selected Evaluate to File, the key/value pair is also saved in a JSON file in the location you configured.

The blocks return the resulting value of the underlying JSON logic. Unlike the result when you evaluate the rule, the result doesn't have to be JSON.

Results from evaluated rules are serialized to JSON before they are displayed in the output. Results are deserialized before the are displayed in the Secure Endpoint Console. For example, C:\User\tjordan\ would appear as C:\\User\\tjordan\\ in the output, but would display correctly in the console.

After you have evaluated a rule or a subset of a rule, you can view an overall performance report for each rule method evaluated. The results can be used to troubleshoot rule methods that are expensive to evaluate.

To view a performance report

1. Evaluate the rule or a subset of the rule.

2. Go to Rule, and the select View Performance Report.

The Performance Report opens and displays the overall performance for each rule method evaluated. The rule methods shown in the Performance Report are named according to the name in the underlying logic, which can differ from the block name used in DataExplorer Builder. To view the underlying logic, you can preview the rule output.

For more accurate timing results, repeat the process multiple times.

Requires DataExplorer Builder version 1.0.5 or higher

It's possible to view the underlying logic of a rule as you create it. In order to appear in the preview, blocks must be connected to the Data item block.

To preview the rule output:

• Go to Rule, and then select View.

The Rule View opens and displays the formatted JSON logic created to query endpoints.

When you have finished building the rule, you need to export it into JSON file so that it can be added to the Custom Data policy using the Secure Endpoint Console.

To export a rule:

1. Open the workspace you want to export.
2. Go to Rule, and select Export rule.
3. Navigate to the location you want to save the exported rule.
4. Enter a File name and click Save.

The file is saved in the selected location as a JSON file. The file consists of three elements: a field name, the data type, and the query used to collect the data from your endpoints. Each JSON file represents one data point that can be that can be added to the Custom Data policy.

The resulting JSON file doesn't contain the blocks, whether connected or disconnected, nor does it contain any comments you added to any block. Make sure you also save the workspace in order to retain these elements.

It is best practice to save the rule as a workspace in an XML file. This ensures that any comments and any disconnected blocks remain a part of the file. However, if you only have the JSON file that was exported from DataExplorer Builder, you can use import to recreate the workspace in DataExplorer Builder.

To import a rule:

1. Go Rule, and select Import rule.
2. Navigate to the location where the JSON file is saved.
3. Select the rule, and then click Open.

A workspace is created from the imported file.

The resulting workspace may use different blocks than were originally used to create it. The result of evaluating the rule is the same.