Field model overview
Every work item carries fields — typed data attributes that store values like priority, status, dates, assignees, and custom data. Fields come in two categories:- Core fields — built-in system fields present on every tenant (e.g. Name, Status, Priority, Area)
- Custom fields — tenant-defined fields for organization-specific data (e.g. Environment, Customer Tier)
Data types
Fields use one of 9 data types:| Type | Stores | Example fields |
|---|---|---|
| Text | Free-form text (plain, multiline, or rich text) | Name, Description, EmailGuid |
| Integer | Whole numbers | Points, ClockHours, Sequence |
| Decimal | Numbers with fractional precision | Cost estimate, hourly rate |
| Percent | Percentage values (0–100) | PercentComplete |
| Date | Calendar dates | StartDate, DueDate, CreateDate |
| Time | Duration values (days, hours, minutes) | WorkEstimate |
| Toggle | Boolean on/off | Approved |
| List | Single or multi-selection from predefined values | Status, Priority, Severity, Resolution |
| Picker | Lookup reference to a related entity | Resource, Area, Container, OwnedBy |
Processes control field visibility
Not all fields appear on every item. Each process (item type) defines which fields are visible, their display order, and whether each is required or optional. Useget_item_screen to discover which fields are available for a specific container + process combination.
When to use which tool
| Question | Tool |
|---|---|
| What fields exist and what are their types/constraints? | get_field_list |
| What are the selectable values for a List field? | get_field_list_data |
| What are the selectable entities for a Picker field? | get_field_picker_data |
| Which fields does a specific process use? | get_item_screen |
| Which fields support filtering? | get_filter_fields |
Core field reference
Item fields (22)
| Field | Type | Description |
|---|---|---|
| Name | Text | Item title or summary |
| Description | Text | Detailed description (rich text) |
| Priority | List | Work priority (e.g. Low, Medium, High) |
| Severity | List | Impact level (e.g. Trivial, Minor, Major, Showstopper) |
| Status | List | Current workflow status — each value’s metadata indicates its phase: Open, Working, Closed, or Blocked |
| Resolution | List | Final outcome (e.g. Resolved, Rejected, Duplicate, Ignored) |
| Approved | Toggle | Simple approval flag |
| Points | Integer | Effort estimation points |
| OwnedBy | Picker (User) | Who reported or owns the item |
| Area | Picker (Area) | Sub-grouping within the container |
| Container | Picker (Container) | The container the item belongs to |
| Process | Picker (Process) | The business process the item follows |
| Resource | Picker (Resource) | Person currently working on the item |
| RestrictedTo | Picker (UserGroup) | Which user groups can see item data |
| CostCenter | Picker (CostCenter) | Cost center for the item |
| Crm | Picker (Crm) | Linked customer record |
| Sku | Picker (Sku) | Linked stock unit |
| JobRole | Picker (JobRole) | Job role associated with the item |
| StartDate | Date | When work is due to start |
| DueDate | Date | When work is due to finish |
| PercentComplete | Percent | Completion percentage |
| WorkEstimate | Time | Estimated effort |
Planning fields (2)
| Field | Type | Description |
|---|---|---|
| Board | Picker (Board) | The board the item is planned on |
| Cycle | Picker (Cycle) | The cycle the item is assigned to |
Clock/SLA fields (5)
| Field | Type | Description |
|---|---|---|
| ClockStart | Date | When the SLA clock started |
| ClockFinish | Date | When the SLA clock expires |
| ClockHours | Integer | Expected duration in hours |
| ClockDelta | Integer | Difference in hours between start and finish |
| ClockStatus | List | Clock state (Green, Amber, Red) |
Audit fields (7, read-only)
| Field | Type | Description |
|---|---|---|
| Sequence | Integer | Item sequence number within its container |
| CreateDate | Date | When the item was created |
| CreateBy | Picker (User) | Who created the item |
| ChangeDate | Date | When last modified |
| ChangeBy | Picker (User) | Who last modified |
| EmailGuid | Text | Unique ID for email-created items |
| RecordSource | Text | Origin: user, email, or API |
Feature fields (2)
| Field | Type | Description |
|---|---|---|
| LinkType | List | Relationship type for linked items (Duplicate, Related) |
| TimeType | List | Category of time entry (Internal, Development, QA, R&D, PMO, Sales, Marketing) |
get_field_list
Get the full field catalog with type-specific metadata. Returns rich metadata per field so AI agents can understand constraints, valid value sources, and data types in a single call.| Property | |
|---|---|
| Read-only | Yes |
Parameters
None.Returns
A list ofFieldDto objects. Every field includes:
| Property | Description |
|---|---|
fieldId | Field identifier used in all tool calls |
fieldName | Human-readable name (e.g. “Priority”, “Status”) |
fieldType | Data type: Text, Integer, Decimal, Percent, Date, Time, Toggle, List, or Picker |
description | Admin-facing description of the field |
defaultValue | Default value assigned when none is provided |
isCore | true for system fields, false for custom fields |
valueHint | Guidance on how to get valid values (e.g. which tool to call) |
| Property | Included for | Description |
|---|---|---|
multiSelect | List, Picker | Whether multiple values can be selected |
scope | Picker | Entity scope (e.g. User, Area, Board) |
pickerHint | Picker | Which tool provides valid entity IDs |
contentType | Text | Content format: Text, Multiline, or Wysiwyg |
maxLength | Text | Maximum character length (0 = unlimited) |
minValue | Integer, Decimal, Percent, Date | Minimum allowed value |
maxValue | Integer, Decimal, Percent, Date | Maximum allowed value |
timeFormat | Time | Allowed components (e.g. “hours and minutes”) |
get_field_list_data
Get the selectable values for a List-type field. Works for any list field — Status, Priority, Severity, Resolution, ClockStatus, and custom list fields alike.| Property | |
|---|---|
| Read-only | Yes |
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fieldId | string | Yes | Field ID of a List-type field. Use get_field_list to find list fields. |
Returns
A list ofDataFieldListData for each option:
| Property | Description |
|---|---|
id | The value ID to use when setting the field on an item |
value | Display text (e.g. “High”, “In Progress”) |
image | Optional image reference |
metadata | Extra context — for Status fields, contains the workflow phase: Open, Working, Closed, or Blocked |
active | Whether the value is currently selectable |
get_field_picker_data
Get the selectable entities for a Picker-type field. Resolves the field’s scope internally and returns matching entities as normalized ID/name pairs — no need to know which entity tool to call.| Property | |
|---|---|
| Read-only | Yes |
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fieldId | string | Yes | Field ID of a Picker-type field. Use get_field_list to find picker fields. |
Returns
A list ofPickerValueDto objects:
| Property | Description |
|---|---|
id | Entity ID to use when setting the field on an item |
name | Human-readable entity name |
Scope resolution
The tool resolves picker scopes automatically:| Scope | Returns |
|---|---|
| User | User ID and display name |
| Area | Area ID and “ContainerCode > AreaName” |
| Container | Container ID and name |
| Board | Board ID and name |
| Cycle | Cycle ID and “BoardName > CycleName” |
| Process | Process ID and name |
| JobRole | Job role ID and name |
| CostCenter | Cost center ID and name |
| Sku | SKU ID and name |
| UserGroup | User group ID and name |
| Crm | CRM record ID and name |
| Resource | Combined users and job roles |
| Item | Returns error — use search_items instead |
Picker fields reference
When you encounter a Picker field inget_item_screen or get_field_list, you can resolve its values in two ways:
- Preferred: Call
get_field_picker_datawith the field ID — resolves the scope automatically - Direct: Use the scope-specific tool listed in the
pickerHintproperty
| Scope | Direct tool |
|---|---|
User | get_user_list |
Area | get_containers |
Container | get_containers |
Board | get_board_list |
Cycle | get_board_cycle |
Process | get_container_process_list |
JobRole | get_job_role_list |
CostCenter | get_cost_center_list |
Sku | get_sku_list |
UserGroup | get_user_group_list |
Crm | get_crm_list |
Resource | get_user_list or get_job_role_list |
Item | search_items |
get_filter_fields
Get the fields that can be used infilter_items conditions. Not all fields support filtering — only use fields returned by this tool.
Each field includes its valid operators and guidance on the value format for the rightSide parameter.
| Property | |
|---|---|
| Read-only | Yes |
Parameters
None.Returns
A list ofFilterFieldDto objects:
| Property | Description |
|---|---|
fieldId | Field ID to use in leftSide of filter conditions |
fieldName | Human-readable field name |
fieldType | Data type (Date, Decimal, Integer, List, Percent, Picker, Text, Time, Toggle) |
operators | Valid operators for this field type (e.g. ["Equal", "NotEqual", "LessThan", ...]) |
valueHint | Guidance on the rightSide value format (e.g. “Value ID from get_field_list_data with fieldId ’…’”) |
Value format reference
When setting field values viafieldsJson on create_item or update_item:
| Field Type | Value format |
|---|---|
| Text | Plain string |
| Integer | String-encoded integer, e.g. "5" |
| Decimal | String-encoded decimal, e.g. "12.50" |
| Percent | String-encoded percentage, e.g. "75" |
| Date | ISO date string, e.g. "2026-03-15" |
| Time | Duration string, e.g. "2h 30m" |
| Toggle | "true" or "false" |
| List | The id from get_field_list_data (not the display text) |
| Picker | The id from get_field_picker_data or the scope-specific tool |