Request definition use
In order to use the request definition UI, a valid openIoT account is required. When the user first launches the request definition UI they will be automatically redirected to a login screen. After a successful login, the user will be redirected to the main application UI.
[
](Documentation/images/request-definition/01-ui-overview.png)
The main application UI consists of four panes: the node toolbox, the property view pane, the design view workspace and the console pane.
The node toolbox is located on the left side of the application UI. It contains a list of nodes that may be dropped into the design view workspace. Nodes are grouped by their function.
The data source group contains a list of sensors types that were discovered via a location-based query. To perform a new discover query click the magnifying glass icon next to the data source header.
The property view pane is located on the right side of the screen. It allows users to examine and modify the properties of the currently selected node in the design view workspace.
Depending on the selected node type, the UI may allow the user to convert a property field into a variable. Variable properties support application cases where one or more of the field values known during the query execution time and not during the application design time. This functionality is however not supported for sink nodes.
To convert a property field into a variable click the convert to variable button next to the property field to launch the variable editor dialog. Check the convert to variable checkbox, enter a name for the variable and adjust its default value. When you click the apply button the previous variable field will become readonly and contain the variable name.
To revert this action, click again the convert to variable button next to the property field and uncheck the convert to variable checkbox
[
](Documentation/images/request-definition/03-variable-editor.png)
[
](Documentation/images/request-definition/04-variable-editor-2.png)
The design view workspace serves as a canvas where toolbox nodes can be dropped, rearranged (click-drag) and connected together.
Connections between nodes may be established by clicking on the source node endpoint and then dragging a connection to a destination endpoint. When a connection attempt is performed, the UI will automatically highlight the destination endpoints that can be connected.
Node selection is performed by clicking on a node. To deselect the currently selected node click anywhere inside the canvas area. To delete a node select it and press the delete key on your keyboard. To disconnect a connection, click the connection destination endpoint, drag the connection and drop it to the canvas.
The console pane allows users to read and edit the application's description, identify and resolve validation error and warnings and examine the generated SPARQL code.
[
](Documentation/images/request-definition/05-file-menu.png)
To create a new application, click the new application menu options to launch the new application dialog.
[
](Documentation/images/request-definition/06-new-application-dialog.png)
Enter a name for the application and an optional description. The name should be unique. Click the apply button to create the new application and open it into the workspace view.
To open a specific application into the workspace click the open application menu and select one of the available applications. The application will be loaded into the workspace view
This menu option allows the user to reload their applications from the openIoT repositories. The loaded applications will replace the currently loaded applications.
This menu options allows the user to import a set of applications that were exported by another request definition instance as a XML document. By clicking this option, the import applications dialog will appear. Choose a file to upload and select whether the applications should be just imported into the workspace or also be persisted to the openIoT repositories. After clicking apply, the application xml file will be loaded and replace the currently loaded applications.
[
](Documentation/images/request-definition/07-import-apps-dialog.png)
This menu option allows the user to export the currently loaded set of applications as a XML document which can then be imported by another request definition UI instance. Before the applications are exported, the system will first validate them. If any validation error occurs, the system will display an error message and abort the export process.
[
](Documentation/images/request-definition/08-app-menu.png)
This menu option allows the user to clear the currently opened application. Any unsaved changes will be lost.
This menu option will validate the currently opened application and display a validation summary message indicating any validation warnings and errors. Warnings and errors are displayed inside the problems and warnings tabs in the console pane. By clicking on a problem or warning description, the UI will highlight the problematic node or endpoint.
[
](Documentation/images/request-definition/09-validation-errors.png)
If the validation is successful, then the code view tab in the console pane will display the generated SPARQL code.
[
](Documentation/images/request-definition/10-code-view.png)
This menu option allows the user to save the currently edited application to the openIoT repositories so that it can be accessed by the request presentation UI and other third-party applications. Before the application is sent to the openIoT scheduler registration service, it will first be validated. If any validation errors are detected, the system will prompt the user to correct them and then try saving the application again.
As you may notice, the data sources entry in the node toolbox initially contains no entries. Since the openIoT architecture supports a vast number of distributed sensor types (classes) and showing them all at the same type is not feasible, the user needs to select a subset of the available sensors using a location-based search query. To perform a search click on the magnifying glass icon next to the data sources header in the node toolbox. This will launch the sensor discovery dialog.
[
](Documentation/images/request-definition/11-find-sensor-dialog.png)
Sensor discovery is facilitated by selecting a geographical location and specifying a search radius. To select the search center location, type the location's name into the location textfield and then click the lookup button. The map will then display the location that matched your search query. Click on any map point to place a selection marker. Then specify a value for the search radius field and click the find sensors button. The system will execute the sensor discovery query and populate the data sources group in the node toolbox any sensor type (class) that matched your search query. These sensor nodes can then be dragged to the main workspace view.
Any application design should contain at least one source node and one sink node. Source nodes can be discovered using the sensor discovery dialog. Sink nodes are basically visualization widgets that will retrieve the incoming (processed) data from the connected source nodes and display them inside a dynamically generated dashboard (request presentation UI)
The meter gauge node displays its input using a meter gauge. Its input enpoint can only accept aggregated values (an aggregation node is required between the source node and this node). The meter gauge supports the following editable properties:
- Widget title: The title that will appear in the request definition dashboard
- Measure unit: A label that will appear next to the gauge to help users understand the measurement unit of the displayed value
- Min/Max value: The minimum and maximum expected value for the incoming data.
[
](Documentation/images/request-definition/12-meter-conf.png)
This node displays a map where the node's inputs are displayed using markers or circle overlays. The node exposes endpoints for connecting the latitude and longitude endpoints of a discovered sensor. Its value input enpoint can only accept aggregated values (an aggregation node is required between the source node and this node's value input). The map node supports the following editable properties:
- Widget title: The title that will appear in the request definition dashboard
- Latitude/Longitude: The coordinate pair that will serve as the map's center for the visualization widget.
- Zoom level: The map zoom level for the visualization widget
- Type: The type of the overlays that will be displayed on the map. Available options are markers only, circles only, circles and markers.
- Value scaler: The rendered circle overlays' radius needs to be specified in pixels. The value scaler allows us to normalize the input values so that the rendered circles appear with the desired size. For example if the displayed value is greater than 0 and less than 1.0 then we can apply a value scaler equal to 100.0 to plot circles between 0 and 100 pixels.
[
](Documentation/images/request-definition/13-map-conf.png)
This node displays a pie-chart with a configurable number of series. Each series' input enpoint can only accept aggregated values (an aggregation node is required between the source node and this node's series value input). The node supports the following editable properties:
- Widget title: The title that will appear in the request definition dashboard
- Series count: The number of series. When this value is changed, the system will automatically generate/remove series endpoints depending on the selected value. The system will also generate/remove properties for each series' label.
- Series X label: A label for each one of the configured series.
[
](Documentation/images/request-definition/14-pie-chart-conf.png)
This node displays a line chart that supports multiple user-configurable series. Depending on the type of the X axis input, the line chart operates in 3 modes. This node supports the following properties:
- Widget title: The title that will appear in the request definition dashboard
- Series count: The number of series. When this value is changed, the system will automatically generate/remove series endpoints depending on the selected value. The system will also generate/remove properties for each series' label.
- X axis type: The type of X axis. The allowed options are number, date(result set) and date(observation)
- Series X label: A label for each one of the configured series.
In this mode, the X axis type is set to number. When in this mode, the node will generate a (xi, yi) enpoint tuple for each configured series. All enpoints expect an aggregated numeric value to be connected to them. This mode of operation allows us to setup linecharts that plot one attributes value in respect to another attribute's value.
[
](Documentation/images/request-definition/15-line-chart-conf-1.png)
This mode is enabled by setting the x axis type to Date (result set). In this mode the node will only generate a yi endpoint for each configured series. The visualization widget will use the incoming query response timestamp as the x axis value. This mode of operation allows us to setup line charts that plot an attribute's aggregated value over time (like for example the average temperature for the last 5 minutes)
[
](Documentation/images/request-definition/16-line-chart-conf-2.png)
This mode is enabled by setting the x axis type to Date (observation). When in this mode, the node will generate a (xi, yi) enpoint tuple for each configured series. The main difference from the other two modes of operation is that in this mode, we can connect multiple time groups (generated by a grouping node) to each one of the xi endpoints. The time group connection order is not important. The visualization widget will automatically detect the connected time groups from the query results and generate the appropriate timestamp for the x axis. The yi enpoints expect an aggregated numeric value generated by a grouping node to be connected to them.
This is a special node that works as a generic sink. It allows the user to define a configurable number of attribute endpoints and connect values to each one of the attributes. This node was designed to support third-party application developers that want to use the request definition UI to visually design their applications and then directly query the middleware for results so as to update their custom UIs. The visualization widget for this particular node renderes all results in tabular form. This node supports the following properties:
- Widget title: The title that will appear in the request definition dashboard
- Attribute count: The number of attribute endpoints. When this value is changed, the system will automatically generate/remove endpoints from the nodedepending on the selected value.
[
](Documentation/images/request-definition/17-line-chart-conf-3.png)
The application designer provides several nodes for aggregating values ( count, min, max, sum and average). Keep in mind that most sink nodes expect an aggregated value expression as their input. These nodes do not expose any user-editable properties.
[
](Documentation/images/request-definition/18-passthrough-conf.png)
The filter node allows us to specify a time-filtering condition for selecting recorded sensor data. To setup data filtering, drag & drop a discovered sensor node to the workspace, then drag & drop a filtering node to the workspace and connect its to node endpoint with the sensor's sel. filter endpoint. Once the connection is established, the recordTime endpoint will appear on the selection filter node. This endpoint can be connected to any comparator node to setup the filter conditions (described in the following sections).
[
](Documentation/images/request-definition/19-agr-nodes.png)
This node allows us to partition one or more sensor attributes into time period buckets. Each grouped value may then be connected to an aggregation node to calculate an aggregate for each generated bucket. To setup this node, drag & drop it into the workspace and then connect one or more sensor attributes to it.
Each connected sensor attribute will generate a new output endpoint (with the grp_ prefix). This endpoint represents each aggregated bucket's contents and can be connected in turn to an aggregation node to apply an aggregation function to each bucket.
To select the grouping options click the group node and press the grouping options button in the property pane. This will launch the grouping options dialog. The left list contains the available grouping fields while the right list contains the fields that will be used for grouping. Fields can be added and removed from the right list using the provided controls, while the actual group order can be changed by rearranging the group field order.
Keep in mind that grouping order is important for getting back proper data (grouping by YEAR, MONTH, DAY is different than grouping by DAY, MONTH, YEAR). Once you have decided which fields should be used for grouping click the apply button. Depending on the group fields that you selected, one or more time-bucket output endpoints will appear on the group node. These endpoints can be connected to any sink node that accepts time-based inputs (currently only the line chart supports this kind of connections).
[
](Documentation/images/request-definition/20-selection-filter-node.png)
[
](Documentation/images/request-definition/21-group-node-dialog.png)
These nodes are used to specify a time-based filter for selecting sensor observation data. They are designed to work in conjunction with a filtering node.
This node allows us to filter the observation data with respect to an absolute date. This filter will ensure that we select the observations that match the following condition: obs_record_time OPERATOR absolute_date To set up this node connect it to a filtering node and then fill in the values for the node's properties.
- Operator: The operator to use for comparing the record time to the given absolute date
<, <=, =, >, >= - Value: The absolute date to use for the comparison. Click the calendar icon to display a date picker.
[
](Documentation/images/request-definition/22-group-node-0.png)
This node allows us to filter the observation data relative to the query execution time. This filter will ensure that we select the observations that match the following condition:
NOW() - obs_record_time OPERATOR value unit
To set up this node connect it to a filtering node and then fill in the values for the node's properties.
- Operator: The operator to use for comparing the record time to the given absolute date
<, <=, =, >, >= - Value: A number which will be combined with the unit to generate a comparison value.
- Unit: The comparison time unit (seconds, minutes, hours, days, months, years). It will be combined with the value to generate a comparison value.
The following example will select observations that have been recorded during the last 10 minutes (relative to the time the query is actually executed)
[
](Documentation/images/request-definition/23-compare-abs-date.png)
This node allows us to select observation data between two absolute dates. This filter is useful when we need to query historical data between two dates. Observation selection is performed using the following condition: from_date <= obs_record_time <= to_date
To set up this node connect it to a filtering node and then fill in the values for the node's properties.
- From date: The earliest date to select observations from.
- To date: The latest date to select observations from.
For using the Request Definition application a service must have been created for it. When the OpenIoT graph is initialized, a service is created for the Request Definition with the following address, key and secret as defined in the openiot.properties:
- security.initialize.reqDef.prefix=http://localhost:8080/ui.requestDefinition
- security.initialize.reqDef.secret=requestDefinitionUI-secret
- security.initialize.reqDef.key=requestDefinitionUI
Currently, for using the application, no permissions are needed for the user on the request definition service. However, the user must have the permission "*" on the scheduler service.
The security configuration for the Request Definition application is located in security-config.ini in the JBoss configuration directory. The configuration content is delimited by @BEGIN-requestDefinition and @END-requestDefinition.