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:

TimeSeriesData
CustomStructureData
DataMart
Indicator

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-API.

Before you begin

Ensure that the following requirements are met:

The appropriate read or write activity is assigned to users to access the API. For more information, see Adding and managing roles.
Valid user credentials or a bearer token is available for authentication. For more information, see Accessing the public APIs.

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 C ustom 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

Example

TS;DURATION;SYSNM;OBJNM;SUBOBJNM;VALUE;DS_SYSNM
2008-05-22 23:59:00;60;192.168.100.41;MEM_FREE;GLOBAL;2.22E7;192.168.100.41
2008-05-22 23:58:00;60;192.168.100.41;CPU_UTIL;GLOBAL;0.002;192.168.100.41
2008-05-22 23:59:00;60;192.168.100.41;SWAP_SPACE;GLOBAL;8.55E8;192.168.100.41

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

<TIMESERIES xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="1.0" xsi:noNamespaceSchemaLocation="timeseries.xsd">
<TIMESERIES>
<COMPONENTID>ID</COMPONENTID>
<SRCID>ID</SRCID>
                <SERIESLIST>
        <SERIES>
                        <INFO>
<SYSNM><![CDATA[TestSysNm]]></SYSNM>
                        <DS_SYSNM><![CDATA[1123]]></DS_SYSNM>
<OBJNM><![CDATA[CPU_UTIL]]></OBJNM>
<SUBOBJNM><![CDATA[GLOBAL]]></SUBOBJNM>
                        <LOCATIONNM><![CDATA[UNKNOWN]]></LOCATIONNM>
</INFO>
                        <DATA>
                          <POINT><TS>2008-06-09 17:39:00</TS><DURATION>60</DURATION><VALUE>84</VALUE></POINT>
             ...
                </DATA>
                 </SERIES>
                 <SERIES>
            ... other series...
         </SERIES>
        </SERIESLIST>
</TIMESERIES>

Example 2: TimeSeriesMessage

<?xml version="2.0" encoding="UTF-8"?>
<TIMESERIES xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0" xsi:noNamespaceSchemaLocation="timeseries.xsd">

<DATASOURCE COMPONENTID="12" SRCID="44" MSGSTAT="" />

<SERIESLIST>
    <SERIES STAGESTATUS="RAW" STATISTIC="AVGVALUE" SYSNM="testSysNm" OBJNM="OBJnm" SUBOBJNM="SubOBJNM" GOLEVELS="GOLEVELS">
        <![CDATA[
        2012-09-12 10:36:39;3600;0.22;
        ]]>
    </SERIES>
</SERIESLIST>

</TIMESERIES>

Note

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

example

#TABLENAME=MYTABLE
#BEHAVIOUR=APPEND
#KEYCOLUMN=A
#COLUMNTYPES=NUMBER;DATE;STRING
A;B;C
value1;value2;value3
value1;value2;value3
value1;value2;value3
...

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

<CUSTOMSTRUCTURE xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"
         xsi:noNamespaceSchemaLocation="customstructure.xsd">
<COMPONENTID>ID</COMPONENTID>
         <SRCID>ID</SRCID>
         <INFO>
              <TABLENAME><![CDATA[MYTABLE]]></TABLENAME>
              <BEHAVIOUR><![CDATA[APPEND]]></BEHAVIOUR>
      <KEYCOLUMN><![CDATA[A]]></KEYCOLUMN>
      <COLUMNTYPES>
<A><![CDATA[NUMBER]]></A>
<B><![CDATA[DATE]]></B>
<C><![CDATA[STRING]]></C>
      </COLUMNTYPES>
      <EXTRACTIONDATE><![CDATA[2008-06-10 12:32:48]]></EXTRACTIONDATE>
      <SOURCE type="SQL"><![CDATA[SELECT * FROM OUTER_TABLE]]></SOURCE>
      <DESCRIPTION><![CDATA[My Description]]></DESCRIPTION>
     </INFO>
  <DATA>
       <RECORD> <!- a single record-->
                <A><![CDATA[value1]]></A>
<B><![CDATA[value2]]></B>
<C><![CDATA[value3]]></C>
        </RECORD>
              <RECORD>
            ... other records ...
      </RECORD>
  </DATA>
</CUSTOMSTRUCTURE>

Example 2: Version 2.0 - CustomStructureMessage

<?xml version="2.0" encoding="UTF-8"?>
<CUSTOMSTRUCTURE xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0" xsi:noNamespaceSchemaLocation="customstructure.xsd">

<DATASOURCE COMPONENTID="4" SOURCE="DATAHUB" SRCID=""/>

<INFO EXTRACTIONDATE="2012-09-24 12:39:03" TABLENAME="TableName" BEHAVIOUR="APPEND" MSGTYPE="msgtype">
<DESCRIPTION>< ![CDATA<a href=!...\]></DESCRIPTION> <"/>\--optional-\->
<COLUMNS>
<COLUMN type="NUMBER" isPk="true">name</COLUMN>
<COLUMN type="DATE">foo</COLUMN>
<COLUMN type="NUMBER">value</COLUMN>
</COLUMNS>
</INFO>

<DATA>
<\!\[CDATA\[
val1;val2;val3
val1a;val2a;val3a
val1s;val2s;val3s
val1d;val2d;val3d
\]\]>
</DATA>
</CUSTOMSTRUCTURE>

Where to go from here

Working-with-the-Data-API