Best Practices for Application Development

Back to top

In order to increase the trust and comfort of Hexamples of identity api : to get the user detailsP DaaS members when granting your application access to their data, it is important to give transparency to how their data will be used. Follow these suggestions to help your application succeed at delivering value to HP DaaS members.

 

Self-managed vs. Partner-managed APIs

 

The HP Device as a Service Proactive Management with TechPulse (henceforth Proactive Management), reports provide insightful analytics on planning and cost optimization and service management capabilities of devices enrolled in Proactive Management.

Customers who wish to manage the Proactive Management analytics on their own are referred to as “self-managed customers”. Customers who choose to outsource the management of Proactive Management analytics to their preferred partners are referred to as “partner-managed customers.”

Self-managed customers can only fetch data for their Proactive Management account. Partner-managed customers can fetch data for all their customers managed in Proactive Management. For e.g. if a Proactive Management partner A is managing three customers – X, Y and Z, invoking a HP TechPulse Analytics API will return analytics information for all three customers either separately for Details APIs and aggregated information for all three customers in the Summary API.

 

Example of a POST request - Self-managed summary API
HTTP request
POST /analytics/v1/reports/reports/softuti/winApplications/type/graph HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
Body: NO need to specify any tenantd id here

HTTP response
{
    "totalResults": 1,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "byPercentages": [
                {
                    "appName": "Windows Explorer",
                    "usage": 52.44
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 51.87
                }
            ],
            "byUsageHours": [
                {
                    "appName": "Windows Explorer",
                    "usage": 81.6
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 50.27
                }
            ]
        }
    ]
}

 

Example of a POST request - Self-managed details API
HTTP request
POST /analytics/v1/reports/softuti/summary/type/grid?count=2 HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <ACCESS_TOKEN>
Body: NO need to specify any tenantd id here

HTTP response
{
    "totalResults": 31,
    "startIndex": 0,
    "itemsPerPage": 2,
    "resources": [
        {
            "appName": "ApplicationFrameHost",
            "appVersion": "",
            "deviceCount": "105873",
            "appUsageCount": "63919",
            "appUsagePercent": "60.37",
            "appUsageHours": "8630562.00",
            "appAvgUsageTime": "81.52",
            "rankAppUsagePercent": "1",
            "rankAppUsageHrs": "3"
        },
        {
            "appName": "Windows Explorer",
            "appVersion": "10.0.15063.0",
            "deviceCount": "105873",
            "appUsageCount": "55523",
            "appUsagePercent": "52.44",
            "appUsageHours": "8639202.00",
            "appAvgUsageTime": "81.60",
            "rankAppUsagePercent": "2",
            "rankAppUsageHrs": "2"
        }
    ]
}

 

Example of a POST request - Partner-managed details API
HTTP Request
POST /analytics/v1/reports/hwinv/details/type/grid?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: NO tenant ids

HTTP response
{
    "totalResults": 11,
    "startIndex": 0,
    "itemsPerPage": 11,
    "resources": [
        {
            "counterId": 134375,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP ProDesk 600 G4 SFF",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "09/29/2018",
            "endDate": "03/01/2021",
            "lastOnlineDate": "11/28/2018 at 03:49 AM (UTC)",
            "memory": "24 GB  2667 MHz",
            "graphics": "Intel(R) UHD Graphics 630",
            "processor": "Intel(R) Core(TM) i5-8400 CPU @ 2.80GHz",
            "mfgDate": "01/31/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": "In warranty",
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "Unknown",
            "osversion": "Unknown",
            "osreleselToggaleEnabled": true
        },
        {
            "counterId": 97989,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP Elite Slice",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "08/31/2018",
            "endDate": null,
            "lastOnlineDate": "11/28/2018 at 08:33 AM (UTC)",
            "memory": "8 GB  2400 MHz",
            "graphics": "Intel(R) HD Graphics 630",
            "processor": "Intel(R) Core(TM) i3-7310T CPU @ 3.40GHz",
            "mfgDate": "01/03/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": null,
            "locationcc": "United States",
            "dateListMonth": "Aug 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "10.0.17134.407",
            "osversion": "10.0.17134.407",
            "osreleselToggaleEnabled": true
        },
        ... // 11 Records
    ]
}

 

Example of a POST request - Partner-managed summary API
HTTP Request
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body: NO tenant ids

HTTP response
{
    "totalResults": 3,
    "startIndex": 0,
    "itemsPerPage": 3,
    "resources": [
        {
            "deviceOs": "Windows 10",
            "total": 8,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "Windows 10",
                    "total": 3,
                    "data": null,
                    "osRelease": "10.0.17134.407",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                },
                ...// 4 records
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        {
            "deviceOs": "Windows 8",
            "total": 2,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                ...// sample data removed
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        {
            "deviceOs": "OSX 10",
            "total": 1,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "OSX 10",
                    "total": 1,
                    "data": null,
                    "osRelease": "OS X Version 10.14 (Build 18A391)",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                }
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "OSX",
            "productOs": null,
            "osreleselToggaleEnabled": true
        }
    ]
}

 

Example of a POST request - Partner-managed details API
HTTP Request
POST /analytics/v1/reports/hwinv/details/type/grid HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ],
    "filter":" ( devicetype eq \"Desktop\" ) "
}

HTTP response
{
    "totalResults": 3,
    "startIndex": 0,
    "itemsPerPage": 3,
    "resources": [
        {
            "counterId": 134375,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP ProDesk 600 G4 SFF",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "09/29/2018",
            "endDate": "03/01/2021",
            "lastOnlineDate": "11/28/2018 at 03:49 AM (UTC)",
            "memory": "24 GB  2667 MHz",
            "graphics": "Intel(R) UHD Graphics 630",
            "processor": "Intel(R) Core(TM) i5-8400 CPU @ 2.80GHz",
            "mfgDate": "01/31/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": "In warranty",
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "10.0.17763.134",
            "osversion": "10.0.17763.134",
            "osreleselToggaleEnabled": true
        },
        {
            "counterId": 97989,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP Elite Slice",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "08/31/2018",
            "endDate": null,
            "lastOnlineDate": "11/28/2018 at 08:33 AM (UTC)",
            "memory": "8 GB  2400 MHz",
            "graphics": "Intel(R) HD Graphics 630",
            "processor": "Intel(R) Core(TM) i3-7310T CPU @ 3.40GHz",
            "mfgDate": "01/03/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": null,
            "locationcc": "United States",
            "dateListMonth": "Aug 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "10.0.17134.407",
            "osversion": "10.0.17134.407",
            "osreleselToggaleEnabled": true
        },{
            "counterId": 21649,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "APPLE",
            "deviceModel": "Macmini6 1",
            "deviceSn": "device-sn",
            "deviceOs": "OSX 10",
            "dateEnrolled": "09/09/2018",
            "endDate": null,
            "lastOnlineDate": "11/26/2018 at 01:54 PM (UTC)",
            "memory": "8 GB 1600 MHz",
            "graphics": "Intel HD Graphics 4000",
            "processor": "Intel(R) Core(TM) i5-3210M CPU @ 2.50GHz",
            "mfgDate": "Unknown",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "OSX 10",
            "warStatus": null,
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "OS X Version 10.14 (Build 18A391)",
            "osversion": "OS X Version 10.14 (Build 18A391)",
            "osreleselToggaleEnabled": true
        }
    ]
}

 

Example of a POST request - Partner-managed summary API
HTTP request
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <Access Token>
Body:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ],
    "filter":" ( devicetype eq \"Desktop\" ) "
}

HTTP response
{
    "totalResults": 2,
    "startIndex": 0,
    "itemsPerPage": 2,
    "resources": [
        {
            "deviceOs": "Windows 10",
            "total": 2,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "Windows 10",
                    "total": 3,
                    "data": null,
                    "osRelease": "10.0.17134.407",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                },
                {
                    "deviceOs": "Windows 10",
                    "total": 1,
                    "data": null,
                    "osRelease": "10.0.17763.134",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                }
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        {
            "deviceOs": "OSX 10",
            "total": 1,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "OSX 10",
                    "total": 1,
                    "data": null,
                    "osRelease": "OS X Version 10.14 (Build 18A391)",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                }
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "OSX",
            "productOs": null,
            "osreleselToggaleEnabled": true
        }
    ]
}

 

 

 

Company, User and Device Identifiers

 

All our Analytics and Incident APIs accept company/device/user unique identifiers of type GUID whereas APIs respond with numeric identifiers. An identity map API can be called in order to get the identifier of type GUID corresponding to numeric identifiers.

Examples of Identity Map API
HTTP Request
GET /analytics/v1/reports/id/{int-id}/type/{id-type} HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTP response
For Device:
{
    "intId": 12345,
    "idType": "deviceid",
    "uuid": "device-uuid-1"
}

For User:
{
    "intId": 1234,
    "idType": "userid",
    "uuid": "user-uuid-1"
}

For Company:
{
    "intId": 1458,
    "idType": "companyid",
    "uuid": "tenant-uuid-1"
}

 

This is an identity service API to fetch all users details or based on user_id.

Examples of Identity API : To get the User details
HTTP Request
GET /analytics/v1/identity/users HTTP/1.1
OR
GET /analytics/v1/identity/users/{user-id} HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTP response
{
    "schemas": [
        "urn:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "user-uuid-1",
    "userName": "test-email@email.com",
    "name": {
        "honorificPrefix": "",
        "familyName": "test",
        "givenName": "testuser",
        "honorificSuffix": ""
    },
    "displayName": "User Name",
    "addresses": [],
    "phoneNumbers": []
    .....
}

 

This is an identity service API to fetch all tenants details or based on tenant_id.

Examples of Identity API : To get the Tenant details
HTTP Request
GET /analytics/v1/identity/tenants HTTP/1.1
OR
GET /analytics/v1/identity/tenants/{tenant-id} HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTP response
{
    "schemas": [
        "urn:scim:schemas:core:2.0:Tenant"
    ],
    "id": "tenant-uuid-1",
    "displayName": "Customer Name",
    "description": "",
    "tenantType": "CUSTOMER",
    "subTypes": [],
    "phoneNumber": {
        "value": "555-5555",
        "type": "work"
    },
    "ownerId": "test-emailid@email.com"
    ....
}

 

 

 

Filtering, Sorting and Pagination Operations

 

Filtering

Filtering is OPTIONAL. Consumers may request a subset of Resources by specifying the 'filter' URL query parameter containing a filter expression. When specified only those Resources matching the filter expression SHALL be returned. The expression language that is used in the filter parameter supports references to attributes and literals. The literal values can be strings enclosed in double quotes, numbers, date times enclosed in double quotes, and Boolean values; i.e., true or false. String literals MUST be valid JSON strings. The attribute name and attribute operator are case insensitive.

For example, the following two expressions will evaluate to the same logical value:
filter=userName Eq "john"
filter=Username eq "john"

The filter parameter MUST contain at least one valid Boolean expression. Each expression MUST contain an attribute name followed by an attribute operator and optional value. Multiple expressions MAY be combined using the two logical operators. Furthermore expressions can be grouped together using "()". The operators supported in the expression are listed in the following table.

Attribute Operators
Operator
Description
Behavior
eq
equal
The attribute and operator values must be identical for a match.
co
contains
The entire operator value must be a substring of the attribute value for a match.
sw
starts with
The entire operator value must be a substring of the attribute value, starting at the beginning of the attribute value. This criterion is satisfied if the two strings are identical.
pr
present (has value)
If the attribute has a non-empty value, or if it contains a non-empty node for complex attributes there is a match.
gt
greater than
If the attribute value is greater than operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison.
ge
greater than or equal
If the attribute value is greater than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison.
lt
less than
If the attribute value is less than operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison.
le
less than or equal
If the attribute value is less than or equal to the operator value, there is a match. The actual comparison is dependent on the attribute type. For string attribute types, this is a lexicographical comparison and for DateTime types, it is a chronological comparison.
neq
not equal
The attribute and operator values must not be identical for a match

 

Logical Operators
Operator
Description
Behavior
and
Logical And
The filter is only a match if both expressions evaluate to true.
or
Logical Or
The filter is a match if either expression evaluates to true.

 

Grouping Operators
Operator
Description
Behavior
()
Precedence grouping
Boolean expressions may be grouped using parentheses to change the standard order of operations; i.e., evaluate OR logical operators before logical AND operators.

 

Filters MUST be evaluated using standard order of operations. Attribute operators have the highest precedence, followed by the grouping operator (i.e, parentheses), followed by the logical AND operator, followed by the logical OR operator.

If the specified attribute in a filter expression is a multi-valued attribute, the Resource MUST match if any of the instances of the given attribute match the specified criterion; e.g. if a User has multiple emails values, only one has to match for the entire User to match. For complex attributes, a fully qualified Sub-Attribute MUST be specified using standard attribute notation. For example, to filter by userName the parameter value is userName and to filter by first name, the parameter value is name.givenName.

Providers MAY support additional filter operations if they choose. Providers MUST decline to filter results if the specified filter operation is not recognized and return a HTTP 400 error with an appropriate human readable response. For example, if a Consumer specified an unsupported operator named 'regex' the Service Provider should specify an error response description identifying the Consumer error; e.g., 'The operator 'regex' is not supported.'

String type attributes are case insensitive by default unless the attribute type is defined as a caseExact string. Attribute operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string attributes unless the attribute is defined as caseExact. By default all string attributes are caseIgnore.

Examples :
filter=dateenrolled gt "2011-05-13T04:42:34Z"

filter= ( devicetype eq \"Desktop\" ) and ( devicetype eq \"Notebook\" )

 

Sorting

Sort is OPTIONAL. Sorting allows Consumers to specify the order in which Resources are returned by specifying a combination of sortBy and sortOrder URL parameters.

sortBy
The sortBy parameter specifies the attribute whose value SHALL be used to order the returned responses. If the sortBy attribute corresponds to a Singular Attribute, Resources are sorted according to that attribute's value; if it's a Multi-valued Attribute, Resources are sorted by the value of the primary attribute, if any, or else the first value in the list, if any. If the attribute is complex the attribute name must be a path to a Sub-Attribute in standard attribute notation ; e.g., sortBy=name.givenName. For all attribute types, if there is no data for the specified sortBy value they are sorted via the 'sortOrder' parameter; i.e., they are ordered last if ascending and first if descending.

sortOrder
The order in which the sortBy parameter is applied. Allowed values are "ascending" and "descending". If a value for sortBy is provided and no sortOrder is specified, the sortOrder SHALL default to ascending. String type attributes are case insensitive by default unless the attribute type is defined as a caseExact string. sortOrder MUST sort according to the attribute type; i.e., for caseIgnore attributes, sort the result using case insensitive, Unicode alphabetic sort order, with no specific locale implied and for caseExact attribute types, sort the result using case sensitive, Unicode alphabetic sort order.

 

Sample: single column sorting
POST /analytics/v1/reports/hwinv/details/type/grid?sortBy=dateenrolled&sortOrder=asc HTTP/1.1
Host: daas.api.hp.com
Query String Parameters: sortBy=dateenrolled& sortOrder=asc

 

Sample: multiple column sorting
POST /analytics/v1/reports/hwinv/details/type/grid?sortBy=dateenrolled%20desc,devicename%20asc HTTP/1.1
Host: daas.api.hp.com
Query String Parameters: sortBy: dateenrolled desc, devicename asc

 

 

Pagination

Pagination parameters can be used together to "page through" large numbers of Resources so as not to overwhelm the Consumer or Service Provider. Pagination is not session based hence Consumers SHOULD never assume repeatable results. For example, a request for a list of 10 Resources beginning with a startIndex of 1 may return different results when repeated as a Resource in the original result could be deleted or new ones could be added in-between requests. Pagination parameters and general behavior are derived from the OpenSearch Protocol.

The following table describes the URL pagination parameters.

 

Pagination Request Parameters
Parameter
Description
Default
startIndex
The 1-based index of the first search result.
1
count
Non-negative Integer. Specifies the desired maximum number of search results per page; e.g., 10.
None. When specified the Service Provider MUST not return more results than specified though MAY return fewer results. If unspecified, the maximum number of results is set by the Service Provider.

 

Pagination Response Elements
Element
Description
itemsPerPage
Non-negative Integer. Specifies the number of search results returned in a query response page; e.g., 10.
totalResults
Non-negative Integer. Specifies the total number of results matching the Consumer query; e.g., 1000.
startIndex
The 1-based index of the first result in the current set of search results; e.g., 1.

For example, to retrieve the first 10 Users set the startIndex to 1 and the count to 10.

Sample Response

{
  "totalResults":100,
  "itemsPerPage":10,
  "startIndex":1,
  "schemas":["urn:scim:schemas:core:1.0"],
  "Resources":[{
    ...
  }]
}

Given the example above, to continue paging set the startIndex to 11 and re-fetch.

 

 

Date Time Conversions

 

For attributes with date and timestamp data types in API response, HP TechPulse Analytics APIs leverage one of the below two scenarios:

  • Scenario 1. Convert the date and timestamp of the data from Proactive Management’s server time to the Proactive Management portal’s Preferred Time Zone setting of the user’s company or partner calling the APIs, or
  • Scenario 2. Use the date and timestamp of the data reported from the devices in their local time zone.

The swagger API reference lists the scenario used for each of the date and timestamp attributes.

Scenario 1

  • If the user (calling the APIs) belongs to a company, the API response will return the date and timestamp values based on the Preferred Time Zone settings set in the Proactive Management portal for the company.
Example: Preferred Time Zone (lastSeenDate)
HTTP request
POST /analytics/v1/reports/batteryrep/details/type/grid HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer <Access Token>
Body: No tenants

HTTP response
{
    "totalResults": 7,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "counterId": 7,
            "companyId": "1",
            "companyName": "company-name",
            "deviceId": "123456",
            "deviceName": "device-name",
            "serialNumber": "device-sn",
            "deviceManufacturer": "HP",
            "manufactureDate": "07/16/2014",
            "lastSeenDate": "11/12/2018 at 09:45 PM (CDT)",
            "batterySn": "battery-sn",
            "batteryGrade": "Severe degradation",
            "batteryReplacementTimeframe": "0",
            "deviceType": "Notebook",
            "deviceModel": "HP EliteBook Folio 9480m",
            "locationcc": "United States",
            "batteryHealth": "Fail",
            "warStatus": "Out of warranty",
            "ctNumber": "ct-number",
            "dwarstatus": "Unknown",
            "oblenddate": "Unknown"
        }
    ]
}

 

  • if the user (calling the APIs) belongs to a partner managing three company’s and each of the three companies have different Preferred Time Zone settings – TZ1, TZ2 and TZ3 – and the partner’s Preferred Time Zone settings is TZ4, the response will return the date and timestamps values based on the Preferred Time Zone settings set in the Proactive Management portal for the partner (i.e. TZ4)
Example: Local Time Zone (Date Occurred - dateList)
HTTP Request
POST /analytics/v1/reports/hwbluescreen/details/type/grid?count=1&startIndex=0 HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token
Body:
{
    "tenants": [ "tenant-uuid-1","tenant-uuid-2" ]
}

HTTP response
{
    "totalResults": 153919,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "deviceId": "12345",
            "devicename": "device-name",
            "devicesn": "device-sn",
            "drivercrashBugcheckcode": "000000d1",
            "drivercrashDescription": "DRIVER_IRQL_NOT_LESS_OR_EQUAL",
            "drivercrashHyperlink": "https://msdn.microsoft.com/en-us/library/windows/hardware/ff560244(v=vs.85).aspx",
            "counterid": 50,
            "dateList": "08/28/2018 18:37:09",
            "lastonlinedate": "01/23/2019 at 06:58 AM (CST)",
            "causedByDriver": "Unable to determine",
            "driverVersion": "Unable to determine",
            "locationcc": "United States",
            "osRelease": "Win10 - 1703"
        }
    ]
}

 

 

 

Numeric Formats

 

HP TechPulse Analytics APIs leverage the Proactive Management portal’s user language setting of the user calling the APIs, for attributes with numeric formats. For example, if the user’s language setting in set to English (United States), then the values all numeric attributes returned by the APIs will follow the conventions of United States.

The user’s language setting can either be set manually in Proactive Management portal or by calling the .

To set the language settings manually, the Proactive Management user with either IT Admin, Report Admin, Partner Admin, or Partner Specialist role signs in to the Proactive Management portal and performs the following steps. 1. Login to the Proactive Management portal. 2. In the main page, click the User icon and then EDIT MY PROFILE to open the User Details page. 3. In the User Details page, click on Edit button in the first section. 4. Change the language from the Language drop down. 5. Click Save

To get the existing user’s language settings, use the

Example
HTTP Request:
POST /analytics/v1/reports/softuti/winApplications/type/graph HTTP/1.1
Host: daas.api.hp.com
Authorization: Bearer <ACCESS_TOKEN>

HTTP Response:
{
    "totalResults": 1,
    "startIndex": 0,
    "itemsPerPage": 1,
    "resources": [
        {
            "byPercentages": [
                {
                    "appName": "Windows Explorer",
                    "usage": 52.44
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 51.87
                }
            ],
            "byUsageHours": [
                {
                    "appName": "Windows Explorer",
                    "usage": 81.6
                },
                {
                    "appName": "Internet Explorer",
                    "usage": 50.27
                }
            ]
        }
    ]
}

 

 

 

Exclude/Include attributes

 

Specifying attributes to return By default, HP TechPulse Analytics returns all attributes that your client application is authorized to read when you request a resource. You can specify either of the following special query parameters to override this behavior:

Parameter
Description
attributes
Indicates the set of attributes to include in the response. Takes a comma-separated list of attribute names. Extension schema attribute names must be prefixed with the extension schema URN.
excludedAttributes
Indicates a set of attributes to exclude from the response. Takes a comma-separated list of attribute names. Extension schema attribute names must be prefixed with the extension schema URN.

The attributes and excludedAttributes parameters are mutually exclusive. Do not specify both in the same request. See the API Reference for a complete list of attributes for each resource.

NOTE: For readability, the filter string and attributes list shown here have not yet been URL encoded.

Example of a POST request that returns all attributes except specific excluded attributes
HTTP request
POST /analytics/v1/reports/softuti/summary/type/grid?count=2&startIndex=1&excludedAttributes=resources.appName,resources.appVersion HTTP/1.1
Host: daas.api.hp.com
Authorization: Bearer <ACCESS_TOKEN>

HTTP response
{
    "totalResults": 31,
    "startIndex": 1,
    "itemsPerPage": 2,
    "resources": [
        {
            "deviceCount": "105873",
            "appUsageCount": "55160",
            "appUsagePercent": "52.10",
            "appUsageHours": "7900112.50",
            "appAvgUsageTime": "74.62",
            "rankAppUsagePercent": "3",
            "rankAppUsageHrs": "4"
        },
        {
            "deviceCount": "105873",
            "appUsageCount": "54915",
            "appUsagePercent": "51.87",
            "appUsageHours": "9808576.00",
            "appAvgUsageTime": "92.64",
            "rankAppUsagePercent": "4",
            "rankAppUsageHrs": "5"
        }
    ]
}

 

Example of a POST request that returns specific excluded attributes
HTTP request
POST /analytics/v1/reports/softuti/summary/type/grid?count=2&startIndex=1&attributes=resources.appName,resources.appVersion HTTP/1.1
Host: daas.api.hp.com
Authorization: Bearer <ACCESS_TOKEN>

HTTP response
{
    "resources": [
        {
            "appName": "Windows Shell Experience Host",
            "appVersion": "10.0.15063.909"
        },
        {
            "appName": "Internet Explorer",
            "appVersion": "11.00.15063.0"
        }
    ]
}

 

 

 

Default Response Limit

 

To prevent APIs being overwhelmed by requests asking for large amount of data, Proactive Management sets a Default Response Limit on details API requests. When request submissions exceed the Default Response Limit, Proactive Management explicitly replaces it with default limit and responds accordingly. As an API developer, you can set the limits for individual details API to improve overall performance across all APIs and leverage the pagination option. The Default response limit (~1K) is based on the current server configuration and the overall performance of the system.

 

 

Summary vs. Details APIs

 

HP TechPulse Analytics provides two kinds of API’s:

  • Summary APIs. The summary APIs provide aggregated information for certain attributes. The naming convention typically followed has a format of < /analytics/v1/reports/report-name/report-option/type/graph>. The most common form of aggregation provided includes SUM, COUNT, and DISTINCT COUNT on certain attributes, grouped by certain other attributes.

For example, the /analytics/v1/reports/hwinv/deviceType/type/graph provides summary information on the count of number of devices by various device type (i.e. Notebook, Desktop, Tablet, Smartphone etc.).

Example details API
HTTP Request
POST /analytics/v1/reports/hwinv/details/type/grid?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTP response
{
    "totalResults": 11,
    "startIndex": 0,
    "itemsPerPage": 11,
    "resources": [
        {
            "counterId": 134375,
            "deviceName": "device-name",
            "deviceType": "Desktop",
            "deviceMfg": "HP",
            "deviceModel": "HP ProDesk 600 G4 SFF",
            "deviceSn": "device-sn",
            "deviceOs": "Windows 10",
            "dateEnrolled": "09/29/2018",
            "endDate": "03/01/2021",
            "lastOnlineDate": "11/28/2018 at 03:49 AM (UTC)",
            "memory": "24 GB  2667 MHz",
            "graphics": "Intel(R) UHD Graphics 630",
            "processor": "Intel(R) Core(TM) i5-8400 CPU @ 2.80GHz",
            "mfgDate": "01/31/2018",
            "dataAsOfDate": "11/29/2018",
            "deviceOsOriginal": "Windows 10",
            "warStatus": "In warranty",
            "locationcc": "United States",
            "dateListMonth": "Sep 2018",
            "deviceId": "123456",
            "companyName": "company-name",
            "osrelease": "Unknown",
            "osversion": "Unknown",
            "osreleselToggaleEnabled": true
        },
        ... // 11 Records
    ]
}

 

  • Details API. The details API provides detailed information on all attributes. The naming convention typically followed has a format of </analytics/v1/reports/report-name/report-option /type/grid>.

For example, the /analytics/v1/reports/hwinv/details/type/grid provides information on all attributes of hardware inventory exposed in Proactive Management.

 

Example summary API
HTTP Request
POST /analytics/v1/reports/hwinv/deviceByOS/type/graph?filter=devicetype eq "Desktop" HTTP/1.1
Host: daas.api.hp.com
Content-Type: application/json
Authorization: Bearer Access Token

HTTP response
{
    "totalResults": 3,
    "startIndex": 0,
    "itemsPerPage": 3,
    "resources": [
        {
            "deviceOs": "Windows 10",
            "total": 8,
            "data": null,
            "osRelease": null,
            "dataForOSRelease": false,
            "osReleaseData": [
                {
                    "deviceOs": "Windows 10",
                    "total": 3,
                    "data": null,
                    "osRelease": "10.0.17134.407",
                    "dataForOSRelease": true,
                    "osReleaseData": null,
                    "deviceos_original_latest": null,
                    "deviceOsMajorVersion": null,
                    "productOs": null,
                    "osreleselToggaleEnabled": false
                },
                ...// 4 records
            ],
            "deviceos_original_latest": null,
            "deviceOsMajorVersion": "Windows",
            "productOs": null,
            "osreleselToggaleEnabled": true
        },
        ...// 2 records
    ]
}

 

 

 

Error Messages

Authorization errors

When HP DaaS encounters an error in an authorization request, either with the /oauth/v1/authorize request itself or the processing of the request, it will respond in one of two ways:

If the redirect URI is invalid or otherwise unusable, or if the client ID is missing or invalid, HP DaaS will not be able to send an error back to your application. In this case, it will display an error message directly to the end user.

Otherwise, HP DaaS will redirect to the redirect URI, appending the error and error_description query parameters. For example, HP DaaS will call the following URL if an invalid scope is requested on the authorization URL:

Invalid scope

http://redirect-uri/?error=invalid_scope&error_description=The%20requested%20scope%20is%20invalid,%20unknown,%20or%20malformed&state=daas_session
 
Invalid redirect-uri

http://redirect-uri/?error=invalid_request&error_description=Invalid%20redirect_uri%20parameter&state=daas_session

 

Token errors

Errors returned by the oauth/v1/token endpoint typically use an HTTP status of 400; the body is a JSON document consisting of error description.

For example:

Invalid response
{ 
  "Error": "Incorrect or missing authorization code" 
}

 

Possible values for error code and description are as given below:

Error Code
Error Description
400
Incorrect or missing authorization code.
401
Unauthorized
402
Invalid clientId
500
Internal Server Error.