Skip to main content
Matrix42 Self-Service Help Center

Rest API – Configuration Items

How to use the FireScope REST API to crete, update, query and delete configuration items.

Overview

The REST API allows you to work with Configuration Items (CIs) in FireScope SPM using a REST client in lieu of the SPM user interface. 

  • Retrieve
  • Search
  • Create or Update
  • Delete

Retrieve

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

http://localhost:38050/web_services/...e1&name=VMware

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

Query Parameter Descriptions

Parameter Description Type Required
account Name of the SPM Account. String Yes
edge_device Name of the CI’s Edge Device. String Yes
name Name of the CI. 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/...page=0&size=10

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

Custom Fields: You can add the optional parameter “custom_fields=true” and the results will be limited to a single CI document which contains nothing but a list of all of the custom fields (ci.ci_profile.custom_fields) gathered from the list of CI’s specified in the search criteria.

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
logicalgroup Filter the results by a Logical Group’s exact name. String   No
servicegroup Filter the results by a Service Group’s exact name. String   No
fs_ci_type Filter the results by Device Type name (fs_ci_type.ci_type) String   No

Example Search Response

{
   "account_id": "firescope",
   "entity": "ci",
   "page": 0,
   "size": 2,
   "results": [
      {
         "account_id": "firescope",
         "edge_device_id": "edge1",
         "ciname": "VMWare",
         "ip": "10.0.6.1"
      }, {
         "account_id": "firescope",
         "edge_device_id": "edge2",
         "ciname": "FireScope Website",
         "dns": "firescope.com",
         "useip": 0
      }
   ]
}

Create or Update

To create or update a CI, POST a JSON document with the specific CI information to the following URL:

http://localhost:38050/web_services/ci

You can use the following example as a guide, but note that it does not include all optional properties.

{
  "account_id" : "firescope",
  "edge_device_id" : "edge1",
  "ciname" : "VMWare",
  "ip" : "10.0.6.1",
  "port" : 8042,
  "status" : 0,
  "useip" : 1,
  "ci_profile" : {
    "contact" : "John Wayne",
    "devicetype" : "Server",
    "location" : "Dallas Data Center",
    "name" : "REST Configuration Item 1",
    "notes" : "This is the notes section",
    "os" : "Linux Mint 14",
    "serialno" : "0U812"
  }
}

Property Descriptions

The following table provides information about all required and optional properties available for a CI.

Property Description Type Default Value Required
account_id Name of the SPM Account. String   Yes
edge_device_id Name of the Edge Device that will collect data for this CI. String   Yes
ciname Name of the Configuration Item. String   Yes
cisco_ucs_conn_info_id Cisco UCS access credentials, which allow Attributes to connect to the Cisco device and determine data relationship. String   No
dns Fully qualified DNS name of CI. String   Yes, if useip = 0
fs_ba_eventdefid The name of the Event Definition used to indicate business availability for this CI. String   No
fs_domain Active Directory domain name. Only required if you are using WMI to collect Attribute values. String   No
fs_proxy_ciname Name of CI acting as a proxy for data collection. Only required if you are using FireScope Sentinel. String   No
infoblox_conn_info_id Name of the credentials being used to connect to Infoblox. String   No
ip IP address of the CI. String 127.0.0.1 Yes, if useip = 1
ldap_conn_info_id Name of LDAP access credentials, which allows Attributes to connect to the LDAP service. String   No
netapp_credential_id Name of NetApp ONTAP access credentials, which allows Attributes to connect to the NetApp device and determine data relationships. String   No
netapp_dfm_conn_info_id Name of NetApp DFM access credentials, which allows Attributes to connect to the NetApp device and determine data relationships. String   No
port Default port for agent communications. Number 8042 Yes
snmp_credential_id Name of SNMP access credentials, which allows Attributes to connect to the SNMP device. String   No
status Status of the CI:0 = Monitored1 = Disabled Number 0 Yes
useip Indicates if it uses an IP address:0 = DNS supplied1 = IP address supplied Number 1 Yes
vm_conn_info_id Name of existing Virtual Center Connection to allow VC Attribute collection. String   No
vm_name Virtual Center Infrastructure Client Name – used as the unique lookup to locate the associated virtual center host or guest. String   No
ci_profile CI profile information:
PropertyDescriptionTypeDefault ValueRequiredcontactPerson of contact for CI.String Nocustom_fieldsA list of custom field
PropertyDescriptionNameStringValueStringObject[] Nodevicetype
Types of Assets-Possible ValuesApplicationServerCollectionServiceData StoreSoftware ProductDeviceStorageFireScopeTemplateGenericUnknownLocationVM GuestNetworkVM HostPrinterVMware vCenterSecurity String Yesfs_port_alias_idName of a known port alias.String NohardwareDescription of hardware CI resides on.String NolocationLocation of CI (e.g., data center, rack, row, city, etc).String NomacaddressMAC address of CI.String NonameName of the CI Profile.String NonotesMisc notes about this CI.String NoosOS information on this device.String Noprimary stack layerPrimary type of function the CI supports in your defined service. For example, your network fileserver CIs for your CRM system should have the stack layer of STORAGE. This identifier is used throughout the application to indicate your issues.
Possible Values0 = None5 = Virtualization1 = User Experience6 = Hardware2 = Application7 = Network3 = Database8 = Storage4 = OS9 = EnvironmentalNumber4Yessecondary stack layer
Possible Values0 = None5 = Virtualization1 = User Experience6 = Hardware2 = Application7 = Network3 = Database8 = Storage4 = OS9 = EnvironmentalNumber0YesserialnoSerial number of this device.String NosoftwareInformation on any software installed on this CI.String NotagDoes this CI have a tag associated with it?String NourlThe URL where the CI resides, if necessary.String No
Object   Yes
ci_storage
PropertyDescriptionTypeDefault ValueRequiredfilesystemThe filesystem path for this storage item. Related macro [CI_STORAGE.FILESYSTEM]String YesmountThe mount point associated with the filesystem.String NomultiplierThis multiplier will be used as the created attribute’s custom multiplier. Related macro [CI_STORAGE.MULTIPLIER]String1Yes
   Object[] [ ] No
ci_memory
PropertyDescriptionTypeDefault ValueRequiredasset_name String Nodescription String Noname String Yesstorage_alloc_units Number0Notype
Possible Values0 = Other5 = Floppy Disk1 = RAM6 = Compact Disk2 = Virtual Memory7 = RAM Disk3 = Fixed Disk8 = Flash Memory4 = Removable Disk9 = Network DiskNumber1Yes
  Object[] [ ] No
ci_interface
PropertyDescriptionTypeDefault ValueRequiredadmin_statusPossible values:1 = Up2 = Down3 = TestingNumber1Yesattribute_statusPossible values:0 = Active1 = Disabled3 = Not SupportedNumber0YesdescriptionRelated macro [CI_INTERFACE.DESCRIPTION]String Yestype String NonameRelated macro [CI_INTERFACE.NAME]String Yesoperational_statusPossible values:1 = Up2 = Down3 = Testing4 = Unknown5 = Dormant6 = Not Present7 = Lower Layer DownNumber1Yes
  Object[] [ ] No
ci_cpu
PropertyDescriptionTypeDefault ValueRequiredasset_name String Nodescription String NoindexRelated macro[CI_CPU.INDEX]Number0YesnameRelated macro [CI_CPU.NAME]String Yesspeed String No
  Object[] [ ] No
ci_bp Blueprint associated with the CI. Read only. Use the Blueprint Web Service to link an existing blueprint to this CI. String[] [ ] No
ci_snmp_table See schema API call for payload structure. Object   No
ci_vm_discovery See schema API call for payload structure Object   No
logicalgroup Name of the Logical Group associated with the CI. String[] [ ] No
servicegroup Name of the Service Group associated with the CI. String[] [ ] No

 Delete

To delete a CI, 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.

  • Was this article helpful?