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.

Add a user-defined field

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

Tip: Before creating user-defined fields, determine how many user-defined fields you need. Certain field types have limits on the amount of user-defined fields that can be created. For details on the number of UDFs that you can define per workspace, see Allowed number of user-defined fields.

If you require more UDFs than allowed, use labels to increase the number of fields without them counting towards the limited amount.

To add a user-defined field:

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

  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 + Field to add a user-defined field.

  6. Enter the following details: 

    Name Description
    Name

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

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

    UDFs can only be defined in English even if ALM Octane has been localized for a specific language. Labels, however, can be specified in other languages.
    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.

    Available field types: List, string, boolean, integer, user, release, team, long string, memo, date and time, date.
    Description

    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.

    Note: The description text remains the same for all ALM Octane display languages. Currently, there is no way to provide a translation of the description.

  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 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. If you require more UDFs than the Allowed number of user-defined fields, use the same UDF name for multiple entities with the same parent. Provide unique labels for each of the entities. For details and examples, see Increase the number of user-defined fields.

  10. To add a UDF 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.
  11. For all entities, except for runs and tasks, indicate if you want to make the field trendable. When you select a UDF as trendable, the UDF is supported in trend widgets. For details, see Define a UDF as trendable.

  12. For Long string and Memo type user-defined fields, select Include as a searchable field in a global search to make the field's contents searchable by users, in a global search. To include these fields in searches, users must select the Include Searchable Fields option. For details, see Perform a global search.

    Note: The following guidelines apply to adding UDFs as searchable fields:

    • The number of UDFs that can be marked as searchable is limited per shared spaced and workspace. By default, the maximum is 14 per shared space and 0 per workspace. You can configure the values using the SEARCHABLE_UDFS_LIMIT_IN_SHARED_SPACE and SEARCHABLE_UDFS_LIMIT_IN_WORKSPACE Configuration parameters. The sum of these values must not exceed 20 per entity type. However, exceeding 15 may affect performance.

    • After you enable the search for a UDF, the data must first be indexed before it is available in a search. The indexing of long-term fields that have existed for a long time, consumes many server resources and may cause performance issues. Therefore, we recommend marking long-term existing UDFs as searchable at a time when there is minimal usage, for example at the end of a business day or on a weekend.

    • For best results, plan ahead and determine which UDFs need to be searchable. To allow your system to work optimally, enable the Include as a searchable field in a global search option for each of these UDFs in close proximity to one another. If you wait a long time between marking multiple UDFs as searchable, it may overload the indexing engine and cause performance issues, since this operation consumes considerable time and resources.

  13. Click Add. The UDF becomes available in ALM Octane just like other predefined system fields.

Back to top

Field types

The following field types are available for an item:

Type Details
List Fields that contain list values.
String Fields that contain string values.
Boolean

Fields that contain Boolean values.

Values: true / false
Integer

Fields that contain integer values.

Note: All ID fields are strings, not integers.
User Fields that contain user information, such user names and IDs (email addresses).
Release Fields that contain release values.
Team Fields that contain team values.
Long string Fields that contain long string values.
Memo Fields that contain text values.
Date

Fields that contain date information without the time component.
Date and Time

Fields that contain complete date and time information.

The date and time is UTC.

For details, see Field metadata reference.

Back to top

Share 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.

  • If you require more UDFs in a workspace, than the Allowed number of user-defined fields, you can use the same UDF name for multiple entities, provided that they have the same parent. You can then provide unique labels for each of the entities. For details and examples, see Increase the number of user-defined fields.

Back to top

In cases whee you need to increase the

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.
Graphs

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.
Filters/
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.

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.

Some grids list multiple entities in a combined view. To display correctly, the field labels for all the entities have to match.

Backlog grid Includes defects, user stories, and quality stories.
Test grid

Includes manual tests, Gherkin tests, test suites, and automated tests.
Run grid Includes manual test runs and automated test runs for test suites.

Solution:  In Settings, change the label for the field for all relevant entities.

Example

  1. Defects, quality stories, and user stories have an Author field.

  2. You want to change the label from Author to Creator.

  3. In Settings, modify the Author field label to Creator three times, once for each of the three entities separately: Defects, quality stories, and user stories.

  4. The combined Backlog grid in ALM Octane displays the Creator label correctly.

Limitation:  If a field is not available for all entities in the combined grid, ALM Octane does not display the new label.

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 has 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 is automatically 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

Allowed number of user-defined fields

The following table lists the number of allowed user-defined fields for each field type per workspace.

Field type Maximum no. of UDFs allowed per workspace

String / Boolean

A combined total of 100 for the two types.

Note: String fields can contain up to 255 characters.
Number 50
Date and Time / Date

A combined total of 40 for the two types.

For example, if there are 30 fields of the Date and Time type, you can only create up to 10 fields of the Date type.
List Unlimited
User Unlimited
Release Unlimited
Team Unlimited
Long string

5

Note: Long string fields can contain up to 1500 characters.
Memo

30

Note: You can modify this value by setting the MEMO_UDFS_LIMIT configuration parameter MEMO_UDFS_LIMIT.

Increase the number of user-defined fields

If your environment requires more than the number of allowed user-defined fields, you can use the same UDF for several subtypes. For each subtype, provide a meaningful and unique label.

In order for a UDF field to be shared, the subtypes must belong to same parent. The following types can share a user-defined field:

  • Work items, such as epics, features, user stories, quality stories, and defects
  • Tests of all types, such as manual tests, Gherkin tests, automated tests, test suites, BDD scenarios, and Model Based tests.

Suppose you want to create a field for your work items, last_reviewed_on_udf, to indicate the date that the entity was last reviewed. You can add this same field name with different labels to multiple work item entities. It is only counted as one UDF field.

In this use case, you would:

  1. Add the last_reviewed_on_udf UDF field to the Epic node. Specify a meaningful label, such as Epic_reviewed_on.
  2. Add the last_reviewed_on_udf UDF field to the Feature node. Specify a meaningful label, such as Feature_reviewed_on.
  3. Repeat the same for defects, user stories, and quality stories.

In this example, you have five UDF fields with the cost of one field.

When you create or edit an entity, the field label becomes available as a displayable field. For example:

Suppose you want to create a field for your tests, last_run_udf, to indicate the date that the test was last run. You can add the same field name with different labels to multiple test entities. It is only counted as one UDF field.

In this use case, you can:

  1. Add the last_run_udf UDF field to the Manual Test node. Specify a meaningful label, such as manual_last_run.
  2. Add the last_run_udf UDF field to the Automated Test node. Specify a meaningful label, such as automated_last_run.
  3. Repeat the same for other test types, such as Gherkin Test, Test Suite, BDD Scenario, and Model Based Test.

In the test's Details tab, the UDF field label becomes available as a displayable field. For example:

Back to top

See also: