Rest API – CI Relationships - Matrix42 Self-Service Help Center

Overview

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

Direct Fetch (not implemented)
Schema
Search
Create or Update (not implemented)
Delete (not implemented)

Direct Fetch

CI Relationship direct fetch is not implemented

Schema

To retrieve the full schema of a CI Relationship 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_relationship?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 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_relationship?search=true&account=firescope&servicegroup=Ordering&page=0&size=10

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

Search Parameter Descriptions

Parameter	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 (`0`) 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
servicegroup	Filter the results by a Service Group’s exact name.	String		No

Example Search Response

{
  "account_id": "firescope",
  "entity": "ci_relationship",
  "page": 0,
  "size": 2,
  "results": [
    {
      "account_id": "firescope",
      "flow_id": null,
      "last_flow_ts": 1627311601,
      "pending_delete": 1,
      "port": 19234,
      "protocol_name": "",
      "protocol_type": "TCP",
      "ci_relationship_category_id": "Network",
      "ci_relationship_type_id": "related",
      "servicegroupid": "Dev Environment",
      "source_ci": {
        "edge_device": "Dallas DC",
        "ci": "esx1",
        "firescope_id": "60fece91e4b0dab636034a4e"
      },
      "source_ci_staging": null,
      "status": 1,
      "target_ci": {
        "edge_device": "Dallas DC",
        "ci": "esx2",
        "firescope_id": "60fece91e4b0dab636034a50"
      },
      "target_ci_staging": null,
      "firescope_id": "60fece91e4b0dab636034a4d",
      "firescope_servicegroupid": "60fece91e4b0dab636034a4e",
    },
    {
      "account_id": "firescope",
      "flow_id": null,
      "last_flow_ts": 1627311601,
      "pending_delete": 0,
      "port": 443,
      "protocol_name": "https",
      "protocol_type": "TCP",
      "ci_relationship_category_id": "Application",
      "ci_relationship_type_id": "related",
      "servicegroupid": "Dev Environment",
      "source_ci": {
        "edge_device": "Dallas DC",
        "ci": "esx1",
        "firescope_id": "60fece91e4b0dab636034a4e"
      },
      "source_ci_staging": null,
      "status": 0,
      "target_ci": {
        "edge_device": "Dallas DC",
        "ci": "weba",
        "firescope_id": "60fece91e4b0dab636034a4f"
      },
      "target_ci_staging": null,
      "firescope_id": "60fece91e4b0dab636034a6b",
      "firescope_servicegroupid":"60fece91e4b0dab636034a6f",
    }
  ]
}

Property Descriptions

The following table provides information about all properties available for a CI Relationship.

Property	Description	Type	Default
acccount_id	Name of the FireScope Account.	String
ci_relationship_category_id	Name of the category this relationship falls into: `Application` `Network` `Storage` `Virtual`	String
ci_relationship_type_id	The type of relationship indicates whether it is a parent/child relation or just a normal relationship. `contains` `related`	String
firescope_id	The internal FireScope ID of the CI Relationship object.	String
last_flow_ts	The UNIX timestamp of the last flow that was seen and responsible for the CI Relationship being created.	Number
pending_delete	Also referred to as "Activity". Identifies whether a Baseline CI Relationship has become Inactive, and is pending user deletion. Possible numeric values: `0` Active `1` Inactive	Number	`0`
port	The port associated with this relationship. Usually this indicates the target server’s listening port.	Number
protocol_name	The application protocol name associated with this traffic. For example, `http`, `ldap`, etc.	String
protocol_type	The transport layer protocol. Either UDP or TCP.	String
servicegroupid	Name of the Service Group associated with the CI.	String
source_ci	The originating CI of the relationship. See Minimal CI Object below.	Object
status	Status of the relationship. Possible numeric values: `0` New `1` Baseline `2` Suppressed	Number	`0`
target_ci	The destination CI of the relationship. See Minimal CI Object below.	Object

Minimal CI Object

Property	Description	Type
ci	The exact name of the CI.	String
edge_device_id	The exact name of the Edge Device assigned to the CI.	String
firescope_id	The internal FireScope ID of the CI object.	String

Create or Update

CI Relationship creation/update functionality is not implemented.

Delete

CI Relationship deletion functionality is not implemented