Custom Fields allow you to extend TestLink's built-in data model by adding your own metadata fields to test cases, test plans, requirements, builds, and test suites. This is one of TestLink's most powerful yet underused features — it lets you track project-specific information without modifying the core schema.

Path: System > Define Custom Fields · Projects > Assign Custom Fields
URL: gui/templates/cfields/cfieldsView.html · gui/templates/cfields/cfieldsAssignView.html
Prerequisite: cfield_management or cfield_view right

1. What Are Custom Fields?
2. Why Use Custom Fields?
3. Field Types
4. Entity Types (Available For)
5. Enable On / Show On
6. Creating a Custom Field
7. Assigning to Test Projects
8. Display Locations
9. Import / Export
10. Custom Fields as Variables
11. Predefined Special Fields
12. Best Practices

TestLink has built-in fields for test cases (title, summary, preconditions, steps, expected results, priority, etc.). But every project has unique metadata needs. Custom Fields let you add those without changing the database or code.

Built-in Fields (always present):
├── Title
├── Summary
├── Preconditions
├── Steps / Expected Results
├── Priority
└── Type

Custom Fields (you define these):
├── Browser Type        → "Which browser to test on?"
├── Environment         → "Dev / Stage / Prod?"
├── Automation Status   → "Manual / Automated / Partial"
├── Risk Level          → "Low / Medium / High / Critical"
├── Estimated Duration  → "How many minutes?"
└── Anything you need   → unlimited flexibility

Potential: Most teams use 5-10% of TestLink's features. Custom Fields unlock the other 90% by making the tool adapt to YOUR process, not the other way around.

Problem: You're testing a checkout flow. Each test case needs to know which payment method, browser, and device to use. Without custom fields, testers waste time writing "Test on Chrome with Visa card" in the summary — and nobody can filter or report on it.

Custom Fields to create:

Result:

• Filter all test cases that use PayPal → instantly see coverage gap
• Report: "47% of checkout tests are automated, 23% are manual"
• During execution, tester fills test_data_set = "set #7: 3DS2 authenticated Visa" and defect_ticket = "PAY-5678"
• PM sees risk heatmap: all Critical-risk tests are assigned to senior testers

Problem: Your bank must prove to auditors that every payment flow test was executed by a certified tester, on a specific environment, within a regulatory window.

Custom Fields to create:

Result:

• Auditor asks: "Show me all PSD2 tests executed in PROD-HOTFIX environment"
• You filter: regulation = PSD2 + environment = PROD-HOTFIX → instant report
• Each execution shows who tested it, their certification, and the audit reference
• Compliance dashboard: "92% of PSD2 tests approved, 8% pending review"

Problem: Your SaaS app must work on 4 browsers × 3 OS = 12 combinations. You have 200 test cases. Without custom fields, you'd need 200 × 12 = 2,400 test cases. With custom fields, you need 200 + 12 configurations.

Custom Fields to create:

Result:

• During test plan design: assign TC-001 to Chrome+Windows AND Firefox+macOS
• Filter execution by browser: "Show me all failures on Safari"
• Report: "Safari has 3× more failures than Chrome — investigate WebKit bugs"
• Accessibility audit: filter accessibility_level = WCAG-AAA → see coverage for highest standard

If you're unsure where to start, create these 3 fields immediately:

1. automation_status (List: Manual|Automated|Partial|Not Automatable)

   • Know your automation coverage at a glance
   • Report: "We're at 34% automation, need 60% by Q3"

2. risk_level (Radio: Low|Medium|High|Critical)

   • Prioritize testing effort
   • Ensure Critical-risk tests always get executed first

3. environment (List: DEV|SIT|UAT|STAGING|PROD)

   • Track which environments each test covered
   • Catch "tested in DEV but never in UAT" gaps

For types 5 (checkbox), 6 (list), 7 (multiselection), and 9 (radio), you must provide pipe-separated values:

Chrome|Firefox|Safari|Edge

or

Low|Medium|High|Critical

Each custom field is bound to one entity type. You choose this at creation time and cannot change it later if the field has data.

Key insight: Only Test Cases support the full lifecycle (design → testplan assignment → execution). Requirements and requirement specs are design-time only.

When creating a custom field, you choose when it appears:

Show On is a read-only display option (the field is visible but not editable). If "Enable on" is set, "Show on" is automatically set too.

Important: Not all combinations are available for all entity types. For example, Requirements only support Design — you cannot enable custom fields on Execution for requirements.

Path: System > Define Custom Fields > Create

The modern screen (cfieldsView.html) opens creation in a modal dialog — no page navigation, the list refreshes after save.

Editing: click the field name in the table — the same modal opens pre-filled, with Name locked (it is the unique identifier). Saving issues a PUT /api/cfields/{id} request; no full-page reload happens.

Custom field definitions are global. To make a field available in a specific test project, you must assign it.

Path: Projects > Assign Custom Fields
URL: gui/templates/cfields/cfieldsAssignView.html

1. Create the custom field definition
2. Go to Assign Custom Fields to Test Project
3. Select the test project from the dropdown
4. Check the fields you want to assign
5. Set Active, Required, Order, and Location
6. Click Assign (or Save Changes to update order/location/flags)

Clicking a field name in either table (Assigned or Available) opens the same Edit modal used by Define Custom Fields — pre-filled with that field's data (label, type, node type, possible values, enable-on flags).

• The modal lives inside the assignment screen, so you stay in context: no navigation to the legacy page, sidebar and navbar remain visible.
• Save issues PUT /api/cfields/{id} and refreshes both tables (a "Changes saved" toast confirms it).
• Cancel closes the modal; unsaved assignment edits (order/location/flags) are kept.

Before this modernization the name links jumped to the legacy lib/cfields/cfieldsEdit.php screen with target="_top", which replaced the whole shell — the modal removes that jump entirely.

For test case custom fields, you can control where on the page the field appears:

Custom field definitions can be imported and exported as XML.

Path: System > Define Custom Fields > Export

Generates an XML file with all field definitions. The format:

<?xml version='1.0' encoding='ISO-8859-1'?>
<custom_fields>
  <custom_field>
    <name><![CDATA[browser_type]]></name>
    <label><![CDATA[Browser Type]]></label>
    <type><![CDATA[6]]></type>
    <possible_values><![CDATA[Chrome|Firefox|Safari|Edge]]></possible_values>
    <default_value><![CDATA[]]></default_value>
    <valid_regexp><![CDATA[]]></valid_regexp>
    <length_min><![CDATA[0]]></length_min>
    <length_max><![CDATA[0]]></length_max>
    <show_on_design><![CDATA[1]]></show_on_design>
    <enable_on_design><![CDATA[1]]></enable_on_design>
    <show_on_execution><![CDATA[0]]></show_on_execution>
    <enable_on_execution><![CDATA[0]]></enable_on_execution>
    <show_on_testplan_design><![CDATA[0]]></show_on_testplan_design>
    <enable_on_testplan_design><![CDATA[0]]></enable_on_testplan_design>
    <node_type_id><![CDATA[3]]></node_type_id>
  </custom_field>
</custom_fields>

Path: System > Define Custom Fields > Import

Upload an XML file in the same format. Fields with duplicate names are skipped.

Custom fields with location = 8 (hidden) can be referenced in test case content using the [tlVar] syntax:

[tlVar]browser_type[/tlVar]

This renders the field's value inline. Useful for:

• Embedding dynamic metadata in test case descriptions
• Creating template-driven test documentation
• Hiding internal tracking fields from the main UI

TestLink recognizes two special custom field names that trigger automatic behavior:

These are not built-in — you must create them as custom fields with the exact names above. TestLink then uses them for time tracking and reporting.

• Start small: Create 3-5 fields first, expand as needed
• Use meaningful names: browser_type not cf1
• Use list types wisely: 3-7 options per dropdown is ideal
• Document what each field means: Add a description in the label
• Set Required for critical fields: "Environment" might be mandatory
• Use Import/Export: Deploy the same fields across environments

• Don't create 20+ fields: It clutters the UI and confuses users
• Don't change a field's type after creation: You'll lose data
• Don't assign fields to projects you don't use: Keep it clean
• Don't forget to assign: A field definition alone does nothing — it must be assigned to a test project