Custom Variables

Insights always ingests data via the pre-defined fields available in the Insights data model, but Admins can also configure custom variables extracted from robot logs and queues to use for calculating specific KPIs or building more specialized dashboards.

Tip:

To include custom variables for processes, you must first make sure they are added to logs in your automation via the UiPath.System.Activities.AddLogFields activity in Studio, and then you must select them for ingestion.
To include custom variables for queues, you must first make sure they are added in workflows via an activity in Studio, and then select them for ingestion.
- Use the UiPath.System.Activities.AddQueueItem activity for Specific Data;
- Use the UiPath.System.Activities.SetTransactionStatus activity for Output Data and Analytics Data.
Disabling custom variables can break the existing dashboards referencing the variables.

Using Custom Variables in Organization-scoped Dashboards

When using custom variables in organization-scoped dashboards, consider the following:

Only custom variables extracted from the Configure Custom Variable window while in the Tenant view are displayed within organization-scoped custom variable configuration section. Any custom variables that aren't extracted from the tenant aren't displayed within organization-scoped dashboards.
When changing tenant-scoped custom variables, the organization-scoped custom variables are disabled from the organization. Make sure to re-enable them after all changes are done to be displayed within dashboards.
ROI and custom variables sections are read-only.

Configuring custom variables

To configure custom variables, an Admin must take the following steps:

Open the 3-dot menu in the top-right corner of any Insights page, and select Configure Custom Variables. The configuration page opens, listing all custom fields that are available for extraction.
Decide whether you want to configure custom variables for processes or queues by clicking the corresponding tab at the top of the configuration page.
In the Extract column, choose the custom variables that you would like to use when building dashboards.
In the Type column, select the custom variable type. You can choose String,Number, or DateTime.
Important:
- The fields are limited to 40 characters and any characters after this number will be cut. To add more than 40 characters, change the Insights.Etl.Json.MaxStringLen flag. You can add this flag in the Orchestrator web configuration and set the value according to your project's needs. For example:
<add key="Insights.Etl.Json.MaxStringLen" value="60" />
- The backfill percentage shows the progress of extracting a custom variable from all processes or queues. You will need to refresh the page to see the latest backfill percentage. This might take some time depending on the data size. Custom variable values will backfill from newest data to oldest. The field will be available for use shortly after the configuration is saved, you will not need to wait until it is 100% backfilled.
- You can extract variables from a maximum of 500 processes or queues, and a maximum of 200 variables per process or queue.
- If you configure the Type of a custom variable to Number make sure that it doesn't contain a , or other non-numeric characters such as $ as these characters are not supported. For numbers with special characters, please select type String.
- Every change in the configuration of custom variables will cause a full new backfill for that specific process. The time of the backfill depends on the number of logs stored in the Insights database for that specific process.

Save the configuration. All extracted variables for a specific Process should appear in an explore named *Process - ProcessName, and all extracted variables for a specific Queue should appear in an explore named *Queue- QueueName.

Important: You can extract variables from a maximum of 500 processes or queues, and a maximum of 200 variables per process or queue.

Number of Custom Variables Configured	Hardware Scale	Number of Processes	Number of Robot Logs per Process	Approximate Time for Extraction
30	Large Scale	1	1,000,000	5 minutes
30	Large scale	1	40,000,000	120 minutes

Editing an Existing Configuration

To edit an existing configuration, an Admin must take the following steps:

Open the 3-dot menu in the top-right corner of any Insights page, and select Configure Custom Variables. The configuration page opens, listing all custom fields that are available for extraction.
Decide whether you want to configure custom variables for processes or queues by clicking the corresponding tab at the top of the configuration page.
To remove variables that were previously selected, uncheck the Extract checkbox.
To change a variable’s type, select the new desired type from the dropdown.
Make sure to save the configuration.
Perform the following checks on existing dashboards that used a modified or removed variable:
1. If you deleted the variable, make sure to remove any references to the variable from formulas that were created or modified, from filters, or inside visualizations;
2. If you changed the variable type, ensure that the new type still applies correctly;

Configuration Example

This section provides an example of using a custom variable in a dashboard.

Take the following steps to configure custom variables:

Select the ProcessCount variable for extraction, and choose the String type.
Enable the Argument1_Email variable, and select the String type and then click Save.
Navigate back to Dashboards, create a new dashboard, and add a new tile.
Choose the *Process - CustomLogs2 explore and then choose the CustomLogs2 view to use the configured custom variables from this process in your tile.

Custom variables null cases

Custom variables can have a null value in some particular cases, as described in the following sections.

Scenario 1

If you use a field from the standard data model in a visualization paired with a process-specific custom variable field, and a process does not contain the custom variable in the robot logs, the value of all fields associated with the process that does not contain the custom variable in its robot logs is null.

There are two ways to eliminate the null values for this scenario:

Option 1: Add the custom variable as a filter, and set the condition to is not null to remove the null values from the visualization.
Option 2: Set a filter for the process name that does include the custom variable. Note, however, that if you adopt this approach, you may run into the second scenario below.

Scenario 2

If a custom variable is not present in all logs generated by a process, the logs that do not contain a value for that custom variable will show the variable's value as null as captured in the image below.

The following example illustrates this particular case.

Go to Configure Custom Variables. You can see that the Birthday2 custom variable field occurs in the CustomLogs2 process.
Open a new or existing dashboard and add a tile.
Navigate to the CustomLogs2 explore. Select the Process Name field from the Jobs view and the custom variable field. In this case, the custom variable field is CustomLogs2.Birthday2.
Click Run. The results you see should be similar to the ones shown in the following screenshot.

To eliminate the null values, add the custom variable field as a filter. Lastly, set the condition to is not null, so that you can remove the null values from the visualization.

Note: Both of these cases occur when you are viewing the custom field’s raw data. When you apply a function (Sum, Average, etc.) to the custom variables, you exclude null values.