Retrieve a list of M2M Devices in UWS Explorer

The Device Lookup feature in UWS Explorer shows the capabilities of the GetDeviceList API.

Get a List of All Devices in an Account

To retrieve a list of the devices in an account:

  1. Select the Device tab and then select the Lookup tab under that:

  2. Click Get Device List to get a list of all devices in the account.

The XML request and response are shown at the bottom of the window:

Notice that the GetDeviceListRequest is very simple and only includes the AccountName parameter. The response can be very long, because it includes ''all'' information about every device in the account. Scroll to the end of the response and look for the IsComplete parameter that indicates that all devices that match the request parameters have been returned.

Get a List of Devices in a Device Group or Service Plan

To retrieve a list of all devices in a device group, or all devices that have a specified service plan:

  1. Select the Device > Lookup tab.
  2. Click the Refresh button for Device Group or Service Plan to get the list of groups or plans used in the account.
  3. Check the box for Device Group or Service Plan and then select the group or plan for which you want to get a list of devices.
  4. Click Get Device List.

Notice that the GetDeviceListRequest includes the DeviceGroupName or ServicePlanFilter parameters, as well as the AccountName. If the response does not include any devices but does show that IsComplete is true, there are no devices that have the parameters that you selected.

You can use both the Device Group and Service Plan filters at the same time to find only devices that are in the selected device group and that have the selected service plan.

Get a List of Devices by Custom Field Value

Each device has five Custom Fields that you can use for unique device identifiers to help manage your M2M devices. For example, you can use one field to store the region that devices are deployed in, and another field for a location or truck identifier. You can then use custom field filters to only include matching devices in API requests.

The custom fields are named "Custom Field 1" through "Custom Field 4" in UWS Explorer and in API requests (without spaces in the names in API requests). You can use whatever labels are needed in the user interface for your application while using "CustomFieldX" in your API requests.

To retrieve a list of devices that have a certain value for a custom field:

  1. Select the Device > Lookup tab.
  2. Check the box for Custom Fields and then click Enter.
  3. Enter the value that you are looking for in the appropriate Custom Field box. (UWS Explorer only shows four custom fields, but there are five per device.) NOTE: Custom field values are not case sensitive, but other than that the value set for a device must be exactly what you enter here or the device will not match; wildcards and partial matches are not supported. If you enter more than one value, only devices that match ''all'' of the values will be included in the response.
  4. Click OK.
  5. Click Get Device List.

Get a List of Active, Suspended, or Deactive Devices

To search for devices in a particular state such as Active or Deactive:

  1. Select the Device > Lookup tab.
  2. Click the State checkbox, and select a service state from the drop-down list.
  3. Click Get Device List.

Get a List of Devices by Date Added

To search for devices by the date they were added to the account:

  1. Select the Device > Lookup tab.
  2. Select Earliest and enter the earliest date/time for the period that devices were added. Use the datetime format shown in Data Types and Unites of Measure, such as 2015-01-05.

  3. Select Latest and enter the latest date/time for the period that devices were added.

    NOTE: You do not have to enter values for both Earliest and Latest.

  4. Click Get Device List.

Working with More Than 2000 Devices

The GetDeviceList API that is called by UWS Explorer returns a maximum of 2000 devices, sorted by the date that they were added to the account. If you need to get information for more than 2000 devices, follow this procedure:

  1. Optionally set any filters, such as Device Group, Service Plan, or Custom Fields.
  2. Click Get Device List.
  3. Save the returned information by clicking in the Response area, then press Ctrl-A to select all, and then Ctrl-C to copy the XML. Paste it into another program.
  4. Scroll to the bottom of the Response area and look at the field. If the value is "true" then you have all of the devices. If not, continue with the steps below.
  5. Look about a dozen lines above the field and find the <CreatedAt> field for the last device. Note the value for that field.

  6. Check the box for the Earliest filter and then type in the value from the <CreatedAt> field in the previous step. You don't need to include the letter from the end of the value, like this:

  7. Click Get Device List.
  8. Repeat step 3 to save the information, and then repeat steps 4 through 7 until the <IsComplete> value is "true."

After you have pasted all of the returned device information into another program, you will need to remove any duplicate entries. The <CreatedAt> value that you used in step 6 came from a device that in the first response, and that device will also be included in the second response. CreatedAt values are not unique (more than one device could have been added to the system at the same time), so the overlap is required to ensure that you get all devices, but it results in duplicate entries at the end of one response and the beginning of the next one.