RenderTypes for References

When to read this document

This document is intended for ServiceNow / Squid administrators wanting to understand how Squid works or creating custom configurations.

Accessing Squid as a data consumer does not require reading this document!

While References and Relations define what is to be rendered, RenderTypes define how that data is rendered.

RenderTypes have an impact on

the rendered JSON and with that what data is returned as well as how that data is structured.
the database load (some RenderTypes can cause exponentially more database queries).
your retrieved entities count. Some RenderTypes count toward your licensed entities limit.

Quick Decision Guide

Use Case	RenderType
Only need the sys_id	`SysId`
Bulk export with referenced data	`Reference`
Single entity, self-contained JSON	`Inline Content`
Field value already is the required value	`Literal`
Render ServiceNow displayValue	`Display Value`
Exclude a reference from output	`Disable`

SysId

References are 'foreign keys' on the referencing entity pointing to the referenced entity. As such the sysId of the referenced entity is already part of the referencing entity, returned when retrieving the referencing entity and can therefore be immediately rendered without any additional effort.

SysId renders a reference property as

Response
{
  "data": [
    {
      ...,
      "model_id": {                                         <= reference field name,
        "sys_id": "5f7e9a66c0a8010e008b58d466ed84b7",       <= sys_id of referenced entity
        "sys_class_name": "cmdb_model"
      },
      ...
    }
  ],
  ...
}

Nothing other than sys_id and sys_class_name, if applicable, are rendered.

SysId is the fallback, default RenderType if no RenderType is explicitly configured and a targetConfig cannot be inferred.

You can explicitly configure SysId as RenderType if that fits your use case, e.g. the caller already has data and only needs the sys_id.

SysId is very similar to what the ServiceNow TableAPI would return:

ServiceNow TableAPI Response
{
  "result": [
    {
      ...,
      "model_id": {
        "link": "https://yourinstance/api/now/table/cmdb_model/5f7e9a66c0a8010e008b58d466ed84b7",
        "value": "5f7e9a66c0a8010e008b58d466ed84b7"
      },
      ...
    }
  ]
}

SysId does not require nor support a targetConfiguration.
SysId has no memory impact.
SysId has no database impact.
SysId references do not count toward your licensed entities limit.

Reference

Reference renders a reference property exactly like SysId, but will additionally add the referenced entity at the end of the returned JSON in the referenced section.

Reference is the most efficient way to render referenced data.

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

Response
{
  "data": [
    {
      ...,
      "model_id": {
        "sys_id": "67c48433873f75503efcec230cbb3595",       <= sys_id of the referenced entity
        "sys_class_name": "cmdb_model"
      },
      ...
    }
  ],
  "relations": {},
  "referenced": {                                           <= referenced section of returned JSON,
    "67c48433873f75503efcec230cbb3595": {                   <= sys_id of the referenced entity
      "display_name": "Hewlett-Packard ProLiant DL380 Gen11",
      "life_cycle_stage": "Operational",
      "life_cycle_stage_status": "In Use",
      "manufacturer": {
        "sys_id": "b7e7a507c0a8016900920ee7d71d6df9",
        "sys_class_name": "core_company"
      },
      "name": "ProLiant DL380 Gen11",
      "sys_class_name": "cmdb_hardware_product_model",
      "sys_id": "67c48433873f75503efcec230cbb3595"
    },
    ...
  }
}

This is the default RenderType if nothing else is configured and a targetConfiguration can be inferred.

Reference supports, but does not require a targetConfiguration. See inferred.
Reference causes negligible memory load. (Caching high variance reference fields however, will cause a noticeable memory load.)
Reference has a minimal database impact of potentially one additional SQL query per targetConfiguration. (References are resolved once per request, not per reference.)
Every resolution of a Reference counts toward your licensed entities limit, unless that entity was previously cached.

Inline Content

Inline Content is the most user-friendly RenderType as it includes data where you would expect it in a structured JSON.

But...

Inline Content is the least efficient RenderType ...

... as data must be retrieved when it is rendered, potentially resulting in 100.000s or millions of SQL queries.

This isn't hyperbole.

Think 100.000 CIs, each with 10 reference properties. If all reference properties are configured as Inline Content, you are causing one million additional SQL queries (100.000 CIs x 10 references = 1.000.000 SQL queries), potentially more if Inline Content is applied recursively.

As a security precaution all predefined configurations with Allow Inline Relations are therefore limited to a maximum of 10 returned entities.

The intended usecase is for single entity data requests, e.g., DevOps pipelines. The database and memory impact remain negligible and with Inline Content we don't burden the caller with resolving references in the returned JSON.

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

Response
{
  "data": [
    {
      ...,
      "model_id": {                                         <= the JSON property 
        "display_name": "Hewlett-Packard ProLiant",         <= contains the payload of the referenced entity 
        "life_cycle_stage": "Operational",
        "life_cycle_stage_status": "In Use",
        "manufacturer": {
          "city": "Palo Alto",
          "name": "Hewlett-Packard",
          "sys_class_name": "core_company",
          "sys_id": "b7e7a507c0a8016900920ee7d71d6df9"
        },
        "name": "ProLiant DL380 Gen11",
        "sys_class_name": "cmdb_hardware_product_model",
        "sys_id": "67c48433873f75503efcec230cbb3595"
      },
      ...
    }
  ],
  "relations": {},
  "referenced": {}
}

Inline Content supports, but does not require a targetConfiguration. See inferred.
Inline Content causes no additional memory load. (Caching high variance reference fields however, will cause a noticeable memory load.)
Inline Content will increase the amount of executed SQL queries exponentially.
Inline Content is only permissible if the requested root configuration has Allow Inline Relations set.
Every resolution of an Inline Content counts toward your licensed entities limit unless, that entity was previously cached.

Literal

Literal simply renders the value of the reference field. This will usually be a sysId, but some referenced entities use other values as 'foreign keys,' e.g. life_cycle_stage and life_cycle_stage_status. Here the content of the reference field already is the content you want to render in JSON.

arc46 attempts to preconfigure all Literal references. If we missed one, please give us a heads-up at Support.

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

Response
{
  "data": [
    {
      ...,
      "life_cycle_stage": "Purchase",                       <= these are reference fields in the db,
      "life_cycle_stage_status": "On Order",                <= these are the actual values in the fields
      ...
    }
  ],
  ...
}

Literal does not require nor support a targetConfiguration.
Literal does not cause any memory load.
Literal has no database impact.
Literal references do not count toward your licensed entities limit.

Display Value

Display Value delegates the rendering of the referenced entity to ServiceNow. See ServiceNow - Display values for details.

As the returned values are potentially localized, this introduces a level of variance that is usually dangerous for technical integrations.

This is probably NOT what you want

While there are legitimate use cases for Display Value (see examples below), the rendered value can be dependent on the locale of the caller. This might lead to unexpected results.

Try it: https://demo.squid46.io/sys_user_group?encodedQuery=base_name=CAB%20Approval

Response
{
  "data": [
    {
      ...,
      "type": [                                             <= reference 'type', has RenderType 'Display Value'
        "itil"                                              <= value returned by ServiceNow's displayValue
      ],
      ...
    }
  ],
  ...
}

Can cause memory load

In order to minimize SQL queries, Squid caches Display Value values. =>

5000 references with RenderType Display Value all to the same company "Dell Inc" costs you approx. 20 bytes in memory load.
5000 references with RenderType Display Value to 5000 different usernames will cause approx. 200 kB in memory load. Returning the Display Value of 250.000 CIs ... isn't a good idea.

Squid will log warnings when the Display Value cache reaches 10.000 and 100.000 entries respectively.

Display Value does not require nor support a targetConfiguration.
Display Value can have a noticeable impact on performance.
Display Value may cause substantial memory load, if a high variance of values is encountered as these values are cached.
Display Value will cause an additional SQL query for every entity rendered. (This only applies to the first retrieval of a Display Value, as they are cached.)
Display Value references do not count toward your licensed entities limit.

Example of a legitimate use case

By default, Squid renders reference fields with the name type that reference sys_user_group_type as Display Value. This allows us to render just the ServiceNow provided displayValue of the reference - on a vanilla installation itil, catalog, survey.

Disable

Disable disables the rendering of a reference and is used in two scenarios:

You want to reuse an existing view in a configuration, but want to exclude a reference, for which there can be numerous reasons.
You are creating a more complex view in which you link tables. In order to link tables, you must include the references in the view, but you don't want to see the sysIds in the returned JSON as you only need the sysIds for the JOIN in the view, e.g. cmdb_ci.sys_id = alm_asset.ci. Both cmdb_ci.sys_id and alm_asset.ci must be included in the view for the JOIN to work, both have the same value, the sysIdof the CI. You will probably NOT want to render alm_asset.ci, therefore set RenderType for alm_asset.ci to Disable.

See Recursive Structures with Render Type Inline for a real world use case.

See Views for details on how views work.

Disable does not require nor support a targetConfiguration.
Disable does not cause any memory load.
Disable has no database impact.
Disable references do not count toward your licensed entities limit.

Quick Decision Guide​

SysId​

Reference​

Inline Content​

Literal​

Display Value​

Example of a legitimate use case​

Disable​