Add custom fields

This topic describes how to add user-defined fields to spaces and workspaces.

The topic also discusses how to change system field display labels.

Sharing UDFs between spaces

UDFs can be defined for shared spaces and workspaces. This overview describes how to work with shared and non-shared UDFs.

Isolated spaces

UDFs cannot be defined at the space level when the space is isolated.

Instead, admins for a workspace can define UDFs in individual workspaces.

The UDFs are available in that individual workspace only.

Shared spaces (Enterprise Edition)

This table summarizes the actions admins can perform when defining UDFs in shared spaces and associated workspaces.

Shared space Associated workspaces

The space admin can add and modify UDFs defined in the shared space.

The UDFs are available to all associated workspaces.

  • For UDFs defined by the space admin in the shared space:

    ALM Octane users working in a specific workspace can access both the UDFs defined for the corresponding shared space and also the UDFs defined specifically for that workspace. Shared UDFs are displayed with the icon.

    Admins for workspaces cannot modify shared UDFs.

  • For UDFs defined by an admin for a workspace:

    The admin for a workspace can add and modify these UDFs.

    The UDFs are available to that individual workspace only.

Must UDF names and labels be unique?

  • If a UDF is defined for a shared space, you cannot create a UDF, or define a label, with the same name in the associated workspaces.

  • If a UDF is defined for an individual workspace, you cannot create a UDF, or define a label, with the same name in the associated shared space. You can create a UDF, or define a label, with the same name in other workspaces.

Add a user-defined field

This section describes how to add a user-defined field.

To add a user-defined field:

  1. In Settings > Spaces, select the shared space or the workspace where you want to create user-defined fields.

  2. Click the Entities tab.

  3. In the Entities list on the left side of the pane, select the item (such as user story, manual test, or epic) for which you want to create your own fields.

  4. Click the Fields tab.

  5. Click + to add a user-defined field.

  6. Enter the following: 

    Name Description

    A unique name that APIs will use to access this field. No uppercase letters or punctuation allowed.

    ALM Octane automatically adds the suffix _udf to the name of the field.

    Label A unique name for the field as you want it displayed in the UI. You can enter English, non-English, and special characters.
    Field type

    Select the field type from the drop-down.


    Enter a description for the user-defined field.

    The field's description can be displayed as a tooltip when the user hovers over the field's label. To enable the tooltips, set the SHOW_FIELD_TOOLTIP site and space parameters. For details, see Configuration parameters.

    Is trendable

    You can select this option for the following types of UDF: List, Boolean, Integer, User, Team, Release, and Date and time.

    When you select a UDF as trendable, the UDF is supported in trend widgets. For details, see Define a UDF as trendable.

    Note: This is available for all trendable entities except runs and tasks.

    Limitations: UDFs can only be defined in English even if ALM Octane has been localized for a specific language.

  7. If you are adding a user-defined field of list type: 

    • Select the list to use for the field.

      For details on creating your own lists, see Set up lists.

    • If you want the user-defined field to contain multiple values, check the Allow multiple values check box.

  8. If you are adding a user-defined field of user, release, or team type: 

    • Select the reference field on which to base the new field's value.

    • If you want the user-defined field to contain multiple values, check the Allow multiple values check box.

  9. To add the user-defined field to existing forms, select the forms from the Add to form drop-down list.

    Context Available forms
    Defining a UDF in a workspace associated with an isolated space Only workspace forms are available from the list.
    Defining a UDF in a workspace associated with a shared space

    Only workspace forms are available from the list. If no workspace forms are defined, the list is empty.

    To add a UDF to a shared space form, add the UDF on the space level.

    Defining a UDF in a shared space Only shared space forms are available from the list.
  10. Click Add.

UDFs are available in ALM Octane like other predefined system fields.

Back to top

Set attributes for the user-defined field

You can set attributes for the user-defined field, such as making the field mandatory, by creating rules for entity types. For details, see Design business rules.

If a user-defined field is Required, but the default Smart View form for adding an item does not display the new user-defined field, ALM Octane still prompts you for a value in the Other Required and Invalid Fields section. This section displays only when needed.

Back to top

Delete a user-defined field

If a user-defined field (UDF) is no longer relevant, you can delete it.

In your entity, select the user-defined field in the grid, and in the toolbar, click the Delete button X.

The deleted field is handled accordingly:

Entity Forms Fields are cleared from a form the next time the form is opened.
Rules A warning is displayed. All rules containing the field are invalid and deactivated.

The field is no longer available as an option. Additionally,

  • For current status graphs, a message is displayed that the graph configuration is no longer valid. Modify the existing configuration as needed.

    Delete the widget if you cannot modify the existing configuration.

  • For trend-based graphs, the field remains in graph data.

Group By filters

Fields in filters are cleared with a message. Reset the filters (either in the grid or in the dashboard configuration) as needed.


Sorting order The field is cleared from the sorting with a message.
Grid displays The field is removed from the grid display without a message.
Favorites Fields in a favorite are cleared without a message.

In addition, the name of the field remains in the server audit log.

Back to top

Change field display labels

You can change the display names of both UDFs and system fields.

Tip: ALM Octane also lets you change display labels for entities. For details, see Customize entity display labels (Enterprise Edition).

To change field labels:

  1. In Settings > Spaces, select a shared space or workspace.

  2. Click Entities > Fields, and select a field.

  1. Modify the Label field and click Save.

Back to top

Define a UDF as trendable

You can define a UDF as trendable, enabling filtering and grouping by UDFs in trend widgets. This is available for all entities except runs and tasks.

When working with trendable UDFs, you should be aware of the following:

  • If you define a UDF as trendable, it cannot be reverted to non-trendable. We recommend that you do not define UDFs as trendable if not necessary. Setting a large amount of UDFs as trendable will have an impact on performance.

  • When you define a UDF as trendable, a Trend sync status property on the UDF shows the status of synchronization, which can take a few minutes. The sync job runs in the scope of a space, and it synchronizes all pending newly-trendable UDFs within the space. There is a 10 minute delay when the job is triggered to allow the Space admin to sign a set of UDFs as trendable. The delay is a site parameter called UDF_BECOME_TRENDABLE_SYNC_DELAY, which can be modified by the admin.

  • In the Space admin’s Fields tab, you can see Is Trendable and Trend Sync Status properties. The Is Trendable definition can be set in the field’s dialog (but not in the grid).

  • When a UDF is defined in multiple entity subtypes with the same name, it must be either trendable or non-trendable in all the subtypes. For example, if my_udf is added both to Defect and Feature entities, it must be trendable in both, or non-trendable in both. If it is not trendable in both, and you then set it to trendable in Feature, it will automatically be set to trendable in Defect as well (following a warning message and approval).

Tip: In the trend graph, you can filter by UDFs using the filter component in the Scope page of the graph configuration. You can group by UDFs using a drop-down list in the Display page.

Back to top

See also: