Rest API – Attributes
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.)