Attaching dashboards to correlator data

Dashboard data tables

To create dashboards, you should have an understanding of how Apama manages correlator data and makes it available for attachment to the object properties.

Apama makes DataView data available to dashboards as tabular data. Multiple data tables may be necessary for a dashboard. Any data table may have multiple objects in the dashboard attached to it. The relationship between dashboard objects and data tables is illustrated in the following diagram.

When a DataView field changes, the correlator generates an update event with details of the change. When this event is received by a dashboard, the dashboard updates one or more data tables and the changes are reflected in all attached objects.

Different data tables are used for each DataView. Data tables are not created until the first attachment requiring the data table is made. In the Dashboard Builder this happens when the attachment is defined. For a deployed dashboard, this happens when the dashboard is launched or loaded.

Once created, a data table exists for the life of the Builder process or deployed-dashboard session, although it may be purged of data if the corresponding DataView definition is deleted from the correlator or if the DataView item is deleted.

Apama filters the DataView items a user can see. Only those instances that the user is authorized for will be added to the user’s data tables. By default, these are the DataView instances created with the same “owner” as the current user. See Administering Dashboard Security for more information on dashboard authorization.

Query instance table

A query instance table contains values of all input parameters for instances of an Apama query. The columns of this table correspond to the input parameters of the query. Several additional columns are added to each row of the table to facilitate dashboard specific table filtering.

Correlator status table

A single correlator status table contains status information about each correlator being used by a dashboard. It is useful when you want to display status information about correlator connections in a dashboard.

The following table illustrates the contents of the correlator status table.

Here two correlators are in use and each is connected.

Data server status table

A single data server status table contains status information for the data server being used by a dashboard. It is useful when you want to display status information about the data server connection in a dashboard.

The table below illustrates the contents of the data server status table.

(This type of table differs from the others in that it cannot be attached to a property with the Attach to Apama dialog—see Creating a data attachment. To attach a property to a data server status table, attach the property to function data—see Using dashboard functions—and specify a function of type Get data server Connection Status.)

DataView item table

A DataView item data table contains the current values of all fields for all items of a single DataView definition. A separate item table exists for each DataView definition. Within a DataView item table, a row exists for each item associated with a specified DataView definition. The columns of the table correspond to the fields of the DataView.

DataView trend table

A DataView trend data table contains the values of the fields of a single DataView item. A separate data table is used for each item associated with a DataView definition. Each row in the table contains the value of the fields as reported in a DataView-item update event. Each row also contains a timestamp indicating when the update occurred.

DataView OHLC table

A DataView OHLC table is contains Open, High, Low, and Close values for a DataView item field as calculated for a specified time interval. As a dashboard or dashboard server receives update events for a DataView item it will calculate the Open, High, Low, and Close values for the field and add a row to an OHLC table at each time interval. The calculated values added will be for the preceding time interval.

OHLC tables allow dashboards to automatically create data suitable for display in a Candlestick or OHLC chart for any DataView-item field and time interval. When you create an attachment to an OHLC table you specify the field and time interval desired. An example would be selecting a Price field and a time interval of 5 seconds.

A separate OHLC table is used for each DataView item and each field and interval pair. If for the Price field you wanted OHLC data at both 5 and 30 second intervals; two OHLC tables would be created for each DataView item.

SQL-based instance table

An SQL-based data table is a special data table designed to ease implementation of complex filtering and improve performance for dashboards that must handle a large number of DataView items. It contains the current values of all fields for all items of a single DataView definition.

A separate table exists for each DataView definition. Within a table, a row exists for each item of the DataView definition. The columns of the table correspond to the fields of the DataView.

See Using SQL-based instance tables for more information on using SQL-based instance tables.

When you specify a data attachment, this kind of table is available only if you started Builder with the -Y or --enhancedQuery command-line option.

Important:

When SQL-based data tables are in use for deployed dashboards, authorization for DataView items does not use scenario authorities (see Administering Dashboard Security). By default, all users have access to all instances or items. Authorization must be built into attachment queries. See Using SQL-based instance tables for more information.

Definition Extra Params table

A definition extra params table contains the metadata for the extraParams member of the selected Definition (DataView). The table has two static columns: key and value. An entry in extraParams is considered a metadata entry if its key name starts with the Metadata: prefix. Each metadata entry in the extraParams member will appear as a row in this table.

For example, a DataView definition may have extraParam like this:

com.apama.dataview.DataViewAddDefinition
  add := new com.apama.dataview.DataViewAddDefinition;
add.dvName := "RecipeDV";
add.dvDisplayName := "Recipe";
add.fieldNames := ["name","ingredients","category","difficulty"];
add.fieldTypes := ["string","string","string","integer"];
add.keyFields  := ["name"];
add.extraParams := {
			"Metadata:author":"John Doe",
			"Metadata:copyrightDate":"October 15, 2015",
			"Metadata:contact":"jdoe@kitchen.com",
			"phone":"234-123-9988",
			"age":"30"};

In the above example, only the first 3 extraParams entries are metadata entries. Therefore, the Definition extra params table will show:

Setting data options

Dashboard Builder provides several options for managing the data stored in data tables.

To set data options

1. Select Options item in the Tools menu.

   The Application Options dialog appears.

2. Select the Apama tab and the Data sub tab to see the data options.

3. Check the Purge instance on edit check box to purge all trend and OHLC data for a DataView item whenever an input variable or field is modified. When an input variable of a field of a DataView item is modified, it may invalidate all previous trend and OHLC data.

4. Check the Purge instance data on remove to purge all data for a DataView when it is removed from a correlator.

5. Check the Maximum decimal precision and specify a maximum number of decimal places to be displayed for any numeric data in a dashboard.

6. Check the Maximum rows per trend table to set the maximum number of rows for each trend and OHLC table. The higher the value, the more data that will be available for charting and the greater the memory utilization.

Scenario instance ownership

Scenario instances in a correlator include an attribute identifying the owner of the instance. When an instance is created through a dashboard, the current user ID is specified as the owner of the instance. For DataViews, the owner is provided by the EPL that sends the DataViewAddItem event.

By default, you are only allowed to see and operate on those scenario instances that you own, that is, the current user ID must match the apama.owner attribute of the instance or item. There are two exceptions to this default:

• If the owner is specified as “*”, all users have access by default.
• SQL query attachments provide access for all users to all instances and items. For more information about SQL query attachments, see Using SQL-based instance tables.

Creating a data attachment

Attachments can be used to provide data for a chart or table. They can also be used to set other properties of objects such as labels, colors, and thresholds. Any non-static object property can be attached to Apama data.

The value of a property, for a given visualization object, can be a single numeric or string value, a sequence of values, or a table of values. The value of an object property can specify a set of characteristics of the object, such as the following:

• Numerical contents of all the cells in a table
• Height and label of all the bars in a bar graph
• X coordinate and Y coordinate of all the plotted points in an XY Graph

For example, the value of the valueTable property for a basic bar graph is a table that has one row for each bar in the graph. The first column in each row provides the label for the corresponding bar, and the second column in the row provides the height of the corresponding bar.

Using the Attach to Apama dialog

To attach an object property to Apama data

1. Right-click the property in the property panel.

   A popup menu appears.

2. In the displayed popup menu pick Attach to Data > Apama.

   This displays the Attach to Apama dialog.

   This dialog allows you to specify the portion of a data table that is to be used as the object property’s value. This portion is itself a table consisting of some or all of the rows and columns of the original data table. The dialog, in effect, allows you to specify a query against a specified data table. At any given time, the result of this query serves as the value of the object property being attached.

3. In the Attach to field select the type of Apama data table needed:

   • DataView

   • DataView trend table

   • DataView OHLC table

   • DataView constraint table

   • Query instance table

     Info

     Apama queries are deprecated and will be removed in a future release.

   • Correlator status table

   • Definition Extra Params table To attach a property to an SQL-based data table, see Using SQL-based instance tables.

   To attach a property to a data server status table, attach the property to function data—see Using dashboard functions—and specify a function of type Get Data Server Connection Status.

4. In the For field, if the Attach to field specifies a DataView trend or OHLC table, select History and new events, New events only, or History only. This specifies whether to attach new or historical data to this property.

5. In the Correlator field enter the correlator where the DataView is loaded. This field is disabled if the Attach to field specifies a correlator status table.

6. In the DataView field, enter the DataView definition to attach to. This field is disabled if the Attach to field specifies a correlator status table.

7. In the Timestamp variable field, for trend table and OHLC table attachments, identify a DataView field, or apama.timestamp to use as the timestamp for rows in the data table.

8. In the Display variables field enter the data table columns (which are DataView fields) to include in the portion of the table to be used as object property value.

9. Check the Filter check box to enable the filter fields (listed below). Filters allow you to specify the data table rows to include in the value of the attached property. You do this by specifying a condition that must be satisfied by a data table row in order for it to be included. The condition specifies a data table column, a value, and a comparison relation (for example, equals, less than, or member of). The condition is satisfied by a given row if and only if the value of the specified column for the row bears the specified relation to the specified value. Enter the filter field values:

   1. By variable — Specifies the data table column (which is a DataView field) to filter against.

   2. Comparison operator field — Specifies one of the following comparisons. To compare numeric or text values, use equals, not equals, greater than, greater than or equals, less than, or less than or equals. Use member of to compare a column value with a list of numeric or text values. Use starts with, ends with, or contains to compare text values only.

   3. Value — Specifies the value to compare with values of the specified column. For Member of comparisons, specify a single value or a semi-colon-separated list of values. Do not use spaces. A single value is considered to be a list with a single member. Escape quotes in values (that use \' instead of ').

      See Filtering data for more information.

10. Using time interval — For OHLC table attachments specifies the time interval to be used in calculating OHLC values.

11. Data Server — For advanced users, specifies the logical name of the data server that you want to serve the data associated with this attachment. You define data server logical names with the Application Options dialog (select Tools Options ). See Working with multiple data servers for more information.

    In this documentation, some of the Attach to Apama dialogs are shown without the Data Server field, which has been added in a later release.

Selecting display variables or fields

Individual display variables or fields can be selected directly in the Attach to Apama dialog.

To select multiple display variables or fields

1. Click “…” next to the Display variables field.

   This displays the Select Columns dialog.

2. Select and order multiple display variables or fields using the buttons provided.

Displaying attached data

To view the data that is currently attached to a given property

1. Right-click the property name.

   A popup menu appears.

2. Select Display Data from the popup menu.

   A dialog appears that contains a table and the following checkboxes:

   • Show Column Types: Provides the option of displaying data-table column types.
   • Insert New Rows: Controls whether new data is added to the table as new rows instead of replacing the old rows.
   • Scroll Columns: Controls whether a scrollbar is provided when needed to prevent truncation of column contents.

Filtering data

The Attach to Apama dialog allows you to define a filter, which specifies a condition on rows of a data table. Only rows that satisfy the condition are included in the table that serves as the value of the attached property. See Using the Attach to Apama dialog for details on specifying filter conditions.

Filters are used frequently in dashboards. Most frequently they are used to select a single DataView item for which dashboard objects are to display

Attaching to constraint data

When you attach a property to data from a constraint table, you use the Attach to Apama dialog to specify a single cell of the constraint table (the dialog requires you to specify a single column for Display Variables and to filter on the value of the Parameter column). The contents of this cell is used as the property’s value. Use this kind of attachment to set constraints on controls, such as the maximum value on a slider.

About timestamps

When creating a stock or trend chart data attachment, you must identify the variable or field to use as the timestamp. You can use either a DataView field or apama.timestamp. When a variable or field changes, the correlator generates an Update event with the new value. The timestamp in the Update event will be used by the dashboard as the time that the change occurred and used to chart the value.

The default timestamp is apama.timestamp. It corresponds to the timestamp the correlator adds to an Update event when the event is generated. This timestamp is suitable in most cases and is always available.

If you want greater control over the value of timestamps, specify a DataView field as the timestamp. Within your DataView, you will need to set the value of the timestamp variable or field when changing the value of any other variable or field. Do this if you want use timestamps from an external event feed such as market data.

Only number variables can be used as timestamps. Timestamps need to be in UTC format where the value represents the number of seconds since the epoch, January 1, 1970. The TimeFormatPlugin can be used to convert string values to UTC format.

Using dashboard variables in attachments

The value of all fields in the Attach to Apama dialog, other than Attach to and For, can be set to dashboard substitution variables. This allows you to dynamically configure an attachment when a dashboard is displayed. For example you could set the Display variables field to the substitution variable $displayVariables (where $displayVariables value equals a semicolon separated list of DataView fields).

To create a substitution variable

1. Select Tools | Variables to display the Variables panel (if the panel is not showing).

2. In the Name field enter a name that starts with “$”. Names of substitution variables start with “$” by convention. Names of variables that are not substitution variables (see below) do not start with “$”.

3. In the Initial Value, optionally supply an initial value.

4. Check the Use as substitution checkbox.

5. In the Data Type field, ensure that this set to Scalar, the default.

The Initial Value field allows static specification of substitution values at development time. You can also allow dashboard users to set the value of a given substitution at runtime by attaching the varToSet property of a control object (such as a text field) to the given substitution.

Dashboard Builder provides a number of predefined substitutions—see About drilldown and $instanceId.

Dashboard variables in attachments only take effect when the dashboard is displayed. Subsequent changes to the variable will not change the attachment unless the dashboard is redisplayed.

About non-substitution variables

In addition to using dashboard variables as field values in the Attach to Apama dialog, you can specify a dashboard variable as the value of an object property. If you use a variable in this way, you can increase dashboard efficiency by clearing the selection Use as substitution field for the variable in the Variables panel, provided you do not use the variable in any of the following:

• Attach to Apama field
• Define Apama Command field (see Defining commands)
• -S command-line option

Substitution variables must have a scalar value, but non-substitution variables can have tabular values if you set the Data Type to Table.

Uncheck the Public checkbox only if you do not want to expose the variable as a property in a Composite object — see Using Composite objects.

About drilldown and $instanceId

When you create a dashboard with Dashboard Builder, you will frequently need to pass context information that identifies a DataView item to display or operate on. Consider, for example, a dashboard with a table containing one row for each instance of a given instance. In order to display detailed information about an instance when the end user selects its corresponding row in the table, you need to pass the identity of the selected instance to the visualization objects that will display the details.

You can pass such information from one object to another by doing both the following:

• Specify that a substitution variable be set to a specified value in response to a specified end-user action on one object.
• Use that substitution variable in the data attachment for the other object.

In many cases you can simplify this procedure by using the predefined substitution variable $instanceId. This variable is automatically set to the value of apama.instanceId for the table row that is currently selected. If multiple rows are selected, $instanceId is set to multiple values.

For more information and examples, see Performing drilldowns on tables and Specifying drill-down column substitutions.

You will find yourself using $instanceId frequently in attachment filters and instance operations. You will see many uses of $instanceId in subsequent sections of this guide.

About other predefined substitution variables

In addition to $instanceId (see About drilldown and $instanceId), Dashboard Builder defines the following substitution variables:

• $apama_lang: by default, this variable is set to what Java reports as the locale in the Locale object as derived from the host system’s locale. You can allow end users to set this to their required locale, and use it to localize dashboard labels. See Localizing dashboard labels.
• $apama_roles: Principles: returned by the login module.
• $apama_server_host: hostname of the machine running the data server or display server; empty for Builder and Viewer with a direct connection to a Correlator.
• $apama_server_port: port used by the data server or display server on the host machine; empty for Builder and Viewer with a direct connection to a correlator.
• $apama_timestamp: by default, this variable is set to the value of apama.timestamp of the instance that is currently selected. See About timestamps.
• $apama_user: current user, set at login.
• $celldata: by default, this variable is set to the value of the cell that is currently selected.
• $colName: by default, this variable is set to the name of the column of the currently-selected cell.

Using SQL-based instance tables

SQL-based instance tables support the use of an SQL query for the specification of a data attachment. (See SQL-based instance table:

• Filtering is optimizable. You can specify indexes which Apama can use to join data tables and filter data attachments more efficiently. This can dramatically improve performance, particularly for large data tables (that is, tables with thousands of rows or more).
• A single attachment specification can refer to multiple tables, including tables from multiple correlators. This can simplify implementation, which would otherwise require attaching properties to dashboard functions whose arguments are attached to data tables.
• Arbitrarily complex filtering and data aggregation is supported, since any read-only SQL select statement can be used. This can simplify implementation, which would otherwise require complex chains of dashboard functions.

Important:

When SQL-based data tables are in use for deployed dashboards, authorization for DataView items does not use scenario authorities (see Administering authentication). By default, all users have access to all instances or items. Authorization must be built into attachment queries.

To attach an object property to Apama data by using an SQL-based instance table

1. Ensure that Builder has been started with the -Y or –enhancedQuery command-line option.

2. Right-click the property in the property panel.

   A popup menu appears.

3. In the displayed popup menu pick Attach to Data > Apama.

   The Attach to Apama dialog appears.

4. In the Attach to field select Instance table query.

   This changes the Attach to Apama dialog, so that there is a single remaining field, SQL Statement.

5. Enter an SQL query into the text box.

   Any read-only select statement is allowed, with the following restrictions and modifications:

   • You must designate tables with table names of the form correlator-name.DataView-ID.
   • You can designate values with predefined or user-defined dashboard substitution variables (for example, $apama_user or $instanceId).
   • You must enclose table names and column names in quotes.
   • You must enclose strings in single quotes. As you construct your query, you can right-click to get suggestions for table names, column names, or substitution variables.

Following is an example of a query that you can use to specify a data attachment. It specifies a three-way join, that is, a join involving three different data tables:

SELECT "prod_name", "vend_name", "prod_price", "quantity"
  FROM "Correlator2.DV_OrderItems_Table", "Correlator1.DV_Products_Table",
    "Correlator1.Scenario_Vendors_Table"
  WHERE "Correlator1.DV_Products_Table"."vend_id" =
      "Correlator1.Scenario_Vendors_Table"."vend_id"
    AND "Correlator2.DV_OrderItems_Table"."prod_id" =
      "Correlator1.DV_Products_Table"."prod_id"
    AND "Correlator2.DV_OrderItems_Table"."order_num" = 20007

Below is a query that filters out instances that are not owned by the current dashboard user. The example assumes that there is a DataView field, owner, whose value is the instance owner.

SELECT "prod_id", "prod_price"
  FROM "Correlator1.Scenario_Vendors_Table"
  WHERE "Correlator1.Scenario_Vendors_Table"."owner" = '$apama_user'

To specify indexes into an SQL-based data table, use the --queryIndex option on the command line when you do any of the following:

• Start the data server or display server
• Start the Dashboard Builder with a direct connection to the correlator
• Start the Dashboard Viewer with a direct connection to the correlator

This option has the form

--queryIndex table-name:key-list

table-name is the name of a DataView. key-list is a comma-separated list of variable names or field names. Here is an example:

--queryIndex DV_Products_Table:prod_id,vend_id

You can only add one index per table, but you can specify this option multiple times in a single command line in order to index multiple tables. Deployed dashboards that use SQL-based instance tables must be connected to a data server or display server that is started with the -Y or --enhancedQuery command-line option. For deployed dashboards that use Viewer connected directly to a correlator, Viewer must be started with the -Y or --enhancedQuery command-line option.

Working with multiple data servers

Deployed dashboards have a unique associated default data server or display server. For web-based deployments, this default is specified with the following properties of the dashboard_deploy.xml configuration file (see Generating a deployment package from the command line ).

• apama.displayserver.port
• apama.displayserver.host
• apama.displayserver.refresh
• apama.displayserver.hiddenmenuitems

For Viewer deployments, it is specified upon Viewer startup. By default, the data-handling involved in attachments and commands is handled by the default server, but advanced users can associate non-default data servers with specific attachments and commands. This provides additional scalability by allowing loads to be distributed among multiple servers. This is particularly useful for display server deployments. By deploying one or more data servers behind a display server, the labor of display building can be separated from the labor of data handling. The display server can be dedicated to building displays, while the overhead of data handling is offloaded to data servers.

Apama supports the following multiserver configurations:

• Builder with multiple data servers. See Builder with multiple data servers.
• Viewer with multiple data servers. See Viewer with multiple data servers.
• Display server (thin client) deployment with multiple data servers. See Display server deployments with multiple data servers.

The Attach to Apama and Define… Command dialogs (except Define System Command) include a Data server field that can be set to a data server’s logical name. To associate a logical name with the data server at a given host and port, use the Data server tab in the General tab group of the Application Options dialog (select Tools Options in Builder).

For display server (thin client) deployments, you must use the option --namedServerMode whenever you start named data servers. See Display server deployments with multiple data servers.

The logical data server names specified in the Builder’s Application Options dialog are recorded in the file OPTIONS.ini, and the deployment wizard incorporates this information into deployments. You can override these logical name definitions with the --namedServername:host:port option to the Builder, Viewer, data server or display server executable. Below is an example. This is a sequence of command-line options which should appear on a single line as part of the command to start the executable:

--namedServer Server1:ProductionHost_A:3278 --namedServer Server2:ProductionHost_B:4278 --namedServer Server3:ProductionHost_C:5278

Here Server1, Server2 and Server3 are the server logical names.

Builder with multiple data servers

Builder maintains connections with the data servers named in attachments and commands. Note that it connects directly to the correlator (dotted lines in the figure below) in order to populate dialogs with metadata. In this illustration, correlator event data is handled by the data servers.

You can override the logical server names specified in the Application Options dialog with the --namedServername:host:port option to the Builder executable. Below is an example. This is a sequence of command-line options which should appear on a single line as part of the command to start the executable:

--namedServer Server1:ProductionHost_A:3278 --namedServer Server2:ProductionHost_B:4278 --namedServer Server3:ProductionHost_C:5278

Here Server1, Server2 and Server3 are the server logical names.

Viewer with multiple data servers

Viewer maintains connections with the data servers named in attachments and commands of opened dashboards.

In the data server Login dialog (which appears upon Viewer startup), end users enter the host and port of the default data server (or accept the default field values). If all attachments and commands use named data servers, end users can check the Only using named data server connections check box and omit specification of a default server.

The logical data server names specified in the Builder’s Application Options dialog are recorded in the deployment package. You can override these logical name definitions with the --namedServername:host:port option to the Viewer executable. Below is an example. This is a sequence of command-line options which should appear on a single line as part of the command to start the executable:

--namedServer Server1:ProductionHost_A:3278 --namedServer Server2:ProductionHost_B:4278 --namedServer Server3:ProductionHost_C:5278

Here Server1, Server2 and Server3 are the server logical names.

Display server deployments with multiple data servers

The display server maintains connections with the data servers named in attachments and commands of its client dashboards.

Important:

In a display server deployment, each named data server must be started with the --namedServerMode option.

The logical data server names specified in the Builder’s Application Options dialog are recorded in the file OPTIONS.ini, which is used by the Deployment Wizard to define deployment logical names. You can override these logical name definitions with the --namedServername:host:port option to the display server executable. Below is an example. This is a sequence of command-line options which should appear on a single line as part of the command to start the executable:

--namedServer Server1:ProductionHost_A:3278 --namedServer Server2:ProductionHost_B:4278 --namedServer Server3:ProductionHost_C:5278

Here Server1, Server2 and Server3 are the server logical names.

Using table objects

Table visualizations provide a way to present the contents of data tables in a direct manner. You can present summary information be attaching a table’s valueTable property to an entire data table, or you can present a specified subset of data table rows and columns by using the filter fields of the Attach to Apama dialog.

• Attach the valueTable property to a DataView item table in order to create an instance summary table.
• Attach the property to a correlator status table in order to display information about each of the correlators that a DataView connects to.
• Attach the property to a trend or OHLC tables in order to create a tabular display of all the changes to a variable or OHLC values over time.

Double-click Summary Table on the tutorial main page to see a table object.

Table objects support typical table operations such as sorting and column ordering:

• Double-click the header of a column to sort by the column’s values. In the table shown above, users can double-click the Price column to sort the entries by price.
• Click a column header and drag it to reorder columns.

Sorting large tables can impact dashboard performance, particularly for display server deployments. Clear the property showSortIconFlag to disable sorting.

Detailed reference information on tables is provided in Table objects.

Creating an instance summary table

Table objects are often attached to an instance table to provide a summary view of the instances.

To create a summary table for an instance, you add a table object to a dashboard and attach its valueTable property to an instance table. When you define the attachment, you can select the variables to be displayed; these will be the columns of the table. You can also specify a filter to show only a subset of instances.

Note that, by default, users are authorized to view only those dashboards that they created. Regardless of filter settings, users will not be able to see instances they did not create.

To create a instance summary table, create a new dashboard and perform the following steps

1. From the Tables tab in the Object Palette, select the Table object and add it to the dashboard canvas.

2. In the Object Properties panel, double-click the valueTable property.

   The Attach to Apama dialog appears. Attach the table object’s valueTable property to an instance table.

3. Select the autoResizeFlag property and enable it by clicking the check box in the Property Value column.

4. Resize the table such that all columns are visible. (You resize the table by selecting it and dragging the handles.)

   The table now displays all the input and output variables of all instances of the specified instance, as well as the special fields Dashboard Builder adds, including apama.timestamp which indicates the time the instance last changed.

   Often, you will not want to display all the variables or the special fields in a summary table. The steps that follow show how to specify the variables to be displayed.

5. Double-click the valueTable property to display the Attach to Apama dialog.

   By default the display variables field is set to the wildcard “*” indicating that all the variables are to be displayed. Next to the field is a button labeled “…” that provides access to the Select Columns dialog.

6. Click on the “…” button to display the Select Columns dialog.

7. In the Select Columns dialog select and order the columns.

8. Click OK in the Select Columns dialog and OK in the Attach to Apama dialog.

   The table object will now display only those columns you selected.

   By default a table will display a maximum of 100 rows. If a dashboard needs to show more than 100 instances, change the value of the maxNumberOfRows property. The maximum value for this property is 131072.

   By default a table is unsorted. If you want a table to have a default sort order, set the sortColumnName property to the name of the variable to sort by, such as Price.

Filtering rows of an instance summary table

You can limit the set of instances displayed in an instance summary table by specifying a filter when you define the attachment. This is useful when you only want to display those instances with a shared characteristic, such as the exchange they are trading on.

To modify a data attachment with filter information

1. Select the table that you want to modify. For example, double-click Summary Table on the tutorial main page, and then select the table object.

2. In the Object Properties panel, double-click the valueTable property.

3. In the Attach to Apama dialog, do the following:

   1. Check the Filter checkbox.

   2. Specify a variable in the By variable field.

   3. Specify a value or values in the Value field. Specify multiple values as a semi-colon-separated list. Do not use spaces.

   4. If you specify multiple values, select Member of in the field above the Value field. (This field specifies a comparison relation. It default to Equals.)

      This selects instances whose value for the specified variable bears the specified comparison relation to the specified value. Here is an example:

      This example filters the table’s contents to display only the instance for which the value of the variable Instrument equals APMA.

Performing drilldowns on tables

Frequently you will want to display the DataView summary information in a table and provide the ability to drill down on a single instance or item in order to display detailed information about it. Table objects support drilldowns on a selected row and the passing of substitutions containing the values of one or more variables or fields of the selected instance.

Double-click Table Drilldown in the tutorial main page.

A drilldown has been specified for this table in such a way that the label object updates to show the value of the Price variable of the selected instance. As Price changes, both the table and label update.

To specify a drilldown as in the example above

1. Add a table to a dashboard and attach its valueTable property to an instance table as in the previous sample.

2. From the Labels tab in the Object Palette, select the second label object and add it to the dashboard canvas.

3. Select the label object on the dashboard and in the Object Properties panel double-click the valueString property to display the Attach to Apama dialog.

   Define the attachment by specifying the Display variables and Filter fields, for example as follows.

   

4. Click OK in the Attach to Apama dialog.

5. Double-click a row in the table. The label object will update to show the value of Price for the selected instance.

   The drilldown properties on the table, bar chart, and pie chart objects are preset for the most common usage paradigm where a drilldown on one will redisplay the current dashboard but with new substitution values. This paradigm fits the case where both the instance summary and instance detail data are displayed in a single dashboard window. You can modify the drillDownTarget property on these objects to use a non-default drill-down paradigm, such as displaying detailed information about the selected instance in a separate window. For more information, see Drill-down specification.

   In the example above, the label object’s data attachment selects the row in the instance table where apama.instanceId equals $instanceId. This is the most common filter used when performing drilldowns. The drilldown on the table object is defined by default to set the dashboard substitution variable $instanceId to the value of apama.instanceId for the selected instance. This allows the dashboard that is displayed in response to the drilldown to know which instance it should display data for.

   Specifying drill-down column substitutions describes how to override this default setting.

Specifying drill-down column substitutions

The substitutions set when performing a drilldown on a table object are defined by the drillDownColumnSubs property. Here is an example that sets a table column to a dashboard substitution variable, and then attaches a label to the variable.

1. Select the table object and double-click the drillDownColumnSubs property.

   The Drill Down Column Substitutions dialog appears.

   This dialog allows you to set a substitution variable to the value of a column in the table. By default, table objects are defined to set several substitutions, including $instanceId and $timestamp. These are set to the values apama.instanceId and apama.timestamp. In addition, substitutions are inherited by drilldown targets. That is, if a parent object sets a substitution variable for a child (the drilldown target of the parent), then that variable is set the same way for any grandchildren (drilldown targets of the child). You can override these or add additional substitutions with the DrillDown Column Substitutions dialog.

2. For the Velocity column, set the substitution string field as follows.

   

3. Click the OK button to close the dialog.

   The substitution variable $velocity will now be set when performing a drilldown on the table.

4. Select Variables from the Tools menu to display the Variables dialog.

   Add the substitution variable $velocity.

   

   You must add the $velocity substitution variable to the list of local variables, because the drilldown on the table is defined to redisplay the current dashboard. Defining the variable makes it available within the dashboard. If the drilldown displays a different dashboard, the variable must be in that dashboard’s list of local variables.

5. Select the label object previously added to the dashboard.

6. In the Object Properties panel, right-click the valueString property and select Attach to Data | VARIABLE.

   This will display the Attach to Local Variable Data dialog.

7. Select $velocityin the dialog and click OK.

   The label is now attached to $velocity. When you double-click a row in the table, the dashboard performs the drilldown and sets $velocity to the current value of Velocity of the selected instance. The dashboard updates the label object to show this value.

Note that when a visualization object is attached directly to Apama, it updates whenever the corresponding DataView field changes; but when it is attached to a dashboard substitution variable, it does not.

If you want a dashboard’s visualization objects to update as DataView fields change, attach them directly to Apama using $instanceId in the filter.

If you do not want the objects to update, that is, if you want only the values at the time drilldown was performed, define a drill down substitution to set a substitution variable to the current value, and then use that substitution in the dashboard drilled down to.

Hiding table columns

When you define drilldown substitutions on a table object, only those variables selected as the display variables in the table’s data attachment are available for setting substitution values. In the previous example, if the Velocity variable was not selected as a display variable for the table, then it would not have been available as a column in the Drill Down Column Substitutions dialog.

If you have a DataView field that you want to use to set a substitution when performing a drilldown on a table but do not want to appear as a column in the table, include it as a display variable when defining the attachment and set the columnsToHide property to prevent it from being displayed. To hide multiple variables specify them as a semicolon-separated list.

The columnsToHide property is preset to hide the apama.instanceId column. Apama transparently forces apama.instanceId to be included as a display variable on all table objects. This is so that you perform a drilldown, $instanceId can be set to the ID of the selected instance. You should always hide the apama.instanceId column.

Using pre-set substitution variables for drill down

There are some hidden variables that are always set when you perform a drilldown. These are useful if you want to know which column or cell was selected to perform the drilldown:

• $celldata: Set to the value of the cell selected.
• $colName: Set to the name of the column of the cell.

You can use these variables, for example, as parameters to functions or commands whose action you want to vary based on the column or cell value selected.

Formatting table data

The table object allows formatting attributes to be specified for each column in a table. Double-click Formatted Table in the tutorial main page.

Here formatting has been specified for the Shares, Price, and Position columns. The Price and Position columns include a currency indicator and the Position column is presenting negative positions inside parenthesis. Apama dashboards provide wide variety of formats, and you can specify custom formats as well.

To specify formatting information, double-click the columnFormat property and use the Column Format Properties dialog:

To format a column, select the column in the Column Name field and either select, or type, a format string in the Column Format field.

Specify column formats using a format string appropriate for use with the Java class java.text.DecimalFormat, or with the following shorthand: $ for US dollar money values, $$ for US dollar money values with additional formatting, () for non-money values, formatted similar to money, or # for positive or negative whole values.

Colorizing table rows and cells

The table object allows the color attributes of rows and cells to be set based on the value of a DataView field. Double-click Colored Table on the tutorial main page. The table shows a typical use for setting color attributes.

Here the Position cell is shown with green text if the position is positive and red text if it is negative. Colorizing a table can make it much easier to identify values of interest. Colorizing attributes are specified by setting the filterProperties property.

To set the filterProperties property

1. Double-click the filterProperties property.

   The Filter Properties dialog appears.

2. Double-click a filter to edit it or click the Add button to add a new filter.

   The Condition fields allow you to specify the condition which must be matched for the action to take affect. The Action field allows you to set the font or background color or hide a row. Hiding a row is useful if you do not want the row to appear based on some attribute of the instance. The Target field allows you to apply the action to single cell, row, or column.

A common use of table colorization is to provide a visual indication of the DataView items which have ended or failed. For example you may want to set the font color to gray for those which have ended and red for those which have failed.

To do this you must include apama.instanceStatus as a display variable in the table’s data attachment and, typically, in the list of columnsToHide. The filter properties for the table can then be used to set the font color based on the value of apama.instanceStatus with the following two filters. The following illustrations show how the Edit Filter dialog can be used for this purpose.

Setting column headers

By default the header for each column is the name of the DataView field it shows.

To change column headers by setting the columnDisplayNames property

1. Select a table object in the Object Properties panel.

2. Double-click the columnDisplayNames property.

   The Column Display Name Properties dialog appears.

   The header for the Instrument column is set to Stock Symbol.

3. Enter the desired column names in the dialog. If you want the header to span multiple lines include \n in the display name such as “Stock\nSymbol”.

Using rotated tables

Rotated tables rotate the data in the data table they are attached to such that rows become columns and columns become rows.

To create a rotated table

1. From the Tables tab in the Object Palette, select the Rotated Table object and add it to the dashboard canvas.

2. Attach the table object’s valueTable property to instance data just as you would for other kinds of tables (see, for example, Creating an instance summary table.

   

   Here the rotated table is attached to an instance table, and the filter is set to select only the instance where Instrument equals APMA. Without a filter, all instances appear as columns.

Using pie and bar charts

Pie and bar charts can be used in dashboards as an alternative to table objects for showing the DataView summary data. The charts are similar in their configuration and behavior. The following illustration shows a typical bar chart:

The following illustration shows a typical pie graph.

Both the bar and pie charts shown above display the value of Position for each instance. The bar chart provides an indication of negative values but the pie chart does not. Each chart supports drill downs similar to those supported by table objects.

Detailed reference information on graphs, including pie and bar charts, is provided in Graph objects.

Creating a summary pie or bar chart

To create a summary pie or bar chart for a DataView, you add an instance of the object to a dashboard and attach its valueTable property to a DataView instance table. When you define the attachment, you can select the variable to be charted as well as the label to be used for the data in the chart legend. As with table objects, when you define the data attachment, you can also supply a filter that specifies the subset of the instances that are charted.

Note that users can view only those DataView items that they created. Regardless of filter settings, users will not be able to see instances they did not create.

To see a sample bar chart, double-click Bar Chart on the tutorial main page.

To create a summary bar chart, create a new dashboard and perform the following steps

1. From the Graphs tab in the object palette, select the Bar Graph object and add it to the dashboard canvas.

2. With the graph object selected, double-click the valueTable property in the Object Properties panel, and attach the graph to a DataView.

3. Click OK.

The bar chart will now chart the value of Position for each instance of the DataView.

In this example the display variables were set to Instrument and Position. Instrument is a string variable and was included to provide a meaningful label for each bar in the chart legend.

For both bar and pie charts, you can pick a DataView string variable to use as the label in the legend. Do not pick a number variable as it will be interpreted as the value to chart.

If multiple number variables are selected for display, the behavior is controlled by the rowSeriesFlag property.

Using series and non-series bar charts

Data in bar charts can be displayed as both series and non-series data. This is determined by the rowSeriesFlag property.

If the rowSeriesFlag property is enabled, one group of bars will be shown for each numeric column in the data attachment. Within the group for each numeric column, there will be a bar for each row in that column. Column names will be used for the x-axis labels. If your data attachment has a label column and the rowLabelVisFlag is selected, data from this column will be used in the legend. If your data attachment does not have a label column, select the rowNameVisFlag checkbox to use row names in the legend. By default, the label column is the first non-numeric text column in your data. Specify a column name in the labelColumnName property to set the label column to a specific column.

If the rowSeriesFlag property is not enabled, one group of bars will be shown for each row in your data attachment. Within the group for each row, there will be a bar for each column in that row. Column names will appear in the legend. If your data attachment has a label column and the rowLabelVisFlag is selected, data from this column will appear on the x-axis. If your data attachment does not have a label column, select the rowNameVisFlag checkbox to use row names on the x-axis. By default, the label column is the first non-numeric text column in your data. Specify a column name in the labelColumnName property to set the label column to a specific column.

1. Create a new dashboard, select the Graphs tab in the Object Palette, and add a Bar Graph object to the dashboard canvas.

   By default the rowSeriesFlag property is enabled and the chart appears as follows.

   

2. With the graph object selected, in the Object Properties panel, select the rowSeriesFlag property and disable it.

3. Select the xAxisFlag property and enable it.

   The chart will now appear as follows.

   

Performing drilldowns on pie and bar charts

Drilldowns on pie charts are defined by setting the same properties you set on table objects in order to perform a drilldown: drill down target and drillDownColumnSubs.

Using trend charts

Trend charts are present in Trends and Trends HTML5 tabs of the object palette. The trend charts in the Trends HTML5 tab provide a pure HTML implementation of a trend chart. The HTML version of a trend chart provides an interactive and high performance trend chart in an HTML5 compatible browser.

Trend charts provide the ability to view changes in a DataView field over time. The following illustration shows a typical trend chart:

In this sample, a single trend line is displayed to show the value of the Price variable of an instance of the tutorial DataView.

A trend chart can display up to ten trace lines allowing you to compare changes in up to ten DataView fields. Useful examples of trend charts might show the changes in price for two stocks or the movement of a single stock price relative to a market average.

The traces in a trend chart can be shown as lines or as individual data points.

1. Open the file tutorial-trend.rtv by selecting Trend Chart on the tutorial main page.

2. Select the trend chart and in the Object Properties panel select the property trace1MarkStyle and change its value to 1.

3. Select the property trace1LineStyle and change its value to 0.

   The trace line in the trend chart will now be displayed as a series of points.

   

The data values displayed are the same; only the presentation has changed.

Detailed reference information on trend charts is provided in Trend graphs.

Creating a trend chart

To create a trend chart, you add it to a dashboard and set its traceCount property to the number of trace lines you want to display. This will cause a set of properties to be added to the property panel for each trace; trace1 through traceN. Following are the properties for trace1.

Each trace will have a traceNValue and traceNValueTable property. These define the data attachment for the traces. The traceNValue property is used to attach the trace to new data (data received after the time of attachment). The traceNValueTable property is used to attach the trace to historical data (data received before the time of attachment).

When attaching a trace to an instance variable, you must specify a filter that identifies the instance the trace will show data for. The filter to identify the instance will typically match on $instanceId although other filters can also be used.

The Trend Drilldown tutorial sample demonstrates how to use a trend chart where the instance charted is determined by the selection in an instance summary table.

To recreate this sample, create a new dashboard and perform the following steps

1. From the Tables tab in the Object Palette, select the Table object and add it to the dashboard canvas.

2. With the table object selected, in the Object Properties panel, double-click the valueTable property and attach it to Apama by specifying the information shown below in the DataView and Display variables fields. Do not apply a filter.

   

3. From the Trends tab in the Object Palette, select the Single Variable Trend object and add it to the dashboard canvas.

4. With the trend object selected, in the Object Properties panel, double-click the trend chart object’s trace1ValueTable property and attach it to the trend table for the tutorial DataView by specifying values in the fields as shown below.

   Here the Price variable is selected for the trace. The DataView item charted will be the selected instance as indicated by the variable $instanceId.

   

5. With the trend object selected, in the Object Properties panel, double-click the trend chart object’s trace1Value property and attach it to the trend table for the tutorial DataView by specifying values in the fields as shown below.

   Here the Price variable is selected for the trace. The DataView item charted will be the selected instance as indicated by the variable $instanceId.

   

6. Select the trend object’s scrollbarMode property and change its value to As Needed. This will add a scrollbar to the chart allowing you to scroll back in time to view earlier values.

7. Select a DataView item in the table by double-clicking on it. The chart will now begin charting the Price variable of the selected DataView item.

   If you have not previously displayed a sample containing a trend chart, no previous values for Price will be displayed. Apama does not collect data in a DataView trend table until the first attachment to an instance of the table is made.

Charting multiple variables

Trend charts are able to show up to 10 trace lines. This is useful for comparing changes in the values of multiple variables or fields. The following illustration shows the multiple variable trend chart from the Multiple Trend Lines tutorial sample.

Here the trend chart displays the Velocity of the stock price of two instances of the tutorial DataView; one where the Instrument is ORCL and the second where the Instrument is MSFT.

To recreate this sample, create a new dashboard and perform the following steps

1. From the Trends tab in the object palette, select the Multiple Variable Trend object and add it to the dashboard canvas.

   The multiple and single variable trend objects are virtually the same. The only difference is that in the multiple variable trend object the traceCount property is set to 2. If you need to display more than two trace lines you can select either object and set the traceCount property to the number of traces needed.

2. With the trend object selected, in the Object Properties panel, double-click the trend object’s trace1ValueTable property and attach it to Apama by specifying the following information:

   

3. With the trend object selected, in the Object Properties panel, double-click the trend object’s trace1Value property and attach it to Apama by specifying the following information:

   

4. Attach the trace2ValueTable property to Apama by specifying the following information:

   

   The trend chart will now chart the Velocity variable of the instances of the tutorial DataView which match the filters where Instrument equals ORCL and MSFT.

5. Attach the trace2Value property to Apama by specifying the following information:

   

   The trend chart will now chart the Velocity variable of the instances of the tutorial DataView which match the filters where Instrument equals ORCL and MSFT.

   When displaying multiple traces, it is often useful to display them as filled regions. To specify this, select the traceFillStyle property and change its value to Transparent Gradient. The following illustration shows an example of a trend chart with filled regions.

   

Adding thresholds

Often you will want to know when the value of a DataView field is outside a specified range. For example you may want to know when the price of a stock is above or below some threshold. Trend charts enable you to display thresholds and show when variables cross them. The following illustration from the Trend Thresholds tutorial sample shows a typical example.

Here the Velocity of an instance of the tutorial is being charted and high and low thresholds of.01 and -.01 are being displayed.

Trend charts support four thresholds that are specified with the properties; valueHighAlarm, valueLowAlarm, valueHighWarning, and valueLowWarning. These properties can be set to fixed values or attached to DataView fields. Each threshold has a set of properties for configuring it. Following are the properties for the valueHighAlarm property.

To recreate this sample create a new dashboard and perform the following steps

1. From the Trends tab in the Object Palette, select the Threshold Trend object and add it to the dashboard canvas.

2. With the threshold trend object selected, in the Object Properties panel, select the trace1ValueTable property and attach it to Apama by specifying the following information:

   

3. With the threshold trend object selected, in the Object Properties panel, select the trace1ValueValue property and attach it to Apama by specifying the following information:

   

   The trace line will now show the Velocity of the instance of the tutorial DataView where Instrument equals ORCL.

4. Select the valueHighAlarm property and change its value to 0.01.

5. Select the valueLowAlarm property and change its value to -0.01.

Thresholds will now be displayed.

Configuring trend-data caching

By default, dashboard servers (data servers and display servers) collect trend data for all numeric output variables of DataViews running in their associated correlators. This data is cached in preparation for the possibility that it will be displayed as historical data in a trend chart when a dashboard starts up. Without the cache, trend charts would initially be empty, with new data points displaying as time elapses.

Advanced users can override the default caching behavior on a given server, and control caching in order to reduce memory consumption on that server, or in order to cache variables that are not cached by default, such as non-numeric variables.

For more information, see Configuring trend-data caching.

Rendering trend charts in HTML5

A dashboard trend graph object can be rendered by using HTML5, which provides added functionalities to the chart object without requiring a Flash Player or other browser plug-in. Select the webChartFlag option to enable this feature.

The webChartFlag option appears in the list of properties for trend graphs (obj_trendgraph02).

When webChartFlag is checked, the HTML5 rendering of the trend graph object appears in place of the swing trend graph in the display server of an HTML5 compatible browser.

Requirements

A browser that supports HTML5 is required. Browsers that do not support HTML5 will display the swing trend chart regardless of the value of the webChartFlag property.

Properties

A trend chart rendered in HTML5 supports the major properties available in trend graphs. However several minor properties are not supported or have limited support in HTML5-rendered trend charts, as follows:

Rendering a trend chart in HTML5 supports two additional properties that are visible in the property sheet only if webChartFlag is checked:

Behavior

In addition to the properties listed above, there are some behavioral differences between an HTML5-rendered trend chart and a swing trend graph. These are described below:

• Legend

  The legend does not show trace point data (y) values. Data values are only shown in the mouseover tooltips (if cursorFlag = 1). The cursor always snaps to the nearest data point, it does not show interpolated values between data points. Trace labels longer than 200 pixels are wrapped in the legend, and labels longer than 150 pixels are clipped in the tooltip.

• Y axis autoscaling

  Given the same y data values, an HTML5-rendered trend chart may choose a different value range for the y axes in autoscale mode as compared to swing trend graphs. This is because somewhat different algorithms are used.

• Reset button

  If the user changes the chart’s visible time range, via the scrollbar or navigator or by dragging the cursor to perform a zoom, then a button labeled Reset will appear in the upper left corner of the plot area. A click on this button will reset the time axis to its original settings. The chart will also resume shifting to show the newest trace points, unless the timeRangeBegin/End properties are set.

• Data point grouping

  Rendering a trend chart in HTML5 makes use of a feature known as data grouping to enhance performance when a trace has many data points. With data grouping, the chart plots a single point using the average y value in cases where otherwise multiple points would be plotted on the same x pixel coordinate.

  When data grouping is in effect, the chart’s tooltip will display a start time and end time (rather than the usual single time value) to indicate the time range of the averaged data points, for example: 05-Mar 12:35:00 ~ 05-Mar 12:45:00.

  Info

  The data point grouping feature is enabled automatically and is not configurable. Also data grouping is performed independently of (and possibly in addition to) any data condensing or compaction that has already been applied by the historian. Also the maxPointsPerTrace property (3200 in the test1 display) is applied to the raw data, before any data grouping is applied.

  The legendTimeFormat property is used to format the date/time strings in the tooltip. If that property is blank then the timeFormat property is used instead. If the string contains a newline it is replaced with a space character to avoid making the tooltip overly tall.

• timeShift

  Rendering a trend chart in HTML5 does not attempt to keep the tick marks on the time axis aligned on even multiples of the timeShift value, in the case where timeShift > 1.

  Also, even if webCharFlag is set on all instances, the swing trend graph will still be used if a display is opened in Internet Explorer 8 or older, or if certain properties not supported by an HTML5-rendered trend chart (as listed above) are configured on a specific trend graph. To disable rendering trend charts in HTML5 globally, regardless of the webChartFlag value on individual objects, specify the

   --apama.extendedArgs "-nohtml5"
  

  argument on the display server command line.

Known issues and limitations

Consider the following when you use HTML5-rendered trend charts:

• After zooming or scrolling, the time axis labels may briefly be misaligned or overlap. They should be drawn correctly on the next refresh.
• The chart’s tooltip may overlap the Reset button making it difficult to click the button. Moving the mouse a bit will correct this problem.
• HTML5 rendering will display all timestamps using the local time zone. This may cause user confusion if the display server is in a different time zone.
• Performance is affected by the number of traces, trace points, use of trace line shadows, trace line thickness, trace markers, trace fill, and other properties. Performance is also affected by the browser and version, and the CPU speed of the client host system.
• If any of the chart’s graphical properties are changed while the chart is displayed (for example the traceFillStyle property is toggled by means of a checkbox control) the chart is rebuilt in the thin client, which in turn resets the chart’s time range (as though the Reset button was clicked).
• Scrolling: If the mouse is moved below the bottom of the chart while dragging the scrollbar, the scrolling will stop. This is unlike the behavior of other objects, which will continue to scroll until the mouse button is released.
• Drilldown from trace points: If traceFillStyle is not None (that is, trace fill is enabled) and multiple traces share the same Y axis, then it is not possible to click on a point belonging to traceN if the fill area of a higher numbered trace is drawn over that point.
• When yAxisLogFlag = 1 and the chart has multiple y axes and traces, some y axis labels may appear rather than numeric values. This is rare.
• Since HTML5-rendered trend charts do not support legendWidthPercent, the width of each chart’s legend will vary according to the trace labels. This makes it difficult to create multiple trend chart instances on the same display whose time axes are all the same length, even if the charts all have the same width. (A single chart in stripchart mode may be more appropriate in those cases).
• On a touch interface, a swipe will scroll the chart left or right. To move the cursor without scrolling, tap the location to which you want the cursor to move.
• On a touch interface, a pinch-open gesture in the plot area, scrollbar, or navigator will zoom the chart’s range in to the pinched range. A pinch-close gesture will zoom out to the pinched range. The pinch-close operation may be difficult to use. A tap on the Reset button gives a better zoom-out experience.

Hidden properties when webChartFlag is selected

Following is the list of obj_trendgraph02 properties that are hidden when webChartFlag is checked:

• borderPixels
• labelMinTabWidth
• legendWidthPercent
• legendBgGradientMode
• legendBgGradientColor2
• legendValueMinSpace
• markDefaultSize
• markScaleMode
• outlineColor
• scrollbarMode
• scrollbarSize
• zoomEnabledFlag
• timeRangeOfHistory
• traceBgColor
• traceBgGradientMode
• traceBgGradientColor2
• traceBgImage
• yAxisAutoScaleVisTracesOnlyFlag
• yAxisFormat
• yAxisFlag
• yAxisPosition
• yAxisValueLabels
• yAxisMajor/MinorDivisions
• xAxisFlag
• xAxisMajorDivisions

For each traceN, the following properties are hidden:

• traceNValueAlarmStatus
• traceNValueAlarmStatusTable
• traceNValueHistoryFlag
• traceGroupNBandedFlag
• traceNYAxisGridVisFlag
• traceNYAxisMinLabelWidth
• traceNYAxisValueLabels
• traceNYAxisVisFlag
• traceNYAxisAutoScaleMode
• traceNYAxisValueMin
• traceNYAxisValueMax

Using stock charts

Stock charts provide the ability to view the Open, High, Low, and Close values (OHLC) for a DataView field such as stock price over set time intervals. The intervals may be small such as 5 seconds if being used for intra-day trading or larger for longer time periods such as hours, days, or weeks. The following illustration is from the Stock Chart tutorial sample.

In this example, the OHLC values are shown as a candlestick chart where each “stick” represents a 5 second interval. The stock chart supports others display formats such as OHLC, line, and bar.

1. Open the file tutorial-stock-chart.rtv by double-clicking Stock Chart on the tutorial main page.

2. Select the stock chart object and in the Object Properties panel, select the priceTraceType property and change its value to OHLC.

   

   The data displayed is the same as that displayed in the previous illustration where priceTraceType was set to Candlestick. Only the presentation has changed.

Although named “stock chart” you are not limited to using it for stock data. You can chart Open, High, Low, and Close values for any DataView field. Other financial and non financial data can often benefit from being visualized as a stock chart.

Detailed reference information on stock charts is provided in Stock charts.

Using OHLC values

The OHLC values for a stock chart can be provided by attaching the stock chart to one of the following:

• OHLC table
• DataView trend table
• DataView instance table

The simplest is to attach the chart to a DataView OHLC table. This is specified when creating the attachment in the Attach to Apama dialog.

When attaching to a DataView OHLC table, you need only specify the DataView variable you want to chart OHLC values for and a time interval. Apama will then automatically calculate the OHLC values. No modifications are required to your DataView. The following section uses the Stock Chart tutorial sample.

1. Select the stock chart object in the tutorial-stock-chart.rtv file.

2. In the Object Properties panel, double-click the priceTraceHistoryTable property to display the attachment settings for the stock chart.

3. In the Object Properties panel, double-click the priceTraceCurrentTable property to display the attachment settings for the stock chart.

Here the attachment is made to the DataView OHLC table of the tutorial DataView and the Price variable is being displayed. This is the variable for which OHLC values will be calculated and displayed. The event timestamp, apama.timestamp, is the timestamp used to determine the time of events. The time interval is set to 5 seconds resulting in an OHLC value being charted every 5 seconds where each represents the preceding 5 seconds. The filter is set to match the DataView instance where the variable Instrument equals APMA.

When attaching to a DataView OHLC table, you must specify the time interval so that Apama knows what interval to use to calculate OHLC values.

You must also specify a filter. As with trend charts a stock chart displays the value of one variable of a single instance over time. If a filter matches more than one instance, the first found will be displayed.

The second way to provide OHLC data for a stock chart is to attach it to a DataView trend table. Do this when you want control of the calculation of OHLC values in a DataView. This requires that the DataView have the variables for open, high, low, and close. When attaching a stock chart to a DataView trend data you must specify for the display variables the individual open, high, low, and close variables of the DataView.

In this illustration, the attachment is made to the DataView trend table of the OHLC DataView. The DataView variables open, high, low, and close are used to provide the OHLC values. Notice that the Using time interval field is disabled. This is because the DataView is calculating the OHLC values; not the dashboard or dashboard server.

The names of the DataView variables do not matter. However, they must be specified in the order open, high, low, and close. Only number variables can be used. String variables must be converted to numbers for use in stock charts.

The third way to provide OHLC data for a stock chart is to attach it to a instance table. This is similar to attaching to a DataView trend table. In that, the DataView has control over the calculation of the OHLC values. It differs in that OHLC data for only one instance that is maintained in memory. This is valuable when you want to minimize memory use. However, it results in the chart being reset, cleared of all data, whenever OHLC values for a different instance are displayed.

Use the priceTraceHistoryTable when attaching a stock chart to an instance table. Attaching the priceTraceCurrentTable property to a instance table will result in only the latest data value being displayed.

In this illustration, the attachment is made to the instance table of the OHLC DataView. The DataView variables open, high, low, and close are used to provide the OHLC values. If you do not enable the Timestamp variable field for instance table attachments, you need to specify the timestamp as the first entry in the Display variables field; here apama.timestamp is being used.

Creating a stock chart

To create a stock chart, you add it to a dashboard and attach its priceTraceHistoryTable property to OHLC data for an instance. The filter to identify the instance will typically match on $instanceId although other filters could also be used.

The Stock Chart Drilldown tutorial sample demonstrates how to use a stock chart where the instance charted is determined by the selection in an instance summary table.

To recreate this sample create a new dashboard and perform the following steps

1. From the Table tab in the Object Palette, select the Table object and add it to the dashboard canvas.

2. With the table object selected, in the Object Properties panel double-click the table object’s valueTable property and attach it to Apama and select the tutorial DataView. Select the display variables shown in the example and do not apply a filter. The information should be specified as follows:

   

3. From the Trends tab in the Object Palette, select the Stock Chart object and add it to the dashboard Canvas.

4. With the stock chart selected, in the Object Properties panel, double-click the priceTraceHistoryTable property. Attach it to the OHLC table for the tutorial DataView and specify the rest of the information as shown in the following illustration. Here the Price variable will be charted over 5 second intervals. The instance charted will be the selected instance as indicated by the variable $instanceId

   

5. With the stock chart selected, in the Object Properties panel, double-click the priceTraceCurrentTable property. Attach it to the OHLC table for the tutorial DataView and specify the rest of the information as shown in the following illustration. Here the Price variable will be charted over 5 second intervals. The instance charted will be the selected instance as indicated by the variable $instanceId.

   

6. Select the timeRange property and set its value to 60.0. This will set the chart’s time axis such that 60 seconds of data will be visible. If you set the value too high you may encounter problems where the “sticks” of the chart are close and overlap.

7. Select the scrollbarMode property and change its value to As Needed. This will add a scrollbar to the chart allowing you to scroll back in time to view earlier values.

8. Select an instance in the table by double-clicking on it. The chart will now begin charting OHLC values for the Price variable of the selected instance.

If you have not previously displayed a sample containing a stock chart, values in the chart will not appear for ten seconds. Apama does not collect data in an instance OHLC table until the first attachment to an instance of the table is made.

Adding overlays

Stock charts support up to nine overlays. An overlay is much like a trace in a trend chart. Overlays can be used to compare the displayed OHLC values against other variables or fields such as other stock prices, overall activity on the stock index, or to show periodic events such as stock splits and earnings announcements.

Here the overlay is showing the velocity of the stock price. Notice that multiple scales are shown on the Y axis; the outer scale corresponds to the stock price and the inner scale the velocity.

1. Open the file tutorial-stock-overlay.rtv by selecting Stock Chart Overlays on the tutorial main page.

2. Select the stock chart and in the Object Properties panel, select the property overlay1Type and change its value to Bar.

The overlay values are now displayed as discrete bars and not as a single line.

If you set overlay1Type to Event, event markers will be placed on the chart at the occurrence of each event. This allows you to easily identify when key events occurred. The following illustration demonstrates this.

The character displayed in event markers is the first letter of the corresponding overlayNLabel property.

When using overlays to display event markers, the event markers should be relatively sparse. Displaying high numbers of event markers will cause them to overlap and limit their usefulness.

To add overlays to a stock chart, set the overlayCount property to the number of overlays to be displayed. This will cause a set of properties to be added to the property panel for each overlay; overlay1 through overlayN. Following are the properties for overlay 1.

When you attach an overlay to a DataView OHLC table or a DataView trend table, use the properties OverlaynCurrentTable and OverlaynHistoryTable.

Use only the OverlaynCurrentTable property when attaching the overlay to an instance table. Attaching to an instance table requires less memory but the resulting overlay may be missing one or more data points. This can occur if the dashboard is running on a heavily loaded system. Unless you have severe memory restrictions, you should not attach overlays to an instance table. Better results can be achieved by attaching to a DataView trend table. This will guarantee that the overlay contains all data points.

Recreating the Stock Chart Overlay sample

To recreate the Stock Chart Overlay sample

1. Open the file tutorial-stock-chart.rtv by selecting Stock Chart on the tutorial main page.

2. Select the stock chart and in the Object Properties panel, select the property overlayCount and change its value to 1. This will cause the overlay1 properties to be added to the property panel.

3. Double-click the overlay1HistoryTable property and attach it to a DataView OHLC table by specifying the following information.

   

   The overlay is now attached to Velocity property of the instance where the Instrument equals APMA; this is the same filter used for the priceTraceHistoryTable attachment.

4. Double-click the overlay1CurrentTable property and attach it to a DataView OHLC table by specifying the following information.

   

   The overlay is now attached to Velocity property of the instance where the Instrument equals APMA; this is the same filter used for the priceTraceHistoryTable attachment.

5. Select the overlayCount property in the property panel and change its value to 2. This will cause the overlay2 properties to be added to the property panel.

6. Double-click the overlay2HistoryTable property and attach it to a DataView trend table by specifying the following information:

   

7. Double-click the overlay2CurrentTable property and attach it to a DataView trend table by specifying the following information:

The stock chart now contains two overlays; one showing the velocity of the stock price and the second showing the current position in that instrument. The following illustration shows how this looks in the sample.

Overlays can be hidden by tuning off the overlayNVisFlag property. This is for use when building dashboards where you will have input controls such as checkboxes which will allow the user to hide or show different overlays.

Generating OHLC values

If you generate OHLC values, you should also use a DataView field as the timestamp. If you use apama.timestamp, you need to design the DataView to generate update events only when the OHLC values change. Your dashboard will add an OHLC data point to a Stock Chart for every Update event it receives. If a DataView, for example, generates Update events in response to other variables changing and apama.timestamp is being used as the timestamp, then spurious OHLC data points will be added to the chart. If the chart were displaying a candlestick this would manifest itself as extra “sticks” appearing in the chart.

If you use a DataView field as the timestamp, data points will only be added to the chart when timestamp and/or OHLC values have changed.

Furthermore, the update of the OHLC values must occur as a whole; that is each Update event must contain the updated value of each of the Open, High, Low, and Close variables. If the update of each variable were to generate a separate Update event, you would also have spurious data points in the chart. This is because your dashboard has no way of knowing if the unchanged values are correct or not.

To update the OHLC variables in a single update event, your DataView needs to set the value of each in the scope of a single rule. For example:

Here local variables _open, _high, _low, and _close are used throughout to calculate the OHLC values. Within this rule, the output variables open, high, low, and close are being set to these values such that a single Update event contains the updated value of each.

If you use a DataView field as the timestamp, data points will only be added to the chart when timestamp and/or OHLC values have changed.

Furthermore, the update of the OHLC values must occur as a whole; that is each Update event must contain the updated value of each of the Open, High, Low, and Close variables. If the update of each variable were to generate a separate Update event, you would also have spurious data points in the chart. This is because your dashboard has no way of knowing if the unchanged values are correct or not.

To update the OHLC variables in a single update event, your DataView needs to set the value of each in the scope of a single rule.

Localizing dashboard labels

You can localize dashboard labels by attaching XML data (filtered based on the end-user-specified value of a dashboard variable) to the object properties that specify the labels. For a complete localization example, select Localization on the Dashboard Builder Tutorial main page.

To localize dashboard labels

1. Create an XML dataset with a tabular data element. (See Using XML data.) Create a column for supported locales, as well as a column for each label. Create a row for each locale. In each row, put a specific locale and the text for each label localized for that specific locale. Here is an example from the Builder tutorial:

   
   <?xml version="1.0" encoding="UTF-8"?>
   <dataset xmlns="www.sl.com" version="1.0">
   <table key="labels">
   	<tc name="Locale"/>
   	<tc name="Confirmation message"/>
   	<tc name="Press button"/>
   	<tc name="Are you sure"/>
   	<tc name="Numeric input"/>
   	<tc name="Datetime input"/>
   	<tc name="Numeric display"/>
   	<tc name="Datetime display"/>
   	<tr name="English">
   		<td>en_US</td>
   		<td>Confirmation message:</td>
   		<td>Press button</td>
   		<td>Are you sure?</td>
   		<td>Numeric input:</td>
   		<td>Date time input:</td>
   		<td>Numeric display:</td>
   		<td>Date time display:</td>
   	</tr>
   	<tr name="French">
   		<td>fr_FR</td>
   		<td>Message de confirmation:</td>
   		<td>Bouton-poussoir</td>
   		<td>Etes-vous sûr?</td>
   		<td>Entrée numérique:</td>
   		<td>Entrée date-heure:</td>
   		<td>Affichage numérique:</td>
   		<td>Affichage date-heure:</td>
   	</tr>
   	<tr name="Spanish">
   		<td>es_ES</td>
   		<td>Mensaje de confirmación:</td>
   		<td>Botón</td>
   		<td>¿Estás seguro?</td>
   		<td>Entrada numérica:</td>
   		<td>Entrada de la fecha y hora:</td>
   		<td>Exhibición numérica:</td>
   		<td>Exhibición de la fecha y hora:</td>
   	</tr>
   	<tr name="Chinese">
   		<td>zh_TW</td>
   		<td>確認信息 :</td>
   		<td>按鈕</td>
   		<td>你肯定嗎？</td>
   		<td>數字輸入:</td>
   		<td>日期-時間的輸入:</td>
   		<td>數字顯示:</td>
   		<td>日期-時間的顯示:</td>
   	</tr>
   </table>
   </dataset>
   

   This file defines labels Press button, Are you sure?, and so forth, for the languages English, French, Spanish, and Chinese. The first column Locale defines the locale, or language, of the corresponding row.

2. For each object property that specifies a label, attach the property to the column that corresponds to that label, filtered to select the row for which the value in the locale column is the value of a dashboard variable that specifies the locale desired for the end user. You can use the predefined variable $apama_lang for this purpose. Here is an example:

   

3. Provide a way for end users to set the relevant variable (for example, the predefined dashboard variable $apama_lang) to their desired locale. One way to do this is to include, on your top-level dashboards, a combo box (from the Controls tab). Attach the selectedValue and varToSet properties of the combo box to $apama_lang, and attach the listValues property to the locale column of your XML data element. Here is an example:

   

   The dashboard substitution $apama_lang is automatically defined for dashboards. Use ISO 639 language codes as values of this variable. This is the same locale string used within Java. See the Java documentation for the java.util.Locale class for more information on locales within Java. Here are some sample locale values:

   For dashboards in Builder and Viewer connected directly to the Correlator, the default value for $apama_lang is what Java reports as the locale in the Locale object as derived from the host system’s locale.

   Locale Name	Locale
   Locale.CHINA	zh_CN
   Locale.CHINESE	zh
   Locale.SIMPLIFIED_CHINESE	zh_CN
   Locale.TRADITIONAL_CHINESE	zh_TW
   Locale.PRC	zh_CN
   Locale.TAIWAN	zh_TW
   Locale.ENGLISH	en
   Locale.UK	en_GB
   Locale.US	en_US
   Locale.FRANCE	fr_FR
   Locale.FRENCH	fr

   For deployed dashboards, the value of $apama_lang is set based on the locale of the host on which the dashboard display server or data server is running. A single dashboard server cannot serve dashboards to users in different languages. Note that number and date formatting performed by the dashboard server are always controlled by the system locale.

   Info

   Numeric formats (1,000.00 versus 1.000,00) are controlled by the system locale. You cannot change this by setting $apama_lang. The only way to override it, other than changing your system locale, is through Java system properties. Date/time formats are also controlled by the system locale.

Localizing dashboard messages

For thin-client (display server) deployments, you can localize the text displayed in popup menus, login windows, status windows, and various error messages.

To localize dashboard messages

1. Extract the file rtvdisplay_strings.properties from the WEB-INF/classes/gmsjsp directory of the rtvdisplay.war file in your deployment package. Copy it to a new file with the desired locale suffix (for example, rtvdisplay_strings_ja.properties for Japanese).

2. Edit the new file so that it contains the localized text.

3. Pack the edited file into rtvdisplay.war, in WEB-INF/classes/gmsjsp.

   The locale setting of your application server is used to determine which properties file to load. If the application server does not have the desired locale setting for the thin client, edit the original file (rtvdisplay_strings.properties) and pack it into the .war file.