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:

1. 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.
   • Process custom variables will be sent with default robot logs (Process has started/ended) and any message written with the Log Message activity. If no variables are being populated, please ensure to write a log message activity.
2. 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.
3. Disabling custom variables can break the existing dashboards referencing the variables.
4. If you’ve already added the custom fields in the Add Queue Item activity, then you only have to designate a Transaction Item as either Successful or Failed, and you don't need to fill in the OutputData or AnalyticsData properties. If you didn’t specify the fields in the Add Queue Item activity, then they must be added in the Set Transaction Item activity when setting the status.

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:

1. 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.
2. Decide whether you want to configure custom variables for processes or queues by clicking the corresponding tab at the top of the configuration page.
   Note: Check the limits of the custom variables highlighted in the top right corner. If you are approaching the limit, consider making more custom variables as common so that they can be used across all processes or queues.
   
   

   

   
   
3. In the Extract column, choose the custom variables that you would like to use when building dashboards.
4. 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 235 processes or queues, and a maximum of 235 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.

5. 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 235 processes or queues, and a maximum of 235 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:

1. 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.
2. Decide whether you want to configure custom variables for processes or queues by clicking the corresponding tab at the top of the configuration page.
3. To remove variables that were previously selected, uncheck the Extract checkbox.
4. To remove Common status from a variable, uncheck the dedicated checkbox.
5. To change a variable’s type, select the new desired type from the dropdown.
6. Make sure to save the configuration.
7. 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;
   3. If the variable no longer has Common status, you need to replace the reference to the common variable with the updated per-process value.

Configuration example

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

In the following image, the ProcessCount variable is present in multiple processes while the Argument1_Email variable occurs only in one process.

Take the following steps to configure custom variables:

1. Select the ProcessCount variable for extraction, and choose the String type. Mark the variable as Common so that you get its value across all processes in which it appears.

2. Enable the Argument1_Email variable, and select the String type. Since this variable does not occur in multiple processes, you should not select Common. Click Save.

   
   

   

   
   
3. Navigate back to Dashboards, create a new dashboard, and add a new tile.

4. Choose the Robot Logs explore to see the already configured custom variables.

   Because you selected Common for ProcessCount, you can see that there is no process name prefix because it was added to the standard data model. Unlike ProcessCount, you did not select Common for Argument1_Email, so the custom field was added as Log_Email.Argument1_Email.

   
   

   

   
   

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.

The following example illustrates this particular case.

1. Go to Configure Custom Variables. You can see that the Argument1_Email custom variable field only occurs in the Log_Email process. Considering that Argument1_Email is a process-specific custom variable field, keep Common unselected.

   
   

   

   
   
2. Open a new or existing dashboard and add a tile.
3. Navigate to the Robot Logs explore. Select the Process Name field and the custom variable field. In this case, the custom variable field is Log_Email.Argument1_Email.

4. 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.

Troubleshooting and limitations

See our Troubleshooting section for information about troubleshooting and limitations.