Skip to main content
Matrix42 Self-Service Help Center

Rest API – Service Groups

  1. Last updated
  2. Save as PDF
How to use the REST API to create, update, query, and delete Service Groups.

Overview

The REST API allows you to work with Service Groups in FireScope.

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

Direct Fetch

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

https://localhost:38060/web_services/servicegroup?account=yourAccount&name=yourServiceGroupName

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

 Query Parameter Descriptions

Parameter Description Type Required
account Name of account. String Yes
name Name of Service Group. String Yes

To retrieve the full schema of a Service Group 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/servicegroup?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/servicegroup?search=true&account=yourAccount&name=yourServiceGroupName&logicalgroup=yourLogicalGroupName&page=0&size=100

Don’t forget to change the domain name (localhost) and query parameter values (account, logicalgroup, name, page and size) 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 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
logicalgroup Filter the results by a Logical Group’s exact name. String   No
schema If true, the response will contain the full schema of the object (instead of the object), with all available fields, their data types, and read/write permissions. Boolean false No

Example Search Response

{
  "account_id": "SDDM",
  "entity": "servicegroup",
  "page": 0,
  "size": 1,
  "results": [
    {
      "account_id": "SDDM",
      "business_service_rule": {
        "address_criteria": {
          "bidirectional": 1,
          "max_num_hops": 1,
          "starting_addresses": [
            {
              "address": "172.31.1.101",
              "port": 0
            },
            {
              "address": "172.31.1.102",
              "port": 0
            },
            {
              "address": "172.31.1.103",
              "port": 0
            }
          ]
        },
        "criteria_type": 1,
        "exclusion_source_ip_range": "",
        "exclusion_target_ip_range": "",
        "exclusion_port_range": "",
        "filter_criteria": {
          "port_range": "",
          "source_ip_range": "",
          "target_ip_range": ""
        },
        "inactive_limit_hours": null,
        "inclusion_source_ip_range": "",
        "inclusion_target_ip_range": "",
        "inclusion_port_range": "",
        "layout": "{\"ids\":{\"5f358bbae4b04797b0361b5f\":{\"id\":\"5f358bbae4b04797b0361b5f\",\"ip\":\"172.26.12.220\",\"coords\":{\"x\":\"157.03842280030557\",\"y\":\"576.0152235177147\"}},\"60fecc42a184e9863610c93b\":{\"id\":\"60fecc42a184e9863610c93b\",\"ip\":\"172.31.1.101\",\"coords\":{\"x\":\"575.7075985888532\",\"y\":\"480.0187925182129\"}},\"60fecc78a184e9c42810c93d\":{\"id\":\"60fecc78a184e9c42810c93d\",\"ip\":\"172.31.1.102\",\"coords\":{\"x\":\"445.15285055140413\",\"y\":\"333.028166711671\"}},\"60fecca7a184e9e12810c8aa\":{\"id\":\"60fecca7a184e9e12810c8aa\",\"ip\":\"172.31.1.103\",\"coords\":{\"x\":\"423.7448309327726\",\"y\":\"708.2995310913407\"}},\"62156433e4b0cf729aa3460f\":{\"id\":\"62156433e4b0cf729aa3460f\",\"ip\":\"192.168.4.99\",\"coords\":{\"x\":\"137.3874682503052\",\"y\":\"251.55186277871735\"}}},\"controls\":{\"control_categories\":[\"application\",\"network\",\"storage\",\"virtual\"],\"control_map_layout\":\"preset\",\"control_pendings\":[\"0\",\"1\"],\"control_statuses\":[\"1\",\"0\"]}}",
        "min_num_packets": 1,
        "result": "0 created, 6 updated, 0 deleted and 0 skipped",
        "skip_count": 0,
        "status": 1,
        "url_criteria": {
          "bidirectional": 0,
          "max_num_hops": 1,
          "starting_urls": []
        },
        "start_time": 1661522137,
        "finish_time": 1661522137
      },
      "delegate_ci": {
        "edge_device": "AWS Edge",
        "ci": "AWS Environment Service Group Delegate"
      },
      "name": "AWS Environment",
      "servicegrouptypeid": 1,
      "ci": [
        {
          "edge_device": "AWS Edge",
          "ci": "AWS Environment Service Group Delegate"
        }
      ],
      "logicalgroup": [
        "App Servers",
        "Mongo Servers",
        "Web Servers"
      ],
      "firescope_id": "5ec575ace20b4d7b7c1b4254"
    }
  ]
}

Create or Update

To create or update a Service Group, POST a JSON document with the specific information for that Service Group to the following URL:

https://localhost:38060/web_services/servicegroup

Don’t forget 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": "SDDM",
  "business_service_rule": {
    "address_criteria": {
      "bidirectional": 1,
      "max_num_hops": 1,
      "starting_addresses": [
        {
          "address": "172.31.1.101",
          "port": 0
        }
      ]
    },
    "criteria_type": 1,
    "exclusion_source_ip_range": "",
    "exclusion_target_ip_range": "",
    "exclusion_port_range": "",
    "filter_criteria": {
      "port_range": "",
      "source_ip_range": "",
      "target_ip_range": ""
    },
    "inactive_limit_hours": null,
    "inclusion_source_ip_range": "",
    "inclusion_target_ip_range": "",
    "inclusion_port_range": "",
    "min_num_packets": 1,
    "status": 1,
    "url_criteria": {
      "bidirectional": 0,
      "max_num_hops": 1,
      "starting_urls": []
    }
  },
  "delegate_ci": {
    "edge_device": "AWS Dev Edge",
    "ci": "AWS Dev Environment Service Group Delegate"
  },
  "name": "AWS Dev Environment",
  "servicegrouptypeid": 1,
  "ci": [
    {
      "edge_device": "AWS Dev Edge",
      "ci": "AWS Dev Environment Service Group Delegate"
    }
  ],
  "logicalgroup": [
    "App Servers",
    "Mongo Servers",
    "Web Servers"
  ]
}

Property Descriptions

Property Description Type Default Required
account_id Name of the FireScope Account. String   Yes
name Name of the Service Group. String   Yes
servicegrouptypeid Type of Service Group.
Possible values:
  • 1 Business Service Group
  • 2 Infrastructure Service Group
  • 3 Operational Service Group
 Number 1 Yes
business_service_rule Contains the configuration for reading flows to generate CI Relationships. See Business Service Rule Object below. Object   Yes
ci Array of CIs assigned to this Service Group directly. See Minimal CI Object below. Object[] [ ] No
delegate_ci A CI chosen to be the Delegate for Attributes & Event Definitions related to changes against the baseline CI Relationship approvals. See Minimal CI Object below. Object [ ] If Business Service Rules are enabled.
logicalgroup The exact names of the Logical Groups associated with the Service Group. String[] [ ] No

Business Service Rule Object

Property Description Type Default Required
criteria_type Sets the processing method for generating CI Relationships:
  • 0 Nothing
  • 1 Starting Address
  • 2 Traffic URLs
  • 3 Traffic IP/Port Filter
  • 4 Topology Discovery Job
  • 5 Virtual Discovery Job
 Number 0 Yes
min_num_packets A minimum number of average packets required for a flow object to be included in CI Relationship consideration. Min: 0 Number 2 Yes
status Whether to process the configured criteria_type to generate CI Relationships:
  • 0 Disabled
  • 1 Enabled
 Number 0 Yes
address_criteria Contains the configuration for processing CI Relationships based those connected in a chain starting from the provided IPs/Host Names. See Address Criteria Object below. Object   If criteria_type=1
filter_criteria Contains the configuration for processing CI Relationships based on those matching the provided Ports, and/or belonging to the Source or Target IP Ranges. See Filter Criteria Object below. Object   if criteria_type=2
url_criteria Contains the configuration for processing CI Relationships based on those connected in a chain starting from the CIs associated with the provided URLs. See URL Criteria Object below. Object   if criteria_type=3
exclusion_port_range Port Blacklist: A comma-separated list of individual Ports or Port Ranges to exclude from CI Relationship consideration. String   No
exclusion_source_ip_range Source Blacklist: A comma-separated list of individual IPs, IP Octet Ranges, or CIDRs to exclude from source consideration. String   No
exclusion_target_ip_range Target Blacklist: A comma-separated list of individual IPs, IP Octet Ranges, or CIDRs to exclude from target consideration. String   No
inactive_limit_hours An override to the global inactivity timeout to mark a CI Relationship as pending_delete=1; value is in hours. Number   No
inclusion_port_range Port Whitelist: A comma-separated list of individual Ports or Port Ranges to ONLY consider for CI Relationship inclusion. String   No
inclusion_source_ip_range Source Whitelist: A comma-separated list of individual IPs, IP Octet Ranges, or CIDRs to ONLY consider for source inclusion. String   No
inclusion_target_ip_range Target Whitelist: A comma-separated list of individual IPs, IP Octet Ranges, or CIDRs to ONLY consider for target inclusion. String   No
Address Criteria Object
Property Description Type Default Required
bidirectional Whether the source-target chain look at traffic from the target back to the source:
  • 0 Disabled
  • 1 Enabled
 Number 0 Yes
max_num_hops The maximum number of hops to traverse in the source-target chain. Min: 1; Max 5 Number 1 Yes
starting_addresses Array of IP/Host Names and optional ports to use as staring points in the source-target chain processing. See Starting Address Object below. Object[] [ ] Yes
Starting Address Object
Property Description Type Default Required
address The IP or Host Name to use as a starting point in the source-target chain. String   Yes
port Optional Port to use in determining which Addresses quality as "starting points". For example, a port could be used to only include a server if it is receiving traffic on the provided port. Number 0 No

Filter Criteria Object
Property Description Type Required
port_range A comma-separated list of ports or port ranges to include when creating CI Relationships. String Yes, if empty source_ip_range and target_ip_range
source_ip_range A comma-separated list of individual IPs or CIDRs to include as sources when creating CI Relationships. String Yes, if empty port_range and target_ip_range
target_ip_range A comma-separated list of individual IPs or CIDRs to include as targets when creating CI Relationships. String Yes, if empty port_range and source_ip_range
URL Criteria Object
Property Description Type Default Required
bidirectional Whether the source-target chain look at traffic from the target back to the source:
  • 0 Disabled
  • 1 Enabled
 Number 0 Yes
max_num_hops The maximum number of hops to traverse in the source-target chain. Min: 1; Max 5 Number 1 Yes
starting_urls A comma-separated list of URLs to use as staring points in the source-target chain processing. String   Yes

Minimal CI Object

Property Description Type Default
ci The exact name of the CI. String  
edge_device_id The exact name of the Edge Device assigned to the CI. String  

Delete

To delete a Service Group, send an DELETE request with the same query parameters as the Direct Fetch request.

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    How-To
    Target Group
    Customer
  2. Tags
    1. API
    2. FireScope
    3. REST
    4. SDDM
    5. Service Groups