Configurations

When retrieving data from squid, you always request a specific configuration.

You call 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
• how references and relations are rendered
• which relations are allowed
• who can access the configuration

More generally speaking configurations define how entities are rendered in squid. In this broader sense configurations are also used to define how referenced entities or entities accessed as relations are rendered.

A configuration is only a starting point. Requests may be further fine-tuned. See API Call

Predefined Configurations

Squid comes with 217 (Release 1.1.0) predefined, ready to use configurations.

Defining Custom Configurations

Predefined configurations are readonly and cannot be edited.

You can create custom, new configurations in the Configs table.

Configuration Name

Configuration Name is the name of the configuration. This name is used

• as part of the request URL. The URL is https://yourinstance/api/x_a46gh_squidx/v1/data/{configName} where {configName} is the name of the configuration you are requesting. See API Call.
• as targetConfig when defining references and relations.

Any configurations with the same name as a predefined configuration will have precedence over the predefined configurations. This allows your peripheral systems to start using the predefined configurations and then switch to your proprietary configurations without changing anything in the calling systems.

Database View

Database view defines which database view is used to retrieve data.

The database view defines what data a configuration will return.

Only visible to admin users

The ServiceNow table sys_db_view defines a read ACL that delegates to the role admin. ('admin role required to read Database View records'). The field Database View is a reference to a row in sys_db_view and ServiceNow will not - if you do not have access - render this field. It just won't be displayed.

From a squid user point of view this is regrettable as it prevents non-admin users from seeing what a squid configuration will actually return, i.e., the database view.

This isn't a real problem if you're only using predefined squid configurations as these are all fully documented on this website.

If however you are defining custom configurations, you will either have to document these analog to the predefined configurations you find here or grant access to sys_db_view to non-admin users.

Please evaluate if this is a problem and if you want to expand read access for sys_db_view to non-admin users.

Primary Database View Prefix

squid requires that one table be defined as base table that includes a sysId. squid only returns data with an entry in the base table. Additional tables may be joined to this base table.

Every table that is incorporated into a ServiceNow database view must have a so-called 'Variable prefix'.

The Primary Database View Prefix defines the prefix that is used by the base table. squid identifies the base table by the value of this field. By convention all squid database views use 'base' as the 'Variable prefix' for the base table.

You are free to use any other prefix. This might be useful if you want to reuse existing database views that do not follow this naming convention.

Preserve Prefix

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 defined as part of the configuration but is also available as a query parameter.

You can see the effect with this query 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
    }
   ]
}

Excluded Database View Prefixes

Excluded Database View Prefixes is a comma seperated list of all prefixes that should not be rendered.

Specific use cases may require that you include tables in a database view that are relevant for either the join or filtering data. You could e.g., resolve cmdb_rel_team relations in a database view resulting in a more classical rendering of one row (JSON object) including teams in the object itself instead of using squid relations.

{
  "data": [
    {
      "asset_tag": "P1000173",
      "team": "Support Group"
    }
   ]
}

For this to work, you will have to include cmdb_rel_team in the view

• in order to filter on a specific group type and
• to reach the sys_user_group at the end of the relation

but you do not want to include all the details of the join in the rendered JSON.

Excluded Database View Prefixes allows you to include cmdb_rel_team for join and filtering purposes but excluded the prefix rel for rendering purposes.

Is Root

A Configuration can be either requested explicitly as part of the API call or indirectly as a targetConfig of a reference or relation.

A usecase would be that you want to allow calling systems to retrieve sys_user_group when referenced by a CI, but prevent a calling system from retrieving all sys_user_group entities directly.

Is Root indicates if a configuration may be requested as part of an API call (true) or only indirectly as a reference or relation (false).

View Filter

ServiceNow database views aren't database views as you would expect in a database. They are restricted to defining joins between tables. Conditions are not supported.

View Filter defines an encodedQuery that is applied to the database view.

Description

Description is a free text field that can be used to describe the configuration. Please use this field to document configurations. Unless you adhere to a very strict naming policy, you will very quickly not know what configurations are being used by whom for what.

References & Relations

Allow Inline Relations

Head over to RenderTypes if the difference between inline and non-inline references and relations is unclear.

Some use cases require that references and relations are rendered inline. A single entity request by a dev-ops pipeline will greatly appreciate not having to resolve the indirection of relations and referenced and squid is all about making things easier for data consumers.

But... inline content is extremely resource intensive. Depending on the requested references and relations rendering inline content may create an extreme load on your database. Think entity with 10 references that each have 5 further references. A caller requesting 100.000 of these entities will - unknowingly - cause 5.000.000 database queries as opposed to 5-10 database queries when references and relations are not rendered inline.

Allow Inline Relations lets you restrict the use of inline references and relations.

In combination with Limit this can prevent callers from unwittingly crashing your instance while allowing for legitimate use cases.

Please see RenderType for details on the impact of the various render types.

Limit

limit allows you to limit the amount of entities returned. As mentioned in the paragraph above, inline rendering can cause an exessive amount of database queries. limit mitigates this risk.

Use limit on all inline configurations!

We strongly suggest setting limit on all configurations that allow inline rendering!

If the query parameter limit is set, the lower value is used.

Reference Group Names

Reference Group Names define what entries in References or References (Predefined) are applied when rendering references.

By default, and without any further configuration, Reference Group Names default as well as configName are implied and used to resolve reference configurations.

Any Reference Group Names defined in a configuration are utilized when resolving reference configurations.

Precedence:

• configName
• any referenceGroupNames defined in the configuration in the order as given
• default

I don't get it! Give me an example!

References just work. Your entity has a reference to a cmdb_ci_server? That reference will be rendered with the configuration cmdb_ci_server.

But sometimes this default behavior is not enough.

The reference fields life_cycle_stage and life_cycle_stage_status are defined as classes life_cycle_stage and life_cycle_stage_status.

A default rendering of these references would be fairly useless or at least cumbersome:

{
  ...,
  "life_cycle_stage": {
    "sys_id": "Operational",
    "sys_class_name": "life_cycle_stage"
  },
  "life_cycle_stage_status": {
    "sys_id": "In Use",
    "sys_class_name": "life_cycle_stage_status"
  },
  ...
}

What we would much rather prefer is something like:

{
  ...,
  "life_cycle_stage": "Operational",
  "life_cycle_stage_status": "In Use",
  ...
}

The solution is to define reference configurations for life_cycle_stage and life_cycle_stage_status telling Squid to render these references literally.

Relations Restricted

This flag indicates if all relations may be requested (not set) or if only the relations defined in Allowed Relations are allowed (set).

Security Feature

Relations Restricted is a security feature.

Access to configurations may be restricted to specific roles. This however has no effect on possibly requested relations.

Let's assume that you want to grant a role access to the configuration cmdb_ci_server. Any caller could additionally request the relation ci_to_user_group which might be information the caller should not be able to see.

If Relations Restricted is checked only relations defined in Allowed Relations are allowed.

Allowed Relations

A comma seperated list of all relations that are allowed for this configuration.

This only has any effect if Relations Restricted is checked.

Security & Access Control

Use ServiceNow ACLs

Roles

Restrict Encoded Query