Core Description Field: Overview, Population, Configuration, and Visibility

The Core Description Field

What it is, how it is populated, where it appears and how it relates to the Quick Description

1. Overview

Every tab in Gimmal Physical has a Quick Description: a short, human-readable label for an item built from one or more of the tab's fields, for example "Barcode - Client - Matter". The Quick Description is defined as a SQL expression on the tab's database view, so every time it is read the database recomputes it by joining and concatenating the underlying fields.

The Core Description is a stored copy of that text. When an item is inserted or updated, the first 850 characters of its Quick Description are written into a real, indexed column named CORE_DESC on the item's own table. Because it is a plain indexed column rather than a computed expression, the Core Description can be searched, sorted and joined cheaply, without the database having to evaluate the Quick Description expression for every row.

Users never type a Core Description. It is maintained entirely by the database and always mirrors the Quick Description, subject to the 850 character limit and a short refresh delay after configuration changes.

1.1 What this document covers

· How the Core Description relates to the Quick Description and to the other description copies the system keeps.

· How and when the value is populated and refreshed.

· Where the field is visible in the application and how to expose it in more places.

· How to configure it (indirectly, through the Quick Description), rules and limits, a technical reference and troubleshooting.

2. Key Concepts

Term	Meaning
Tab (item type)	A record type such as Box, File, Matter or Location. Each tab has its own ITEM_* table and a generated view named ITEM_*_V.
Quick Description	The configured display label for items of a tab. Stored as a SQL expression (SQL_VIEW_EXPRESSION) on the tab's QUICK_DESCRIPTION dictionary field and exposed as a computed column on the tab's view. Configured in web Admin under Quick Description Field Configuration.
Core Description	A physical column, CORE_DESC (nvarchar 850, nullable, indexed), on each tab's item table. Holds the first 850 characters of the item's Quick Description. Caption "Core Description", abbreviated caption "Core Desc".
ITEM_CORE.QUICK_DESCRIPTION	A cross-tab copy of the Quick Description (up to 2,000 characters) kept in the shared ITEM_CORE table for every item of every tab. Used by cross-tab features such as barcode lookups and integrations.
History description	A further copy (up to 1,000 characters) written into item history rows so that history remains readable after an item changes.
Alternate System Description	A different, separately configured description used only when requests are interchanged with external systems. Not related to the Core Description.

3. How the Core Description Is Populated

3.1 On every insert and update

Each tab has generated insert and update stored procedures. After the row has been written, both procedures read the item back through the tab's view, which yields the freshly computed Quick Description, and then fan the text out to the three stored copies. The block is only emitted for tabs whose table actually has the column, so tabs without a Core Description are unaffected.

DECLARE @BARCODE NVARCHAR(50)

DECLARE @QUICK_DESC NVARCHAR(MAX)

SELECT @QUICK_DESC = LEFT([QUICK_DESCRIPTION],2000), @BARCODE = [I_BARCODE_STRING]

FROM ITEM_BOX_V WHERE [I_ID] = @I_ID

UPDATE [ITEM_CORE] SET [QUICK_DESCRIPTION] = @QUICK_DESC, [I_BARCODE_STRING] = @BARCODE

WHERE [I_ID] = @I_ID

UPDATE [ITEM_BOX] SET [CORE_DESC] = LEFT(@QUICK_DESC,850) WHERE [I_ID] = @I_ID

UPDATE [ITEM_HISTORY] SET [IH_ITEM_DESCRIPTION] = LEFT(@QUICK_DESC,1000) WHERE [IH_ITEM_ID] = @I_ID

Shown for the Box tab. The generators substitute the table and view names for every tab. The Core Description line is emitted only when COL_LENGTH(table, 'CORE_DESC') is not null.

Three copies, three lengths. The same text is truncated differently for each destination:

Destination	Max length	Purpose
ITEM_CORE.QUICK_DESCRIPTION	2,000	Cross-tab lookup copy
ITEM_HISTORY.IH_ITEM_DESCRIPTION	1,000	Readable history rows
ITEM_<TAB>.CORE_DESC	850	Indexed per-tab copy (the Core Description)

850 characters is the practical ceiling for an indexed nvarchar key in SQL Server (900 bytes), which is why the Core Description is shorter than the other copies.

3.2 Bulk refresh

Because the value is a copy, it must be regenerated whenever the Quick Description definition changes. Two stored procedures do this in bulk:

· CORE_UPDATE_CORE_FOR_VIEW takes one view name and runs UPDATE <view> SET CORE_DESC = LEFT(QUICK_DESCRIPTION,850) for that tab.

· CORE_DESC_CREATE_UPDATE_CORE_PROC regenerates a procedure named UPDATE_CORE_DESC containing one such statement for every tab that has the column. Running UPDATE_CORE_DESC refreshes the whole database.

The updates are issued through the tab views. This works because CORE_DESC is a pass-through column of the view that maps directly to the base table.

4. When the Value Is Recalculated

Trigger	What happens
Item inserted or updated	The generated procedure rewrites the item's Core Description immediately, as part of the same save.
Quick Description reconfigured	When an administrator saves a new Quick Description for a tab, the tab's view is recreated, the ITEM_CORE copy is refilled in the background, and a second background task calls CORE_UPDATE_CORE_FOR_VIEW for that tab. If that task fails or times out, the values are corrected by the nightly maintenance run.
Nightly index maintenance	The maintenance procedure IX_REBUILD_INDEXES begins by executing UPDATE_CORE_DESC, refreshing the Core Description of every item in every tab before it defragments indexes.
Item types saved in the Configuration tool	The tool's clean-up step regenerates UPDATE_CORE_DESC so that newly added or renamed tabs are included. It does not run the refresh itself; the next nightly run or manual execution does.
Field used by the Quick Description is deleted	The Configuration tool resets that tab's Quick Description to the barcode and warns the administrator. Core Descriptions follow the reset value at the next recalculation until the Quick Description is reconfigured.

5. Where the Core Description Appears

5.1 On the tab's own pages

The Core Description dictionary field is created hidden on the Add and Edit pages and visible on the View page. The page generator additionally restricts it so that, even if visibility flags are changed, it is only rendered on the View and Search pages. It is not shown in the home page grid or quick search by default, although those settings can be changed through the normal field configuration screens.

For every foreign key field that points at another tab (for example the Matter field on Box), the upgrade adds an output column captioned "<Field caption> Core Description" to that field's one-to-many output columns. The column carries the related item's Core Description into the referencing tab's view under an alias ending in _CORE_DESC. It is switched off for the home page grid and quick search by default and can be turned on through the Quick Search and Home Page Grid configuration pages.

5.3 In views, exports and queries

Because it is a real column on the item table, CORE_DESC is available on every tab's ITEM_*_V view and therefore to view exports, reports and custom SQL. It is the recommended column to filter or sort on when a description-based query needs to use an index.

5.4 Where it is not used

· The REST API exposes the Quick Description, not the Core Description.

· The Iron Mountain and O'Neil integrations use the ITEM_CORE Quick Description copy.

· There is no full-text index on the column; the index is an ordinary B-tree index named IX_CORE_DESC.

6. Configuration

There is no configuration screen for the Core Description itself. Its content is controlled entirely by the tab's Quick Description, and its presence on a tab is handled by the database upgrade and the Configuration tool.

6.1 Changing what the Core Description contains

In the web application open Admin and click Quick Description Field Configuration. The security right "Configure Quick Description Field" is required.

Choose the data tab.

Pick up to three fields and type any separator text between them. The page shows the current Quick Description expression for reference.

Save. The tab's view is recreated with the new expression, the ITEM_CORE copies are refilled, and the Core Descriptions for that tab are refreshed in the background.

Only the first 850 characters of the resulting text reach the Core Description, so keep the Quick Description concise if it will be used for searching.

6.2 Making sure a tab has the column

· Existing tabs receive the column, its index and its dictionary entry from the database update script (PBI 114515). The script processes each tab in turn and skips any tab where the step fails, so a tab can occasionally be left without the column; see Troubleshooting.

· New tabs created with the Configuration tool's Add Item Type wizard receive a Core Description field and index automatically.

After a new tab is added, save item types in the Configuration tool (which regenerates UPDATE_CORE_DESC) and either run UPDATE_CORE_DESC or wait for the nightly maintenance run so the new tab's values are populated.

7. Rules and Limits

Rule	Detail
Read-only	The value is always overwritten by the database on save. Any value supplied through the generated procedure parameter is replaced immediately.
850 character limit	Longer Quick Descriptions are truncated. The ITEM_CORE copy keeps up to 2,000 characters.
Mirror of the Quick Description	If the Quick Description contains only the barcode (for example after a reset), the Core Description contains only the barcode too.
Nullable	Items that have not been saved since the column was added, and tabs whose refresh has not yet run, have a NULL Core Description until the nightly run.
View and Search pages only	The page generator will not render the field on Add or Edit pages regardless of the dictionary visibility flags.
Deletable dictionary entry	The dictionary row is marked deletable. Deleting it from a tab removes the field from pages but not the column from the table; the generated procedures keep filling the column as long as it exists.
Per-tab column	Each tab has its own CORE_DESC column and index. There is no single cross-tab Core Description; ITEM_CORE.QUICK_DESCRIPTION plays that role.

8. Technical Reference

8.1 Database objects

Object	Type	Purpose
ITEM_<TAB>.CORE_DESC	Column	nvarchar(850) NULL on every item-type table.
IX_CORE_DESC	Index	Nonclustered index on CORE_DESC, one per item-type table.
DATA_DICTIONARY_FIELDS row	Dictionary	Caption "Core Description", abbreviated "Core Desc", display order 1000, visible on View only, not a core field, not secured.
DD_ONE_TO_MANY_OUTPUT_COLUMNS rows	Dictionary	"<Field> Core Description" output column for each foreign key into another tab, alias <parent>_CORE_DESC, display order 800, off by default.
STR_CREATE_INSERT_SP_FOR_TABLE / STR_CREATE_UPDATE_SP_FOR_TABLE	Generators	Emit the per-item refresh block into every tab's INS and UPD procedures.
CORE_UPDATE_CORE_FOR_VIEW	Stored procedure	Refreshes CORE_DESC for one tab view.
CORE_DESC_CREATE_UPDATE_CORE_PROC	Stored procedure	Regenerates UPDATE_CORE_DESC for all tabs.
UPDATE_CORE_DESC	Stored procedure (generated)	Refreshes CORE_DESC for every tab.
IX_REBUILD_INDEXES	Stored procedure	Nightly maintenance; runs UPDATE_CORE_DESC first.
IX_FILL_ITEM_CORE_BY_ITEMTYPE	Stored procedure	Refills ITEM_CORE.QUICK_DESCRIPTION for a tab after its Quick Description changes.

8.2 Application source

File	Role
Gimmal.Physical.Web\SQL\ Gimmal.Physical.Update.sql	PBI 114515 section: column and index creation, dictionary rows, refresh procedures, IX_REBUILD_INDEXES; Core Description lines inside the INS/UPD generators.
Gimmal.Physical.Components\Item\ItemType\ ItemTypeDataSet.cs	Constants COL_CORE_DESC, PROC_CORE_DESC_CREATE_UPDATE_CORE_PROC, PROC_CORE_UPDATE_CORE_FOR_VIEW.
Gimmal.Physical.Components\Pages\ PageCreator.cs	Restricts the field to the View and Search pages.
Gimmal.Physical.Web\Admin\QuickDescription\ QuickDescription.aspx.cs	Quick Description configuration; recreates the view, refills ITEM_CORE and queues the Core Description refresh.
Gimmal.Physical.Components\Item\ ItemBusinessRules.cs	UpdateCoreDescriptionForView: calls CORE_UPDATE_CORE_FOR_VIEW.
Gimmal.Physical.Configuration\Wizards\ AddItemType\Finish.cs	Adds the Core Description field and index to newly created tabs.
Gimmal.Physical.Configuration\MainForm.cs	Clean-up step that regenerates UPDATE_CORE_DESC.
Gimmal.Physical.Configuration\ ItemTypeDetailForm.cs	Resets the Quick Description to the barcode when a referenced field is deleted.

8.3 Known discrepancies

· The Add Item Type wizard registers the new field with a length of 450, while the update script and every write use 850. The physical column created by the wizard path should be checked before relying on lengths above 450 for wizard-created tabs.

· The wizard captions the field "<Tab> Core Desctiption" (misspelled and prefixed with the tab name), whereas the update script uses "Core Description". Correct the caption in the field configuration after creating a tab.

· The dictionary row inserted by the update script leaves the field length blank even though the column is 850 characters.

9. Troubleshooting

Symptom	Likely cause and check
Core Description is blank for many items	The bulk refresh has not run since the column was added or since the Quick Description changed. Run EXEC UPDATE_CORE_DESC (all tabs) or EXEC CORE_UPDATE_CORE_FOR_VIEW 'ITEM_BOX_V' (one tab), or wait for the nightly maintenance run.
Core Description does not match the Quick Description	The item has not been saved since the Quick Description changed and the background refresh failed. Same remedy as above. Also confirm the text is not simply truncated at 850 characters.
Field is missing on one tab	The upgrade loop skipped the tab after an error. Check COL_LENGTH('dbo.ITEM_<TAB>','CORE_DESC'). Re-run the PBI 114515 section of the update script, or add the column, index and dictionary row manually, then regenerate the INS/UPD procedures by saving the item type.
Field does not appear on the Add or Edit page	By design. The page generator only renders Core Description on the View and Search pages.
Core Description shows only the barcode	The tab's Quick Description was reset to the barcode, usually because a field it referenced was deleted in the Configuration tool. Reconfigure the Quick Description in web Admin.
"<Field> Core Description" column not visible in the grid	The one-to-many output column is created switched off. Enable it in the Home Page Grid or Quick Search configuration for the referencing tab.
Caption reads "Core Desctiption"	The tab was created with the Add Item Type wizard, which contains a caption typo. Rename the field caption in field configuration.