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.

In this topic:

• Add a user-defined field
• Field types
• Share UDFs between spaces
• Delete a user-defined field
• Change field display labels
• Define a UDF as trendable
• Allowed number of user-defined fields

Add a user-defined field

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

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 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. 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 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. 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. Click Add. The UDF will be 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	Available in ValueEdge and from ValueEdge and ALM Octane 16.1.100: 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.

To change field labels:

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

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

3. 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).

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.

Back to top

See also:

• Design forms
• Design business rules
• Set up lists
• Customize entity display labels (Enterprise Edition)