{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":504,"path":"api-reference/rest-apis/dcim-metric-data-feed-api.md","title":"DCIM Metric Data Feed API","bundle":null,"doc_type":null,"release":"australia","body":"\n# DCIM Metric Data Feed API\n\nThe DCIM Metric Data Feed API provides an endpoint to accept Data Center Infrastructure Management \\(DCIM\\) metric data from an external system and store the data in a MetricBase database.\n\nThis API receives near real-time metric data such as temperature, humidity, and power usage.\n\nThis API can be extended for use with a chosen external system by implementing the scripted extension point TNIDCIMFeedParser. The default implementation TNIDCIMFeedParserImpl can be used as an example. For more information about extension points, see [Using extension points to extend application functionality](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/web-services/extension-points.md).\n\nThis API is included in the Network Inventory Advanced application, which is available on the ServiceNow Store. This API also requires the MetricBase plugin \\(com.snc.clotho\\).\n\nThe calling user must have the sn\\_ni\\_adv.metric\\_integrator role.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## DCIM Metric Data Feed - POST /sn\\_ni\\_adv/dcim/feed/\\{vendorname\\}\n\nStores metric data such as temperature, humidity, and power usage into MetricBase.\n\nBy default, this endpoint can be used to store data about the following types of configuration items \\(CIs\\):\n\n- Circuit \\[cmdb\\_ci\\_circuit\\]\n- Cabinet \\[cmdb\\_ci\\_container\\_cabinet\\]\n- Cage \\[cmdb\\_ci\\_cage\\]\n- Data Center \\[cmdb\\_ci\\_datacenter\\]\n- Data Center Zone \\[cmdb\\_ci\\_zone\\]\n\nTo use this endpoint with additional CI types, [create metric definitions](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/set-up-data-monitoring.md) and implement the scripted extension point TNIDCIMFeedParser.\n\n### URL format\n\nDefault URL: `/api/sn_ni_adv/dcim/feed/{vendorname}`\n\n### Supported request parameters\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nvendorname\n\n\n\nName of the external system to receive metric data from. When using the default implementation of this API, this value is `equinix`. When using this API with other external systems, the **vendorname** used here must be included in your implementation of the TNIDCIMFeedParser extension point.\n\nData type: String\n\n
|Name|Description|\n|----|-----------|\n|None| |\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\ndata\n\n\n\nRequired. The data to store in MetricBase. Data type: Object\n\n**Note:** The elements that must included in this object vary based on the **type** parameter and the configuration item type, such as datacenter or circuit.\n\n```\n\"data\": {\n \"apparentPower\": {Object},\n \"asset\": {Object},\n \"cabinet\": \"String\",\n \"cabinetRating\": {Object},\n \"cage\": \"String\",\n \"contractualPower\": {Object},\n \"ibx\": \"String\",\n \"kilowattHour\": {Object},\n \"peakLastSevenDays\": {Object},\n \"peakLastSevenDaysRatio\": {Object},\n \"powerConsumptionToContractual\": {Object},\n \"powerFactor\": {Object},\n \"reading\": {Object},\n \"readingTime\": \"String\",\n \"realPower\": {Object},\n \"soldCurrent\": {Object},\n \"tag\": {Object}\n}\n```\n\n
\n\ndata.apparentPower\n\n\n\nApparent power data in kilovolt-amperes. Required when the **type** parameter is `power`.Data type: Object\n\n```\n\"apparentPower\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.apparentPower.unit\n\n\n\nUnit of measurement. The only accepted value is `kVA`.Data type: String\n\n
\n\ndata.apparentPower.value\n\n\n\nThe recorded kilovolt-amperes reading.Data type: String\n\n
\n\ndata.asset\n\n\n\nAsset data. Required for circuits when the **type** parameter is `metered-power` or `power`. Required for cabinets, cages, and zones when the **type** parameter is `environmental`. Data type: Object\n\n```\n\"asset\": {\n \"id\": \"String\",\n \"level\": \"String\",\n \"type\": \"String\"\n}\n```\n\n
\n\ndata.asset.id\n\n\n\nName of the asset.Table: Circuit \\[cmdb\\_ci\\_circuit\\], Cabinet \\[cmdb\\_ci\\_container\\_cabinet\\], Cage \\[cmdb\\_ci\\_cage\\], or Data Center Zone \\[cmdb\\_ci\\_zone\\]\n\nField: Name\n\nData type: String\n\n
\n\ndata.asset.level\n\n\n\nType of asset. Used for cabinets, cages, and zones.Possible values:\n\n- CABINET\n- CAGE\n- ZONE\n\nData type: String\n\n
\n\ndata.asset.type\n\n\n\nType of asset. Used for circuits. The only accepted value is `CIRCUIT`.Data type: String\n\n
\n\ndata.cabinet\n\n\n\nName of the cabinet. Required for cabinets when the **type** parameter is `metered-power` or `power`.Table: Container Cabinet \\[cmdb\\_ci\\_container\\_cabinet\\]\n\nField: Name\n\nData type: String\n\n
\n\ndata.cabinetRating\n\n\n\nPower usage the cabinet is rated for in kilovolt-amperes. Required when the **type** parameter is `power`.Data type: Object\n\n```\n\"cabinetRating\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.cabinetRating.unit\n\n\n\nUnit of measurement. The only accepted value is `kVA`.Data type: String\n\n
\n\ndata.cabinetRating.value\n\n\n\nThe power usage rating for the cabinet.Data type: String\n\n
\n\ndata.cage\n\n\n\nName of the cage. Required for cages when the **type** parameter is `metered-power` or `power`.Table: Cage \\[cmdb\\_ci\\_cage\\]\n\nField: Name\n\nData type: String\n\n
\n\ndata.contractualPower\n\n\n\nPower usage allotted by the contract in kilovolt-amperes. Required when the **type** parameter is `power`.Data type: Object\n\n```\n\"contractualPower\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.contractualPower.unit\n\n\n\nUnit of measurement. The only accepted value is `kVA`.Data type: String\n\n
\n\ndata.contractualPower.value\n\n\n\nThe power usage allotted by the contract.Data type: String\n\n
\n\ndata.ibx\n\n\n\nName of the datacenter. Required when storing metric data for a datacenter.\n\nTable: Data Center \\[cmdb\\_ci\\_datacenter\\]\n\nData type: String\n\n
\n\ndata.kilowattHour\n\n\n\nPower usage data in kilowatt-hours. Required when the **type** parameter is `metered-power`. Data type: Object\n\n```\n\"kilowattHour\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.kilowattHour.unit\n\n\n\nUnit of measurement. The only accepted value is `kWh`.Data type: String\n\n
\n\ndata.kilowattHour.value\n\n\n\nThe recorded kilowatt-hours reading.Data type: String\n\n
\n\ndata.peakLastSevenDays\n\n\n\nThe maximum power usage within the last week in kilovolt-amperes. Required when the **type** parameter is `power`. Data type: Object\n\n```\n\"peakLastSevenDays\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.peakLastSevenDays.unit\n\n\n\nUnit of measurement. The only accepted value is `kVA`.Data type: String\n\n
\n\ndata.peakLastSevenDays.value\n\n\n\nThe maximum power usage value from the last week.Data type: String\n\n
\n\ndata.peakLastSevenDaysRatio\n\n\n\nThe maximum percentage of power used out of the amount allotted by the contract within the last week. Required when the **type** parameter is `power`.Data type: Object\n\n```\n\"peakLastSevenDaysRatio\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.peakLastSevenDaysRatio.unit\n\n\n\nUnit of measurement. The only accepted value is `PERCENT`.Data type: String\n\n
\n\ndata.peakLastSevenDaysRatio.value\n\n\n\nThe maximum percent of power used.Data type: String\n\n
\n\ndata.powerConsumptionToContractual\n\n\n\nPercentage of power used out of the amount allotted by the contract. Required when the **type** parameter is `power`.Data type: Object\n\n```\n\"powerConsumptionToContractual\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.powerConsumptionToContractual.unit\n\n\n\nUnit of measurement. The only accepted value is `PERCENT`.Data type: String\n\n
\n\ndata.powerConsumptionToContractual.value\n\n\n\nThe percent of power used.Data type: String\n\n
\n\ndata.powerFactor\n\n\n\nPower factor data. Required when the **type** parameter is `power`.Data type: Object\n\n```\n\"powerFactor\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.powerFactor.unit\n\n\n\nUnit of measurement. The only accepted value is `pf`.Data type: String\n\n
\n\ndata.powerFactor.value\n\n\n\nThe power factor value.Data type: String\n\n
\n\ndata.reading\n\n\n\nThe collected environmental data. Required when the **type** parameter is `environmental`. Data type: Object\n\n```\n\"reading\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.reading.unit\n\n\n\nUnit of measurement.Possible values:\n\n- `CELSIUS`: Used when **data.tag.id** is `temperature`.\n- `PERCENT`: Used when **data.tag.id** is `humidity`.\n\nData type: String\n\n
\n\ndata.reading.value\n\n\n\nThe recorded value.Data type: String\n\n
\n\ndata.readingTime\n\n\n\nRequired. Date and time the data was collected. This value must be in UTC in ISO 8601 format. For example, `2025-07-03T16:22:15.000Z`.\n\nData type: String\n\n
\n\ndata.realPower\n\n\n\nPower usage data in kilowatts. Required when the **type** parameter is `power`. Data type: Object\n\n```\n\"realPower\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.realPower.unit\n\n\n\nUnit of measurement. The only accepted value is `kW`.Data type: String\n\n
\n\ndata.realPower.value\n\n\n\nThe recorded kilowatts reading.Data type: String\n\n
\n\ndata.soldCurrent\n\n\n\nElectric current allotted by the contract in amps. Required when the **type** parameter is `power`.Data type: Object\n\n```\n\"soldCurrent\": { \n \"unit\": \"String\",\n \"value\": \"String\" \n}\n```\n\n
\n\ndata.soldCurrent.unit\n\n\n\nUnit of measurement. The only accepted value is `A`.Data type: String\n\n
\n\ndata.soldCurrent.value\n\n\n\nThe electric current allotted by the contract.Data type: String\n\n
\n\ndata.tag\n\n\n\nObject containing the type of environmental data. Required when the **type** parameter is `environmental`.Data type: Object\n\n```\n\"tag\": {\n \"id\": \"String\"\n}\n```\n\n
\n\ndata.tag.id\n\n\n\nThe type of environmental data.Possible values:\n\n- humidity\n- temperature\n\nData type: String\n\n
\n\ntype\n\n\n\nRequired. Type of metric data.Possible values:\n\n- `environmental`: Used for humidity or temperature.\n- `metered-power`: Used for power usage in kilowatt-hours \\(kWh\\).\n- `power`: Used for power usage in kilowatts \\(kW\\) and kilovolt-amperes \\(kVA\\).\n\nData type: String\n\n
### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Header|Description|\n|------|-----------|\n|Accept|Data format of the response body. Only supports **application/json;charset=UTF-8**.|\n|Authorization|Basic.|\n|Content-Type|Data format of the request body. Only supports **application/json**.|\n\n|Header|Description|\n|------|-----------|\n|Content-Type|Data format of the response body. Only supports **application/json;charset=UTF-8**.|\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|400|Bad Request. A bad request type or malformed request was detected.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|403|Forbidden. The user doesn't have access rights to the specified record.|\n|404|Not found. The requested item wasn't found.|\n|429|Too many requests.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON\\)\n\n\n
\n\nName\n\n\n\nDescription\n\n
\n\nresult\n\n\n\nDetails about the request.Data type: Object\n\n```\n\"result\": {\n \"status\": \"String\",\n \"sys_id\": \"String\"\n}\n```\n\n
\n\nresult.status\n\n\n\nStatus of the request.Data type: String\n\n
\n\nresult.sys\\_id\n\n\n\nSys\\_id of the CI updated with the metric data.Table: Circuit \\[cmdb\\_ci\\_circuit\\], Cabinet \\[cmdb\\_ci\\_container\\_cabinet\\], Cage \\[cmdb\\_ci\\_cage\\], Data Center \\[cmdb\\_ci\\_datacenter\\], or Data Center Zone \\[cmdb\\_ci\\_zone\\]\n\nData type: String\n\n
### cURL request\n\nStores metered power data for a datacenter.\n\n```\ncurl \"https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n \"type\": \"metered-power\",\n \"data\": {\n \"ibx\": \"Datacenter Name\",\n \"kilowattHour\": {\n \"value\": \"40509.323\",\n \"unit\": \"kWh\"\n },\n \"readingTime\": \"2025-07-03T16:22:15.000Z\"\n }\n}\" \\\n--user 'username':'password'\n```\n\nResponse body.\n\n```\n{\n \"result\": {\n \"status\": \"success\",\n \"sys_id\": \"c88dde85ff2662109cb9ffffffffffcc\"\n }\n}\n```\n\n### cURL request\n\nStores power data for a circuit.\n\n```\ncurl \"https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n \"type\": \"power\",\n \"data\": {\n \"asset\": {\n \"id\": \"Circuit Name\",\n \"type\": \"CIRCUIT\"\n },\n \"realPower\": {\n \"value\": \"0.522\",\n \"unit\": \"kW\"\n },\n \"apparentPower\": {\n \"value\": \"1.070\",\n \"unit\": \"kVA\"\n },\n \"contractualPower\": {\n \"value\": \"60.000\",\n \"unit\": \"kVA\"\n },\n \"powerFactor\": {\n \"value\": \"0.48\",\n \"unit\": \"pf\"\n },\n \"soldCurrent\": {\n \"value\": \"15.000\",\n \"unit\": \"A\"\n },\n \"powerConsumptionToContractual\": {\n \"value\": \"32.151\",\n \"unit\": \"PERCENT\"\n },\n \"cabinetRating\": {\n \"value\": \"123.300\",\n \"unit\": \"kVA\"\n },\n \"peakLastSevenDays\": {\n \"value\": \"1.146\",\n \"unit\": \"kVA\"\n },\n \"peakLastSevenDaysRatio\": {\n \"value\": \"34.424\",\n \"unit\": \"PERCENT\"\n },\n \"readingTime\": \"2025-07-03T16:22:15.000Z\"\n }\n}\" \\\n--user 'username':'password'\n```\n\nResponse body.\n\n```\n{\n \"result\": {\n \"status\": \"success\",\n \"sys_id\": \"c67dbe45fc2662109cb9ffffffffffcd\"\n }\n}\n```\n\n### cURL request\n\nStores temperature data for a zone.\n\n```\ncurl \"https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n \"type\": \"environmental\",\n \"data\": {\n \"asset\": {\n \"id\": \"Zone Name\",\n \"level\": \"ZONE\"\n },\n \"reading\": {\n \"value\": \"23.300\",\n \"unit\": \"CELSIUS\"\n },\n \"tag\": {\n \"id\": \"temperature\"\n },\n \"readingTime\": \"2025-07-03T16:22:15.000Z\"\n }\n}\" \\\n--user 'username':'password'\n```\n\nResponse body.\n\n```\n{\n \"result\": {\n \"status\": \"success\",\n \"sys_id\": \"c64dbc42fe2862109cb9ffffffffffed\"\n }\n}\n```\n\n### cURL request\n\nStores humidity data for a cabinet.\n\n```\ncurl \"https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--data \"{\n \"type\": \"environmental\",\n \"data\": {\n \"asset\": {\n \"id\": \"Test Cabinet\",\n \"level\": \"CABINET\"\n },\n \"reading\": {\n \"value\": \"66.120\",\n \"unit\": \"PERCENT\"\n },\n \"tag\": {\n \"id\": \"humidity\"\n },\n \"readingTime\": \"2025-07-03T16:22:15.000Z\"\n }\n}\" \\\n--user 'username':'password'\n```\n\nResponse body.\n\n```\n{\n \"result\": {\n \"status\": \"success\",\n \"sys_id\": \"c24dbc82fe3862107cb9ffffffffffbc\"\n }\n}\n```\n\n"}}