Skip to main content

Creating Custom Reports Based on the SPARQL Endpoint

Abstract

Creating Custom Reports Based on the SPARQL Endpoint

PoolParty offers the ability to easily generate reports. Choose from several default reports or create custom reports using SPARQL queries and the Velocity template engine.

Prerequisites for a Custom Report

  1. A SPARQL query for selecting the data.

  2. A Velocity template for formatting the query results.

  3. A report entry in the PoolParty configuration file SesameSetup.xml

1. SPARQL Query

First you need to write your query selecting the data for the report. You can test your query with the SPARQL endpoint of your project (the endpoint will also be used for the reports).

The query has to be a SELECT query in the syntax specified by the W3C.

You can use variables in your query by marking them with %%% before and after the variable name (e.g. %%%Language%%%)

In the next step you need to add your query to the SesameSetup.xml (located in the Configuration folder of the PoolParty installation):

  1. Look for the <namedQueries> node in the config/SesameSetup.xml

  2. Add a new <entry> node under the <namedQueries>node for your query (anywhere before or after an existing entry) :

    <entry>
     <key>{Your Query Name}</key>
     <value>
         <sparqlQueryParameterMap>
             <entry>
                  <key>{Variable Name}</key>
                  <value>{Default Value}</value>
             </entry>
         </sparqlQueryParameterMap>
         <sparqlQueryTemplate>
             {Your SPARQL Query}
         </sparqlQueryTemplate>
      </value>
</entry>

  3. Replace the following parts with your query details:

    1. Your Query Name - name of the query

    2. (The sparqlQueryParameterMap node is optional and only necessary if you use variables in your query)

      1. Variable Name (optional) - name of the variable used in the SPARQL query (The one marked with %%%Variable Name%%% in the query)

      2. Default Value (optional) - default value for the variable if no value is specified

    3. Your SPARQL Query - the SPARQL query for data selection

Necessary character replacements

Greater-than (>) and less-than (<) characters have to be XML-encoded:

&lt; and &gt;

Logical AND (&&) has to be converted to:

&amp;&amp;

Quotation marks have to be converted to:

&quot;

2. Velocity Template

For detailed information on how to write Velocity templates, please visit the Apache Velocity user guide .

Within the template you can access the following variables:

  • $bindings - A list of strings containing the binding names

  • $result - A list of the result "rows" of your query.

Check out the SPARQL Endpoint documentation for more information about the result structure and how to access the rows.

Put your template file in the following folder:

  • /opt/poolparty/data/resourceRoot (GNU/Linux)

  • C:\Users\Public\PoolParty\data\resourceRoot (Windows)

3. The Report Entry - Glueing It Together

With the <reports> entry in the SesameSetup.xml you are weaving together the query and the template and assigning a name for the report.

  1. Look for the <reports> node in the SesameSetup.xml

  2. Add a new <entry> node under the <report>node for your report (anywhere before or after an existing entry) :

    <entry>
     <key>Your Report Name</key>
     <value>
          <contentType>Content Type</contentType>
          <namedQuery>Your Query Name</namedQuery>
          <template>Template Filename</template>
     </value>
</entry>

  3. Replace the following parts with your report details:

    1. Your Report Name - name of the report as displayed in the report dialog

    2. Content Type - The content-type of the generated report (e.g. application/xml, text/plain, etc.)

    3. Your Query Name - name of the your SPARQL query as defined in the entry under namedQueries

    4. Template Filename - name of the template file in the velocity folder

After the next restart of the web application (the setup has to be refreshed), the report will be available from the Project -> Reports menu entry.

When you click on the "Generate Report" button a call to the SPARQL endpoint is made using the following pattern:

http.//<server>/PoolParty/SPARQLEndPoint/<project-id>?queryname=<queryname>&template=<template>&content-type=<content-type>&<variable>=<value>

This will produce the report.

In this section: