Skip to main content

HTTP GET 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 Predefined Configurations for an overview of all predefined configurations provided by squid by arc46.

Query Parameter​

The configuration on its own is only of limited use. Query parameter allow the caller to request a specific entity, filter results, add relations to the request and further influence the behavior of squid by arc46.

relations​

Resolving references and relations is the added value of squid by arc46. References are resolved by default. Relations must be explicitly requested. See Predefined Relations for an overview of all predefined relations provided by squid by arc46.

Relations are requested as query parameters relations. squid by arc46 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.

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

*.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 by arc46 to add the given relations whenever an entity is rendered with a configuration configName.

As with relations squid by arc46 accepts this parameter in various formats:

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

Use whatever fits your calling application best.

Try it: TODO generate demo entity and create link.

encodedQuery​

ServiceNow has the concept of 'encodedQueries'.

See ServiceNow: 'Encoded query strings' for details on how to structure a query.
See ServiceNow: 'Operators available for filters and queries' for details on available operators for encodedQueries.

Usage in the context of squid by arc46​

squid by arc46 uses ServiceNow database views to

a) define what data is retrieved and
b) aggregate data of multiple tables in a single JSON.

Every table that is incorporated into a ServiceNow database view must have a so-called 'Variable prefix'. By convention all squid by arc46 database views use 'base' as the 'Variable prefix' for the base table. (If you want to use existing database views that do not follow this naming convention, the prefix can be changed in any specific configuration.)

The prefixes for any additional outer left joined tables are documented in the corresponding configuration documentation.

Field Names​

squid by arc46 removes the database view specific 'Variable prefixes' to present the returned JSON in a more expected format. Instead of base_sys_id we return sys_id.

For ServiceNow to understand a given encodedQuery we have to use the field names defined on the database view that we are querying, i.e. we have to set conditions on base_sys_id instead of sys_id.

A future release will take care of this for you, but we're not quiet there yet.

Supported encodedQuery Operators​

  • ^ / ^OR (AND/OR)
  • =, !=
  • STARTSWITH
  • ISEMPTY / ISNOTEMPTY
  • EMPTYSTRING
  • IN / NOT IN
  • < / <= / >= / > / BETWEEN / MORETHAN / LESSTHAN
  • SAMEAS / NSAMEAS
  • GT_FIELD / GT_OR_EQUALS_FIELD / LT_FIELD / LT_OR_EQAULS_FIELD
  • RELATIVEGT / RELATIVELT
  • VALCHANGES / CHANGESFROM / CHANGESTO
  • . (dot walking)

As always with database queries handle with care. The above operators will cause full table scans if the queried fields are not indexed. squid by arc46 has no plausible way of checking for the existence of an index. (This is technically possible, but the performance impact on each and every request does not justify that approach.)

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

Restricted encodedQuery Operators​

squid by arc46 is built to deliver large amounts of data in the most performant way possible without impacting your ServiceNow instance. We therefore prevent encodedQueries from executing operations that have the potential of having a noticeable impact on your instance. Anything that would cause a full table scan with text search, order by operations etc. are by default rejected.

As the performance of database queries always depends on the exact query and the presence of indexes our categorizing of operators into critical (restricted) and non-critical (unrestricted) can only be a best effort.

For you to better understand why we are restricting at all we have included the following anecdotal query durations:

Querying cmdb_ci with 1.1 million entries. (These are just anecdotal values to give an impression of what we're talking about. This is NOT a full-fledged performance evaluation. Measurement after 5 warmup queries.)

FieldSTARTSWITHLIKEENDSWITHORDERBY
name - indexed2ms1900ms1900ms48ms
environment - not indexed3500ms3500ms3500ms4700ms

Restricting encoded queries in this way might sound heavy-handed, but in most use cases the caller of squid by arc46 is coming from a peripheral system that has little to nothing to do with ServiceNow other than that it needs data. The caller will probably neither know nor notice any negative impact he or she is causing.

We however recognize that there may be valid use cases when these operators are necessary and useful. Configurations therefore have a property Restrict Encoded Query that is set to true on all predefined configurations. If this property is set to true the following operators are NOT allowed. If you wish to allow these operators, create a new configuration and set the Restrict Encoded Query to false.

  • % / ENDSWITH
  • * / LIKE / CONTAINS
  • !* / NOT LIKE
  • javascript (Anything that requires javascript is restricted)
  • ORDERBY
  • 123TEXTQUERY321 / 123TEXTINDEXGROUP321

Unless the requested configuration explicitly allows the use of restricted operators, including any of the restricted operators in an encodedQuery is considered an error condition and the request is rejected.

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

Forbidden for security reasons​

  • NQ - squid by arc46 allows configurations to be restricted by the role of the caller and configurations to define view filter that limit the returned data. Both together are a security feature (TODO add link to corresponding documentation).
    NQ would add a top level OR clause to any query allowing a caller to circumvent any set restrictions.

Including a forbidden operator in an encodedQuery is considered an error condition and the request is rejected.

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

Use restricted encodedQuery operators in view_filter​

Configurations have a property called view_filter. This allows an squid by arc46 administrator to add an encodedQuery to the configuration. This encodedQuery is NOT restricted in any way as it is defined by an squid by arc46 administrator.

Time/Date values​

Time/Date values are a difficult topic in a ServiceNow context. ServiceNow will accept nonsense Time/Date values without throwing any kind of error and just make a best effort. This will give you the impression of your query being correct until you notice that your results do not match what you were expecting.

The following is based on trial and error:

encodedQuery=base_sys_updated_on>2024-04-22 23:00:00 will be read as '2024-04-22 23:00:00 UTC' as will

encodedQuery=base_sys_updated_on>2024-04-22T23:00:01
encodedQuery=base_sys_updated_on>2024-04-22T23:00:01Z
encodedQuery=base_sys_updated_on>2024-04-22T23:00:01nonsense(!)

warning

encodedQuery=base_sys_updated_on>2024-04-22x23:00:01 will be accepted as valid encodedQuery, but ServiceNow will only interpret the first part, i.e. '2024-04-22' resulting in a query value of '2024-04-22 00:00:00 UTC'.

Please be sure to check any encodedQueries that use Time/Date values.

encodedQuery (HTTP) query parameter format​

squid by arc46 will accept encoded queries as

encodedQuery=yourEncodedQuery

Multiple values are considered an error condition.

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

tags (cmdb_key_value)​

EARLY ACCESS FEATURE

This feature is only available to EARLY ACCESS CUSTOMERS.

WORK IN PROGRESS

This documentation is work-in-progress and subject to change.

All public cloud provider have adopted tags as way of adding metadata to entities (AWS, Azure, GCP).

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

In order to support querying tags in squid we offer the tags query parameter. Both AND and OR conditions are supported.

Syntax: tags=tagName=value1,value2,value3.

tags is the query parameter
tagName is the tag name, i.e. the key in cmdb_key_value
value1,value2,value3 are the values, i.e. the valuein cmdb_key_value, the query should filter on. Multiple values are combined as OR condition.

Multiple tags are AND combined.

tags=tagName=value1&tags=tagName=value2 would be result in a query returning entities that have a tag tagName=value1 AND a tag tagName=value2

warning

tags=tagName=value1,value2
is NOT the same as
tags=tagName=value1&tags=tagName=value2

The first expression requires one tag with name tagName and value being one of value1 OR value2.

The second expression requires two tags. Both tags with name tagName but one with value value1 and another with value value2.

teams (cmdb_rel_team)​

EARLY ACCESS FEATURE

This feature is only available to EARLY ACCESS CUSTOMERS.

WORK IN PROGRESS

This documentation is work-in-progress and subject to change.

squid supports a teamsquery parameter.

Syntax: teams=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 tags are AND combined.

warning

teams=managed_by=group1,group2
is NOT the same as
teams=managed_by=group11&teams=managed_by=group2

The first expression will restrict the query to CIs that are managed_by group1 OR group2.

The second expression will restrict the query to CIs that are managed_by group1 AND group2.

showBlank​

By default, squid by arc46 will surpress 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 by arc46 to render null JSON properties.

Only the presence showBlank is checked, not the value. (showBlank ≡ showBlank=true ≡ showBlank=false)

Try it:

sys_id​

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

squid by arc46 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 by arc46 only accepts and returns ISO8601 Date/Time values (except when encoded in encodedQueries).

Multiple values are considered an error condition.

Try it:

preservePrefix​

squid by arc46 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.

Try it: https://demo.squid46.io/cmdb_ci_server?limit=1&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. Accordingly multiple configs will be returned as comma seperated list in the squid_config property.

The query parameter showConfig will add a property squid_config to each and every returned entity.

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

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

Last updated on