Data Selector

This article applies to version 4.4.5 and later of P2 Explorer. For more, see Release History

Overview

The Data Selector is a property field used in many component editors, such as the data label and charts, that makes it easy to add data to a component in Explorer Studio. 

The Data Selector is available wherever you see a property field with the "Click to configure data..." placeholder text. 

  • To open the data selector, click the drop-down list containing the placeholder text. In the following example, the Data Selector is shown for the Value property of the Data Label.

The data selector expands to a larger panel below the property. The contents of this panel may vary, depending on the data category initially shown.

Data Categories

Depending on what a component is used for, there can be up to 5 separate Data Categories to choose from, when you select your data. If a category is not applicable to a component, it will not be available for selection.

The category initially selected in the Data Selector component will depend on the type of component. E.g. In the Data Label the Value category is selected by default, but in a Chart component the Dataset category is selected by default.

Click the links below to find out how to configure each category.

Dataset Tabular data returned from a dataset datasource.
Ad hoc Calculation A temporary calculation. An ad hoc calculation is specific to a component, and cannot be reused in other components.
Attribute An attribute associated with an entity, usually from an asset model.
Tag A tag from a tag datasource, or a calculation tag. 
Value A fixed or variable value, as defined in Studio.

Note: You can tab through the different data categories to configure each one. The one that is selected when you save the page remains the configured option. Any other configurations will be lost.

Data Types

Each data category shows a variety of data types, which determine what may be entered for a particular property. Each property will show 2 buttons: a fixed type (on the left) and a variable (on the right). 

One of these buttons will be selected by default, however you may change the selection if you wish.

Fixed Values

The following fixed values may be available. When you see these icons, the field must contain appropriate values. If using a variable instead, the variable type must be of the corresponding data type.

Icon Data Type Valid Values Example
Datetime A date/time value in UTC format. 
Number A valid numeric value. Can be integer or decimal. 
Text An alphanumeric text value. 
Text  This is a list of pre-defined values for the component property, and is used when a specific value is required. For example, Sample Method can only have the following valid options: Last Known Value, Average, Linear Interpolate, or Raw.
Text The name of a column from the dataset. The relevant columns are available in a drop-down list.
List A list of text values. 
Yes/No Select the check box to indicate Yes; clear the check box to indicate No. 
Calculation or CalculationList syntactically valid calculation expression (or list of expressions) that can be parsed by the Calculation Engine. If specifying the name of a saved calculation, it must be enclosed in curly brackets { }. You may find it easier to first open a calculation editor and then copy-paste the calculation.  
Tag A tag defined in P2 Server. 
TagList A list of tags defined in P2 Server. 
EntityList  A list of entities defined in P2 Server.
Entity or EntityList The name of an entity or entities defined in P2 Server. 
Template The name of a template defined in P2 Server. 
Attribute An attribute defined in P2 Server. 
AttributeValue An attribute value defined in P2 Server.

Variables 

  • To use a variable, click the variable  button, and then select a variable from the drop-down list. 
    Only variables of the correct type are available in the drop-down list. E.g. Where the property expects text, only text variables are available.
  • If the variable you want is not in the list, type in the variable name you want to use. 
    If you want to give the variable a default value, ensure its data type suits the property. E.g. If you configure a time field to use a variable, that variable should be assigned a Datetime data type. You can view or update the page default variables on the Default Values panel.

If the variable type is selected by default in the Data Selector, you will often find that the corresponding page default variable has already been assigned. You can see this in the following example, using an ad hoc calculation:

Related: VariablesDefault Values 


Adding Data

To add data using the Data Selector, first choose the data category, and then complete the relevant fields, as per the following sections.

Using Dataset Data

The Dataset category has 3 sections, plus a preview button. Below is an example of a configured dataset for a data label's Value property, which requires a single numeric value.

Dataset Query selector The dataset query used to source a list of data for this component’s property. Dataset queries are configured in P2 Server. If you know the name of the query, type it into this box and select it from the autocomplete drop-down list. Otherwise, click the Browse  button to select if from a dialog box.
Data Filters

Filters are only available for components that require a single list of data (such as the Data Label's Value property). These three columns are used collectively, to specify a single point of data from the result set. For more, see Filter Column and Filter Value.

  • Property components that require a single point of data (such as the Option Links's Option Values property) only use the Value Column.
  • Property components that require a full set of data (such as the Chart's Data property) do not use these three columns.
Dataset Parameters Dataset parameters are configured as part of the query in P2 Server. Not all queries have dataset parameters, and if they do these will vary depending on the query. If the dataset parameters have been configured with default values in P2 Server, you do not need to fill these in before previewing the data. Otherwise, they should be filled in before you will see any data. 
Preview button Click the Preview button to see what columns and values are returned by the query. This is helpful for setting up filtering and checking that you are getting data. If the preview window is blank, no data will be displayed in the component. If you expect to see data but none is shown, this could mean that your parameters are configured incorrectly. 

How to Select Dataset Data

This example uses a Data Label. Some of the components' properties (such as the Chart's Data) require fewer or no filter details.

Step 1. Click the drop-down list next to the Value property to open the Data Selector.

Step 2. In the Data Selector, click the Dataset Dataset icon category.

Step 3. Select the dataset query. In this example, we want the OilDowntimeByReason dataset from the Oil and Gas Data datasource. You can do this in 2 ways: type the name or browse.

  • Typing in a Dataset Query Name: If you know the name of the query, start typing part of the dataset query name into the edit box, and select the query from the list of matching options. 
     

      
  • Browsing for the query: If you don't know the name of the query, click the browse button next to the edit box.

     
    The Choose Data window opens, with the available dataset queries listed in the main panel. Use the search options to locate the one you want, or scroll through the list. If a dataset has a description, this is listed below the name.
     

    a. The panel on the left lists the available datasources. If you know the datasource of your query, click it to filter the datasets.
    b. To locate the dataset, scroll through the list or type part of the dataset query name into the Search box.
    c. When you have found your query, click on the query name, in the main panel.
    d. Click OK. The selected name appears in the Dataset Query edit box.

Step 4. Set the filters (where applicable).

Tip: If available, click the Preview button to see the available columns and values. Note that you will only see data if default values have been configured for the dataset parameters. Here is an example of a preview, showing the available fields:

Filter Column Select a column name from the dataset. In this example, we use the DowntimeReason column.
Filter Value Type in a value from the Filter Column. In this example, we use No Issues. This row is used to determine where the value comes from.
Value Column This column provides the actual value to be used in the component. In this example, we use the SumDowntimeHours column, as we want the data label to show the downtime hours.

The following image shows how setting the filters determines the value to be shown:

Read more:  Filter Column and Filter Value

Step 5. If there are Dataset Parameters, type a value in each one’s corresponding edit box. Note that if the dataset parameters have been assigned default values in the query, these will not be shown. 

Tip: Some parameters lend themselves well to using page default variables, such as startTime and endTime.

Step 6. Click Preview to view the results in the Dataset Preview window. The dataset preview shows the result set with the specified dataset parameters applied to the full dataset query. 

The Data Label's Value property is now configured, and the resulting data value is displayed in the Data Label component.

Watch the video below to see how a dataset query is selected for a Data Table component. Note: This video shows an older version of the Data Table.


Using Ad hoc Calculation Data

Ad hoc calculations are useful when testing ideas for a page or when you need a calculation for a specific, one-off purpose. Ad hoc calculations cannot be saved, reused in other components, commented on, or monitored by P2 Sentinel. If you require these functionalities, you should use the tag category to add a calculation tag created in P2 Server.

The Ad hoc Calculation category has 4 sections, plus a preview button. Below are 2 examples of configured ad hoc calculations: one that accepts a single calc and one that accepts a list of calcs.

Calculation:

Calculation List:

Calculation The calculation to be used to create the component's data. The calculation must be a syntactically valid calculation expression (or list of expressions) that can be parsed by the Calculation Engine. If specifying the name of a saved calculation, it must be enclosed in curly brackets { }. You may find it easier to first open a calculation editor and then copy-paste the calculation. For component properties where only a single point of data is used, you can only enter a single calculation, which will be for a single point in time.
Sampling options

These are used to define the method (e.g. Average) and the interval (e.g. 3600 seconds) that tag and attribute data within the specified ad hoc calculation is collected, for this component.

  • Sample Method: defines the way the data is processed (e.g. Average). This defaults to the pageSampleMethod variable, which by default is Average. The other available sample methods are: Last Known Value, Linear Interpolate, and Raw. 
  • Sample Interval defines the amount of time (in seconds) between each data point returned in the request interval. This defaults to the pageSampleInterval variable, which by default is 3600 (i.e. 60 minutes)The interval should be a multiple of 60.

Related: Data Transformation and Sample Methods

Request Interval

For a list of calculations: The Start Time and End Time specify the time range over which we want data (tags or attributes) that form part of the calculations.

  • Start Time defaults to the startTime variable, which by default is midnight of the current dayStart Time should be specified in UTC, or as another Datetime variable.
  • End Time defaults to the endTime variable, which by default is midnight of the next dayEnd Time should be specified in UTC, or as another Datetime variable.

For a single calculation:

  • Time indicates the point in time for which to return a value.
  • Item: The default of Value will use the values of any tags or attributes in the calculation. 
Entity Context

If you want to create an ad hoc templated calculation, specify the entity name to be used within the calculation. This option is used for Templated Calculations, when the calculation contains the Entity keyword.

Note that this templated ad hoc calculation is specific to the configured component only, and cannot be reused elsewhere within Explorer. If you want to reuse a templated calculation, this should be configured by an administrator as an attribute value on a template within P2 Server.

Preview button  Click the Preview button to see what columns and values are returned by the calculation. This is helpful for checking that you are getting data. If the preview window is blank, no data will be displayed in the component. If you expect to see data but none is shown, this could mean that your ad-hoc calculation is not valid.  

How to Select Ad hoc Calculation Data

This example uses a Chart component, which accepts a list of calculations.

Step 1. Click the drop-down list next to the Data property to open the Data Selector.

Step 2. In the Data Selector, click the Ad-hoc Calculation  category.

Step 3. Type in an ad hoc calculation and then click the Add  button to the right of the Calculations box. Continue to add new calculations in this way. All calculations must follow the appropriate syntax, in order for the Calculation Engine to parse it.

Examples of calculations:

100 A simple numerical value.
1+1 A simple mathematical formula, using mathematical operators such as multiply *, add +, subtract - and divide %.
{RandomCalc} A saved calculation in P2 Server. Calculation names must be enclosed in curly braces {}.
{Abes.ChokePos} A tag in P2 Server. Tag names must be enclosed in curly braces.
{Abes[Oil Producing Well]:
Status!Actual}

An attribute value from P2 Server. Attributes must be enclosed in curly braces {}. Correct syntax must be followed when specifying entities, templates, attributes, and attribute values. If these are time-aware, the value current for the retrieved data's timestamp will be used.

Note: If you choose not to specify a template, the primary template is used. For an attribute, if you choose not to specify an attribute value, the default is used.

Read more: Calculation Overview and Syntax

 

Step 4. Keep the defaults for Sample Method, Sample Interval, Start Time, and End Time

Step 5. Click Preview to see the calculation results in a table. The calculations are shown for each timestamp, and each calculation has a value, confidence, and error column. 

To use this data, we've configured a Line chart to use data from the ad hoc calculations as follows: the {RandomCalc}*2 column and the Max({RandomCalc}, 70) column for two series, and the Timestamp column as the X Axis Column.

In the screenshot below, you can see the two calculation values {RandomCalc}* 2 and Max({RandomCalc}, 70) plotted along the X Axis (Timestamp).

 


Using Attribute Data

The Attribute category has 4 sections, plus a preview button. Below are 2 examples of configured attributes: one that accepts attributes for a single entity and one that accepts attributes for a list of entities. The attribute name is made up of the following components: Entity, Template, Attribute, and Attribute Value. They are put together in this format: Entity[Template]:Attribute!Attribute Value

Related:  Asset Model

Entity:

List of Entities:

Entity entity defined in the data model, which should have the attributes defined below. For component properties where only a single point of data is used (such as the Data Label's Value), you can only enter a single Entity.
Attribute Value Definition

For each attribute value definition, you should define the Template, Attribute, and Attribute Value names.

  • Template: The entity's current primary template is used, unless you define another template.
  • Attribute: Any attribute that belongs to the specified template may be used.
  • Attribute Value: The attribute's current default attribute value is inserted. You can replace this with any other attribute value belonging to the attribute.

These will be paired with each entity listed. E.g. If you define 2 entities, (e.g. Pump1 and Pump2) and 2 attribute values (e.g. [Oil Producing Well]:Status!Actual and [Oil Producing Well]:Status!Planned), the attributes will be applied to each entity, like so:

  • Pump1[Oil Producing Well]:Status!Actual
  • Pump1[Oil Producing Well]:Status!Planned
  • Pump2[Oil Producing Well]:Status!Actual
  • Pump2[Oil Producing Well]:Status!Planned
Sampling Options

These are used to define the method (e.g. Average) and the interval (e.g. 3600 seconds) that attribute data is collected, for this component.

  • Sample Method: defines the way the data is processed (e.g. Average). This defaults to the pageSampleMethod variable, which by default is Average. The other available sample methods are: Last Known Value, Linear Interpolate, and Raw. 
  • Sample Interval defines the amount of time (in seconds) between each data point returned in the request interval. This defaults to the pageSampleInterval variable, which by default is 3600 (i.e. 60 minutes)The interval should be a multiple of 60.

Related: Data Transformation and Sample Methods

Request Interval

For a list of entities: The Start Time and End Time specify the time range over which we want attributes to be collected. 

  • Start Time defaults to the startTime variable, which by default is midnight of the current dayStart Time should be specified in UTC, or as another Datetime variable.
  • End Time defaults to the endTime variable, which by default is midnight of the next dayEnd Time should be specified in UTC, or as another Datetime variable.

For a single entity:

  • Time indicates the point in time for which to return a value.
  • Item: The following options should be available: Value, Name, Timestamp, Confidence.
    The default is Value, which returns the value of the attribute at the specified time. Confidence and Timestamp return a value from the Confidence and Timestamp properties (respectively) of the data point. Name returns the name of the entity/attribute.
Preview button Click the Preview button to see what columns and values are returned by the calculation. This is helpful for checking that you are getting data. If the preview window is blank, no data will be displayed in the component. If you expect to see data but none is shown, this could mean that your ad-hoc calculation is not valid.  

How to Select Attribute Data

This example uses a Line Chart component, which accepts a list of entities.

Step 1. Click the drop-down list next to the Data property to open the Data Selector.

Step 2. In the Data Selector, click the Attribute  category.

TOP TIP

Use the drag and drop method of adding attributes onto the component property. Note that this is only available on some of the components.

 
Step 3.
Add the entities. Start typing an entity name in the Entities box. As you type, a list of matching names appears. Click to select an entity from the list. Alternatively, type an entity name and then click the Add   button to the right of the Entities box. 
Continue to add new entities in this way.

Tip: You can search for an entity using the Wildcard characters ? and *. Read more about Searching with Wildcard Filtering.

Step 4. Click the Add  button to the right of the Attributes label, to add the attribute value definition.

  • Template: Type in the name of a Template. As you type, a list of matching names appears. Click to select a template from the list.
  • Attribute: Type in the name of an Attribute. As you type, a list of matching names appears. Click to select an attribute from the list.
  • Attribute Value: The current default attribute value appears in the box, or type a new Attribute Value into the box. As you type, a list of matching names appears. Click to select an attribute value from the list.

Step 5. Keep the defaults for Sample Method, Sample Interval, Start Time, and End Time

Step 6. Click Preview to see the data in a table. The attribute values are shown for each timestamp, and each attribute has a value, confidence, and error column. This is what the previewed data looks like, for this example.

To use this data, we've configured the chart to use the [Gas Producing Well]:THP!Actual column (just for entity Herbert) for a Line Series Y Column, and the Timestamp column as the X Axis Column.

In the screenshot below, you can see the values for the attribute (THP[Gas Producing Well]:THP!Actual) plotted along the X Axis (Timestamp).


Using Tag Data

A tag is a time series data item or a calculation saved in P2 Server. The Tag category has 3 sections, plus a preview button. Below are 2 examples of configured tags: one that accepts a single tag and one that accepts a list of tags. 

Tag:

List of Tags:

Tags A tag or calculation tag defined in P2 Server. For component properties where only a single point of data is used (such as the Data Label's Value), you can only enter a single tag.
Sampling Options

These are used to define the method (e.g. Average) and the interval (e.g. 3600 seconds) that tag data is collected, for this component.

  • Sample Method: defines the way the data is processed (e.g. Average). This defaults to the pageSampleMethod variable, which by default is Average. The other available sample methods are: Last Known Value, Linear Interpolate, and Raw. 
  • Sample Interval defines the amount of time (in seconds) between each data point returned in the request interval. This defaults to the pageSampleInterval variable, which by default is 3600 (i.e. 60 minutes)The interval should be a multiple of 60.

Related: Data Transformation and Sample Methods

Request Interval

For a list of tags: The Start Time and End Time specify the time range over which we want tags to be collected. 

  • Start Time defaults to the startTime variable, which by default is midnight of the current dayStart Time should be specified in UTC, or as another Datetime variable.
  • End Time defaults to the endTime variable, which by default is midnight of the next dayEnd Time should be specified in UTC, or as another Datetime variable.

For a single tag:

  • Time indicates the point in time for which to return a value.
  • Item: The following options should be available: Value, Name, Timestamp, Confidence.
    The default is Value, which returns the value of the tag at the specified time. Confidence and Timestamp return a value from the Confidence and Timestamp properties (respectively) of the data point. Name returns the name of the tag.
Preview button Click the Preview button to see what columns and values are returned by the tag. This is helpful for checking that you are getting data. If the preview window is blank, no data will be displayed in the component. If you expect to see data but none is shown, this could mean that your tag is not valid, or no data is being returned for the sample interval.

How to Select Tag Data

This example uses a Line Chart component, which accepts a list of tags.

Step 1. Click the drop-down list next to the Data property to open the Data Selector.

Step 2. In the Data Selector, click the Tag  category.

TOP TIP

Use the drag and drop method of adding attributes onto the component property. Note that this is only available on some of the components.

 
Step 3.
Select the tags. In the Tags box, start typing a tag name. As you type, a list of matching names appears. Click to select a tag from the list. Alternatively, type a tag name and then click the Add  button to the right of the Tags box. 
Continue to add new tags in this way.

Tip: You can search for an entity using the Wildcard characters ? and *. Read more about Searching with Wildcard Filtering.

Step 4. Keep the defaults for Sample Method, Sample Interval, Start Time, and End Time

Step 5. Click Preview to see the data in a table. The tag values are shown for each timestamp, and each attribute has a value, confidence, and error column. This is what the previewed data looks like, for this example.

The Chart's Data property is configured, and the resulting data is available for use in the chart component. In the screenshot below, you can see the value for the RandomCalc tag, plotted along the X Axis (using the Timestamp column).


Using Value Data

Here is an example of what a property’s value configuration looks like, where a list of data is required (such as the Option Values for an Option Links) component.

Single Value:

List of Values:

Values A value or set of values. These can be numerical or text. For component properties where only a single point of data is used (such as the Data Label's Value), you can only enter a single Value.

How to Select Value Data

This example uses an Option Links component, which accepts a list of values.

Step 1. Click the drop-down list next to the Option Values property to open the Data Selector.

The Data Selector editor opens, for the Option Values property.

Step 2. In the Data Selector, click the Value category.

Step 3. Add the values. In the Values box, type in a number or string, and then click the Add  button to the right of the Values box, or press the Enter key. Keep adding values in this way, until you have all the value options that you want to use.

The Option Links Option Values property is configured, and the resulting data is displayed in the Option Links component.

The video below shows how data is selected for a combo box. First we use a dataset column, and next we use values. Note that only the currently selected data category is saved when the page is saved.


Drag and Drop Tags or Attributes

Some of the components can have data dropped into their Data Selectors straight from the Hierarchy or Tag navigators. This method is an alternative to opening the Data Selector drop-down list, when assigning tags or attributes.

Watch the video below to see how to drag and drop data items into the Data Selector.

 


Release History

  • Data Selector 4.4.5 (this release)
    • The Ad Hoc Calculation editor has an additional option, for configuring an entity variable, called Entity Context.
  • Data Selector 4.4.2
  • Data Selector 4.4.1

Comments are closed