User interface object designs

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

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.

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.

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.

Label guidelines

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.

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.

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

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

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

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

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

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

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