Data API

The Data Web Service in BMC Helix Capacity Optimization exposes its functionality via a RESTful (Representational State Transfer) API, and enables you to work with the following types of 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 API to connect to the BMC Helix 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 your user role to access the API. For more information, see Configuring user roles and access groups.
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

BMC Helix Capacity Optimization uses the following data formats to import data from custom sources: Time Series (TS) and C ustom Structures (CS) as explained in DWH information model.

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 data formats in 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 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