Skip to main content
Matrix42 Self-Service Help Center

Rest API – Configuration Items

  1. Last updated
  2. Save as PDF

Overview

The REST API allows you to work with Configuration Items (CIs) in FireScope using a REST client in lieu of the FireScope user interface. Below you'll find documentation for the following operations:

  • Direct Fetch
  • Schema
  • Search
  • Create or Update
  • Delete

Direct Fetch

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

https://localhost:38060/web_services/ci?account=yourAccount&edge_device=yourEdgeName&name=yourCiName

Be sure to change the domain name (localhost) and query parameters (account, edge_device, name) values to match your environment and data.

Query Parameter Descriptions

Property Description Type Required
account Name of the FireScope Account. String Yes
edge_device Name of the CI’s Edge Device. String Yes
name Name of the CI. String Yes

To retrieve the full schema of a CI object, with all available fields, their data types, enumeration values, and read/write permissions, send a GET request with the following URL format:

https://localhost:38060/web_services/ci?account=yourAccount&schema=true

Be sure to change the domain name (localhost) and query parameter (account) value to match your environment and data.

Schema Parameter Descriptions

Property Description Type Required
account Name of the FireScope Account. String Yes
schema If true, the response will contain the full schema of the object with all available fields, their data types, potential enumeration values, and read/write permissions. Boolean Yes

Search

Searching provides for the ability to return multiple results in a single call using various filter criteria. To accomplish this:

  1. A GET request is sent with a parameter search=true
  2. Every other field besides account is optional and is used to further filter the results.
  3. 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 total size of the requested dataset. 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.

https://localhost:38060/web_services/ci?search=true&account=yourAccount&edge_device=yourEdgeName&name=yourCiName&page=0&size=100

Be sure to change the domain name (localhost) and query parameters (account, edge_device, name , page, size) values to match your environment and data.

Search Parameter Descriptions

Property Description Type Default Required
account Name of the FireScope 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

Example Search Response

{
  "account_id": "SDDM",
  "entity": "ci",
  "page": 0,
  "size": 2,
  "results": [
    {
      "account_id": "SDDM",
      "edge_device_id": "DallasCOLOEdge1",
      "amazon_aws_conn_info_id": "AWS conn",
      "ciname": "weba",
      "cisco_ucs_conn_info_id": null,
      "dns": "",
      "fs_ba_eventdefid": null,
      "fs_domain": "",
      "fs_proxy_ciname": "",
      "infoblox_conn_info_id": null,
      "ip_numeric": 2887713125,
      "ip": "172.31.1.101",
      "ldap_conn_info_id": null,
      "netapp_credential_id": null,
      "netapp_dfm_conn_info_id": null,
      "port": 8042,
      "snmp_credential_id": "Matrix Community String",
      "smis_conn_info_id": null,
      "ssh_credential_id": "Kerberos Password",
      "status": 0,
      "useip": 1,
      "vm_conn_info_id": "CoLo Vcenter Credential",
      "vm_name": "",
      "wmi_credential_id": null,
      "ci_profile": {
        "architecture": "",
        "asset_type": "",
        "contact": "",
        "devicetype": "Application",
        "fs_port_alias_id": null,
        "hardware": "",
        "last_seen": 0,
        "location": "",
        "manufacturer": "",
        "macaddress": "",
        "model": "",
        "name": "",
        "notes": "",
        "os": "",
        "os_distribution": "",
        "primary_stack_layer": 2,
        "secondary_stack_layer": 0,
        "serialno": "",
        "software": "",
        "tag": "",
        "total_ram": "",
        "url": "",
        "version": "",
        "custom_fields": [],
        "imageid": null
      },
      "ci_storage": [],
      "ci_memory": [],
      "ci_interface": [],
      "ci_cpu": [],
      "ci_bp": [
        "Web Server BP"
      ],
      "logicalgroup": [
        "Web Servers"
      ],
      "servicegroup": [
        "Gateway"
      ],
      "ci_snmp_table": [],
      "ci_vm_discovery": {
        "ci_vm_virtual_datacenter": [],
        "ci_vm_virtual_nic": [],
        "ci_vm_datastore": [],
        "ci_vm_vmnic": []
      },
      "ci_netapp": {
        "ci_netapp_filer": {
          "ip": "",
          "ci_netapp_aggregate": [],
          "ci_netapp_volume": [],
          "attributeset_id": null
        }
      },
      "azure_conn_info_id": null,
      "ip_group": [],
      "parent_ciid": null,
      "child_ciids": [
        {
          "ci": "webb",
          "firescope_id": "60fecc78a184e9c42810c93d",
          "edge_device": "DallasCOLOEdge1"
        },
        {
          "ci": "webc",
          "firescope_id": "60fecca7a184e9e12810c8aa",
          "edge_device": "DallasCOLOEdge1"
        }
      ],
      "firescope_id": "60fecc42a184e9863610c93b"
    },
    {
      "account_id": "SDDM",
      "edge_device_id": "DallasCOLOEdge1",
      "amazon_aws_conn_info_id": "AWS conn",
      "ciname": "webb",
      "cisco_ucs_conn_info_id": null,
      "dns": "",
      "fs_ba_eventdefid": null,
      "fs_domain": "",
      "fs_proxy_ciname": "",
      "infoblox_conn_info_id": null,
      "ip_numeric": 2887713126,
      "ip": "172.31.1.102",
      "ldap_conn_info_id": null,
      "netapp_credential_id": null,
      "netapp_dfm_conn_info_id": null,
      "port": 8042,
      "snmp_credential_id": "Matrix Community String",
      "smis_conn_info_id": null,
      "ssh_credential_id": null,
      "status": 0,
      "useip": 1,
      "vm_conn_info_id": "CoLo Vcenter Credential",
      "vm_name": "",
      "wmi_credential_id": null,
      "ci_profile": {
        "architecture": "",
        "asset_type": "",
        "contact": "",
        "devicetype": "Application",
        "fs_port_alias_id": null,
        "hardware": "",
        "last_seen": 0,
        "location": "",
        "manufacturer": "",
        "macaddress": "",
        "model": "",
        "name": "",
        "notes": "",
        "os": "",
        "os_distribution": "",
        "primary_stack_layer": 2,
        "secondary_stack_layer": 0,
        "serialno": "",
        "software": "",
        "tag": "",
        "total_ram": "",
        "url": "",
        "version": "",
        "custom_fields": [],
        "imageid": null
      },
      "ci_storage": [],
      "ci_memory": [],
      "ci_interface": [],
      "ci_cpu": [],
      "ci_bp": [
        "Web Server BP"
      ],
      "logicalgroup": [
        "Web Servers"
      ],
      "servicegroup": [
        "Gateway"
      ],
      "ci_snmp_table": [],
      "ci_vm_discovery": {
        "ci_vm_virtual_datacenter": [],
        "ci_vm_virtual_nic": [],
        "ci_vm_datastore": [],
        "ci_vm_vmnic": []
      },
      "ci_netapp": {
        "ci_netapp_filer": {
          "ip": "",
          "ci_netapp_aggregate": [],
          "ci_netapp_volume": [],
          "attributeset_id": null
        }
      },
      "azure_conn_info_id": null,
      "ip_group": [],
      "parent_ciid": {
        "ci": "weba",
        "firescope_id": "60fecc42a184e9863610c93b",
        "edge_device": "DallasCOLOEdge1"
      },
      "child_ciids": [],
      "firescope_id": "60fecc78a184e9c42810c93d"
    }
  ]
}

Create or Update

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

https://localhost:38060/web_services/ci

Be sure to change the domain name (localhost) to match your environment and data.

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

{
  "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.

The following tables only include fields that can be modified through the API. They do not include descriptions of all available fields in an object. See the Schema API call for a list of all possible fields available and their data types.

Property Description Type Default Required
account_id Name of the FireScope Account. String   Yes
ci_profile See the CI Profile Object below. Object   Yes
ciname Name of the Configuration Item. String   Yes
dns Fully qualified DNS name of CI. String   Yes, if useip=0
edge_device_id Name of the Edge Device that will collect data for this CI. String   Yes
ip IP address of the CI. String 127.0.0.1 Yes, if useip=1
port Default port for agent communications. Number 8042 Yes
status Status of the CI:
  • 0 Monitored
  • 1 Disabled
 Number 0 Yes
useip For Attribute polling, indicates whether this CI should be accessed by IP or Hostname:
  • 0 Use Hostname
  • 1 Use IP Address
 Number 1 Yes
ci_bp Read only. Use the Blueprint Web Service to link an existing blueprint to this CI.

The exact names of the Blueprints associated with the CI.		 String[] [ ] No
ci_cpu See the CI CPU Object below. Object[] [ ] No
ci_interface See the CI Interface Object below Object[] [ ] No
ci_memory See the CI Memory Object below. Object[] [ ] No
ci_snmp_table See the Schema API call for payload structure. Object   No
ci_storage See the CI Storage Object below. Object[] [ ] No
ci_vm_discovery See the Schema API call for payload structure. Object   No
fs_ba_eventdefid The exact name of the Basic 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 Exact name of CI acting as a proxy for data collection. Only required if you are using FireScope Sentinel. String   No
ldap_conn_info_id The exact name of LDAP Connection Credential, which allows Attributes to connect to the LDAP service. String   No
logicalgroup The exact names of the Logical Groups associated with the CI. String[] [ ] No
netapp_credential_id The exact name of NetApp ONTAP Connection Credential, which allows Attributes to connect to the NetApp device and determine data relationships. String   No
servicegroup The exact names of the Service Groups associated with the CI. String[] [ ] No
snmp_credential_id The exact name of SNMP Connection Credential, which allows Attributes to connect to the SNMP device. String   No
vm_conn_info_id The exact name of existing Virtual Center Connection Credential to allow VMware Attribute collection. String   No
vm_name The Virtual Center Infrastructure Client Name. This is used as the unique lookup to locate the associated virtual center host or guest. String   No
cisco_ucs_conn_info_id Deprecated in SDDM

The exact name of the Cisco UCS Connection Credential which allows Attributes to connect to the Cisco device and determine data relationship.		 String   No
infoblox_conn_info_id Deprecated in SDDM

The exact name of the Infoblox Connection Credential being used to connect to Infoblox.		 String   No
netapp_dfm_conn_info_id Deprecated in SDDM

The exact name of NetApp DFM Connection Credentials, which allows Attributes to connect to the NetApp device and determine data relationships.		 String   No

CI CPU Object

Property Description Type Default Required
index The core number as an index value starting from 0.

Related Macros:
  • [CI_CPU.INDEX]
 Number 0 Yes
name A name for the CPU object.

Related Macros:
  • [CI_CPU.NAME]
 String   Yes
asset_name A CMDB Asset Name, or serial number, for this specific CPU String   No
description A description for this specific CPU String   No
speed The speed of the CPU. String   No

CI Interface Object

Property Description Type Default Required
admin_status The status of the Admin Interface Port.

Possible numeric values:
  • 1 Up
  • 2 Down
  • 3 Testing
 Number 1 Yes
attribute_status The status of the Attribute representing this Interface.

Possible numeric values:
  • 0 Active
  • 1 Disabled
  • 3 Unsupported
 Number 0 Yes
description A description of this Interface.

Related Macros:
  • [CI_INTERFACE.DESCRIPTION]
 String   Yes
name The name of this Interface.

Related Macros:
  • [CI_INTERFACE.NAME]
 String   Yes
operational_status The status of the Operational Interface Port.

Possible numeric values:
  • 1 Up
  • 2 Down
  • 3 Testing
  • 4 Unknown
  • 5 Dormant
  • 6 Not Present
  • 7 Lower Layer Down
 Number 1 Yes
type A type, label, or category represented by this Interface. String   No

CI Memory Object

Property Description Type Default Required
name A name for the memory object String   Yes
type The type of memory object.

Possible numeric values:
  • 0 Other
  • 1 RAM
  • 2 Virtual Memory
  • 3 Fixed Disk
  • 4 Removable Disk
  • 5 Floppy Disk
  • 6 Optical Disk (DVD/CD Drive)
  • 7 RAM Disk
  • 8 Flash Memory
  • 9 Network Disk
 Number 1 Yes
asset_name A CMDB Asset Name, or serial number, for this specific memory object. String   No
description A description of the memory object. String   No
storage_alloc_units The specific memory allocation units used in the memory object. Number 0 No

CI Profile Object

Property Description Type Default Required
devicetype Type of asset. Available default values:
  • Application
  • Collection
  • Data Store
  • Device
  • FireScope
  • Generic
  • Location
  • Network
  • Printer
  • Product
  • Security
  • Server
  • Service
  • Software
  • Storage
  • Template
  • Unknown
  • VM Guest
  • VM Host
  • VMware vCenter
 String   Yes
primary_stack_layer The primary function the CI supports in your defined services. For example, your network file server CIs for a CRM system should have the stack layer of 8 for "Storage".

This identifier is used throughout the application to indicate your issues.

Possible numeric values:
  • 1 User Experience
  • 2 Application
  • 3 Database
  • 4 Operating System
  • 5 Virtualization
  • 6 Hardware
  • 7 Network
  • 8 Storage
  • 9 Environmental
 Number 4 Yes
secondary_stack_layer The secondary function, if any, that the CI supports in your defined services.

Possible numeric values:
  • 0 None
  • 1 User Experience
  • 2 Application
  • 3 Database
  • 4 Operating System
  • 5 Virtualization
  • 6 Hardware
  • 7 Network
  • 8 Storage
  • 9 Environmental
 Number 0 Yes
contact Person of contact for the CI. String   No
custom_fields A list of custom field objects. See CI Profile Custom Fields Object below. Object[] [] No
fs_port_alias_id Name of a known port alias. String   No
hardware Description of the hardware the CI represents. String   No
location The location of the CI (e.g., data center, rack, row, city, etc.). String   No
macaddress The MAC Address of the CI. String   No
name An alternate name for the CI. String   No
notes Miscellaneous notes about this CI. String   No
os Operating System name for this CI. String   No
serialno Serial number of this device for warranty tracking. String   No
software Information on any software installed on this CI String   No
tag Asset tag for asset tracking String   No
url The URL to access the CI's web interface, if any String   No
CI Profile Custom Field Object
Property Description Type Default Required
name Field name or label to display String   Yes
value Field value to store String   Yes

CI Storage Object

Property Description Type Default Required
filesystem The file system path for this storage item.

Related Macros:
  • [CI_STORAGE.FILESYSTEM]
 String   Yes
multiplier
 		 This multiplier will be used as the created Attribute's "Custom Multiplier" value.

Related Macros:
  • [CI_STORAGE.MULTIPLIER]
 String 1 Yes
mount The mount point associated with the file system. String   No

Delete

To delete a CI, send a DELETE request using the same query parameters as the Direct Fetch request.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    How-To
    Checked
    Checked
    Stage
    Final
    Target Group
    Customer
  2. Tags
    1. API
    2. CI
    3. FireScope
    4. REST