Reports: RunReportRuns a new Report and returns the results

See Also

Usage Notes

Targetting

Fleet Freedom reports use a targetting system so that multiple targets can be selected for a single report. Target types can be mixed so that you can target all or specific Accounts, Fleets and Devices simultaneously.

<!-- like this -->
<targets>
<account>
AccountID
</account>
<fleet>
FleetID
</fleet>
<device>
DeviceID
</device>
</targets>

When choosing a report type which has a TargetType of device, and the tagets node supplied contains account and fleet nodes, the Devices within those Accounts and Fleets are targetted.
This selection is not static, so if you move a Device from a targetted fleet to a non-targetted fleet, on the next run of this scheduled report that device will not be within the results.

If you wish to target a Fleet for the report, and you want to make sure a Device is specifically included (even if it is currently in the targetted Fleet), you can include both the fleet and device nodes.

Examples:
<!-- specific account -->
<targets>
<account>
1
</account>
</targets>
<!-- specific devices -->
<targets>
<device>
1
</device>
<device>
2
</device>
<device>
3
</device>
<device>
4
</device>
</targets>
<!-- multiple fleets -->
<targets>
<fleet>
1
</fleet>
<fleet>
2
</fleet>
<fleet>
365
</fleet>
</targets>
<!-- combinations -->
<targets>
<account>
1
</account>
<fleet>
365
</fleet>
<fleet>
376
</fleet>
<device>
1979
</device>
</targets>

You are able to group any of the node types together.

In order to have a target included in the results, your User must have Access to the target, or you must have the target Assigned to your User. This is done by granting access through the UpdateUserAccessAccounts and UpdateUserAssignedFleets methods.

Parameters

Depending on the type of report selected, different drill-down options are available. There are four types of drill-down parameters; Speed, Duration, Tolerance, and Time of Day.

<parameters>
<speed type="" kph="#" mph="#" />
<duration type="" hours="#" minutes="#" seconds="#" />
<tolerance type="" hours="#" minutes="#" seconds="#" />
<timeofday starting="HH:mm:ss.fff" ending="HH:mm:ss.fff" />
</parameters>

Depending on the type of report selected, multiple drill-down parameters can be specified.
Multiples parameters of a single type can also be specified, and in those cases the type attribute must be specified.
Please refer to APIReportTypesList for a list of report types and their accociated parameters.

<parameters>
<duration minutes="5" />
<daytime starting="09:00:00" ending="17:00:00" />
</parameters>
<parameters>
<tolerance type="moving" minutes="2" seconds="30" />
<tolerance type="nofix" hours="2" />
</parameters>
<parameters>
<speed type="max" kph="115" />
<speed type="street" kph="10" />
</parameters>
<parameters>
<speed type="max" kph="115" />
<duration seconds="300" />
</parameters>

Filtering

Filters are used to drill-down even further to include or exclude specific areas and locations.
There are five types of drill-down filters; Country, Province/State, Zone, Zone Colour, and Location. You can easily filter based on whole Accounts and/or Fleets of zones and/or locations as well.

The FiltersXml node can be specified as <include /> or <exclude />.
The <include /> node will filter the report so that only results that occured within the specified filter targets will be returned. The <exclude /> node will remove from the results any events that occured within the specified filter targets.

<includeORexclude>
<location>
LocationID
</location>
<zone>
ZoneID
</zone>
<fleet type="">
FleetID
</fleet>
<account type="">
AccountID
</account>
<zone colour="" color="" />
<province />
<state />
<country />
</includeORexclude>

Inclusive filtering will by design return far fewer results than exclusive filtering.
The province and state nodes are interchangable and are not affected by country. You can use the state node to filter on provinces in Canada, and you can use the province node to filter states in the United States. The node names are interchangable to make writing code easier.
The same is true of the colour/color attributes.

<exclude>
<zone>
1
</zone>
<zone>
2
</zone>
<location>
1
</location>
<location>
2
</location>
<location>
3
</location>
</exclude>
<inc1ude>
<zone colour="red" />
</inc1ude>
<inc1ude>
<province>
BC
</province>
<state>
AB
</state>
<country>
US
</country>
</inc1ude>
<exclude>
<account type="zones">
1
</account>
<account type="locations">
1
</account>
<account type="zones">
376
</account>
<fleet type="locations">
365
</fleet>
</exclude>

Returned Results

The ReturnData parameter allows you to specify which data is returned for the Report. Multiple flags can be used if you wish to return multiple types of data. If you specify a flag which is not valid for the report type, no results of that type are returned. The order of the flags is not important, and results will always be ordered (if specified) as Totals, Summary, Breakdown.

Valid flags are:

B
For "Breakdown", which represents the detailed list of all events used to calculate the report.
S
For "Summary", which represents the summary instances for the report. Summary instances are different from Totals in that individual instances are separated for review. As an example, for the Idling report, each instance of Idling is shown in the Summary including the duration of the instance.
T
For "Totals", which represents the totals per device. Totals differ from Summary in that the Totals represent the total cummulative values for each device. As an example, for the Idling report, the total duration of idling is summed for each device.
A
For "All", same as using "BST".

Not all report types contain every return data types. Some reports contain only Breadkown, some have Summary and Totals but no Breakdown. For assistance please contact support@trakitwireless.com.

Returned Formats

The FormatCode parameter allows you to specify format of the Report. The SOAP response will always be in XML, and the results will be contained withing the root node (document element) in the desired format.

Valid codes are:

csv
The inner text children of the root node (document element) will contain the CSV (comma separated values) formatted results. New line characters are preserved even if they do not appear to be when previewing results in a browser window.
xhtml
The first child node of the root node (document element) is an html element. The results are formatted as a normal XHTML document, however the DOCTYPE is missing and may need to be added after the response is processed.
xml
Raw XML is returned for the results.
Please note that the dates and times are listed as UTC instead of the Session User's preference, and all speeds and distances are in metric regardless of the Session User's preference.
xls
Microsoft Office 2003 provides a native XML format for Excel spreadsheets. The documentation for which can be found on the MSDN website.
Our response is missing a document declaration for Microsoft's native format which will need to be added by you; <?mso-application progid="Excel.Sheet"?>. The declaration comes after the XML declaration and before the Woorkbook element. When serving the file it should be given with the ContentType header of application/vnd.ms-excel. It's also important to add a &#10; between any HTML elements inside cell data; this is a workaround for older versions of Microsoft Office which do not support line-breaks properly.

For assistance please contact support@trakitwireless.com.

Example of Returned Data

<!-- csv -->
<RunReport Success="?" Message="" FormatCode="">
<!-- Failed to insert some or all of included XML -->
</RunReport>
<!-- xml -->
<RunReport Success="?" Message="" FormatCode="">
<Report Identifier="" UserID="#" UserName="" ScheduleID="#" ScheduleName="" GMTAdded="yyyy-MM-dd HH:mm:ss.fff" GMTCompleted="yyyy-MM-dd HH:mm:ss.fff" Archived="?" Name="" AccountID="#" Notes="">
<ReportType ID="#" Name="">
description
</ReportType>
<Parameters StartDate="yyyy-MM-dd HH:mm:ss.fff" EndDate="yyyy-MM-dd HH:mm:ss.fff">
<Parameter Name="" other="attributes" />
<Parameter Name="" other="attributes" />
<!-- etc -->
</Parameters>
<Targets>
<Raw>
<account>
#
</account>
<fleet>
#
</fleet>
<device>
#
</device>
<!-- etc -->
</Raw>
<Account ID="#" Name="" IconSrc="">
<Fleet ID="#" Name="" IconSrc="">
<Device ID="#" Name="" IconSrc="" />
<!-- etc -->
</Fleet>
</Account>
<!-- etc -->
</Targets>
<Filters Type="">
<Raw>
<account type="">
#
</account>
<fleet type="">
#
</fleet>
<zone color="" />
<zone>
#
</zone>
<location>
#
</location>
<!-- etc -->
</Raw>
<Account ID="#" Name="" IconSrc="">
<Fleet ID="#" Name="" IconSrc="">
<Zone ID="#" Name="" IconSrc="" />
<!-- etc -->
</Fleet>
</Account>
<!-- etc -->
<Country Code="" Name="">
<Province Code="" Name="" />
<State Code="" Name="" />
<!-- etc -->
</Country>
</Filters>
<Results TotalsRows="#" SummaryRows="#" BreakdownRows="#" />
</Report>
</RunReport>
<!-- xhtml -->
<RunReport Success="?" Message="" FormatCode="">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:svg="http://www.w3.org/2000/svg" xmlns:vml="urn:schemas-microsoft-com:vml">
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
<meta name="X-Identifier" content="" />
<meta name="X-User" content="#" />
<meta name="X-Report-Type" content="#" />
<meta name="X-Report-Schedule" content="#" />
<meta name="X-Account" content="#" />
<meta name="X-Report-Name" content="" />
<meta name="X-Report-Notes" content="" />
<meta name="X-Date-Run" content="yyyy-MM-dd HH:mm:ss.fff" />
<meta name="X-Date-Completed" content="yyyy-MM-dd HH:mm:ss.fff" />
<meta name="X-Date-Starting" content="yyyy-MM-dd HH:mm:ss.fff" />
<meta name="X-Date-Ending" content="yyyy-MM-dd HH:mm:ss.fff" />
<meta name="X-Param-[name]" content="additional parameter value" />
<!-- etc -->
<meta name="X-Results-Bounds" content="N# E# S# W#" />
<meta name="X-Size-[Totals|Summary|Breakdown]" content="#" />
<meta name="X-Filter-[Zones|Locations|Regions]" content="#" />
<title />
</head>
<body>
<div class="hi report [saved]">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info notes">
<h4>
Notes
</h4>
<p />
</div>
<div class="info parameters">
<h4>
Parameters
</h4>
<dl>
<dt>
Starting Date Range
</dt>
<dd>
yyyy-MM-dd HH:mm:ss.fff
</dd>
<dt>
Ending Date Range
</dt>
<dd>
yyyy-MM-dd HH:mm:ss.fff
</dd>
<dt>
additional parameter name
</dt>
<dd>
additional parameter value
</dd>
<!-- etc -->
</dl>
</div>
<div class="info filters">
<h4>
Filter Type: [None|Inclusive|Exclusive]
</h4>
<div class="account">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="grp">
<div class="fleet">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="grp">
<div class="location">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
</div>
<div class="zone">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
</div>
<!-- etc -->
</div>
</div>
<!-- etc -->
</div>
</div>
<div class="country">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info" />
<div class="grp">
<div class="province">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info">
Province
</div>
</div>
<div class="state">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info">
State
</div>
</div>
<!-- etc -->
</div>
</div>
<!-- etc -->
</div>
</div>
<table class="totals">
<caption>
<a herf="#toggle?totals">
<span class="hide">
Hide totals
</span>
<span class="show">
Show totals
</span>
</a>
<div>
# Rows
</div>
</caption>
<tbody>
<tr id="device#" class="odd">
<td class="index device">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info">
<span>
ADDITIONAL TOTAL NAME: ADDITIONAL TOTAL VALUE
</span>
<span>
ADDITIONAL TOTAL NAME: ADDITIONAL TOTAL VALUE
</span>
<!-- etc -->
</div>
</td>
<td class="chart">
<div class="bar" style="width:#%;">
TOTAL NAME: TOTAL VALUE
</div>
</td>
<td class="num">
#
</td>
</tr>
<tr id="device#" class="even">
<td class="index device">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info">
<span>
ADDITIONAL TOTAL NAME: ADDITIONAL TOTAL VALUE
</span>
<span>
ADDITIONAL TOTAL NAME: ADDITIONAL TOTAL VALUE
</span>
<!-- etc -->
</div>
</td>
<td class="chart">
<div class="bar" style="width:#%;">
TOTAL NAME: TOTAL VALUE
</div>
</td>
<td class="num">
#
</td>
</tr>
<!-- etc -->
</tbody>
</table>
<hr />
<div id="device#" class="hi device none">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info accflt">
ACCOUNT NAME/FLEET NAME
</div>
<div class="info results">
No Results
</div>
</div>
<hr />
<div id="device#" class="hi device results">
<div class="icon" style="background-image:url(/)" />
<h3 class="name" />
<div class="info accflt">
ACCOUNT NAME/FLEET NAME
</div>
<table class="summary">
<caption>
<a herf="#toggle?summary#">
<span class="hide">
Hide summary
</span>
<span class="show">
Show summary
</span>
</a>
<div>
# Rows
</div>
</caption>
<thead>
<tr>
<th class="index num" />
<th class="" />
<th class="" />
<!-- etc -->
</tr>
</thead>
<tfoot>
<tr>
<td class="index num" />
<td class="" />
<td class="" />
<!-- etc -->
</tr>
</tfoot>
<tbody>
<tr id="start#" class="[other classes] odd">
<td class="index num">
#
</td>
<td class="" />
<td class="" />
<!-- etc -->
</tr>
<tr id="start#" class="[other classes] even">
<td class="index num">
#
</td>
<td class="" />
<td class="" />
<!-- etc -->
</tr>
<!-- etc -->
</tbody>
</table>
<table class="breakdown hidden">
<caption>
<a herf="#toggle?breakdown#">
<span class="hide">
Hide detailed breakdown
</span>
<span class="show">
Show detailed breakdown
</span>
</a>
<div>
# Rows
</div>
</caption>
<thead>
<tr>
<th class="index num" />
<th class="" />
<th class="" />
<!-- etc -->
</tr>
</thead>
<tfoot>
<tr>
<td class="index num" />
<td class="" />
<td class="" />
<!-- etc -->
</tr>
</tfoot>
<tbody>
<tr id="event#" class="[inactive|normal|alarm|track|bait|maintenance] [located|stopped|idling|moving|speeding] [n|ne|e|se|s|sw|w|nw] [old] odd start#">
<td class="index num">
#
</td>
<td class="" />
<td class="" />
<!-- etc -->
</tr>
<tr id="event#" class="[inactive|normal|alarm|track|bait|maintenance] [located|stopped|idling|moving|speeding] [n|ne|e|se|s|sw|w|nw] [old] event start#">
<td class="index num">
#
</td>
<td class="" />
<td class="" />
<!-- etc -->
</tr>
<!-- etc -->
</tbody>
</table>
</div>
<!-- etc -->
</body>
</html>
</RunReport>
<!-- xls -->
<RunReport Success="?" Message="" FormatCode="">
<ss:Workbook xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:c="urn:schemas-microsoft-com:office:component:spreadsheet">
<o:DocumentProperties>
<o:Title>
[Report Name]
</o:Title>
<o:Created>
[User prefered Date/Time format]
</o:Created>
<o:Company>
[Account Name]
</o:Company>
<o:Version>
[3.#.#.#]
</o:Version>
</o:DocumentProperties>
<ss:Styles>
<ss:Style />
<!-- etc -->
</ss:Styles>
<!-- The first Worksheet node contains a list of all devices targetted by the report. Totals are also included in the first Worksheet node. -->
<ss:Worksheet ss:Name="Devices">
<ss:Table>
<ss:Column />
<!-- etc -->
<ss:Row ss:StyleID="Header" ss:Height="25">
<ss:Cell>
<ss:Data ss:Type="String">
Column Name
</ss:Data>
</ss:Cell>
<!-- etc -->
</ss:Row>
<ss:Row ss:AutoFitHeight="1">
<ss:Cell>
<ss:Data ss:Type="[String|Number|DateTime|Boolean]">
Column Name
</ss:Data>
</ss:Cell>
<!-- etc -->
</ss:Row>
</ss:Table>
</ss:Worksheet>
<!-- The Worksheet nodes with the ss:Name starting with Summary or Breakdown repeat for each device with results. -->
<ss:Worksheet ss:Name="Summary - [Device Name]">
<ss:Table>
<ss:Column />
<!-- etc -->
<ss:Row ss:StyleID="Header" ss:Height="25">
<ss:Cell>
<ss:Data ss:Type="String">
Column Name
</ss:Data>
</ss:Cell>
<!-- etc -->
</ss:Row>
<ss:Row ss:AutoFitHeight="1">
<ss:Cell>
<ss:Data ss:Type="[String|Number|DateTime|Boolean]">
Column Name
</ss:Data>
</ss:Cell>
<!-- etc -->
</ss:Row>
</ss:Table>
</ss:Worksheet>
<!-- etc -->
<ss:Worksheet ss:Name="Breakdown - [Device Name]">
<ss:Table>
<ss:Column />
<!-- etc -->
<ss:Row ss:StyleID="Header" ss:Height="25">
<ss:Cell>
<ss:Data ss:Type="String">
Column Name
</ss:Data>
</ss:Cell>
<!-- etc -->
</ss:Row>
<ss:Row ss:AutoFitHeight="1">
<ss:Cell>
<ss:Data ss:Type="[String|Number|DateTime|Boolean]">
Column Name
</ss:Data>
</ss:Cell>
<!-- etc -->
</ss:Row>
</ss:Table>
</ss:Worksheet>
<!-- etc -->
</ss:Workbook>
</RunReport>

Test Method

ParameterValueTypeUsage
ReportTypeIDbyteIdentifier for the type of report
TargetsXmlstringSee Usage Notes.
StartingGMTdatetimeThe starting date/time range for the report
EndingGMTdatetimeThe ending date/time range for the report
ParametersXmlstringSee Usage Notes.
FiltersXmlstringSee Usage Notes.
ArchivebooleanIf true, the report is archived for later review
AccountIDint32When archiving, the Account under which this report is listed must be specified. If null, it will default to the session User's account.
Namestring 
Notesstring 
ReturnDatastringSee Usage Notes.
A string to represent the types of data to return.
FormatCodestringThe format of the Report results. Possible values are: csv, xhtml, xls, xml