This documentation supports the 21.05 version of BMC Helix ITSM. To view an earlier version, select the version from the Product version menu.

User interface object designs

As a developer, you can use the information in this topic for user interface object designs, their standard formats and guidelines.

Form names

When extending BMC Helix ITSM applications, use the standards provided here to define a system code and form code that is unique. This naming convention helps to distinguish which code is a standard, out-of-the-box workflow and which is specific to you. Also, in a multitenant environment, this convention can help distinguish code that belongs to particular tenants.

Form name format

All form names must be unique. The standard format for a form name is as follows:

System Code:Form Name Description

Use the following information to generate form names for all types of form usages (for example, regular, join, dialog, console):

  • System Code — Forms within a system are prefixed with an uppercase letter code. This prefix is used to distinguish the system's forms and must contain uppercase letters. Always use a colon to separate the prefix code from the remainder of the form name. For example, AST: is used to represent the Asset Management application, and CHG: is used to represent the Change Management application.

  • Form Name Description — The remainder of the form name is an informative text string that reflects the purpose of the form. This string must use camelCase notation, which is a mixture of uppercase and lowercase letters with each distinct word beginning with an uppercase letter followed by lowercase characters and no spaces between words. The first part of the name can be used to group forms to define a subsystem or component.
    Example form names

    Form name

    Form type

    AST:AssetCost

    Regular

    AST:Application

    Join

    AST:ApplicationService

    Join

    AST:ManageInventory

    Display-Only

    TCO:Configuration

    Regular

    SHARE:Application_Properties

    Regular

    In this descriptive part of the name, do not include words that describe the form's intent, such as join or dialog.

  • Form web alias—The web alias is based on the form name and follows camelCase notation. Characters such as a colon and spaces are not permitted.
    Example form web aliases

    Form name

    Form web alias

    AST:AssetCost

    ASTAssetCost

    AST:Application

    ASTApplication

  • Form code—Every form in an application must have an associated form code. This form code is composed of three uppercase letters. The form code is used in the creation of active link, filter, escalation, guide, and menu names.
    Example form codes

    Example form name

    Form code

    CHG: Infrastructure Change

    CRQ

    CFG:MenuItems

    MNI

Join forms

For more information about the purpose of join forms, see Join forms.

For join forms, use the same label, database name, and field IDs as the fields on the parent forms of the join, unless there is a reason not to do so. For example, if the same field ID from the primary and secondary forms is included in the join form, the field from the secondary form must be assigned a new field ID. The form code prefix followed by an underscore is added to the database field name. This convention enables easy reuse of code from parent forms and facilitates the administration and maintenance of these forms.

Join form fields

Form name

Type

Database field name

Field ID

CTM:Site Company Association

Primary

Site ID

1000000074

CTM:Site Alias LookUp

Secondary

Site ID

1000000074

CTM:Site Alias Company LookUp

Join

Site ID (from Primary form)

1000000074

CTM:Site Alias Company LookUp

Join

STL_Site ID (from Secondary form)

New field ID generated

Use reference images on BMC Helix ITSM forms to avoid embedding images

The Image Object is a type of a server object that is available in Developer Studio and provides the following functionality:

  • Handles images in applications effectively.
  • Stores images only once in the Action Request System server database.
  • References images by name instead of embedding the binary image content in display properties and displays instances of views and fields, which results in a smaller server cache memory footprint.

Important

When you attach images to the forms and to the objects in the form, attach them as a reference image and not as an embedded image.

To use reference images

  1. Create a new image object in Action Request System by using Developer Studio.
  2. Provide a description for the image object.
  3. Save the image object with a name.
  4. Add the image to an object.
    For example, to add an image to a button, go to the properties of the button and select the image.
    You are prompted to select the image. By default, the image type is set as Image Reference.
  5. Click Select and select the images.

Use field names that are informative and reflect the purpose of the field. A form with fields that are organized and well-named is easier for administrators to maintain and end users to follow.

General database field names

For all general database fields, create names that are distinct and informative. Use camelCase notation for the names, When possible, make database field names the same as label names, but without spaces. Do not use special characters in database field names.

Use database field names that can help indicate that they are extension attributes.

Example

LastName, CompanyName

For the steps to create or manage fields, see Creating and managing fields.

Labels

A label is the name associated with a field that the end user sees when navigating through forms. 

  • If a field has any functionality associated with it, place a plus sign at the end of the label; for example, a user presses Return in a given field and other fields on the form become auto-populated with information. A plus sign at the end of the label reminds the user that hidden functionality exists for certain fields.
  • Do not include spaces at the end of a label.
  • If a field is required, place an asterisk sign at the end of the label.
  • Be consistent when creating names.
Example

Last Name, Company Name

Label guidelines

Appearance of label

Example

Meaning

Bold label with an asterisk (*)

Company*

The field is required to submit and update the form.

Any label, bold or not bold, with a plus sign (+)

Support Group+
Company*+

The field has functionality associated with it. For example, if the user presses Return in this field, a search dialog box or a search based on the value typed into the field could be displayed. If the label has both an asterisk and a plus sign, BMC uses the following order: label name followed by *+.

Label not bold

Middle Name

The field is optional.

Italicized label

Entry ID
Create Date

The field is a system field generated by Action Request System. These fields are usually read-only and are automatically populated by the system.

Display-only and global fields

Display-only fields are non database fields. Begin these fields with z1D, followed by an underscore, either the field name or the function for a specific field or field type, and a two-digit number for generic field usage. This convention groups all hidden display-only (or temporary) fields together for easy maintenance and to facilitate field lookups.

Begin global fields with z1G, followed by an underscore and the field name or function.

Example

z1G_Global_SandBoxEnabled is an example of a global field and it is used to determine whether the Sandbox data set is enabled in the Asset Inventory component. This setting is global and can be referenced in workflow by looking at the data stored in this field.

Display-only field name guidelines

  • A display-only (specific use) field is a temporary field that is created to store the data for one specific variable; for example, if you need to store the Customer Login ID for future reference in a workflow, you could create a temporary field called z1D_Customer_CorporateID.
  • A display-only (general use) field is a temporary field that is created to store data for a defined workflow set. Display-only (general use) fields can be overwritten by other workflow sets. If you need to reference this field for future workflow needs, you do not store data in this field.

An example of a display-only (general use) field is z1D_Char01, which is a temporary field used to store character data that will be referenced in a workflow for a defined workflow set.

Field type

Field name prefix (database and label are the same)

Examples

Display-only (specific use)

z1D_fieldName/function

z1D_Customer_CorporateID

Display-only (general use)
# is replaced by a two-digit number

z1D_Char#
z1D_Integer#
z1D_Real#
z1D_Decimal#
z1D_TableChar#
z1D_TableInt#
z1D_External#
z1D_View#
z1D_Date#
z1D_DateTime#
z1D_Currency#
z1D_Time#

z1D_Char01

z1D_Char02

Global

z1G_fieldName/function

z1G_Global_SandBoxEnabled

Fields on display-only forms and attachment pools are considered non-database fields and must have prefix as z1D. However, if a display-only form such as a console or search dialog box contains general database fields, use the field ID, database name, and label already registered; for example, the Company Name field.

Placeholder fields

Placeholder fields include page holders, page fields, table fields, and attachment fields. Begin the database name of these fields with a lowercase z2, followed by the type of placeholder field being created, an underscore, and then the placeholder field name in camelCase notation. The first part of the name can be used to group forms to define a subsystem or component.

Placeholder field names

Field type

Database field name prefix

Label name

Page Holder field

z2PH_fieldName

field Name

Page field

z2PF_fieldName

field Name

Table (Holder) field

z2TH_fieldName

Leave blank

Table (Column) field

z2TF_fieldName

Label name of field

Attachment field

z2AF_fieldName

field Name

Attachment pool

z2AP_fieldName

Leave blank

Flashboard field

z2FB_fieldName

Leave blank

Application list

z2AL_fieldName

field Name

Control and navigation fields

Control fields include buttons and navigation fields. Begin buttons with a lowercase z3, followed by the type of control field being created, an underscore character, and then the control field name in camelCase notation. The label has no prefix.

Navigation fields (vertical navigation bar and horizontal navigation bar) begin with z2N, followed by the type of navigation field being created, an underscore character, and then the control field name in camelCase notation. The label has no prefix, and field name must have spaces.

Control field names

Field type

Database field name prefix

Label name

Button field

z3Btn_fieldName

field Name

Navigation field

z2NF_fieldName

field Name

Navigation menu

z2NM_fieldName

field Name

Navigation menu item

z2NI_fieldName

field Name

Example

Database name z3Btn_CustomerInformation with a button label as Customer Information

Trim fields

Trim fields include text, lines, and boxes. Begin these fields with a lowercase z5, followed by the type of trim field being created, an underscore character, and then the trim field name in camelCase notation. Where applicable, the label has no prefix, and the field name must have spaces and an ampersand (&) symbol before the hot key accelerator or separator symbols. This naming convention groups all trim-only fields together for manageability and to facilitate field lookups. Text fields are primarily used out of the different trim fields listed in the preceding table. Some consoles contain a box field around the navigation area and above tables.

Trim field names

Field type

Database field name prefix

Label name

Text field

z5Text_fieldName

Not applicable

Line field

z5Line_fieldName

Not applicable

Box field

z5Box_fieldName

Not applicable

Menu item (toolbar)

z5Menu_fieldName

field Name and & for a hot key

Menu separator

z5Separator_fieldName

Separator symbols

Example

z5Text_Header, z5Text_ChangeRequester, z5Box_Details

For information about the purpose of trim fields, see Trim fields.

Field help text

Help text is a requirement for all fields; especially for the fields that have a special meaning or use. These fields are often not visible but they are used in a workflow. Always complete the Help text field in the Help text tab of the individual field properties. Make the Help text informative, and include details on a specific functionality associated with the field. Also, note escalations that might be triggered on a given field.

Field identification numbers

Field identification numbers (field IDs) must be numbered within the designated range for manageability and maintainability. If a field is in multiple forms, it must use the same ID, database name, and label in all locations.

A field ID that you add must not be within the BMC reserved field ranges. For more information, see Reserved fields.

Menu names

The following different types of menus are available for use:

  • Character
  • File
  • Search
  • SQL
  • Data Dictionary

Query, SQL, and data dictionary menus

Query, SQL, and data dictionary menus are named according to the data they retrieve. Use the example provided in the following section as a reference when creating these menu names.

Query, SQL, and data dictionary menu naming convention

The standard format for a query, SQL, and data dictionary menu is as follows: System Code:Form Code:Description

Query, SQL, and data dictionary menu name format

Parameter

Definition

System Code

System code that uses two to six uppercase letters

Form Code

(Optional) Actual form code of the form from which the data is being retrieved. If a form code cannot be supplied (for example, a data dictionary menu that is using a field), use DD0 (zero) for the code. The form code must be consistent within applications and application suites.

Description

Type of lookup performed by the menu. Use camelCase notation.

Example

CHG:CTK:ChgTaskLookup

Character and file menus

Character and file menus are named according to the type of data that they contain. Use the example provided in the following section as a reference when creating these menu names. If a character or file menu is used by several systems, use the SHR:SHR: prefix for the system and form code. In such cases, the form code is not optional.

Character and file menu naming convention

The standard format for a character or file menu is as follows: System Code:Form Code:Description

Character and file menu name format

Parameter

Definition

System Code

System code that uses two to six uppercase letters. If a menu is used by several systems, use SHR.

Form Code

(Optional) Form code of the form where the menu is to be used. If it is used by more than one form, use SHR. The Form code must be consistent within applications and application suites.

Description

Type of information contained in the menu. Use camelCase notation.

Example

CHG:CAT:Category

Select the type of menu and refresh options that you implement carefully, with the following considerations:

  • If possible, do not create SQL menus. Although SQL menus retrieve information more quickly than search menus, they are not as portable between databases and nor as easy to maintain.
  • Minimize or eliminate the use of character and file menus. Every time a character menu is updated, the client cache is refreshed the next time any user of the system loads a form that uses the updated menu. If the character menu is large, this refresh process could cause a performance impact.
  • Use the $MENU$ pattern matching function of Action Request System only with character menus. Using this function with search menus can cause inconsistent behavior.

Views across all forms must have consistent names, labels, web aliases, and view ID values.

View user interface (VUI) IDs must have a range specified per view locale. The default locale is en-US, and this value is left blank in all default views.

Example of view attributes

VUI ID

Name

Label

Locale

Web alias

10003000

Administrator

Administrator

Blank for default

Administrator

300907300

Management

Management

Blank for default

Management

399990900

Administrator_fr

Administrator

fr

Administratorfr

399990903

Management_fr

Management

fr

Managementfr

399991900

Administrator_de

Administrator

de

Administratorde

399991903

Management_de

Management

de

Managementde

View aliases and labels

A view alias is the name that is seen by the end users for forms that are directly exposed, like consoles. Aliases can be assigned to each view. Assign alias values that are, where possible, similar to the form name following the system code. For example, if a console has a form name of AST:AssetManager, the various alias values for singular, plural, short singular, and short plural would be Asset Manager. If a form has multiple views, assign appropriate alias names that reflect the form name, if possible.

View labels can be assigned to each view for the new and search entry points, and are required only on forms that have entry points enabled. If such labels are assigned values and the entry points are enabled, the label content is shown in preference to the form name.

Example of view aliases and labels

Form name

Type

View name

View aliases

View labels

AST:AssetManager

Console

Management

Asset Manager

Asset Manager

CHG:ChangeManagementConsole

Console

Console Default User View

Change Management
Console

Change Management
Console


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*