Flags
Flags are query parameters 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:
- https://demo.squid46.io/cmdb_ci_server_full?limit=1&showBlank
- https://demo.squid46.io/cmdb_ci_server_full?limit=1
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.
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):
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": {
"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": {
"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:
showTagsdefaults toshowTags=objectshowTags=objectshowTags=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.
{
...,
"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"
}
},
...
]
}
{
...,
"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
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