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 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 quite 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
  • DYNAMIC
  • SUBQUERY / ENDSUBQUERY / JOIN
  • . (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 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
  • RLQUERY / ENDRLQUERY

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

warning

squid reserves the right to expand the above-mentioned list of restricted encoded query operators at any point in time.

ServiceNow may implement new encoded query operators or undocumented operators may come to our attention. If considered
potentially performance critical, these will be added to the above list at our discretion. Please check the release notes for any changes.

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

squid error!

Version 1.0.0 checks for NQ case-insensitive, i.e. any encoded query including NQ, nq, Nq or nQ will be rejected as forbidden. This is obviously not what was intended. Version 1.0.1 correctly checks for ^NQ (case-sensitive)

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

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
We track. Ok?