References (Predefined)

It just works

Without any further configuration squid by arc46 will render referenced entities as expected. It just works. You don't have to do anything.

ServiceNow References are foreign key relations to other entities.

The major added value of squid by arc46 as opposed to out-of-the-box ServiceNow TableAPI access is the resolution and inclusion of referenced data. See also Relations. This is where you get what you're paying for.

Instead of

{
  ...,
  "manufacturer": {
    "link": "https://instance.service-now.com/api/now/table/core_company/494c08903b5f4610231c057f16e45ab5",
    "value": "494c08903b5f4610231c057f16e45ab5"
  },
  ...
}

you get

{
  ...,
  "manufacturer": {
    "city": "Bridgewater",
    "country": "USA",
    "name": "BROTHER INDUSTRIES, LTD.",
    "state": "New Jersey",
    "street": "200 Crossing Blvd.",
    "sys_class_name": "core_company",
    "sys_created_by": "rainer@arc46.io",
    "sys_created_on": "2024-07-05T13:28:53Z",
    "sys_id": "494c08903b5f4610231c057f16e45ab5",
    "sys_updated_by": "rainer@arc46.io",
    "sys_updated_on": "2024-07-05T13:35:30Z"
  },
  ...
}

How does it work?

squid by arc46 uses the referenceTable value of a reference field to determine the class of the referenced entity. squid by arc46 then attempts to find a suitable configuration. If such a configuration is found that configuration is used to render the referenced entity. If no suitable configuration could be determined the reference is rendered as Inline SysId.

This also works for GlideLists that are references.

Examples

The configuration cmdb_ci_server defines a property manufacturer. The table(!) cmdb_ci_server defines manufacturer as a reference with a type of core_company.

squid by arc46 will now search for a matching configuration

• core_company or
• core_company_inline if cmdb_ci_server_inline was requested
  (or more exactly, if 'Reference Group Names' contains inline)

As both core_company and core_company_inline are installed as predefined configurations with squid by arc46, any references to a core_company will just work as expected and render correctly.

See the example rendered above.

When would you want to explicitly configure references?

• You want to render a specific reference with some other targetConfiguration e.g. as core_company_minimal.
• You want to render the literal value of a reference. (See life_cycle_stage / life_cycle_stage_status below.)
• You want to cache the referenced entity.
• You do not want to render the referenced entity at all.

How you can do this is described in Custom References.

Predefined Reference Configurations

squid by arc46 ships with some predefined reference configurations that optimize common use cases.

life_cycle_stage / life_cycle_stage_status

References usually contain a sys_id value that is a technical primary key of the referenced table.

A reference may however specify access to the referenced table by way of some other column.

Both life_cycle_stage and life_cycle_stage_status define the foreign key value as name. As name is effectively the value we want to display we can skip the resolution of the reference and render the value of the reference field directly.

This is achieved by defining the RenderType of the reference as Literal.

Reference Default LifeCycle Stage / LifeCycle Stage Status

inline - manufacturer

manufacturer references core_company.

When rendering an inline configuration a referenced manufacturer would be resolved to core_company_inline forcing the retrieval of the referenced company for every referencing entity.

We are assuming there are only a small amount of manufacturers. Caching referenced manufacturers is therefore feasible.

We change the behavior of referenced inline - manufacturer by adding a reference configuration as

Reference Inline Manufacturer

This will not change the rendered result, but it will tell squid by arc46 to cache any manufacturers it encounters when rendering an entity inline.

inline - vendor

vendor references core_company.

When rendering an inline configuration a referenced vendor would be resolved to core_company_inline forcing the retrieval of the referenced company for every referencing entity.

We are assuming there are only a small amount of vendors. Caching referenced vendors is therefore feasible.

We change the behavior of referenced inline - vendor by adding a reference configuration as

Reference Inline Vendor

This will not change the rendered result, but it will tell squid by arc46 to cache any vendors it encounters when rendering an entity inline.

Fun Fact

Apple is both a vendor and a manufacturer. Imagine your company has 10.000 iPhones. You want to export this data including vendor and manufacturer. With the above reference configurations this will cause one(!) additional request to the database instead of 20.000.

inline / recursive - cmdb_ci_ip_pool

cmdb_ci_ip_pool is a recursive data structure and care must be taken to prevent endless recursion when rendering inline.

See Recursive Structures with Render Type Inline for details on how this is achieved.

cmdb_ci_ip_pool_inline_down / cmdb_ci_ip_pool_inline_stop

cmdb_ci_ip_pool_inline_down and cmdb_ci_ip_pool_inline_stop are 'utility' configurations used to break endless recursions.

See Recursive Structures with Render Type Inline for details on how these reference configurations work in the context of recursive structures.

References Inline IP Pool

The long and short of it is that we're preventing the reference to parent_pool from being rendered from an IP Pool that itself is rendered as cmdb_ci_ip_pool_inline_down or cmdb_ci_ip_pool_inline_stop.