# Reference Data & Dictionaries

Reference Data & Dictionaries provide two complementary ways to surface structured lookup information inside the OtisEd.Nimble portal. Reference items are plain-language terms with definitions and optional links that any portal user can read, and that administrators can manage through a built-in table. Dictionaries — the Analyst Dictionary and the Element Dictionary — are externally hosted, searchable reference sources that the portal embeds as full-page views, giving data consumers a consistent place to look up reporting field definitions without leaving the portal.

## Table of Contents

* [Overview](#overview)
* [Reference Items](#reference-items)
  * [Viewing the Reference List](#viewing-the-reference-list)
  * [Managing Reference Items](#managing-reference-items)
  * [Adding a Reference Item](#adding-a-reference-item)
  * [Editing a Reference Item](#editing-a-reference-item)
  * [Reordering Reference Items](#reordering-reference-items)
  * [Deleting a Reference Item](#deleting-a-reference-item)
* [Analyst Dictionary](#analyst-dictionary)
* [Element Dictionary](#element-dictionary)
* [Dictionaries and Reporting](#dictionaries-and-reporting)
* [Dictionary Settings](#dictionary-settings)
* [Permissions](#permissions)
* [Troubleshooting](#troubleshooting)

***

## Overview

The portal separates reference information into two distinct areas:

**Reference items** are short entries — a title, a plain-language definition, and an optional URL — that live entirely inside the portal database. Administrators create and maintain them through the Reference Administration screen. All authenticated users can view the resulting list. Because the entries are stored in the portal itself, they can be tailored to your organization's specific terminology and updated at any time without outside assistance.

**Dictionaries** (Analyst Dictionary and Element Dictionary) are comprehensive, externally maintained data definition catalogs hosted by the Synergyz dictionary service. The portal embeds them as full-page iframes so users can browse or search the complete catalog from within the portal navigation, but the content is managed and versioned by the dictionary service rather than by portal administrators.

Both areas are accessible through the portal navigation and require no special setup beyond the permissions described in the [Permissions](#permissions) section.

***

## Reference Items

### Viewing the Reference List

The public-facing reference list is available to all users who can sign in to the portal. Navigate to the Reference page through the portal menu. The page displays every reference item in the order set by administrators, showing each item as:

* A linked title — clicking the title opens the associated URL in a new browser tab (if a URL has been provided)
* A definition paragraph below the title
* A horizontal rule separating entries

Items with no URL still display as plain text rather than a link. If no reference items have been created yet, the page displays "No Data Found."

### Managing Reference Items

Administrators access the management screen through the Reference Administration area. The screen shows all reference items in a searchable, sortable table with the following columns:

| Column             | Description                                                           |
| ------------------ | --------------------------------------------------------------------- |
| Sort               | The numeric sort order controlling display sequence                   |
| Title / Definition | The item title (clickable to edit) and its full definition text below |
| URL                | The associated URL, shown as a clickable navigation link              |
| Modified           | Audit columns showing who last changed the item and when              |

The toolbar at the top of the table provides a keyword search field and two action buttons: **Add New Term** and **Sort Items** (Sort Items appears only when two or more items exist).

The table paginates automatically when the list exceeds ten items and supports export.

### Adding a Reference Item

1. Open the Reference Administration screen.
2. Select **Add New Term** in the toolbar.
3. Complete the form that opens:

| Field      | Required | Notes                                                                                      |
| ---------- | -------- | ------------------------------------------------------------------------------------------ |
| Title      | Yes      | 2–120 characters                                                                           |
| Definition | Yes      | 2–1,000 characters; use the large text area for longer definitions                         |
| Sort Order | Yes      | Numeric value controlling display position; lower numbers appear first                     |
| URL        | Yes      | Full URL (2–120 characters); enter a placeholder such as `#` if no external link is needed |

4. Select **Save**. The new item appears in the table immediately and on the public Reference page at the next load.

### Editing a Reference Item

1. In the Reference Administration table, locate the item to change.
2. Select the pencil icon in the Actions column, or click the item's title directly.
3. The same form used for adding opens, pre-filled with the current values.
4. Make changes and select **Save**.

Changes take effect immediately for all users viewing the Reference page.

### Reordering Reference Items

Display order is controlled by the Sort Order field on each item. You can change order in two ways:

**Per-item:** Edit an individual item and change its Sort Order number. Items with lower numbers appear first.

**Bulk reorder using the Sort tool:**

1. Select **Sort Items** in the toolbar (available when two or more items exist).
2. A drag-and-drop sort panel opens listing all current items.
3. Drag items into the desired order.
4. Select **OK**. The portal saves the updated sort numbers for every item whose position changed. Items whose positions did not change are not modified.

### Deleting a Reference Item

1. In the Reference Administration table, locate the item to remove.
2. Select the trash icon in the Actions column. The delete icon is only visible for items that have no dependent child records.
3. A confirmation dialog appears: "Are you sure you want to delete the Reference?" Select **OK** to confirm.
4. The item is removed and the table refreshes.

Deletion is permanent. The item is removed from the public Reference list immediately.

***

## Analyst Dictionary

The Analyst Dictionary is a full-page view of the external dictionary service's analyst-focused reference catalog. It is accessible to users who have been granted access through the portal menu.

The dictionary renders inside the portal at full viewport height so that the navigation, filtering, and browsing tools provided by the dictionary service are all usable without scrolling outside the embedded view. The content — field definitions, business rules, data lineage notes, and related documentation — is maintained by the dictionary service and updated automatically as the external catalog changes.

Because the Analyst Dictionary is embedded from an external URL, its search, filter, and navigation controls are those of the dictionary service rather than the portal. Refer to the dictionary service's own help documentation for guidance on using those controls.

***

## Element Dictionary

The Element Dictionary is a companion view to the Analyst Dictionary. It presents the element-level data definitions from the same external dictionary service, oriented toward understanding the individual data fields used in reports and data collections.

Like the Analyst Dictionary, it renders as a full-page embedded view. Content is maintained externally. The two dictionaries cover overlapping subject matter from different angles:

* **Element Dictionary** — focuses on individual data elements: what each field means, its valid values, and how it is collected.
* **Analyst Dictionary** — focuses on the analyst's perspective: how fields relate to each other, how they are used in reports, and what business questions they answer.

***

## Dictionaries and Reporting

The Analyst and Element dictionaries serve as the authoritative field-level documentation for the portal's reporting features. When users encounter unfamiliar column names or filter labels in a report, the Element Dictionary is the primary resource for understanding what that field contains and how it is defined. The Analyst Dictionary provides the broader context needed to interpret results correctly and to understand how fields are aggregated or categorized.

Using the dictionaries alongside live reports allows analysts to:

* Verify that a report column matches their intended definition before drawing conclusions.
* Identify valid value sets for filter fields, reducing the chance of empty results from mismatched filter values.
* Understand population rules and exclusion criteria that affect counts and percentages.
* Trace how a calculated field is derived from source data.

There is no configuration required to use the dictionaries for report interpretation — they are simply reference resources available through the portal navigation.

***

## Dictionary Settings

Tenant administrators can control whether the dictionary feature is enabled for their tenant and configure the URLs used for the embedded views. These settings are found under:

Administration menu > Settings > Dictionary Settings

| Setting | Description                                                                                                                                                    |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Enable  | Turns the dictionary feature on or off for the current tenant. When disabled, the Analyst Dictionary and Element Dictionary pages are not accessible to users. |
| Element | The URL for the Element Dictionary embedded view. Change this only if directed by your system administrator or support team.                                   |
| Analyst | The URL for the Analyst Dictionary embedded view. Change this only if directed by your system administrator or support team.                                   |

Select **Save** after making any changes. Settings take effect immediately for all users on the tenant.

***

## Permissions

Access to reference data and dictionary features is controlled by the portal's role-based permission system.

**Reference Items — read access:** The public Reference list is accessible to all authenticated users without any specific permission. No special role is required to view published reference items.

**Reference Items — administration:** Managing reference items (creating, editing, deleting, reordering) requires one or more of the following permissions, which are assigned through the portal's role management screens:

| Permission                   | Allows                                    |
| ---------------------------- | ----------------------------------------- |
| Nimble.ReferenceItems        | View the Reference Administration table   |
| Nimble.ReferenceItems.Create | Add new reference items                   |
| Nimble.ReferenceItems.Edit   | Edit existing reference items and reorder |
| Nimble.ReferenceItems.Delete | Delete reference items                    |

**Dictionaries — view access:** Access to the Analyst Dictionary and Element Dictionary pages is controlled by menu and route permissions configured by administrators. Contact your system administrator if you expect to see these pages but cannot find them in the navigation.

**Dictionary Settings — configuration:** Changing dictionary settings requires the `SettingManagement.Dictionary` permission.

***

## Troubleshooting

**The Reference page shows "No Data Found."** No reference items have been created yet, or all existing items have been deleted. A user with Reference Administration access should add items through the Reference Administration screen.

**The Add New Term or edit icons are not visible.**\*\* Your account does not have the Create or Edit permission for Reference Items. Contact your administrator to request the appropriate role assignment.

**The Analyst Dictionary or Element Dictionary page is blank or shows an error.** The dictionary service URL may be unreachable from your network, or the tenant's dictionary feature may be disabled. Check the following:

1. Confirm that the Enable toggle is on in Dictionary Settings (Administration > Settings > Dictionary Settings).
2. Verify that your network allows outbound connections to `dictionary.synergyz.otised.net`.
3. If both of the above are correct, contact your system administrator, as the embedded URL in Dictionary Settings may need to be updated.

**Changes to reference items are not appearing for other users.** The Reference page loads data from the server on each visit. Ask the affected user to refresh their browser. If the item still does not appear, verify that the save completed without an error message.

**The Sort Items button does not appear.** The Sort Items button is only shown when two or more reference items exist. If only one item is in the list, use the item's Sort Order field directly to set its position.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nimble.docs.otised.com/guides/reference-data-dictionaries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.