Data API

The Data Web Service in TrueSight Capacity Optimization exposes its functionality via a RESTful (Representational State Transfer) API, and enables you to work with the following types of TrueSight Capacity Optimization data:

If you have installed the BMC License Usage Collection Utility to identify the number of product licenses, you can use the License Utility REST API to connect to the TrueSight Capacity Optimization server and generate the license report. For more details, see License Utility REST API.

Before you begin

  • Ensure that you have valid user credentials in Base64-encoded format for the Authorization HTTP header. For more details, see Restful web services authentication.
  • Ensure that your user role has the Enable access to Data API activity (API_DATA) assigned to it. The out-of-the-box role API-Client has access to all the APIs by default. For more information about managing roles and activities, see Adding and managing roles.

Importing data from custom sources through data formats

This section explains TrueSight Capacity Optimization data formats that are used to import data from custom sources.

As explained in DWH information model, the two main types of information in TrueSight Capacity Optimization are Time Series (TS) and Custom Structures (CS).

This results in two types of data – TS and CS – with three different supported formats: CSV, RS, and XML. The RS (RecordSet) format is identical to CSV in structure, but it is produced by a query over a database.

The following sections discuss these TrueSight Capacity Optimization Data Formats in further detail.

Time Series (TS) format

This format is used to transmit data relative to a time series, i.e. a series of historical data related to the same measured object.

The measured object is identified, as usual in TrueSight Capacity Optimization, by the following identifiers:

  • entity name: system or business driver
  • resource name: name of the measured object (metric)
  • sub-resource name: name of the subobject (subset of resource)
  • location name: location

The following additional details are also provided:

  • Original data source identifiers: For example, the prefix ds_, for lookup purposes.
  • A set of samples: For example, time/duration/value.

TS/CSV format


2008-05-22 23:59:00;60;;MEM_FREE;GLOBAL;2.22E7;
2008-05-22 23:58:00;60;;CPU_UTIL;GLOBAL;0.002;
2008-05-22 23:59:00;60;;SWAP_SPACE;GLOBAL;8.55E8;

This format is identical to the v2.x OpenETL format and to RecordSet (output of a SQL query). The column order is not relevant.

TS/XML format

Example 1

	<?xml version="1.0" encoding="UTF-8"?>
	<TIMESERIES xmlns:xsi=""
         version="1.0" xsi:noNamespaceSchemaLocation="timeseries.xsd">
                          <POINT><TS>2008-06-09 17:39:00</TS><DURATION>60</DURATION><VALUE>84</VALUE></POINT>
		            ... other series...

Example 2: TimeSeriesMessage

<?xml version="2.0" encoding="UTF-8"?>
<TIMESERIES xmlns:xsi="" version="2.0" xsi:noNamespaceSchemaLocation="timeseries.xsd">
        2012-09-12 10:36:39;3600;0.22;


  • This format also allows to specify the source IDs, as it can be transmitted using the Data API without the mediation of an ETL task.
  • SRCID is used by external sources without mediation.
  • COMPONENTID is used internally to identify Scheduler or DatAccumproducing data.

Custom Structure (CS) format

This format is used to transmit data relative to a Custom Structure Table, that is, a set of rows in a table with custom columns.

A Custom Structure table is defined by the following elements:

  • TABLENAME: Name of the table.
  • COLUMNTYPES: Types of columns in the table (NUMBER, DATE, STRING).
  • KEYCOLUMN: The key column for the table.

 CS format also provides the following additional information:

 BEHAVIOUR: Specifies how to use transmitted data, in INPUT case; can be TRUNCATE, APPEND, DELETE, UPDATE.

  • SOURCE: Specifies the sender of the data (optional).

CS/CSV format




This format includes a configuration header (rows preceded by #) that explains the destination table, behavior, key column.

 CS/XML format

Example 1: Version 1.0

<?xml version="1.0" encoding="UTF-8"?>
<CUSTOMSTRUCTURE xmlns:xsi="" version="1.0"
	      <EXTRACTIONDATE><![CDATA[2008-06-10 12:32:48]]></EXTRACTIONDATE>
	      <DESCRIPTION><![CDATA[My Description]]></DESCRIPTION>
 	      <RECORD> <!- a single record-->
		            ... other records ...

Example 2: Version 2.0 - CustomStructureMessage

<?xml version="2.0" encoding="UTF-8"?>
<CUSTOMSTRUCTURE xmlns:xsi="" version="2.0" xsi:noNamespaceSchemaLocation="customstructure.xsd">
<INFO EXTRACTIONDATE="2012-09-24 12:39:03" TABLENAME="TableName" BEHAVIOUR="APPEND" MSGTYPE="msgtype">
<DESCRIPTION>< ![CDATA<a href=!...\]></DESCRIPTION> <"/>\--optional-\->
<COLUMN type="NUMBER" isPk="true">name</COLUMN>
<COLUMN type="DATE">foo</COLUMN>
<COLUMN type="NUMBER">value</COLUMN>

Where to go from here

Working with the Data API

Was this page helpful? Yes No Submitting... Thank you