# App Terms

## Table of Contents

* [Overview](#overview)
* [Getting Started](#getting-started)
* [Understanding App Terms](#understanding-app-terms)
  * [Term Fields](#term-fields)
  * [The Current Year Term](#the-current-year-term)
  * [Feature Enablement](#feature-enablement)
* [Managing App Terms](#managing-app-terms)
  * [Viewing All Terms](#viewing-all-terms)
  * [Adding a New Term](#adding-a-new-term)
  * [Editing a Term](#editing-a-term)
  * [Deleting a Term](#deleting-a-term)
* [How Terms Are Used Across the Portal](#how-terms-are-used-across-the-portal)
* [Common Scenarios](#common-scenarios)
* [Troubleshooting](#troubleshooting)

## Overview

App Terms are short, reusable pieces of vocabulary that administrators define once and the portal uses throughout. Think of them primarily as academic year identifiers — each term represents a reporting period and carries a code, a short label, and a description that appear in drop-down menus, filters, and headings wherever a year selection is needed.

Because App Terms also control which portal features can reference a given term, administrators have precise control over where each year appears. One term might be available to Reports and Datasets but not yet enabled for File Requests, letting staff roll out access to a new academic year one area at a time.

## Getting Started

App Terms are managed from the Report Administration area. Only users with the appropriate administration permissions can create, edit, or delete terms.

To reach App Terms administration:

1. Sign in to OtisEd.Nimble.
2. Navigate to **Report Administration** from the main navigation menu.
3. Select the **App Terms** tab.

If the App Terms tab is not visible, contact your system administrator to confirm your account has the required permissions.

## Understanding App Terms

### Term Fields

Each App Term has three identifying fields:

| Field       | Maximum length | Purpose                                                                                                                                                             |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Code        | 8 characters   | A unique short identifier for the term, often a numeric year value such as `20242025`. The portal uses this as the term's internal key when matching filter values. |
| Description | 9 characters   | A brief human-readable label shown in drop-down lists, such as `2024-2025`.                                                                                         |
| Label       | 4 characters   | An even shorter display abbreviation, such as `2425`, used where space is limited.                                                                                  |

All three fields are required. Each code must be unique across the portal — you cannot create two terms with the same code.

### The Current Year Term

Exactly one term can be designated as the **Current Year**. The portal uses this designation to pre-select the active academic year in filters and to drive features that behave differently for current versus historical data. When you mark a term as the current year, the portal automatically removes that designation from whichever term previously held it, so only one term is ever current at a time.

If no term is marked as current, features that depend on the current year designation will not function correctly. Always ensure one term carries the Current Year flag.

### Feature Enablement

Each term has individual toggle switches that control which portal features can reference it. The available features are:

* **File Requests** — whether this term appears in file request workflows
* **Form Requests** — whether this term appears in form request workflows
* **Messages** — whether this term is available when composing or filtering messages
* **Reports** — whether this term appears in report page filters
* **Approvals** — whether this term is available in approval workflows
* **Flags** — whether this term is available in flag workflows
* **Datasets** — whether this term appears in dataset selection

All toggles default to enabled when you create a new term. Disable specific features when a term should not yet appear in certain areas, or when a historical term should be retired from active use in specific workflows without being deleted entirely.

The **Enabled Features** column in the terms list gives a quick summary of which features each term currently serves.

## Managing App Terms

### Viewing All Terms

The App Terms administration screen displays all terms in a sortable table. Columns show the Code, Label, Description, Current Year status, and Enabled Features for each term.

Use the search box at the top to filter by keyword. The search looks across the Code, Label, and Description fields simultaneously. Results update automatically as you type, starting from two characters.

You can click any column header to sort the list by that column.

### Adding a New Term

1. From the App Terms administration screen, click **Add New Term**.
2. In the dialog that opens, fill in the required fields:
   * **Code** — up to 8 characters; must be unique.
   * **Description** — up to 9 characters.
   * **Label** — up to 4 characters.
3. Under **Feature Enablement**, set the **Current Year** toggle if this term should become the active academic year. The portal will automatically clear the flag from the previously current term.
4. Review the feature toggles and disable any features where this term should not appear yet.
5. Click **Save**.

The new term appears in the list immediately and is available to the portal features you enabled.

### Editing a Term

1. Locate the term in the list. Use the search box to narrow results if needed.
2. Click the **Edit** icon (pencil) in the Actions column.
3. Modify any fields as needed.
4. Click **Save**.

Changing the Current Year toggle follows the same single-current-year enforcement as when creating: enabling it here will clear the flag from whichever term currently holds it. If you are simply changing the code or label for the current-year term, the Current Year status is preserved as long as the toggle remains on.

### Deleting a Term

Deleting a term is permanent and cannot be undone. Before deleting, verify that the term is no longer referenced by reports, file requests, form requests, or other portal records. If the term is still in use, deletion may cause data inconsistencies in historical records.

1. Locate the term in the list.
2. Click the **Delete** icon (trash) in the Actions column.
3. A confirmation dialog will ask you to confirm the deletion. It shows the term's code and label so you can verify you have selected the right record.
4. Click **OK** to confirm, or **Cancel** to go back.

The term is removed and will no longer appear in any drop-down menus or filters throughout the portal.

## How Terms Are Used Across the Portal

App Terms provide the academic year vocabulary used throughout OtisEd.Nimble. When a staff member or administrator sees a year selector on a report page, a file request, a dataset, or a message filter, the options in that selector are drawn from the App Terms enabled for that specific feature.

**Reports.** Report page filters that include an academic year selector pull their options from terms enabled for Reports. The portal can also detect whether the year a user has selected matches the current year, which some reports use to determine whether to show live data versus historical data.

**File Requests and Form Requests.** Workflows that ask users to associate a submission with an academic year use terms enabled for File Requests or Form Requests respectively.

**Messages.** Message composition and filtering interfaces use terms enabled for Messages to let users scope communications to a specific year.

**Approvals.** Approval workflows that are scoped to an academic year use terms enabled for Approvals.

**Flags.** Flag workflows that require a year context use terms enabled for Flags.

**Datasets.** Dataset selection interfaces use terms enabled for Datasets to let users choose which year's data they are working with.

Because each feature draws only from terms enabled for it, you can stage the availability of a new academic year across the portal incrementally. For example, you might enable a new term for Datasets and Reports first, then enable it for File Requests once those workflows are ready to accept submissions for the new year.

## Common Scenarios

**Adding a new academic year.** Create a new term with the correct Code, Description, and Label for the new year. Enable only the features where submissions or data should be accepted immediately. Set the Current Year toggle to make it active — this automatically retires the previous current year flag.

**Retiring a year from active workflows.** Edit the term and disable the feature toggles for any workflows that should no longer accept new activity for that year. Leave the term in place so that historical records remain intact.

**Correcting a label or description.** Edit the term and update the Description or Label field. The Code is the portal's internal key and is used to match filter values, so changing a Code for a term that is already in wide use may cause mismatches in existing filters or reports. Change the Code only when you are certain no existing data references it.

**Checking which year is current.** Look for the checkmark in the Current Year column of the App Terms list. There should always be exactly one term with a checkmark. If none is marked, portal features that depend on the current year will not resolve correctly.

## Troubleshooting

**A year I expected to see in a filter does not appear.** Confirm that the term exists and that its feature toggle for the relevant area is enabled. For example, if the year is missing from a report filter, open the term in the App Terms administration screen and verify that the Reports toggle is on.

**I cannot save a new term — the code already exists.** Each code must be unique. Check the existing terms list for a term with the same code. If the existing term is a duplicate or was created in error, delete it before creating the new one.

**I cannot save a new term — the ID already exists.** The term's numeric ID is derived from its code. If a previous term was created with the same numeric code value, the portal will reject the duplicate. This typically happens if a term was created and then deleted but the code was reused too quickly. Use a distinct code value.

**I set a term as the current year but another term still shows as current.** The portal enforces a single current year automatically. If both show as current, try refreshing the page — the save operation may have cleared the previous flag but the display has not yet updated. If the problem persists after refreshing, contact your system administrator.

**A term was deleted but old records reference it.** Deletion removes the term from all future selections but does not retroactively update records that already referenced it. Historical report filters or file requests may show a year code that no longer resolves to an active term. Contact your system administrator to assess the impact and determine whether data remediation is needed.


---

# 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/app-terms.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.