Skip to main content

RenderTypes

RenderTypes are used to define how and where a referenced entity should be 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)
  • the memory usage (some RenderTypes will cause high memory loads)
  • your retrieved entities count. Some RenderTypes count toward your licensed entities limit.

Defining how to render references is straightforward. We have the following options:

  • SysId
  • Reference
  • Inline Content
  • Literal
  • Display Value
  • Disable

Relations have other options that mirror those for references, but differentiate for the placement of the relation in the JSON structure. We have these options:

  • Relation SysId
  • Relation Reference
  • Relation Content
  • Relation Literal
  • Relation Display Value

and

  • Inline SysId
  • Inline Reference
  • Inline Content
  • Inline Literal
  • Inline Display Value
Usage in Configurations
RenderType in 1-to-N Relations​

Image

RenderType in Relations​

Image

RenderType in M-to-N Relations​

Image

RenderTypes for References​

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​

SysId renders a reference property as

{
  "data": [
    {
      ...,
      "model_id": {
        "sys_id": "67c48433873f75503efcec230cbb3595",
        "sys_class_name": "cmdb_model"
      },
      ...
    }
  ],
  ...
}

Nothing other than sys_id and sys_class_name are rendered.

SysId is the fallback, default RenderType if no RenderType is explicitly configured and a targetConfiguration cannot be implicitly determined.

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 has no memory or database impact.

SysId does not require a targetConfiguration.

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.

{
  "data": [
    {
      ...,
      "model_id": {
        "sys_id": "67c48433873f75503efcec230cbb3595",
        "sys_class_name": "cmdb_model"
      },
      ...
    }
  ],
  "relations": {},
  "referenced": {
    "67c48433873f75503efcec230cbb3595": {
      "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 implicitly determined.

Reference is the most efficient way to render referenced data.

Reference has a minimal database impact (one additional SQL query per targetConfiguration. 500 referenced core_company? One additional SQL query).

Reference causes negligible memory load (unless you cache indiscriminately).

Reference requires a targetConfiguration.

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. It is also 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.)

The intended usecase is for single entity data requests where the database and memory impact are both negligible and we don't want to burden the caller with resolving references in the returned JSON.

All predefined configurations with Allow Inline Relations are therefore limited to a maximal amount of 10 returned entities.

{
  "data": [
    {
      ...,
      "model_id": {
        "display_name": "Hewlett-Packard ProLiant DL380 Gen11",
        "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"
      },
      ...
    }
  ],
  ...
}

Inline Content will increase the amount of executed SQL queries exponentially.

Inline Content causes no additional memory load (unless you cache indiscriminately).

Inline Content requires a targetConfiguration.

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 fields 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.

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

{
  "data": [
    {
      ...,
      "life_cycle_stage": "Purchase",
      "life_cycle_stage_status": "On Order",
      ...
    }
  ],
  ...
}

Literal has no database impact.

Literal does not cause any memory load.

Literal does not require a targetConfiguration.

Literal references do not count toward your licensed entities limit.

Display Value​

This is probably NOT what you want

While there are legitimate use cases for Display Value (see examples below), the fact that it is dependent on the locale of the caller might lead to unexpected results.

Display Value renders the display value of the referenced entity as defined by ServiceNow. This might appear similar to Literal but differs in two aspects:

  • Display Value may be dependent on the locale of the caller. Squid may return different values for different callers.
  • Display Value has a noticeable impact on performance.
{
  "data": [
    {
      ...,
      "manufacturer": "Dell Inc",
      ...
    }
  ],
  ...
}

Display Value will cause an additional SQL query for every entity rendered. (This will only happen once for every entity as the display value is cached.)

Display Value values are cached in order to minimize the amount of SQL queries required. This should cause only negligible memory load. If a high variance of values is encountered, this could cause problems.

Can cause memory load

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 is only available for references.

Display Value references do not count toward your licensed entities limit.

Example for a legitimate use case: By default, Squid renders reference fields type referencing sys_user_group_type as Display Value. This allows us to render just the value of the reference - on a vanilla installation itil, catalog, survey.

The (fake) JSON below shows the different renderTypes for the same reference.

{
  "type_display_value": "itil",
  "type_literal" : "72f2c03f475706103c1eb150706d437f",
  "type_reference" : {
    "sys_id": "72f2c03f475706103c1eb150706d437f",
    "sys_class_name": "sys_user_group_type"
  },
  "type_inline_content" : {
    "name": "itil",
    "sys_id": "72f2c03f475706103c1eb150706d437f",
    "sys_class_name": "sys_user_group_type"
  }
}

Disable​

Disable disables the rendering of a reference.

Disable is used in two scenarios:

  • You want to reuse an existing view in a Config, 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 don't want to see the sysIds in the returned JSON as you only need the sysId for the JOIN in the view.

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

Disable is only available for references.

Disabled references do not count toward your licensed entities limit.

RenderTypes for Relations​

While references are defined as part of a configuration / view and already part of a retrieved entity, relations must be explicitly requested (see Relations) and resolved against the database.

When and where relations are rendered determines the amount of database queries required as well as the memory pressure caused.

Relation*​

RenderTypes starting with Relation * will be rendered in the relation section of the returned JSON. This allows for consolidated database queries and is generally more performant.

As we consolidate all relations before they are rendered, relations must be held in memory for a short period of time. Depending on the amount of entities and the renderType this may have a significant memory impact.

{
  ...,
  "data": [
    {
      "cidr": "2a00:17cf::/52",
      "last_discovered": "2024-06-23T22:41:16Z",
      "name": "2a00:17cf::/52",
      "parent_pool": {
        "sys_id": "1879ee65873906146dc863540cbb35d7",
        "sys_class_name": "cmdb_ci_ip_pool"
      },
      "sys_class_name": "cmdb_ci_ip_pool",
      "sys_id": "0279aeed87fdc6903efcec230cbb3544"
    }
  ],
  "relations": {
    "0279aeed87fdc6903efcec230cbb3544": {
      "subnets": [
        ...,
        {
          "sys_id": "388922a5873906146dc863540cbb351a",
          "sys_class_name": "cmdb_ci_ip_pool"
        },
        ...,
        {
          "sys_id": "ac9bbbe9873146146dc863540cbb350a",
          "sys_class_name": "cmdb_ci_ip_pool"
        }
      ]
    }
  },
  "referenced": {
    ...,
    "388922a5873906146dc863540cbb351a": {
      "cidr": "2a00:17cf:0:f00::/56",
      "last_discovered": "2024-06-23T22:41:17Z",
      "name": "2a00:17cf:0:f00::/56",
      "sys_class_name": "cmdb_ci_ip_pool",
      "sys_id": "388922a5873906146dc863540cbb351a"
    },
    ...,
    "ac9bbbe9873146146dc863540cbb350a": {
      "cidr": "2a00:17cf:0:e::/64",
      "last_discovered": "2024-06-23T22:50:42Z",
      "name": "2a00:17cf:0:e::/64",
      "sys_class_name": "cmdb_ci_ip_network_subnet",
      "sys_id": "ac9bbbe9873146146dc863540cbb350a"
    }
  }
}

Inline*​

RenderTypes starting with Inline * will render the relation directly as property of the referencing entity. This forces us to retrieve the referenced entity the moment we are rendering the referencing entity. This will result in a potentially very high amount of database queries, while having no significant memory impact.

{
  ...,
  "data": [
    {
      "cidr": "2a00:17cf::/52",
      "last_discovered": "2024-06-23T22:41:16Z",
      "name": "2a00:17cf::/52",
      "parent_pool": {
        "cidr": "2a00:17cf::/48",
        "last_discovered": "2024-06-23T22:41:15Z",
        "name": "2a00:17cf::/48",
        "sys_class_name": "cmdb_ci_ip_pool",
        "sys_id": "1879ee65873906146dc863540cbb35d7"
      },
      "sys_class_name": "cmdb_ci_ip_pool",
      "sys_id": "0279aeed87fdc6903efcec230cbb3544",
      "subnets": [
        ...,
        {
          "cidr": "2a00:17cf:0:f00::/56",
          "last_discovered": "2024-06-23T22:41:17Z",
          "name": "2a00:17cf:0:f00::/56",
          "sys_class_name": "cmdb_ci_ip_pool",
          "sys_id": "388922a5873906146dc863540cbb351a"
        },
        ...,
        {
          "cidr": "2a00:17cf:0:e::/64",
          "last_discovered": "2024-06-23T22:50:42Z",
          "name": "2a00:17cf:0:e::/64",
          "sys_class_name": "cmdb_ci_ip_network_subnet",
          "sys_id": "ac9bbbe9873146146dc863540cbb350a"
        }
      ]
    }
  ],
  "relations": {},
  "referenced": {}
}

Relation SysId​

Relation SysId is the equivalent to SysId for references.

Relation SysId renders a relation as

{
  ...,
  "relations": {
    "0279aeed87fdc6903efcec230cbb3544": {
      "subnets": [
        ...,
        {
          "sys_id": "0978732987f50a903efcec230cbb3509",
          "sys_class_name": "cmdb_ci_ip_pool"
        },
        ...
      ]
    }
  }
}

Nothing other than sys_id and sys_class_name are rendered.

Relation SysId causes negligible memory load.

Relation SysId has minimal database impact (one additional SQL query per relation requested with the HTTP GET Request)

Relation SysId does not require a targetConfiguration.

Relation SysId relations do not count toward your licensed entities limit.

Relation Reference​

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

{
  ...,
  "data": [
    {
      "cidr": "2a00:17cf::/52",
      "last_discovered": "2024-06-23T22:41:16Z",
      "name": "2a00:17cf::/52",
      "parent_pool": {
        "sys_id": "1879ee65873906146dc863540cbb35d7",
        "sys_class_name": "cmdb_ci_ip_pool"
      },
      "sys_class_name": "cmdb_ci_ip_pool",
      "sys_id": "0279aeed87fdc6903efcec230cbb3544"
    }
  ],
  "relations": {
    "0279aeed87fdc6903efcec230cbb3544": {
      "subnets": [
        ...,
        {
          "sys_id": "388922a5873906146dc863540cbb351a",
          "sys_class_name": "cmdb_ci_ip_pool"
        },
        ...,
        {
          "sys_id": "ac9bbbe9873146146dc863540cbb350a",
          "sys_class_name": "cmdb_ci_ip_pool"
        }
      ]
    }
  },
  "referenced": ...
}
}

Relation Reference has a minimal database impact (one additional SQL query per targetConfiguration. 500 referenced core_company? One additional SQL query).

Relation Reference causes negligible memory load (unless you cache indiscriminately).

Relation Reference requires a targetConfiguration.

Every resolution of a Relation Reference counts toward your licensed entities limit unless that entity was previously cached.

Relation Content​

Potentially extreme memory usage! (All relation content is cached before it can be written to JSON.)

Relation Display Value​

Inline SysId​

Inline Reference​

Inline Content​

Inline Display Value​

Last updated on
We track. Ok?