Rest API – Configuration Items
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 |
Schema
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:
- 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
andsize
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:
|
Number | 0 |
Yes |
useip | For Attribute polling, indicates whether this CI should be accessed by IP or Hostname:
|
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:
|
Number | 0 |
Yes |
name | A name for the CPU object. Related Macros:
|
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:
|
Number | 1 |
Yes |
attribute_status | The status of the Attribute representing this Interface. Possible numeric values:
|
Number | 0 |
Yes |
description | A description of this Interface. Related Macros:
|
String | Yes | |
name | The name of this Interface. Related Macros:
|
String | Yes | |
operational_status | The status of the Operational Interface Port. Possible numeric values:
|
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:
|
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:
|
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:
|
Number | 4 |
Yes |
secondary_stack_layer | The secondary function, if any, that the CI supports in your defined services. Possible numeric values:
|
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:
|
String | Yes | |
multiplier |
This multiplier will be used as the created Attribute's "Custom Multiplier" value. Related Macros:
|
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.