Cloud Reporting User Guide

Source: This article refers to Cloud Reporting User Guide

Introduction

Coresystems Reporting allows you to design and build reports for your Coresystems account. You can get a list of service calls created in the last 30 days in a nice PDF form.

You can generate any of the embedded reports using any of the client applications or by using the Coresystems API directly. We also encourage you to create your own custom reports using Jaspersoft Studio and Coresystems Report Designer.


Definitions

Report Design A report design represents some parts of the final report. It defines what data will be included in the report and how that data will be arranged.
Report Template A set of artifacts used to produce the final report. Report templates contain one or more report designs, style files, translation files and images.
Report A document generated based on a report template, using the data from your account.

Prerequisites

Before proceeding with this user guide you should have a good understanding of JasperReports. We recommend reading JasperReports Tutorial, which covers most of the basics. Basic knowledge of Coresystems API is also needed.

You can also check some videos with tutorials.


Building Reports

Reports can be built from the client applications or by directly calling the Coresystems API.


Building Reports with Client Applications

You can use any of the Coresystems client applications to build a report of your choice. If at least one report template is defined for a given object type, the Build Report button will be displayed. Some report templates define parameters which can be used to define the data or the final look of the report.


Building Reports using the API

The Coresystems API delivers a set of web services for building reports. A report can be built out of an existing report template only.

HTTP URL

POST https://host[:port]/api/reporting/v1/build

HTTP Headers

Property Value
Content-Type Defines in which format the parameters will be send. Either ‘application/json’ or ‘multipart/form-data’.

HTTP Body (application/json)

{ "reportTemplate": string, // the cloud ID (non-embedded templates) or the name of the report (embedded templates) "reportLanguage": string, // language of the report "reportParameters": { // report parameters passed to the reporting engine; can be used to specify the checklist instance or to pass some values to queries inside the report definition; this object must comply with the json schema stored in the parameters schema field string: object, ... } }

HTTP Body (multipart/form-data)

reportTemplate=String&reportLanguage=String&reportParameters.key1=String&reportParameters.key2=String

Example (application/json)

{ "reportTemplate": "sales", "reportLanguage": "en", "reportParameters": { "objectId": "01a143bc5d8a49de8e26cc8deec34ad8", "objectType": "SALESORDER", "showPrices": true } }

Example (multipart/form-data)

reportTemplate=sales&reportLanguage=en&reportParameters.objectId=01a143bc5d8a49de8e26cc8deec34ad8&objectType=SALESORDER&showPrices=true

Embedded Report Templates

Every Coresystems account comes with a set of embedded report templates covering the most common use cases. Currently those templates can’t be modified or deleted by users.

Embedded report templates can be modified by the Coresystems support team only.

Name Object Types Description
checklist Checklist Standard checklist reports combining information for a given checklist instance and referenced checklist template
sales Sales Order, Sales Quotation Standard sales document report
serviceCall Service Call Standard service call report

Creating Report Templates

Report templates contain report designs, style files, translation files and images. All artifacts can be created manually or mastered using Jaspersoft Studio.

Jaspersoft Studio is a free, open source, eclipse-based report designer. Report Designer is a free plugin for Jaspersoft Studio which adds support for Coresystems Reporting Together they deliver the most simple way of creating report templates.

In Jaspersoft Studio you create report designs, choose data sources and define the data using queries. The data source can represent any data, but most often it is a relational database. In Coresystems you never have direct access to the underlying database (security and permission concerns). Thus the data access has to be defined on top of coresystems API.


Report Parameters

Report parameters are useful for passing data to the report engine during the build phase. A report can have zero or more parameters. You can define them in the Outline window when using the Design view.



Alternatively, you can use the Source view. Parameter declaration is as simple as follows:

<parameter name="parameter1" class="java.lang.String"/>

Depending on the type of parameter, Coresystems client applications may ask the user for a value. Currently, Coresystems Reporting supports the following classes of parameters:

  • java.lang.Boolean
  • java.util.Date
  • java.lang.Double
  • java.lang.Float
  • java.lang.Integer
  • java.lang.String

Report Query String (CoreSQL)

The CoreSQL queries are similar to Coresystems API calls. They define what data needs to be retrieved from your Coresystems account. You can define only one query string per report design. You can use subreports to group different kinds of data.

Imagine a URL to retrieve a checklist instance with a given ID using the Coresystems API call:

https://eu1.dc.Coresystems.com/api/data/v4/ChecklistInstance?query=id="34a88076d28b4de99a2dcf68c029193f"&dtos=ChecklistInstance.12

A CoreSQL query doing the same thing might look like this:

ChecklistInstance ? query = id = "34a88076d28b4de99a2dcf68c029193f" & dtos = ChecklistInstance.12

This CoreSQL query omits all server and connection information as well as credentials from the web service URL. For more examples and documentation, please refer to Coresystems API.

Some query parameter values are only known during the build process. You can use report parameters to parametrize your queries.

ChecklistInstance ? query = id = $P{checklist.id} & dtos = ChecklistInstance.12

Keep in mind that you don’t have to worry about quotation marks. Just make sure to choose the right class for your parameter.


Report Fields

Report fields are elements which represent the mapping of data between the data source and the report template. Fields can be combined in the report expressions to obtain the desired output. When declaring report fields, the data source should supply data corresponding to all the fields defined in the report template.

A report design can contain zero or more fields. You can define them in the Outline window when using the Design view.



Alternatively, you can use the Source view. Field declaration is done as below:

<field name="field1" class="java.lang.String"/>

Report Preview

Using the preview feature in Jaspersoft Studio you can check what the final report might look like. You need to install the Coresystems Report Designer plugin to be able to see data from your account.

  • Make sure that you have the latest version of Jaspersoft Studio installed. You can download it from here. The currently supported version is 6.0.4 or higher.
  • Create a new data adapter for CoreSQL. It must be of type Coresystems Cloud Connection. You are free to use any name.
  • You are done. Go to the preview tab, choose the correct data adapter and hit Run.

Fonts

You want your report to look exactly the same on every device or on paper. Cloud Reporting supports one font and one font only - DejaVu. We made sure that we you can use it in many ways.

Font Name Normal Bold Italic Bold Italic
Sans Serif DejaVu Sans DejaVu Sans DejaVu Sans DejaVu Sans
Monospace DejaVu Sans Mono DejaVu Sans Mono DejaVu Sans Mono DejaVu Sans Mono
Serif DejaVu Serif DejaVu Serif DejaVu Serif DejaVu Serif

If your report defines a different font family, DejaVu will be used anyway.


Functions

For most common situations expressions represent the perfect tool for acquiring and processing dynamic data. Jaspersoft Studio defines a set of functions for most common operations on data, e.g. get current date. Report Designer delivers new functions for most common operations on Cloud objects.

Report Designer functions are grouped in Coresystems category.

Function Description Example
Object fieldValue(String objectType, int objectVersion, String objectId, String fieldName) Gets the value of the field with the given name
fieldValue(BusinessPartner, 10, $F{businessPartner.id}, code)
Map fieldValues(String objectType, int objectVersion, String objectId) Gets the field name to value mapping for the given object
fieldValues(BusinessPartner, 10, $F{businessPartner.id})
Object udfValue(String objectType, int objectVersion, String objectId, String udfName) Gets the value of the UDF with the given name
udfValue(BusinessPartner, 10, $F{businessPartner.id}, COR_CLOUD_IGNORE)
Map udfValues(String objectType, int objectVersion, String objectId) Gets the UDF name to value mapping for the given object
udfValues(BusinessPartner, 10, $F{businessPartner.id})
Object fieldValueInlined(String objectType, int objectVersion, String objectId, String fieldName, int lineIndex, String inlinedFieldName) Gets the value of the inlined field with the given name
fieldValueInlined(SalesOrder,17,$F{SalesOrder.id},MYNEWFIELD,0,salesOrderItems )
Map fieldValuesInlined(String objectType, int objectVersion, String objectId, String fieldName, int lineIndex) Gets the field name to field value mappings for the given inlined object.
fieldValuesInlined(SalesOrder,17,$F{SalesOrder.id},MYNEWFIELD,0)
Object udfValueInlined(…)
udfValueInlined()
Object udfText(String udfName, String udfValue) Gets the Text of the UDF with the given name for the given value
 udfText(NEWSELECTION1,udfValue(Activity,10,$F{a.id},NEWSELECTION1))

Report Variables

The following report variables are supported:

Variable Name Type Description
REPORT_EMPTY Boolean Used by the cloud to determine if the built report is empty or not. If the report is empty, then there is no need to send it to customers.
REPORT_NAME String The name of the file that contains the report. The cloud might use this value to create an attachment containing the report.

Report Variable Example

<variable name="REPORT_EMPTY" class="java.lang.Boolean">
   <variableExpression><![CDATA[true]]></variableExpression>
</variable>
<variable name="REPORT_NAME" class="java.lang.String">
   <variableExpression><![CDATA["name"]]></variableExpression>
</variable>

Example Use Case

Inside the JasperSoft report template you can define a new variable in the report that will determine the name of the report used when sending the report via email or attaching the file to an object from within the mobile application. This can be acheived by completing the following:

  1. Download the report withing JasperSoft from your company
  2. Create a new variable in the report with name “REPORT_NAME”
  3. Add in the expression the values or fields you want to use to define the report name, e.g. $F{template.name} + "_" + NOW( )
  4. Upload the report again to your company
  5. In the mobile application (e.g. iOS App) synch to get the latest report template and use this to send the checklist via email or attach it to the linked object.
  6. It will now use the new name defined in the report




Subreports

A subreport is a report included inside another report. This allows the creation of very complex layouts with different portions of a single document filled using different data sources and reports.

You can include a subreport in the main report just as any other element.

<subreport>
  <reportelement x="0" y="0" width="200" height="200">
	<subreportexpression>![CDATA["subreport.jasper"]]</subreportexpression>
  </reportelement>
</subreport>

Subreport can accept parameters. They can also return some values.


Problems and Log Files

An empty report usually means that an incorrect data adapter has been selected.

The error message should give you enough information in case of rendering issues. For more information, you can check the Error Log view.


Report Template Bundle

Report and subreport designs are defined in XML files with the \\*.jrxml extension. The main report design must be named report.jrxml. There are no naming conventions for subreports, although the report_[objectType].jrxml naming schema is encouraged.

Styles are defined in \\*.jrtx files. If you have more than one report design, you can define the styles in the style file and reference them in every design. Usually a single styles.jrtx file is enough.

Translation files are defined using the Java resource bundle concept. The translation files are optional, but they have to be named like this: translations[_language[_country]].properties.

All images which are included in the bundle and referenced in the report designs will be included in the report. Any type of image (PNG, JPG, etc.) should work just fine.

The smallest bundle possible contains:

report.jrxml

A report template bundle with subreports, translations and images contains more files:

report.jrxml
report_address.jrxml
translations_en.properties
translations_de.properties
image.png

When the files are ready, create a zip archive and upload it to your Coresystems account.

zip [name].zip \\*.jrxml \\*.jrtx \\*.properties \\*.png

The bundle must not contain any directories and all the files need to be placed directly in the bundle. Any directories and their content will be ignored.


Report Template Upload

Report templates can be uploaded to Coresystems Cloud by either creating a new report template object, or by updating an existing one. In both cases, the archive file will be scanned to detect supported languages and parameters.

In Coresystems, a report template is represented as an meta-data object and an attachment with the content.

Embedded report templates can’t be updated or deleted.

Uploading Report Template

The easiest way to upload a report template is with the Jaspersoft Plugin. View the following video tutorial for more information.


Upload with API

The upload using the API requires two web service calls. One for the report template object, and second one for the attachment. Please refer to Coresystems API for more details.


Set “With Checklists” Parameter as Default for Online Reports

This setting is currently available in iOS only.

The following example shows how the With Checklists parameter can be set for Online Reports.

<parameter name="withChecklists" class="java.lang.Boolean">
		<property name="default" value="true"/>
		<property name="title" value="With Checklists"/>
		<property name="remember" value="false"/>
		<defaultValueExpression><![CDATA[true]]></defaultValueExpression>
	</parameter>
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.