Devices (GET)

Retrieves metadata for the list of devices that accessed this project.

Note

Since 7.1, the offset parameter is no longer supported. Use the bookmark parameter instead for paging.

Roles

Users in the following roles are authorized to perform this operation:

mfpadmin
mfpdeployer
mfpmonitor
mfpoperator

Method

GET

Path

/management-apis/2.0/runtimes/runtime-name/devices

Example

https://www.example.com/mfpadmin/management-apis/2.0/runtimes/myruntime/devices?bookmark=ABC&locale=de_DE&orderBy=uid&pageSize=100&query=Jeremy

Path Parameters

runtime-name: The name of the runtime. This is the context root of the runtime web application, without the leading slash.

Query Parameters

Query parameters are optional.

bookmark: The bookmark for the page if only a part of the list (a page) should be returned.
locale: The locale used for error messages.
orderBy: The sort mode. By default, the elements are sorted in increasing order. If the sort mode starts with - (minus sign), the elements are sorted in decreasing order. Possible sort modes are: uid, friendlyName, deviceModel, deviceEnvironment, status, lastAccessed. The default sort mode is: uid.
pageSize: The number of elements if only a part of the list (a page) should be returned. The default value is 100.
query: A device-friendly name or a user to search for.

Produces

application/json, application/xml, text/xml

Response

The metadata of the devices that accessed this project.

JSON Example

{
  "items" : [
    {
      "applicationDeviceAssociations" : [
        {
          "appId" : "com.ibm.app$ios$1.0.0",
          "appName" : "myapplication",
          "certSerialNumber" : "",
          "deviceId" : "12345-6789",
          "deviceStatus" : "LOST",
          "status" : "ENABLED",
        },
        ...
      ],
      "deviceDisplayName" : "Jeremy's Personal Phone",
      "deviceModel" : "Nexus 7",
      "deviceOs" : "4.4",
      "id" : "12345-6789",
      "lastAccessed" : "2014-05-13T00:18:36.979Z",
      "status" : "LOST",
      "userIds" : [
        {
          "str" : "Jeremy",
        },
        ...
      ],
    },
    ...
  ],
  "nextPageBookmark" : "DEF",
  "pageNumber" : 2,
  "pageSize" : 100,
  "prevPageBookmark" : "ABC",
  "productVersion" : "8.0",
  "startIndex" : 0,
  "totalListSize" : 33,
}

XML Example

<?xml version="1.0" encoding="UTF-8"?>
<devices
  nextPageBookmark="DEF"
  pageNumber="2"
  pageSize="100"
  prevPageBookmark="ABC"
  productVersion="8.0"
  startIndex="0"
  totalListSize="33">
  <items>
    <item
      deviceDisplayName="Jeremy's Personal Phone"
      deviceModel="Nexus 7"
      deviceOs="4.4"
      id="12345-6789"
      lastAccessed="2014-05-13T00:18:36.979Z"
      status="LOST">
      <applicationDeviceAssociations>
        <applicationDeviceAssociation
          appId="com.ibm.app$ios$1.0.0"
          appName="myapplication"
          certSerialNumber=""
          deviceId="12345-6789"
          deviceStatus="LOST"
          status="ENABLED"/>
        ...
      </applicationDeviceAssociations>
      <userIds>
        <userId str="Jeremy"/>
        ...
      </userIds>
    </item>
    ...
  </items>
</devices>

Response Properties

The response has the following properties:

items: The array of device metadata
nextPageBookmark: The bookmark of the next page if only one page of devices is returned.
pageNumber: The page index if only one page of devices is returned.
pageSize: The page size if only one page of devices is returned.
prevPageBookmark: The bookmark of the previous or first page if only one page of devices is returned.
productVersion: The exact product version.
startIndex: The start index in the total list if only one page of devices is returned.
totalListSize: The total number of devices.

The device has the following properties:

applicationDeviceAssociations: The applications on the device.
deviceDisplayName: The friendly name of the device.
deviceModel: The device model.
deviceOs: The device operating system.
id: The device id.
lastAccessed: The date in ISO 8601 format when the device was last accessed.
status: The status of the device: ACTIVE, LOST, STOLEN, EXPIRED, DISABLED.
userIds: The applications on the device.

The device application has the following properties:

appId: The application id.
appName: The name of the application.
certSerialNumber: The serial number of the certificate
deviceId: The device id.
deviceStatus: The status of the device:ACTIVE, LOST, STOLEN, EXPIRED, DISABLED.
status: The status of the application: ENABLED or DISABLED.

The user-ids has the following properties:

str: The name of the user

Errors

403

The user is not authorized to call this service.

404

The corresponding runtime is not found or not running.

500

An internal error occurred.