Data Definitions

Data Definitions allow developers to leverage Logi Info's ability to connect to a variety of datasources in order to create a powerful JSON and XML data provider for Logi applications, non-Logi applications, and client browsers.

About Data Definitions

Logi Info applications are capable of connecting to, and retrieving data from, a wide range of datasources. They also allow retrieval from multiple datasources simultaneously and can provide SQL-like JOINs between non-SQL datasets.

Data definitions allow the developer to retrieve data from these sources, manipulate it, and then make it available as a JSON data stream to a variety of data consumers.

The diagram shown above illustrates this concept. Creating a Logi data definition is simple and uses the same elements and techniques used in Logi report definitions. Writing code that consumes the JSON data is also easy and a variety of examples are provided in the later sections of this topic.

The JSON data produced can be accessed by Logi apps, directly from browsers, and by any application written in a programming language that supports HTTP requests.

Data definitions can also create both JSON and XML data.
 

Browsers and Cross-Origin Resource Sharing

When the client accessing the Logi data definition is a browser that's not on the same domain, you'll need to use the Cross-Origin Resource Sharing (CORS) mechanism to guarantee access. The CORS standard describes HTTP headers which provide browsers with a way to request remote URLs when they have permission. CORS is supported by most modern browsers.

 CORS is not necessary when web server applications are consuming the data.

CORS is implemented for Logi data definitions by configuring your web server's HTTP Response Header.

The example above shows this being done for IIS, using the IIS Manager application. It can also be done by modifying the web.config file directly.
 

<filter>
  <filter-name>CorsFilter</filter-name>
  <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>CorsFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

For Apache Tomcat (starting with v7.0.41), the code shown above can be added to $CATALINA_BASE/conf/web.xml or WEB-INF/web.xml. Other Linux-UNIX web servers can be configured similarly. Refer to your server's documentation.

This external site, Enable CORS, provides a lot of useful information about CORS and has server configuration examples.

Back to top

Data Definition Basics

Data definitions are very similar to report and process definitions.
 


     

In Logi Studio, they're organized beneath the Data folder in the Application panel, as shown above.


     

In the file system, they're stored in the _Data folder, which is in the _Definitions folder along with the _Processes and _Reports folders, as shown above.

You can test a Data definition in Studio using the Run tab at the bottom of the Workspace panel, shown above left. When you do, the actual JSON data generated will be displayed, as shown above right.

As with any other definition, you can use Debugger links to see the details of the definition execution.

Back to top

Creating a JSON Data Definition

A JSON Data definition uses a small subset of the standard Logi Info elements, most of them related to data retrieval and manipulation.
 

The first element that needs to be added in any JSON Data definition is a Json Data element, as shown above. It will run a datalayer, insert the results into a JSON JavaScript variable, and streams it. Its attributes are:
 

Attribute Description

ID

(Required) A unique element ID.

Json Var Name

(Required) When used in Data definitions, this should always be set to Exclude.

Json Human Readable

Specifies whether spaces and LFs are used to format the output JSON data, for easier debugging.

Json Output

When used in Data definitions, this should always be blank, or Inline.

Json Style

This attribute specifies the format of the data output; either as RowsToObjects,RowsToValueArrays, or as ColumnsToPropertyArrays. See the discussion below with output examples. Default: RowsToObjects

Security Right ID

Controls access to this element when using Logi Security. Provide the ID of a Right defined in the application's _Settings definition and only users that have a Role referenced in the Right will be able to use the data. Multiple Right IDs, separated by commas, may be entered.


 

Next, we add a datalayer beneath the Json Data element. In the example above, we've used DataLayer.Static to make it easy to see the data. And we're done. You can, of course, have more complex data arrangements, using any of the usual datalayer types, filters, JOINs, and other elements to retrieve and manipulate the data set.
 

Using Different Json Styles

The Json Data element can format its data in three different ways, using its Json Style attribute:
 

{ "data": [{"CategoryID" : "1", "sumFreight" : "500"}, {"CategoryID" : "2", "sumFreight" : "521"}, {"CategoryID" : "3", "sumFreight" : "600"}, {"CategoryID" : "4", "sumFreight" : "750"}, {"CategoryID" : "5", "sumFreight" : "900"}, {"CategoryID" : "6", "sumFreight" : "902"}] }

If Json Style is left blank or set to RowsToObjects, the data from our example will be formatted as shown above. The datalayer rows are serialized into an array of objects, where each object represents a data row and the objects have a property for each column.
 

{ "data": { "CategoryID" : ["1", "2", "3", "4", "5", "6"], "sumFreight" : ["500", "521", "600", "750", "900", "902"] } }

If Json Style is set to ColumnsToPropertyArrays, the data from our example will be formatted as shown above. The datalayer is serialized into a single object, where each column is a property with all the row values contained in an array.
 

{ "data": [["1", "500"], ["2", "521"], ["3", "600"], ["4", "750"], ["5", "900"], ["6", "902"]] }

Or, finally, if it's set to RowsToValueArrays, the data will be formatted as shown above. This serializes the data into a single array with a child array for each row in the data. Each value in the array represents a column in the data.

You need to select the format that works with the client applications that will consume the data.

Back to top

Creating an XML Data Definition

An XML Data definition uses a small subset of the standard Logi Info elements, most of them related to data retrieval and manipulation.
 

The first element that needs to be added in any XML Data definition is an XML Data element. It runs a datalayer, inserts the results into an XML document, and streams it. Its optional attributes are:
 

Attribute Description

Attributes as Elements

Specifies the format of the data values. The values are normally expressed as attributes in XML, but may be represented instead as elements with text nodes. When this attribute is set to True, values are contained in elements. For example:

If False (the default) is specified, the output will look like:

<Root>
   <Order OrderID="12345" Freight="1.12" />
<Root>

If True is specified, the output will look like:

<Root>
  <Order>
    <OrderID>12345</ID
    <Freight>1.12</Freight>
  </Order>
<Root>

Data Row Element Name

Specifies the name for XML elements which represent each of the data rows. The default is the Xml Data element's ID attribute.

Document Element Name

Specifies the name of the output XML's root element. The default is the Xml Data element's ID attribute.

ID

A unique element ID.


Back to top

Retrieving Data

Retrieving the Logi data stream is extremely easy: simply use a URL in this format:

https://yourWebServer/yourLogiApp/rdTemplate/rdData.aspx?rdData=yourDataDefinition

In the following sections, you'll see examples of data retrieval, from within several Logi applications. We'll also see how additional Query String parameters in the URL can be used to dynamically condition the data.

Back to top

Example: Getting Data for a Logi Application

Here's a very simple example of a Logi application that uses the data from the "Create a Data Definition" section above. The Json Style is blank (RowsToObjects) in that example.

In the report definition above, Data Table and DataLayer.Json File elements have been added. The datalayer's Json File attribute has been set to:

https://localhost/v12test/rdTemplate/rdData.aspx?rdData=myDataDef

A Flattener element has been used to flatten the JSON data array into rows and columns for use in the data table and an Auto Columns element handles our columns. For more information on these elements, see The Flattener and Auto Columns.
 

And, if we preview the report definition, the resulting output is shown above.

Back to top

Example: Using Parameters for Dynamic Data

This example is similar to the previous one, but introduces the ability to condition the data using Query String parameters.
 

A new data definition, shown above, includes both a Default Request Parameters element and a DataLayer.SQL element. The Default Request Params ensures that the SQL query, which uses a Request token, will always have a valid WHERE clause value.
 

We'll start our example report definition, shown above, by adding an Input Select List, with a datalayer and event handler, to allow the user to select an Employee ID. A Default Request Params element will ensure that the select list always has a default value and the event handler just refreshes the report (and updates the select list Request variable) when a new Employee ID selection is made.
 

We'll finish our report definition with the same set of elements we used previously: Data Table, DataLayer.Json File, Flattener, and Auto Columns. The datalayer's Json File attribute is set to:

https://localhost/v12test/rdTemplate/rdData.aspx?rdData=myDataDefSQL&inpEmployeeID=@Request.empID~

Note the use of an extra Query String parameter, with a value set from a Request token.
 

And the resulting report looks like this when previewed. Changing the Employee ID selection causes the data to refresh.

Back to top

Example: Using 3rd-Party APIs

Now let's look at a somewhat more complicated example that uses 3rd-party APIs (JQuery and Google) to draw three visualizations, using data from two Data definitions. The Data definitions are very similar, except one has more data points.
 

The Data definitions shown above are much like those we've seen earlier, except for two differences. The Json Data element's Json Style attribute is set to RowsToValueArrays and two Json Column elements are used.

By default, the Json Data element generates JSON data with the same column names as those output by the datalayer and all the JSON data types are strings. The Json Column element allows you to specify which columns will be included in the data, their variables names, and their data types. The Data Column attribute is the column name in the datalayer, the ID is column name in the JSON data, and the Data Type can be Number, String, or Date.
 

In our report definition, shown above, we've added two Include Script File elements to include the scripting libraries (one local, one external) we want to use. Empty Division elements, with real <DIV> tag output, are provided as the containers of the charts and data table we'll draw.

Finally, an Include Script element contains our JavaScript, which looks like this:
 

// load the Visualization API and the piechart package
google.load('visualization', '1', {'packages':['corechart']});
google.load("visualization", "1", {packages:["table"]});
 
// set a callback to run when the Google Visualization API is loaded
google.setOnLoadCallback(drawVisuals);
      
function drawVisuals() {
 
    // get data from the first data definition
    var jsonData = $.ajax({
        url: "http://localhost/v12test/rdTemplate/rdData.aspx?rdData=GoogleChartLine",
        dataType:"json",
        async: false
    }).responseJSON;
          
    // create a table of the first data set
    var data = new google.visualization.DataTable();
    data.addColumn('number', 'Category ID');
    data.addColumn('number', 'Freight Total');
    
    // apply the data
    data.addRows(jsonData.data);
        
    // get data from a second data definition
    var jsonData2 = $.ajax({
        url: "http://localhost/v12test/rdTemplate/rdData.aspx?rdData=GoogleChartPie",
        dataType:"json",
        async: false
    }).responseJSON;
          
    // create a table of the second data set
    var data2 = new google.visualization.DataTable();
    data2.addColumn('string', 'Category ID');
    data2.addColumn('number', 'Freight Total');
    data2.addRows(jsonData2.data);
    
    // instantiate and draw the data table, with some options
    var table = new google.visualization.Table(document.getElementById('divTable'));
    table.draw(data, {showRowNumber: false});
 
    // instantiate and draw the line chart, using the same data as the table
    var lineChart = new google.visualization.LineChart(document.getElementById('divLineChart'));
    lineChart.draw(data, {width: 600, legend: 'bottom'});
 
    // instantiate and draw the pie chart, with some options
    var pieChart = new google.visualization.PieChart(document.getElementById('divPieChart'));
    pieChart.draw(data2, {title: 'Another Fine Pie Chart', width: 400, height: 240, is3D: true});
}

The example shows you how to use the Data definition URL in code.
 

And the resulting output looks like the image shown above.

Though we've shown you these examples within Logi applications for convenience, you can use the same techniques with non-Logi applications or with HTML page data consumers. Just issue the URL for the Data definition to get the JSON data stream. And, of course, there are other techniques that can be used to retrieve and use the data.

Back to top