Skip to main content
Matrix42 Self-Service Help Center

Rest API – Attributes

How to create, update and delete attributes using the FireScope REST API.

Overview

The REST API allows you to work with Attributes in FireScope SPM. 

  • Retrieve
  • Search
  • Create or Update
  • Delete

Retrieve

To retrieve the current information about an Attribute as a JSON document, send a GET request with the following URL format:

http://localhost:38050/web_services/...2.15&name=ping

Note: Don’t forget to change the (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

Query Parameter Descriptions

Property Description Type Required
account Name of the SPM Account. String Yes
edge_device Name of the Edge Device. String Yes
ci Name of the CI. String Yes
name Name of the Attribute. String Yes

Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this, a GET request is sent with a parameter search=true. Every other field besides account is optional and is used to further filter the results. Pagination is mandatory and accomplished using the page and size parameters. The JSON response will wrap the result list and also display the page and the size. The size in the response represents the number of results actually returned, not the size in the request. The response does not contain a count of the total number of pages or the total number of records for performance reasons. The client is expected to keep querying, increasing the page each time, until the result size is less than the requested size, indicating no more results.

http://localhost:38050/web_services/...age=0&size=100

Note: Don’t forget to change the (localhost) and query parameter values (account, edge_device, ci, and name) to match your environment and data.

Search Parameter Descriptions

Parameter Description Type Default Required
account Name of the SPM Account. String   Yes
search Enable searching by setting to true. Setting to false will revert functionality to retrieving a single result. Boolean FALSE Yes
page Indicates which result set is being returned starting at zero and increasing until there are no more results Number 0 Yes
size Indicates how many results are returned in a single page. A max of 250 results is supported. Number 100 Yes
name Filter the results by a case-insensitive substring search of the name field. String   No
edge_device Filter the results by an Edge Device’s exact name. String   No
ci Filter the results by a Configuration Item’s exact name. String   No

Example Search Results Response

{
   "account_id": "firescope",
   "entity": "attribute",
   "page": 0,
   "size": 2,
   "results": [
      {
         "account_id": "firescope",
         "edge_device_id": "edge2",
         "description": "Host ping",
         "ciid": "10.0.6.11",
         "operation": "ping"
      },
      {
         "account_id": "firescope",
         "edge_device_id": "edge1",
         "description": "Host ping",
         "ciid": "10.0.2.15",
         "operation": "ping"
      }
   ]
}

Create or Update

To create an Attribute, send a POST operation with a JSON document to the following URL:

           http://[SPM IP address]:38050/web_services/attribute

Note: Don’t forget to change the (SPM IP address

Use the following example as a guide.

{
   "account_id":"firescope",
   "edge_device_id":"Edge 1",
   "asset_name":null,
   "ciid":"REST Created 1",
   "delay":60,
   "delta":0,
   "description":"test PING 1",
   "formula":"1",
   "logtimefmt":"",
   "metadata":"STATUS,,,PING,53177150e4b011a3f27f25d2,test PING 1",
   "multiplier":0,
   "operation":"ping",
   "snmp_oid":"interfaces.ifTable.ifEntry.ifInOctets.1",
   "snmp_port":161,
   "status":0,
   "translationid":null,
   "trapper_hosts":"",
   "type":3,
   "units":"",
   "value_type":3,
   "fs_attribute_type":{
      "attribute_major":"80",
      "attribute_max":"1",
      "attribute_warning":"60",
      "avail":0,
      "kpi":0,
      "def_graph":"none",
      "perf":1,
      "sec":0
   },
   "attributeset":["Ping attributes"]
}

Property Descriptions

Property Description Type DefaultValue Required
account_id Name of the SPM Account. String   Yes
edge_device_id Name of the Edge Device. String   Yes
asset_name A name used to group related attributes together that belong to the same asset. String   No
ciid Name of the associated CI. String   Yes
delay How often (in seconds) SPM should check values. Number 60 Yes
delta Option to either collect the raw value or its rate of change over time.Possible values:0 = As Is1 = Speed per Second2 = Simple Change Number 0 Yes
description Attribute description, which will be listed on the Attributes page. String   Yes
formula The actual multiplier value you want to use. E.g. 1024 to convert bytes to kilobytes. String 1 No
lastvalue The attribute’s last reported value. Read-only. String   No
logtimefmt   String   No
metadata Options for using metadata, in the following format: [Type],[SubType],[Vendor],[Detail],[Index],[Label] String   No
multiplier Controls whether to use a multiplier or not. See the formula field for the actual multiplier value.Possible values:0 = Do Not Use1 = Use Number 0 No
operation Operation used for gathering data. You must enter an Operation corresponds to the Type.If you are using FireScope Agent, make sure the Operation you use is defined in the FireScope Agent’s configuration. For SNMP, you must enter the credentials required to access the SNMP connection (port 161) of the device. String   Yes
prevvalue The attribute’s previous value that occurred before the value in the ‘lastvalue’ field. Read-only. String   No
snmp_oid Object Identifier (OID) required to access the SNMP connection and gather data for this Attribute. String   No
snmp_port Port for the SNMP connection. Number 161 No
status Whether the attribute is active or not.Possible values:0 = Active1 = Disabled Number 0 Yes
translationid Name of the translation being used String   No
trapper_hosts   String   No
type The type of the attribute, which help denotes the source of the attribute.Possible Values:0 = FireScope1 = SNMP V12 = Trapper3 = Simple4 = SNMP V25 = Internal6 = SNMP V37 = FireScope Active8 = Grouped Attribute10 = External11 = FireScope WMI12 = Syslog13 = ESB JDBC14 = ESB FTP15 = ESB HTTP16 = ESB HTTPS17 = ESB WSDL18 = ESB File19 = ESB SOAP20 = ESB Multicast21 = ESB POP322 = ESB SMTP23 = ESB TCP24 = ESB UDP25 = VM Host26 = VM Guest27 = VM VC28 = LDAP Check29 = Calculated Attribute31 = Percentile Attribute32 = Delegate Syslog33 = Delegate SNMP V134 = Delegate SNMP Trap35 = Delegate SNMP V236 = Delegate SNMP V337 = Service Availability38 = NetApp39 = Cisco UCS40 = App Server Stat41 = SMongo Server Stat42 = SWeb Server Stat43 = NetApp DFM44 = Attribute Incoming45 = Attribute Incoming JSON46 = Infoblox47 = Days to target48 = Amazon AWS49 = Edge Server stat50 = SMIS Number 0 Yes
units Unit type appended to the end of all values for this Attribute whenever they are displayed. For example, % for processor utilization, B (bytes) for file system size, and Bps (bytes per second) for network performance. String   No
value_type
ValueTypeDescription0FloatDouble e.g. 3.141StringCharacter (max size 1024) e.g. “Hello world”2LogActual lines from a log attribute / Windows Event log attribute (Max size 65535)3LongInteger e.g. 21474836474TextVery large “String” equivalent of a CLOB (Max size 65535)9JSON (Max size 4096)e.g. {“first_name”:”Bryan”,”company_name”:”FireScope”}
  Number 0 Yes
fs_attribute_type Attribute type information:
PropertyDescriptionTypeDefaultValueRequiredattribute_major String80Noattribute_max String1Noattribute_warning String60NoavailClassifies whether this attribute impacts the availability of this CI.Number0YeskpiEnable some summary views of CIs to display the attributes labeled as a Key Performance IndicatorNumber0Yesdef_graph Show/hide possible valuesStringnoneYesperfClassifies whether this attribute impacts the performance of this CI.Number1YessecClassifies whether this attribute impacts the security of this CI.Number0Yes
Object   Yes
attributeset Names of the Attribute Set(s) this Attribute is associated with. String[]   No

Delete

To delete an Attribute, send an HTTP DELETE request with the same query parameters as the GET request.See the Retrieve for the URL format and query parameter descriptions.

Note: Deleting an Attribute will have a cascading delete effect. All elements that are based on this Attribute will be effected (for e.g.  Dashboards, AEDs, ED, Policies etc. Data collected by this Attribute will be lost for good.)

  • Was this article helpful?