Description of reports

Introduction

A control panel has a built-in mechanism for generating various reports.

This article describes reports, their metadata, and output data.

Example of report description

<metadata name="journal.stat" type="report" level="30" firstrun="no">
 	 <toolbar>
		 <toolbtn func="journal" type="back" img="t-back" name="back"/>
	 </toolbar>
	 <form>
		 <period/>
	 </form>
	 <band name="function">
		 <diagram name="func" label="funcname" data="percentage" type="pie"/>
		 <col name="funcname" type="data" total="count" link="yes"/>
		 <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
		 <band name="user">
			 <diagram name="user" label="username" type="histogram">
				 <line data="percentage"/>
			 </diagram>
			 <col name="username" type="data" total="count"/>
			 <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
		 </band>
	 </band>
 </metadata>

Report

Create a child element in metadata for describing your report.

name - report name, the key attribute.

 type  - a mandatory parameter that always must be set to 'report'.

firstrun  - a report will not be generated upon the first start. This option can be used if it takes a long time to generate a report, and you first need to choose parameters your report will be based on.

Test description to report

<msg name="report_info">Подробный отчет о расходах</msg>

To add a test description for your report, add a message named report_info.

Report form (the form element)

This metadata element describes form fields.

Description of report data structure (the band element)

Structure of data and output data interface are described with the band element as follows:

 <band>
   <query/>
   <action/>
   <diagram/>
   <col/>
   [[<band>]]
 </band>

The band elements can be included into band of a higher level. One of upper-level band may not contain the query or action elements if the program already has a function corresponding to the report's name. All included bandelements must have either action or query element. One band cannot contain both action and query.

the name attribute  - band name, a key attribute.

the hidden attribute   - if "yes" is specified, the table with data will be hidden.

Data table description - add a message named table_[BANDNAME] into the messages section of the XML-file

Diagram description - add a message named diagram_[DIAGRAMNAME] into the messages section of the XML-file

Report description - add a message named report_info into the messages section of the XML-file

The col element

Indicates a table column in your report. If upper-level the metadata element (band) contains only one column, its data will be used as a heading for child data.

name - column name, a key attribute.

type - column type, if "data", the column will be shown in a data table.

link- if "yes", the column will contain a link (anchor) to child data elements.

sort  - specifies how to sort out data in the column. Its value can be either alpha (sort alphabetically; by default) or digit (sort in ascending order)

sorted - if sorted="yes", the table will be sorted by this column by default. sorted="desc" - sorting in descending order.

total- specifies total sums shown at the bottom of your table. Its value can be either count (number of rows with data in that column) or sum (total sum from raws in that column (for numeric columns))

nestedreport- adds a link to another report (function) that will be specified in the attribute's value (the elid parameters will be also sent - value in the column, col - column name).

The query element

Contains a SQL-query that displays information. You should use aliases for columns in the query to associate them with the col element. For example, "s.name as name" will be assigned to the column "<col name="name" ...". In a SQL-query you can use parameters from a report, and upper-level band values, if query is included into band. Parameters' names should be put into double square brackets. Example:

  .....
  <form>
    <field name="testinput">
      <input name="testinput" type="text"/>
    </field>
  </form>
  <band name="project">
    <query>select id , name from project where account = [[account]]</query>
    <col name="name" type="data"/>
      <band name="testdata">
        <query>
          select .... from ... where param=[[testinput]] and project=[[project.id]]
        </query>
  .....

When generating reports with queries to a database, you should specify a source of data for such queries. Use the isp_api::SetReportSource() function to specify the source.

The action element

Contains a query to any function. This function should provide report data according to its description.

  .....
  <band name="testdata">
    <action>
      testaction
    </action>
  .....

The diagram element

Describes a diagram for the selected band in your report. Diagrams can be included in any band. name is the key attribute. 

Description of report output data (the reportdata element)

The report data are generated according to the report structure (the band element).

The root of your report should contain the <reportdata> element with report data. Data of a specific data element (band) should locate in the element, which name corresponds to the "name" attribute of the data description element which they correspond to. Each row of the report is штсдгвув into the elem element and indicates a number of data included into elements which name corresponds to the "name" attribute of the corresponding report column. Data from included elements should locate within the same elem element, for which such data are considered child.

For example, we have the following report description in the metadata tag (example port is taken from COREmanager):

  <band name="function">
    <diagram name="func" label="funcname" data="percentage" type="pie"/>
    <col name="funcname" type="data" total="count" link="yes"/>
    <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
    <band name="user">
      <diagram name="user" label="username" type="histogram">
        <line data="percentage"/>
      </diagram>
      <col name="username" type="data" total="count"/>
      <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
    </band>
  </band>

Example of report data for a detailed description:

  <reportdata>
    <function>
      <elem>
        <funcname>mgr.edit</funcname>
        <percentage>100.00</percentage>
        <user>
          <elem>
            <username>root</username>
            <percentage>100.00</percentage>
          </elem>
        </user>
      </elem>
    </function>
  </reportdata>

The above example contains the element for describing upper-level data (function), there is only one data element for that element.

For the element describing second-level data (user), there is a data element corresponding to the second-level data description (band3).

The resulting XML will look like the following:

  <metadata name="journal.stat" type="report" level="30" firstrun="no" mgr="core">
    <band name="function">
      <diagram name="func" label="funcname" data="percentage" type="pie"/>
      <col name="funcname" type="data" total="count" link="yes"/>
      <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
      <band name="user">
        <diagram name="user" label="username" type="histogram">
          <line data="percentage"/>
        </diagram>
        <col name="username" type="data" total="count"/>
        <col name="percentage" type="data" sort="digit" sorted="desc" total="sum"/>
      </band>
    </band>
  </metadata>
  <reportdata>
    <function>
      <elem>
        <funcname>mgr.edit</funcname>
        <percentage>100.00</percentage>
        <user>
          <elem>
            <username>root</username>
            <percentage>100.00</percentage>
          </elem>
        </user>
      </elem>
    </function>
  </reportdata>