Object Lists

The OnTime SDK allows for the retrieval of lists of certain objects. Is also allows developers to search for particular objects and filter the aforementioned lists based on some criteria. The following objects in the OnTime SDK have this functionality.

• Customers
• Invoices
• Locations
• Orders
• Payments
• Users
• User Sessions
• Vehicles
• Zones

The retrieval of these lists occurs through two functions, All and Where.

The All Function

The All function simply queries the database for every object of a particular type. For example, to get a list of all Users in an OnTime account, a developer can use the following VB.NET code.

Dim results As List(Of User) = Data.GetUserList.All()

Simple Filtering Using the Where Function

The Where function has five overloads that allow for different types of filtering. The simplest overload of the Where function filters on one property and by a single value. For example, the GetUserList object has the following overload of the Where function in VB.NET.

Public Function Where(column As UserColumn, value As Object) As IList(Of User)

This overload of the Where function is demonstrated in the following VB.NET code. This code will return only the users in an OnTime account that are drivers.

Dim results As List(Of User) = Data.GetUserList.Where(UserColumn.IsDriver, True)

Advanced Filtering Using the Where Function and the Filter Object

The remaining four overloads of the Where function make use of the Filter object in the OnTime SDK. There are three types of filters available in the OnTime SDK: Filter.Exact, Filter.Contains, and Filter.Range.

Filter.Exact

The Filter.Exact object for the user list has the following constructor signature in VB.NET code.

Public Sub New(column As UserColumn, value As Object)

The constructor accepts an enumeration value from the UserColumn enumeration and an object to filter by exactly. The following VB.NET code demonstrates the use of the Filter.Exact object in conjunction with the Where function. This code returns the same result as the previous example that used the simplified version of the Where function.

Dim results As List(Of User) = Data.GetUserList.Where(New Filter.Exact(UserColumn.IsDriver, True))

Filter.Contains

The Filter.Contains object for the user list has the following constructor signature in VB.NET code.

Public Sub New(column As UserColumn, value As Object)

The constructor accepts an enumeration value from the UserColumn enumeration and an object to filter matches that contain the value of the object. The following VB.NET code demonstrates the use of the Filter.Contains object in conjungtion with the Where function. This code returns a list of users whose email address contains the string '@gmail.com.'

Dim results As List(Of User) = Data.GetUserList.Where(New Filter.Contains(UserColumn.Email, "@gmail.com"))

Filter.Range

The Filter.Range object for the user list is slightly more complicated and has the following constructor signature in VB.NET code.

Public Sub New(column As UserColumn, minValue As Object, maxValue As Object, Optional includeMin As Boolean = True, Optional includeMax As Boolean = True)

The constructor accepts an enumeration value from the UserColumn enumeration, an object representing the minimum value to filter by, an object representing the maximum value to filter by, a Boolean value indicating whether to include the minimum value or not, and a Boolean value indicating whether to include the maximum value. The following VB.NET code demonstrates the use of the Filter.Range object in conjungtion with the Where Function. This code returns a list of users that were hired between the dates of January 1, 2017 and January 1, 2018 and includes users that were hired on January 1, 2017 and January 1, 2018.

Dim results As List(Of User) = Data.GetUserList.Where(New Filter.Range(UserColumn.HiredDate, New DateTime(2017, 1, 1), New DateTime(2018, 1, 1)))

The Filter.Range object is flexible in that only one of the bounds must be defined. For example, the following VB.NET code returns a list of users that were hired after the date of January 1, 2017.

Dim results As List(Of User) = Data.GetUserList.Where(New Filter.Range(UserColumn.HiredDate, New DateTime(2017, 1, 1), Nothing))

Composing Filters

There exists an overload of the Where function which accepts a list of filters. This overload allows developers to filter lists using multiple criteria. The GetUserList object has the following overload of the Where function in VB.NET code.

Public Function Where(filters As IList(Of Filter)) As IList(Of User)

The following code demonstrates how to compose filters. The code returns a list of users who are drivers and were hired after the date of January 1, 2017.

Dim filters As New List(Of Filter)
filters.Add(New Filter.Exact(UserColumn.IsDriver, True))
filters.Add(New Filter.Range(UserColumn.HiredDate, New DateTime(2017, 1, 1), Nothing))
Dim results As List(Of User) = Data.GetUserList.Where(filters)

Filtering and Ordering

The final overloads of the Where function introduce the ability to order a returned list by a particular column. The GetUserList object contains overloads of the Where function with the following signature in VB.NET code.

Public Function Where(filter As Filter, orderBy As UserColumn) As IList(Of User)
Public Function Where(filters As IList(Of Filter), orderBy As UserColumn) As IList(Of User)

The previous example of composing filters can be extended to order the list by a particular column. The following VB.NET code returns the same result as the previous example, except that the list is ordered by the user's last name. This code represents the full functionality of querying and filtering in the OnTime SDK.

Dim filters As New List(Of Filter)
filters.Add(New Filter.Exact(UserColumn.IsDriver, True))
filters.Add(New Filter.Range(UserColumn.HiredDate, New DateTime(2017, 1, 1), Nothing))
Dim results As List(Of User) = Data.GetUserList.Where(filters, UserColumn.LastName)