Virtual Members (KPI Admin)

Overview

Virtual Members provide a powerful way to build advanced queries, measures, and KPIs. It allows you to produce dynamic members for a dimension based on a scripting language. It also would allow you to automatically generate matching KPIs for the conditions set for the Virtual Members.

This page aims to provide you with easy-to-follow steps when working with Virtual members based on common use cases outlined in this page. For any other use cases pertinent to Virtual Members, please reach out to the eMite Consulting Team or your eMite account executive for further guidance.

Scripting Guidelines

General rules to follow when creating Virtual Members:

• When creating the expression, you must type everything into a single line. Do not use Enter to create a new line.

• Field names must start with "@".

• There are some special characters in field names which must be replaced by keywords:

  • The space character (" ") must be replaced by the "_SPACE_" keyword. For example, a field called DATE OPEN is written as @DATE_SPACE_OPEN.

  • The dash character ("-") must be replaced by the "_DASH_" keyword. For example, a field called RefQuery-Price is written as @RefQuery_DASH_Price.

  • The dot character (".") must be replaced by the "_DOT_" keyword. For example, a field "Value.Keyword" is written as @Value_DOT_Keyword.

• Mind the parenthesis while creating complex expressions.

• There must be a space before and after the operator. For example, "if(@name1>0)" is an invalid expression. The format should be "if(@name1 > 0)".

You may also check out Elastic’s Painless Scripting Guide here.

Open

Creating a Virtual Member

1. Go to KPI Admin screen to access the Virtual Members configuration page. All Virtual Members previously saved will display on the screen.

2. Click the Add new record button.
   To edit an existing Virtual Member, click on its edit button.

Open

The Virtual Member Details will display.

Virtual Members Details Pop-up

The following screenshot is an example of a fully defined Virtual Member.

Common Use Cases

Grouping Queues

In this example, we will look at how Virtual Members can be used to group queues based on characters within the queue names.

1. Fill out the Name field with what you want the new Virtual Member to be displayed as. 

2. Select the appropriate index within which this should appear with the Cubes drop down. In this example, QueueHistory index is selected. 

3. Since we want this to be a new Dimension, leave the Dimensions box blank and tick Create a new dimension. 

For the purpose of this example, we are using the following expression:

This will check that the value of the QueueName field is not null, and check for any which start with the letters “SC”, as shown in the image below: 

4. Click Save. Once saved, this will create the new Virtual Member and also create the new Dimension.

5. Click the Count button to check the returned values. This will give you an indication of the number of times this string has been encountered. 

You can replace “SC” with the first few characters of your own naming conventions to suit your unique needs. 

Now you can create a standard cube report using this new dimension as shown below:

You can verify the data by linking the cube to the drillthrough datablock as shown below:

To group queue names which include specific characters:

This can be achieved by following the above steps and substituting the condition with the following: 

We have replaced value.StartsWith, with value.contains. 

In this example, we used the expression to ensure that the field is not null and to find all field content that contain the text “EMEA”. This text will be specific to your requirements.  

The value member will look like this: 

There are some syntax differences between a text type field and a keyword type field for Virtual Member.

For a text field using comma analyser in Elasticsearch, ie QueueName

1. Elasticsearch will store the field as array and sort the array items in alphabetical order.

2. doc['QueueName'].value will return the first item in the array. 

3. doc['QueueName'].values will return the whole array.

4. To do exact match with the array items, use doc['QueueName'].values.contains('searchterm') only when one of the array item equal to searchterm will match it.

5. To do wildcard match with the array items, first convert the array to string. Use doc['QueueName'].values.toString().contains('searchterm'). All the array items that contain searchterm will match it.

Reporting on Null Values

A common requirement is to select the data that is not there. Here is a brief example:

Using the logic above, we will be able to filter all rows where the “Organization” field contains a null value:

Aliasing DNIS/ANI

In this example, we will look at how Virtual Members can be used to alias DNIS/ANI based on characters within the DNIS/ANI.

Example 1

if(@Dnis != null && doc['Dnis'].value.contains('DNISorANI'))

else if((@Dnis != null && (doc['Dnis'].value.contains('DNISorANI') || doc['Dnis'].value.contains('DNISorANI') || doc['Dnis'].value.contains('DNISorANI') || doc['Dnis'].value.contains('DNISorANI'))))

else if(@Dnis != null && doc['Dnis'].value.contains('DNISorANI'))

Example 2

1. Fill out the Name field with what you want the new Virtual Member to be displayed as. 

2. Select the appropriate index within which this should appear with the Cubes drop down. In this example, QueueHistory index is selected. 

3. Since we want this to be a new dimension, leave the Dimensions box blank and tick Create a new dimension. 

For the purpose of this example, we are using the following expression:

This will check that the value of the QueueName field is not null, and check for any which start with the letters “SC”, as shown in the image below: 

4. Click Save. Once saved, this will create the new Virtual Member and also create the new Dimension.

5. Click the Count button to check the returned values. This will give you an indication of the number of times this string has been encountered. 

You can replace “SC” with the first few characters of your own naming conventions to suit your unique needs. 

Now you can create standard cube report using this new dimension as shown below:

You can verify the data by linking the cube to the drillthrough datablock as shown below:

To group queue names which include specific characters:

This can be achieved by following the above steps and substituting the condition with the following: 

We have replaced value.StartsWith, with value.contains. 

In this example, we used the expression to ensure that the field is not null and to find all field content that contain the text “EMEA”. This text will be specific to your requirements.

The value member will look like this: 

There are some syntax differences between a text type field and a keyword type field for Virtual Member.

For a text field using comma analyzer in Elasticsearch, ie QueueName

1. Elasticsearch will store the field as array, and sort the array items in alphabetical order.

2. doc['QueueName'].value will return the first item in the array. 

3.  doc['QueueName'].values will return the whole array.

4. To do exact match with the array items, use doc['QueueName'].values.contains('searchterm') only when one of the array item equal to searchterm will match it.

5. To do wildcard match with the array items, first convert the array to string. Use doc['QueueName'].values.toString().contains('searchterm'). All the array items that contain searchterm will match it.

Testing Virtual Members

When adding a new Virtual Member Definition, there are buttons on the bottom of the Virtual Members Details page.

Once you're done creating a new Virtual Member definition, you can test if the aggregation will work on an actual dashboard.

In this very example, the axis generated will be exclusively numeric (items in yellow in the last picture). That means that you can test all basic measures.
In contrast, if one or more axis (return column) have text in it, you can only use the count measure.

If the test is successful, a dialog box similar to the below is shown:

Otherwise, a popup with an error will be displayed.

Additional Reference Information

Virtual Members definitions are built on a language called Painless which is a built-in scripting language of Elasticsearch.

Most of the time, you'll be dealing with string comparisons to evaluate a condition, i.e. If (XXX is true), then it returns something 'YYY'.

XXX and YYY are usually string/text, so you can use the below references for any type of functions around string and text manipulation:

• Strings: https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-api-reference-string-sort-java-lang.html#painless-api-reference-string-sort-String

• Text: https://www.elastic.co/guide/en/elasticsearch/painless/master/painless-api-reference-shared-java-text.html

You may also check more Elastic’s Painless Scripting Guide here.