Tivoli Endpoint Manager Analytics API Reference PDF

Tivoli Endpoint Manager Analytics http://damashii.bigfix.
com/help/scm/api
Tivoli Endpoint Manager Analytics

Reports
Saved Reports
Security and Compliance
Overview
Checklists
Checks
Computers
Computer Groups
Check Results
Exception Results
Last Import at 05/20/2011 12:26 PM
Management
General
Computer Groups
Computer Properties
Datasources
Imports
Roles
Users
Exceptions
Account
bigfix
Preferences
Logout
Help
About
API
Tivoli Endpoint Manager: Security and Configuration Analytics supports a HTTP-based data API. Using this API, you make HTTP GET requests to the Tivoli Endpoint Manager
Analytics server, and receive responses containing JSON-encoded representation of the requested resource. Using URL query parameters, you can apply filters to the data, specify
what order it should be returned in, and select a subset of columns or rows.
Resources
Resources are sources of specific information, each of which is referenced by a distinct URI. There are two types of resources, collections and elements.
A collection URI follows the pattern /api/scm/:resource/ where :resource uses the plural form. For example, the collection URI for computers would be
http://damashii.bigfix.com/api/scm/computers/
An element URI follows the pattern /api/scm/:resource/:id where :id is the unique identifier for the element being addressed. For example, the element URI for the computer
with ID 42 would be http://damashii.bigfix.com/api/scm/computers/42
Authentication
Each Tivoli Endpoint Manager Analytics user is assigned an unique API access token. This token must accompany every API request as the token parameter. If the token is invalid,
the server will block the request and respond with HTTP code 401. A user may view their API token in the Account Preferences screen of the Tivoli Endpoint Manager Analytics
interface.
Request Format
Parameters
API options are specified using URL query parameters. The query parameters are formatted according to HTTP browser form submission conventions. Parameters will vary
depending on the resource type being addressed.
Some parameter values are logically lists (arrays) of multiple items. These "array valued" parameters are specified by providing one URL parameter for each item, with the name of
the parameter suffixed by [] (open and close square brackets). For example, to specify the values "Joe" and "Susan" for the "names" parameter, the URL query string would be
names[]=Joe&names[]=Susan. (This is the format that the jQuery function jQuery.param generates.)
Common Parameters
Parameters applicable to either a collection or element resource.
ccoolluummnnss
1 of 11 5/20/11 3:22 PM
Tivoli Endpoint Manager Analytics http://damashii.bigfix.com/help/scm/api
The columns parameter is an array-valued parameter specifying which columns to retrieve. See the documentation for each resource type to find out which columns are supported.
If no columns parameter is specified, a set of default columns will be retrieved. The set of default columns are subject to change with each release.
Examples:
Retrieve the name and version columns:
columns[]=name&columns[]=version
Some resource URLs support retrieving data of nested records inline with the main record. For example, you may want to get data about the check associated with each check
result. In those cases, you can specify which columns from the association you want by prefixing each of them by the name of the association followed by a period:
Retrieve the name column from the base record and time column from an associated record:
columns[]=name&columns[]=rollup_history.time
Only one level of nested retrieval is supported in a single request; to retrieve data for data nested more than one level deep, make multiple requests to the appropriate resources
URLs.
ttiimmee
The time parameter specifies the time range desired for historical data. It is an array-valued parameter with exactly two elements, the starting and ending time encoded using the
ISO 8601 datetime format.
Example:
Retrieve data from 2011:
time[]=2011-01-01T00:00:00+00:00&time[]=2011-12-31T23:59:59+00:00
The rollup and rollup_history associations and the state column and history association of check and exception results respect the time parameter. Additionally, if the time
parameter is specified, the exceptions API will reflect the last imported state of exceptions, whereas if the time parameter is omitted, the current state is returned, which may differ if
exceptions have been modified in the management screens since the last import.
The data for other resources and associations always reflect the last imported value, and are not affected by the time parameter.
Collection Parameters
In addition to the common parameters listed above, a collection resource supports the following parameters.
ccrriitteerriiaa
The criteria parameter allows you to retrieve records which match specific conditions. The criteria parameter is expected to conform to the following JSON structure:
<criteria> ::= <left-brace> <boolean-operator><colon> <left-bracket> <criterion> [ { <comma> <criterion> }... ] <right-bracket> <right-brace>
<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> ::= <json-array> | <json-string> | <json-number> | <json-null>
The valid operators will depend on the datatype of the <column> being filtered.
string: '=', '!=', 'contains', 'not_contains', 'begins_with', 'ends_with'

integer: '=', '!=', '<', '<=', '>', '>='
float: '=', '!=', '<', '<=', '>', '>='
datetime: '=', '!=', '<', '<=', '>', '>='
date: '=', '!=', '<', '<=', '>', '>='
boolean: '=', '!='
set: 'in', 'not_in'
Example:
Retrieve computers whose name begins with 'R23PO' AND compliance is less than 100
{ and: [ ["name", "begins_with", "R23PO"], ["rollup.compliance", "<", 100] ] }
You may nest criteria at most once.
2 of 11 5/20/11 3:22 PM
Example:
Retrieve computers whose operating system contains "xp" OR the last seen date within a specific date range
{ or: [ ["os", "contains", "xp"], { and: [ ["last_seen", ">", "1970-01-01T00:00:00+00:00"], ["last_seen", "<", "1970-01-02T00:00:00+00:00"] ] } ] }
oorrddeerr
The order parameter is an array-valued parameter specifying how to sort the returned data. The default direction for sorting columns is ascending. To specify a descending sort,
you must append desc to the column name.
Examples:
Order first by name ascending, then version descending
order[]=name&order[]=version desc
lliimmiitt
The limit parameter specifies the number of rows to retrieve. If omitted, all rows will be retrieved. This does not affect the total property of the top-level JSON object.
ooffffsseett
The offset parameter specifies the number of rows to skip. It can be used in conjunction with the limit parameter to paginate results.
Examples:
Retrieve rows 2051-2100
limit=50&offset=2050
Response Format
The API response body is a JSON object. The exact format will depend on the resource type.
Collection Format
The collection response format contains a list of resource instances. It consists of a JSON object with two properties: total, whose integer value gives the total number of rows for
that resource, without regard to the limit parameter; and rows, an array of objects representing the resource instances. Each element will conform to the JSON schema for that
resource; see the "Schemas" section below for details.
Element Format
The element response format represents a single resource instance. It is a single JSON object conforming to the JSON schema for that resource.
Errors
If a server side processing error occurs, the API will return a JSON object with a single property error, whose value contains the error message.
Cross-domain Requests
The Tivoli Endpoint Manager Analytics API supports Cross Origin Resource Sharing and JSONP for cross-domain requests.
Schemas
For each resource type provided by the API, a corresponding JSON schema is provided that specifies the structure of that resource type. These schemas can be downloaded from
your Tivoli Endpoint Manager Analytics server:
http://[your.server.domain]/api/schemas/scm/[resource].json
For example, the exception schema is at
http://damashii.bigfix.com/api/schemas/scm/exception.json
The schema shows you what columns are available and what each column means. It follows the JSON schema draft standard.
API Bookmarklet
For exploring the API and testing the various parameters, the following bookmarklet may be useful. Drag it to your bookmark bar, and when you are on an SCM list report, you can
3 of 11 5/20/11 3:22 PM
click it to see the URL and resulting data for the corresponding API call. Note that if you wish to use the resulting URL outside of your browser, you will need to include your API
token as well.
Inspect API
Resources
Security and Configuration Analytics supports the following data API resources.
Overview
URLs
/api/scm/overview (show)
Retrieves information about the entire deployment.
Associations
rollup_history (array)
An array of rollups, ordered by time. Each element contains aggregated statistics about the compliance state of all visible computers across all content. If a range of times is
given, the history will be limited to the rollups which cover that range.
Element Columns
time (date-time string)

The time at which the rollup statistics were calculated.
count_computers (integer)
The number of computers in the deployment.
count_computer_groups (integer)
The number of root computer groups in the deployment.
count_checklists (integer)
The number of checklists in the deployment.
count_checks (integer)
The number of checks in the deployment.
count_quartile_0 (integer)
The number of computers that are between 0% and 24% compliant across all subscribed checks.
The number of computers that are 100% compliant across all subscribed checks.
total_passed (integer)
The number of compliant, non-excepted results.
total_excepted_passed (integer)
The number of compliant, excepted check results.
total_excepted_failed (integer)
The number of non-compliant, excepted check results.
total_failed (integer)
The number of non-compliant, non-excepted check results.
total_na (integer)
The number of non-applicable check results.
total_compliant (integer)
The sum of total_passed + total_excepted_passed + total_excepted_failed.
total_applicable (integer)
The sum of total_passed + total_failed + total_excepted_passed + total_excepted_failed.
total_by_states (integer)
The sum of total_passed + total_failed + total_excepted_passed + total_excepted_failed + total_na.
compliance_percentage (integer or null)
Equal to floor(total_compliant / total_applicable) 100, or null if no results are applicable
Exceptions
Schema
/api/schemas/scm/exception.json
URLs
/api/scm/exceptions (index)
Retrieves information about all exceptions accessible to the API user.
4 of 11 5/20/11 3:22 PM
/api/scm/exceptions/:id (show)
Retrieves information about a specific exception identified by ID.
Columns
id (integer)
The database ID of the exception.
version (integer)
The version of the exception. Begins at 0 and is incremented by one each time the exception is updated.
updated_at (date-time string)
The time the exception was last updated.
expiration_date (string or null)
The exception expiration date, or null if it never expires.
reason (string)
The reason given by the user for the exception.
Associations
user
The user who created or last edited the exception.
checklist
The targeted checklist, or null if targeted by checks. All base columns from the checklist schema are also available via this association (for example, checklist.name).
checks
Targeted checks, or null if targeted by checklist. All base columns from the check schema are also available via this association (for example, checks.name).
computer_group
Targeted computer group, or null if targeted by computers. All base columns from the computer group schema are also available via this association (for example,
computer_group.name).
computers
Targeted computers, or null if targeted by computer group. All base columns from the computer schema are also available via this association (for example, computers.name).
Computer Groups
Schema
/api/schemas/scm/computer_group.json
URLs
/api/scm/computer_groups (index)
Retrieves information about the root computer groups accessible to the API user.
/api/scm/computer_groups/:id (show)
Retrieves information about a specific computer group identified by ID.
/api/scm/computer_groups/:id/children (index)
Retrieves information about children of a specific computer group.
/api/scm/checklists/:id/computer_groups (index)
Retrieves information about computer groups, including checklist-specific rollup data.
/api/scm/checks/:id/computer_groups (index)
Retrieves information about computer groups, including check-specific rollup data.
Columns
id (integer)
The database ID of the computer group.
The time the computer group was last updated.
name (string)
The name of the computer group.
Associations
An array of rollups, ordered by time. Each element contains aggregated statistics about the compliance state of the computer group across all content, or across a single
checklist or single check specified in the request path. If a range of times is given, the history will be limited to the rollups which cover that range.
Element Columns

The number of computers in the computer group. If the request path specifies a single checklist or check, the count is also limited to subscribed computers.
count_computer_groups (integer)
The number of child computer groups. This column is not available if the request path specifies a single checklist or check.
5 of 11 5/20/11 3:22 PM
The number of checklists in the deployment. This column is not available if the request path specifies a single checklist or check.
The number of checks in the deployment, or in the checklist specified in the request path. This column is not available if the request path specifies a single checklist.
The number of computers that are between 0% and 24% compliant across all subscribed checks, or across the checks in the checklist specified in the request path.
This column is not available if the request path specifies a single check.
The number of computers that are 100% compliant across all subscribed checks, or across the checks in the checklist specified in the request path. This column is not
available if the request path specifies a single check.
The number of compliant, non-excepted results for the appropriate computers and checks.
The number of compliant, excepted results for the appropriate computers and checks.
The number of non-compliant, excepted results for the appropriate computers and checks.
The number of non-compliant, non-excepted results for the appropriate computers and checks.
total_na (integer)
The number of non-applicable results for the appropriate computers and checks.
rollup
A single rollup having the same properties as the rollup_history association. If no time parameter is given, the most recent rollup is returned. If a range of times is given, the
most recent rollup within that range is returned. If a single time is given, the rollup closest in time is returned.
Computers
Schema
/api/schemas/scm/computer.json
URLs
/api/scm/computers (index)
Retrieves information about all computers accessible to the API user.
/api/scm/computers/:id (show)
Retrieves information about a specific computer identified by ID.
/api/scm/computer_groups/:id/computers (index)
Retrieves information about the members of a specific computer group.
/api/scm/checklists/:id/computers (index)
Retrieves information about computers subscribed to a specific checklist.
Columns
id (integer)
The database ID of the computer.
remote_id (integer)
The unique identifier of the computer in the source database.
last_seen (date-time string)
The time new data from the computer was last received.
os (string, array, or null)
OS
dns_name (string, array, or null)
DNS Name
name (string, array, or null)
Computer Name
ip_address (string, array, or null)
6 of 11 5/20/11 3:22 PM
IP Address
Associations
An array of rollups, ordered by time. Each element contains aggregated statistics about the compliance state of the computer across all subscribed checklists, or across a
single checklist specified in the request path. If a range of times is given, the history will be limited to the rollups which cover that range.
Element Columns

The number of checklists subscribed to by this computer. This column is not available if the request path specifies a single checklist.
The total number of checks in all the checklists subscribed to by this computer, or in the checklist specified in the request path.
The number of compliant, non-excepted checks.
The number of compliant, excepted checks.
The number of non-compliant, excepted checks.
The number of non-compliant, non-excepted checks.
total_na (integer)
The number of checks that are not applicable to this computer.
The sum of total_passed + total_failed + total_excepted_passed + total_excepted_failed + total_na = count_checks.
Equal to floor(total_compliant / total_applicable) 100, or null if no checks are applicable
rollup
Checklists
Schema
/api/schemas/scm/checklist.json
URLs
/api/scm/checklists (index)
Retrieves information about all checklists.
/api/scm/checklists/:id (show)
Retrieves information about a specific checklist identified by ID.
/api/scm/computer_groups/:id/checklists (index)
Retrieves information about checklists, including computer-group specific rollup data.
/api/scm/computers/:id/checklists (index)
Retrieves information about checklists to which a specific computer is subscribed.
Columns
id (integer)
The database ID of the checklist.
site_tag (string)
The unique identifier of the checklist's site in the source database.
The time the checklist was last updated.
name (string)
The name of the checklist.
Associations
An array of rollups, ordered by time. Each element contains aggregated statistics about the compliance state of the checklist across all computers visible to the user, or
across a single computer or group of computers specified in the request path. If a range of times is given, the history will be limited to the rollups which cover that range.
Element Columns
7 of 11 5/20/11 3:22 PM

The number of computers subscribed to the checklist. If the request path specifies a computer group, the count is also limited to computers in that group. This column
is not available if the request path specifies a single computer.
The number of checks in checklist.
The number of computers that are between 0% and 24% compliant across the checks in the checklist. This column is not available if the request path specifies a
single computer.
single computer.
single computer.
single computer.
The number of computers that are 100% compliant across the checks in the checklist. This column is not available if the request path specifies a single computer.
The number of compliant, non-excepted results for the appropriate computers and checks.
The number of compliant, excepted results for the appropriate computers and checks.
The number of non-compliant, excepted results for the appropriate computers and checks.
The number of non-compliant, non-excepted results for the appropriate computers and checks.
total_na (integer)
The number of non-applicable results for the appropriate computers and checks.
rollup
Checks
Schema
/api/schemas/scm/check.json
URLs
/api/scm/checks (index)
Retrieves information about all checks.
/api/scm/checks/:id (show)
Retrieves information about a specific check identified by ID.
/api/scm/checklists/:id/checks (index)
Retrieves information the checks belonging to a specific checklist.
/api/scm/computer_groups/:id/checks (index)
Retrieves information about checks, including computer-group specific rollup data.
Columns
id (integer)
The database ID of the check.
remote_id (string or null)
The unique identifier of the check. This is the value of the 'x-fixlet-scm-id' custom MIME field.
updated_at (string or null)
The time the check was last updated.
name (string or null)
The name of the check.
checklist_name (string or null)
The name of the check's checklist.
8 of 11 5/20/11 3:22 PM
category (string or null)

Category
source (string or null)
Source
source_id (string or null)
Source ID
source_release_date (string or null)
Source Release Date
source_severity (string or null)
Source Severity
description (string or null)
Description
disa_group_title (string or null)
DISA Group Title
disa_ia_controls (string or null)
DISA IA Controls
disa_rule_id (string or null)
DISA Rule ID
disa_responsibility (string or null)
DISA Responsibility
disa_vulid (string or null)
DISA Vulid (STIG-ID)
disa_documentable (string or null)
DISA Documentable
disa_false_positives (string or null)
DISA False Positives
disa_false_negatives (string or null)
DISA False Negatives
disa_potential_impacts (string or null)
DISA Potential Impacts
disa_check_content (string or null)
DISA Check Content
disa_documentable_explanation (string or null)
DISA Documentable Explanation
disa_fix_text (string or null)
DISA Fix Text
xccdf_profile_id (string or null)
XCCDF Profile ID
xccdf_rule_id (string or null)
XCCDF Rule ID
xccdf_rule_weight (number or null)
XCCDF Rule Weight
xccdf_benchmark_id (string or null)
XCCDF Benchmark ID
Associations
An array of rollups, ordered by time. Each element contains aggregated statistics about the compliance state of the check across all computers visible to the user, or across a
particular computer group specified in the request path. If a range of times is given, the history will be limited to the rollups which cover that range.
Element Columns

The number of computers subscribed to this check's checklist.
The number of compliant, non-excepted computers.
The number of compliant, excepted computers.
The number of non-compliant, excepted computers.
The number of non-compliant, non-excepted computers.
total_na (integer)
The number of computers for which the check is not applicable.
9 of 11 5/20/11 3:22 PM
The sum of total_passed + total_failed + total_excepted_passed + total_excepted_failed + total_na = count_computers.

Equal to floor(total_compliant / total_applicable) 100, or null if no computers are applicable
rollup
desired_values (array)
The desired values for this check.
Element Columns
name (string)
The machine-readable name of this desired value.
human_name (string)
The human-readable name of this desired value.
description (string or null)
The description of this desired value.
type (string)
The type of this desired value.
default_value (string or null)
The value that the desired value takes if not customized.
desired_value (string or null)
The value set as the desired value. A null value can indicate that the desired value is null, or that no desired value has been set. Use the 'customized' property to
distinguish between these two cases.
current_value (string or null)
The current desired value. Equal to desired_value if customized, otherwise default_value.
customized (boolean)
Whether or not a custom desired value has been set.
Check Results
Schema
/api/schemas/scm/check_result.json
URLs
/api/scm/check_results (index)
Retrieves information about all check results.
/api/scm/checklists/:id/check_results (index)
Retrieves information about results from a specific checklist.
/api/scm/checks/:id/check_results (index)
Retrieves information about results from a specific check.
/api/scm/computer_groups/:id/check_results (index)
Retrieves information about results from a specific computer group.
/api/scm/computer/:id/check_results (index)
Retrieves information about results from a specific computer.
Columns
state (string)
The current state of the check on the computer.
Associations
check
The check for which this is a result. All base columns from the check schema are also available via this association (for example, check.name).
computer
The computer for which this is a result. All base columns from the computer schema are also available via this association (for example, computer.name).
history (array)
The history of results for the check on the computer.
Element Columns
valid_from (date-time string)

The inclusive start time of this historical state.
valid_to (date-time string)
The exclusive end time of this historical state. The value "9999-12-31T23:59:59Z" is a special value indicating that this historical state is the current state.
state (string)
The state of the check on the computer during the time period [valid_from, valid_to).
measured_values (array)
The measured values for this check on the computer.
10 of 11 5/20/11 3:22 PM
Element Columns
name (string)
The name of this measured value.
type (string)
The type of this measured value.
value (string, array, or null)
The measured value. If the measured value is plural, this is an array. If a value has not been reported or if the property is inactive, it is null.
Exception Results
Schema
/api/schemas/scm/exception_result.json
URLs
/api/scm/exception_results (index)
Retrieves information about all exception results.
/api/scm/checklists/:id/exception_results (index)
Retrieves information about results from a specific checklist.
/api/scm/checks/:id/exception_results (index)
Retrieves information about results from a specific check.
/api/scm/computer_groups/:id/exception_results (index)
Retrieves information about results from a specific computer group.
/api/scm/computer/:id/exception_results (index)
Retrieves information about results from a specific computer.
Columns
state (string)
The current state of the check/computer/exception combination.
Associations
check
The check for which this is a result. All base columns from the check schema are also available via this association (for example, check.name).
computer
The computer for which this is a result. All base columns from the computer schema are also available via this association (for example, computer.name).
exception
The exception for which this is a result. All base columns from the exception schema are also available via this association (for example, exception.reason).
history (array)
The history of results for the check/computer/exception combination.
Element Columns
valid_from (date-time string)

The inclusive start time of this historical state.
valid_to (date-time string)
The exclusive end time of this historical state. The value "9999-12-31T23:59:59Z" is a special value indicating that this historical state is the current state.
state (string)
The state of the check/computer/exception combination during the time period [valid_from, valid_to).
11 of 11 5/20/11 3:22 PM

Tivoli Endpoint Manager Analytics API Reference PDF

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Tivoli Endpoint Manager Analytics API Reference PDF

Загружено:

Авторское право:

Доступные форматы

Tivoli Endpoint Manager Analytics http://damashii.bigfix.

Tivoli Endpoint Manager Analytics

Parameters applicable to either a collection or element resource.

Retrieve the name and version columns:

Retrieve data from 2011:

string: '=', '!=', 'contains', 'not_contains', 'begins_with', 'ends_with'

{ and: [ ["name", "begins_with", "R23PO"], ["rollup.compliance", "<", 100] ] }

You may nest criteria at most once.

Order first by name ascending, then version descending

Retrieve rows 2051-2100

For example, the exception schema is at

time (date-time string)

time (date-time string)

time (date-time string)

time (date-time string)

category (string or null)

time (date-time string)

The sum of total_passed + total_failed + total_excepted_passed + total_excepted_failed + total_na = count_computers.

valid_from (date-time string)

valid_from (date-time string)

Вам также может понравиться