Scripting in Reporting

Scripting in the Report Module

The Report Module allows you to use scripting in several ways to extend the existing functionality. You can use some or all of these to extend the flexibility of Ignition's Report module. If the existing builders aren't enough, Ignition offers scripting for you to create exactly the functionality you need.

  • Data Sources: There is a Script Data Source type that allows you to create your data set in any way you like. You can alter other Data Sources, combine results, do complex calculations and more.

  • Scheduling: There is a Run Script action in the Report Scheduling system. If the existing print/email/save/FTP Actions aren't flexible enough, create a script to do exactly what you want with a generated report.

  • Scripting Functions: The Report Module adds additional functions to the list of system.* functions available throughout Ignition. You can use these functions to execute and/or distribute reports on demand.

  • Editing Charts: The Chart components in the Report Module are completely customizable.

On this page ...

Script Data Source

The Script data source allows you to add additional data into a report. Script data sources are able to reference data keys from other data sources. This allows you to modify keys from one data source, and return a new altered data source.

Alter Dataset Example

Say we have a query data source named "Area Data" which contains four columns: month, north_area, south_area, and t_stamp. If we need to build a new data source without the t_stamp column we can use the following code:

Script data source
#build a header and initialize a pydataset
header = ['month', 'north_area', 'south_area']
filteredDataset = []
#get the results from the Area Data data source
rawDataset = data['Area Data'].getCoreResults()
#build the new pydataset out of only some of the Area Data's data keys
for row in range(rawDataset.rowCount):
valCategory = rawDataset.getValueAt(row,'month')
valNorthArea = rawDataset.getValueAt(row,'north_area')
valSouthArea = rawDataset.getValueAt(row,'south_area')
filteredDataset.append([valCategory,valNorthArea,valSouthArea])
#convert the pydataset to a standard dataset
filteredDataset = system.dataset.toDataSet(header, filteredDataset)
#create a new data source with the filtered results
data['updated Area Data'] = filteredDataset

images/download/attachments/6035796/script_data_source.PNG

The above code would create a new data source in the Design panel named 'updated Area Data'. Note that .getCoreResults() is only applicable when the raw data source is a query. If 'Area Data' in the example above was a static CSV then you could get the data into a 'new data source' with the following:

Static CSV example
data['new data source'] = data['Area Data']

What if our 'Area Data' query has a nested query called 'Area Details' that we would like to manipulate in a script?

Script data source for nested query
nested = data['Area Data'].getNestedQueryResults() # Gets results from our parent query
subQuery = nested['Area Details'] #Gets the subquery we want -- there can be more than one
header = ['productName', 'cost', 'triple']
alteredDataset = []
for child in subQuery:
children = child.getCoreResults() # children is a dataset
for row in range(children.rowCount):
valProductName = children.getValueAt(row,'productName')
valCost = children.getValueAt(row,'cost')
valTimesThree = None
if valCost != None:
valTimesThree = 3 * valCost
alteredDataset.append([valProductName,valCost,valTimesThree])
 
#convert the pydataset to a standard dataset
alteredDataset = system.dataset.toDataSet(header, alteredDataset)
 
#create a new data source with the altered results
data['Updated Area Details'] = alteredDataset

Scheduling Action

The Run Script action is a scripting event that executes based on the schedule. This action does not inherently email, save, or otherwise distribute a report unless you do so in the script. However you can easily use executeAndDistribute() to send out the report.

Run Script Example

The following would insert a copy of the report into a database table

handleFinishedReport code
# the handleFinishedReport function provides reportName and reportBytes for us
 
# save a copy of the report in the database
query = "INSERT INTO report_log (name, data) VALUES (?,?)"
system.db.runPrepUpdate(query, [reportName,reportBytes])

System Functions

The Reporting Module provides convenient scripting functions in system.reporting section that enable report generation from scripting. These reports can be generated in teh Client scope, or in any Gateway scoped scripts. It is useful to generate a report in the Gateway scope because you can then email or save it without ever opening a client.

Execute Report

Will immediately execute a report on use and return a byte[] array of the results. See executeReport() in the appendix.

executeReport
# sample:
# system.report.executeReport(path, [project], [parameters], [fileType]) 
 
# execute the report
reportName = "MyReport"
reportBytes = system.report.executeReport(reportName)
# save a copy of the report in the database
query = "INSERT INTO report_log (name, data) VALUES (?,?)"
system.db.runPrepUpdate(query, [reportName,reportBytes])

Execute and Distribute

Will generate a report and distribute it by the configured Report Schedule Actions. See executeAndDistribute() in the appendix.

executeAndDistribute
# sample:
# system.report.executeAndDistribute(path, project, [parameters], action, [actionSettings])
 
# create and distribute (save) the report
system.report.executeAndDistribute(path='MyReport', project='my_project',action='save', actionSettings={'path':'C:\\Saved_Reports_Folder','fileName':'SavedReport.png','format':''png'})

Get Report Dataset

This function will return a dataset with the names and paths of all reports for a given project.

getReportNamesAsDataset
# sample:
# system.report.getReportNamesAsDataset(project)
 
# get a dataset
existingReports = system.report.getReportNamesAsDataset('my_project')

Get Report List

This function will return a list with the paths of all reports for a given project.

getReportNamesAsList
# sample:
# system.report.getReportNamesAsList(project)
 
# get a dataset
existingReports = system.report.getReportNamesAsList('my_project')

Editing Charts

The most common configuration options for charts are found in the properties panel, but almost every part of a chart can be configured through scripting.

To turn on configuration scripting in a chart, select the chart, scroll to the bottom of the Chart Options tab, enable scripting and click on Edit Script.

Change Legend Font Example

Say we want to change the font used in a charts labels. We can use the following code:

Configure Chart
def configureChart(chart):
# This configures the legend on a report chart to use a large, bold, monospaced font
from java.awt import Font
 
legend = chart.getLegend() # http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html
font = Font(Font.MONOSPACED, Font.BOLD, 48) # https://docs.oracle.com/javase/7/docs/api/java/awt/Font.html
legend.setItemFont(font) # http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/title/LegendTitle.html

The above code would change the font used in the chart's legend to a 48 point bold monospaced font. The comments give links to the APIs used in each line of the code.

Similar Topics ...