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

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

Comments