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 Backreferences

RenderType in Relations

RenderType in M-to-N Relations

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

Display Value renders the display value of the referenced entity as defined by ServiceNow. This might appear similar to Literal but 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 has a negligible memory load.

Display Value is only available for references.

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

Disable

Disable disables the rendering of a reference. Use cases exist where you want to exclude a certain reference, but otherwise render the same content as for an existing configuration / view. Instead of defining a separate view for this purpose, you can configure Disable for the 'unwanted' reference.

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 (by the caller) 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 have to 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.

{
  ...,
  "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 has minimal memory or no additional database impact. (The relation as such must be resolved, but the entity is not retrieved.)

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