Skip to main content

API Call

Squid supports HTTP GET requests and returns JSON.

Request​

Squid API Request OverviewOverview diagram showing the structure of a Squid API request. A Squid URL consists of: 1. Base path (fixed): /api/x_a46gh_squidx/v1/data/ 2. Configuration name: The primary element - determines database view, fields, reference handling, and available relations 3. Query parameters in three categories: - Filters (purple): Restrict which records return - Relations (red): Include related entities - Flags (gray): Toggle output features/api/x_a46gh_squidx/v1/data/Base path (fixed)cmdb_ci_serverConfiguration?encodedQuery=base_name=myserverFilters&relations=network_ports,used_byRelations&showTags&...FlagsConfigurationThe configuration defines what data is returned and how it's rendered.QUERY PARAMETERSFiltersRestrict which records returnencodedQuerysys_idlimitupdatedSincefilterOnTagsfilterOnTeamsRelationsInclude related entitiesrelations{config}.relations1:N, M:N, CMDB relationsFlagsToggle output featuresshowBlankshowTagsshowConfigmetaDatapreservePrefixlenient

The URL is https://yourinstance/api/x_a46gh_squidx/v1/data/{configName} where {configName} is the name of the configuration you are requesting. Configurations define what data is returned—for example, cmdb_ci_server returns all server CIs. See Predefined Configurations for available configurations.

Query parameters refine requests: filter results, request specific entities, include relations, and toggle output features.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?limit=10

info

The demo server is proxied and rate limited. If you're getting HTTP 429s, slow down! (This is only an issue on the publicly available demo server.)

To keep URLs shorter and more readable, all links to https://demo.squid46.io omit the /api/x_a46gh_squidx/v1/data/ path segment.

Response​

Before diving into query parameters, it helps to understand what Squid returns. Every response contains four sections:

Squid Response StructureThis diagram illustrates the structure of a Squid JSON response, showing how the four main sections connect to provide complete entity data with resolved references and relations. RESPONSE STRUCTURE - A Squid response contains four top-level sections: 1. METADATA - Request information and statistics 2. DATA - Array of requested entities with reference stubs 3. RELATIONS - Related entities organized by parent sys_id 4. REFERENCED - Fully resolved reference and relation data The diagram uses color-coded sys_ids to show how references resolve: - Cyan "abc" in data matches the key "abc" in relations - Purple "xyz" in data.assigned_to resolves to "xyz" in referenced - Purple "g1" in relations resolves to "g1" in referencedSQUID RESPONSEapplication/json"metadata"{ config, row_count, provided_filter, ... }"data"[ array of entities ]{"sys_id": "abc","name": "Server01","assigned_to": { "sys_id": "xyz" }}"relations"{ keyed by entity sys_id }"abc": {"user_groups": [{ "sys_id": "g1" }, ...]}"referenced"{ resolved entities }"xyz": {"name": "John Smith","email": "john@example.com","sys_class_name": "sys_user"},"g1": {"name": "Admins","active": true,"sys_class_name": "sys_user_group"}HOW IT CONNECTSEntity sys_id links data → relationsReference sys_ids resolve in "referenced"No data duplication
  • metadata — Request information, timing, and filter details
  • data — Array of requested entities
  • relations — Related entities, organized by parent sys_id
  • referenced — Complete data for all referenced and related entities

This structure avoids data duplication: an entity referenced multiple times appears once in referenced.

Relations​

Resolving references and relations is the added value of Squid. References are resolved by default and do not have to be explicitly requested. Relations require additional database queries and are only resolved if requested.

Squid supports three different types of relations:

Squid Relation Types OverviewThis diagram explains the three types of relations Squid supports for retrieving related data from ServiceNow. The diagram uses a vertical layout with one section per relation type. 1. 1:N RELATIONS (Top section, cyan color): A child entity has a reference field pointing back to the parent entity. The diagram shows a Parent table (cmdb_ci with sys_id "abc") on the left, and a Child table (cmdb_ci_network_adapter) on the right with multiple rows, each containing a "cmdb_ci" field with value "abc" pointing back to the parent. An arrow flows from the child table back to the parent, illustrating the reference direction. Example use case: Network adapters belonging to a server, IP addresses on a NIC. Key characteristic: Child references parent via a field. Single efficient query. 2. M:N RELATIONS (Middle section, purple color): A junction table connects two entities via reference fields (from_column and to_column). The diagram shows three tables: Table A (cmdb_ci) on the left, a Junction table (cmdb_rel_team) in the center with columns for "ci", "group", and "group_type", and Table B (sys_user_group) on the right. Arrows connect Table A to the junction table's "ci" column, and the junction table's "group" column to Table B. The group_type column is highlighted as it can become a dynamic JSON property name. Example use case: Team assignments (managed_by, support, approval groups for a CI). Key characteristic: Junction table with optional column for dynamic JSON property names. 3. CI RELATIONS (Bottom section, red color): ServiceNow's native CI relationship system using the cmdb_rel_ci table. The diagram shows a Parent CI (e.g., Server) on the left, the cmdb_rel_ci table in the center with columns for "parent", "child", and "type", and a Child CI (e.g., Application) on the right. Bidirectional arrows indicate that queries can retrieve parents, children, or both. A relationship type badge shows "runs_on" as an example type. Other relationship types include: depends_on, hosts, contains, uses, virtualizes. Example use case: Server runs_on VM, Application depends_on Database. Key characteristic: Directional - query parents, children, or both. Named relationship types. All three relation types can be rendered using either "Relation" render types (batched, efficient, data in separate relations/referenced sections) or "Inline" render types (self-contained but with potential performance impact for large datasets).1:N RelationsChild references parentcmdb_cisys_id: abccmdb_ci_network_adaptercmdb_ci: abccmdb_ci: abccmdb_ci: abcChild entity contains a reference fieldpointing to the parent entity.Single query retrieves all children formultiple parents. Very efficient.Examples: network adapters, IP addresses, disksM:N RelationsJunction table connects entitiescmdb_cisys_idcmdb_rel_teamci (from)group (to)group_typesys_user_groupsys_idJunction table connects two tablesvia reference columns.Column values can become dynamicJSON property names:group_type → "managed_by", "support"Examples: team assignments, task_ci, user groupsCI Relationscmdb_rel_ciParent CIServercmdb_rel_ciparentchildtypeChild CIApplicationruns_onget_parentsget_childrenServiceNow's native CI relationshipsystem with named relationship types.Directional: query parents, children,or both directions.Relationship types:depends_on hosts runs_oncontains uses virtualizes

See Predefined Relations for an overview of all predefined relations provided by Squid.

relations​

Relations are requested as query parameter relations. Squid accepts this parameter in various formats:

  • relations=rel1,rel2,rel3
  • relations=rel1&relations=rel2&relations=rel3
  • relations=rel1,rel2&relations=rel3

Use whatever fits your calling application best.

Depending on your configurations, relations may be rendered in various ways:

This is just an overview

Please see RenderTypes for Relations for details.

and

The key distinction is where related data appears in the response:

Relation vs Inline Rendering ComparisonThis diagram compares two approaches for rendering relations in Squid responses: external (Relation) rendering and Inline rendering. The comparison helps developers choose the right approach based on their performance and data structure requirements. RELATION RENDERING (Left side, recommended default): The data array contains minimal entity stubs with sys_id references. Related entities are placed in the "relations" object, keyed by parent sys_id. Full entity details are resolved once in the "referenced" object. Example structure: - data: [{ sys_id: "abc", name: "Server1" }] - relations: { "abc": { user_groups: [{ sys_id: "g1" }, { sys_id: "g2" }] } } - referenced: { "g1": { name: "Admins", ... }, "g2": { name: "Ops", ... } } Benefits marked with checkmarks: - Efficient: batched queries, one query per relation type - No duplicates: referenced entities appear once regardless of how many times referenced - Smaller payload: avoids data repetition Tradeoff marked with circle: - Requires assembly: client must join data with relations and referenced INLINE RENDERING (Right side, use with caution): Related entities are embedded directly within the parent entity object. The relations and referenced objects remain empty. Example structure: - data: [{ sys_id: "abc", name: "Server1", user_groups: [{ name: "Admins" }, { name: "Ops" }] }] - relations: {} - referenced: {} Benefits marked with checkmarks: - Self-contained: each entity has all its data inline - Easy to consume: no assembly required, ready to use Tradeoffs marked with warning: - Performance impact: requires individual queries for each entity's relations - Data duplication: same referenced entity may appear multiple times - Larger payload: repeated data increases response size RECOMMENDATION: Use Relation rendering by default. Only use Inline when the consuming application truly benefits from self-contained entities and the performance cost is acceptable.RELATION RENDERINGDefault"data": [{"sys_id": "abc","name": "Server1"}],"relations": {"abc": {"user_groups": [{ "sys_id": "g1" },{ "sys_id": "g2" }]}}Efficient (batched queries)No duplicates in responseRequires assembly by clientINLINE RENDERINGUse with care"data": [{"sys_id": "abc","name": "Server1","user_groups": [{ "name": "Admins", ... },{ "name": "Ops", ... }]}],"relations": {},"referenced": {}Self-contained entitiesEasy to consumePerformance impact possible

Relation​

Relations are rendered not in the parent JSON object, but in a dedicated relations property. See RenderType Relation* for details.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?sys_id=5f9b83bfc0a8010e005a2b3212c9dc07&relations=ci_to_user_group

Response
{
  ...,
  "data": [
    {
      "asset_tag": "P1000182",
      "last_discovered": "2024-07-12T11:21:50Z",
      "name": "dbaix901nyc",
      "sys_class_name": "cmdb_ci_unix_server",
      "sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07",         <= sys_id of requested server
      "sys_mod_count": 12,
      "sys_updated_on": "2024-07-17T10:54:43Z"
    }
  ],
  "relations": {
    "5f9b83bfc0a8010e005a2b3212c9dc07": {                   <= sys_id of requested server
      "user_groups": [
        {
          "sys_id": "6577e5908f972410960c53ac37bdee66",     <= sys_id of user group
          "sys_class_name": "sys_user_group"
        },
        {
          "sys_id": "b85d44954a3623120004689b2d5dd60a",     <= sys_id of user group
          "sys_class_name": "sys_user_group"
        }
      ]
    }
  },
  "referenced": {
    "6577e5908f972410960c53ac37bdee66": {                   <= sys_id of user group
      "active": true,
      "name": "Infrastructure",
      "sys_created_by": "admin",
      "sys_created_on": "2021-03-30T18:56:30Z",
      "sys_id": "6577e5908f972410960c53ac37bdee66",
      "sys_mod_count": 0,
      "sys_updated_by": "admin",
      "sys_updated_on": "2021-03-30T18:56:30Z"
    },
    "b85d44954a3623120004689b2d5dd60a": {                   <= sys_id of user group
      "active": true,
      "description": "CAB approvers",
      "name": "CAB Approval",
      "sys_created_by": "admin",
      "sys_created_on": "2011-09-30T16:30:34Z",
      "sys_id": "b85d44954a3623120004689b2d5dd60a",
      "sys_mod_count": 0,
      "sys_updated_by": "admin",
      "sys_updated_on": "2011-09-30T16:30:34Z",
      "type": [
        "itil"
      ]
    }
  }
}

Inline​

Inline relations are rendered as properties of the enclosing JSON object.

Rendering relations inline may have an extreme performance impact. See RenderType Inline* for details.

Try it: https://demo.squid46.io/cmdb_ci_server_inline_minimal?sys_id=5f9b83bfc0a8010e005a2b3212c9dc07&relations=ci_to_user_group_inline

Response
{
  ...,
  "data": [
    {
      "asset_tag": "P1000182",
      "last_discovered": "2024-07-12T11:21:50Z",
      "name": "dbaix901nyc",
      "sys_class_name": "cmdb_ci_unix_server",
      "sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07",
      "sys_mod_count": 12,
      "sys_updated_on": "2024-07-17T10:54:43Z",
      "user_groups": [                                      <= ci_to_user_group_inline
        {
          "active": true,
          "name": "Infrastructure",
          "sys_created_by": "admin",
          "sys_created_on": "2021-03-30T18:56:30Z",
          "sys_id": "6577e5908f972410960c53ac37bdee66",     <= sys_id of user group
          "sys_mod_count": 0,
          "sys_updated_by": "admin",
          "sys_updated_on": "2021-03-30T18:56:30Z"
        },
        {
          "active": true,
          "description": "CAB approvers",
          "name": "CAB Approval",
          "sys_created_by": "admin",
          "sys_created_on": "2011-09-30T16:30:34Z",
          "sys_id": "b85d44954a3623120004689b2d5dd60a",     <= sys_id of user group
          "sys_mod_count": 0,
          "sys_updated_by": "admin",
          "sys_updated_on": "2011-09-30T16:30:34Z",
          "type": [
            "itil"
          ]
        }
      ]
    }
  ],
  "relations": {},
  "referenced": {},
  ...
}

{configName}.relations​

When rendering inline content you might want to request relations for referenced entities. You can do this by adding a query parameter with the following structure:

configName.relations=rel5,rel6

This tells Squid to add the given relations whenever an entity is rendered with a configuration configName.

As with relations Squid accepts this parameter in various formats:

  • configName.relations=rel5,rel6,rel7
  • configName.relations=rel5&configName.relations=rel6&configName.relations=rel7
  • configName.relations=rel5,rel6&configName.relations=rel7

Use whatever fits your calling application best.

Try it: TODO generate demo entity and create link.

Filters​

Most use cases require a specific subset of data. You will seldom want all entities in cmdb_ci_server. Squid allows you to define query parameter that restrict what data is returned, e.g. only 'all server with modelId xxx' or all PC clients updated in the last 14 days.

Squid supports the following filters:

encodedQuery​

ServiceNow encoded queries filter results using field conditions. Squid supports most operators but restricts some for performance reasons.

Basic usage: ?encodedQuery=base_name=myserver

Important: Use the database view field names with base_ prefix (e.g., base_name, base_sys_id).

See encodedQuery Reference for supported operators, restrictions, and time/date handling.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=dbaix901nyc

sys_id​

sys_id allows retrieval of one or more entities by way of their sysId.

Squid accepts this parameter in various formats:

  • sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951,1072335fc611227500c0267a21be5dc5

sys_id=5f9b83bfc0a8010e005a2b3212c9dc07&sys_id=106c5c13c61122750194a1e96cfde951&sys_id=1072335fc611227500c0267a21be5dc5

  • sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951&sys_id=1072335fc611227500c0267a21be5dc5

Use whatever fits your calling application best.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951,1072335fc611227500c0267a21be5dc5

updatedBefore / updatedSince / lastDiscoveredBefore / lastDiscoveredSince​

updatedBefore, updatedSince and lastDiscoveredBefore, lastDiscoveredSince are utility query parameters intended to make querying both values easier.

The expected DateTime format is ISO8601

  • "YYYY-MM-DD'T'hh:mm(:ss)?'Z'" or
  • "YYYYMMDD'T'hhmm(ss)?'Z'"

The given values are used as to build a filter of

  • base_sys_updated_on<givenDateTimeValue for updatedBefore
  • base_sys_updated_on>=givenDateTimeValue for updatedSince
  • base_sys_last_discovered<givenDateTimeValue for lastDiscoveredBefore
  • base_sys_last_discovered>=givenDateTimeValue for lastDiscoveredSince

Please notice that these values are inclusive for *since and exclusive for *before. (Feel free to give us feedback on this at support.arc46.io)

The 'Variable prefix' (base_) will automatically be adjusted for whatever value is defined in the requested configuration.

Squid only accepts and returns ISO8601 Date/Time values (except when encoded in encodedQueries).

Multiple values are considered an error condition.

Try it:

filterOnTags (cmdb_key_value)​

Public cloud provider have adopted tags as way of adding metadata to entities (AWS, Azure, GCP) making tags a common and established way of qualifying and accessing configuration items, especially in a dev-ops environment.

ServiceNow supports this concept by way of cmdb_key_value. This table is populated by Cloud Discovery, but may also be populated directly.

Tags are not Tags

ServiceNow uses the term tag for a slightly different concept. See Tags for details on the ServiceNow usage.

Squid users are mainly peripheral systems or devOps integrations. These users generally understand tag as described by the major public cloud providers. We try to make life easy for our users.

filterOnTags allows restricting the returned data to only configuration items (cmdb_key_value only allows references to cmdb_ci) that are referenced by at least one key-value entry in cmdb_key_value that matches the given criteria.

Negative filtering, i.e., returning only configurations items that are NOT referenced by a specific key-value entry, is NOT supported.

filterOnTags does NOT change the returned data, i.e., it does not implicitly add tags to the returned configuration items. filterOnTags only filters (nomen-est-omen) data.

See showTags/showTagsInline below for details on how to render tags for configuration items.

filterOnTags query parameter have the following structure:

filterOnTags=tagClause1^ORtagClause2^ANDtagClause3

Following ServiceNow GlideRecord conventions (but contrary to what you might be used to from SQL) ^OR has precedence over ^AND! The above filterOnTags query parameter would result in

(tagClause1 OR tagClause2) AND tagClause3

tagClauses have the following structure:

  • tagName / tagName=* - filters on having a tag with key=tagName ignoring value
  • tagName* / tagName*=* - filters on having a tag with keySTARTSWITHtagName ignoring value
  • tagName= - filters on having a tag with key=tagName andvalue=null
  • tagName*= - filters on having a tag with keySTARTSWITHtagName andvalue=null
  • tagName=value1(,value2,...) - filters on having a tag with key=tagName and a value of value1 OR value2
  • tagName*=value1(,value2,...) - filters on having a tag with keySTARTSWITHtagName and a value of value1 OR value2

Value wildcards (value*) are NOT supported.

Multiple filterOnTags query parameter are AND combined.

filterOnTags=tagName1=value1&filterOnTags=tagName2=value2 is equivalent to filterOnTags=tagName1=value1^ANDtagName2=value2

filterOnTeams (cmdb_rel_team)​

filterOnTeams allows restricting the returned data to only configuration items (cmdb_rel_team only allows references to cmdb_ci) that are referenced by at least one entry in cmdb_rel_team that matches the given criteria.

Negative filtering, i.e., returning only configurations items that are NOT referenced by a specific team relation, is NOT supported.

filterOnTeams does NOT change the returned data, i.e., it does not implicitly add team relations to the returned configuration items. filterOnTeams only filters (nomen-est-omen) data.

In order to include Teams relation, request one of the predefined Teams relations.

filterOnTeams query parameter have the following structure:

filterOnTeams=group_type=group1,group2,group3

group_type is e.g. managed_by, approval

group1,group2,group3 are either sysIds of a sys_user_group or the name of a sys_user_group. If a name is given Squid will attempt to resolve the name to a sysId. Multiple values are combined as OR condition.

Multiple filterOnTeams query parameter are AND combined.

filterOnTeams=managed_by=group1,group2 will restrict the query to CIs that are
managed_by group1 OR group2.

filterOnTeams=managed_by=group11&filterOnTeams=managed_by=group2 will restrict the query to CIs that are
managed_by group1AND group2.

limit​

limit allows you to limit the amount of entities returned. This is of limited use in a production environment, but during development you might want to test your queries with just 10 returned entities instead of 10.000.

As the order of the result set is intentionally undefined, which entities are returned may vary from call to call.

Try it: https://demo.squid46.io/cmdb_ci_server_minimal?limit=5

Flags​

Flags are query parameter that turn on features.

showBlank​

By default, Squid will suppress any properties with a null value.

Some client libraries might rely on a stable JSON structure and not play nice with missing JSON properties.

The query parameter showBlank will cause Squid to render null JSON properties.

Try it:

showTags​

Public cloud provider have adopted tags as way of adding metadata to entities (AWS, Azure, GCP) making tags a common and established way of qualifying and accessing configuration items, especially in a dev-ops environment.

ServiceNow supports this concept by way of cmdb_key_value. This table is populated by Cloud Discovery, but may also be populated directly.

Tags are not Tags

ServiceNow uses the term tag for a slightly different concept. See Tags for details on the ServiceNow usage.

Squid users are mainly peripheral systems or devOps integrations. These users generally understand tag as described by the major public cloud providers. We try to make life easy for our users.

Just as relations, resolving tags requires at least one additional database query. For this reason, tags are only rendered when explicitly requested.

The query parameter showTags tells Squid to retrieve and render tags belonging to a configuration item.

Tags can be rendered in two locations (external vs inline) and two formats (object vs array):

Tags Rendering Comparison MatrixThis diagram presents a 2×2 matrix comparing the four ways to render tags (cmdb_key_value entries) in Squid responses. The two dimensions are: 1. Location: External (showTags) vs Inline (showTagsInline) 2. Format: Object vs Array TOP-LEFT: EXTERNAL + OBJECT (showTags or showTags=object) Tags appear in a separate "tags" object at the response root, keyed by entity sys_id. Format uses key-value pairs where the tag name is the property name. Example: "tags": { "abc123": { "Environment": "Production", "Owner": "IT Ops" } } Pros: Clean, intuitive structure; easy to access by tag name; smallest payload. Cons: Cannot represent duplicate tag names (only one value per key); structure varies by data. TOP-RIGHT: EXTERNAL + ARRAY (showTags=array) Tags appear in a separate "tags" object at the response root, keyed by entity sys_id. Format uses an array of {name, value} objects. Example: "tags": { "abc123": [{ "name": "Environment", "value": "Production" }] } Pros: Handles duplicate tag names; predictable structure for deserialization. Cons: More verbose; requires iteration to find specific tags. BOTTOM-LEFT: INLINE + OBJECT (showTagsInline or showTagsInline=object) Tags are embedded directly in each entity object as a "tags" property. Format uses key-value pairs. Example: "data": [{ "name": "Server1", "tags": { "Environment": "Production" } }] Pros: Self-contained entities; no assembly required. Cons: Performance impact (individual queries per entity); can't handle duplicate names. Requires "Allow Inline Relations" enabled in configuration. BOTTOM-RIGHT: INLINE + ARRAY (showTagsInline=array) Tags are embedded directly in each entity object as a "tags" property. Format uses an array of {name, value} objects. Example: "data": [{ "name": "Server1", "tags": [{ "name": "Environment", "value": "Production" }] }] Pros: Self-contained; handles duplicates; predictable structure. Cons: Performance impact; most verbose option. Requires "Allow Inline Relations" enabled in configuration. RECOMMENDATIONS: - Default choice: showTags=object (external + object) for simple cases with unique tag names - Need duplicate handling: showTags=array (external + array) - Need self-contained entities: showTagsInline with caution (performance impact) - Strict typing/deserialization: Array format provides predictable structureOBJECT FORMAT{ "TagName": "value" }ARRAY FORMAT[{ name, value }]EXTERNALshowTagsINLINEshowTagsInlineshowTags=objectDefault"tags": {"abc": {"Environment": "Prod","Owner": "IT Ops"}}Clean syntaxSmallest payloadNo duplicate namesshowTags=array"tags": {"abc": [{ "name": "Environment","value": "Prod" },{ "name": "Owner", ... }]}Handles duplicatesPredictable structureMore verboseshowTagsInline=objectUse with care"data": [{"name": "Server1","tags": {"Environment": "Prod","Owner": "IT Ops"}}]Self-containedNo assembly neededPerformance impactNo duplicate namesshowTagsInline=arrayUse with care"data": [{"name": "Server1","tags": [{ "name": "Environment","value": "Prod" },{ "name": "Owner", ... }]}]Self-containedHandles duplicatesPerformance impactMost verbose

Squid can render tags in two formats:

As Object​

As object. This is a standard JSON object with tagName (key) as property name and value as value.

tags with queryParameter showTags=object
{
  ...,
  "tags": {
    "995390bccd34f010f8778495fd9bf7f7": {                   <= sys_id of the entity
      "Owner": "SD DC Ops",                                 <= key:value pairs
      "Location": "San Diego",
      "Environment": "Production"
    },
    "6e5314bccd34f010f8778495fd9bf72b": {
      "Owner": "SD DC Ops",
      "Environment": "Production",
      "Location": "San Diego"
    },
    "9c5314bccd34f010f8778495fd9bf710": {
      "Service": "San Diego Wiki",
      "Owner": "SD DC Ops",
      "Location": "San Diego",
      "Environment": "Production"
    },
    "821b6357c0a8018b244b9609d7010267": {
      "Owner": null
    }
  },
  ...
}

While object is easy to read intuitively it is not without problems.

ServiceNow does NOT prevent multiple tags with the same name for a single configuration item. In our example above, nothing prevents a configuration item from having two or more tags with the name Service. As object may only have * one* property with a given name, it is undefined which of the multiple values is returned.

The structure of the returned object is unknown beforehand, this may lead to problems when deserializing with some JSON frameworks.

For these reasons Squid additionally offers

As Array​

as array

The exact same data as above (with the addition of the extra 'Service' tag for demonstration purposes) renders as shown below.

tags with queryParameter showTags=array
{
  ...,
  "tags": {
    "995390bccd34f010f8778495fd9bf7f7": [                   <= sys_id of the entity
      {                                                     <= array element
        "name": "Owner",                                    <= name (key)
        "value": "SD DC Ops"                                <= value
      },
      {
        "name": "Location",
        "value": "San Diego"
      },
      {
        "name": "Environment",
        "value": "Production"
      }
    ],
    "6e5314bccd34f010f8778495fd9bf72b": [
      {
        "name": "Owner",
        "value": "SD DC Ops"
      },
      {
        "name": "Environment",
        "value": "Production"
      },
      {
        "name": "Location",
        "value": "San Diego"
      }
    ],
    "9c5314bccd34f010f8778495fd9bf710": [
      {
        "name": "Service",                                  <= Conflicting name 'Service'
        "value": "Redundant Tag!"                           <= different values for same name (key)
      },
      {
        "name": "Service",                                  <= Conflicting name 'Service'
        "value": "San Diego Wiki"                           <= different values for same name (key)
      },
      {
        "name": "Owner",
        "value": "SD DC Ops"
      },
      {
        "name": "Location",
        "value": "San Diego"
      },
      {
        "name": "Environment",
        "value": "Production"
      }
    ],
    "821b6357c0a8018b244b9609d7010267": [
      {
        "name": "Owner",
        "value": null
      }
    ]
  },
  ...
}

This is a much harder read and more verbose, but it is able to render 'conflicting' tagNames and has a predefined structure.

Allowed showTags query parameter are:

  • showTags defaults to showTags=object
  • showTags=object
  • showTags=array

showTagsInline​

Tags may also be rendered inline. The basic structure is the same as with showTags. The difference is that tags are rendered directly in the JSON object of the entity.

showTagsInline will render the tags directly as property of the referencing entity. This forces us to retrieve tags the moment we are rendering the referencing entity. This will result in a potentially very high amount of database queries.

showTagsInline is only allowed if the requested configuration has Allow Inline Relations set checked.

tags with queryParameter showTagsInline
{
  ...,
  "data": [
    {
      "name": "WA VM 02",
      "sys_class_name": "cmdb_ci_vmware_instance",
      "sys_id": "1f3350bccd34f010f8778495fd9bf7f0",
      "sys_mod_count": 6,
      "sys_updated_on": "2021-06-30T01:04:23Z",
      "tags": {
        "Environment": "Production"
      }
    },
    ...
  ]
}
tags with queryParameter showTagsInline=array
{
  ...,
  "data": [
    {
      "name": "WA VM 02",
      "sys_class_name": "cmdb_ci_vmware_instance",
      "sys_id": "1f3350bccd34f010f8778495fd9bf7f0",
      "sys_mod_count": 6,
      "sys_updated_on": "2021-06-30T01:04:23Z",
      "tags": [
        {
          "name": "Environment",
          "value": "Production"
        }
      ]
    },
    ...
  ]
}

preservePrefix​

Squid uses ServiceNow database views to aggregate data. These views prefix all properties with so-called Variable Prefixes, e.g. base_, lin_, etc.

Most of the time you do NOT want to see these prefixes. There are however use cases where preserving the prefix is essential, e.g. when aggregating tables with name collisions. In the case of two joined tables, one with the prefix base and the other with the prefix other with both having the property name would give us a raw result set with base_name and other_name, with base_name having priority and other_name being ignored. The returned JSON would only contain one property name with the value of base_name

This will usually be part of the configuration ( See Configurations - Preserve Prefix), but is also available as a query parameter. preservePrefix has precedence over configuration settings.

Try it: https://demo.squid46.io/cmdb_ci_server?limit=1&preservePrefix

{
  "data": [
    {
      "base_asset_tag": "P1000173",
      "base_classification": "Production",
      "base_company": {
        "sys_id": "e7c1f3d53790200044e0bfc8bcbe5deb",
        "sys_class_name": "core_company"
      },
      "base_cost_center": {
        "sys_id": "d9d0a971c0a80a641c20b13d99a48576",
        "sys_class_name": "cmn_cost_center"
      },
      "base_cpu_count": 1,
      "base_cpu_manufacturer": {
        "sys_id": "067018092b2692103c92f65ac891bf66",
        "sys_class_name": "core_company"
      },
      "base_cpu_speed": 3192,
      "base_cpu_type": "GenuineIntel",
      "base_discovery_source": "ServiceNow",
      "base_firewall_status": "Intranet",
      "base_install_status": 1,
      ...,
      "base_vendor": {
        "sys_id": "b7e7d7d8c0a8016900a5d7f291acce5c",
        "sys_class_name": "core_company"
      },
      "base_virtual": false
    }
   ]
}

{config}.preservePrefix​

The query parameter preservePrefix described above will only apply to the root configuration, i.e. any references or relations will be rendered according to their corresponding configuration.

{
  "data": [
   {
     "base_asset_tag": "P1000173",                          root config => base_ prefix
     "base_cpu_manufacturer": {                             
       "country": "USA",                                    reference => no prefix
       "customer": false,
       "manufacturer": false,
       "name": "Intel",
       ...
     },
     "base_cpu_speed": 3192
   }
   ]
}

{configName}.preservePrefix lets you to override the configuration setting for a specific configuration and preserve prefixes for entities rendered with that configuration.

In the above example we might want to render the manufacturer with prefixes preserved.

{
  "data": [
   {
     "base_asset_tag": "P1000173",
     "base_cpu_manufacturer": {
       "base_country": "USA",
       "base_customer": false,
       "base_manufacturer": false,
       "base_name": "Intel",
       ...
     },
     "base_cpu_speed": 3192
   }
   ]
}

Try it: https://demo.squid46.io/cmdb_ci_server_inline?limit=1&core_company_inline.preservePrefix

showConfig​

The config used to render entities is normally not part of the returned JSON and of no value to the recipient. During development, it may however help to know which configuration was used to render a specific entity.

Referenced entities may be retrieved based on multiple configs depending on the path by which they are referenced. The returned JSON will be a merge of all data returned by all relevant configs.

The query parameter showConfig will add a property squid_config to each and every returned entity as a string array of all configs used to render the entity.

{
  ...,
  "data": [
    {
      ...,
      "squid_config": [
        "cmdb_ci_server"
      ],
      ...
    }
  ],
  "relations": {},
  "referenced": {
    "067018092b2692103c92f65ac891bf66": {
      ...
      "squid_config": [
        "core_company"
      ],
      ...
    }
  }
}

Try it: https://demo.squid46.io/cmdb_ci_server?limit=1&showConfig

metaData​

metaData will add additional metadata to the returned JSON.

Try it: https://demo.squid46.io/cmdb_ci_server_inline?limit=1&metaData

lenient​

Do not use for production queries

We strongly suggest you use this query parameter ONLY during development.

Use in production can lead to unnoticed missing data!

Squid may encounter two different types of errors while processing a request.

  • configuration errors: these are errors when configurations reference non-existent target configs etc. (We might do a deep dive on why we don't validate when a configuration is created, but for now please take our word for it that this is the only realistically workable approach.)
  • query errors: these are errors when the query itself has errors, e.g., requesting a non-existent relation.

Squid now has two options:

  • crash hard and early. This is usually the safest option, but developers trying to get their queries right won't have much fun with this approach - or
  • be 'nice' and include warnings in the metadata of the returned JSON pointing developers to what went wrong.

Being nice has the risk of missing data without noticing. Who reads the metadata of a JSON in a technical API? Therefore, Squid will, by default, return an error whenever it encounters any type of problem.

Developers tweaking their queries have the option of adding a query parameter lenient. This tells Squid to play 'nice' and only add warnings to the metadata.

Some types of errors are not recoverable, e.g., requesting a non-existent configuration will result in a 404 error, regardless of whether lenient is set or not.

Try it:

Lenient: https://demo.squid46.io/cmdb_ci_server_minimal?limit=10&relations=non-existent&lenient
Not Lenient: https://demo.squid46.io/cmdb_ci_server_minimal?limit=10&relations=non-existent

Last updated on
We track. Ok?