Reports Schedules: AddReportScheduleAdds a recurring Report Schedule

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>

Recurrence

There are five types of recurring schedules, and depending on the recurrence type chosen the parameters used will be different. The five types are; daily, weekly, monthly, calendar, and once.

daily
This schedule will run on all the days specified with the RecurWeekDays parameter.
The RecurWeekDays parameter is a string of 7 characters which are all either 1 (one) or 0 (zero).
The this recurrence type, the RecurEvery is always 1 (one).
Examples:
  • Weekdays is 0111110
  • Weekends is 1000001
  • Monday, Wednesday and Friday is 0101010
  • Just Friday is 0000010
Daily reports only run for a single day, so if you specify the report to run Fridays, then only data from that Friday will be returned, not the previous Friday to the current Friday.
weekly
This type of schedule will run once every RecurEvery number of weeks on the specified RecurWeekday. The RecurWeekday is a number between 1 and 7; Sunday is the first day of the week.
If the RecurWeekday lower than 1 is specified, the value will default to 1.
If the RecurWeekday higher than 7 is specified, the value will default to 7.
monthly
This type of schedule will run once every RecurEvery number of months on the specified RecurDate. The RecurDate. is a number between 1 and 31.
To run a report on the last day of the month, use the RecurDate of 31. Months which do not have a 31st, 30th, or 29th will have their report run on the last day of the month.
If the RecurDate lower than 1 is specified, the value will default to 1.
If the RecurDate higher than 31 is specified, the value will default to 31.
calendar
This type of schedule will run once every RecurEvery number of months on the specified RecurWeekday of the RecurWeekNumber. The RecurWeekday is a number between 1 and 7; Sunday is the first day of the week. The RecurWeekNumber is a number between -5 and 5.
If the RecurWeekday lower than 1 is specified, the value will default to 1.
If the RecurWeekday higher than 7 is specified, the value will default to 7.
If the RecurWeekNumber lower than -5 is specified, the value will default to -5.
If the RecurWeekNumber is specified as 0, the value will default to 1.
If the RecurWeekNumber higher than 5 is specified, the value will default to 5.
Examples:
  • RecurWeekday = 1, and a RecurWeekNumber = 1 means the first Sunday of the month.
  • RecurWeekday = 6, and a RecurWeekNumber = 4 means the fouth Friday of the month.
  • RecurWeekday = 7, and a RecurWeekNumber = -1 means the last Saturday of the month.
  • RecurWeekday = 4, and a RecurWeekNumber = -2 means the second last Wednesday of the month.
once
This schedule runs once after the RecurEnd date has passed.

Example of Returned Data

<AddReportSchedule Success="?" Message="" ScheduleID="#" />

Test Method

ParameterValueTypeUsage
NamestringThe name for this Reucrring Report Schedule
AccountIDint32Unique account identifier
TimezoneIDint32Unique time zone identifier
IconIDint32Unique icon identifier
Enabledboolean 
NotifybooleanShould notifications be sent when this report is run as per schedule
NotifyFormatstringIf notifications are enabled, the report can be attached as:
  • csv
  • xml
Notesstring 
ReportTypeIDbyteIdentifier for the type of report
TargetsXmlstringSee Usage Notes.
ParametersXmlstringSee Usage Notes.
FiltersXmlstringSee Usage Notes.
RecurTypestringSee Usage Notes.
The type of recurrence for this schedule
RecurEverybyteSee Usage Notes.
Interval
RecurStartdatetimeSee Usage Notes.
RecurEnddatetimeSee Usage Notes.
Can be null if schedule should always run
RecurDatebyteSee Usage Notes.
Day of the month. Can be null depending on recurrence type
RecurWeekdaybyteSee Usage Notes.
Day of the week. Can be null depending on recurrence type
RecurWeekNumberbyteSee Usage Notes.
Week of the month. Can be negative to choose last week of the month. Can be null depending on recurrence type
RecurWeekDaysstringSee Usage Notes.
Days on which to run a weekly schedule. Can be null depending on recurrence type