@servicenow/sdk/docs/api/service-catalog/variables/referencevariable-api.md

ServiceNow SDK

---
tags: [ReferenceVariable, variable, service catalog, reference, lookup]
---
# ReferenceVariable

Creates a reference lookup variable for service catalog forms. Use when users need to select a record from another table (e.g., a user, group, or configuration item) via a searchable lookup field. Add a `ReferenceVariable` to a `CatalogItem` or `VariableSet` via the `variables` property.

## Signature

```typescript fluent
ReferenceVariable(config)
```

## Parameters

### config

`ReferenceVariableType<keyof Tables, string | ExplicitKey<string> | Record<keyof Tables>>`

Configuration for the reference variable including:

**Properties:**

- **question** (required): `string`

- **referenceTable** (required): `RefTable`
  Table that is being referenced by this variable

- **active** (optional): `boolean`

- **alwaysExpand** (optional): `boolean`
  Always expand

- **attributes** (optional): `string`
  Attributes of the variable

- **category** (optional): `string`
  Category

- **conversationalLabel** (optional): `string`

- **createRoles** (optional): `(string | Role)[]`

- **defaultValue** (optional): `string | Type`

- **deliveryPlan** (optional): `string`
  Delivery plan

- **dependentQuestion** (optional): `string`
  Dependent question for dynamic default value

- **description** (optional): `string`
  Description

- **disableInitialSlotFill** (optional): `boolean`

- **dotWalkPath** (optional): `string`
  Dot walk path for dynamic default value

- **dynamicRefQual** (optional): `string | Record<'sys_filter_option_dynamic'>`
  Dynamic reference qualifier (use with useReferenceQualifier='dynamic'). Mutually exclusive with referenceQualCondition and referenceQual.

- **exampleText** (optional): `string`

- **field** (optional): `string`
  Field to map (required when mapToField is true)

- **global** (optional): `boolean`
  Global

- **helpTag** (optional): `string`

- **helpText** (optional): `string`

- **hidden** (optional): `boolean`
  Indicates whether the field is hidden. Cannot be true when mandatory is true.

- **instructions** (optional): `string`

- **layout** (optional): `'normal' | '2across' | '2down'`
  Layout style for the container

- **mandatory** (optional): `boolean`
  Indicates whether the field must contain a value. Cannot be true when hidden or readOnly is true.

- **mapToField** (optional): `boolean`
  Map to field

- **order** (optional): `number`
  Order in which the variable appears

- **postInsertScript** (optional): `string`
  Post insert script

- **pricingDetails** (optional): `PricingDetail[]`
  Pricing details

- **pricingImplications** (optional): `boolean`
  Pricing implications

- **readOnly** (optional): `boolean`
  Indicates whether the field is read-only. Cannot be true when mandatory is true.

- **readRoles** (optional): `(string | Role)[]`

- **readScript** (optional): `string`
  Read script

- **referenceQual** (optional): `string`
  Advanced reference qualifier (use with useReferenceQualifier='advanced'). Mutually exclusive with referenceQualCondition and dynamicRefQual.

- **referenceQualCondition** (optional): `string`
  Filter reference based on a filter condition (use without useReferenceQualifier or with 'simple'). Mutually exclusive with dynamicRefQual and referenceQual.

- **removeFromConversationalInterfaces** (optional): `boolean`
  Remove from Conversational Interfaces

- **showHelp** (optional): `boolean`

- **tooltip** (optional): `string`

- **unique** (optional): `boolean`
  Unique value

- **useDynamicDefault** (optional): `boolean`
  Use dynamic default

- **useReferenceQualifier** (optional): `'advanced' | 'simple' | 'dynamic'`
  Type of reference qualifier. Determines which qualifier field to use.

- **visibility** (optional): `'Always' | 'Bundle' | 'Standalone'`
  Visibility

- **visibleBundle** (optional): `boolean`

- **visibleGuide** (optional): `boolean`
  Indicates whether the variable is visible in guides

- **visibleStandalone** (optional): `boolean`
  Indicates whether the variable is visible when standalone

- **visibleSummary** (optional): `boolean`
  Indicates whether the variable is visible in summaries

- **width** (optional): `100 | 25 | 50 | 75`
  Width of the variable

- **writeRoles** (optional): `(string | Role)[]`


## See

- https://docs.servicenow.com/csh?topicname=variable-types.html&version=latest