Skip to main content

Who is this article for?

CrashPlan Cloud
CrashPlan for Small Business

Find your product plan in the Code42 console on the Account menu.
Not a CrashPlan Cloud customer? Search or browse CrashPlan for Small Business or Incydr and Instructor.

Instructor, no.

Incydr Professional, Enterprise, Horizon, and Gov F2, no.

Incydr Basic, Advanced, and Gov F1, no.

CrashPlan Cloud, yes.

CrashPlan for Small Business, no.

HOME
GETTING STARTED
RELEASE NOTES
FAQs
APIs
SYSTEM STATUS
Code42 Support

View device backup status with the CrashPlan API

Who is this article for?

CrashPlan Cloud
CrashPlan for Small Business

Find your product plan in the Code42 console on the Account menu.
Not a CrashPlan Cloud customer? Search or browse CrashPlan for Small Business or Incydr and Instructor.

Instructor, no.

Incydr Professional, Enterprise, Horizon, and Gov F2, no.

Incydr Basic, Advanced, and Gov F1, no.

CrashPlan Cloud, yes.

CrashPlan for Small Business, no.

Overview

The Code42 API DeviceBackupReport resource efficiently retrieves the data you need to address common problems and answer common questions about users and devices in your Code42 environment. DeviceBackupReport provides centralized reporting and better performance than separate calls to the User, Computer, and Destination resources.

Capabilities of the DeviceBackupReport resource

DeviceBackupReport provides information about users and devices in your Code42 environment, such as:

  • Backup status
  • Disk usage
  • Cold storage state
  • Connection status and alerts
  • Organization and destination details
  • User information
  • Operating system type
  • Network information

Considerations

The DeviceBackupReport resource cannot modify your Code42 environment, and the results it can provide are limited by the user's role.

Specify at least one query parameter
In very large Code42 environments (100,000+ devices), sending a request to the DeviceBackupReport resource without specifying at least one parameter-value pair puts an unusually heavy load on the Code42 cloud and can cause noticeable performance delays. Specify query parameters and values whenever possible.

Before you begin

Before you attempt to use DeviceBackupReport, become familiar with the basics.

Partial string matches and flexible search

You can search for users, organizations, devices, destinations, and operating systems using partial string matching. The search is conducted against multiple source fields for each entity. For example, you can search for a user based on the user's last name, username, email, or the userExtRef field.

Output formats

DeviceBackupReport provides JSON-formatted output by default, but you can also get output in CSV format with the query parameter export=csv.

  • All records are returned when exporting to CSV format.
  • Paging is not used when exporting in CSV format, even if the pgSize query parameter is specified.
  • CSV format is ideal when the DeviceBackupReport resource does not provide the sorting, grouping or filtering you require. Simply open the CSV file in your spreadsheet, and apply the sorting and grouping options you require.

Sorting and paging

When sorting using the srtKey query parameter, paging is limited to the first page.

Example use cases

The following examples show how to use DeviceBackupReport to administrate your Code42 environment.

Use case 1: Backup status report

This backup status report identifies which devices have not backed up for a long period of time.

Example request

This request shows device backup status for active devices, sorted by the time they last connected to the Code42 cloud:

Copied!
https://console.us1.crashplan.com/api/DeviceBackupReport?srtKey=lastConnectedDate&active=true

Interpret the results

The default sorting direction is ascending, so the first devices listed are the devices that have not connected for the longest period of time. The backupCompletePercentage data can help you identify whether some or all data on a device has successfully backed up.

Using this information, you can investigate user devices that have not connected for a long time. Some possible causes:

  • The user is on vacation or sabbatical.
  • A remote user's router or firewall is preventing connection.
  • The Code42 service has been disabled on the device.
  • The user uninstalled the Code42 app.

Use case 2: Disk usage

This disk usage report identifies the users who are consuming the most storage space.

Example request

This request shows devices sorted by the size of their archives:

Copied!
https://console.us1.crashplan.com/api/DeviceBackupReport?srtKey=archiveBytes&srtDir=desc

Interpret the results

The devices with the largest archives are listed first, highlighting the users and devices that are taking up the most disk space in your Code42 environment. You can then examine the file exclusions, version settings, and other device backup settings for these users.

Alternative request

Alternatively, you may want to sort the output by the total size of the files and folders selected for backup, rather than by the size of the archives stored by the Code42 environment:

Copied!
https://console.us1.crashplan.com/api/DeviceBackupReport?srtKey=selectedBytes&srtDir=desc

Use case 3: Device migration plan

DeviceBackupReport can identify devices on a particular operating system in an organization, and how much data will need to be migrated to replacement devices.

Example request

This request shows all Mac devices in the organization named "Accounting:"

Copied!
https://console.us1.crashplan.com/api/DeviceBackupReport?os=mac&org=Accounting&active=true&srtKey=selectedBytes&srtDir=desc

Replace the operating system type and organization name in this example request with values appropriate for your Code42 environment.

Interpret the results

The Mac devices with the largest archives are listed first, highlighting the migrations that may take longer.

Use case 4: Purge cold storage to free space

To locate archives that can be purged from cold storage, DeviceBackupReport shows all devices with archives in cold storage, along with the date on which the devices last connected.

Purging archives
This is an example only. Before purging any archives from cold storage, confirm that the archives are no longer needed. Depending on your company's data retention policy, archives may need to be kept for a defined period of time.

Example request

The following request generates a CSV file with backup information for all devices:

Copied!
https://console.us1.crashplan.com/api/DeviceBackupReport?export=csv

Interpret the results

In this example, the data is available for download through your web browser. After downloading the file, open the file in a spreadsheet, and sort the results by the output value coldStorage. The coldStorage output value has the boolean data type.

  • True indicates that a device's archive is in cold storage.
  • False indicates that a device's archive is not in cold storage.

The report contains a list of all the devices in the Code42 environment. By filtering the results to show only devices with archives in cold storage, and sorting this filtered list by the last connected date, the administrator can confirm that the archives are no longer needed and purge the archives to free up space.

Use case 5: Search with custom metadata fields

DeviceBackupReport also searches reference fields, which are used to store descriptive information for users (userExtRef), devices (computerExtRef. deviceExtRef) and organizations (orgExtRef).

Example request

The user query parameter flexibly searches on username, email, userExtRef, or last name. The following request finds all devices for a user based on userExtRef, such as an employee ID number stored in the reference field:

Copied!
https://console.us1.crashplan.com/api/DeviceBackupReport?user=1001

Security and permissions

Read-only reports

The DeviceBackupReport resource cannot make changes to your Code42 environment, so it is safer to use than other resources that provide the same data.

Roles and permissions

The DeviceBackupReport resource can be used by any user in your Code42 environment, but the results that it can provide are limited by the the permissions that are assigned to the user's role. For example:

  • A standard desktop user with no additional permissions can get information on her own devices, but cannot get information on anyone else's devices.
  • An org manager can get information on all the devices of the organization that he manages, but not for devices in other organizations.
  • A system administrator can get information on any user in the Code42 environment.

Parameters

orgUid
string

Returns the device reports for users in the organization with the specified orgUid.

userUid
string

Returns the device reports for the user with the specified userUid.

deviceUid
string

Return the device report for the device with the specified deviceUid.

destinationUid
string

Returns the device report for devices in the destination with the specified destinationUid.

org
string

Returns the device report for devices in an organizations with an orgName or orgExtRef that contains the supplied string.

incChildOrgs
boolean

Indicates if we should also return computers from the organization's children (true), or just the organization (false).

user
string

Returns the device report for devices owned by a user with a username, email, userExtRef, or last name that contains the supplied string.

device
string

Returns the device report for devices with a deviceName, deviceOsHostname, or deviceExtRef that contains the supplied string.

destination
string

Returns the device report for devices in a destination, with a destinationName that contains the supplied string.

active
boolean

Optional filter to show only active or deactivated objects. True = active, false = inactive. If not included, both active and inactive devices are returned.

userActive
boolean

Optional filter to show only active or deactivated users. True = active, false = inactive. If not included, both active and inactive users are returned.

os
string

Returns the device report for all devices with an operating system that contains the supplied string.

alerted
string
Enum: "false" "true" "backup_warning" "backup_critical" "no_backup_alerts"

Optional filter for alertStates

mostRecentUserProfileCreationResult
string
Enum: "SUCCEEDED" "FAILED" "NOT_APPLICABLE" "FAILED_OR_NOT_APPLICABLE"

Filter for mostRecentUserProfileCreationResult

mostRecentUserProfileBackupResult
string
Enum: "SUCCEEDED" "FAILED" "NOT_APPLICABLE" "FAILED_OR_NOT_APPLICABLE"

Filter for mostRecentUserProfileBackupResult

srtKey
string
Enum: "lastConnectedDate" "lastCompletedBackupDate" "selectedBytes" "archiveBytes" "mostRecentUserProfileCreationResult" "mostRecentUserProfileBackupResult"

Key to sort on.

srtDir
string
Default: "ASC"
Value: "ASC or DESC (case is irrelevant)."

Direction of sort.

secondarySrtKey
string
Value: "mostRecentUserProfileBackupResult"

A secondary key to sort on. This acts as a tiebreaker for items with the same 'srtKey' value. A primary srtKey is required when using secondarySrtKey.

secondarySrtDir
string
Default: "ASC"
Value: "ASC or DESC (case is irrelevant)."

Direction of secondary sort. A secondarySrtKey is required when using secondarySrtDir.

pgSize
integer <int32>

Specifies the number of results to return per page. Maximum value is 1000.

pgNum
integer <int32>

The page of results to return. Starts with 1.

export
string
Value: "csv"

Exports data as the specified file type.

Response samples

{
  "metadata": {
    "timestamp": "2016-01-14T13:56:32.545-06:00",
    "params": {}
  },
  "data": [
    {
      "archiveGuid": "724855853869125969",
      "orgUid": "724855825398190417",
      "orgName": "engineering_1452795339",
      "orgExtRef": null,
      "userUid": "724855845514072401",
      "username": "leland.buckridge_1452795339",
      "email": null,
      "userExtRef": null,
      "deviceUid": "724855847728664913",
      "deviceName": "d45de1705186b69ba50c3439e1651470",
      "deviceOsHostname": "CE24DI64M",
      "deviceExtRef": null,
      "destinationUid": "72",
      "destinationName": "PROe Destination1",
      "serverUid": "7201",
      "serverName": "PROe Master",
      "version": "6.9.2.3546",
      "status": "Active",
      "userStatus": "Active",
      "alertStates": "OK",
      "os": null,
      "osVersion": null,
      "address": "192.168.0.1:1234",
      "remoteAddress": "192.168.0.1",
      "creationDate": "2016-01-14T12:15:54.061-06:00",
      "selectedBytes": "846",
      "backupCompletePercentage": "100.0",
      "archiveBytes": "150",
      "coldStorage": "false",
      "lastConnectedDate": null,
      "lastCompletedBackupDate": "2016-01-12T12:16:00.000-06:00",
      "lastActivity": null,
      "mostRecentUserProfileCreationResult": "SUCCEEDED",
      "mostRecentUserProfileBackupResult": "SUCCEEDED"
    }
  ]
}

Related topics