You are on page 1of 660

BMC Remedy Action Request System 7.6.

04

Form and Application Objects Guide

January 2011

www.bmc.com

Contacting BMC Software


You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.

United States and Canada


Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000

Outside United States and Canada


Telephone (01) 713 918 8800 Fax (01) 713 918 8000

If you have comments or suggestions about this documentation, contact Information Design and Development by email at doc_feedback@bmc.com.

Copyright 19912011 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. IBM, DB2, and Informix are registered trademarks of International Business Machines Corporation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. UNIX is a registered trademark of The Open Group. BusinessObjects, Crystal Reports, and SAP are trademarks or registered trademarks of SAP AG in Germany and in several other countries. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.

Restricted rights legend


U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or email. To expedite your inquiry, please see Before Contacting BMC Software.

Support website
You can obtain technical support from BMC Software 24 hours a day, 7 days a week at http://www.bmc.com/support. From this website, you can:

Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax numbers, and telephone numbers.

Support by telephone or email


In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 or send an email message to customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) Outside the United States and Canada, contact your local support center for assistance.

Before contacting BMC Software


Have the following information available so that Customer Support can begin working on your issue immediately:

Product information Product name Product version (release number) License number and password (trial or permanent)

Operating system and environment information Machine type Operating system type, version, and service pack System hardware configuration Serial numbers Related software (database, application, and communication) including type, version, and service pack or maintenance level

Sequence of events leading to the problem Commands and options that you used Messages received (and the time and date that you received them) Product error messages Messages from the operating system, such as file system full Messages from related software

License key and password information


If you have a question about your license key or password, contact Customer Support through one of the following methods:

E-mail customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local support center for assistance. Submit a new issue at http://www.bmc.com/support.

Contents
Preface 17

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Chapter 1 Defining access control 21 22 22 23 25 26 28 29 29 31 31 32 37 38 38 39 40 40 40 42 46 48 49 49 54 55 58 59 61 65 66 67 68


5

Understanding access control in AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Groups in AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Special groups in AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Groups you createRegular, computed, and dynamic . . . . . . . . . . . . . . . . . . . . . Using a parent group for permissions inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . Roles in AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Users in AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additive access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access to AR System objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form, active link guide, and application permissions . . . . . . . . . . . . . . . . . . . . . . . Field permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Active link permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access to requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling access by using implicit groupsRow-level security . . . . . . . . . . . . Submitter and Assignee access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assignee Group access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamic group access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Request ID field with implicit groups . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Assignee Group and dynamic groupsExamples . . . . . . . . . . . . . . . . Controlling access to requests for hierarchical groups . . . . . . . . . . . . . . . . . . . . . . Putting it all together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and managing groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Managing groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and mapping roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining default permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assigning permissions for individual or multiple AR System objects . . . . . . . . . Checking object visibility for the Public group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Subadministrators in AR System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Rights for subadministrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining subadministrator permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents

Chapter 2

Using version control

71

About version control in AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 About object reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 About the object modification log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Object reservation and object modification for overlays and origin objects . . . . . 74 Using object reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Using the object modification log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Labeling a collection of objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Chapter 3 Defining applications 85

Deployable applications in AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Features of deployable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Shared workflow in deployable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Contents of deployable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Access control for deployable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Building deployable applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Creating a deployable application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Including objects in an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Dividing an application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Working with deployable application states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Working with deployable application access points . . . . . . . . . . . . . . . . . . . . . . . . 99 Application attributes and properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Alternatives for presenting applications to users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Specifying General and Forms attributes for Application mode . . . . . . . . . . . . . 104 Specifying Help properties for Application mode . . . . . . . . . . . . . . . . . . . . . . . . . 106 Distributing the application to users as a shortcut . . . . . . . . . . . . . . . . . . . . . . . . . 108 Exporting and importing deployable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Creating a deployable application definition file . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Exporting and importing shared workflow and integrated applications . . . . . . 109 Exporting and importing deployable applications with localized views . . . . . . 113 Exporting and importing data with deployable applications . . . . . . . . . . . . . . . . 115 Deleting applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Local applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Chapter 4 Customizing objects 119

About preserving customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Features for preserving customizations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 About overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Overlay process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 About custom objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Preserving customizations during upgrade of the AR System server and other AR System components to version 7.6.04 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Overlayable and non-overlayable objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Overlay object names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Guidelines for overlaying forms, views, and fields . . . . . . . . . . . . . . . . . . . . . . . . 126 Working with overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Working with custom objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Properties shared between overlays and origin objects . . . . . . . . . . . . . . . . . . . . . 135
6 Form and Application Objects Guide

Locating overlays and custom objects in BMC Remedy Developer Studio . . . . Converting custom objects to origin objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for auditing and archiving overlays and custom objects. . . . . . Export and import operations on overlays and custom objects . . . . . . . . . . . . . . Working only with origin objects at design time . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring AR System to support only origin objects. . . . . . . . . . . . . . . . . . . . . Chapter 5 Creating AR System forms

137 141 142 144 145 145 147 148 148 148 149 150 150 151 151 153 153 154 154 155 157 157 157 158 162 162 168 170 170 170 173 174 176 178 179 181 183 184 184 185 186 189 191 191 192 195
7

Types of forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Regular forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display-only forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . View and Vendor forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inline Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and managing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copying forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renaming forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Previewing form updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display-only forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating display-only forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a display-only form as a control panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using a display-only form as a dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding join forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using join forms in workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Request ID field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating entries in join forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating join forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying join form properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting form properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining next ID block size, cache, and status history. . . . . . . . . . . . . . . . . . . . . . Defining search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting up sort order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 6 Creating and managing fields

Determining what types of fields to use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating data fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a file system browser to character fields . . . . . . . . . . . . . . . . . . . . . . . . . . Adding rich-text-formatting capabilities to a character field . . . . . . . . . . . . . . . . Adding field effects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using character fields to generate GUIDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating currency fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a currency field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating currency exchange ratios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents

Creating selection fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Creating attachment pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Attachment field size considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Creating view fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Creating data visualization fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Creating application list fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Executing entry points in HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Creating navigation fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Setting navigation field color options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Applying flyout mode to navigation fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Creating button fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Adding images to buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Creating trim fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Creating global fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 Regular global fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Window-scoped global fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Managing fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Modifying fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Copying fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Deleting fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Making data fields nonoperational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Finding fields in a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Setting tab order for fields on a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Z-order options for form objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Selecting z-order from the Layout menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Positioning an object in a stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 Working with fields in join forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Chapter 7 Working with tables 233

About table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 List view tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Structure of list view table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Editing row data in list views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Tree view tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 Structure of tree view table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 Editing data in tree views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Arranging nodes in tree views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 Selecting requests in list views and tree views . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Cell-based tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 Templates for cell-based tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Editing data in cell fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Alert lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 Structure of alert list table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Editing row data in alert lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Results lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Editing row data in results lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Creating table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Adding a table field to a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Customizing table labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
8 Form and Application Objects Guide

Setting column properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting sort order and visible levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Grouping rows in tables and adding a row count . . . . . . . . . . . . . . . . . . . . . . . . . Setting table colors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining a context menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the remaining table properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow considerations for table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow in tree view tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow in cell-based tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying images in tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Column display types and images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mid-tier performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Runtime images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow considerations for images in tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding images to tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding buttons and URLs to tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a select/cancel all check-box column to tables . . . . . . . . . . . . . . . . . . . . . . . . Using drop-down menus in list view tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating dynamic tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dynamically defining table field search criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . Updating tables on-screen only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Set Fields with temporary tree nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example: temporarily displaying table rows on-screen . . . . . . . . . . . . . . . . . . . . Enabling users to customize columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refreshing table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting refresh intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Locale-specific refresh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 8 Creating menus

257 259 261 263 267 268 268 268 269 269 271 271 271 272 272 272 272 273 275 278 281 282 284 284 288 291 295 297 297 297 299 300 301 303 304 305 306 310 312 315 316 316 319 319 320 320 323 323
9

About character field menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating character menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating file menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating dynamic file menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Menu file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating search menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating dynamic search menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating SQL menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample SQL menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Database security issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating data dictionary menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Refreshing menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding (clear) to drop-down lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing (clear) from drop-down lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Automatically completing menu entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for search menus with large data sets. . . . . . . . . . . . . . . . . . . . . . Workflow considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents

Recording menu change history. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 Creating help text for menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Modifying menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Copying menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Deleting menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Chapter 9 Working with panels 327

About panel fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 About panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 About panel holders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Panel layout styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 Panel holder display types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 About floating panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Characteristics of floating panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Creating panel holders and panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Creating panel holders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Creating panels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Creating floating panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 How users can move a dialog floating panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Adding a panel to a panel holder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Modifying panel holders and panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 Background Mode in panel holders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 Setting color options for panels and panel headers . . . . . . . . . . . . . . . . . . . . . . . . 345 Adding an image to a panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Applying border colors and thickness to a panel . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Applying rounded corners to a panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 Shared fields in panel holders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Avoiding scroll bars in panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 Distributing slack to avoid scroll bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 Using Fit to Content to dynamically resize panels . . . . . . . . . . . . . . . . . . . . . . . . . 355 Avoiding scroll bars in view fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Including space for panel elements to avoid scroll bars . . . . . . . . . . . . . . . . . . . . 357 Workflow considerations for panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 Using workflow to expand and collapse panels . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 Chapter 10 Working with images 359

About images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 Using backslashes in image object names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Creating image objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Working with image objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 Adding background images to fields and form views . . . . . . . . . . . . . . . . . . . . . . . . . 363 Using transparent images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 Chapter 11 Types of fields 367

Data fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Character fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Diary fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Date and time fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
10 Form and Application Objects Guide

Currency fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Real fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Decimal fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selection fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Table fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attachment pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow considerations for attachment pools . . . . . . . . . . . . . . . . . . . . . . . . . . . View fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using view fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow considerations for view fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data visualization fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application list fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Displaying a subset of a servers applications and entry points . . . . . . . . . . . . . Navigation fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Workflow considerations for navigation fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . Button fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Panel fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trim fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 12 Using templates

371 375 375 376 376 377 377 380 380 381 381 382 382 383 383 383 384 384 385 387 388 389 389 390 391 391 392 393 394 394 399 400 400 403 403 404 404 405 405 411 412 413 414 415 416 419
11

Resources for templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Template content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters in templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using templates with fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Binding a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Evaluating a template with the TEMPLATE function . . . . . . . . . . . . . . . . . . . . . . Using auto-complete functionality with the TEMPLATE function . . . . . . . . . . . Chapter 13 Creating and managing form views

About form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How a form view is selected for the user. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How a form view is selected in BMC Remedy Developer Studio . . . . . . . . . . . . Creating and managing form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing which view is displayed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modifying form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Renaming form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resizing form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting form view properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Including and excluding fields from form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Arranging fields in a form view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting multiple fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sizing fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Aligning fields using the grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Positioning fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Aligning fields using commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents

Anchoring fields to the right side of a form or panel . . . . . . . . . . . . . . . . . . . . . . . 420 Tips for aligning and resizing fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Spacing fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 Stacking fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Rendering forms in right-to-left format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Setting the tab order of fields in a form view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 Applying skins to form views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 Properties to which skins can be applied . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 Types of skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 How skin priorities are applied . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 How field display property priorities are applied . . . . . . . . . . . . . . . . . . . . . . . . . 429 Skins and permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 Skins and localized views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 Defining skins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 Activating skins through the mid tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 Chapter 14 Defining entry points and home pages 433

Overview of home pages and entry points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 Using a home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 Using entry points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Types of entry points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Creating form entry points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 Creating entry point guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 Using the AR System Customizable Home Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 Defining forms, descriptors, and layouts for the home page . . . . . . . . . . . . . . . . 444 Using the Home Page form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Creating a home page form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 Using style sheets with application list and navigation fields. . . . . . . . . . . . . . . . . . . 452 Viewing a subset of entry points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 Home page navigation aids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 BMC Remedy Useradding a home page form action field to a form . . . . . . . . 456 Creating run process workflow that returns to the home page . . . . . . . . . . . . . . 457 Configuring home page preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 Specifying a home page on the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 Specifying a server for the mid tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 Understanding how a home page appears in a browser . . . . . . . . . . . . . . . . . . . . 459 Understanding how a home page appears in BMC Remedy User. . . . . . . . . . . . 461 Specifying a server and home page in the AR System User Preference form. . . 462 Suppressing automatic opening of home pages in BMC Remedy User . . . . . . . 463 Chapter 15 Defining packing lists 465

Using packing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 Creating packing lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 Saving packing lists as XML import/export command files . . . . . . . . . . . . . . . . . . . . 469 Appendix A Core fields 471

Core fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 Core field characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474


12 Form and Application Objects Guide

Appendix B

Reserved fields

477 478 479 480 483 484 486 489

Reserved field ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reserved IDs used as placeholders in definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reserved fields in access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Localization reserved field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DSO reserved fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form action reserved fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix C Special forms

AR System installed forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 Appendix D Appendix E Field properties Archiving data 501 533 534 534 536 537 537 539 539 540 540 541 541 543 544 544 545 548 549 549 551 552 552 553 553 553 554 555 555 555 556

Understanding data archiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring data archiving for a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting an archive form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR_ARCHIVER user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How changes to the main form affect the archive form . . . . . . . . . . . . . . . . . . . . . . . . Characteristics of archive forms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . All archive forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Archive forms created by the AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distributed Server Option (DSO) and archive forms. . . . . . . . . . . . . . . . . . . . . . . Configuring data archiving for a server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server events and logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix F Auditing

Understanding auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Audit styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form-style audits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log-style audits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring auditing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring a form for auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying fields to be audited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Table fields in audit forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing field properties on the main form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations for forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . View and vendor forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Join forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing field properties on the main form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distributed Server Option and audit forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Assignee Group and other dynamic group fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using flag fields to view changes to an individual field . . . . . . . . . . . . . . . . . . . . . . . Audit processing and filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

13

Appendix G

Importing and exporting object definitions and locking objects

557

AR System definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 The AR System definition (*.def) file type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 The AR System XML (*.xml) file type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 Exporting and importing definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Exporting object definitions, views, and applications . . . . . . . . . . . . . . . . . . . . . . 560 Importing object definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 Locking objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 Modifying locked objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 Levels of object locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572 Locking objects when exporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 Importing locked objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 Appendix H Localizing AR System applications 577

Data versus display languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 Localizing AR System forms and applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 Structure of the localized environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 Localizing form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Tasks for localizing AR System forms and applications . . . . . . . . . . . . . . . . . . . . 581 Step 1: Installing languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Installing the AR System server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Installing BMC Remedy User and BMC Remedy Alert . . . . . . . . . . . . . . . . . . . . . 583 Step 2: Creating a localized view of a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 Locale field language entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 Field label for localized view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 Step 3: Localizing the user interface of a form view . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 Localizing the user interface through exporting and importing. . . . . . . . . . . . . . 584 Localizing the user interface manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 Step 4: Localizing menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Localizing character menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Localizing file menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Localizing search menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Step 5: Localizing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Step 6: Localizing message components of a form view. . . . . . . . . . . . . . . . . . . . . . . . 588 Step 7: Localizing currency codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 Step 8: Localizing the mid tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 Creating localized login and logout pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 Step 9: Setting the Localize Server option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Step 10: Adjusting view size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Step 11: Setting user preferences settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 Setting the display locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 Setting the Date/Time style and time zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 Defining ARDATE, ARDATEONLY, and ARTIMEONLY . . . . . . . . . . . . . . . . . . . . . 597 Customizing Date/Time formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598 Errors in formatting ARDATE, ARDATEONLY, and ARTIMEONLY . . . . . . . . 599 How AR System selects a view for the user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600

14

Form and Application Objects Guide

Appendix I

Using the localization toolkit to localize your applications

601 602 602 602 603 605 606 607 609 612 613 617 618 619 619 620 621 622 626 626 627 629

Localizing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Before you begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Localization toolkit process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing your application to be localized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installing the localization toolkit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a root folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a localization package definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Extracting the strings for localization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting the extracted strings to an XLIFF file . . . . . . . . . . . . . . . . . . . . . . . . . . . Translating the XLIFF file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Importing the translated strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating or updating the content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reviewing the translations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adjusting view layouts that have been localized . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the default settings for localization rules in Analyzer. . . . . . . . . . . . . Exporting the contents of the root folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the CLI to localize your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Localizing the AR System server forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Localizing system forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Packaging the output for a specific language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix J Struct Admin group permissions matrix

Struct Admin group permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 Index 635

Contents

15

16

Form and Application Objects Guide

Preface
This manual contains reference information and procedures for creating, modifying, and maintaining BMC Remedy Action Request System (AR System) components, including applications, forms, form views, fields, menus, images, and packing list. See the Workflow Objects Guide for information and procedures about workflow.

IMPORTANT
The compatibility information listed in the product documentation is subject to change. See the compatibility matrix at http://www.bmc.com/support for the latest, most complete information about what is officially supported. Carefully read the system requirements for your particular operating system, especially the necessary patch requirements.

Audience
This guide is written for developers and administrators who create, customize, and maintains applications based on AR System.

NOTE
You should be familiar with BMC Remedy User and BMC Remedy Alert before you begin. See the Introduction to Application Development with BMC Remedy Developer Studio guide for basic information about AR System application development and the development environment.

AR System documents
The following table lists documentation available for AR System 7.6.04. Unless otherwise noted, online documentation in Adobe Acrobat (PDF) format is available on AR System product installation DVDs, on the Customer Support website (http://www.bmc.com/support), or both.

Preface

17

BMC Remedy Action Request System 7.6.04

You can access product help through each products Help menu or by clicking Help links.

NOTE
The AR System product help has not been updated for version 7.6.04. The help topics still apply to version 7.6.03. For the most recent content, refer to the PDF documentation.
Title Concepts Guide1 Description Audience

Overview of AR System architecture and features; includes Everyone information about add-on products that extend AR System functionality and a comprehensive glossary for the entire AR System documentation set. Instructions for installing AR System. Information about the development of AR System applications, including an introduction to using BMC Remedy Developer Studio. Information about AR System applications and their user interface components, including forms, fields, views, menus, and images. Administrators Developers2

Installation Guide Introduction to Application Development with BMC Remedy Developer Studio Form and Application Objects Guide Workflow Objects Guide

Developers

Information about the AR System workflow objects (active Developers links, filters, and escalations) and how to use them to create processes that enforce business rules. Information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data. Information about configuring the mid tier, setting up applications for the mid tier, and using applications in browsers. Administrators

Configuration Guide

BMC Remedy Mid Tier Guide Integration Guide

Administrators

Instructions for integrating AR System with external Administrators/ systems by using web services, plug-ins, and other products, Developers/ including LDAP, OLE, and ARDBC. Programmers3 Information about monitoring and maintaining AR System Administrators/ and AR System applications to optimize performance and Developers/ solve problems. Programmers Database administration topics and rules related to how AR System interacts with specific databases; includes an overview of the data dictionary tables. Information about implementing a distributed AR System server environment with BMC Remedy Distributed Server Option (DSO). Administrators/ Developers/ Programmers Administrators

Optimizing and Troubleshooting Guide Database Reference

BMC Remedy Distributed Server Option Guide BMC Remedy Flashboards Guide C API Reference C API Quick Reference

Instructions for creating, modifying, and administering Administrators/ flashboards to display and monitor AR System information. Developers Information about AR System data structures, C API function calls, and OLE support. Quick reference to C API function calls. Programmers Programmers

18

Form and Application Objects Guide

AR System documents

Title Java API

Description

Audience

Programmers Information about Oracle Java classes, methods, and variables that integrate with AR System. For the location of the JAR file containing this online documentation, see the information about the Java API in the Integration Guide. Information about Java classes, methods, and variables used Programmers to write plug-ins for AR System. For the location of the JAR file containing this online documentation, see the information about plug-ins in the Integration Guide. Instructions for configuring and using BMC Remedy Email Administrators Engine. Descriptions of AR System error messages. Administrators/ Developers/ Programmers Everyone Administrators

Java Plug-in API

BMC Remedy Email Engine Guide Error Messages Guide

Master Index BMC Remedy Approval Server Guide Release Notes Release Notes with Known Issues BMC Remedy User Help BMC Remedy Developer Studio Help BMC Remedy Data Import Help BMC Remedy Alert Help BMC Remedy Mid Tier Configuration Tool Help BMC Remedy Browser Help BMC Remedy Migrator 7.6.04 BMC Remedy Migrator Guide BMC Remedy Migrator online help BMC Remedy Encryption Security 7.6.04 BMC Remedy Encryption Security Guide
1

Combined index of all books. Instructions for using BMC Remedy Approval Server to automate approval and signature processes in your organization. Information about new features, compatibility, and international issues.

Everyone

Information about new features, compatibility, international Everyone issues, installation planning, and open issues. Instructions for using BMC Remedy User. Instructions for using BMC Remedy Developer Studio to develop AR System forms, workflow objects, and applications. Instructions for using BMC Remedy Data Import. Instructions for using BMC Remedy Alert. Instructions for configuring BMC Remedy Mid Tier. Instructions for using AR System forms in browsers. Outlines procedures for installing BMC Remedy Migrator, setting options, and performing migration tasks. Procedures for setting BMC Remedy Migrator options and performing migration tasks. Everyone Developers

Administrators Everyone Administrators Everyone Administrators / Developers Administrators / Developers

Provides an overview of the BMC Remedy Encryption Administrators Security products and explains how to install and configure them.

The full title of each guide includes BMC Remedy Action Request System 7.6.04 (for example, BMC Remedy Action Request System 7.6.04 Concepts Guide), except

Preface

19

BMC Remedy Action Request System 7.6.04

the BMC Remedy Migrator Guide and BMC Remedy Encryption Security Guide. Application developers who use BMC Remedy Developer Studio. 3 C and Java programmers who write plug-ins and clients for AR System.
2

20

Form and Application Objects Guide

Chapter

Defining access control

This section describes how to define access control within AR System and how users can have different permissions to access an AR System application, parts of an application, or objects. It also covers limited administrative access to server objects for subadministrators. The following topics are provided: Understanding access control in AR System (page 22) Groups in AR System (page 22) Roles in AR System (page 28) Users in AR System (page 29) Additive access control (page 29) Access to AR System objects (page 31) Access to requests (page 38) Putting it all together (page 48) Creating and managing groups (page 49) Creating and mapping roles (page 55) Assigning permissions (page 58) Subadministrators in AR System (page 66)

Chapter 1

Defining access control

21

BMC Remedy Action Request System 7.6.04

Understanding access control in AR System


Access control is the AR System mechanism that controls which users can open an application, form, or guide in BMC Remedy User or a browser, can perform an action, and can create, view, modify, and delete a request. In defining access control, you must:
1 Identify and create the groups and roles (for deployable applications) that reflect

key functions in your company and the type of information each function must access.
2 Create users on your AR System server and assign their respective groups to them.

Group membership ultimately determines which objects a user can access and which operations individual a user can perform. AR System has various levels of security: ServerControls access to an AR System server. A user must be defined on a server or connect to it as a guest user if the server permits them. Application, form, and workflowControls access to AR System objects. A user must belong to a group that has permission to access an application, form, active link, or active link guide to see it and use it. Request (or row)Controls access to individual requests in a form. A user can have permission to view or change only requests the user created or those created by a member of a group to which they belong. Field (or column)Controls whether a user can view or can change a field in a form. A user can have permission to view or change a request but cannot see or change individual fields unless the user also belongs to a group with the required fieldlevel permission.

Groups in AR System
Access control groups are collections of AR System users. A user gains access to an object, a field, or a request if a group the user is in has access, or a role mapped to such a group has access. Notifications also can use groups. For example, you can designate an entire group to be notified in a filter action. AR System includes a Public group and eight other special groups that are essential for access control within the system. You can define additional groups based on a common profile and assign access accordingly. For example, you might create a Sales group and allow members to view the status of a request but not to change it. A group can also be a general category, such as Browsers. For information about adding groups, see Creating and managing groups on page 49.
22 Form and Application Objects Guide

Groups in AR System

AR System provides two types of groups: Explicit groupsGroups to which you must manually assign users in the User form. When a user becomes a member of a group, the user is given access to all objects and fields to which the group is granted access. Explicit groups that you create are defined for a particular server. If you move the objects to a new server with its own defined explicit groups, you might need to resolve permission conflicts. Consider using a deployable application, which uses role permissions that can be mapped to different groups on different servers. For more information, see Roles in AR System on page 28. For information about assigning users to groups, see the Configuration Guide, Adding and modifying user information, page 57. Implicit groupsGroups that depend on specific user circumstances and situations. Users belong to these groups based on specific conditions, such as the contents of special fields within each request. You do not directly assign users to implicit groups. Any dynamic groups that you create are also implicit groups. For more information, see Dynamic group access on page 40.

Special groups in AR System


AR System reserves the following group IDs for special group definitions. The following table describes the access privileges for each of these groups.
Table 1-1: Special groups in AR System (Sheet 1 of 3) Group Public ID 0 Type Description

Implicit Provides general access. Access granted to this group is granted to all users. Every user who logs in to AR System is automatically a member of the Public group. This includes registered users (that is, listed in the User form) and guest users. For information about allowing guest users, see the Configuration Guide, Allowing guest users, page 64.

Administrator

Explicit Defines users who have full and unlimited access to AR System. Administratorsmembers of this groupcan view any object or field in BMC Remedy User or a browser and can create a request in any form. Administrators can view, create, modify, and delete any server object in BMC Remedy Developer Studio. A user must have a fixed license or this group assignment is ignored.

Customize

Explicit Grants users the ability to customize their form view layout in BMC Remedy User. Use this group with caution.

Chapter 1

Defining access control

23

BMC Remedy Action Request System 7.6.04

Table 1-1: Special groups in AR System (Sheet 2 of 3) Group Submitter ID 3 Type Description

Implicit Provides field access to the user whose login name is in the Submitter field (field ID 2) for a particular request. The user who creates a request is usually automatically belongs to the Submitter group for that requests. For more information, see Submitter and Assignee access on page 39. See the Configuration Guide, Enabling submitters to modify requests, page 65, to enable a special server Submitter mode that allows the user who submitted a request to modify it without having a write license.

Assignee

Implicit Provides field access to the user whose name is in the Assignee field (field ID 4) for a particular request. The user whose name is in the Assignee field automatically belongs to the Assignee group. For more information, see Submitter and Assignee access on page 39.

Sub Administrator 5

Explicit Provides administrative access to selected server objects. Subadministratorsmembers of this groupcan be granted administrative access to objects that have the Subadministrator Permissions property. With administrative access, a subadministrator has the same access as an administrator for that object. See Subadministrators in AR System on page 66. A user must have a fixed license or this group assignment is ignored.

Assignee Group

Implicit Provides field access to the user who is a member of one of the groups listed in the Assignee Group field (field ID 112) for a request. A user automatically belongs to the Assignee Group group for requests in which the Assignee Group field exists and contains the name or ID of a group to which the user belongs, the name or ID of a role that maps to a group to which the user belongs, or the users name. For more information, see Assignee Group access on page 40 and Form, active link guide, and application permissions on page 31.
Note: Do not confuse this group with the Assignee

group, which gives permission to the individual user named in the Assignee field.

24

Form and Application Objects Guide

Groups in AR System

Table 1-1: Special groups in AR System (Sheet 3 of 3) Group Struct Admin ID 8


1

Type

Description

Explicit Struct Admin members can create, modify, and delete AR server objects, but have no access to data or to administrative functions unless provided by other groups in the user's group list. If the user is also assigned to a Struct Admin Permission Group, the user has the same access as an Administrator.
Note: For more information about Struct Admin

permissions, see Struct Admin group permissions on page 528. The assigned user must have a fixed license or this group assignment is ignored. Struct Subadmin 91 Explicit Struct Subadmin members can modify AR server objects subject to the same rules that govern Sub Administrator group members. If the object's Administrator group list contains a group in which the Struct Subadmin user is a member, the user has access. Struct Subadmin members have no access to data or to administrative functions unless provided by other groups in the user's group list. The assigned user must have a fixed license or this group assignment is ignored.
1.

This Group ID assignment is introduced in this release, and may present a conflict with custom type assignments.

In addition to the groups listed in the previous table, groups with IDs in the range of 60000 to 60999 are reserved for dynamic groups.

Groups you createRegular, computed, and dynamic


You can create the following groups in the Group form. Regular groupsExplicit groups that you create and to which you assign a specific list of users. For information about assigning users to groups, see the Configuration Guide, Adding and modifying user information, page 57. Computed groupsExplicit groups that you create and to which users are assigned based on the memberships of explicit groups included in an expression. For example, you can create a computed group definition such as (A AND B) OR C AND NOT D. This computed group includes the list of users who are members of both groups A and B, or members of group C, but not members of group D. Computed groups make groups easier to manage. You can manage your users in a limited number of regular groups, and use computed groups based on these regular groups for more complex access control without the need to make changes in multiple groups.

Chapter 1

Defining access control

25

BMC Remedy Action Request System 7.6.04

Dynamic groupsImplicit groups are similar to the reserved Assignee Group group in that the contents of special fields determine group membership. For more information, see Dynamic group access on page 40. For information about creating groups, see Creating and managing groups on page 49.

Using a parent group for permissions inheritance


Assigning a parent group can simplify permissions management in cases where one group, such as a service provider (the parent group), should have access to a set of objects or data belonging to several different groups, such as the separate companies contracting with the service provider (the child groups). When a parent group is defined, you manage access to objects and data in the application by assigning permissions to the child group and configuring the objects to allow permissions inheritance. As a result, members of the parent group automatically have the same access as members of the child group. Any regular or computed group that you create can be a parent group. A parent group is not a separate type of group, but rather represents a hierarchical relationship between the parent group and the child group, in which the parent group inherits the permissions of the child group. A parent group can have one or more child groups. A child group can also have child groups of its own, forming a multilevel hierarchy, but each child group can only have one parent group. In a multilevel hierarchy, assigning permission to a child group grants access to all ancestor groups, such as the parent group of a parent group. For example, in Figure 1-1, the group named Parts Supplier is a parent to the Dealer A and Dealer B groups, and an ancestor all the groups in the relationship. Dealer A and Dealer B are child groups to Parts Supplier, but parent groups to their respective Shop groups.

26

Form and Application Objects Guide

Groups in AR System

Figure 1-1: Hierarchical group relationships

In this example, an auto parts supplier needs to control access to the order database, such that employees of the parts supplier can see orders from all dealers and their respective authorized repair shops, but employees of each dealer can see only their own orders or those of their subcontracted shops. Employees of each shop can see only the orders for their own shop. This is accomplished by assigning Parts Supplier as the parent group for Dealer A and Dealer B, and by assigning Dealer A or Dealer B as the parent group for each of the shop groups. To assign a parent group, you modify the Group form entry for the child group. See Creating and managing groups on page 49.

NOTE
Hierarchical group relationships are used for permissions management only, and are not recognized when sending notifications by group.

Chapter 1

Defining access control

27

BMC Remedy Action Request System 7.6.04

Object properties that control hierarchical group access


Two object properties determine whether AR System grants access according to a parent group relationship: Static permissions inheritance controls hierarchical access for all AR System object types that use permissions, such as forms, active links, applications, and so on. Hierarchical access to fields is controlled by the permissions of the form. See Assigning permissions for individual or multiple AR System objects on page 61. Dynamic permissions inheritance is a form property that controls record-level access to data for hierarchical groups, in conjunction with implicit groups and related fields on the form. See Controlling access to requests for hierarchical groups on page 46. If the object properties do not include permissions inheritance, any hierarchical relationship defined for any of the groups in the object permission list is ignored.

Roles in AR System
Roles are permissions similar to groups, except that they belong to a particular application, instead of a particular server. Roles are used exclusively in deployable applications. Roles are defined for each deployable application and then mapped to explicit groups on the server. You can map a deployable applications roles to different groups on different servers, depending on how the groups are defined on each server. This allows you to develop and test the application on one server and deploy it to a number of other servers without having to redefine permissions on each server. You can also map roles to different groups for each development state, such as Test or Production. You can then switch between states using BMC Remedy Developer Studio or workflow. For more information, see Creating and mapping roles on page 55. Because roles are mapped to groups, the groups you define on the server and the users that belong to them are the foundation of access control. For more information about creating and using deployable applications, see Chapter 3, Defining applications.

28

Form and Application Objects Guide

Users in AR System

Users in AR System
A user is any person to whom you give permission to access AR System. Users can be members of multiple groups or no group at all. Users in AR System range from an administrator (who maintains the entire system) to employees (who submit requests or view data). AR System includes one predefined user (Demo). You can use the User form in BMC Remedy User or a browser to rename this user, and you can create additional users in AR System. For information about defining users for AR System, see the Configuration Guide, Adding and modifying user information, page 57.

Additive access control


Access control in AR System is additive. This means that each user in AR System begins with no permissions. Administrators then add permissions as needed. The server verifies the permissions of an object to determine if access to the object is granted. If access is granted at any step along the decision tree, as shown in Figure 1-3 on page 32, the user has permission to access the object. As you add permissions to various AR System objects, users have access to the object if they are members of any group with access or any role that maps to a group with access.

Chapter 1

Defining access control

29

BMC Remedy Action Request System 7.6.04

In Figure 1-2, Lydia Lan is a member of two groups: Engineering and Engineering Managers.
Figure 1-2: Additive permissions

Engineering Group

Engineering Managers Group

No Access

Access

Form1

Form1

In this example, the Engineering group does not have access to Form1, but the Engineering Managers group does. Thus, although Lydia does not have access to Form1 through the Engineering group, she does have access through the Engineering Managers group. You must assign permissions to every application, form, field, active link, active link guide, packing list, and web service that requires access control. Start by designing the access control for your application or forms. Define default permissions before you create objects and fields to save time and prevent errors. You can also use batch Edit dialog box and the Assign Group Permissions dialog box to change permissions for multiple object in one operation. For more information, see Assigning permissions on page 58.

30

Form and Application Objects Guide

Access to AR System objects

Access to AR System objects


You define permissions for applications, forms, fields, active links, active link guides, packing lists, and web services. Filters, filter guides, and escalations do not have permissions because these objects operate on the server. Menus also do not have (or need) permissions because they are attached to fields that have permissions.

Form, active link guide, and application permissions


Permissions determine which access control groups can access forms, active link guides, or applications in the user client (BMC Remedy User or a browser). If a user does not have access to the object, it does not appear in the home page or in the object list for the user. When creating a form, active link guide, or application, you must decide the permission for each group or role: VisibleMembers of the group or role can select and view the object in the user client. HiddenMembers of the group or role can access the object through workflow or by entering the URL in a browser, but cannot select the form in the home page or in the object list. NoneMembers of the group or role have no access to the object. Giving the members of a group access to a form does not automatically give those users access to the fields in that form or to active links and active link guides that use that form. You must also assign group permissions to each field and related object. If the form, active link guide, or application is configured to allow static permissions inheritance, granting permission to the form for a group also grants the same permission to any ancestors (parent groups at all levels) of that group. Similarly, when you map a role to a group, the role permissions for the application also apply to any ancestors of the mapped group. Figure 1-3 lists the questions that you can ask to determine the access that users have to forms in AR System. You can use this flowchart for guides and applications as well.

NOTE
A user who has access to the form through a hierarchical group relationship is in a group with permissions to the form. Also, web users can open Hidden forms with the correct URL, but the ability to use the form is controlled by field permissions.

Chapter 1

Defining access control

31

BMC Remedy Action Request System 7.6.04

Figure 1-3: Accessing forms, guides, and applications

Are you an administrator?

Yes

Full administrator access to all forms in the system

No

Are you a subadministrator?

Yes

Are you in a group with subadministrator permissions to form?


No

Yes

Full Administrator access to form

No

Are you in a group with permissions to form?


No

Yes

Is form hidden or visible?

Visible

Can see form in the Open dialog box in BMC Remedy User

Hidden

Cannot see form in the Object List dialog box in BMC Remedy User

Does Public group have permissions to form?


No

Yes

Can see form in BMC Remedy User

No access to form

Field permissions
Field permissions determine the types of access that groups or roles have for individual fields in a form: ViewUsers can read the contents of the field. ChangeUsers can read and write the contents of the field. If neither permission is selected, members of the group or role cannot view or change the field. Groups and roles are defined with maximum privileges of View or Change, as explained in To define default permissions for a server or an application on page 60 and in the example on page 36. Groups or roles with maximum View permission can never be assigned Change permission for a field; groups or roles with maximum Change permission can be assigned Change, View, or no permission for a field.

32

Form and Application Objects Guide

Access to AR System objects

If the form is configured to allow static permissions inheritance, granting permission to a field in the form for a group also grants the same permission to any ancestors (parent groups at all levels) of that group. Similarly, when you map a role to a group, the role permissions for the application also apply to any ancestors of the mapped group. Users must belong to a group or role with permission to view a forms Request ID field (core field 1), or they cannot access any information from that request. After you give a group or role access to the Request ID field, or to any field in the form, the user does not automatically have access to the form or to workflow attached to the field. You must grant permissions to each object individually.

NOTE
In a Set Fields operation, because active links execute with the permissions of the user, field values set through an active link are updated only if the user has permission to change the field. Values retrieved must be accessible by the user. For more information, see the Workflow Objects Guide, Set Fields action, page 129. Figure 1-4 on page 34 lists the questions that you can ask to determine the access that users have to fields in AR System. Some of the questions are covered in the Configuration Guide.

Chapter 1

Defining access control

33

BMC Remedy Action Request System 7.6.04

Figure 1-4: Accessing fields

Are you an administrator?

Yes

Full administrator access to all fields in all forms

No

Are you a subadministrator?

Yes

Are you in a group with subadministrator permissions to form?


No

Yes

Full administrator access to all fields in form

No

Are you in a group with change permissions to field?


No

Yes

Do you have a write license?

Yes

Can change data in field

No

Allow any user to submit?

Yes

Can change data in field during submit

Do you have a restricted read license?


No

Yes

View access only to data in field

No

No

Are you in a group with view permissions to field?


No

Yes

Can view data in field

Are you submitter and is Submitter mode set to locked?

Yes

Does Submitter group have Change permission?

No

Yes

Without permissions, no access at all to field

View access only to data in field

Can change data in field

Advanced data fields


Advanced data fields require you to set permission on various levels. The advanced data field types are table fields, panel fields, and attachment pools. For example, a panel field consists of three levels, each requiring consistent permission settings: the panel holder, the panel, and the fields on the panel (so the user can see the complete panel set). See Chapter 11, Types of fields, for more information about the following advanced fields.

34

Form and Application Objects Guide

Access to AR System objects

Table field permissions properties


Table field permissions are set in the same way as button field permissions, with the exception that you must set permissions at four levels. You must grant or deny a user access to the: Table field. Columns in the table. Form from which rows are drawn. Fields from which each column draws its data. The following examples explain the permission hierarchy: If a user does not have permission to view any columns, the field or list appears blank in the user client. If a user does not have permission to access a field in the supporting form that contains column data, the user sees a blank cell. If the user has no permission to access any of the cells in a row, the row is not displayed.

Panel field permissions properties


Panel field permissions are set at three levels. You must grant or deny a user access to The panel holder Each panel in the panel holder Each field in each panel To see an individual field (the lowest level of the permission hierarchy), the user must have permission to the upper levels of the hierarchythat is, to the panel holder and the individual panels.

Attachment pool permissions properties


For attachment pool field and attachment field permissions, you must grant or deny a user access to both. To see an individual attachment field, the user must have permission to the attachment pool field. If a user does not have permission to view any attachment fields, the attachment pool appears blank in the user client.

Chapter 1

Defining access control

35

BMC Remedy Action Request System 7.6.04

Special submit setting


A special submit setting allows users to submit a new request without Change permission for data and attachment fields that require a value. To use this feature, set the Allow Any User to Submit property to Yes for each applicable field. If the Allow Any User to Submit property is set to No and the field requires a value, a user must have a Write license and belong to a group with Change permission for the field to submit a request. For more information about using this feature, see Defining default permissions on page 59 and Assigning permissions for individual or multiple AR System objects on page 61.

Field permissions example


Figure 1-5 illustrates how both permissions and field definitions work together to determine the access to a field. The example lists three groups: Browser, CS Staff, and Sales Staff. These groups have different maximum privileges of View or Change, as explained in To define default permissions for a server or an application on page 60.
Figure 1-5: Specifying field access control
Browser Group (Maximum View access) Members: Rick Silvia CS Staff Group (Maximum Change access) Members: John Doug Sales Staff Group (Maximum Change access) Members: Alice Ben Lydia

At the field level, each group is granted specific access to the Short Description data field: CS Staff groupChange Sales Staff groupView Browser groupView (Because the Browser group has a maximum access of View, Change access at the field level is not possible.)

36

Form and Application Objects Guide

Access to AR System objects

John is a member of the CS Staff group and the Browser group. Although membership in the Browser group alone does not allow him to change the field, he can change it because of his group permission in the CS Staff group. When a user belongs to more than one group with different permissions to a field, the user has the highest level of permission granted by a group to which the user belongs. Alice is a member of the Sales Staff group, which has maximum permission of Change. However, at the field level, members of the Sales Staff group can only view the contents of this field. Rick also can only view the contents of the Short Description field because he is a member of the Browser group. Because the Browser group has maximum privileges of View, you can never give him Change permission for the Short Description field through the Browser group as it is currently defined.

Active link permissions


When you create an active link, you must define which groups or roles have access to it. A group or role needs permission to execute an active link. After you give a group or role access to an active link, the user does not automatically have access to the field to which the active link is attached or to the form that contains the field. You must also assign permissions to the form and the field. Figure 1-6 lists the questions that you can ask to determine the access that users have to active links in AR System.
Figure 1-6: Accessing active links

Are you an administrator?

Yes

Can execute all active links

No

Are you a subadministrator?

Yes

Are you in a group with subadministrator permissions to form?


No

Yes

Can execute all active links connected to forms you administer

No

Are you in a group with permissions to active link?


No

Yes

Can execute active link

Cannot execute active link

Chapter 1

Defining access control

37

BMC Remedy Action Request System 7.6.04

Access to requests
Defining access to requests is important when you want to keep certain groups of users from knowing that certain requests exist. For example, if you use AR System as the outsource help desk for several companies, you can assign access to requests so that only the company that submitted the request can see it. You determine which groups or roles have access to a request through the Request ID field (field ID 1). If a group or role does not have access to that field, the group or role has no access to the request, even if it has access to other fields in that form. You can grant access to members of explicit groups or roles. For example, you can give managers access to all requests. You can also grant access to members of implicit groups. For example, submitters can see their own requests but not those submitted by other users. For more information, see Controlling access by using implicit groupsRow-level security on page 38. Figure 1-7 lists the questions that you can ask to determine the access that users have to requests in AR System.
Figure 1-7: Accessing requests

Are you an administrator?

Yes

Full administrator access to all requests

No

Are you a subadministrator?

Yes

Are you in a group with subadministrator permissions to form?


No

Yes

Full administrator access to all entries created from form

No

Are you in a group with permissions to Request ID field?


No

Yes

Can view request

Cannot view request

Controlling access by using implicit groupsRow-level security


You can limit access to requests on a per-group or per-user basis. (This is often described as row-level access, because each request is a row in the database table.) Membership in implicit groups (and their corresponding permissions) is implied when specific values are entered into certain AR System fields.
38 Form and Application Objects Guide

Access to requests

The following table shows the differences and similarities among these implicit groups and their associated fields.
Table 1-2: Implicit groups and their associated fields Implicit group Submitter Assignee Assignee Group Dynamic groups Group ID 3 4 7 Associated default Field ID field name Submitter Assigned To None 2 4 112 Core field? Yes Yes No Associated field contents User name User name User, group, or role names User, group, or role names

6000060999 None

6000060999 No

You can also grant parent groups row-level access. For information, see Controlling access to requests for hierarchical groups on page 46. Fields with row-level security in searches are handled differently than regular fields to ensure that indexes (if used) are used properly and performance is not impacted. For example, a form might contain two fields (Field1 and Field2) and two dynamic groups (DynamicGroup1 and DynamicGroup2). DynamicGroup1 controls access to Field1, and DynamicGroup2 controls access to Field2. A user (not an administrator) performs a search with the following qualification:
'Field1' != $\NULL$ OR 'Field2' != $\NULL$

The following SQL WHERE clause is used in the search:


(Field1 is not NULL OR Field2 is not NULL) AND (user is member of DynamicGroup1) AND (user is member of DynamicGroup2)

If regular fields were used, the following SQL WHERE clause would be used:
(Field1 is not NULL AND (user is member of DynamicGroup1)) OR (Field2 is not NULL AND (user is member of DynamicGroup2))

Submitter and Assignee access


The Submitter and Assignee groups allow access to requests or fields on a per-user basis. To have access as a member of the Submitter group, the contents of field ID 2 must be the users login name. Field ID 2 is usually set on submission by using the $USER$ keyword to define this fields contents. To have access as a member of the Assignee group, the contents of field ID 4 must equal the users login name. Field ID 4 is often set manually or by workflow to a users name when the status of the request changes.

Chapter 1

Defining access control

39

BMC Remedy Action Request System 7.6.04

Assignee Group access


The Assignee Group group allows access to requests or fields on a per-user or pergroup basis. To provide Assignee Group access, you must add the Assignee Group field (field ID 112) to your form and then specify which users, groups, or roles should have access to the request in this field. Although you can set the Assignee Group field manually, it is typically set by workflow. For more information, see Using the Assignee Group and dynamic groupsExamples on page 42.

Dynamic group access


Dynamic groups are similar to the Assignee Group (field ID 112), except that they are defined by the developer and include field and group IDs in the range of 60000 to 60999. For example, when you create a group with group ID 60000, its user list includes the individual user name or the members of any group or role that appears in field ID 60000. For more information, see Using the Assignee Group and dynamic groupsExamples on page 42.

NOTE
The BMC Remedy ITSM Suite uses group IDs 60899, 60900, and 60901 to control multi-tenancy in ITSM applications. Do not use these IDs if you are using a dynamic group to customize an ITSM application.

Using the Request ID field with implicit groups


Using implicit groups to control access to requests is a powerful method of access control within AR System. The Request ID field plays a key role in access control because a user cannot see a request unless the user belongs to a group with permission for its Request ID field.

Defining access to requests at the user level


You can link access control to a users login name: To give submitters or assignees access to their requests on a single-user basis, grant the Submitter and Assignee groups permission to the Request ID field. To give other users access, grant the Assignee Group or dynamic groups access to the Request ID field. Make sure that you also add field ID 112 (the Assignee Group field) or the correct dynamic group fields to the form. To grant access to requests for hierarchical groups, use the Dynamic Permissions Inheritance form property. See Controlling access to requests for hierarchical groups on page 46.

40

Form and Application Objects Guide

Access to requests

If you are using a users login name to assign access, remember these tips: In the Submitter or Assignee fields, enter the users login name without quotation marks. In the Assignee Group or dynamic group fields, enter the users login name in single quotation marks. Double any single quotation marks that are part of the login name (for example, Dan OConnor).

Defining access to requests at the group level


Unlike Submitter and Assignee access, Assignee Group and dynamic group access can extend access control on a conditional basis by using explicit group and role membership. To permit multiple user, group, and role names in the Assignee Group field and dynamic fields, select Enable Multiple Assign Groups on the Configuration tab of AR System Administration: Server Information form. To enter users Dan OConnor and Mary Manager, group ID 12000, role ID -9000, and role Managers, use the following syntax:
Dan OConnor;Mary Manager;12000;-9000;Managers

NOTE
If a group and role have the same name, the role name is assumed. For example, if a dynamic field contains Managers;Sales, AR System assumes the Managers and Sales roles, if they exist; otherwise, AR System assumes the Manager and Sales groups. For more information about all settings in the AR System Administration: Server Information form, see the Configuration Guide, Configuring AR System servers, page 122. Assignee Group and dynamic group permissions to the Request ID field, combined with the contents of the Assignee Group field or dynamic group fields, determines who can see the request. If a group or role to which the user belongs is in the Assignee Group or dynamic group field for a request, that user is given whatever access privileges you defined for the Assignee Group or dynamic group, as shown in Figure 1-8.

Chapter 1

Defining access control

41

BMC Remedy Action Request System 7.6.04

Figure 1-8: Controlling access to requests by using row-level security


AR System checks permissions for Request ID field

Yes

Your name in Field ID 2?


No

Yes

Submitter group has access?


No

Can access request

Yes

Your name in Field ID 4?


No

Yes

Assignee group has access?


No
Unless a member of another group with access to Request ID field or dynamic groups if applicable or dynamic group fields (ID 60000-60999) if applicable

Yes

Your name, group, or role in Field ID 112?


No

Yes

Assignee Group group has access?


No

No access to request

Using the Assignee Group and dynamic groupsExamples


Use Assignee Group access, dynamic group access, or both to set up permissions so that users have conditional access to requests. Imagine that you are working for Acme Outsource Help Desks, Inc. Three computer companies hire you to manage all of their help desk responsibilities. For security reasons, each computer company must not know about the existence of the other two. Therefore, you must create one form all three companies can use, but allows each company to see only the requests they create. Explicit groups for each company have already been created, and each user belongs to one of these company groups.

42

Form and Application Objects Guide

Access to requests

To use the Assignee Group to control access to requests


1 Create the groups (or roles) and users to which you want to assign access.

In this example, the four groups are: Acme Help Desk Staff (who will have access to all requests) Beta Computers Gamma Computers Delta Computers Beta Computers, Gamma Computers, and Delta Computers users must belong only to their company group. Acme employees can be members of more than one group.
2 Create a form, and give the appropriate groups Visible permission for it.

For example, giving the Public group Visible permission for the form enables all of the users to see it.
3 Add Assignee Group access to the form.

The Assignee Group capabilities of AR System are activated when you add a character field to the form with field ID 112 and a database input length of 255.
4 Restrict access to the necessary requests.

Because only groups or roles with permission for the Request ID field can access a request, restricting access to the Request ID field is the key to restricting access to a request. In this example, the Acme Help Desk Staff and the Assignee Group groups have the appropriate permissions for the Request ID field, as shown in Figure 1-9.
Figure 1-9: Field permissions for the Request ID field

Chapter 1

Defining access control

43

BMC Remedy Action Request System 7.6.04

With Assignee Group access, a user from Beta Computers can submit requests, and anyone from Beta Computers can query them. However, no one from Gamma Computers or Delta Computers can query Beta Computers requests.

NOTE
You might want to give permissions to a single group to begin with and submit a sample request to determine if any group other than the designated group can access it.
5 Add workflow that inserts at least one explicit group, role, or user name into field

ID 112 according to the business rules at your site. If Enable Multiple Assign Groups is selected on the Configuration tab of the AR System Administration: Server Information form, you now can enter more than one explicit group, role, or user name into field ID 112. For sample syntax, see Defining access to requests at the group level on page 41. For more information about all settings in the AR System Administration: Server Information form, see the Configuration Guide, Configuring AR System servers, page 122. Because field ID 112 is designed for administrators and your help desk staff, deny access for most groups to this field. You can define a filter to set the contents of this field and use an active link Change Field action to allow your help desk staff to see and change the field as needed. If you must change the group or role in the field, field ID 112 includes system-defined menus of all groups on the server and roles in the application (if the form is owned by a deployable application). Administrators can override these menus in BMC Remedy Developer Studio as needed. In the example, Acme allows access to its service call database from a browser but limits users to view only requests submitted by members of their company. An access control group was created for each different company name, and a filter that copies the company name into field ID 112 (labeled Assignee Group in Figure 110) executes when users submit requests.

44

Form and Application Objects Guide

Access to requests

Figure 1-10: Using Assignee Group access in workflow

When the filter executes, the Assignee Group for this request is Beta Computers. You also could have created individual filters, one that enables Beta Computers to see their requests, another that enables Gamma Computers to see their requests, and so on. Use appropriate filter qualifications to make sure that only users from the Beta Computers group can execute the filter, set field ID 112 to Beta Computers, and so on. For more information about creating and using filters, see the Workflow Objects Guide, Introducing workflow, page 15.
6 Change the permissions of other fields in the form to grant access as needed.

Include the Assignee Group where appropriate. As a result of carefully defining access control in your system, when members of Acme Outsource Help Desks search all open help desk requests, they see a results list that includes requests submitted by Beta, Gamma, and Delta Computers. In contrast, if users from Delta Computers perform the same search, they see only the requests where Delta Computers is the Assignee Group (that is, the requests submitted by anyone at Delta Computers).

Chapter 1

Defining access control

45

BMC Remedy Action Request System 7.6.04

To use a dynamic group to control access to requests


Step 1 Create the groups (or roles) and users to which you want to assign access. Step 2 Create a dynamic group in the Group form.

For example, create a group called Dynamic Access with a group ID of 60001.
Step 3 Create a form, and give the appropriate groups Visible permission for it. Step 4 Add a character field to the form with field ID 60001, the same ID number as the

dynamic group ID.


Step 5 Restrict access to requests in the form by granting the group Dynamic Access

permission to the Request ID field.


Step 6 Add workflow that inserts at least one explicit group name or ID, role name or ID,

or user name into field ID 60001 according to the business rules at your site. If Enable Multiple Assign Groups is selected on the Configuration tab of the AR System Administration: Server Information form, you can enter more than one explicit group, role, or user name into field ID 60001. For sample syntax, see Defining access to requests at the group level on page 41. For more information about all settings in the AR System Administration: Server Information form, see the Configuration Guide, Configuring AR System servers, page 122. Like field ID 112, dynamic group fields can be modified manually. They include system-defined menus of all groups on the server and roles in the application (if the form is owned by a deployable application). Administrators can modify these menus as needed.

Controlling access to requests for hierarchical groups


To manage row-level access for the parent or ancestor groups in a hierarchical group relationship, use the Dynamic Permissions Inheritance form property along with a second implicit group field on the form. (The static permissions inheritance property can also be set on the form to control access to the form and its fields for parent groups.) To configure dynamic permissions inheritance, you create a dynamic group that AR System will populate with any parent or ancestor groups at run time, and add a field to the form with the same ID as this dynamic group. At run time, for any group ID or name that workflow enters in the child dynamic group field, AR System checks whether there are any ancestor groups defined. If so, AR System enters the parent group ID (or IDs, if there are multiple levels of hierarchy) in the parent dynamic group field, giving the parent group row-level access to the request. For an overview of hierarchical group relationships, see Using a parent group for permissions inheritance on page 26.

46

Form and Application Objects Guide

Access to requests

To control access to requests for hierarchical groups


1 Follow the appropriate procedure in Using the Assignee Group and dynamic

groupsExamples on page 42 to configure row-level access for the child group.


2 Create a new dynamic group that will identify the parent group relationships at

run time, and assign it a group ID in the dynamic group range, such as 60002. For example, create a dynamic group named Parent Dynamic Access.
3 Add a character field to the form with the same field ID number as the Parent

Dynamic Access group ID, in this example, 60002.


4 Grant the group Parent Dynamic Access permission to the Request ID field. 5 With the form selected, choose Form > Form Properties > Permissions.

6 In the Dynamic Permissions Inheritance field, map the child implicit group field

ID to the parent dynamic group field ID, as in these examples:


112:60002 60001:60002

Enter the child dynamic group ID first, followed by a colon, and then the parent group ID.
7 Click OK to save the form permissions.

Chapter 1

Defining access control

47

BMC Remedy Action Request System 7.6.04

Putting it all together


Figure 1-11 presents an overview of access control, and lists the questions that you can use to determine the access that users have to AR System.
Figure 1-11: Access control overview

Server Access

Does login name match user definition?


Yes

No

Are guests allowed to log in?

No

No access to server

Yes

Does password match?

No

No access to server

Yes

Form Access

Do you have access to the form?

No

No access to form

Yes

Request Access

Is the request viewable?

No

No access to request

Yes

Field Access

Is the field viewable?

No

No access to field

Yes

Form, request, and field accessible

48

Form and Application Objects Guide

Creating and managing groups

Creating and managing groups


Use the Group form (shown in Figure 1-12) in BMC Remedy User or a browser to create and manage the access control groups to which you grant or deny access to AR System objects.

NOTE
You must log on as an Administrator to work with the Group form.

Creating groups
This section provides the steps to create AR System access control groups. Although there is no limit to the number of groups that you can create, for maintenance purposes you might want to limit the number to avoid confusion. After you have created the necessary groups, see the Configuration Guide, Adding and modifying user information, page 57, to assign individual users to the appropriate groups.
Figure 1-12: Group Information formNew mode

Chapter 1

Defining access control

49

BMC Remedy Action Request System 7.6.04

The following table lists the fields you can set the Group form.
Table 1-3: Fields in the Group Information form (Sheet 1 of 4) Field Group Name Description Name of the access control group. Use this name in the Group list field in the User form and in the Permission and No Permission lists when you are defining AR System object permissions. Every group name should be different. Use caution when creating group names that include spaces, because group names in the Group list field on the User form are separated by spaces. For example, if you have a group named CUSTOMER SUPPORT, you should not create a group named CUSTOMER or a group named SUPPORT. Group ID Integer ID that is the recognized identity of the group. The ranges are: 01000For AR System groups and current AR System applications 100013004 and 1300714999For regular and computed groups 1300513006For CMDB groups 1499959999For future AR System applications 6000060999For dynamic groups If you use the same ID with multiple group names, you must keep the Group type the same for each because you are creating aliases for the same group. To make sure that you do not create duplicate Group IDs, use BMC Remedy Developer Studio to build a unique index on the Group ID field in the Group form. (For more information, see To define indexes for a form on page 181.) The Group ID defines the priority of a group when a user obtains a floating license. See the Configuration Guide, License pools, page 53.
Note: The BMC Remedy ITSM Suite uses the IDs 60899, 60900, and

60901 to control multi-tenancy in ITSM applications. Do not use these IDs if you are customizing an ITSM application. Group Type Maximum permission type intended for the group. Your choices are None (no access), View (view field contents), and Change (modify field contents). Specify None to disable all access for the group without deleting the group itself. The group remains as a placeholder (and can be restored in the future), but all permissions for the group are lost. To define a group used only for notifications, create a group with the type None. For more information about field permissions, see Field permissions on page 32. Long Group Name Additional information about a group. The text should be descriptive of the group because it appears by default in the Results pane in BMC Remedy User when listing groups.

50

Form and Application Objects Guide

Creating and managing groups

Table 1-3: Fields in the Group Information form (Sheet 2 of 4) Field Group Category Description The group category, such as Regular, Dynamic, or Computed, which is described in Groups you createRegular, computed, and dynamic on page 25. To define a dynamic group, use a group ID in the range of 60000 to 60999. On the form containing requests to which you want to define row-level access, add a field with a field ID that is the same as the dynamic group ID. You can populate a dynamic group field with a group name, role name, or the name of an individual user. Dynamic Groups are used only to control access to requests (row-level access). To define a computed group, select Computed Group as the group category and enter a qualification string in the Computed Group Definition field. Parent Group The parent group, if any, of the current group. This field is optional. If a parent group is assigned, members of the parent group have the same rights as members of the current group to objects that allow permissions inheritance. A group can have at most one parent group. Any regular or computed explicit group can act as a parent group, except for Administrator, Sub Administrator, and Customize. Implicit groups cannot be used as a parent group. (Implicit groups include Assignee, Submitter, Assignee Group, and dynamic groups.) To assign a parent group, the parent group must already exist. Select the parent group from the drop-down list. For an overview of hierarchical groups, see Using a parent group for permissions inheritance on page 26. For information about setting permissions inheritance for an object, see Assigning permissions for individual or multiple AR System objects on page 61. For information about row-level access control and hierarchical groups, see Controlling access to requests for hierarchical groups on page 46.

Chapter 1

Defining access control

51

BMC Remedy Action Request System 7.6.04

Table 1-3: Fields in the Group Information form (Sheet 3 of 4) Field Overlay Group Description Use the setting to define the group as an Overlay Group. The Overlay Group option on the Group Information Form, provides the following access options: Overlay Group field set to 1 When a group assigned to the user has the Overlay Group field is set to 1, the user is restricted to working on overlay and custom mode objects. In Developer Studio, the user can work only in Best Practice Customization mode. Overlay Group field set to 0 When a group assigned to the user has the Overlay Group field is set to 1, the user is restricted to working on base mode objects. In Developer Studio, the user can work only in Base Developer mode. Overlay Group set to (clear) When the Overlay Group is set to (clear) the Group provides no restrictions on access to base, overlay, or custom objects.
Note: For more information about Overlay Groups, see the Form and

Application Objects Guide, Table 1-3 on page 50, Overlay Group.


Note: For more information, see the Form and Application Objects

Guide, Groups in AR System, page 22. Also see Introduction to Application Development with BMC Remedy Developer Studio, Operations on objects restricted by development mode, page 32. Computed Group Definition Qualification string that defines a computed group. Construct the string from any valid combination of explicit group IDs, explicit group names (in double quotation marks), user names (in single quotation marks), and operators such as AND, OR, and AND NOT. Optionally, use the AND, OR, NOT, Append Group, Append User, and parentheses buttons to build the qualification string. For example: 12000 OR 12001 includes all users in group ID 12000 or group ID 12001. A OR B includes all users in group A or group B. A AND B includes only those users in group A and group B. (A OR B) AND NOT C includes all users in groups A or B, except for those users who are in group C. A OR Mary Manager includes all users in group A, and the user Mary Manager. Floating Licenses Number of floating licenses reserved for the group. See the Configuration Guide, License pools, page 53. If this field is missing from the Group form, you can add it using BMC Remedy Developer Studio. Use field ID 115. See Creating data fields on page 184.

52

Form and Application Objects Guide

Creating and managing groups

Table 1-3: Fields in the Group Information form (Sheet 4 of 4) Field Application Floating License Description Application name and the number of application floating licenses to be held in the application license pool for a particular group. Manually enter the information for this field. You can add more than one entry of application names and number of licenses, separated by a semicolon. Use the following syntax when providing users with application licenses: vendorName:applicationName user typeOfLicense:Number of licenses;
Note: For the Application Floating License field, the value of

typeOfLicense is Floating. For example: For single application: XYZ:MusicManager User Floating:5; For multiple applications, separate multiple licenses with semicolons: XYZ:MusicManager User Floating:5; XYZ:NoiseManager User Floating:2;
Note: The applicationName string must be the same as the

Product Name string in the Application Licensing dialog box (Application > License Application) in BMC Remedy Developer Studio. If the Application Floating License field is missing from the Group form, you can use BMC Remedy Developer Studio to add the field. Use field ID 115. See Creating data fields on page 184.
Note: To use BMC Remedy AR Systembased applications from

BMC Software, you need an AR System user (floating) license (to access the AR System server) and an application user (floating) license (to access the application). Unique Identifier A unique identifier for the group. A unique identifier is useful if you have two groups with the same name for different applications. You can use the unique identifier to differentiate the two.

NOTE
If attributes that you want to specify in the group definition are not represented in the Group form, you can use BMC Remedy Developer Studio to add the appropriate fields. However, be careful that you do not modify or delete any of the original fields or field IDs.

Chapter 1

Defining access control

53

BMC Remedy Action Request System 7.6.04

To create groups
1 In BMC Remedy User or a browser, open the Group form of the appropriate server

in New mode.
2 Enter information in the appropriate fields, as described in the previous table. 3 Save your changes.

For a regular group, assign users to it by using the User form in BMC Remedy User or a browser. After you save a group, the server automatically recaches, and the new group appears in the Group menu in the User form after a short delay. For more information about adding users, see the Configuration Guide, Adding and modifying user information, page 57. To enable a dynamic group, add a field to the form with a field ID that is the same as the group ID. For more information, see Group Category on page 51.

Managing groups
You can modify, delete, or search for groups in the Group form.

To search for groups


1 In BMC Remedy User or a browser, open the Group form of the appropriate server

in Search mode.
2 Enter values in fields, or use the Advanced Search Bar to specify search criteria.

For computed groups, enter one group ID or one user name (in single quotation marks) in the Computed Group Definition field. If you use the Advance Search Bar, use the LIKE operator to indicate that you are searching for a portion of a string (see the Workflow Objects Guide, Operators, page 216). The search returns all computed groups that include the specified user or group in the definition. You cannot search the Computed Group Definition field for group names, or for strings that include operators such as AND, OR, and NOT. This is because AR System converts group names to group IDs and encodes operators before storing them in the database. However, the search results do show the strings as they were originally entered, with group names and operators.
3 Choose Actions > Search to retrieve the list of currently defined groups that match

your search criteria. For more information about performing searches, see BMC Remedy User Help.

NOTE
Informix databases do not support searches on the Computed Group Definition field.

54

Form and Application Objects Guide

Creating and mapping roles

To modify groups
1 In BMC Remedy User or a browser, open the Group form of the appropriate server

in Search mode.
2 Perform a search to retrieve a list of currently defined groups. 3 Select the appropriate group from the list. 4 Modify information in the appropriate fields. 5 Save your changes.

To delete groups
1 In BMC Remedy User or a browser, open the Group form of the appropriate server

in Search mode.
2 Perform a search to retrieve a list of currently defined groups. 3 Select the appropriate group from the list. 4 Choose Actions > Delete.

A confirmation box appears to verify that you want to delete the group entry.
5 Click OK.

NOTE
Permissions for a user are determined by the list of groups in the Group list field of the users entry in the User form. If you later delete a group or change its Group ID, the users originally assigned to the group are still attached to the old ID. If there is no group with the old ID, these users are no longer attached to any group.

Creating and mapping roles


Use the Roles form (shown in Figure 1-13 on page 56) in BMC Remedy User or in a browser to create roles to which you grant or deny access to objects in deployable applications. In deployable applications, you assign permissions using implicit groups (including dynamic groups) and roles. You then map roles to explicit groups on the server. For more information about deployable applications, see Chapter 3, Defining applications. This section provides the steps to create roles and map them to explicit groups. Although there is no limit to the number of roles that you can create, for maintenance purposes you might want to limit the number.

NOTE
You must log on as an Administrator to work with the Roles form.

Chapter 1

Defining access control

55

BMC Remedy Action Request System 7.6.04

You can map roles to regular or computed groups for the Test and Production application development states. You can also create custom states and map roles for those states, as explained in Creating custom states on page 98. To enable a particular mapping, change the applications state, as described in Working with deployable application states on page 97.
Figure 1-13: Roles formNew mode

The following table lists the key fields in the Roles form.
Table 1-4: Key fields in the Roles form (Sheet 1 of 2) Field Application Name Description Name of the deployable application for which the role is defined. You can define the same role for multiple applications, but you must create a separate Roles form entry for each. Name by which the role is known. Within each application, every role name should be unique. You can reuse the same role name-role ID pairs across a suite of applications. Integer ID that is the recognized identity of the role. The ID must be a negative number, such as -10001. Role IDs must be unique for each application name. You can reuse the same role name-role ID pairs across a suite of applications.

Role Name

Role ID

56

Form and Application Objects Guide

Creating and mapping roles

Table 1-4: Key fields in the Roles form (Sheet 2 of 2) Field Test Description Enter or select one group name for the regular or computed group to which you want to map this role for the Test application state. To enable this mapping, set the applications State property to Test. For more information, see Working with deployable application states on page 97. Production Enter or select one group name for the regular or computed group to which you want to map this role for the Production application state. To enable this mapping, set the applications State property to Production. For more information, see Working with deployable application states on page 97.

To create and map roles


1 In BMC Remedy User or a browser, open the Roles form in New mode for the

server that contains the deployable application for which you are creating roles.
2 Enter information in the Application Name, Role Name, and Role ID fields, as

described in the previous table. If you save the role now, you can begin assigning permissions for this role to objects within the application. A role is listed only for object in the deployable application to which the role belongs.
3 Enter a regular or computed group ID in each Mapped Group field to define access

permissions for each application state.


4 Save your changes.

NOTE
Newly created roles appear in Permissions dialogs after the server recaches (about 5 seconds, depending on your system).

To modify roles and role mappings


1 In BMC Remedy User or a browser, open the Roles form in Search mode for the

server that contains the deployable application for which you are creating roles.
2 Search the form to retrieve a list of currently defined roles for a particular

application.
3 Select the appropriate roles and modify information in the appropriate fields. 4 Save your changes.

To delete roles
1 In BMC Remedy User or a browser, open the Roles form in Search mode for the

server that contains the deployable application for which you are creating roles.
2 Search the form to retrieve a list of currently defined roles for a particular

application.
Chapter 1 Defining access control 57

BMC Remedy Action Request System 7.6.04

3 Select the appropriate role. 4 Choose Actions > Delete.

A confirmation box appears to verify that you want to delete the role entry.
5 Click OK.

Assigning permissions
You assign permissions to applications, forms, fields, active links, active link guides, flashboards, flashboard variables, packing lists, and web services. BMC Remedy Developer Studio includes these ways to assign or modify permissions: Default permissionsThe permissions automatically created for a new object. Default permissions are preset permissions that you define per object type. You can set default permissions to apply to all objects on the server, or only within an application. Once defined, default permissions are automatically applied when you create any object of that type. Defining default permissions is optional, but can be useful if a certain group or role should always have permission to an object type. If you do not set default permissions, only administrators (and subadministrators where assigned) can access an object until you assign specific permissions to it. See Defining default permissions on page 59. Permissions for individual objectsYou can specify which groups or roles can access an object when you create or modify the object. when you need to control user access at the object level. The steps for this option are described in To assign permissions for a form on page 61 and To assign permissions for other objects on page 62. Permissions for fieldsYou can specify which groups or roles can view or change the data in a field when you create or modify the field. A group can have permission to a form but must also be granted permission to the fields in the form. The steps for assigning field permissions are described in To assign permissions for one or more fields on page 63. Batch permissionsYou can specify permissions for multiple objects of the same type at the same time. For more information, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Modifying object properties, page 51. Group and role permissionsYou can give a group or role access to every applicable object in a server or deployable application instead of opening each object and modifying the permissions individually. This method can be useful if you have added a new group or role after the objects were created. The steps for this option are described in To assign permissions for a group to multiple objects on page 64.

58

Form and Application Objects Guide

Assigning permissions

Defining default permissions


Default object permissions are defined by object type. They are applied when you create a new object or when you click Apply Defaults in the permissions dialog box for an existing object. You can define default permissions for an object type for the server in general, or you can set them within an application. Server default permissions are an administrator preference setting and are stored in the users Developer Studio workspace, so they only apply for the administrator or subadministrator who defines them. Application default permissions are associated with the application, so any administrator or assigned subadministrator can use them. Application default permissions are applied to objects created in that application, but not to other objects on the server. Setting default permissions is most appropriate for a development server. When developing an application or a workflow component, first create the groups or roles that will have access to all the objects in the application or workflow. Then, configure default permissions to use those groups or roles. Thereafter, when you create these objects and fields, AR System applies the default permissions and you only need to set individual object or field permissions in cases where the default permissions are not correct. Figure 1-14 shows example default permissions defined for forms on a server. The groups listed will be granted visible permissions or hidden permissions to any new forms.
Figure 1-14: Server default permissions

Chapter 1

Defining access control

59

BMC Remedy Action Request System 7.6.04

Figure 1-15 shows the Default Permissions dialog box for an application. In this case, the administrator is assigning permission for new active link guides created in the application.
Figure 1-15: Application default permissions

The default permissions for the object type are automatically applied to the object or field when it is created, and are displayed in the Permissions property. To reset permissions to the defined default permissions for an existing object or field, open the Permissions dialog box for the object or field, and then click Restore Defaults. For additional information about permissions, see the following sections: Form, active link guide, and application permissions on page 31 Field permissions on page 32 Active link permissions on page 37 Assigning permissions for individual or multiple AR System objects on page 61

To define default permissions for a server or an application


1 Open the appropriate Default Permissions dialog box:

To set default permissions for an application:


a Open the application in the application editor. b Choose Application > Default Permissions.

To set default permissions for a server:


a Choose Window > Preferences. b In the Preferences dialog box, expand BMC Remedy Developer Studio and

select Default Permissions.


c Select the appropriate server from the Server drop-down list. 2 In the Default Permissions preferences page or dialog box, select the appropriate

object type.
60 Form and Application Objects Guide

Assigning permissions

3 To add default permissions, click Add.

For a server, all appropriate groups are listed. For an application, the roles for that application and appropriate implicit groups are listed.
4 In the Add Groups dialog box, select the groups or roles to add and click OK. 5 In the Default Permissions page or dialog box, set the access level in the

Permissions column.
Table 1-5: Access levels Object type Access level Access for users in the group or group mapped to the role View and access the object in the user client. Access to the object only through workflow.

Active link guide Visible Application Hidden Form Web service Field Active link Packing list View Change (none)

View the field. View and change the field. View and access the object in the user client.

6 For fields only, select or clear the Allow Any User to Submit check box.

Use this mode to determine security for the field when a request is submitted. If the check box is: SelectedAny user can assign a value to the field, regardless of whether the submitter belongs to a group with Change permission to the field. Cleared (the default)Only users who belong to one or more groups with Change permission to the field (or users who belong to groups mapped to roles with Change permission to the field) can enter data into the field.
7 To remove default permissions, select the group or role in the Permissions list and

click Remove or click Remove All.


8 Click OK to save your changes and close the Preferences dialog box.

The default permissions are defined for the server or application you selected and the current administrator login. Each administrator can have different default permissions for objects created on each server.

Assigning permissions for individual or multiple AR System objects


To override the default permissions or otherwise set specific permissions for individual objects or multiple objects, use the procedures in this section.

To assign permissions for a form


1 In BMC Remedy Developer Studio, open the form for modification. 2 Select Form > Form Properties. 3 In the Form Properties dialog box, select the Permissions page.

Chapter 1

Defining access control

61

BMC Remedy Action Request System 7.6.04

4 In the Permissions page, use the arrow buttons to move the appropriate groups

and roles into the Permissions list.


5 For each group or role in the Permissions list, click the drop-down menu in the

Permissions column to set the access level to Visible or Hidden.


6 To configure hierarchical group access to the form, select Static Permissions

Inheritance. When static permissions inheritance is allowed, the Complete Permissions area shows a list of all groups that have access to the form, including any parent groups. However, you must save the permissions changes and reopen the Form Properties Permissions page to see the current list.

NOTE
You will not automatically see updates to this list if changes are made simultaneously by another developer. To see concurrent updates, you must close and reopen the Form Properties Permissions page.

7 To configure hierarchical group access to requests in the form, configure the

Dynamic Permissions Inheritance field as described in Controlling access to requests for hierarchical groups on page 46.
8 Click OK to close the Form Properties dialog box. 9 Choose File > Save to save the permission changes.

To assign permissions for other objects


1 In BMC Remedy Developer Studio, open the object for modification. 2 In the Properties tab, click the Permissions property and click the ellipsis button. 3 In the Permissions dialog box, use the arrow buttons to move the appropriate

groups and roles into the Permissions list. All groups defined on the server (or roles defined for the application that contains the object) are displayed. To allow all users to see a form, active link guide, or application, add the Public group to the Permission list.

62

Form and Application Objects Guide

Assigning permissions

4 For objects that have different access levels, for each group or role in the

Permissions list, click the drop-down menu in the Permissions column to set the access level.
5 To set the object permissions to their defaults, click Apply Defaults.

For more information, see Defining default permissions on page 59.


6 Click OK to close the Permissions dialog box. 7 To configure hierarchical group access to the object, set the object permissions

property Static Permissions Inheritance to True, as shown in Figure 1-16.


8 Choose File > Save to save the permission changes. Figure 1-16: Setting object permissions inheritance

To assign permissions for one or more fields


1 In BMC Remedy Developer Studio, open the form for modification. 2 Select the fields. 3 In the Properties tab, click the Permissions property and click the ellipsis button. 4 In the Permissions dialog box, use the arrow buttons to move the appropriate

groups and roles into the Permissions list. All groups defined on the server (or roles defined for the application that contains the object) are displayed. The Submitter, Assignee, and Assignee Group groups are implicit based on field contents. For more information about implicit groups, see Controlling access by using implicit groupsRow-level security on page 38. To allow all users to view or change a field, add the Public group to the Permission list.
5 For object that have different access levels, for each group or role in the

Permissions list, click the drop-down menu in the Permissions column to set the access level.
6 To set the object permissions to their defaults, click Apply Defaults.

For more information, see Defining default permissions on page 59.


7 Click OK to close the Permissions dialog box.

Chapter 1

Defining access control

63

BMC Remedy Action Request System 7.6.04

8 Set the Allow Any User to Submit property.

Use this mode to determine access control (security settings) for the field when a request is submitted. If the check box is: YesAny user can assign a value to the field, regardless of whether the submitter belongs to a group with Change permission to the field. No (the default)Only users who belong to a group with Change permission to the field can enter data into the field.
9 Choose File > Save to save the permission changes.

To assign permissions for a group to multiple objects


1 In BMC Remedy Developer Studio, open the Groups object list. (Double-click on

Groups in the AR System Navigator.)


2 Right-click the appropriate group, and select Assign Permissions. 3 In the Assign Group Permissions dialog box, select Fields or the appropriate object

type. If you select Fields, click the ellipsis button and select a form. Only forms that are not in deployable application are available.
4 To remove permissions to objects or fields in the list, click Remove All or select

objects and click Remove.


5 To assign permissions to other objects or fields, click Add. 6 In the Selector dialog box, select the objects or fields in the list, and click OK to

assign permission for the group to those objects.


7 For object that have different access levels, in the Assign Group Permissions dialog

box, for each object in the list, click the drop-down menu in the Permissions column to set the access level.
8 To assign permission for this group to other object types, return to step 3. 9 Click OK to save the permission changes.

NOTE
To assign common permissions to a collection of objects, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Modifying object properties, page 51.

64

Form and Application Objects Guide

Assigning permissions

Checking object visibility for the Public group


When you log in as a member of the Administrator group, you have access to all objects by default. When other users view the object list and the home page, they see only those forms, entry points, and applications for which they have Visible permission. Administrators can select a setting that limits their view of the object list and the home page to only those objects for which the Public group has Visible access. (Subadministrators can use this setting to manipulate the visibility of only those forms to which they have access as a subadministrator.) This allows you to quickly double-check which forms, entry points, and applications have Visible permission assigned to Public. For non-administrators, this setting has no effect; objects are displayed in the list according to the users group permissions.

To check the visibility of objects for Public in BMC Remedy User


1 Log in to BMC Remedy User as an administrator or subadministrator. 2 Choose Tools > Options. 3 Click the Advanced tab. Figure 1-17: Options dialog boxAdvanced tab

Chapter 1

Defining access control

65

BMC Remedy Action Request System 7.6.04

4 Select or clear the Display Hidden Forms (Admin Only) check box.

If the check box is: Selected (the default)All forms are displayed in the object list and all entry points appear on the home page for the administrator in BMC Remedy User. ClearedOnly those forms and entry points for which the Public group has Visible access are displayed to the administrator in BMC Remedy User.
5 Click OK.

For more information, see Form, active link guide, and application permissions on page 31. If you have configured AR System to make the object list available in a browser, use the following procedure to control whether hidden forms, entry points, and applications appear for administrators and subadministrators. For information about displaying the object list in a browser, see the BMC Remedy Mid Tier Guide.

To check the visibility of objects for Public in a browser


1 Open the object list by entering this URL in a browser: http://webServerName/arsys/forms 2 Select or deselect the Show Hidden Forms check box.

Subadministrators in AR System
Administratorsmembers of the Administrators groupcan use BMC Remedy Developer Studio to view every AR System server object and can modify any object that is not reserved by another user. (See Chapter 2, Using version control.) You can use Subadministrator Permissions to grant administrator access to a subset of existing forms, local applications, and workflow to subadministratorsmembers of the Sub Administrator group. A subadministrator with administrator access to a server object can use BMC Remedy Developer Studio to view and modify it the same as an administrator. A subadministrator can also create objects. Figure 1-18 is an example of using Subadministrator Permission to enable users to maintain some objects on an AR System server.

66

Form and Application Objects Guide

Subadministrators in AR System

Figure 1-18: Users administering forms

Administrator

Engineering Support Services application

Sales application

Bug Tracking form

Enhancements form

Sales Lead form

Contact Info form

Subadministrator for Engineering

Subadministrator for Sales

Rights for subadministrators


Subadministrators can perform the following functions: Log on to BMC Remedy Developer Studio. When you log in to BMC Remedy Developer Studio as a Subadministrator, the server icon in AR System Navigator has a yellow badge with a letter S instead of a green badge with a letter A. Create local applications, forms, and packing lists.

NOTE
When you create an object as a subadministrator, make sure to set the Subadministrator Permissions so you can access the object. Modify local applications, forms, and packing lists to which they have administrator access. Create and modify filters, active links, and escalations associated with forms to which they have administrator access. Create and modify active link guides, filter guides, images, and menus.

Chapter 1

Defining access control

67

BMC Remedy Action Request System 7.6.04

Subadministrators cannot perform the following functions: Modify local applications, forms, and packing lists to which they have no administrator access. View or modify forms to which they do not have subadministrator access in local application or packing lists to which they do have administrator access. If a user has subadministrator access to a local application or a packing list, but not to a form in the local application or packing list, the form is not listed in the object list or editor. Create or access deployable applications. View or modify roles, distributed mappings, or distributed pools. Change server information settings. Release licenses of users currently accessing AR System.

To make a user a subadministrator:


1 Include the Sub Administrator group in the Group list in the User form entry for

every user who is to be a subadministrator. A member of the Sub Administrator group must have a fixed license.
2 Give a group, of which the user is a member, administrative access to the

appropriate local applications, forms, and guides. For more information, see Defining subadministrator permissions on page 68. To give all members of the Subadministrator group administrator access to an object, give the Public group Subadministrator permission. To divide administrator access between groups, as Figure 1-18 on page 67 shows, create a group for each collection of objects, for example, Engineering Subadministrators and Sales Subadministrators.

NOTE
To give subadministrators access to an AR System server that has object reservation enforced, you must grant them access to a form. See Chapter 2, Using version control.

Defining subadministrator permissions


The following procedures explain how to define additional administrator permissions, such as granting subadministrator permissions to users, defining subadministrator permissions for forms and applications, and changing the visibility of forms for administrators. After you have granted a group subadministrator permissions for an application, the members of that group can modify the applications appearance, group permissions, help text, and change history. Subadministrators can also change which forms are included in an application object, although they cannot alter the forms themselves unless they have administrator access to them. For more information, see Subadministrators in AR System on page 66.
68 Form and Application Objects Guide

Subadministrators in AR System

To grant subadministrator capabilities to a user


1 In BMC Remedy User or the mid tier, open the User form of the appropriate server

in Search mode.
2 Perform a search to find the user you want to give administrator access to. 3 Make the following changes:

From the Group list menu, select Sub Administrator. The list must include the Sub Administrator group to give the user the potential to be a subadministrator. From the License Type option list, select Fixed. You must assign subadministrators a Fixed Write license.
4 Save your changes. 5 Give subadministrator permission for the form to a group or role to which the

subadministrator belongs, as described in the following procedure.

To assign subadministrator permissions to forms, local applications, and packing lists


1 In BMC Remedy Developer Studio, open the appropriate form, local application,

or packing list for modification.


2 Access the Subadministrator Permissions:

For a form, choose Form > Form Properties, and in the Form Properties dialog box, select the Subadministrator Permissions page. For a local application or a packing list, in the Properties tab, click the Subadministrator Permissions property and then the ellipses button.
3 In the Subadministrator Permissions page or dialog box, use the arrow buttons to

move the appropriate groups into the Permissions list. When assigning permissions for an application, you must assign the same permission as are assigned for the individual forms in the application.
4 Click OK to close the dialog box and save the changes.

The members of the group or role have the same privileges and permissions that an administrator has for that object.

Chapter 1

Defining access control

69

BMC Remedy Action Request System 7.6.04

70

Form and Application Objects Guide

Chapter

Using version control

This section describes how to use version control to prevent BMC Remedy Developer Studio users from overwriting other users work and to log changes to server objects. The following topics are provided: About version control in AR System (page 72) Using object reservation (page 74) Using the object modification log (page 76)

Chapter 2 Using version control

71

BMC Remedy Action Request System 7.6.04

About version control in AR System


Version control provides two independent functions: Object reservationUsers can reserve server objects. AR System prevents other users from modifying reserved objects. Object modification logWhen users change an object, AR System automatically logs the change. It can also export the objects definition file when the changes are saved. To restore the object to the saved state after making additional changes, users can import the object definition file. Version control applies to the following AR System objects: Active links Active link guides Applications Escalations Filters Filter guides Forms Images Menus Packing lists Web services (tracked as container objects in the object modification log)

About object reservation


AR System object reservation supports team development of applications by enabling one developer to prevent other developers from modifying objects. Object reservation permits you to perform these actions: Reserve an object for your exclusive use. See who has reserved objects. Release a reserved object so others can modify it. Open an object reserved by someone else in Read mode and view it. Save a copy of an object reserved by someone else. (You cannot save a copy of a deployable application, however, because a form cannot belong to more than one deployable application.) Add an object to a guide, packing list, local application, or working list, or export an object whether or not it is reserved.

72

Form and Application Objects Guide

About version control in AR System

Object reservation prevents you from performing these actions: Import, modify, or delete an object reserved by someone else. Delete a form if a workflow object reserved by someone else is related to it. Delete a form joined to a form reserved by someone else (through any number of joins). Add a form reserved by someone else to a deployable application. Add a form to a deployable application reserved by someone else. If you are prevented from taking an action because an objects is reserved by someone else, you can find the user who reserved it. See To list all reserved objects on page 75.

TIP
Use individual AR System users with object modification. Do not share users. If the same user is connected to the same server in two different BMC Remedy Developer Studio sessions, object reservation does not prevent simultaneous modification of objects. The AR System Version Control: Object Reservation form stores the object reservations. See Appendix C, Special forms. For information about enabling and using object reservation, see Using object reservation on page 74.

About the object modification log


When the object modification log is enabled, the AR System server automatically logs every change to the object types listed in About version control in AR System on page 72. Optionally, it also exports an objects definition file when the object is created or modified. You can use the object modification log to find a previous version of an object and restore it. This enables you to Recover from errors such as deleted objects or bad changes to objects. Undo changes to objects when they do not work. The AR System Version Control: Object Modification Log form contains the log entries. See Appendix C, Special forms. For information about enabling and using the object modification log, see Using the object modification log on page 76.

Chapter 2 Using version control

73

BMC Remedy Action Request System 7.6.04

Object reservation and object modification for overlays and origin objects
AR System allows you to reserve and modify origin and overlay objects independent of each other. When you modify the properties on an origin form that are inherited by its overlay, the operation updates the overlay object too. However, when modifying such properties on the origin form, you do not need to reserve its overlay. AR System uses the Overlay Group and Resolved Name fields on the following forms to manage object reservation and object modification: AR System Version Control: Object Reservation AR System Version Control: Object Modification Log The AR System server populates these fields, while AR System clients use real names for object reservation and object modification. For information about overlay objects, see Customizing objects on page 119.

Using object reservation


When developing an application with others, you need to prevent them from overwriting your object changes. To do this, use object reservation. For example, before starting a development task, reserve the objects you plan to change. After completing and testing the changes, release the objects so others can work on them.

To enable object reservation


1 On the Version Control tab of the AR System Administration: Server Information

form, set Object Reservation to Enforced. See the Configuration Guide, Server InformationVersion Control tab, page 165.
2 Click OK.

To reserve objects in a list


1 Open an object list that includes the objects to reserve. 2 Select the objects. 3 Right-click and choose Reserve from the pop-up menu.

The objects are reserved. Your user name appears in the Reserved By column of the object list.

To reserve an object as you work


1 Open an object that you have not reserved.

It opens in Read mode, as shown in the status bar.


2 Change the object.

74

Form and Application Objects Guide

Using object reservation

3 If no one has reserved the object, click OK in the confirmation message.

The object is reserved in Write mode.

NOTE
If you click Cancel or if the object is reserved by someone else, the object remains in Read mode. Any changes you make to it are not saved. To save changes, choose File > Save As, and save a copy of the object.
4 When you finish working on the object, release it.

To reserve a form and all related objects


1 Create a View-by-Form list containing the form and all related objects.

See the Introduction to Application Development with BMC Remedy Developer Studio guide, Creating working lists, page 61.
2 Open the list, and switch the list to single-list layout. 3 Select the first object in the list, and press Shift+End to select all objects in the list. 4 Right-click the objects, and choose Reserve from the pop-up menu.

To find reserved objects in a list


Click the Reserved By column header to sort the list. All reserved objects appear at the top of the list. Use the filtering options to display objects where Reserved By does not equal "". Only reserved objects appear in the filtered list.

NOTE
By default, object lists in object selector dialog boxes also contain a Reserved By column.

To list all reserved objects


In AR System Navigator, expand serverName > Working Lists, and open Reserved Objects. This special list includes all objects reserved by any user. If you logged in as a subadministrator, only the objects reserved by you are listed.

To release objects
1 Open an object list that includes the objects to release. 2 Select the objects. 3 Right-click the objects, and choose Release.

The object reservations are removed. The Reserved By column in the object list is cleared. Other users can change or reserve the objects.

Chapter 2 Using version control

75

BMC Remedy Action Request System 7.6.04

Using the object modification log


The object modification log records object changes and, optionally, saves the definition file of each version of an object. This enables you to do the following: Track who changed an object, what change they made, and when they made it. Restore a previous version of an object.

To enable the object modification log


1 On the Version Control tab of the AR System Administration: Server Information

form, set the following options: Set Object Modification Log to Enabled. (Optional) Set Save Definition Files to Yes. See the Configuration Guide, Server InformationVersion Control tab, page 165.

IMPORTANT
To restore previous versions of an object, you must configure the object modification log to save object definition files. For information about restoring previous versions, see To restore a previous version of an object on page 78.
2 Click OK.

When the object modification log is enabled, the AR System server adds an entry to the AR System Version Control: Object Modification Log form every time anyone creates, modifies, or deletes an object in BMC Remedy Developer Studio or by importing. The server adds the entry when it makes the change. The entry includes the following information:
Table 2-1: Fields in object modification log entries Field Object Name Obj Old Name Object Type Operation User Modified Date Comments Description Name of the new, changed, or deleted object. Previous name of the object if the change is renaming the object. Type of changed object: form, active link, escalation, filter, menu, image, or container (application, guide, or packing list). Create, Delete, or Modify. User who made the change. Time stamp of the change. Text from the New Description property of the object.

76

Form and Application Objects Guide

Using the object modification log

Table 2-1: Fields in object modification log entries Field Def Description Attachment field containing a .def file saved by the server after the change. The syntax of a .def file name is as follows: objectName.objectTypeNumber.instanceNumber.def The objectTypeNumber represents the following object types: 1Form, field, or view 3Filter 4Active link 6Character menu 7Escalation 10Container 12Image If an object name contains any of the following characters, the characters are converted to the following strings in the .def file name: Asterisk ( * ) is converted to _AST_ Colon ( : ) is converted to _CLN_ Greater than sign ( > ) is converted to _GT_ Less than sign ( < ) is converted to _LT_ Pipe ( | ) is converted to _PIP_ For example, the form name Sample:Cities becomes Sample_CLN_Cities in the .def file name. This field does not contain a .def file in the following situations: The Save Definition Files option is set to No (see step 1). The object was deleted. Instance API ID API Target Label An integer, starting at one, that specifies the version of the object. An identifier that is the same for all log entries resulting from the same API call to the AR System server. A flag indicating whether the object was referenced by the API call (Yes) or is related to a referenced object (No). Reserved for future development.
Note: This field is not associated with version control labels (see

Labeling a collection of objects on page 78). Task ID Reserved for future development.

A single change in BMC Remedy Developer Studio can produce many changes on the AR System server and many log entries. For example, when you modify a form, several entries are created in the AR System Version Control: Object Modification Log form: An entry for the form An entry for the form view An entry for any fields that were changed

Chapter 2 Using version control

77

BMC Remedy Action Request System 7.6.04

To restore a previous version of an object


If the object modification log is not configured to save definition files, you cannot perform this procedure. See To enable the object modification log on page 76.
1 In a browser or BMC Remedy User, log in to AR System as an administrator. 2 Open the AR System Version Control: Object Modification Log form in Search

mode.
3 Specify the appropriate search criteria. 4 Perform the search. 5 Find the log entry in the search results. 6 Save the .def file from the entry to your computer and import it.

Labeling a collection of objects


To identify and retrieve a collection of versioned objects, you can apply version control labels to any object listed in the object modification log. For example, you might apply a Patch 003 label to objects used in the final build for that patch. You can then retrieve a list of those objects and, using information provided in the list, download the definition file for each of the objects in the patch.

Adding version control labels to objects


You can add version control labels to any object listed in the object modification log (the AR System Version Control: Object Modification Log form).

IMPORTANT
If an object does not have at least one entry in the AR System Version Control: Object Modification Log form, you cannot add a version control label to it. You can add version control labels only to the current version of the object. You cannot add them to previous versions, even if those versions are listed in the log. Each version of an object can have multiple version control labels. Each version control label can be added to multiple objects.

78

Form and Application Objects Guide

Using the object modification log

Label name limitations


If you use the following characters in a version control label name, the search results for the label might be inaccurate.
& * @ ampersand asterisk at sign ! ` > < # % . exclamation point grave accent greater than sign hyphen less than sign number sign percent period + ; ? / ~ _ plus sign semicolon single quotation mark question mark quotation mark slash mark tilde underscore

{ } braces [ ] brackets ^ : $ = caret colon dollar sign equal sign

( ) parentheses

To enable version control labeling


1 On the Version Control tab of the AR System Administration: Server Information

form, set the following options: Set Object Modification Log to Enabled. Set Save Definition Files to Yes. See the Configuration Guide, Server InformationVersion Control tab, page 165.
2 Click OK.

To add a version control label to a new object


When you save an object for the first time, enter a version control label name and, optionally, a label description in the Save objectType As dialog box:

To use an existing label, select it from the Version Control Label list.

NOTE
The Version Control Label and Label Description fields are also available when you perform the following operations: Rename, Edit > Rename (available only when multiple objects are selected), Save As, and Delete.

Chapter 2 Using version control

79

BMC Remedy Action Request System 7.6.04

To add a version control label to one or more existing objects


1 In BMC Remedy Developer Studio, open the appropriate object list. 2 Select one or more objects. 3 Right-click one of the selected objects, and choose Add Version Control Label. 4 In the Add Version Control Label dialog box, enter the label name in the Version

Control Label field. The name can have up to 254 characters. It must be unique on the server.
5 (Optional) In the Label Description field, enter a description that explains why

objects are grouped under this label. For example, they might be part of a particular product build.
6 Click OK. 7 Click OK in the confirmation message.

To add a version control label to all objects on a server


1 In BMC Remedy Developer Studio, right-click the appropriate server in the

AR System Navigator, and choose Add Version Control Label.


2 In the Add Version Control Label dialog box, enter the label name in the Version

Control Label field. The name can have up to 254 characters. It must be unique on the server.
3 (Optional) In the Label Description field, enter a description that explains why

objects are grouped under this label. For example, they might be part of a particular product build.
4 Click OK. 5 Click OK in the warning message.

WARNING
If an object on the server does not have at least one entry in the AR System Version Control: Object Modification Log form, a version control label is not added to it.

80

Form and Application Objects Guide

Using the object modification log

To add a version control label to all objects imported in a definition file


During the import process, enter a label name and, optionally, a label description in the Import File page of the Import wizard:

To use an existing label, select it from the Version Control Label list. For more information about importing definition files, see Appendix G, Importing and exporting object definitions and locking objects.

Finding objects with a specified version control label


To retrieve a list of all the objects that have a specified version control label, follow this procedure.

To find objects with a specified version control label


1 In BMC Remedy Developer Studio, choose Search > Search. 2 On the Label Search tab, enter the search criteria.

The search is not case sensitive.


3 Click OK.

The search results appear in the Label Search Results tab at the bottom of the editing pane. For example, a search for the version control label build returned two labels, Build 001 and Build 002:

Chapter 2 Using version control

81

BMC Remedy Action Request System 7.6.04

4 In the Label Search Results tab, click a label to display the objects that have that

label. For example, in the preceding figure, all the objects that have the Build 002 label are listed in the top panel.

Exporting .def files for labeled objects


From the Label Search Results tab in BMC Remedy Developer Studio, you can export object definition (.def) files for a group of objects that have the same label or for a single labeled object.

NOTE
If no definition files are exported when you perform these procedures, verify that the Save Definition Files option in the Version Control tab on the AR System Administration: Server Information form is selected. See the Configuration Guide, Server InformationVersion Control tab, page 165.

To export .def files for a group of labeled objects


1 In BMC Remedy Developer Studio, search for the appropriate label.

See Finding objects with a specified version control label on page 81.
2 In the Label Search Results, right-click the appropriate label, and choose Export All

Objects.
3 In the confirmation message, click Yes. 4 In the Save As dialog box, navigate to the appropriate folder, and click Save.

The .def files of all the objects listed under that label in the label search results are exported to the selected location.

To export a .def file for a single object


1 In BMC Remedy Developer Studio, search for the appropriate label.

See Finding objects with a specified version control label on page 81.
2 In the Label Search Results tab, expand the list of objects associated with the label. 3 In the expanded list, select one or more objects. 4 Right-click the selected objects, and choose Export Selected Objects. 5 In the Save As dialog box, navigate to the appropriate folder, and click Save.

The .def file of the selected objects are exported to the specified location. For information about downloading individual object .def files from the object modification log, see To restore a previous version of an object on page 78.

82

Form and Application Objects Guide

Using the object modification log

Modifying version control labels


To modify a version control label, follow this procedure.

To modify a version control label


1 Conduct a search that returns the appropriate label.

See To find objects with a specified version control label on page 81.
2 In the Label Search Results tab, right-click the label to modify, and choose Edit. 3 In the Edit Version Control Label dialog box, revise the label name, label

description, or both.
4 Click OK.

The revisions are displayed in the Label Search Results tab.

Removing version control labels


These procedures explain how to remove a version control label from all the objects on a server and from a specified object.

To remove a version control label from all objects on a server


1 Conduct a search that returns the appropriate label.

See To find objects with a specified version control label on page 81.
2 In the Label Search Results tab, right-click the label to modify, and choose Delete. 3 In the confirmation message, click Yes.

The label is removed from the Label Search Results tab and from all objects to which it was assigned on the specified server.

To remove a version control label from a specified object


1 Conduct a search that returns the appropriate label.

See To find objects with a specified version control label on page 81.
2 In the Label Search Results tab, expand the list of objects associated with the label. 3 In the expanded list, select one or more objects. 4 Right-click the selected objects, and choose Remove Object. 5 In the confirmation message, click Yes.

The label is removed from the selected objects, and the objects are removed from the labels list of objects in the Label Search Results tab.

Chapter 2 Using version control

83

BMC Remedy Action Request System 7.6.04

84

Form and Application Objects Guide

Chapter

Defining applications

This section describes application objects and explains how to work with them. The following topics are provided: Deployable applications in AR System (page 86) Building deployable applications (page 91) Alternatives for presenting applications to users (page 103) Exporting and importing deployable applications (page 108) Deleting applications (page 117) Local applications (page 117) For information about determining your application needs and working with BMC Remedy Developer Studio, see the Introduction to Application Development with BMC Remedy Developer Studio guide. For specific information about creating and managing web applications, see the BMC Remedy Mid Tier Guide, Working with applications that will be viewed in a browser, page 65.

Chapter 3 Defining applications

85

BMC Remedy Action Request System 7.6.04

Deployable applications in AR System


An AR System application is a container object that contains a related set of forms, workflow objects, and other information designed and packaged together to allow users to accomplish a task. When you create an application, you define it as a local application or a deployable application. A local application is the original AR System application type and is most appropriate when the application is intended for use on the same AR System server where it is developed. For information about working with local applications, see Local applications on page 117. A deployable application includes functionality that makes it easier to develop and maintain the application in a development environment, test it in a test environment, and then deploy it to any number of production servers for end user access.

Features of deployable applications


Deployable applications include these features: The deployable application automatically owns or controls all forms that are in the application, as well as any workflow that has one of the included forms as its primary form. A form can be in only one deployable application, but workflow can be used to integrate two deployable applications. All the components of the application, including forms, workflow objects, roles, data, and other information owned by the application, are automatically exported together from the development server and imported together to a test or production server. Access control in a deployable application is determined by roles and implicit groups. Roles are mapped to explicit groups, and the roles travel with the application. You can therefore assign permissions to roles at development time, and then map the roles to groups specific to the local server when the application is deployed. Access to the application is further determined by the application state, which can be set to maintenance, test, production, or a custom value. You define different access control roles and groups for the development (maintenance), testing, and production phases. You can set default permissions for the application. Once defined, default permissions are assigned to objects and fields as you create them in the application. A deployable application can own data, and the data can be exported and imported along with the application definitions. A deployable application can have access points. An access point is an indication to other developers to show which forms and active link guides in your application are designed to be used as integration points with the application.
86 Form and Application Objects Guide

Deployable applications in AR System

A deployable application can be licensed. You might use application licensing together with object locking, which prevents objects from being modified in BMC Remedy Developer Studio. For more information, see Locking objects on page 571 and the Integration Guide, Making applications licensable for integration system vendors, page 323 A deployable application can be configured to track server statistics within the application only. You can collect performance information such as how many times an application is accessed in a given period of time. You can collect similar statistics on individual forms. For more information, see the Optimizing and Troubleshooting Guide, Gathering baseline information, page 14.

Shared workflow in deployable applications


Depending on the design, a deployable application can function as a complete application in and of itself, or a related set of deployable applications can act as modules that are part of a larger application. In either case, you might need to use shared workflow to integrate two deployable applications. When a deployable application is used as a module in a larger application, or otherwise interacts with another deployable application, some of the workflow components that the application owns are also associated with forms owned by other deployable applications. Such workflow components are shared workflow that integrates the two application modules or applications. For example, a filter might gather data from its primary form in one application module, and push it to another form owned by another application module. The filter is owned by the application that contains the primary form, and integrates with the application that contains the other form. As of release 7.6.02, you can configure the AR System server to maintain the full list of forms used by shared workflow components, even if those forms belong to other deployable applications and do not exist on the destination server. You can also set the Integration Workflow property on shared workflow components to identify a second deployable application that shares the workflow. This allows you to export only the shared workflow objects for two related deployable applications. See Exporting and importing shared workflow and integrated applications on page 109. These features make it easier to implement concurrent development in your organization, using different development servers, and maintain full functionality when application modules are brought back together in the larger application.

Chapter 3 Defining applications

87

BMC Remedy Action Request System 7.6.04

Contents of deployable applications


A deployable application contains all the information needed to deploy the application on another AR System server, including the forms and workflow, the roles associated with the application, and other data such as form data or help contents that you add to the application.

Objects in deployable applications


When you add a form to a deployable application, the form is owned by that application. A form can be in only one deployable application, and when a form is in an application, all AR System objects related to the form are also in the application. The objects that are included in an application by means of association with an included form are: Active links, active link guides, escalations, filters, and filter guides for which the form is an associated form. Images, flashboards, and menus referenced by fields in the form. Flashboard variables referenced by flashboards in the application. Flashboard alarms that reference flashboard variables in the application. Web services for which the form is the associated form. You can also add a packing list to an application, but the objects in the packing list are not necessarily part of the application. See Chapter 15, Defining packing lists. To see all the objects that are included in the application, open the application from the Applications branch in BMC Remedy Developer Studio. An expandable panel appears for each object type included in the application. For example, Figure 3-1 shows the object list for the Sample application, with the Active Link Guides panel expanded to show the list of included active link guides. Expand the panel for each object type to see the list of objects included in the application.

88

Form and Application Objects Guide

Deployable applications in AR System

Figure 3-1: The Sample application object list in BMC Remedy Developer Studio

When you edit an object owned by a deployable application, the server and application names are shown in the object label in the editor as illustrated by Figure 3-2.
Figure 3-2: The Sample:Cities form which is owned by the Sample application

Other contents of deployable applications


In addition to the server objects it contains, a deployable application also includes the following related information: RolesAll roles that are used to define access control for forms, fields, active links, and active link guides in the application are part of the application. DataAn application can use requests to represent business rules or other required data. You specify the forms that contain the data. You can also define qualifications that select the data to include. Support filesAn application can use external files, for example, files referenced by file menus or other data files. Image filesYou can specify image files that the AR System server uses as the application icon and About box. Help filesYou can create an external help file and link it to the application.
Chapter 3 Defining applications 89

BMC Remedy Action Request System 7.6.04

Access control for deployable applications


You use only roles and implicit groups to grant permission to objects in a deployable application. Because you map each role to an explicit group and the AR System server uses the role mappings to determine access, the groups on servers where the application is deployed do not need to be the same as those on the development server. The server also uses the application state to determine the group currently mapped to a role. By mapping different groups to a role for different states, you control access to the application based on its current state. For example, when the application is in the Test state, only users in the mapped testing group can access the application. When you change the application state to Production, users in the group mapped to the role for the Production state gain access. For more information, see Working with deployable application states on page 97. When a user attempts to reference a form, field, active link, active link guide, or web service, the AR System server uses the application state and the role mappings of the controlling application to determine access. When a form is in a deployable application, that application controls the form. The application also controls the fields in the form, and any active links, active link guides, and web services for which the form is the primary form. When working with a deployable application, keep the following points in mind regarding the controlling application: If a form or active link guide is an entry point, it appears under its controlling application on the home page. A user who does not have access to an application has limited access to the applications entry points. See Chapter 14, Defining entry points and home pages. If an active link or active link guide in a deployable application is shared outside of its controlling application, access to the active link or active link guide is determined by the role mappings and state of the controlling application. In this case the developer must coordinate the roles of the controlling application with those of the integrated application to ensure that the workflow is accessible and operates as expected. If you delete the primary form of an active link or active link guide, one of the other associated forms becomes the primary form. If the new primary form is in a different deployable application, the controlling application of the workflow object changes, and the role permissions are those of the new controlling application. Flashboards and flashboard variables function as global objects. They can be in a deployable application, but they are not controlled by the application. You must grant permissions to these objects using groups and not roles.

90

Form and Application Objects Guide

Building deployable applications

Granting permission to applications and their objects


You must grant or deny access to the deployable application itself, and to each form, field, and active link, and active link guide in the application. The objects in an application do not inherit the access you grant to the application itself. Likewise, if you deny access to an application, access is not denied to the objects within the application. You can configure default permissions for the application before creating the application object to simplify permissions assignment and ensure consistency within the application. See Defining default permissions on page 59. When you add a form to a deployable application, all explicit groups are removed from its permissions and from the permissions of its fields and all active links and active link guides that have the form as an associated form. If the application has default permissions, those are added. You can grant permissions to roles and implicit groups, as described in Assigning permissions on page 58, to these objects and fields as needed.

NOTE
Default role permissions are not applied to forms in deployable applications. You must apply the role permissions to each form. When you remove a form from a deployable application, all roles are removed from the forms permissions, from the permissions of its fields, and from all active links and active link guides associated with the form.

Building deployable applications


In BMC Remedy Developer Studio, each application appears as a entry in the AR System Navigator Applications branch, as shown in Figure 3-3. Use this location to open and work in the application, including such tasks as adding forms and workflow to the application, exporting the application, and opening the application object for editing.
Figure 3-3: Applications branch with Home Page application opened

Chapter 3 Defining applications

91

BMC Remedy Action Request System 7.6.04

Because an application is itself an AR System server object, an Applications node appears in the All Objects branch of the AR System Navigator, as shown in Figure 3-4. You can also open an application for editing from this location.
Figure 3-4: Applications node in server object list with Home page application opened

The following steps describe one good approach to creating, defining, and deploying an application:
Step 1 Determine the forms required for the application user interface. Step 2 Determine the roles required to control access to the application and its

functionality. When you plan a deployable application, be sure to design the access control roles required by the application early in your work. With a clear idea of application roles, you can assign permissions to forms, fields, active links, and active link guides as you define them. With the roles defined, you can set default permissions that will be automatically applied to objects created in the application.
Step 3 Create the roles, test groups, and test users so you can test the forms and workflow

in the application as you define it. Map the roles to the test groups.
Step 4 Configure default permissions for the application. Step 5 Create the deployable application object and set its permissions.

92

Form and Application Objects Guide

Building deployable applications

Step 6 Create the objects in the deployable application:

Create the forms required for the application user interface. Create supporting forms, workflow, menus, images, and other supporting objects as required by the functionality of the forms you create. Define the permissions for the objects as you define the objects. Define data forms and criteria for data export and create the requests in these forms required by the functionality. Create external support files and add them to the application. Test the functionality as you create it using the test users. You can also create packing lists to organize groups of application objects during development.
Step 7 Define entry points to appear in application lists. Step 8 Optionally, define access points to indicate to developers where external workflow

should access the application.


Step 9 Define help text for the application or create external help files and add them to the

application.
Step 10 Optionally, configure the application or some of its forms to record statistics. See

the Optimizing and Troubleshooting Guide.


Step 11 Export the application, import it to a different AR System development or test

server, define the required groups, users, and role mappings, and test the application.
Step 12 After the application functionality and its deployment are tested successfully,

import the application to the production server, define the required groups, add the group to the Group List for the users, and define the role mappings and application state.

Creating a deployable application


Use the following procedure to create a deployable application object.

To create an application
1 In the AR System Navigator, expand the server branch where you want to create

the application.

2 Right-click Applications and choose New Application. 3 In the New Application dialog box, select Deployable Application, and click

Finish.

4 In the Properties tab, define the Permissions for the application object.

Chapter 3 Defining applications

93

BMC Remedy Action Request System 7.6.04

5 Choose File > Save. 6 In the Save Application As dialog box, enter the application name and click OK.

The name must be unique among applications, active link guides, filter guides, packing lists, and web services on an AR System server. Names can be a maximum of 80 characters, including spaces. Names can include double-byte characters, but avoid a digit as the first character. The new application appears as node in the Applications branch of the server tree in the AR System Navigator.

NOTE
Subadministrators cannot create or view deployable application objects in BMC Remedy Developer Studio. They can view and modify objects in the application if they have administrative access to them.

Including objects in an application


You can create objects directly in an application, or you can add existing objects to the application.

Creating objects in the application


To create an object in an application, right-click the applications node in the AR System Navigator and choose the object type from the New Object pop-up menu as shown in Figure 3-5.
Figure 3-5: Adding a form to the New Hire application

94

Form and Application Objects Guide

Building deployable applications

The selected object type opens in the editor area and you can proceed with defining the object. When you save the object, it is added to the application. When you create an object in an application using this method, BMC Remedy Developer Studio behaves as follows: FormThe application controls the form. Workflow objectThe list of forms to associate with the workflow object is filtered to include only forms in the application. Web serviceThe list of forms to serve as the base form for the web service is filtered to include only forms in the application. Flashboard variableThe list of forms to serve as the data source for the flashboard variable is filtered to include only forms in the application. Packing listThe packing list is added to the application. PermissionsIf default permissions are defined for the application and object type, they are applied when you create each new object.

Adding existing objects to the application


You can use these methods to add existing objects to an application: Forms and packing listsThen open the application for editing and use the Add button to add an existing form or packing list to the application. See To add existing forms to an application and To add existing packing lists to an application on page 96. All other objectsAssociate the object with a form controlled by the application. Any object you create is in the application if it is associated with a form in the application. For example, if you create a menu and attach it to a field in a form in an application, the menu is in the application. When you add an existing form to an application, all of the objects associated with that form, such as workflow and menus, are also added to the application. Likewise, when you remove a form, all of the objects related to it are removed from the application. Removing a form from an application does not delete the form on the server. For more information, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Deleting objects, page 59.

NOTE
When you add an existing form to a deployable application, AR System removes all explicit group permissions from the form and its associated objects. However, it does not apply default permissions for the application. You must manually apply role permissions to every object, including the form and its fields, and to any active links and active link guides for which the form is the primary form.

Chapter 3 Defining applications

95

BMC Remedy Action Request System 7.6.04

To add existing forms to an application


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 In the application tab, expand the Forms panel. 3 Click Add. 4 In the Forms Selector dialog box, select the forms to add to the application, and

click OK. Only forms that are not in any application are shown. To filter the list of forms, type a pattern in the Name field. To move to a form in the list by name, type the first characters of the name in the Locate field. To set the view presented in the application, select it from the View drop-down list below the forms list. The forms you selected and all related objects are added to the application.
5 Chose File > Save to save the changes to the application.

To add existing packing lists to an application


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 In the application tab, expand the Packing Lists panel. 3 Click Add. 4 In the Packing List Selector dialog box, select the packing lists to add to the

application, and click OK. To filter the list of packing lists, type a pattern in the Name field. To move to a packing list in the list by name, type the first characters of the name in the Locate field. The packing lists you selected are added to the application. The forms and other objects in the packing lists are not added to the application.
5 Chose File > Save to save the changes to the application.

Dividing an application
You might need to divide the functionality in an application into two applications.

To divide an application
1 Create a new application and set its basic properties. Do not add or create any

forms.
2 Close the application tab and open the Applications branch of the AR System

Navigator.
3 Double-click the existing application to open its application object list, and then

expand the Forms panel.

96

Form and Application Objects Guide

Building deployable applications

4 Drag the forms to move to the new application from the application object list to

the new applications node in the AR System Navigator. The forms and all associated objects are moved from the existing application to the new application. When you decide to replace a local application with a deployable one, you can also use this procedure to move objects from the local application to a new deployable application.

NOTE
You cannot create copies of deployable applications using the Save As command because different deployable applications cannot contain the same forms.

Working with deployable application states


In deployable applications, role permissions resolve to different groups depending on the development state of the application, such as Maintenance, Test, or Production. By mapping roles to groups for the Test and Production states, you can assign permission for all the roles while creating the application. When you change the application state at test or production time, the permissions for the new state automatically take effect. When you create or import a deployable application, the state is set to Maintenance. Only administrators and subadministrators have access to the application in Maintenance state.

Specifying roles for deployable application states


You can change an applications state in the application tab in the editor area, in BMC Remedy User, or through workflow, as described in the following sections. You can also create custom states for use by all deployable applications on the server.

To specify deployable application states


1 Define role-group mappings for each state in the Roles form: a In BMC Remedy User, open the Roles form and search for all roles defined for

the application. If the search returns no roles, define roles for the application.
b For each role, make sure that the role is mapped to an explicit group for each

state.
c Save the roles.

For more information about roles, see Roles in AR System on page 28.
2 Specify the state for the application, as follows: 3 Open the application for modification as described in the Introduction to

Application Development with BMC Remedy Developer Studio guide, Working with applications and packing lists, page 64.
a In the application tab, expand the General panel. Chapter 3 Defining applications 97

BMC Remedy Action Request System 7.6.04

b Choose a state from the State list. c Choose File > Save.

The role-group mappings for the specified application state become effective after the server recaches.

Using the user client or workflow to change deployable application states


The state defined in application properties is stored in an entry for that application in the AR System Application State form. You can edit the entries in this form in the user client or create workflow that acts on this form to change the applications state. When creating the workflow, remember the following tips: A state value of NULL is the same as the Maintenance (administrators only) state. State names are case-sensitive. Entries are removed from the AR System Application State form when applications are deleted.

Creating custom states


You can create custom application states by adding fields to the Roles form. Use field IDs in the range of 2003 to 2199.

To create custom states


1 In BMC Remedy Developer Studio, open the Roles form. 2 Under the Production field, add a character field. 3 In the Properties tab, in the ID field, enter a unique field ID in the range from 2003

to 2199.
4 Save the form.

AR System automatically adds a menu to the field for selecting groups. The new state is available for deployable applications on the current server after the server recaches.
5 To make custom states available on another server, export the Roles form and

import it on the target server. For more information about exporting and importing forms, see Appendix G, Importing and exporting object definitions and locking objects.

98

Form and Application Objects Guide

Building deployable applications

Working with deployable application access points


Some deployable applications are designed to integrate with other deployable applications, such as when they are acting as modules of a larger overall application. You can define access points to indicate which forms, active link guides, or filter guides in your application are designed to be accessed by workflow that is not in the application. Access points are not enforced. Workflow running in an AR System server can access any forms or active link guides, subject only to access control. Also, the access points you create for an application are recommended points of integration only; developers can still choose to work with any objects on the server, including objects in your application. Access points are indicated in object lists in BMC Remedy Developer Studio to assist other developers who need to integrate another application with the deployable application. When creating table fields, join forms, and certain workflow actions (such as Set Fields or Call Guide actions), developers can choose to sort the list to find only those that are identified as access points in other applications. Use the following procedures to define access points for your application, and to take advantage of access points in other applications during development.

To define access points in a deployable application


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 In the application tab in the editor area, open the Access Points panel. 3 Click Add. 4 In the Object Selector, select the forms, active link guides, and filter guides to add

as access points to the application, and click OK.


5 Choose File > Save.

Using access points during development


To locate access points for other applications, use the Access Points column when selecting the form, active link guide, or filter guide. This procedure describes the specific steps for an example in which you want to add a secondary form to an active link. The secondary form is owned by another application and is defined as an access point. This example is illustrated in Figure 3-6.

Chapter 3 Defining applications

99

BMC Remedy Action Request System 7.6.04

Figure 3-6: Locating an external form marked as an access point

Example procedure: Add a form defined as an access point


1 In BMC Remedy Developer Studio, open the object for which you want to locate

an access point. In this case, the object is an active link that already has its primary form defined.
2 In the Associated Forms panel, click Add. 3 In the Form Selector dialog box, change the filter settings for Application to <All>. 4 Click the Access Points column heading to sort the list based on the access point

setting. Access points are labeled Yes in this column.


5 Select the correct form from the list.

Application attributes and properties


Except for the change history and permissions, which are set in the Properties tab, all application attributes are set in the application editor. Use the following procedure to define the attributes and properties of an application.

To define application attributes and properties


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 Expand one or more panels and modify attributes as needed.

The following sections describe the contents of each panel.


3 Modify permissions and other properties in the Properties tab. 4 Choose File > Save.

100

Form and Application Objects Guide

Building deployable applications

General panel
The primary properties in the General panel determine the application label and development state. The following sections describe these properties in detail. The following additional properties on this tab are for configuring applications for direct access in BMC Remedy User: Description Show Only Forms in Application Run with Form Windows Maximized Custom Title Bar Icon Custom About Box For more information about these properties, see Specifying General and Forms attributes for Application mode on page 104.

Label
For deployable applications, if a Label is specified, it is used in place of the application object name to identify the application corresponding to entry points in the home page. For more information about entry points and home pages, see Chapter 14, Defining entry points and home pages. The Label also has a specific meaning when an applications is accessed directly in Windows clients. For more information, see Alternatives for presenting applications to users on page 103.

State
This property defines the application state (Maintenance, Production, Test, or custom) and appears for deployable applications only. Depending on the state you choose, different access permissions are applied to the application. For more information, see Working with deployable application states on page 97.

Forms panel
The Forms panel determines the forms included in the application, as explained in Creating objects in the application on page 94 and Adding existing objects to the application on page 95. The following Forms properties apply only to applications that users do not access through entry points on a home page: Primary Form Primary View For more information about these properties, see Alternatives for presenting applications to users on page 103.

Chapter 3 Defining applications

101

BMC Remedy Action Request System 7.6.04

Packing Lists panel


For deployable applications only, this panel defines the packing lists to include in the application.

Support Files panel


The Support Files Panel is for web applications only. This panel defines the names and locations of resources used in web views that are included in the application object. For more information, see the BMC Remedy Mid Tier Guide, Managing resource files, page 74.

Access Points panel


For deployable applications only, this panel defines which forms, active link guides, and filter guides are integrated with other deployable applications. For more information, see Working with deployable application access points on page 99.

Data panel
For deployable applications only, this panel defines the forms whose data is included in an application export. It also defines the qualifications (if any) that select sets of records, and import options such as the handling of duplicate request IDs.

Statistics panel
For deployable applications only, this panel defines the forms that participate in statistics tracking for the application. For more information, see the Optimizing and Troubleshooting Guide, Gathering baseline information, page 14.

Help Text panel


The Help Text panel supplies help text about the application for administrators. It typically includes a description of the application, what it does, and how it is used. For general information about creating help text in AR System, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Providing help text, page 54. The Help properties also apply to applications configured for direct access in BMC Remedy User. For more information, see Specifying Help properties for Application mode on page 106.

102

Form and Application Objects Guide

Alternatives for presenting applications to users

Properties tab
Use the Permissions property in the Properties tab to determine which access control groups can display the application in the user client. For more information, see Access control for deployable applications on page 90. Use the Subadministrator Permissions property to define subadministrator permissions for access control groups. For more information, see Subadministrators in AR System on page 66. AR System automatically records the owner of an application, the developer who last modified the application, and the date of the modification. To display or add to this information, click the Change History property in the Properties tab. For general information about building and using change history, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Updating change history, page 53.

Alternatives for presenting applications to users


Users can open an application in several ways. The typical method to present an application to users is to define entry points that appear in a home page, as explained in Chapter 14, Defining entry points and home pages. For web applications, you can provide links to forms using special URLs, such as encoded URLs, URLs that bypass the login page, or URLs that pass search parameters when a search form is opened. Include the URLs on a web page or form. For more information, see the BMC Remedy Mid Tier Guide, URLs for forms and applications, page 76. You can configure Windows applications so that users open the applications within BMC Remedy User in Application mode. This technique works for both local and deployable applications, as explained in this section. In BMC Remedy User, users access an application in the Object List dialog box, locating the application by name or by a custom label that you provide. A description of the application (if defined) appears below the task list when the user selects the application, as shown in Figure 3-7.

Chapter 3 Defining applications

103

BMC Remedy Action Request System 7.6.04

Figure 3-7: Object List dialog box

Users can also open the application from an ARTask shortcut that you provide, as described in Distributing the application to users as a shortcut on page 108. To configure how an application opens and how a user can open it and use it, you must complete these general tasks: Define the application label, description, primary form, and primary form view. Define forms and guides in the application as entry points. Entry points are listed in home pages under the controlling application. Configure whether the user can access forms and guides that are not in the application and whether the form window opens maximized in BMC Remedy User.

Specifying General and Forms attributes for Application mode


Use the following procedures to specify General and Forms attributes for use in Application mode. For more information about Application mode, see Alternatives for presenting applications to users on page 103.

To specify General properties for an application


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 In the application tab, expand the General panel.

104

Form and Application Objects Guide

Alternatives for presenting applications to users

3 In the Label field, specify the label that you want to appear in the Object List dialog

box in BMC Remedy User, and in the title bar in Application mode. If you do not specify a label, the Name property is used to identify the application. Labels can be as long as 255 bytes, including spaces.
4 In the Description field, specify the description that you want to appear below the

task list in the Object List dialog box in BMC Remedy User. You can enter a maximum of 2000 bytes.
5 To specify a custom icon: a Select the Custom Title Bar Icon check box. b Click the Browse button and select the appropriate image file.

You can add an image in .bmp, .dib, .jpg, or .jpeg format that is as large as 16 pixels wide by 16 pixels high. An image larger than these dimensions is cropped. The image file size limit is 512 KB. Keep the file size as small as possible to avoid performance problems.
c To save the image to another area on the network, click Save To Disk. 6 To display an image in the About box: a Select the Custom About Box check box. b Click the Browse button to locate the appropriate image.

You can add an image in .bmp, .dib, .jpg, or .jpeg format that is as large as 16 pixels wide by 16 pixels high. An image larger than these dimensions is cropped. The image file size limit is 512 KB. Keep the file size as small as possible to avoid performance problems.
c To save the image to another area on the network, click Save To Disk. 7 Choose File > Save.

To specify the behavior of forms in Application mode


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 In the application tab, expand the Forms panel. 3 From the Primary Form list, select the form to appear in BMC Remedy User when

the application first opens. If you do not specify a primary form, no form appears when users open the application in BMC Remedy User.
4 From the Primary View list, select the view of the form to appear when the

application opens. The views available in the list are defined by the view label. If no view is selected, the default view or the user preference view is used.
5 Expand the General panel.

Chapter 3 Defining applications

105

BMC Remedy Action Request System 7.6.04

6 Select or clear the Show Only Forms in Application check box. If this check box is:

Selected, users can access only those forms and guides within the application. Cleared, users can access any forms, guides, or applications to which they have access regardless of whether they are related to the application.
7 Select or clear the Run With Form Windows Maximized check box. If this check

box is: Selected, the form window is maximized when it opens. Cleared, the form window opens with the size that the developer defines.
8 Choose File > Save.

Specifying Help properties for Application mode


You can create field-level help for users of your application, as explained in the Introduction to Application Development with BMC Remedy Developer Studio guide, Providing help text, page 54. For applications that run in Application mode, you can also provide help in the following ways: Using help text that opens from the Help menu in a system-generated dialog box. Use this method if the application does not require extensive help text. Using external help files that open from the Help menu in a supporting program such as a web browser or Adobe Reader. Use this method if the application is complex and requires detailed instructions. You can provide up to five external help files.

Specifying help text in a dialog box


Use the following procedure to specify help text that users can access by choosing Help > Help on applicationLabel or pressing F1 in BMC Remedy User.
Figure 3-8: Help text example

106

Form and Application Objects Guide

Alternatives for presenting applications to users

To specify help text in a dialog box


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 In the application tab, expand the Help Text panel. 3 From the Type drop-down list, select Help Text. 4 In the field, supply the help text that you want to appear. 5 Choose File > Save.

Specifying external help files


You can specify up to five different external help files for an application. Help formats that you can use include .htm, .html, .doc, .pdf, .txt, .hlp, or .chm files. Your users must be able to access the help file locally on their computers. For example, if your help file is a web page, users must have browsers installed. When users choose Help > Contents and Index (for a single help file) or Help > Help on applicationLabel (for multiple help files) in Application mode in BMC Remedy User, the help appears in the format that you specify. For example, if you created an HTML help system for your application, the users default browser opens, displaying the HTML help file.

To specify external help files


1 In BMC Remedy Developer Studio, right-click on the applications name in the

AR System Navigator, and choose Edit Application.


2 In the application tab, expand the Help Text panel. 3 From the Type drop-down list, select External Help Files. 4 Click Add. 5 In the Add External Help File dialog box: a In the Label field, enter a label for the help file. b Click the browse button next to the Help File field and select a file. c Click OK.

The Label and Help File name are added to the field changes to identify the help file that you have selected.
6 To test a help file, select it in the list and click Test. 7 To export a help file from an application, select it in the list and click Save to Disk. 8 Choose File > Save.

Chapter 3 Defining applications

107

BMC Remedy Action Request System 7.6.04

Distributing the application to users as a shortcut


You can send an application as an ARTask shortcut to your users, who can use the shortcut to start the application in BMC Remedy User. You can create the shortcut in BMC Remedy User.

NOTE
Creating a shortcut using the following procedure requires a MAPI-compliant email client.

To create an application shortcut in BMC Remedy User


1 In BMC Remedy User, open the Object List dialog box. 2 Right-click the application for which you want to create a shortcut. 3 Choose Create Shortcut to open the Save a Shortcut dialog box. 4 Specify a location, and click Save.

Exporting and importing deployable applications


To deploy, or copy, a deployable application to another AR System server for testing, additional development, or production, you export it from the current server and import it to the destination server using BMC Remedy Developer Studio.

Creating a deployable application definition file


When you export a deployable application, all objects and data necessary for the application to correctly install and execute on the target server are automatically written into a single definition file, sorted by type and object name. The resulting .def file serves as a server-independent archive of the application because it contains everything needed to install the application on a different AR System server. The definition file for a deployable application includes the following definitions: The application itself and its properties, including permissions. The forms and workflow objects included in the application. For information about including shared workflow, see Exporting and importing shared workflow and integrated applications on page 109. All menus referenced by the application. A menu is referenced by the application if a form in the application has a field that references the menu or if an active link in the application includes a Change Fields reference to the menu. All roles associated with the application. The group mappings for each role are not included, because these must be redefined for the groups that exist on the destination server.
108 Form and Application Objects Guide

Exporting and importing deployable applications

Any packing lists included in the application. Objects in the packing list are included only if they are also in the application. Data stored in AR System forms that are defined as data forms for the application. See Exporting and importing data with deployable applications on page 115. The application state is a server-specific setting. The application is automatically set to Maintenance state when you import it to the destination server. Therefore, custom application state definitions are not exported or deployed with the application.

WARNING
If the AR System server has Record Object Relationships enabled, the relationships are recorded as the application objects are created during import. If you import a large application or many object definitions, the server might become highly loaded and unresponsive for a period of time.

To export a deployable application


1 In the AR System Navigator area, right-click the application name in the

Applications list.
2 Select Export Application. 3 In the Application Selection dialog box, enter a path and file name for the definition file, for example, C:\AppExports\AppA.def 4 Export with default settings or configure additional settings:

To export the application with default settings, click Finish. To configure options for exporting shared workflow, integration workflow, or localized form views, click Next. To export include shared workflow or to export integration workflow only, see Exporting and importing shared workflow and integrated applications on page 109. To export an application with multiple localized views for import on deployment servers with different locales, see Exporting and importing deployable applications with localized views on page 113.

Exporting and importing shared workflow and integrated applications


Shared workflow is any workflow associated with forms both inside and outside the deployable application. When this is the case, the primary form determines the owner application for the workflow. When developing deployable applications as modules of a larger application, you might need to have developers working concurrently on separate development servers. In this situation, previous releases of AR System required you to export and import any shared workflow not owned by the application separately, or to install all related deployable applications on each development server.

Chapter 3 Defining applications

109

BMC Remedy Action Request System 7.6.04

Beginning with release 7.6.02, you can use the following features to help manage cross-server development of integrated deployable applications: Include Shared Workflow optionUse this option in the Export wizard in BMC Remedy Developer Studio to include shared workflow not controlled by the application in the application definition file. See Exporting shared workflow not owned by the application on page 110.
Create-Workflow-Placeholders configuration optionSet this option in the configuration file of the destination development server to allow the creation of placeholder forms for any external forms associated with shared workflow. See Importing shared workflow not owned by the application on page 111.

Workflow Integration property for workflow objectsSet this property to allow the Export wizard to export only the integration workflow for two deployable applications. In addition, when you import shared workflow that is owned by the application, the full list of associated forms, including those owned by another application, is now preserved.

Exporting shared workflow not owned by the application


Workflow that is in the application but not owned by the application is any workflow object whose primary form is in another application, but which is also associated with a form in the current application. For example, consider the deployable applications and objects described in the following table:
AppA FormA ActiveLinkA is associated with FormA its primary form AppB FormB ActiveLinkA is also associated with FormB (a secondary form)

In this example, AppA owns FormA and ActiveLinkA. Both objects will be exported with AppA by default because they are owned by it. AppB owns FormB but not ActiveLinkA. By default, ActiveLinkA is not exported with AppB, but by using the Include Shared Workflow option of the Export wizard, you can include ActiveLinkA when you export AppB.

110

Form and Application Objects Guide

Exporting and importing deployable applications

To include all shared workflow when exporting an application


1 In AR System Navigator, right-click the application to export in the Applications

list, and then select Export Application.


2 In the Application Selection dialog box, enter a path and file name for the

application definition file, and then click Next.


3 In the Export Options dialog box, select Entire Application and Include Shared

Workflow.
4 Click Finish.

The application is exported and any shared workflow not owned by the application is included in the definition file.

Importing shared workflow not owned by the application


When you import an application definition file that contains shared workflow not owned by the application, AR System can create a non-functional placeholder form for each external form associated with the shared workflow. This allows developers to modify the shared workflow owned by another application without installing the integrated application on the development server. It also ensures that the complete list of associated forms is preserved with any shared workflow. Placeholder forms are created during application import in these cases: The import definition contains shared workflow from another application that includes a Push Fields or Set Fields action. In this case, a placeholder is created for the external form used by the Push Fields or Set Fields action. The server configuration file (ar.cfg or ar.conf) contains the option Create-Workflow-Placeholders: T. In this case, a placeholder form is created for any external form associated with the shared workflow, regardless of the workflow action type. A placeholder form has no fields and can only be deleted. If the actual definition of a placeholder form is imported, it replaces the existing placeholder. In the Forms object list in BMC Remedy Developer Studio, placeholder forms are identified as form type None. When importing an application definition that contains shared workflow not owned by the application, the workflow object is created if it does not already exist. If the workflow object already exists, only the list of associated forms is updated. If the application that owns the shared workflow object is later imported, the workflow is replaced.

Chapter 3 Defining applications

111

BMC Remedy Action Request System 7.6.04

Defining and exporting integration workflow objects


When a workflow object integrates two deployable applications, for example, by using a Push Fields action to move data from a form in one deployable application to a form in the other, you can set the Integration Workflow: Application object property to mark the workflow object as integration workflow and indicate the integrated application. When this property is set, the Export wizard can locate all workflow objects that integrate two applications and export only those workflow objects to an object definition file.

To set the Workflow Integration property for a shared workflow object


1 Open the workflow object, such as an active link, for editing. 2 In the Properties view, expand the Integration Workflow category. 3 Click in the Value column for the Application property. 4 Select the integrated application from the drop-down list, as shown in Figure 3-9. Figure 3-9: Defining the Integration Workflow: Application property

To export workflow objects defined as integration workflow


1 In AR System Navigator, right-click the application name of the application that

owns the workflow.


2 Select Export Application. 3 In the Application Selection dialog box, enter a path and file name for the

definition file, and then click Next.


4 In the Export Options dialog box, click Select Application in the Export Integration

Workflows area.
5 Select the integrated application from the drop-down list, as shown in Figure 3-10. 6 Click Finish.

112

Form and Application Objects Guide

Exporting and importing deployable applications

Figure 3-10: Exporting integration workflow only

In this case, the definition file is an object definition file that contains definitions for only the integration workflow objects. To import the integration workflow, the integrated applications should already exist on the destination server. Use the Import > Object Definitions option to import the integration workflow objects.

Exporting and importing deployable applications with localized views


For deployable applications that include forms with localized views, you can create a deployable application definition file that contains only the default views, and then use the Export wizard to generate a view definition file that contains all the views in the application for a specified locale. This is helpful in cases where you need to deploy the application to servers with different locales.

To export the deployable application with default views only


1 Right-click the application name in the Applications list in AR System Navigator. 2 In the Application Selection page of the Export wizard, enter a path and file name

for the application definition file, and then click Next.


3 In the Export Options page, select Entire Application and Selected Locale Only.

Keep the Default Locale selection to export all forms in the application with the default view.
4 Click Finish.

The application is exported with only the default view of each form.

Chapter 3 Defining applications

113

BMC Remedy Action Request System 7.6.04

To export all views in the application for a specific locale


1 Right-click the application name in the Applications list in AR System Navigator. 2 In the Application Selection page of the Export wizard, enter a path and file name

for the view definition file for a locale, and then click Next.
3 In the Export Options page, select Locale Specific Contents Only, and then click the

ellipsis button, as shown in Figure 3-11.


4 Select the locale from the list, and click OK.

For example, to export all form views in the application that have a locale property set to fr (French), select fr.
5 Click Finish.

The Export wizard creates a view definition file containing only the form views with the selected locale property.
Figure 3-11: Using the Export Options page to export all form views for a locale

On each destination server, first import the application definition file that contains the application with default views of each form. Then import the appropriate view definition files.

To import the application and the locale-specific views


1 Log in to the destination server with BMC Remedy Developer Studio. 2 Import the application definitions a In AR System Navigator, right click on the server name. b Select Import > Application c Navigate to the application definition file and then click Next. d Select the appropriate Replace Options on the Destination Server settings, and

then click Finish. The application is imported with the default view of all forms only.

114

Form and Application Objects Guide

Exporting and importing deployable applications

3 Import the appropriate view definitions a In AR System Invoker, right click on the server name. b Select Import > View Definitions, and then click Next. c Navigate to the view definition file that contains views for the locale that you

want to import, and then click next.


d In the View Selection dialog box, click Finish.

Exporting and importing data with deployable applications


With deployable applications, you can include configuration data to deploy with the application by editing the application and then defining the data to include in the Data tab. This data can include back-end data that users might need to enable or disable workflow. You can bundle data with an application using either a form included in the application or from an external form, such the Group form. You can define a qualification to select only certain records from the form. If you select a form and do not define an export qualification, all data from the form is exported. You can also configure the import options to define how duplicate data is handled at import time. Use the Data tab in the Application window to choose the form containing the data and configure the settings that are used when you create the definition file.

To include form data when exporting definitions


1 In BMC Remedy Developer Studio AR System Navigator, right-click the

application name in the Applications list.


2 Select Edit Application from the pop-up menu. 3 Click the Data tab to open the panel. 4 Use the Add button to add forms containing the data to export to the list in the

Form Selector dialog box.


5 In the Export Qualification field, specify a query to narrow the amount of data

included when you export the application. If you do not specify a query, all data in the form is included. Using an unqualified query can result in a very large.def file.

Chapter 3 Defining applications

115

BMC Remedy Action Request System 7.6.04

6 In the Fields to Match on Import table, select which fields to map against the form

in the target server when you import data. Use the Add button and the Field Selector dialog box to add fields to the list.
Figure 3-12: Selecting fields to map against target server

7 From the Handle Duplicate Request IDs By list, select how to resolve duplicate

request IDs when data conflicts are found: Reject Duplicate RecordsEntries are imported using their existing IDs. If an ID is already in use, an error is generated. (Default) Generate New ID for Duplicate RecordsEntries are imported using their existing IDs. If a record with the same ID already exists in the database, a new ID is generated for the imported record with the duplicate ID. Replace Old Record with New RecordEntries are imported using their existing IDs. If a duplicate ID exists, the entire database record is overwritten with the record being imported. If you use this option, you must map the required core fields. If required core fields are not mapped, the server rejects the records. Update Old Record with New RecordEntries are imported using their existing IDs. If a duplicate ID exists, only the fields being imported are replaced, merging the record. This setting also makes all required fields that are not core fields optional. Generate New ID for All Records New request IDs are assigned to all requests in the data file, regardless of whether any IDs are duplicates.
8 Save the changes. 9 Use the procedure described in To export a deployable application on page 109

to export the application to a definition file. The form data is exported along with the object definition files.

116

Form and Application Objects Guide

Deleting applications

Deleting applications
When you delete an application, it is removed from the database and from the list of applications in BMC Remedy Developer Studio. The forms, workflow, and data included in the application are not deleted. You must remove them separately. If you provided an application as a shortcut, tell your user community to delete the application shortcut from their desktops. If users try to start an application after it is deleted from the server, they receive an error message. For more information, see Alternatives for presenting applications to users on page 103.

To delete the forms, data, menus, and workflow in an application


1 Open the application for modification as described in the Introduction to

Application Development with BMC Remedy Developer Studio guide, Working with applications and packing lists, page 64.
2 Change the list layout to a single list as described in the Introduction to

Application Development with BMC Remedy Developer Studio guide, To change the layout of an object list, page 39.
3 Select all the objects in the list. 4 Choose Edit > Delete. 5 In the Confirm Deletion dialog box, click OK.

NOTE
To delete the roles used in an application, see To delete roles on page 57.

To delete an application
1 In the AR System Navigator, expand serverName > Applications. 2 Right-click the application node and choose Delete. 3 In the Confirm Deletion dialog box, click OK to delete the object or Cancel to

preserve the object. The application is removed from the database, but the objects in the application are not deleted.

Local applications
Local applications are intended for use on a single server or a small number of servers. They use permissions based on groups, which means that each local application is designed for one specific server environment. If you must move or copy an application to another server, you must create the same groups on the destination server, or else redefine permissions for many objects in the application, including forms, fields, and workflow.

Chapter 3 Defining applications

117

BMC Remedy Action Request System 7.6.04

118

Form and Application Objects Guide

Chapter

Customizing objects

This section describes the features in release 7.6.04 that help you preserve customizations made to AR System objects. It also describes how to customize AR System objects in a way that ensures that the customizations will not be lost when an application or server is upgraded. The following topics are provided: About preserving customizations (page 120) Features for preserving customizations (page 120)

Chapter 4

Customizing objects

119

BMC Remedy Action Request System 7.6.04

About preserving customizations


In pre-7.6.04 releases of AR System, when you customized AR System application and server objects, you had to follow certain BMC development rules and guidelines to ensure that your changes would not be overwritten during upgrades. Following these guidelines to make even simple customizations sometimes required modifying many objects. For example, to modify a filter that was called by five filter guides, you had to disable the filter and each of the guides, copy them, and then modify the copies of the filter and the guides. In the 7.6.04 release of AR System, a new feature called Overlays has been introduced that allows customization of applications with a minimal chance of conflicts with the future versions of applications. The feature allows tracking of customizations and preserves changes to application objects even if they are modified during an application upgrade.

Features for preserving customizations


This section introduces the features that streamline the customization process and enable you to define, manage, and preserve customizations on AR System objects. Using these features greatly enhances the likelihood that your customizations are not lost when an application or server is upgraded. OverlaysAn overlay is a copy of an AR System object that is used in place of the origin object. All out-of-the-box AR System application and server objects in release 7.6.03 or earlier and objects created in the Base Development mode of BMC Remedy Developer Studio in this release are origin objects. To ensure that customizations are not lost during upgrades, you modify the overlay, not the origin object. During upgrades, the overlay is preserved, if the upgrade program modifies the origin object definition. After an upgrade, AR System continues to use the overlay in place of the origin object. See About overlays on page 121. Custom objectsA custom object is an object created by an AR System user. Objects created in the Best Practice Customization mode of BMC Remedy Developer Studio are considered custom objects. Upgrades do not modify or destroy custom objects. See About custom objects on page 123.

120

Form and Application Objects Guide

Features for preserving customizations

Figure 4-1 shows how unmodified objects, overlays, and custom objects are used in place of the original objects for a customized application.
Figure 4-1: Difference between a base application and a customized application

Unmodified BMC objects (origin)

User-created objects

Application objects in use

Modified BMC object (overlay)

Origin application (out-of-the-box)

Only origin objects are affected during an upgrade

An overlay is retained when its origin object is modified during an upgrade.

These features protect your business investment in customizations by providing the following benefits: Enforce best practice development in BMC Remedy Developer Studio. Preserve customizations during upgrades of AR System servers, components, and applications. Enable you to find all your customizations quickly and easily. In addition to these new features, the Best Practice Conversion utility enables you to convert pre-7.6.04 customizations into overlays and custom objects. See Preserving customizations during upgrade of the AR System server and other AR System components to version 7.6.04 on page 123.

About overlays
An overlay is a copy of an AR System structure or workflow object that is used in place of the origin object. An origin object for which an overlay has been created is an overlaid object. Until you modify the overlay, its appearance and functionality are identical to that of the overlaid object.
Chapter 4 Customizing objects 121

BMC Remedy Action Request System 7.6.04

To customize out-of-the-box AR System objects in a way that ensures that the customizations are not lost when an AR System application or server is upgraded, create an overlay of the object and then modify the overlay (see Working with overlays on page 128). At runtime, the AR System server and clients (such as the mid tier and BMC Remedy User, use overlay objects in place of the origin objects. For example, if a filter is to be used during an operation and AR System detects that the filter has an overlay, the server executes the overlay filter instead of the origin filter. Or if a client is required to fetch an object from the server and the object has been overlaid, the client fetches the objects overlay instead. During upgrades, an AR System installation program ignores overlaysit does not undo their modifications, overwrite them, or delete them; in fact, it is unaware that they exist. It changes only the objects that were installed with the application or server. After the upgrade, the application or server continues to use the overlays instead of the origin objects for runtime operations. For more information, see Preserving customizations during upgrade of the AR System server and other AR System components to version 7.6.04 on page 123. Overlays also make it easy to identify all the customizations in your applications (see Locating overlays and custom objects in BMC Remedy Developer Studio on page 137). Overlays do not perform the following functions: Preserve customizations to an object that is deleted during an application upgrade. If an existing object in your production environment is deleted during an application upgrade, any overlay of the object is deleted as well. Automatically merge customizations with functionality added during upgrades. For example, if a filter has three new actions in an upgraded application, those actions will not automatically be added to the filters existing overlay. Instead, you must identify the new actions by comparing the overlay to the upgraded origin object and then add them to the overlay if you decide to use them. Enable you to make all possible changes to AR System objects. For example, you cannot make changes that would alter the underlying database, such as changing a fields data type. For information about creating overlays to preserve pre-7.6.04 customizations, see Preserving customizations during upgrade of the AR System server and other AR System components to version 7.6.04 on page 123.

122

Form and Application Objects Guide

Features for preserving customizations

Overlay process
To use overlays to customize AR System, follow this process:
Step 1 Install AR System 7.6.04.

See the Installation Guide.

NOTE
AR System releases earlier than 7.6.04 do not support overlays.
Step 2 Create overlays of any object that you wish to modify and then modify the overlay

objects as necessary. To modify 7.6.04 and later objects, see Working with overlays on page 128 and Working with custom objects on page 133.

About custom objects


Objects that are newly created by Developer Studio in its default Best Practice Customization Mode are custom objects; they are not in an original BMC application.

WARNING
BMC recommends that you create or modify objects in Best Practice Customization mode. If you create or modify objects in Base Development mode, they might not survive application and server upgrades. Using custom objects has the following advantages: When you create an object in Best Practice Customization mode (that is, when you create a custom object), AR System forces you to follow BMC development best practices. This is not the case if you create an origin object in Base Development mode. The application and server installation programs do not modify or delete custom objects during application and server upgrades. Custom objects make it easy to identify all the user-created (versus out-of-thebox) objects in your applications.

Preserving customizations during upgrade of the AR System server and other AR System components to version 7.6.04
If you install BMC applications onto an AR System server 7.6.04 and make all customizations using Developer Studio in Best Practice Customization Mode, then all of your changes are captured as overlays or custom objects. However, if you have previously modified the applications and then upgraded your server, the previous modifications appear as origin objects. In that case, you can use the Best Practice Conversion utility to convert these changes into overlays and custom objects.
Chapter 4 Customizing objects 123

BMC Remedy Action Request System 7.6.04

After upgrading your AR System server to version 7.6.04, use the Best Practice Conversion utility to identify deviations from BMC development best practices in the following: Modifications that you made to BMC-provided objects User-created objects that you added to your applications After you fix the deviations, you can use the utility to convert your properly implemented object modifications to overlays and your user-created objects to custom objects.

IMPORTANT
BMC recommends generating overlays to preserve your customizations before upgrading your AR System components (other than the AR System server that must be of version 7.6.04 to create overlays) and applications to release 7.6.04.

To use overlays to preserve your customizations


Step 1 Upgrade only your AR System server to release 7.6.04. Step 2 Use the Best Practice Conversion utility to identify your customizations and

extensions and convert them to overlays and custom objects.


Step 3 Upgrade all your other AR System componentssuch as BMC Remedy Approval

Server, BMC Remedy Assignment Engine, BMC Remedy Email Engine, and the AREA LDAP and ARDBC LDAP plug-insto release 7.6.04.
Step 4 Upgrade your AR Systembased applicationssuch as BMC Atrium CMDB and

BMC Remedy ITSM Suiteto release 7.6.04.

WARNING
If you do not follow this process, your customizations might be overwritten during the upgrade. For more information, see the Installation Guide.

124

Form and Application Objects Guide

Features for preserving customizations

Overlayable and non-overlayable objects


In release 7.6.04, you can create overlays for certain objects only. This section identifies which objects you can or cannot overlay. Overlayable objects You can create overlays for the following objects: Active links Active link guides Escalations Filters Filter guides Forms Fields Nonoverlayable objects Images Local applications Menus Packing lists Views Web services

You cannot create overlays for the following items: Custom objectsSee About custom objects on page 123. Deployable applicationsOverlays of deployable applications are not supported for licensing reasons. You can, however, overlay and customize the objects within the deployable applications. See Deployable applications in AR System on page 86. Creating and modifying deployable applications is not permitted in Best Practice Customization mode. See Introduction to Application Development with BMC Remedy Developer Studio, About development modes on page 27. Overlaid objectsYou cannot create multiple overlays for the same object. Overlay objectsYou cannot create overlays of overlays. Form dataDSO mappings, DSO pools, flashboards, skins, and templates are stored as data in a form. They are not AR System objects. Therefore, you cannot use overlays to customize them, and any modifications that you make to them might be lost when an application or server is upgraded.

Overlay object names


In contexts where it is important to distinguish overlay objects from overlaid objects, such as in object definition files and server-side (escalation and filter) workflow logs, __o appears at the end of overlay object names:
overlaidObjectName__o

That is the format of the overlay objects real name. Elsewhere, overlay object names match the name of their corresponding overlaid object. The __o string is reserved for overlay objects. You cannot include that string anywhere in the names of new objects.

Chapter 4

Customizing objects

125

BMC Remedy Action Request System 7.6.04

NOTE
By default, object names can have no more than 80 characters. If the real name of an object exceeds 77 characters, an error occurs when you try to create an overlay for the object because the server cannot append the three-character __o suffix to the objects name.

View and field overlay names


Views and fields are identified by IDs, not names. Overlays for views and fields use the same ID as their overlaid views and fields. The way that overlays for views and fields are distinguished from their overlaid objects is that the overlays are associated with a forms overlay object, not with the overlaid form.

Renaming overlay and overlaid objects


You cannot rename overlay objects. If you rename an overlaid object, AR System automatically updates the name of its overlay object to match the new name.

Guidelines for overlaying forms, views, and fields


To customize a form, you must first create a form overlay. You may also need to create one or both of the following types of overlays, depending on which elements of the form you want to modify: View overlay Field overlay Before creating a view or field overlay, you must create a form overlay. Overlays of views and fields have the same IDs as the corresponding overlaid objects, so they must be attached to an overlay form to distinguish them from the overlaid objects. If a form is unmodified but creating its overlay is allowed, the Create Overlay menu is enabled. If you click Create Overlay to create a field or view overlay, a confirmation dialog box asks whether you want to create a form overlay before overlaying the field or view. The following sections describe the purpose of each of these overlays.

Form overlays
Unlike most overlay objects, a form overlay is not a copy of the form object. Instead, it is a subset of the forms properties. In a form overlay, you can make the following customizations: Modify form properties, such as permissions. Add custom views and fields. (To add fields that are not associated with a view, use the Outline tabs Show Fields Not in Any View button.)

126

Form and Application Objects Guide

Features for preserving customizations

Modify existing views and fields by creating overlays for them. (See View overlays on page 127 and Field overlays on page 127.)

View overlays
To overlay a view, you must first overlay the form that contains the view. In view overlays, you can modify the layout of the view and its fields. You can also add fields to the view.

NOTE
When you open a form, BMC Remedy Developer Studio typically fixes corrupt display properties (such as incorrect Z-order, missing menus, and missing labels). In Best Practice Customization mode, however, such errors in origin views are not fixed. Instead, BMC Remedy Developer Studio displays a message that the view overlay is required.

Field overlays
To overlay a field, you must first overlay the form that contains the view in which the field appears. Unlike most overlay objects, a field overlay is not a copy of the field object. Instead, it is a subset of the fields properties. The field overlay and the origin field in the origin form share the same data. In a field overlay, you can modify the fields permissions, default value, length, associated menu, Help text, and full text multiform search category. To change a fields layout, modify the overlay of its associated view. To determine where to modify a field property, select the field in the form overlay, and then select the property in the Properties tab. If the property cannot be modified in the form overlay, one of the following messages appears in the BMC Remedy Developer Studio status bar:
propertyName: To modify, create field overlay. propertyName: To modify, create view overlay.

The following modifications affect all the views with which a field is associated: Adding an item to a selection field Adding a character menu to a field This means that you can make these modifications only when each of those views has an overlay.

Chapter 4

Customizing objects

127

BMC Remedy Action Request System 7.6.04

Working with overlays


This section describes how to create, modify, and delete overlays for AR System 7.6.04 and later objects. You can work with overlays only in the Best Practice Customization mode of BMC Remedy Developer Studio.

To create an overlay
1 Open BMC Remedy Developer Studio in Best Practice Customization mode.

For information about changing the development mode, see Introduction to Application Development with BMC Remedy Developer Studio, Changing the development mode on page 30.
2 Open the appropriate object list. 3 Perform one of the following procedures: Objects Active links Active link guides Escalations Filters Filter guides Forms Local applications Menus Packing lists Web services Views Procedure
1 In the object list, locate and select the object that you want to overlay. 2 Right-click the object, and choose Create Overlay. Note: In Best Practice Customization mode, the Create Overlay context menu is

disabled for overlays and custom objects. If you try to create an overlay of an object that is open in the editor, ARERR 5328 is displayed. Save your changes and close the relevant editor to proceed. The new overlay object is opened in the appropriate editor. AR System automatically saves the overlay object and removes the overlaid object from the object list. In the object list and in the object editors tab, overlapping blue and gray squares are added to the overlays icon. See Viewing overlays on page 138.
1 Open the form containing the view that you want to overlay.

The form containing the view must be an overlay. See Guidelines for overlaying forms, views, and fields on page 126.
2 Open the form view that you want to overlay. 3 Choose Form > Create View Overlay.

Most of the view properties and the field formatting properties in the Properties tab become available for modification. The form view overlay icon appears on the views tab. See Viewing overlays on page 138.
4 Right-click the form view, and choose Save.

128

Form and Application Objects Guide

Features for preserving customizations

Objects Fields

Procedure
1 Open the form containing the field that you want to overlay. 2 In the form editor, right-click the field, and choose Create Overlay.

Alternatively, right-click the field in the Outline tab, and choose Create Overlay. If the view containing the field is not an overlay, some of the following types of field properties become available in the Properties tab: attribute, change history, database, help text, and permissions. If the view containing the field is an overlay, most of the color, display, font, and highlight field properties also become available in the Properties tab.
3 When prompted to confirm whether to create an overlay of the form, click Yes.

IMPORTANT: BMC Remedy Developer Studio creates the form overlay and opens it in the editor. The form overlay is created irrespective of whether or not you save the form after this.
4 To save the field overlay, choose File > Save. Note: If you close the form without saving it, the field overlay is not created. However,

the form overlay still gets created.

For information about creating overlays for pre-7.6.04 objects, see Preserving customizations during upgrade of the AR System server and other AR System components to version 7.6.04 on page 123. You can modify or delete overlays like any other AR System objects in BMC Remedy Developer Studio. Unlike the Create Overlay menu, no separate menu is available to modify or delete overly objects. For general information about modifying or deleting objects, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Working with existing objects, page 41. Table 4-1 on page 129 provides information about the modifications that you can or cannot perform on overlays. The Best Practice Customization mode of BMC Remedy Developer Studio prevents you from making nonpermitted modifications. In case of custom objects, the only nonpermitted modifications is the use of the __c or __o strings (underscore, underscore, letter c or oregardless of case) in the object name.

Non-permitted modifications on overlays


The following table lists the permitted and non-permitted modifications on overlays.
Table 4-1: Permitted and non-permitted modifications on overlays (Sheet 1 of 4) Overlay or custom object type1 All objects Can modify None Cannot modify Object name to include __c or __o
Note: These strings are reserved by BMC.

Chapter 4

Customizing objects

129

BMC Remedy Action Request System 7.6.04

Table 4-1: Permitted and non-permitted modifications on overlays (Sheet 2 of 4) Overlay or custom object type1 Active link Can modify Cannot modify

Name Associated form or form list Execution options, including state (enabled/disabled), execution order, and execution condition If actions and Else actions (add, modify, and delete) Primary form Run If qualification Associated form or form list Display information Entry point Primary form Workflow objects and labels Name Type

Active link guide

Escalation

Name Associated form or form list Execution options, including state (enabled/disabled), execution order, and execution condition If actions and Else actions (add, modify, and delete) Primary form Run If qualification Associated menu Audit option Change history Default value FTS properties Help text Length units Localize data option
Note: Before you can modify the localize

Field

Data type Entry mode (Display) Field map Field type ID Name

data option property in a field overlay, all views in the form that contain that field must be overlaid. When this property is modified in one view, it is updated in all views. Maximum and minimum value Full text multiform search category Permissions Size (reducing or increasing)

130

Form and Application Objects Guide

Features for preserving customizations

Table 4-1: Permitted and non-permitted modifications on overlays (Sheet 3 of 4) Overlay or custom object type1 Filter Can modify Cannot modify

Name Associated form or form list Error handler Execution options, including state (enabled/disabled), execution order, and execution condition If actions and Else actions (add, modify, and delete) Primary form Run If qualification Associated form or form list Display information Primary form Workflow objects and labels Add and delete custom fields Add and delete field overlays Delete form overlays Archive (add or change form) Audit (add or change form)
Note: The form for archive or audit must be

Filter guide

Name Type

Form

a custom form. Change history (text portion only) Default field list for results list Default sort order Default view Display property cache settings Entry points Fields (overlay only) FTS properties Help text Join qualification Localization information Next request ID block size Object properties Permissions (including subadmin) Status history Views (add and overlay only) Image All properties except Name

Application Owner (do not change the inclusion or exclusion of form in a deployable application) Display-only form information (type) Join form information (cannot change underlying forms, join option, type, qualifier information) Name Origin fields (cannot delete) Unique index Vendor form information (cannot change the associated plug-in, table name, type, vendor name) View form information (type, table name, key field) Views (cannot delete)

Name

Chapter 4

Customizing objects

131

BMC Remedy Action Request System 7.6.04

Table 4-1: Permitted and non-permitted modifications on overlays (Sheet 4 of 4) Overlay or custom object type1 Local application Can modify Label Description Show only forms in application Run with form windows maximized Custom title bar icon Custom about box Primary form Primary view Forms in application Support files Help text All properties except Name Label and description Add and remove objects Help text Permissions Aliases Appearance properties, including background color and background image Defined searches Field display properties Field layout Fields (add and remove) Image objects associated with the view Menu access Results list General information XML schema WSDL ports WSDL publishing location Cannot modify Name

Menu Packing list

Name Name

View (VUI)

Label (the only display property that is not permitted for modification) Locale Name View ID (must not be in BMC reserved rangessee Reserved IDs used as placeholders in definitions on page 479) View Type

Web service

Name

1. You cannot create overlays for all object types. For information about objects that you cannot overlay,

see Overlayable and non-overlayable objects on page 125.

In the Best Practice Customization mode, the Delete context menu (Delete View menu for views) is available only when you select an overlay or custom object. You cannot delete out-of-the-box objects in that mode.

132

Form and Application Objects Guide

Features for preserving customizations

The delete operation has the following consequences: If you delete an overlaid object (Base Development mode), its overlay is automatically deleted. Workflow objects associated with the overlay are also deleted, along with their overlays (if any). If you have workflow that uses a custom field on an overlay form, and you delete the overlay form, the workflow does not function correctly at run time.

Working with custom objects


You can work with custom objects in the same way that you work with origin AR System objects, provided that you are in the Best Practice Customization mode of BMC Remedy Developer Studio. Table 4-2 describes the activities that you can perform on custom objects and provides references to the related information.
Table 4-2: Activities you can perform on custom objects and the related information (Sheet 1 of 2) Activity Reference

CreatingAny object that you create in Best Practice For general information about creating objects, see the Introduction to Application Development with BMC Customization mode is treated as a custom object. Remedy Developer Studio guide, Creating objects, Note: To create origin objects, you must use the Base page 39. Development mode. RenamingYou can rename custom objects without restriction. The only restriction is that you do not use suffix the object name with __c. That string is reserved for future use. For general information about renaming objects, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Renaming objects, page 44.

Chapter 4

Customizing objects

133

BMC Remedy Action Request System 7.6.04

Table 4-2: Activities you can perform on custom objects and the related information (Sheet 2 of 2) Activity ViewingTo view custom objects, open the appropriate object list and select only the Custom filtering option. In object lists, custom objects appear with a black rectangle containing a concentric blue rectangle on their icons. For example, this is the icon of a form overlay: Reference See Displaying the Customization Type column in object lists on page 139.

For custom objects, the following decorator appears in the right bottom corner of the icon:

To identify the following types of custom objects, you can also look for the value Custom in the Customization Type column: Active link guides Escalations Filter guides Images Menus Packing lists Web services ModifyingYou can modify custom objects without restriction. However, you should follow BMC guidelines when modifying certain properties. The Best Practice Customization mode of BMC Remedy Developer Studio prevents you from making nonpermitted modifications to out-of-the-box objects. DeletingYou can delete custom objects without restriction. See Permitted and non-permitted modifications on overlays on page 129. For general information about modifying objects, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Working with existing objects, page 41. For general information about deleting objects, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Deleting objects, page 52.

134

Form and Application Objects Guide

Features for preserving customizations

Properties shared between overlays and origin objects


Overlay objects have the following types of attributes or properties: Properties that are independent and can have different values Properties that are shared with origin objects Properties that are inherited from the origin object and cannot be modified or controlled by the overlay object (If such a property is changed on the origin object, it is overwritten to the overlay as well. For example, name of the object.) This section describes the shared properties. When shared properties are modified, cumulative changes to the origin objects and their overlays are reflected on the corresponding database tables. Table 4-3 lists the shared properties and the permitted modifications for those properties, and describes their impact on the database tables.
Table 4-3: Impact of modifying shared properties on the database tables (Sheet 1 of 3) Shared property Enum or Selection field Permitted modification on overlay There are no restrictions on changing the properties of an Enum field. However, it is important to remember that these values are stored in an integer index in the database. Impact on database table On an overlay Enum field, if you add a new item in between existing items, the sequence of the index changes. Thus, the same field has different meanings on the origin and overlay forms, which might lead to workflow failures.
Note: When modifying such overlay

objects, you should carefully plan and assess the changes to make sure that they do not disrupt the existing data or workflow.

Chapter 4

Customizing objects

135

BMC Remedy Action Request System 7.6.04

Table 4-3: Impact of modifying shared properties on the database tables (Sheet 2 of 3) Shared property FTS and multiform search properties Permitted modification on overlay Most FTS properties on origin and overlay objects are considered cumulatively. The following multiform search properties cannot be cumulative (exceptions): For fieldsCategory Name For forms Environment Keywords Title For these exceptions, the AR System server behavior is as follows: If these attributes are set on the overlaid form, you cannot change them on the overlay. Overlay forms only inherit these attribute values. If these attributes are not set on the origin form, you can change them on the overlay. Their values are available for both the origin and overlay forms at run time. If you make any changes to these attributes on the origin form, the AR System server reflects the same on the overlay form by overwriting these attribute values. Functional currency for a Currency field Adding functional currency Deleting functional currency For each functional currency that you add to a Currency field, a column is added in the database. The number of columns in the database is a sum of the number of functional currencies added to the origin object and its overlay. For example, if the origin object has two functional currencies (INR and USD) but on its overlay you removed USD and added EUR, the database contains three columns: INR, USD, and EUR. If you removed a functional currency from both the origin object and the overlay, the corresponding column is deleted from the database. Impact on database table No impact

136

Form and Application Objects Guide

Features for preserving customizations

Table 4-3: Impact of modifying shared properties on the database tables (Sheet 3 of 3) Shared property Permitted modification on overlay Impact on database table Lengths of the origin Character field and its overlay are compared to find the maximum of the two. Actual length of the corresponding column in the main data table is set to this value. For example, if the origin fields length is 100 bytes and the overlay fields length is 200 bytes, the size of the corresponding database column is 200 bytes. Next request ID block size You can set this property independently on the overlaid and overlay objects. Adding a new non-unique index Changing a non-unique index Deleting a non-unique index By default, Status History is enabled for a form. When Status History is disabled, the AR System server deletes the corresponding column from database. Enabling status history Disabling status history At run time, the maximum of the next ID block size of the overlaid and overlay object is used. Actual indexes on the main data table reflect a combination of the indexes on the origin object and its overlay. If the Status History settings of an overlaid form and its overlay differ, the corresponding column in the database is retained, because one of them is enabled. If Status History is disabled on both the origin object and the overlay, the field is deleted from the database.

Length of a Character field Changing the field length

Non-unique index on a form Status History

Locating overlays and custom objects in BMC Remedy Developer Studio


When you use overlays and custom objects to modify AR System applications and servers, you can easily locate all your customizations. In the Best Practice Customization mode of BMC Remedy Developer Studio, you can identify customized objects as follows: In the object list filtering options, clear the Base Customization Type option, and select Custom and Overlay to display only custom and overlay objects. See Hiding unmodified objects in Best Practice Customization mode on page 139. In the Customization Type column of an object list, look for the Overlay (identifies overlay objects) and Custom (identifies custom objects) values. See Displaying the Customization Type column in object lists on page 139.

NOTE
The Customization Type column is available only when you connect to a 7.6.04 AR System server.

Chapter 4

Customizing objects

137

BMC Remedy Action Request System 7.6.04

Viewing overlays
To view overlay objects, you must use the Best Practice Customization mode of BMC Remedy Developer Studio. The following procedures assume that you are in that mode.

To view any overlay object except form view overlay or field overlay
1 Open the appropriate object list.

In object lists, overlays for active links, active link guides, escalations, filters, filter guides, forms, local applications, menus, packing lists, and web services have overlapping blue and gray squares on their icons. For example, this is the icon of a form overlay:

2 Double-click the overlay object in the object list.

The overlay object is opened in the appropriate editor.

To view a form view overlay


1 Open the form that contains the overlay form view in the form editor.

Overlay views have the following icon on their tab at the bottom of the form editor:

2 To display the form view overlay, click its tab.

To view a field overlay


1 Open the form that contains the overlay field in the form editor. 2 Select the form view that contains the overlay field.

In the Outline tab, overlapping blue and gray squares appear on the icons of all overlay fields. For example, see the icon of the Request ID field in the following figure:

3 In the Outline tab, select the appropriate overlay field to display its properties in

the Properties tab.


138 Form and Application Objects Guide

Features for preserving customizations

Displaying the Customization Type column in object lists


Object lists in both Base Development mode and Best Practice Customization mode include a Customization Type column. Depending on the mode, the column can contain several of the following values:
Value Custom Overlay Overlaid Unmodified Description Identifies custom objects Identifies overlay objects Identifies overlaid origin objects Identifies origin objects that are not overlaid Mode Best Practice Customization Best Practice Customization Base Best Practice Customization and Base

By default, the Customization Type column is hidden. To display it, follow this procedure:

To display the Customization Type column in object lists


1 Choose Window > Preferences to open the Preferences dialog box. 2 In the BMC Remedy Developer Studio branch, click Object List View to show the

Object List View preferences.


3 In the list, choose the customization type. 4 If necessary, select the All Columns option (the default). 5 In the table of columns, click the Display cell next to the Customization Type label. 6 Click the down arrow button that appears in the column, and select Yes. 7 Click OK to save your changes. 8 Close and reopen the object list to see the Customization Type column.

Hiding unmodified objects in Best Practice Customization mode


With respect to customization types, unmodified objects are objects created in Base Development mode that are not overlaid. By default, overlay, custom, and unmodified origin objects are displayed in object lists in Best Practice Customization mode. It is often useful to be able to see only customizations to applications that are just overlays and custom objects. To hide all unmodified origin objects in this mode, use the following procedure.

Chapter 4

Customizing objects

139

BMC Remedy Action Request System 7.6.04

To hide unmodified objects in Best Practice Customization mode


1 In Best Practice Customization mode, open the appropriate object list. 2 Expand Filtering Options, and select Custom and Overlay in the Customization

Type options, as shown in the following figure:

The list now displays only overlay and custom objects. To redisplay the unmodified objects, select only the Base option.

Navigating between overlays and overlaid objects


This section describes how to navigate between overlays and overlaid objects.

To open an overlaid object from an overlay


It is often useful to be able to compare an overlay to its origin object. You can do that in Developer Studio in the Best Practice Customization mode. For this, right-click the overlay object, and choose Open Selected > Overlaid. The overlaid object is opened in read-only format in the appropriate editor. To create an editable custom version of the overlaid object, use the File > Save As command. A copy of the overlaid object is saved as a custom object.

To open a related object on another server from an overlaid object


To identify new functionality in an upgraded application object, you can compare it with the corresponding overlaid object from an earlier release by opening both objects in BMC Remedy Developer Studio. If those objects are on different servers, use the following procedure to open the upgraded object from the overlaid object:
1 Open BMC Remedy Developer Studio, and log in to the server that contains the

overlaid object and the server that contains the upgraded object.
2 If you are not in Base Development mode, switch to that mode. 3 Right-click the overlaid object, and choose Open Selected > name_of_server_containing_upgraded_object.

140

Form and Application Objects Guide

Features for preserving customizations

NOTE
The context menu contains only the names of servers to which BMC Remedy Developer Studio is logged in and on which an object with the same name as the selected object resides. The object on the selected server that has the same real name as the selected object is opened in an editor.

Converting custom objects to origin objects


You can convert custom objects to origin objects only in the Best Practice Customization mode of BMC Remedy Developer Studio.

WARNING
Follow this procedure only if the Best Practice Conversion utility has converted an origin object into a custom object. Other than this, if you follow this procedure, application upgrades will fail and you will not be able to distinguish customizations from original objects. When converting the following custom objects to origin, first convert the related forms and workflow to origin, and then convert the objects themselves: Active link guides Filter guides Local applications Packing lists

WARNING
When an object is converted from a custom object to an origin object, the next AR System server or AR System application upgrade may overwrite the object and all customizations are lost. Also, if you do not convert all the related objects correctly, certain run-time failures might occur. For example, if a field is having a reference to a custom menu and if the field and form are converted to origin objects, but the custom menu is not converted, then at run-time, the menu will not be displayed for that field.

To convert a custom object to an origin object


1 In the objects list, select the custom object that you want to convert to origin. 2 Right-click and select Convert to Base. 3 Click OK when a dialog box appears that prompts you for confirmation.

If you convert a custom form to origin, AR System also converts the corresponding views and fields to origin. You cannot explicitly convert custom views and fields to origin. However, if required, you must explicitly convert the associated workflow.

Chapter 4

Customizing objects

141

BMC Remedy Action Request System 7.6.04

TIP
To check whether custom fields are converted to origin, you can use the Outline view.

Considerations for auditing and archiving overlays and custom objects


Table 4-4 describes the behavior of the auditing and archiving functions in case of overlay and custom forms.
Table 4-4: Audit and archive behavior on overlay and custom forms Action Enable an origin form for audit or archive. Result or rule You cannot change these properties on its overlay, but you can add new fields on the overlay and enable them for auditing or archiving. The AR System server checks whether the form you specified is a custom form, and if not, returns an error. You cannot specify an origin form as the audit or archive form of an overlay; it must be a custom form. The AR System server implicitly creates an overlay of its audit or archive form. You can enable auditing or archiving on the overlay. The AR System server creates the audit or archive form as a custom form, which belongs to the same group as that of the overlay form.

Specify an existing form name as the audit or archive form name for an overlay form.

Create an overlay of a form that is enabled for audit or archive. Create an overlay of a form that is not enabled for audit or archive.

Add new or special fields to an origin form. The AR System server converts these fields to custom on the custom audit or archive form. Add new fields to an overlay form. The AR System server adds the same fields to the overlay of the audit or archive form.

Enable an overlaid or overlay form for audit The setting is applicable to all modes. Entry operations or archive. performed in any mode (base or audit) use the shared audit and archive information regardless of the operations or systems overlay group. For example: If you enable an overlay form for audit and the entry operation is done in the base mode, the entry is audited. If you enable an overlay form for audit and the system overlay mode is set to 0 (base), the entry operation is audited. The audit form, which is a custom form in this case, is not available to users in base mode, but the data is audited and available in the system. User can see that data if they use the correct mode.

Behavior of overlay audit form or overlay archive form: An overlay audit form inherits information about the form being audited from its origin audit form. When information about the audited form is changed on the origin audit form, the AR System server reflects this change on the overlay audit form.
142 Form and Application Objects Guide

Features for preserving customizations

Consider that Form1 is the origin form and Form1_audit is its audit form. When an overlay of Form1 is created (call it Form1__o), the AR System server implicitly creates an overlay of Form1_audit (call it Form1_audit__o). Form1_audit__o inherits information about Form1 from its origin form, which is Form1_audit. When Form1__o is deleted, Form1_audit__o continues to have information about Form1 because its origin form is Form1_audit. However, when audit information is removed from Form1, the AR System server removes this information from Form1_audit__o as well.

NOTE
The preceding description is applicable to archive forms as well.

Handling of reserved fields


AR System contains some reserved fields that you can add to an out-of-the-box BMC application. These fields play specific, system-supported roles. The IDs of these fields are within BMC reserved ranges. For more information about reserved fields, see the Form and Application Objects Guide, Reserved fields, page 477. The Best Practice Conversion utility creates overlays for the forms and views on which it finds these special fields, and converts the fields to custom. For example, consider that you added the GUID field (ID 179) on a BMC Remedy Service Desk application form. When run in Overlay mode, the Best Practice Conversion utility creates overlays of the form and the appropriate view, and converts the GUID field to custom. The field is moved from the origin form to the overlay form by using the ARCreateOverlayFromObject API. The server does not overwrite the custom field, but converts that custom field as an overlay of the base field, when: The base form is imported with the same field ID as that on the overlay form. When the field is created on the base form with the same field ID as that on the overlay form. The conversion procedure does not work in the following circumstances for the target custom field and the base field that is being imported or created: Field types are not same (for example, the base field is of character type and the target custom field is of integer type). Field options are not same and either of the fields option is Display (for example, the base fields option is Required and the target custom fields option is Display). Field types are same and its character field and its Clob storage is not the same. (for example, the base fields storage option is In Row and the target custom fields storage option is Out Row). Field types are same and its column field and base fields data source id (field id on the form that is associated to the parent table field) does not exist on the form that is associated to the parent table field of custom column field.

Chapter 4

Customizing objects

143

BMC Remedy Action Request System 7.6.04

NOTE
If the conversion procedure does not work from ARImport API, the AR System servers behavior depends upon the selected importOption. If the ARCreateField or the ARCreateMultipleFields APIs are used, the AR System server issues an error. For more information about the APIs, see the C API Reference Guide.

Export and import operations on overlays and custom objects


This section briefly describes export and import operations on overlays and custom objects.

Export operations on overlays and custom objects


Table 4-5 shows the object customization types that can be exported in each development mode.
Table 4-5: Exporting objects by development mode Mode Best Practice Customization Objects that can be exported Origin (unmodified only) Overlay (with resolved name1) When an overlay object is exported, its overlaid object is automatically exported, too. Custom Base Development
1.

Origin (unmodified and overlaid)

For information about the real and resolved names of overlays, see Overlay object names on page 125.

You can include any combination of the permitted object customization types in a single export operation. For more information, see the Introduction to Application Development with BMC Remedy Developer Studio guide, Exporting objects, page 51.

Import operations on overlays and custom objects


You can import any combination of overlay, overlaid, unmodified, and custom objects in the same operation as long as they are in the same .def file. The following situations require special handling: Importing overlay objects with prohibited modifications Imported overlay objects must not contain any prohibited modifications (that is, modifications that you cannot make in Best Practice Customization mode). If they do, the import will fail.

144

Form and Application Objects Guide

Features for preserving customizations

Importing an overlaid object whose overlay is on the target server If properties that are not controlled by overlays are changed in an overlaid object before it is imported (for example, the overlay object name is changed), the change is reflected in the corresponding overlay object on the target server after the import is complete (in the previous example, the overlay object name is updated to match the new name of the imported overlaid object). Importing only overlay objects If you import an overlay object but do not import its corresponding overlaid object, the target server must contain a copy of the overlaid object. If it does not, the import will fail. For more information, see the Form and Application Objects Guide, Importing object definitions, page 523.

Working only with origin objects at design time


An origin object is an object created in the Base Development mode of BMC Remedy Developer Studio. All out-of-the-box AR System application and server objects are origin objects. By default, BMC Remedy Developer Studio is in Best Practice Customization mode. In this mode, you cannot create, directly modify, or delete origin objects. To work with origin objects, switch to Base Development mode. See the Introduction to Application Development with BMC Remedy Developer Studio, About development modes on page 27.

WARNING
BMC strongly recommends that you do not create or modify objects in Base Development mode. If you do, your changes might be lost when your AR System applications and servers are upgraded. The only exception to this recommendation is that you must use Base Development mode to reverse non-permitted modifications made to origin objects.

Configuring AR System to support only origin objects


By default, BMC Remedy Developer Studio and the AR System server are configured to work with and execute overlay and custom objects. To work only with origin objects at design time, run time, or both, follow the instructions in this section.

Chapter 4

Customizing objects

145

BMC Remedy Action Request System 7.6.04

Ignoring overlay and custom objects at run time


By default, the AR System server performs operations on overlay and custom objects at run time and ignores overlaid (origin) objects. You can, however, configure the server to execute overlaid objects at run time and to ignore overlay and custom objects unless an operations control record specifies an overlay group. (This exception enables clients to request that the server should execute an overlay or origin object.)

To ignore overlay and custom objects at runtime


1 In a text editor, open the AR System server configuration file:

(UNIX) ARSystemServerInstallDir/conf/ar.conf (Windows) ARSystemServerInstallDir\Conf\ar.cfg


2 Change the value of the Overlay-mode option from 1 to 0. 3 Restart the AR System server to make your changes take effect.

To configure the server to execute overlays and custom objects, reset the Overlaymode option to 1.

146

Form and Application Objects Guide

Chapter

Creating AR System forms

Use forms to capture and display information. A form typically includes related components such as employee and department information. A form contains fields in which the information is entered and displayed. The collection of fields represents a record of information in AR System. While the entries comprise the rows of a database table, the fields comprise the columns. This section discusses the types of forms available, and the tasks used to create them. The following topics are provided: Types of forms (page 148) Creating and managing forms (page 151) Display-only forms (page 157) Join forms (page 162) Setting form properties (page 174)

Chapter 5

Creating AR System forms

147

BMC Remedy Action Request System 7.6.04

Types of forms
An administrator can create forms that serve as part of a unique workflow solution. Form types include regular, join, display-only, view, and vendor forms. These forms can be customized using form views, as explained in Chapter 13, Creating and managing form views.

Regular forms
Regular forms are generally the main forms of your applications. Within the AR System database, AR System builds and manages tables to store the data displayed on your forms. When you create a regular form, you see the eight core fields (see Figure 5-1). All regular forms contain these fields. For information about core fields, see Core fields on page 472.
Figure 5-1: Create Form window and core fields

Join forms
You can create a join form to combine information from multiple AR System forms. This composite form includes fields derived from other existing forms. Use join forms to avoid data redundancy (information is stored in only one form) and maintain data integrity (information updated through the join form is updated in all other places).

148

Form and Application Objects Guide

Types of forms

For example, you can combine the information from the Help Request and the Employee ID forms (as shown in Figure 5-2) into a join form that displays information from both forms without duplicating employee information in every help request. You can combine a join form with other forms, or you can join a form to itself.
Figure 5-2: How joins work in AR System
New Join form

Help Request form

Employee ID form

For information about creating and using join forms, see Join forms on page 162.

Display-only forms
Display-only forms are not represented in the database, so they do not have any requests and they do not contain the core fields. You can use display-only forms in various ways: Control panels (as shown in Figure 5-5 on page 158)These provide an efficient way to organize and present users with specific tasks or objectives. Dialog boxesThese enable you to reuse specific groups of fields in a variety of ways. For example, you can create an employee information dialog box that contains generic fields (such as name and address) that multiple forms and applications can use. Entry points to other forms that contain dataYou can add an OK or a Continue button to a display-only form to cause an active link to transfer data from the display-only form to the primary form and then submit a request.

Chapter 5

Creating AR System forms

149

BMC Remedy Action Request System 7.6.04

View and Vendor forms


View and vendor forms allow users to access external data sources outside of AR System. These forms can be used to: Execute workflow on creation and modification of data when the changes are performed using the view or vendor form. Execute escalations on external data. Access external data to populate search style character menus or table fields. View forms allow AR System to point to and access data in an existing database table created outside AR System. The table can be located on the same server or in any other database server accessible from the current AR System database server. Vendor forms allow AR System to access arbitrary external data sources through the use of an ARDBC plug-in. ARDBC plug-ins enable AR System to interface with external data sources such as LDAP directory services, legacy systems, spreadsheets, text files, or database tables. A vendor form provides for easy integration with external data, without replicating the data. For more information, see the Integration Guide, Vendor forms, page 183, and the Integration Guide, View forms, page 187.

Inline Forms
Inline forms allows you to: Automatically load embedded forms on the view fields when the container form is loaded. Load an embedded form on a view field based on user action, such as, selecting a console, loading an incident into the view field. Replace an existing embedded form on a view field by an another form. You can use inline forms to: Reduce the number of open windows. Provide an appearance of a single form. Improve performance. You can open forms that are embedded in the view fields as inline. When using inline forms in your application, consider these behaviors: Forms load into view fields using an active link Open Window action. Child forms load faster. The pop-up windows appear at the center of the entire page and deactivate the entire parent window regardless of which embedded form triggered it. The view field boundaries do not cut or trim the pop-up windows. A single prompt bar appears for the entire page, including when workflow in the embedded form executes a message action with the prompt bar option.

150

Form and Application Objects Guide

Creating and managing forms

You can set the Inline Property to an AR System form while defining a workflow using Open Window action. For more information, see the following sections in the Workflow Objects Guide: Creating Open Window actions for Search or Submit windows Creating Open Window actions for Modify or Display windows

Creating and managing forms


Forms are created and defined using the following steps. To make sure that all form components are properly defined, follow the steps in the order listed.
Step 1 Create a form (see Creating and managing forms on page 151). Step 2 Set form properties (see Setting form properties on page 174). Step 3 Plan the layout of a form (see Arranging fields in a form view on page 412). Step 4 Create fields on a form (see Types of fields on page 367). Step 5 Set field properties (see Field properties on page 501). Step 6 Create form views (see Creating form views on page 400).

Creating forms
When planning a form, sketch the layout before you begin creating fields so that you have an idea of the best field location and order. When deciding where to place fields that have menus, text editors, or diary editors associated with them, allow space for the icons that will appear next to the fields. Consider using panels or trim (lines, boxes, or text) to group and label related fields. You can also add color to buttons and text labels. For information about form layout, see Arranging fields in a form view on page 412 and the Introduction to Application Development with BMC Remedy Developer Studio guide, Opening an object for editing, page 48. Form names must be unique on each AR System server. Names can contain up to 80 characters (including spaces), but avoid beginning a name with a number. Avoid using a plus sign (+) sign in the form name to ensure that a URL that contains the form name is not interrupted. Names can include double-byte characters. When you create forms: Users who are logged in to AR System using a browser or BMC Remedy User will not be able see the new form until you save the form and they log in to their client again. For forms opened in BMC Remedy User, the size of the window from which you save the form is the initial size. (This rule does not apply to forms opened in a browser.)

Chapter 5

Creating AR System forms

151

BMC Remedy Action Request System 7.6.04

To create forms
1 In AR System Navigator, expand serverName > All Objects. 2 Right-click Forms, and choose New formType.

Depending on the type of form you selected, the following action occurs: For regular forms, an Untitled Regular Form appears with the Core fields as displayed in Figure 5-1 on page 148. For join forms, the New Join Form Wizard opens. To continue, see Creating join forms on page 170. For display-only forms, a blank form opens. To continue, see Display-only forms on page 157. For view and vendor forms, other dialog boxes open. For more information, see the Integration Guide, Vendor forms, page 183, and the Integration Guide, View forms, page 187.
3 Choose File > Save. 4 In the Save Form As dialog box, enter the name of the new form.

NOTE
Avoid characters in a form name that result in an invalid URL when the form is accessed through the mid tier. BMC Remedy Developer Studio warns you if you use one of the invalid characters configured in the Form preferences page. By default, the Invalid Characters for Form Name preference is set to /&#%'".?.
5 Click OK.

152

Form and Application Objects Guide

Creating and managing forms

Opening forms
The following procedure describes how to open all form types when you want to make changes.

To modify forms
1 In AR System Navigator, expand serverName > All Objects. 2 Double-click Forms. 3 In the Forms list, double-click the form name.

The default form view of the selected form opens. For information about default form views, see Setting form view properties on page 405.
4 Click the tab of the form view that you want to modify. 5 Make the necessary changes to the form view.

For information about the types of modifications you can make to a form view, see Modifying form views on page 403.
6 To change the form properties, choose Form > Form Properties, make the changes

in the Form Properties dialog box, and click OK. For more information, see Setting form properties on page 174.
7 Save the form.

The form is available to users at their next login.

Copying forms
When you copy forms, the new form retains all of the fields, views, and properties of the original form. Workflow objects (such as active links, filters, and escalations) associated with a form are not copied.

IMPORTANT
Most system forms (such as User, Group, Server Events, and Server Statistics) contain reserved fields that make these forms unique. Do not copy these forms, or you might introduce unintended access control functionality into your environment.

To copy forms
1 In AR System Navigator, expand serverName > All Objects. 2 Double-click Forms. 3 In the Forms list, double-click the form name. 4 Choose File > Save As. 5 In the Save Form As dialog box, enter the new name of the form. 6 Click OK.

Chapter 5

Creating AR System forms

153

BMC Remedy Action Request System 7.6.04

Renaming forms
When you rename a form, all settings are retained, and any workflow that references the form is automatically updated with the new name of the form.

To rename forms in BMC Remedy Developer Studio


1 In AR System Navigator, expand serverName > All Objects. 2 Double-click Forms. 3 In the Forms list, right-click the form name, and choose Rename. 4 Enter the new name, and click OK.

NOTE
Avoid characters in a form name that result in an invalid URL when the form is accessed through the mid tier. BMC Remedy Developer Studio warns you if you use one of the invalid characters configured in the Form preferences page. By default, the Invalid Characters for Form Name preference is set to /&#%'".?.

Deleting forms
When you delete a form, all associated data and workflow that are not associated with any other forms are deleted. However, if the workflow is shared by multiple forms, that workflow is not deleted until the last form that uses it is also deleted. Menus, applications, and images must be deleted separately because they are independent of forms. If you delete a primary or secondary form of a join, the join form is also deleted.

WARNING
Do not delete the User or Group forms, or you lose the ability to add or modify users and groups. For more information about the Group form, see Creating groups on page 49. For information about the User form, see the Configuration Guide, Adding and modifying user information, page 57.

To delete forms
1 In AR System Navigator, expand serverName > All Objects. 2 Double-click Forms. 3 In the Forms list, right-click the form name, and choose Delete.

154

Form and Application Objects Guide

Creating and managing forms

Previewing form updates


In Development mode, you can preview changes made to a form within Developer Studio, as shown in Figure 5-3.
Figure 5-3: Previewing a form in Developer Studio

To enable form previewing, you must configure the mid tier preferences to identify the server and protocol information used by Developer Studio to access the forms that you want to preview, as shown in Figure 5-4 and described in the following procedure.

Chapter 5

Creating AR System forms

155

BMC Remedy Action Request System 7.6.04

Figure 5-4: Setting mid tier information for previewing forms in Developer Studio

To enable form previewing in Developer Studio


1 Open the Preferences dialog box. 2 Select Mid Tier Information. 3 Select one of the following options:

Default Mid Tier to useThe mid tier to use for all servers to which you are connected Custom Mid Tier to useThe path for specific servers on which forms are installed. You can edit the name in the Mid Tier Path column.
4 For the selected server, specify a path, or edit an existing path as needed. 5 Click OK.

To preview a form in a browser


1 Right-click a form from the form list. 2 From the context menu, select Open in Browser. 3 The selected form is displayed in the editor area.

156

Form and Application Objects Guide

Display-only forms

Display-only forms
You can create display-only forms for various purposes. This section provides tips for creating these forms, and examples of how you can use them.

Creating display-only forms


You can create display-only forms that work in New mode and Search mode in a browser and in BMC Remedy User (as shown in Figure 5-5). For general information, see Creating and managing forms on page 151. Be aware of the following issues when you create a display-only form: Unlike regular forms, display-only forms do not have the following form properties: Results list fields Sort Archive Audit Indexes Status history By definition, all fields that you add are display-only.

Using a display-only form as a control panel


A display-only form can be used as a centralized entry point from which users choose the tasks they want to accomplish. This is called a control panel, and it might include tasks from a variety of functional areas such as Help Desks, Employee Services, and Asset Tracking. Users select a functional area from the control panel and fill in data on the form related to the specific task.

Chapter 5

Creating AR System forms

157

BMC Remedy Action Request System 7.6.04

Figure 5-5: Display-only form used as a control panel

In this figure, the buttons on the display-only form act as entry points to multiple underlying forms.

NOTE
When using a display-only form as a control panel in an application, set the control panel form as the primary form. Consider hiding the Details Pane Banner of control panels so that users are not distracted by banner buttons. For information about how to hide the Details Pane Banner, see Details Pane Banner on page 407.

Using a display-only form as a dialog box


Dialog boxes require user interaction and are useful when you want to: Prompt users for confirmation. Implement a main-detail (or parent-child) relationship between forms where users can edit the main form using a details dialog box. Reuse a form in a variety of ways. Embed a table that lists options from which users can choose. Provide a way for users to edit or view a rarely used set of fields, and thus avoid cluttering the main form. Provide a way for users to view or edit a set of fields that handle complex calculations of multiple components.
158 Form and Application Objects Guide

Display-only forms

To define a dialog box, use the following active link actions with the Window Type set to Dialog:
Table 5-1: Workflow actions for defining a dialog box Action Open Window Description Sets the Open Window action to open a dialog box from a parent form. This action also defines what data is transferred from the parent form to the dialog box when the dialog box opens, and what data is transferred from the dialog box back to the parent form when the Commit Changes action occursusually when the user clicks an OK button or the dialog box closes. Commit Changes Changes the fields in the parent form to the values that the user specifies in the dialog box. The data from the dialog box is written to the parent form based on the mapping you created for the On Close mode in the Field Mapping region when setting the Open Window active link action. Changes are usually committed with the OK button on the dialog box. You might also want to create an Apply button that commits changes without closing the dialog box. Close Window Closes the active dialog box. The Close Window action usually occurs immediately after the Commit Changes action or as the active link action associated with Cancel occurs. For information about active links, see the Workflow Objects Guide.

Creating dialog boxes


The following procedure provides a general overview for creating an application that uses dialog boxes. In this example, a button named Enter Serial Number is created on the parent form. When the user clicks this button, a confirmation dialog box (display-only form) appears to allow the user to enter a serial number and click OK. An active link returns the value to the parent form. For more information about active links, see the Workflow Objects Guide.

To create a simple dialog box


1 On the parent form, create a button named Enter Serial Number from which you

want to open the dialog box, and save the parent form. For more information about buttons, see Button fields on page 384.

Chapter 5

Creating AR System forms

159

BMC Remedy Action Request System 7.6.04

2 Create a display-only form with the following fields:

A character field representing the entry field For example, if the user must enter the serial number of a product, create a field labeled Serial Number. An OK button A Cancel button You can add additional fields to a dialog box, but they will be display-only fields.
3 Create an active link that will launch the display-only form (dialog box). a In AR System Navigator, expand serverName > All Objects. b Right-click Active Links, and choose New Active Link. c On the Associated Forms panel, click Add, and add the parent form that contains

the Enter Serial Number button, which will open the display-only form.
d On the Execution Options panel, in the Button/Menu Field field, enter the name

of the button.
e Right-click the If Actions panel heading, and choose Add Action > Open

Window.
f On the Open Window sub-panel, complete the following fields as follows: In this field: Window Type Data Source Server Name Form Name View Name Enter: Dialog SERVER (The name of server that contains the displayonly form) (The name of the display-only form) (The name of view for display-only form)

g If you want the field to be automatically populated when the display-only form

opens, enter the fields name in the Field column, and enter a value in the Value column in the On Dialog Open Action area.
h Under On Dialog Close Action, enter the field from the parent form that you

want populated from the display-only forms Serial Number field.


i Click the Value pane at the selection point, enter the field whose value you want

transferred to the parent form when the display-only form closes. In this example, the field is Serial Number.
j Save the active link.

160

Form and Application Objects Guide

Display-only forms

4 Create an active link that executes when the user clicks the OK button on the dialog

box. Creating this workflow transfers information from the Serial Number field on the dialog box to a field on the parent form.
a Create a new active link. b On the Associated Forms panel, click Add, and add the display-only form

(dialog box).
c On the Execution Options panel, in the Button/Menu Field field, enter the name

of the button that users will click to confirm their entry in the display-only form. In this example, the button name is OK.
d Right-click the If Actions panel heading, and choose Add Action > Commit

Changes. The Commit Changes subpanel appears under the If Actions panel.
e Right-click the If Actions panel heading, and choose Add Action > Close

Window.
f On the Close Window subpanel, from the State list, select Close Current. g Save the active link. 5 Create an active link that executes when the user clicks Cancel. This action simply

closes the dialog box without returning any values.


a Create a new active link. b On the Associated Forms panel, click Add, and add the display-only form

(dialog box).
c On the Execution Options panel, in the Button/Menu Field field, enter the name

of the button that users will click to confirm their entry in the display-only form. In this example, the button name is Cancel.
d Right-click the If Actions panel heading, and choose Add Action > Close

Window. The Close Window subpanel appears under the If Actions panel.
e From the State list, select Close Current. f Save the active link. 6 Set the correct permissions for the forms and active links so that your users can

operate them successfully. For information about permissions, see Chapter 1, Defining access control. For additional examples of using buttons that open dialog boxes, open the Sample:ClassCentral form that is installed with AR System, and click the Enroll tab.

Chapter 5

Creating AR System forms

161

BMC Remedy Action Request System 7.6.04

Join forms
Join forms are composite forms that consist of fields derived from other existing forms. A join form can be useful in the following situations: When you need to produce reports from data that exists in more than one form. When data is stored in multiple forms and you want to display the data in a single form. To eliminate the need to enter the same data into multiple forms. This section helps you understand more about join forms.

Understanding join forms


A join form in AR System is similar to joining tables in a relational database. A join form uses searches to combine fields from two forms based on join criteria (see the Join criteria section that follows). The data in a join form comes from the database tables of the forms that make up the join form. After the join form is created, it behaves similarly to non-join forms. Users can submit data for creation or modification, report from it, select entries from it, use it in workflow requests, define workflow on it, and so on. From the users perspective, there is no difference between join and non-join forms. You can use a join form as a member of another join form. For more information, see Joining three or more forms on page 165.

Primary and secondary forms in the join form


When creating join forms, you designate one of the underlying forms as the primary form and the other as the secondary form. Primary forms are used when determining which extra entries are included in outer join forms (see Inner and outer joins on page 164) and the execution order in workflow (see Filters and join forms on page 168).

Join criteria
Join criteria define the link between the two underlying forms. Join criteria are values common to the forms that you want to join. For example, if a help desk form and an employee record form both have an employee ID field, the two can be joined by the equality relationship between them, as shown in Figure 5-6 on page 163. In database terms, this is an equal join.

162

Form and Application Objects Guide

Join forms

Figure 5-6: Join criteria in AR System


Join form

Help Desk.Employee ID = Employee Record.Employee ID (your join criteria)

Help Desk form

Employee Record form

NOTE
Try to use indexed fields in the join criteria. A join, like any other query of the database, should be optimized for best performance results. For information about indexing fields, see Defining indexes on page 181.

Including fields in the join form


You choose the fields from the primary and secondary forms that will be part of the join form. If you choose two fields that have the same field ID, the system provides a new mapped field ID for one of the fields because duplicate field IDs are not allowed in a form. The new field ID is mapped to the actual field ID in the underlying form when operations are performed.

NOTE
In a join form, BMC Remedy Developer Studio tries to preserve the name and field ID of fields from the primary form. You can change the display properties for fields in a join form and set permissions for the join form itself. After creating a join form, you can add display-only fields to the form. For information, see Chapter 11, Types of fields.

Chapter 5

Creating AR System forms

163

BMC Remedy Action Request System 7.6.04

Inner and outer joins


You can create two types of join forms: Inner joinSelects entries (or rows) only when corresponding values exist in both forms. For example, to retrieve only the entries from one form that have matching entries in another form, use an inner join. If an entry in one of the forms does not have a corresponding entry in the other form, the data is omitted. Outer joinIncludes all of the entries from the form that you select as primary, even entries for which there are no matching entries in the secondary form. For example, to see all submitted help requests, including those that have no specific employee information connected with them, create an outer join.

NOTE
An outer join in AR System is what relational database administrators call a left outer join. Selecting the left (or primary) form includes all of the entries associated with that form. Figure 5-7 illustrates the concept of inner joins. The Library Catalog form is the primary form. The Customer Checkout form is the secondary form. The join criteria is the ISBN (International Standard Book Number). Because an inner join creates a form that contains only the entries in which the join criteria exists in both the primary and secondary forms, the join form produces a report that shows only the titles that are checked out.
Figure 5-7: Example of an inner join
Primary form
Library Catalog Form

Secondary form
Customer Checkout Form

Title A B C D E F

ISBN 1 2 3 4 5 6

ISBN 1 2 4 6

Customer ID 200 201 203 267

ISBN is join criteria

Resulting inner join


Library Catalog Join

Because an inner join contains only the entries in which the join criteria is present in both forms, ISBN items 3 and 5 (which are not in the secondary form) are omitted from the join form.

ISBN 1 2 4 6

Title A B D F

Customer ID 200 201 203 267

164

Form and Application Objects Guide

Join forms

If the library had produced the same report using an outer join, it would be a comprehensive listing of all the catalog items in the library, regardless of whether they had corresponding entries in the other form. The Figure 5-8 shows an example of an outer join.
Figure 5-8: Example of an outer join
Primary form
Library Catalog Form

Secondary form
Customer Checkout Form

ISBN 1 2 3 4 5 6

Title A B C D E F

ISBN 1 2 4 6

Customer ID 200 201 203 267

ISBN is join criteria

Resulting outer join


Library Catalog Form

An outer join contains all of the entries from the primary form even if there is no corresponding join criteria in the secondary form.

ISBN 1 2 3 4 5 6

Title A B C D E F

Customer ID 200 201 203 267

When determining whether to create an inner join or an outer join, one approach is to base your choice on how much data you want to see. Inner joins are more useful for ad hoc queries and selection lists, while outer joins are more useful for special reports that are comprehensive by nature.

Joining three or more forms


To join three forms, you must first join two forms and then join the resulting form to the third, creating a hierarchy of joins. Joining multiple forms in a hierarchical order makes it easier to provide a consistent workflow. If you need to combine data from three or more forms, you can do so by creating a series of two-way joins. As shown in the Figure 5-9, you can join two regular forms, a regular form to a join form, or two join forms.

Chapter 5

Creating AR System forms

165

BMC Remedy Action Request System 7.6.04

Figure 5-9: Joining several forms


Layer 1

Form A

Form B

Form C

Form D

Form E

Layer 2

Join Form F

Join Form G

Layer 3

Join Form H

Layer 4

Join Form I

Add only as many join layers as you need, and make sure that your join criteria is efficient. The practical upper limit for combining forms is about six layers. This is because each join form is created by querying the databasewhich ultimately affects system performance. In addition, the workflow attached to each form in multiple layers of joins can also severely impact performance.

Self-join forms
You can join a form to itself. This is also known as a Cartesian Join. This functionality is useful when comparing data from the same form or when preparing reports. Suppose that you want a report of all of the managers, the managers phone numbers, the employees they supervise, and the employees phone numbers. Assume also that the employees and managers both exist in this form. In this example, DemoHD:Staff is the primary (designated as A) and the secondary form (designated as B), and it has the data shown in the following table.

166

Form and Application Objects Guide

Join forms

Figure 5-10: Self-join example 1


Request ID 001 002 003 004 005 006 Employee ID 111 222 333 444 555 666 Employee Name Bob Steve John Sue Doug Nancy Employee Phone Number 111-1111 222-2222 333-3333 444-4444 555-5555 666-6666 Manager ID 555 555 555 666 666 NULL

If you join the form to itself and specify A.Employee ID = B.Manager ID as the join criteria, you can then add and rename the following fields in the resulting join form: A.Employee Name (from the primary form) renamed to Manager. A.Employee Phone Number (from the primary form) renamed to Manager Phone Number. B.Employee Name (from the secondary form) renamed to Employee. B.Employee Phone Number (from the primary form) renamed to Employee Phone Number. The join form with four fields (or five if you include the composite request ID) contains the following results from an unqualified search.
Figure 5-11: Self-join example 2
Composite Request ID 005|001 005|002 005|003 006|004 006|005 Manager Doug Doug Doug Nancy Nancy Manager Phone Number 555-5555 555-5555 555-5555 666-6666 666-6666 Employee Name Bob Steve John Sue Doug Employee Phone Number 111-1111 222-2222 333-3333 444-4444 555-5555

You can include phone numbers for each manager and employee in one entry, even though they come from the same column in the same table. The self-join logically joins two separate forms that contain identical information. Self-join forms are useful for certain parent-child relationships. In the previous example, the manager-employee relationship is a type of parent-child relationship in which child entries (the employees) belong to a parent entry (the manager).

Chapter 5

Creating AR System forms

167

BMC Remedy Action Request System 7.6.04

Requirements for creating a join form using a vendor form


This section explains the requirements and limitations of creating a join form using a vendor form.

Requirements
Do not use pipe characters in the Entry ID of the vendor form that is a part of the join form. BMC Remedy AR System server distinguishes between the Entry IDs using the pipe characters as a separator. For example, do not use 00001|a4. As plug-ins return the Entry ID list to the plug-in server, all the Entry IDs in the list must be of 15 characters in length except for the last ID. For example, for an Entry ID list with 2 IDs, 0000000001 and 0000000002 cannot be used. The Entry ID list length of a vendor form must be a fixed length. The Entry ID length for all the entries of a vendor form must be the same, that is, a vendor form cannot have different Entry ID lengths. For example, if the Entry ID length of the first entry is 20, the Entry ID lengths of all the remaining entries must also be 20.

Limitations
The data from the join form is available only when the form is accessed through the AR Servers API. For example, the reporting engines that work directly against the database do not receive data from the vendor forms. The direct SQL and Set Fields with the SQL data source does not make data available from the joins form.

NOTE
You cannot create a join form using a display-only form.

Using join forms in workflow


When you use join forms in workflow, all of the typical execution conditions that apply to objects in non-join forms also apply. To enable the data entry functionality of a join form, data created or updated for a particular field must be associated with the appropriate database. The administrator must create workflow that defines how data should be pushed into the database when entered through join forms.

Filters and join forms


Filters are used to enforce the integrity of the system. When you use filters with join forms, the filters for the join form execute first, and then the filters for the underlying forms execute. The Figure 5-12 illustrates the execution order of the join forms and their primary and secondary forms.

168

Form and Application Objects Guide

Join forms

Figure 5-12: Execution order of filters with join forms

Join Form I

Join Form H

Join Form F

Join Form G

Form A

Form B

Form C

Form D

Form E

As you go down the execution order of the filters, all of the forms on the left side (the primary forms) execute first, and then forms on the right side (the secondary forms) execute. For more information, see the Workflow Objects Guide, Filter processing in the AR System server, page 177.

Transaction control in database operations


All of the operations performed on join forms, such as querying, displaying, and workflow operations, are executed as a single database transaction. For example, if you update data in one form that affects the data in multiple forms, all of the changes are performed as a single transaction in the database. This process ensures the integrity of the information. The completion of the database transaction for a hierarchy of forms is all or none. For example, in Figure 5-9 on page 166, if a filter returns an error on form I, none of the updates for the other forms is written to the database.

Chapter 5

Creating AR System forms

169

BMC Remedy Action Request System 7.6.04

The Request ID field


The AR System tracks the entries in the underlying forms that comprise a join form through the request ID of each entry. When you look at the Request ID field in a join form entry, you see that the field contains the Request ID of each underlying entry separated by a vertical bar. For this reason, if you create a join form from a non-join form and a join form (see join form H in Figure 5-9 on page 166), the join forms Request ID field contains three request IDs separated by vertical bars. The default permissions of the Request ID field in a join form are defined as Visible for the Assignee, Public, and Submitter groups. (For all other fields, the permissions are inherited from the underlying forms and cannot be changed.) However, you can remove the Public permissions of the Request ID field to make row-level security work in AR System. For information, see Controlling access by using implicit groupsRow-level security on page 38.

Creating entries in join forms


When creating entries through a join, AR System does not initiate a database operation. Because creating an entry in a join is not a determinate action, the system cannot automatically perform it. However, all filter operations defined for a join are performed, which requires you to define workflow that appropriately creates or modifies entries in the primary and secondary forms. For example, if you create a join between a customer and an item purchased, creating an entry through the join can be defined through workflow. With push fields filter actions, the workflow can create an entry for an item purchased or an entry for a customer.

Creating join forms


The following procedure guides you through the process of creating a join form.

To create a join between forms


1 In AR System Navigator, expand serverName > All Objects. 2 Right-click Forms, and choose New Join Form.

The New Join Form wizard appears.

170

Form and Application Objects Guide

Join forms

Figure 5-13: Choosing forms and join types

3 Select a primary form, and click Next. 4 Select a secondary form, and click Next. 5 In the Join Properties screen, select the options you want for your join form:

Join Type InnerSelects entries (or rows) only when corresponding values exist in both forms. OuterIncludes all of the entries from the form that you select as primary, even entries for which no matching entries are in the secondary form. Field Positioning HorizontalArranges the fields of the primary form on the left side of secondary form fields. Vertical (the default)Arranges the fields of the primary form above the fields of the secondary form.

Chapter 5

Creating AR System forms

171

BMC Remedy Action Request System 7.6.04

Inheritance Inherit Help Text for All FieldsTakes the help text from the fields in both forms and uses it in the join form. Inherit Help Text for Selected FormsTakes the help text from fields in the forms you select and uses it in the join form.
6 Enter a qualification in the Join Criteria section.

To use the Expression Editor to build the qualification, click the ellipsis button. For example, the following qualification join forms from requests with the same part numbers, you might use the following qualification:
$Part Number$ = 'Part Number'

Use dollar signs ($) around field names from the primary form, and use single quotation marks ( ' ) around field names from the secondary form.

NOTE
For optimal performance, use indexed fields in the join criteria. For information about indexing fields, see Defining indexes on page 181.
7 Click Next. 8 On the Primary Form Field Selection screen, move the fields you want included in

the join form from Available Fields column to Selected Fields column.

NOTE
You can join fields only if they have Input Length of 4000 or less.
9 Click Next. 10 On the Secondary Form Field Selection screen, move the fields you want included

in the join form from Available Fields column to Selected Fields column.
11 Click Finish.

The new join form appears.


12 Arrange the fields as you want them to appear in the join form. For example:

Add trim, buttons, panel fields, or table fields. Create views for the join form. For information about fields in join forms, see Working with fields in join forms on page 229. For information about arranging fields on a form, see Arranging fields in a form view on page 412.
13 Save the form.

172

Form and Application Objects Guide

Join forms

Modifying join form properties


After you create a join form, you can modify properties that determine the characteristics of how that join form looks and performs during operations performed in a browser or BMC Remedy User. The Join Information page in the Form Properties dialog box of BMC Remedy Developer Studio allows you to modify options specific to join forms.
Figure 5-14: Form Properties dialog boxJoin Information page

You can swap which form is primary and which is secondary. You can also change the type of joininner or outer. Depending on whether you are working with an inner join or outer join, swapping forms can result in completely different criteria. For example, if the primary form (A) has three fields (1, 2, 3) and the secondary form (B) has three fields (3, 4, 5), an inner join retrieves the field that the two forms have in common (field 3), and an outer join retrieves this field and the remaining primary form fields, that is, fields 1, 2, and 3. If you swap forms so that form B becomes the primary form and form A becomes the secondary form, an inner join yields the same results (field 3), but an outer join now retrieves the fields 3, 4, and 5. For more information about inner and outer joins, see Inner and outer joins on page 164. In the large field under the Join Type field, you can modify the join criteria qualification.

Chapter 5

Creating AR System forms

173

BMC Remedy Action Request System 7.6.04

Setting form properties


For each form, you can define properties that determine how that form looks and performs during operations performed in a web browser or in BMC Remedy User. The pages that appear on the Form Properties dialog box vary depending on the type of form (regular, join, and so on) you are modifying. The available pages are as follows:
Table 5-2: Pages on Form Properties dialog box (Sheet 1 of 2) Page name Basic Entry Points Description Defines settings for next ID block size, cache, and status history. Defines the order in which entry points appear in a Application List field and the mode (New or Search) in which the form will open. For more information, see: Defining next ID block size, cache, and status history on page 176 Creating form entry points on page 439

Results List Fields

Defines the forms fields that appear when Defining search results on page 178 a user performs a Search operation in a web browser or BMC Remedy User. Defines the order in which requests appear Setting up sort order on page 179 in the matching table list when clicking the Search button on a form in a web browser or BMC Remedy User. Defines the settings for periodically backing up or deleting form data. Defines form indexes to reduce the database search time for frequently searched fields. Defines the primary and secondary forms of a join form, the join type, and a qualification. Defines form indexes to reduce the database search time for frequently searched fields. Defines the weighted relevancy fields for searches on multiple forms. Defines the scan times for join, vendor, and view forms. Appendix E, Archiving data Appendix F, Auditing

Sort

Archive Audit

Join Information

Modifying join form properties on page 173 Defining indexes on page 181

Indexes

Full Text Search

The Configuration Guide, Configuring forms for multiple-form FTS, page 322

Vendor Information

For vendor forms only, defines the vendor The Integration Guide, Vendor forms, and table names used to create the form. If page 183 you modify these fields and specify a vendor name that is not associated with a valid ARDBC plug-in or a table name that the plug-in does not support, you receive errors when you try to access data from the vendor form.

174

Form and Application Objects Guide

Setting form properties

Table 5-2: Pages on Form Properties dialog box (Sheet 2 of 2) Page name View Information Description For more information, see:

For view forms only, displays the names of The Integration Guide, View forms, the table and key field used to create the page 187 form. You cannot edit these fields. Defines the access control groups that can Form, active link guide, and application access the form. permissions on page 31 Defines the access control groups that have Form, active link guide, and application subadministrator permissions for the form. permissions on page 31 Defines the owner of a form, the user who last modified it, the date and time of the modification, and a description of the changes. The Introduction to Application

Permissions Subadministrator Permissions Change History

Help Text

Development with BMC Remedy Developer Studio guide, Updating change history, page 53 Defines the help text for the form. This help The Introduction to Application text should describe the form, what it does, Development with BMC Remedy and how to use it. Developer Studio guide, Providing help text, page 54 BMC Remedy User users can view this
help text in the prompt bar (if visible) or in a list by choosing Whats This? help. Web browser users can view help by clicking the Help button, if a Help form action field is added to the form.

Form properties apply to all form views associated with that form. To set properties for a specific form view, select the tab of the form view, click in an empty area on the form, and edit the forms view properties under Properties. For more information about setting view-specific properties, see Setting form view properties on page 405.

To define form properties


1 Open the form. 2 Choose Form > Form Properties. 3 In the Form Properties dialog box, modify the properties.

Select the names on the left to move through the pages in the Form Properties dialog box. The form type you are modifying determines which pages appear.

Chapter 5

Creating AR System forms

175

BMC Remedy Action Request System 7.6.04

Figure 5-15: Form Properties dialog box

4 Click OK. 5 Save the form.

Defining next ID block size, cache, and status history


On the Basic page of the Form Properties dialog box, you can: Define the number of next request IDs that are allocated at once for a form. This improves server performance. To set a default for a server, see the Configuration Guide, Server Information Configuration tab, page 128, and the Optimizing and Troubleshooting Guide, Allocating blocks of Next-IDs, page 28. Override server view and field display property caching for a form. This option can be set to improve 32-bit server performance. When this option is enabled, the server will not cache display properties. This will improve memory usage, and server start up times, but it can slow performance when the display properties are called. To set the server default, see the Configuration Guide, Server Information Configuration tab, page 128. For more details about this option and the memory use impact, see the Configuration Guide, Configuring the display property cache to reduce memory use on page 446.

176

Form and Application Objects Guide

Setting form properties

NOTE
This option is not useful in a 64-bit environment. Most 64-bit environments do not impose memory limitations and setting the option could unnecessarily impact performance. Disable the server maintenance of status history for a form. When the check box is selected, the server clears the history and does not update it when the status changes. BMC Remedy User and the mid tier show no status history for a form when it is disabled. When the Disable Status History check box is cleared, the server starts to record and return status history for the form. When status history is enabled, BMC Remedy User and the mid tier show the status history for the form starting from when it was enabled.

To define the next ID block size, cache, and status history


1 Open the form with which you want to work. 2 Choose Form > Form Properties. 3 In the Form Properties dialog box, select the Basic page. 4 To define the next ID block size: a Select Enable Next Request ID Block Size to make the Next Request ID Block

Size field available.


b In the Next Request ID Block Size field, enter a value between 1 and 1000

inclusive.

WARNING
The use of this configuration setting might result in unpredictably large request ID sequence gaps. The likelihood of this occurring increases with the use of multiple servers that share a database. The AR System server does not malfunction due to this gap, so it should not be considered a defect.
5 To disable server view and field display property caching for this form: a Select the Override Server Default Display Property Cache Settings. b To disable caching of view display properties, select Disable VUI Display

Property Caching.
c To disable caching of field display properties, select Disable Field Display

Property Caching.
6 To disable the server maintenance of status history, select Disable Status History. 7 Click OK, and save the form.

Chapter 5

Creating AR System forms

177

BMC Remedy Action Request System 7.6.04

Defining search results


Use the Results List Fields page to customize which fields appear in the results pane when a user performs a search operation in a web browser or BMC Remedy User. If you do not define a results list for a form, the default is to display the contents of the Short Description field only. If you add any other field to the results list, the Short Description field is no longer automatically included and is not part of the results list unless you add it. If you include an attachment field, the results list displays the attachment file name. You can include fields that are greater than 255 characters, but only 128 characters appear in the column.

NOTE
Even though 128 characters or fewer are displayed, all of the fields data is returned to the client, possibly causing a performance issue. In addition to the Results List, this configuration controls the appearance of the selection list that can be displayed when the match criteria of a Set Fields active link action matches multiple requests. The separator is used in the selection list for BMC Remedy User. The width is used in a web browser and BMC Remedy User. The settings in the Results List Fields page specify the default set of fields returned for API programs that do not override the fields returned.

To define fields returned in a search


1 Open the form with which you want to work. 2 Choose Form > Form Properties. 3 In the Form Properties dialog box, select the Results List Fields page.

178

Form and Application Objects Guide

Setting form properties

Figure 5-16: Form Properties dialog boxResults List Fields page

4 To add fields to the table, click Add and complete the Field Selector dialog box for

each field. Only fields of the following types appear in the Field Selector dialog box: character, date/time, date, time, currency, integer, real, decimal, drop-down list, radiobutton, check box, and attachment. If you purchased the full text search option, you can select the WEIGHT field to display the weighted value of retrieved requests when you perform a search in a browser or BMC Remedy User. For information about full text search, see Configuration Guide, Using full text search, page 295.
5 In the Width column for each field, enter a number (1128) to set its initial width

in the results list. For example, if you set a width of 20, approximately the first 20 characters of the field value appear initially in the list.
6 To remove fields or to change the order of the fields, select a field, and click the

Remove, Up, and Down buttons.


7 Click OK.

To set the color of requests that appear in the results list, see To define form view properties on page 405.

Setting up sort order


Use the Sort page to define the order in which requests appear in the matching results list when clicking the Search button in a browser or BMC Remedy User.

Chapter 5

Creating AR System forms

179

BMC Remedy Action Request System 7.6.04

To set up the sort order for the results list pane


1 Open the form with which you want to work. 2 Choose Form > Form Properties. 3 In the Form Properties dialog box, select the Sort page. Figure 5-17: Forms Properties dialog boxSort page

4 To add fields to the Sorted Fields list, click Add and complete the Field Selector

dialog box for each field you want to add.


5 To remove a field, select it, and click Remove.

To remove all of the fields, click Remove All.


6 To change the order of the fields in the Sorted Fields list, select a field, and use the

Up and Down buttons.


7 As needed, change the Sort Order value for the fields in Sorted Fields list.

Click in the table cell, and choose Ascending or Descending from the list.
8 Click OK.

180

Form and Application Objects Guide

Setting form properties

Defining indexes
Indexing can greatly reduce database search time. Indexes can be defined for data fields on regular forms. You cannot create indexes for other form types because: Join forms use the indexing defined for the forms from which they are constructed. Display-only forms have no database table, so they need no indexing. View and vendor forms are owned outside of AR System, so any indexing they support must be managed outside of AR System. The Request ID field is already indexed, so you need not build a separate index for this field. Good candidates for indexing include fields that users search on frequently. If you define an index for a character field, you might save search time by using a QBE Match setting of Leading or Equal, not by using a QBE Match setting of Anywhere. For information, see QBE Match on page 525. If you are creating or modifying indexes in a form for which a large amount of data exists, this process can take a significant amount of time and disk space because the index must be built or rebuilt. Therefore, avoid defining indexes during normal production hours. More time is required to modify a form (for example, adding new fields) when indexes are defined for the form. The greater the number of indexes defined for the form, the more time and disk space is required. Submit and modify operations in a browser and in BMC Remedy User also take longer on forms with many indexes. For more information about maximizing index performance, see the Optimizing and Troubleshooting Guide, Creating effective indexes, page 33.

To define indexes for a form


1 Open the form with which you want to work. 2 Choose Form > Form Properties. 3 In the Form Properties dialog box, select the Indexes page.

Chapter 5

Creating AR System forms

181

BMC Remedy Action Request System 7.6.04

Figure 5-18: Form Properties dialog boxIndexes page

4 To add an index: a Click New.

An index is added to the Index List.


b Select the new index. c To add fields to the index, click Add and complete the Field Selector dialog box

for each field. You can combine multiple fields into a composite index. You can enter as many as 16 fields. Add the fields in the order you want them indexed, or use the Up and Down buttons to put them in the correct order. Each indexed field must be less than or equal to 255 character, but the composite Index can have a total length greater than 255.
d Use the Remove and Remove All buttons to remove fields form the index.

NOTE
AR System does not verify if the size violates the databases rules, but a database error is returned if the size is too large.
5 To remove an index from the database, select the index, and click Delete. 6 Click OK.

For more information about performance issues and tuning in AR System, especially analyzing forms for performance, see the Optimizing and Troubleshooting Guide, Managing performance, page 13.

182

Form and Application Objects Guide

Chapter

Creating and managing fields

You can create or modify fields in a form at any time. All changes take effect as soon as you save them, but if a user has a form open when you modify its fields, the user must close all instances of the form and reopen it to see your changes. The following topics are provided: Determining what types of fields to use (page 184) Creating data fields (page 184) Creating currency fields (page 191) Creating selection fields (page 196) Creating attachment pools (page 198) Creating view fields (page 201) Creating data visualization fields (page 203) Creating application list fields (page 203) Executing entry points in HTML (page 204) Creating navigation fields (page 205) Creating button fields (page 210) Creating trim fields (page 214) Creating global fields (page 217) Managing fields (page 219) Working with fields in join forms (page 229) To create table fields, see Creating table fields on page 247. To create panel fields, see Creating panel holders and panels on page 336. For detailed descriptions of each field, see Chapter 11, Types of fields.

Chapter 6

Creating and managing fields

183

BMC Remedy Action Request System 7.6.04

Determining what types of fields to use


The way you add fields to a form should be guided by the planned use of the fields. Some possible uses include: Data fields that all users need. These fields should be grouped together. Data fields used by selected groups of users. Consider grouping these fields on separate tabbed panels. Data fields that contain information not presented to users. Consider hiding these fields from all views. Temporary workflow fields. These fields store temporary, working values used during workflow processing. Consider hiding them from all views because users do not need to interact with these fields. Visual cue fields. Trim fields, panel fields, view fields, and images on button fields provide cues to users on how best to use each form. List-oriented fields. Use table fields when presenting data lists on forms. Add fields carefully because you might find it impractical to eliminate a field after users have come to rely on it. In addition, how you administer fields can affect performance. For more information about system performance and fields, see the Optimizing and Troubleshooting Guide, Managing performance, page 13.

Creating data fields


Use this procedure to create all data fields except currency and selection fields, which are discussed in Creating currency fields on page 191 and Creating selection fields on page 196.

NOTE
For an overview of data fields, see Data fields on page 368.

To create a data field


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > dataFieldType.

The new field appears on the form.


3 Select the field. 4 In the Properties tab, set the field properties as needed.

See Appendix D, Field properties.


5 To add a file system browser to a character field, see Adding a file system browser

to character fields on page 185.

184

Form and Application Objects Guide

Creating data fields

6 To add effects such as highlighting to fields, see Adding field effects on

page 189.
7 Select the field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


8 Right-click the form, and choose Save.

Adding a file system browser to character fields


File system browsers enable users to browse network file systems for a file and add the file path to a character field. (File system browsers do not enable users to upload or attach files.)

WARNING
Using the path in a Run Process active link action to access the contents of the file is not supported on the web.

To add a file system browser


1 Open the form where you want to add the browser. 2 Right-click the form, and choose Create a New Field > Character.

The new field appears on the form.


3 Select the field. 4 In the Properties tab, select File from the Display Type list.

A file selection button is attached to the character field. For example:

When the Display Type property of a character field is set to File: If a menu is attached to the character field, the menu is disabled, and the menu button is hidden. The character fields Expand Box property is disabled, and the expand box button is hidden. When users click the file selection button in BMC Remedy User, a standard file selection dialog box is displayed. When users click the file selection button in browsers, a dialog box containing a Browse button is displayed; clicking Browse displays a standard file selection dialog box. When users select a file name to add to the character field, any existing data in the field is overwritten.

Chapter 6

Creating and managing fields

185

BMC Remedy Action Request System 7.6.04

Adding rich-text-formatting capabilities to a character field


You can add rich-text formatting (RTF) to character fields in browsers so that users can make changes to the format of text in a character field. For example, a user might want to italicize or center text. Figure 6-1 shows the RTF dialog box that appears when a user clicks the RTF icon ( ) next to the field.
Figure 6-1: Editing a character field with rich text formatting

NOTE
BMC Remedy User does not support rich text formatting.

NOTE
Right-to-left (RTL) formatting is not supported in RTF fields. The rich-text-formatting (RTF) options provide a way for users to apply some basic styling of text and inclusion of images with their text. The options do not provide the level of functionality of a desktop-based word processor such as Microsoft Word. For information about using the RTF functions, see the BMC Remedy Mid Tier Guide, Editing fields with rich text formatting, page 130. For information about using the STRIPHTML function in workflow to remove RTF formatting, see the Workflow Objects Guide, Functions, page 229.

To add rich-text-formatting capabilities to a character field


1 Create a character field. 2 In the Properties tab, select one of the following options from the Display Type list:

Rich TextAllows users to click the RTF icon ( a separate dialog box.

) and make RTF changes in

Rich Text In PlaceAllows users to make RTF changes within the field, which includes a toolbar with a smaller subset of the commands found on the dialog box.

186

Form and Application Objects Guide

Creating data fields

NOTE
If you attach a menu to a character field with the Display Type property defined as Rich Text In Place, the RTF toolbar will not appear inside the field if the user selects the menu.
3 If you select the Rich Text In Place option: a Set the Rows property to 10 or more. b Set the Width property to 500 or more.

The changes to the Rows and Width properties enable the rich-text-formatting functions to appear when the user clicks in the field.
4 To enable users to add an image to a character field, complete the To allow users

to add an image to a character field procedure.


5 Save the field.

Enabling dynamic resizing of RTF fields


You can enable dynamic resizing of RTF fields so that the fields resize to fit the current contents as a user is entering information (text or images), and scroll bars are not required. To enable this type of resizing, the RTF fields must be in a panel.

NOTE
In modify mode, dynamic resizing of RTF fields fails when you switch among panels (that were initially collapsed) with RTF Auto Resize set to Vertical in a flow layout panel. This issue occurs in all browsers. In create mode, dynamic resizing works for RTF fields. The panels in questions are Collapsible and Accordion Panels.

To enable dynamic resizing of RTF fields


1 Create a panel that will contain the RTF fields.

For more information, see Creating panel holders and panels on page 336.
2 Resize the panel so that it is large enough to hold the RTF fields. 3 Set the following properties for the panel:

Set Layout Style to Flow. When you set this property, the panel can contain only one field per row. Tabbed Panel Holders support the Flow Layout Style; however, if an RTF grows dynamically, a scroll bar will not appear on the tab. Consequently, users cannot see fields that disappear at the bottom of the panel because of the resized RTF. Additionally, if you add a gradient color (Background Color property) or an image (Background Image property) to a panel that includes an RTF field, the color or image might not extend to the bottom of the panel when Flow is selected for the panels Layout Style property.

Chapter 6

Creating and managing fields

187

BMC Remedy Action Request System 7.6.04

NOTE
When you select Flow as the Layout Style property for a panel, the fields in the panel are left-aligned and vertically spaced equally. If you add another field after setting the Flow option, that field will not be properly aligned until you select the Flow option again. Set Vertical Spacing to the number of pixels of space between each field in the panel. (optional) Set the following properties to create margins around the fields in the panel. Panel Bottom Margin Panel Left Margin Panel Right Margin Panel Top Margin

NOTE
These Panel Margin properties are not supported on Tabbed Panel Holder fields.
4 Create RTF fields in the panel.

For more information, see Adding rich-text-formatting capabilities to a character field on page 186.
5 Set the following properties for each RTF field within a panel:

Set Auto Resize to Vertical. Set Maximum Height to 0 (no limit) or to a number that is equal to or greater than the fields Height property.

Allowing users to add an image to a character field


Users can add an image to a field with rich-text formatting (RTF) by referencing a URL to an image or through an attachment pool.

NOTE
If entries in an .arx file include an RTF field with an image from a URL, the image does not appear in the record after the .arx file is imported to a server. To view the image, you must re-enter the URL.

To allow users to add an image to a character field


1 Create an attachment pool on the form. 2 Add one or more attachment fields to the pool, depending on how many images

you want to allow the users to add to the character field. For more information, see Creating attachment pools on page 198.

188

Form and Application Objects Guide

Creating data fields

3 To ensure that the RTF field can store the text, images, and the hidden HTML tags

used for formatting purposes, increase the Input Length property, or set the property to 0 (unlimited length). The default Input Length property for character fields is set to 255. Inserting an image or a table can insert many more referencing text characters in the field.
4 To hide the attachment pool, set the Visible property to False. 5 Create a character field with rich-text formatting capabilities. a For the Display Type property, choose Rich Text or Rich Text In Place. b For the Image Attachment property of the character field, select the attachment

pool field that you want to link to the character field.

IMPORTANT
If you delete an attachment pool that is linked to an RTF field, remove the reference in the Image Attachment property of the corresponding character field. For more information, see To allow users to add an image to a character field on page 188.
6 Save the form.

NOTE
If a user adds an attachment image to a field with RTF but clicks the main cancel button to close the editor, the image is removed from the field, but the image remains in the attachment pool until the Browse button in the Image Options dialog box is clicked again. The image also remains in the attachment pool if the user deletes the image from the editor before saving the entry.

Adding field effects


Field effects in AR System can serve as visual cues to specific system actions.

Highlight field on value change


Three field properties under the Highlight property heading control whether a field is highlighted when a value is changed through a Set Fields action, and the color of the highlight. These properties apply only to data fields (character, diary, date, time, date/time, currency, integer, real, and decimal, radio-button fields, check boxes, and drop-down lists). If the value being changed is in a selection field (such as a radio button field) that does not have a single input element, the entire set of boxes or buttons is highlighted.

Enabled
When the Enabled property is set to True, you can specify a highlight start color and a highlight end color. The default value is false (highlight not enabled).
Chapter 6 Creating and managing fields 189

BMC Remedy Action Request System 7.6.04

Highlight start color


The Start Color property enables selection of a color for the highlight based on the theme of the form, background color, and other factors. If no start color is specified, the mid tier uses the default color of yellow.

Highlight end color


The End Color property enables a smooth visual transition following a system action. For best results, choose a color that matches the background color of the element on which the field resides, whether it is a panel or a form. The default color is white. For display-as-text fields, by default, the mid tier uses transparency to transition to the background color of the form.

Additional effects
The following effects are also available.

Dialog zoom out


This effect applies to calendar field, currency field, and character and diary field expand boxes. When an expand button is clicked, the associated dialog box zooms out.

Highlight on required fields when a submit action fails


When a submit action fails due to missing required values, fields needing values are highlighted with a red border. This effect applies only to data fields. For data fields that have a specific input element (such as a text entry box in a character field), the input element is highlighted with a red border. For selection fields (such as radio button fields or check boxes) that do not have a single input element, the red border appears around the entire field set (the entire set of buttons or check boxes).

Slide in and slide out of items in vertical navigation bar and panels
This effect enables submenu items in a vertical navigation bar to be slowly shown and hidden by having them slide in and out.

NOTE
Field effects can be disabled by selecting No in the Animated Effects field on the Web tab of the AR System User Preference form.

190

Form and Application Objects Guide

Creating currency fields

Using character fields to generate GUIDs


You can use a character field to automatically generate a globally unique identifier (GUID) for each request in a form. GUIDs are useful in a multiAR System server environment where you need unique IDs across AR System servers. Using GUIDs in such environments guarantees unique, transactionally safe IDs for your requests. GUIDs do not replace Request IDs. Each request still has a Request ID.

NOTE
Before AR System 7.1.00, the $PROCESS$ command was used to generate GUIDs. Using a GUID field provides better performance than the $PROCESS$ command. To automatically store a GUID in a field, create a character field with database ID 179. A GUID is available through all filter phases. By contrast, the value of a Request ID field is not available until a request is successfully committed to the database. You can customize all the properties of the GUID field except data type, input length, and ID.

Creating currency fields


Use this process to create currency fields:
Step 1

Set default currency types. Before you create a currency field, you should set default allowable and function currency types in the AR System Administration: Server Information form (see the Configuration Guide, Server InformationCurrency Types tab, page 141). The defaults appear in the Currency Types property dialog box of all new currency fields. For information about allowable and functional currencies, see Allowable and functional currencies on page 372.

Step 2 Create the currency field (see the following procedure). Step 3 Create currency exchange ratios (see page 195).

NOTE
For an overview of currency fields, see Currency fields on page 371.

Chapter 6

Creating and managing fields

191

BMC Remedy Action Request System 7.6.04

Creating a currency field


Use this procedure to add a currency field to a form.

To create a currency field


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > Currency.

The new field appears on the form.


3 Select the field. 4 In the Properties tab, select the Currency Types property, and click its ellipsis

button. If default allowable currency types are not specified in the AR System Administration: Server Information form, all the available currency types are selected in the Currency Types dialog box on the Allowable Currency Types tab, as shown in Figure 6-2.
Figure 6-2: Initial Allowable Currency Types tab without default currencies

If defaults are specified in the AR System Administration: Server Information form, those default currencies are selected on the Allowable Currency Types tab. For example, see Figure 6-3.

192

Form and Application Objects Guide

Creating currency fields

Figure 6-3: Initial Allowable Currency Types tab with default currencies

TIP
Although BMC Remedy Developer Studio might default to using all allowable currencies when a currency field is created, select only the relevant currencies for your locale to avoid the overhead of too many conversions. For information about allowable and functional currencies, see Allowable and functional currencies on page 372.
5 To change the allowable currencies for this field, perform these tasks in the

Allowable Currency Types tab:


a In the Select Types field, select the Customize option. b Use the arrow buttons to move currencies to and from the Available Types and

Selected Types lists. Currencies in the Selected Types list appear in the menu attached to the currency field. For example:

If you remove all currencies from the Selected Types list, all the available currencies are allowed and appear in the menu.
c (Optional) To change a currencys decimal precision, click the precision field in

the Selected Types list, and select a precision value from the drop-down list.

Chapter 6

Creating and managing fields

193

BMC Remedy Action Request System 7.6.04

d In the Primary Currency list, select the currency to use when no currency code

is entered in the currency field. If you do not select a primary currency, the first currency in the Selected Types list is used as the primary currency. For more information, see Currency fields on page 371.
6 To change the functional currencies for this field, perform these tasks in the

Functional Currency Types tab:


a Use the arrow buttons to move currencies to and from the Available Types and

Selected Types lists. The Selected Types list must contain at least one currency. There is no maximum number, but BMC recommends that you specify no more than five functional currencies to avoid delays when you submit requests.
b (Optional) To change a currencys decimal precision, click the precision field in

the Selected Types list, and select a precision value from the drop-down list.

IMPORTANT
The first functional currency that is defined is used in workflow evaluations and in searches. It is critical that you define a currency exchange ratio entry for the first function currency.
7 Click OK. 8 In the Properties tab, you can set one or both of these currency field properties:

Default ValueSpecifies the value that appears in the field when a user initially opens the form in New mode. The value consists of a decimal number and an allowable currency code. This value overrides the Initial Currency Type field property value set in BMC Remedy Developer Studio and the initial currency type preference set in the AR System Preference form. Initial Currency TypeSpecifies the currency code that appears in the field when the form opens in New mode if there is no Default Value and if the user has not specified an initial currency type in BMC Remedy User.
9 Set the other field properties as needed.

See Appendix D, Field properties.


10 Select the field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


11 Right-click the form, and choose Save.

194

Form and Application Objects Guide

Creating currency fields

Creating currency exchange ratios


The following procedure describes how to create currency exchange ratios for converting allowable (user-entered) currencies to functional (stored) currencies. You must create currency ratios from every allowable currency to every functional currency and, conversely, from every functional currency to every allowable currency. For example, if United States dollars is an allowable currency and Euros is a functional currency, create one entry for converting from USD to EUR and another entry for converting from EUR to USD.

NOTE
The first functional currency that is defined is used in workflow evaluations and in searches. Additionally, if you create an incomplete set of ratios, your applications might not work properly. For example, sorting on currency fields might produce incorrect results.

To create currency exchange ratios


1 On the server where you created the currency field, open the AR System Currency

Ratios form in New mode in BMC Remedy User.


2 Create two entries for each pair of currencies to which and from which you want

to convert. For example, you might create one entry for converting from USD to EUR:
Field Conversion Date From Currency To Currency Conversion Ratio Contents $TIMESTAMP$ USD EUR 0.640

Then create a second entry for converting from EUR to USD:


Field Conversion Date From Currency To Currency Conversion Ratio Contents $TIMESTAMP$ EUR USD 1.562

Chapter 6

Creating and managing fields

195

BMC Remedy Action Request System 7.6.04

To set the currency exchange ratio refresh interval


1 In the BMC Remedy AR System Administration Console, open the AR System

Administration: Server Information form.


2 Click the Timeouts tab. 3 In the Client Refresh Interval field, enter the interval in seconds.

The default setting is 60. A setting of 0 disables refresh. This is the interval at which clients query the server for new currency ratios from the AR System Currency Ratios form.
4 Click Apply.

Creating selection fields


Use these procedures to create selection fields.

NOTE
For an overview of selection fields, see Selection fields on page 376.

To create a selection field


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > selectionField.

Selection field types are Drop-Down List, Radio Button, or Check Box. The new field appears on the form.
3 Select the field. 4 In the Properties tab, set the Selections values.

See the following procedures: To add selection items To modify selection items To delete selection items
5 Set the other field properties as needed.

See Appendix D, Field properties.


6 Right-click the form, and choose Save.

196

Form and Application Objects Guide

Creating selection fields

To add selection items


1 Select the appropriate selection field. 2 In the Properties tab, select the Selections property, and click its ellipsis button.

In the Selections dialog box, you can create items that have linear IDs or custom IDs. AR System creates linear IDs automatically, beginning with 0. You must enter custom IDs manually. A selection field cannot have items with both linear IDs and custom IDs. See Selection fields on page 376.
3 To add items with linear IDs, go to step 5. 4 To add items with custom IDs: a In the ID Enumeration list, select Custom. b In the ID column of the item, enter an integer from 0 through 2147483647.

Negative integers are not permitted.


5 In the Selection Values column, enter the database value. 6 In the Alias column, enter the text to display in BMC Remedy User or a browser. 7 Click Add to add the item to the selection field. 8 Repeat steps 3 through 7 for each item you want to add.

NOTE
For Check Box fields, add only one item because users have access to only the first item.
9 To rearrange the items, select an item and click Up or Down.

IMPORTANT
If the items have linear IDs, do not change the order of existing items. If you do, the meaning of data previously entered in the database is changed. See Selection fields on page 376.
10 (Optional) In the Default Value list, select the item that appears when users

initially open the form to perform a search or to create a request.


11 Click OK. 12 Right-click the form, and choose Save.

Chapter 6

Creating and managing fields

197

BMC Remedy Action Request System 7.6.04

To modify selection items


1 Select the appropriate selection field. 2 In the Properties tab, select the Selections property, and click its ellipsis button. 3 In the Selections dialog box, select an item. 4 In the Selection Values, Alias, or Default Value fields, edit the information. 5 Click OK. 6 Right-click the form, and choose Save.

To delete selection items


1 Select the appropriate selection field. 2 In the Properties tab, select the Selections property, and click its ellipsis button. 3 In the Selections dialog box, select an item. 4 Click Delete.

IMPORTANT
If the items have linear IDs, do not delete items in the beginning or middle of a selection field in an existing form. See Selection fields on page 376.
5 Click OK. 6 Right-click the form, and choose Save.

Creating attachment pools


Use these procedures to create an attachment pool.

NOTE
For an overview of attachment pools, see Attachment pools on page 377.

To create an attachment pool


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > Attachment Pool.

The new attachment pool field appears on the form.


3 Select the field. 4 Add attachment fields to the attachment pool: a In the Properties tab, select the Attachment Fields property, and click its ellipsis

button.
b In the Attachment Fields dialog box, click New, and then click OK. c In the attachment pool, select the new attachment field.

198

Form and Application Objects Guide

Creating attachment pools

d In the Properties tab, enter these values:

Audit Log KeySee Appendix D, Field properties. Audit OptionSee Appendix D, Field properties. LabelCan have up to 80 characters. It is used as the display label and database name for the attachment field. See Appendix D, Field properties. Max SizeSpecifies the maximum size of the attachment in bytes. If you set Max Size to 0 (the default), users can add attachments up to the size that your database allows. See Attachment field size considerations on page 201.
e To add another attachment field, repeat steps a through d.

The number of attachment fields determines the number of attachments users can add. You can specify as many attachment fields as your database permits. If you exceed the limit, you get a database error. To determine the limit, see your database documentation.
f To move an attachment field from another attachment pool to this pool, see To

move an attachment field from one attachment pool to another on page 200.
g (Optional) Rearrange the attachment fields by using the Up and Down buttons

in the Attachment Fields dialog box


5 Set database properties for each attachment field: a In the attachment pool, select the appropriate attachment field. b In the Properties tab, set these properties as necessary:

Entry Mode ID Index for FTS Name See Appendix D, Field properties.
c Repeat steps a through b for each attachment field. 6 (Optional) Specify column headings and button (mid tier) or context menu

(BMC Remedy User) labels for the attachment pool:


a Select the attachment pool. b In the Properties tab, edit or clear the values of the following label properties.

If you clear a label for a button, the button is not displayed. If you clear a label for a column, the default column name is used. When users add attachments, the file names appear in the attachment pool even if you do not display any columns or buttons.
Label property Add Label Default value Add Description Label on button or context menu used for adding attachments. Label on column displaying attachment field labels. Chapter 6 Creating and managing fields 199

Attach Name Label Attach Name

BMC Remedy Action Request System 7.6.04

Label property Delete Label Deselect Label

Default value Delete Deselect

Description Label on button or context menu used for deleting selected attachments. Label on button or context menu used to deselect selected attachments. When you open a form created before version 7.1.00 in BMC Remedy Administrator, and BMC Remedy Developer Studio detects that an attachment pool is on the form, the modified flag is set, so you must save the form. The saved form includes the Deselect button or context menu. If the form is not opened in BMC Remedy Developer Studio before a user opens it: In BMC Remedy User, the Deselect item appears in the context menu. In a browser, the Deselect button or context menu does not appear.

Display Label

Display

Label on button or context menu used for opening selected attachments on the client. For browsers, only files with file name extensions configured to open in the browser open. If a file type is not configured to open in the browser, a Save dialog box opens.

File Name Label File Size Label Save Label

File Name Max Size Save to Disk

Label on column containing attached file names. Label on column containing attached file sizes. Label on button or context menu used for saving selected attachments on the client.

7 Set other field properties as needed.

See Appendix D, Field properties.


8 Select the attachment pool, drag it to a position in the form, and adjust its size.

NOTE
For web views, make sure to leave enough space on the form to accommodate the Add, Delete, Display, and Save to Disk buttons that appear below the attachment pool in a browser. See Arranging fields in a form view on page 412.
9 Right-click the form, and choose Save.

To move an attachment field from one attachment pool to another


1 Select the attachment field to move. 2 In the Attachment Pool List list on the Properties tab, select the name of the

attachment pool to move the field to. Both attachment pools must be on the same form.
3 Right-click the form, and choose Save.

200

Form and Application Objects Guide

Creating view fields

To delete an attachment field from an attachment pool


1 Right-click the attachment field, and choose Delete. 2 In the confirmation message, click Yes. 3 Right-click the form, and choose Save.

Attachment field size considerations


When setting the Max Size property for an attachment field, set a size that is large enough to accommodate typical attachments but small enough to conserve database space. If the size of an attachment exceeds the attachment fields allocated space, users cannot add an attachment to it even when the attachment pool contains other empty attachment fields. Attachment size can also be limited by the available memory on the client computer. For example, your database might allow attachments up to 2 GB but be limited to attachments of only a few MB because of client memory constraints. To set maximum attachment sizes for Oracle (including memory allocation), Microsoft SQL Server, and Sybase databases, see the Configuration Guide, DbMax-Text-Size2, page 362.

NOTE
Remote procedure call (RPC) and memory allocation errors might occur when users open large attachments on computers with limited memory resources. The error that appears depends on the stage of transfer (from client to server computer) at which the memory failure occurred. If you receive a malloc in client library failed error, check the memory resources of the client. If the error is Unable to send, check the memory resources of the client and server. If it was a databasespecific memory error, check the data or log (or transaction) space.

Creating view fields


Use this procedure to create a view field.

NOTE
For an overview of view fields, see View fields on page 380.

To create a view field


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > View.

The new view field appears on the form.


3 Select the field. 4 In the Properties tab, select the Text property, and click its ellipsis button.

Chapter 6

Creating and managing fields

201

BMC Remedy Action Request System 7.6.04

5 In the Text dialog box, enter an initial value for the view field, and click OK.

You can enter any value that a browser can read. For example, you can enter your companys URL, the URL for a form in the mid tier, an HTML snippet, or Oracle JavaScript. The web page, form, or interpreted code appears in the view field in BMC Remedy Developer Studio when you close the dialog box.

WARNING
In view fields, the primitive value is returned from the server. If you use scripting in view fields, make sure that the script does not appear to users. You can also reference a template. See Using templates with fields on page 390. In BMC Remedy User and a browser, the contents of a view field do not load automatically when users open a form. To display the initial value in those applications, perform one of these steps: Select the view and set the Set to Defaults property to True (governs New mode), and set user preferences to Set Fields to Default Values in New and Search modes in the AR System User Preference form. You can also set these user preferences in BMC Remedy User by choosing Tools > Options and selecting the Behaviors tab of the Options dialog box. Use a Set Fields active link action to set the view field value to $DEFAULT$ when the form opens. In this case, set the execute on condition to Window Loaded. You can also leave the Text property blank and use workflow to set the initial display value. To make the contents of the view field persist across actions in the same window, make the view field a window-scoped global field. Create the view field with a field ID in the range of 3000000 to 3999999, and use workflow to set the initial value. See Creating global fields on page 217.

WARNING
Do not use HTML snippets that contain tables or frames. Instead, use a URL to display this type of content.
6 Set border and scroll bar properties. See Appendix D, Field properties.

If the contents of the web page or HTML snippet are too large for the field, the value of the Scroll Bar property determines whether scroll bars appear at the fields bottom and right side in BMC Remedy User and a browser.
7 Set the other field properties as needed. See Appendix D, Field properties. 8 Select the view field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


9 (Optional) Use a trim text field to add a label (view fields do not have labels). 10 Right-click the form, and choose Save.

202

Form and Application Objects Guide

Creating data visualization fields

Creating data visualization fields


Use the following process to create data visualization fields. The steps in the process are detailed in the Integration Guide, Data visualization fields, page 167.
Step 1 Create a module on the mid tier. Step 2 Register the module. Step 3 Deploy a custom data visualization module. Step 4 Add a data visualization field to a form.

NOTE
For an overview of data visualization fields, see Data visualization fields on page 382.

Creating application list fields


Use this procedure to create an application list field.

NOTE
For an overview of application list fields, see Application list fields on page 382.

To create an application list field


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > Application List.

The new application list field appears on the form.


3 Select the field. 4 In the Properties tab, set the field properties as needed.

See Appendix D, Field properties.


5 Select the field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


6 Right-click the form, and choose Save.

Chapter 6

Creating and managing fields

203

BMC Remedy Action Request System 7.6.04

Executing entry points in HTML


To execute an entry point in a form, add a view field with custom HTML that uses the arInvokeObject commands to execute entry points in BMC Remedy User and in a browser:
arInvokeEntryPoint("serverName","guideName")Executes the specified

entry point guide.


arInvokeGuide("serverName","guideName")Executes the specified guide. arInvokeForm("serverName","guideName","mode")Executes the specified form in New or Search mode. Valid values for mode are New and Search.

You can use single or double quotation marks in these commands because JavaScript conventions permit strings to be enclosed by single or double quotation marks.

To execute entry points in HTML


1 Create a view field.

See Creating view fields on page 201.


2 Select the view field. 3 In the Properties tab, select the Text property, and click its ellipsis button. 4 In the Text dialog box, enter your commands.

For example:
<html> <script> function doInvokeForm(server, form, mode) { if("external" in window && "arInvokeForm" in window.external) arInvokeForm(server, form, mode); else parent.arInvokeForm(server, form, mode); } </script> <body> <form> <a href="javascript:doInvokeForm('ServerA','HelpDesk', 'search')">Search HelpDesk form</a> <br> </form> </body> </html>

In this example, doInvokeObject makes sure that the arInvokeObject functions are available. In BMC Remedy User, arInvokeObject is then called. In a browser, the functions are not available in the view field because the view field is an HTML iframe element. To access the arInvokeObject functions in a browser, you must reference parent.
204 Form and Application Objects Guide

Creating navigation fields

5 Click OK. 6 Right-click the form, and choose Save.

Creating navigation fields


Use this procedure to create a horizontal or vertical navigation field. For an overview of navigation fields, see Navigation fields on page 383.

To create a navigation field


1 Open the form to which you want to add a navigation field. 2 Right-click the form, and choose Create a New Field > Horizontal Navigation or

Create a New Field > Vertical Navigation.


3 Right-click the navigation field and choose Edit Menu/Navigation Items. 4 In the Edit Navigation Items dialog box, use the Add Menu, Add Item, and Add

Separator buttons to create menus for the field.

NOTE
Do not enclose menu labels within angle brackets (<>) such as those used to enclose HTML or XML tags. When a form with the menu is viewed in a browser, the angle brackets will cause the label text to be interpreted as a tag; as a result, the menu will not appear.
5 Click Close. 6 In the Properties tab, click the Attach Orphan Items property, and click its ellipsis

button.
7 In the Attach Orphan Items dialog box, attach orphaned navigation field and menu

items that are not attached to the form. Orphaned items are: Deleted menu bar items (choose Form > Edit Menu Bar to view them) Unattached items from deleted navigation fields
8 Click OK. 9 For each menu item, attach an active link that defines the action that occurs when

the item is clicked:


a Right-click the navigation field and choose Edit Menu/Navigation Items. b In the Edit Navigation Items dialog box, select the menu item. c In the Properties tab, click the Active Link(s) property, and click its ellipsis

button.
d In the Active Link(s) dialog box, move the appropriate active link to the Selected

Active Links field.


e Click OK. Chapter 6 Creating and managing fields 205

BMC Remedy Action Request System 7.6.04

f Repeat steps b through e for each menu item. g Click Close.

For information about creating workflow, see the Workflow Objects Guide.

NOTE
If you disable a parent item in a vertical navigation field, the parent item is collapsed and disabled, so the user cannot access the children. (To disable an item, use the Change Field workflow action.)
10 Select the navigation field. 11 In the Properties tab, select the appropriate item in these lists:

Fire workflow again on selected itemSelect an option to specify if workflow is fired again: Do not fire workflowWorkflow does not fire when the selected navigation item is clicked again. Fire workflowWorkflow fires again when the selected navigation item is clicked again. Navigation Initial StateIf you want a particular menu item selected when the user opens the form, select that item. Select item on clickTo select menu items with a single click, set to True. To select menu items with a double-click, set to False.
12 Set other navigation field and menu item properties as needed.

For example, select a menu item, click the Permissions property, click its ellipsis button, and set permissions for the menu item in the Permissions dialog box. Users see only the menu items to which they have access. See Appendix D, Field properties.
13 Select the navigation field, drag it to a position in the form, and adjust its size.

Make sure that the field is large enough to hold the menus and items that you created. Horizontal and vertical scrollbars appear in a navigation field in BMC Remedy User and a browser if the field is not large enough. See Arranging fields in a form view on page 412.
14 Right-click the form, and choose Save. 15 (Optional) To change the styling of menus in forms in a browser, create properties

in the applications cascading style sheet (CSS). For more information, see the BMC Remedy Mid Tier Guide, Customizing AR System style sheets, page 55.

206

Form and Application Objects Guide

Creating navigation fields

Setting navigation field color options


When using panels along with navigation fields in a console (for example, if you embed a navigation field in a collapsible panel), you might find that the panels and navigation fields differ in background colors, height of header text, and appearance of the icons used to expand and collapse items. Figure 6-4 shows the difference in colors between panel headers and navigation field items.
Figure 6-4: Navigation field and panel colors

Previously, text and background colors were not customizable for navigation fields, but were for panels. You can now customize navigation field text and colors (including gradients) so that their appearance matches that of panels used in conjunction with them in a form. You can customize navigation field elements using these properties: Top level background color for menu (including gradient colors) Sub level background color (where subordinate menus and menu items are listed) Top level text color Sub level text color Item height Font of menu label and text Figure 6-5 shows a navigation field and a panel with the same color and text display attributes.

Chapter 6

Creating and managing fields

207

BMC Remedy Action Request System 7.6.04

Figure 6-5: Navigation field and panel with same color and display attributes

Each object has these properties:


Navigation field Top level background color: Maroon Sub level background color: Gray Label font: Header Text (III) Navigation item height: 20 Panel Header background: Maroon Background color: Gray Label font: Header Text (III) You cannot change the height of the panel header. To make the height of the navigation bar header match that of the panel, set the navigation item height to 20.

To customize a navigation fields display properties


1 Select the navigation field to customize. 2 If the navigation field will be displayed in conjunction with a panel (for example,

embedded in a collapsible panel or as part of a series of navigation items in a console), determine the display properties that you need for the appearance of the items to match.
3 Select the display properties for the navigation field:

ColorTop level text color, sub level text color DisplayTop level background color, sub level background color, item height. For more information about display properties, see Appendix D, Field properties.

Navigation field display and color properties


Navigation fields include the following display and color properties: Top level text colorThe text color of the top level of the menu Sub level text colorThe text color of the menu items Top level background colorThe background color (and gradient, if selected) of the menu label Sub level background colorThe background color of the area where menu items are listed

208

Form and Application Objects Guide

Creating navigation fields

Item heightThe height of the navigation item in the navigating bar

NOTE
Sub level items do not support gradients. Item heightThe amount of line spacing, between 20 and 50 pixels, between items in the menu. The default is 25 pixels. Label fontThe font of the menu label and menu items.

NOTE
This selection applies the chosen font to all items. You cannot select one font for the menu labels and another for the menu items.

Applying flyout mode to navigation fields


Horizontal and vertical navigation fields enable users to navigate to screens quickly and easily. A horizontal navigation field might enable users to move from application to application, and a vertical navigation field might give users access to common functions and application entry points within an application. Navigation fields can act as anchors for other menu fields, and you can use multiple navigation fields with menus attached to them. Horizontal navigation fields can have only one level in their structure. Vertical navigation fields can have unlimited levels. Previously, vertical navigation fields could be displayed only by expanding the menu items in them vertically or horizontally. As a result, navigation fields containing many menu items could require a significant amount of screen space to display all of the items included in a menu. Vertical field menu items can now be configured to be displayed in a flyout mode. When users select menu items, those items are displayed to the right of the menu from which they were selected. Submenus also can be set to fly out from their main menu items. Enabling menu items to be displayed in this mode, as shown in Figure 6-6, can help application developers make better use of screen space and can enhance the web look and feel for a form.

NOTE
If you create two or more adjacent navigation fields with flyout enabled, be sure that you allow enough space between the two navigation fields so that any submenu items that they contain do not overlap. If they overlap, one submenu will be hidden beneath the submenu of the adjacent navigation field and will not be visible to the user. For example, if you create two adjacent navigation fields and one is at the right edge of the form without enough space for its menu items to fly out to the right, those menu items will fly out to the left instead, and will be hidden by the items on the navigation field next to it.

Chapter 6

Creating and managing fields

209

BMC Remedy Action Request System 7.6.04

Figure 6-6: Flyout navigation menu display

Developer Studio provides a property called Mode to enable flyout capability for menus displayed in vertical navigation fields on the web. This property has two settings: Expandable Menu items are displayed vertically as expandable lists. FlyoutMenu items are displayed in a parallel list to the right of the menu. A flyout menu can be displayed either when a menu is clicked or when the user moves the mouse over it.

NOTE
When a navigation bar resides within a panel, you might not see all of the navigation bar's available menus. For example, if a navigation bar has 10 menus, you might initially see only 7 of them (depending on the size of the panel). To see the remaining menus, you must click or hover over the last visible root (first-level) menu (for example, the 7th menu).

NOTE
The Flyout mode setting is ignored when a form is displayed in BMC Remedy User.

Creating button fields


Use this procedure to create a button field.

NOTE
For an overview of button fields, see Button fields on page 384.

To create a button field


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > Button.

210

Form and Application Objects Guide

Creating button fields

The new button appears on the form.


3 Select the button. 4 In the Properties tab, set these properties:

Button LabelThe text displayed on the button. Display TypeSelect one of these button styles: ButtonThe button looks like a button. Users can click it to initiate active link actions. MenuThe button field is added to the menu bar. For more information, see the Workflow Objects Guide, Using buttons and menu bar items to execute active links, page 165. URLThe button looks like a URL. Users can click it to initiate active link actions.
5 (URL only) Modify the color of the URL: a In the URL Color propertys drop-down list, select Custom. b Choose a color from the color palette, and click OK. 6 Specify active links to execute when the button is clicked: a In the Properties tab, select the Active Link(s) property, and click its ellipsis

button.
b In the Active Link(s) dialog box, connect active links to the button. c Click OK.

For more information, see the Workflow Objects Guide, Using buttons and menu bar items to execute active links, page 165.
7 Set other field properties as needed.

See Appendix D, Field properties.


8 Select the field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


9 Right-click the form, and choose Save.

Chapter 6

Creating and managing fields

211

BMC Remedy Action Request System 7.6.04

Adding images to buttons


Bitmap size is not restricted in the form or on the disk. All forms are stored in memory, however, and forms with large images can cause a performance decline. Furthermore, adding an image to multiple views causes copies of the same image to be stored in memory. For a browser, large images increase the download time. For best performance, use images with small file sizes, such as GIF or JPG files.

NOTE
To support the Image Reference functionality for button fields, AR System clients and supporting applications such as BMC Remedy User and the mid tier must be release 7.5.00 or later. When previous clients open a form containing an image reference, the server converts the image format into a byte stream that is cached on the client, as in previous versions. The functionality to gray out disabled buttons is part of the button feature; you do not need different bitmaps to represent different button states (for example, normal, grayed, depressed, reversed).

To add an image to a button


1 Select the button. 2 In the Properties tab, click the Image property, and click the ellipsis button. 3 In the Image dialog box: a If necessary, click Clear Image to delete an existing image. b Browse for the image to display on the button.

You can choose BMP, JPEG, JPG, GIF, and PNG files. The chosen image appears in the Preview area.
c

To save the image to a different file or folder, click Save to File. Embedded ImageThe image is stored in the field display properties as an ARByteList. In this case, the image is embedded in the form and is therefore downloaded with the form whenever the form is refreshed by the client. Image ReferenceA reference to a shared image object is stored in the field display properties. In this case, the image is stored as an image object in AR System. When the form is downloaded, the image is cached separately, so the image does not have to be refreshed along with the form. This allows for faster form refresh time. See Chapter 10, Working with images.

d Set the Image Type:

e Click OK.

212

Form and Application Objects Guide

Creating button fields

4 Select the button, and set the following properties in the Properties tab:

Alternative TextProvides a text description of the button to display as a tooltip and to satisfy accessibility requirements. The alternative text description can include spaces.

NOTE
When the Alternative Text field is left blank, the button does not have a tooltip association. To satisfy accessibility requirements, the button label displays when the field is left blank. Display as Flat ImageDisplays the button without its three-dimensional border. This is helpful when you want to use images as trim. If the button performs an action when clicked, make sure the button looks like an object that users should click. For example, you can include a label for the button. Image PositionSets the image location relative to the label: Center (default) Left Right Top Bottom When the image is centered, the label is not visible inside the button. Scale Image to FitScales the image to fit the size of the button. If this option is set to False, the image might be cropped, and you might need to resize the button frame. Maintain Aspect RatioRetains the proportions of he image when the image is resized to fit the size of the button. This option is enabled when Scale Image To Fit is set to True.
5 Set other field properties as needed.

See Appendix D, Field properties.


6 Right-click the form, and choose Save.

Chapter 6

Creating and managing fields

213

BMC Remedy Action Request System 7.6.04

Creating trim fields


Use this procedure to create any of these trim fields: Horizontal line Vertical line Trim text Trim box

NOTE
For an overview of trim fields, see Trim fields on page 385.

To create trim fields


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > trimType.

The new trim field appears on the form.


3 Select the trim field. 4 (Trim text) In the Properties tab, select the Text property, click its ellipsis button,

enter the text that will appear on the form into the Text dialog box, and click OK. See also To add a URL to a trim text field on page 215.
5 (Trim text) Set these properties:

Text AlignSpecifies where text is positioned relative to the top and bottom edges of the text box: Top, Middle (default), or Bottom. Text StyleSpecifies a font type for the text field.

NOTE
Users can change the font family, style, and size of each font type by using the BMC Remedy User Display options settings. As the administrator, your font preferences should match that of the majority of your users tools. Text Rotation - Specifies the angle at which the text can be rotated within a trim text field. The valid values are: 00 (default), 900, or 2700 degrees.

NOTE
Users must modify the size of the trim text field according to the length of the rotated text

214

Form and Application Objects Guide

Creating trim fields

6 Set the remaining field properties.

See Appendix D, Field properties. By default, trim box and trim text backgrounds are opaque (default trim text backgrounds are the color of the form). To show the area beneath a trim box or trim text (for example, when using an image on a button and placing trim text on the image), make their backgrounds transparent, and bring the trim box or trim text to the front (choose Layout > Bring To Front).

NOTE
In some browsers, users cannot click fields under a transparent trim box. For applications viewed in a browser, place trim box fields under other fields.
7 Select the trim field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


8 Right-click the form, and choose Save.

Adding a URL to a trim text field


Using a trim text field, you can add a URL to a form that links users to an Internet or intranet site or that opens a file in its associated program. In BMC Remedy User, the URL target opens in a browser window. In a browser, the target opens in a new window.

To add a URL to a trim text field


1 Open the appropriate form. 2 Create a trim text field (see To create trim fields on page 214).

The new field appears on the form.


3 Select the trim text field. 4 In the Properties tab, select the Text property, and click its ellipsis button. 5 In the Text dialog box, enter the text that will appear on the form.

For example, enter Go to the BMC Software site.


6 Select all or part of the text to convert to a URL, and click Insert URL.

Chapter 6

Creating and managing fields

215

BMC Remedy Action Request System 7.6.04

7 In the Insert URL dialog box, enter the appropriate URL.

For example, enter http://www.bmc.com. You can use any of these prefixes:
file: ftp:// gopher:// http:// mailto:

TIP
Before using the URL in the trim text field, test it in your browser.
8 Click Insert.

The URL text in the Text dialog box is automatically converted to HTML. For example:
Go to the <a href="www.bmc.com">BMC Software</a> site

By default, the URL appears in blue text.


9 Click OK. 10 (Optional) Change the color of the URL text: a Select the trim text field. b In the Properties tab, select Custom from the URL Color drop-down list. c In the URL Color palette, select the appropriate color. d Click OK.

Only the color of the URL text is updated. For example, if you use the text in step 8, only BMC Software is updated. To update any other text in the trim text field, use the Label/Text Color property.
11 Right-click the form, and choose Save.

For more information about adding URLs to a form, see the BMC Remedy Mid Tier Guide, URLs for forms and applications, page 76.

216

Form and Application Objects Guide

Creating global fields

Creating global fields


Global fields are display-only fields. AR System has two types of global fields: Regular global fieldsShare data across multiple windows and forms. See Regular global fields on page 218. Window-scoped global fieldsShare data across multiple records in the same window. See Window-scoped global fields on page 218. To make a field a global field, you set the field ID to a value within a reserved range (see To create a regular global field on page 218 and To create a window-scoped global field on page 218). The following types of fields can be global fields: Character Currency Date Date/Time Decimal Diary Integer Real Selection (drop-down list, radio button, or check box) Time View (window-scoped global fields only) You cannot create default values for global fields. The values in global fields begin as NULL until active links initialize them or users enter information into them. The values in global fields are not affected if users choose Edit > Clear All or Edit > Set to Defaults. For more information about display-only fields, see Entry Mode on page 510. In forms viewed in a browser, global fields are implemented as encoded values in cookies, which have a 4 kilobyte limitation. (With other cookie data, you can estimate that 3,500 bytes can be stored.) Global values are checked and fields are updated when a window receives focus.

Chapter 6

Creating and managing fields

217

BMC Remedy Action Request System 7.6.04

Regular global fields


Use regular global fields to share data across multiple forms. The field value stays in BMC Remedy User memory until the next login. In a browser, the value in the global field persists across forms for the user session, but the value is not shared across sessions. Use regular global fields for information that is expected to be shared across multiple forms and windows in an application. For example, on several forms, you might include a global field for a users license information.

To create a regular global field


1 Add one of the valid global field types to a form.

For a list of valid field types, see Creating global fields on page 217.
2 Select the field. 3 In the Properties tab, set the fields database ID to a value from 1000000 through

1999999. See ID on page 514.


4 Copy the global field to multiple forms.

Make sure that each copy of the global field uses the same field ID number.

Window-scoped global fields


Use a window-scoped global field to share data across multiple records in the same window. The initial field value is set by a user or by active links and stays in the field until the window is closed. This value must be reinitialized when the window reopens. For example, you could use window-scoped global fields to display information about weather conditions in a view field. The information remains the same while the user performs searches on other fields in the same window. If you displayed the same information in a regular global field, it would have to be refreshed every time a new record is displayed. With a window-scoped global field, you set the value once for that window and update the value when you choose to do so by using active links. For example, you could update the information about weather conditions on an interval.

To create a window-scoped global field


1 Add one of the valid global field types to a form.

For a list of valid field types, see Creating global fields on page 217.
2 Select the field. 3 In the Properties tab, set the fields database ID to a value from 3000000 through

3999999. See ID on page 514.

218

Form and Application Objects Guide

Managing fields

Managing fields
The following sections explain how to modify, copy, delete, disable, and find fields in a form.

Modifying fields
If you modify the display properties of a field, the modifications apply only to the current form view. If you modify any other field properties, the modifications apply to all form views.

To modify a field
1 Open the appropriate form. 2 Select the appropriate field. 3 In the Properties tab, modify the field properties as needed.

See Appendix D, Field properties.


4 If necessary, drag the field to another position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


5 Right-click the form, and choose Save.

Copying fields
You can copy all field types except attachment fields. Most properties of the copy are the same as the original with these exceptions: If you copy a field to the same view or to a different view of the original form, the only field properties that change are the ID and Name. If you copy a field to a different form, all the fields properties (including the ID) remain the same. To use the field in shared workflow (for example, in an active link), you must modify the workflow to include the form to which the field was copied.

WARNING
Be careful when using different field names that share the same field ID because shared workflow might use the field ID. You might want to use the same field name to help you remember what the fields purpose is on each form if you attach shared workflow to multiple forms. Regardless of the form or form view to which you copy a field, menus attached to a field are copied with the field and do not need to be reattached.

Chapter 6

Creating and managing fields

219

BMC Remedy Action Request System 7.6.04

To copy a field
1 Open the form from which you want to copy a field. 2 Right-click the field, and choose Copy.

You can also select and copy multiple fields.


3 Open the form to which you want to copy the field. 4 Right-click the form, and choose Paste.

The new field appears on the form. If the form has multiple views, these conditions apply: If your form preferences are set to add that type of field to all form views, the field is added to all form views. For more information about form preferences, see Setting form properties on page 174. If your form preferences are not set to add that type of field to all form views, the field is added only to the current form view. To add the field to a different form view, too, select the view, and choose Form > Add/Remove Fields On View. See Including and excluding fields from form views on page 411. If you copy the field to a different view on the same form, a dialog box appears with this prompt: Do you wish to add existing fields to this view or create new fields? Select one of these options, and then click OK: Create New FieldsCreates a copy of the field, and adds it to the view. The copied field has the same properties as the original field except for the ID and Name. Add to ViewAdds the selected field to the view. No fields are created. The added field has the same properties as the original field. For another way to perform this operation, see Views on page 530.
5 Select the newly pasted field. 6 In the Properties tab, modify the field properties as necessary.

See Appendix D, Field properties.


7 Select the field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412.


8 Right-click the form, and choose Save.

220

Form and Application Objects Guide

Managing fields

Deleting fields
When a field is deleted, it is removed from all form views. When you save a form from which you have deleted a field, the field is deleted from the form in the database, and the field and its associated data for each request are also deleted from the database and space is freed. The operation might take several minutes to complete. Because your database might be unavailable while the deletion is occurring, users might not be able to access the server and might receive time-out messages. To minimize user inconvenience, perform deletions during off-peak hours. To disable data fields without removing them or their associated data from the database, see Making data fields nonoperational on page 221.

To delete a field
1 Open the appropriate form. 2 Right-click the field, and choose Delete.

You cannot delete core fields. See Core fields on page 472.
3 In the confirmation box, click Yes to delete a single field, or click Yes To All to

delete multiple fields.


4 Right-click the form, and choose Save.

NOTE
When you delete a panel field, the data fields on the panel are not deleted; they are only removed from the view. See Including and excluding fields from form views on page 411.

Making data fields nonoperational


To stop using a data field without deleting it, make it nonoperational. Do this for fields that contain necessary data that you do not want users to access or for fields that you plan to delete when you restructure the database.

To make a data field nonoperational


1 Open the appropriate form. 2 Select the field. 3 In the Properties tab, make sure that the Entry Mode value is set to Optional.

The Entry Mode property is enabled only for required and optional fields. You cannot change the entry mode of a display-only field, table field, or panel field. See Entry Mode on page 510.
4 If the form has multiple views, remove the field from all form views except the

current form view. See Views on page 530.

Chapter 6

Creating and managing fields

221

BMC Remedy Action Request System 7.6.04

5 Remove the field from the current form view.

See Including and excluding fields from form views on page 411.
6 Right-click the form, and choose Save.

The field is not hidden to current users of the form until they reopen the form or log in again.

NOTE
You can also set permissions to make a field available to selected users only. See Field permissions on page 32.

Finding fields in a form


Use the procedures described in this section to locate a field in a specific form view. These procedures are useful in the following circumstances: The form has a lot of fields. You need to find an unlabeled field. You need to find a field that is behind another field. You know the field ID but do not know where the field is on the form.

Finding fields by label, name, or ID


Use this procedure to search for a field by all or part of the fields label, name, or ID.

To find a field by ID, label, or name


1 Open the appropriate form. 2 If the form has multiple views, select the appropriate view. 3 Choose Edit > Find/Replace. 4 In the Find Field field of the Find Fields dialog box, enter an alphanumeric string

to search for. The string can be all or part of the fields label, database name, or ID.
5 In the By Type section, select the option that identifies the string entered in step 4:

LabelThe name of the field displayed on the form. NameThe name that identifies the field in the database. Field IDThe number that identifies the field internally in AR System.
6 Select the direction to search. 7 (Optional) Select one or more search options. 8 Click Find.

The first field that matches the search criteria is highlighted in the form.
9 Repeat step 8 until all fields matching the search criteria are found. 222 Form and Application Objects Guide

Managing fields

Finding fields in a list on the Outline tab


Use this procedure to search for a field in a hierarchical or tabular list on the Outline tab.

To find a field in the Outline tab


1 Open the appropriate form. 2 If the form has multiple views, select the appropriate view. 3 In the Outline tab, click one of these display format buttons:

Show Tree Overview In this format, the fields are displayed in a tree view, which shows any parentchild relationships among the fields. Each field is identified as follows: fieldTypeIcon fieldDatabaseName (fieldID) Show Table Overview In this format, the fields are listed in a table that contains these columns: Field ID, Name, Label, and Type. You can sort the table on any column.
4 In the Outline tab, select the field that you want to locate.

In the form, the selected field is outlined with a selection box, and its properties are displayed in the Properties tab.

Setting tab order for fields on a form


You can specify the order by which fields in a form receive focus as users tab through a form. This information is used by both BMC Remedy User and the mid tier. Specifying a tab order can help users navigate a form and perform related actions faster and easier. Figure 6-7 shows the tab order specified for a form.
Figure 6-7: Tab order displayed in form editor

Chapter 6

Creating and managing fields

223

BMC Remedy Action Request System 7.6.04

You can specify tab order for fields in a form by using any of the following methods: By editing the tab order in the form editor By dragging and dropping fields in Outline view when fields are sorted by tab order By updating the tab order in the field's properties

Viewing and modifying tab order in the form editor


The following procedures outline how to view and modify tab order, and reset the default tab order, in the form editor.

To specify a tab order


1 Choose Layout > Tab Order > Select and Edit. 2 In the editor, enter the appropriate numbers for the tab order. 3 Save the form.

To specify incremental tab order by clicking through fields


1 Choose Layout > Tab Order > Increment on Click. 2 Click the field on which you want to start the tab order. 3 Click each field in the desired tab order. The tab order number appears as you click

each field.

To reset the default tab order


1 Choose Layout > Tab Order > Set Default. 2 Respond to the prompt by clicking OK.

Viewing and modifying tab order using Outline view


If some fields on a form overlap, you can display a list of fields in Outline view and sort them by tab order, and then change the tab order as needed by dragging and dropping fields to the position that represents the desired tab order.

To view and change the tab order from Outline view


1 Open the applicable form. 2 In Outline view, select Sort by Tab Order to view the list of fields in their current

tab order. The tab order for a field appears in the list as a tooltip when the mouse is moved over that field, as shown in Figure 6-8.

224

Form and Application Objects Guide

Managing fields

Figure 6-8: Tab order shown in Outline view

Fields that do not have a tab order, such as horizontal or vertical lines, and trim boxes, are not displayed.
3 To change the tab order of a field, drag it to the desired order in the list.

Keep the following conditions in mind as you modify tab order: You can drag and drop only one field at a time. You cannot drag a field from its current parent to a different parent.

NOTE
Sort by Tab Order is disabled when Show Table Overview is active in Outline view. To enable tab order sorting, click the Sort by Tab Order icon at the upper right in Outline view (Figure 6-8). If you change the tab order either in the form editor or through the field properties after displaying the tab order in Outline view, the Outline view is refreshed immediately to reflect the new tab order.

Viewing and modifying tab order using field properties


The following procedure outlines how to view and modify tab order using field properties.

To modify tab order using field properties


1 Select the field whose tab order you want to change. 2 In the field properties, enter the new tab order.

Chapter 6

Creating and managing fields

225

BMC Remedy Action Request System 7.6.04

Z-order options for form objects


Z-order refers to the order in which overlapping objects are positioned. In Developer Studio, z-order defines the order in which multiple overlapping objects are placed on an AR System form. Z-order provides application developers with greater layering options when working with multiple objects that overlap on a form. In previous releases, overlapping objects could be moved only to the front or the back of stack of objects, using two buttons in the BMC Remedy Developer Studio toolbar. Two additional toolbar buttons are now available to enable an object in a stack to be moved forward or backward one position (layer) at a time, as well as to the front or back of the stack.

Selecting z-order from the Developer Studio toolbar


The Developer Studio toolbar provides four toolbar icons (Figure 6-9) that enable additional layering options and allow control of the z-order of fields in a form.
Figure 6-9: Z-order toolbar icons

These icons perform the following actions, from left to right: Bring to FrontMoves an object to the front of the stack, so that it appears on top of all other objects Bring ForwardMoves an object one position forward in the stack Send to BackMoves an object to the back of the stack, so that it is appears behind all other objects Send BackwardMoves an object one position backward in the stack

Selecting z-order from the Layout menu


The four options are also available from the Layout menu.

Positioning an object in a stack


When you select an object to move forward or backward in a stack, the relevant toolbar icons become active. For example, if your form includes four overlapping panels and you select the top panel to be moved (the green panel in Figure 6-10), the Send Backward and Send to Back toolbar icons become active. The Bring to Front and Bring Forward buttons are not active, because the selected panel is already at the top of the stack and cannot be moved forward.

226

Form and Application Objects Guide

Managing fields

Figure 6-10: Moving the top panel backward

If you select Send Backward, the panel is moved one position back in the stack, as shown in Figure 6-11.
Figure 6-11: Moving a panel backward

Using Outline view for objects hidden from view


When smaller objects are hidden behind larger objects, you can use the Outline view to identify their position. For example, the smaller trim text field might be behind a larger panel field and therefore might not be visible. Selecting the trim text field in Outline view enables you to determine its position in the object stack, and you can then move it as needed.

To change the position of an object in a stack using Outline view


1 Select the object in the stack whose position you want to change.

If the object that you want to reposition is hidden behind a larger object, select it in Outline view.
2 In the toolbar (or from the Layout menu), select the button for moving the object

forward or backward. You can set the Entry Mode property of a field to Required at design time or runtime.
Chapter 6 Creating and managing fields 227

BMC Remedy Action Request System 7.6.04

At design time, select a data or attachment field and in the Properties window, select Database > Entry Mode > Required. For more information about field entry modes, see Entry Mode on page 510. At runtime, you can change a fields entry mode from Optional to Required by using a Change Field action. When you set the Entry Mode property to Required for a field, the following changes occurs: The field label becomes bold. By default, an asterisk is added to the end of the label. To add a different character to the label or to add the character to the beginning of the label, see To configure a character identifier for required fields on page 229. The browser or BMC Remedy User validates the field when a request is created. If the field is empty and does not have a default value, the following occurs: In BMC Remedy User, an error message is displayed and the request is not created. In browsers, the field is highlighted (for example, outlined in red), an error message is displayed, and the request is not sent to the server.

NOTE
Although you can use a Change Field action to change a design-time Required field to Optional at runtime, BMC recommends that you do not do this. The optional field would still be validated by the server. If it contained no value, the server would generate an error message.

To change a fields entry mode to Required at runtime


You use an active link with a Change Field action whose Process Entry Mode is set to Required. For information about creating active links that perform Change Field actions, see the Workflow Objects Guide.

To reset a fields entry mode to Optional at runtime


You use an active link with a Change Field action whose Process Entry Mode is set to Not Required. You can use a Change Field action to reset the fields entry mode to Optional at runtime. When this occurs, the field label becomes plain, the asterisk is removed, and the field is no longer validated when a request is created.

228

Form and Application Objects Guide

Working with fields in join forms

To configure a character identifier for required fields NOTE


This identifier will be added to all required field labels in all forms on the AR System server.
1 In a browser or BMC Remedy User, open the AR System Administration Console,

and click System > General > Server Information. The AR System Administration: Server Information form appears.
2 Click the Configuration tab. 3 In the Required Field Identifier area, set the following options:

Prefix on LabelSelect this option to add the character to the beginning of the field label. Suffix on Label(Default) Select this option to add the character to the end of the field label. IdentifierEnter an ASCII character to add as an identifier to the field label. The default is an asterisk.
4 Click OK.

The changes take effect immediately. You do not need to restart the server.

Working with fields in join forms


Field properties function somewhat differently in join forms than in other forms. For each field in a join form, you can perform these tasks: View information about the underlying form and field, such as this: Database properties such as field ID and data type. The name of the field in the underlying form. (This information is helpful for keeping track of field names when they are changed in a join form.) Group permissions. See To view or modify field properties in a join form on page 230. Modify a join fields change history, color, database name, display, font, and help text properties. See To view or modify field properties in a join form on page 230. Add data fields to the join form, or create display-only or trim fields. (Displayonly fields can be inherited or created on the join form.) See Adding data fields to join forms on page 230. Remove fields from the join form. See Removing fields from join forms on page 231.

Chapter 6

Creating and managing fields

229

BMC Remedy Action Request System 7.6.04

To view or modify field properties in a join form


1 Open the appropriate join form. 2 Select the appropriate field in the join form. 3 In the Properties tab, if the properties are not grouped by category, click the Show

Categories button.
4 Modify any field properties in these categories:

Change History Color Database (name only) Display Font Help Text For information about the properties, see Appendix D, Field properties. In the Properties tab, you can also view important read-only information. For example, the Join Information properties provide information about the underlying form that the field came from.
5 Right-click the form, and choose Save.

Adding data fields to join forms


From a database perspective, a join form is a temporary composite table. Therefore, you cannot add data fields directly to a join form. Instead, you can add only data fields that already exist in the underlying primary or secondary form. The following procedure explains how to do that.

NOTE
You can add trim fields (lines, text, and boxes), buttons, panel fields, table fields, and display-only data fields directly to a join form in the same way that you add them to other types of forms.

To add a data field to a join form


1 Open the appropriate join form. 2 Right-click the form, and choose Add Fields from formName, where formName is the

primary or secondary form that contains the appropriate field. The Add Fields dialog box appears. It contains a list of fields in the underlying form that are not on the join form.
3 In the Select Field from formName list, select the appropriate fields, and click OK.

The selected fields appear in the upper-left corner of the join form.
4 Drag the fields to the appropriate position in the join form.

230

Form and Application Objects Guide

Working with fields in join forms

5 To modify the display properties of the new data fields: a Select the field. b In the Properties tab, if the properties are not grouped by category, click the

Show Categories button.


c Modify the field properties in these categories as needed:

Change History Display Help Text See Appendix D, Field properties.


6 Right-click the form, and choose Save.

Removing fields from join forms


You can remove inherited data fields from a join form at any time, but doing so removes them only from the join form view, not from the database. To delete a data field displayed in a join form from the database, you must delete the field from the underlying form (see Deleting fields on page 221.).

NOTE
If you remove a display-only field or trim from a join form, it is deleted.

To remove a field from a join form


1 Open the appropriate join form. 2 Select the appropriate field.

You can also select and remove multiple fields.


3 Choose Edit > Delete. 4 In the confirmation box, click Yes to delete a single field, or click Yes To All to

delete multiple fields.


5 Right-click the form, and choose Save.

Chapter 6

Creating and managing fields

231

BMC Remedy Action Request System 7.6.04

232

Form and Application Objects Guide

Chapter

Working with tables

This section describes how to create and modify tables. The following topics are provided: About table fields (page 234) List view tables (page 235) Tree view tables (page 236) Cell-based tables (page 243) Alert lists (page 245) Results lists (page 246) Creating table fields (page 247) Workflow considerations for table fields (page 268) Displaying images in tables (page 269) Adding buttons and URLs to tables (page 275) Adding a select/cancel all check-box column to tables (page 278) Using drop-down menus in list view tables (page 281) Creating dynamic tables (page 282) Updating tables on-screen only (page 284) Enabling users to customize columns (page 295) Refreshing table fields (page 297)

Chapter 7

Working with tables

233

BMC Remedy Action Request System 7.6.04

About table fields


AR System supports the following types of table fields: List view (see page 235) Tree view (see page 236) Cell-based (see page 243) Alert list (see page 245) Results list (see page 246) These fields can be used by the client and the server. Depending on your needs, you might use the same table field in one context as a server-side table field and in another context as a client-side table field. The choice depends on whether you want to process the information on the client or on the server. When using table fields, remember this important distinction: Active links work on table fields on the client. Filters work on table fields on the server. Client-side table fields enable users to view fields and requests from a form in tabular format. The set of requests displayed in a table is the result of a search of the tables source form. A server-side table field is any table field that appears in server-side workflow in filters or filter guides. You can use server-side table fields with filters to perform calculations on a set of records. For example, you can create filters to find a specific row in a table field (such as the last Entry ID) and then perform actions based on specific criteria. You can also use functions with server-side table fields. For example, you can compute how many records exist for a specified user or for all users. For more information, see the Workflow Objects Guide. Data in server-side table fields is read-only. The most important reason for using server-side table fields is network performance. When you perform actions on large amounts of data (for example, Push Fields actions), server-side tables improve performance because they do not use API calls from the client to the server. To lessen network traffic, use filters with server-side table fields instead of client-side table fields in these situations: To communicate from a form in a browser through the mid tier to the server and back through the mid tier to the browser When BMC Remedy User must communicate with the server

234

Form and Application Objects Guide

List view tables

List view tables


Use a list view table field to display data in a standard table grid with column headings. You can have multiple list view table fields on one form. Operations for a list view table field are contained in a context menu.
Figure 7-1: List view table field with menu

NOTE
To display data in a list view table field when a user opens a form, you must create a Change Field action that refreshes the field when the form is loaded. See the Workflow Objects Guide, Change Field action, page 77.

Structure of list view table fields


In list view table fields, each column represents a field from the source form, and each row represents a request from that form. You specify which fields from the source form are displayed as columns in the table. Almost any field can be a column except attachment fields and diary fields with a data length of more than 255 bytes. The columns themselves are also fields, and you can specify their properties. For more information, see Creating table fields on page 247.

Editing row data in list views


If the Table Drill Down property of a list view table is set to True, users can change the data in list view tables by drilling down to the source request. Users must have access permission for the source form, the fields on the source form, and the table field. See Table Drill Down on page 254. To make a column editable, change the columns Display Type property to Editable. To store the edited values, use workflow to push them to the source request (see Workflow considerations for table fields on page 268).

Chapter 7

Working with tables

235

BMC Remedy Action Request System 7.6.04

Tree view tables


Use a tree view table field to display data from forms in a hierarchical manner, as shown in Figure 7-2.
Figure 7-2: Tree view table field

In tree view tables, users open and close nodes by double-clicking them or by selecting the twisty-right ( ) or twisty-down ( ) sign next to them. Workflow that you create determines what happens when users select a node. For example, a large organization might use a tree view table that lists IT requests by region, as shown in the above figure, to find requests associated with a particular part of the country (Eastern, Central, and Western). The list of requests could be dynamically pulled from the IT database. Users would open the appropriate nodes in the table to find requests for their region. Under each regional node, requests could be grouped by severity (Low, Medium, High, and Urgent). When users click a request leaf node, information about the request could be displayed in fields next to the table, which could be populated through workflow that is triggered by actions associated with the table (see the Workflow considerations for table fields on page 268).

Structure of tree view table fields


A tree view table field can obtain data from only one form, either local or remote. Each level of a tree view table represents a field from the source form (or a column in a list view table). Each node represents one or more requests from that form. Ideally, each leaf node should contain data from a field in one request. For example, the tree view table in Figure 7-3 has these levels:
Table 7-1: Example tree view table levels Level 1 2 Source field Type Severity Nodes Problem, Defect Critical, Severe, Moderate Requests per node Multiple Multiple

236

Form and Application Objects Guide

Tree view tables

Table 7-1: Example tree view table levels Level 3 4 Source field Priority Description Nodes Urgent, High, Medium, Low Customer Downtime, Incorrect Setup, and so on Requests per node Multiple One

Figure 7-3: Example of tree levels, nodes, and leafs


Level 1 Level 2

Single requests (called leaf nodes because they have no child nodes)

Level 3 Level 4

You use the Sort/Levels property of the tree view table field to specify which fields from the source form appear as levels in the tree view (see Setting sort order and visible levels on page 259). You cannot use the following fields as tree levels: Attachment fields, diary fields, or character fields with a data length of more than 255 bytes. Display-only fields Tree levels are also fields, and you can specify their properties. For more information, see Creating table fields on page 247.

Editing data in tree views


If the Table Drill Down property of a tree view table is set to True, users can double-click a leaf node to open the source form, which might show one or more requests. Users must have access permission for the source form, the fields on the source form, and the table field. See Table Drill Down on page 254.

Chapter 7

Working with tables

237

BMC Remedy Action Request System 7.6.04

Arranging nodes in tree views


The nodes in each level of a tree view table are sorted alphanumerically. To arrange nodes in a logical order instead, use hidden sort levels. For example, suppose your source form contains this data:

If you use the Type, Severity, Priority, and Description fields as levels in a tree view table, their data is sorted alphabetically and appears in an unintuitive order:

To arrange each level in a logical manner, add Type Sort, Severity Code, and Priority Code sort fields to the form:

238

Form and Application Objects Guide

Tree view tables

Then add the new sort fields as levels to the tree view table field in the order shown in the preceding figure. The following figure shows the resulting tree view table when the new sort levels are visible and when they are hidden:

When the sort levels are hidden, child nodes of a node in a hidden level appear as children of the first visible ancestor of the hidden node.

IMPORTANT
The best practice is to hide only levels used for sorting. Do not hide levels that contain data leaf nodes. If a visible parent node with multiple hidden leaf nodes is selected, workflow selects only the request represented by the first hidden leaf node in most instances. It does not select the entire set of leaf nodes associated with the parent node. See Selecting requests in list views and tree views on page 242.

Chapter 7

Working with tables

239

BMC Remedy Action Request System 7.6.04

Using PERFORM-ACTION-TABLE-SELECT-NODE
The PERFORM-ACTION-TABLE-SELECT-NODE command selects nodes according to a specified row and column (level) offset. If a tree view table contains hidden levels, this action might select a hidden node. If it does, the selection is rejected and the first visible ancestor is selected instead. For example, in both of the following tables, the action was instructed to select row 1, column (level) 2:

If the action is instructed to select row 1, column 3 in the preceding example, it selects the Change node in both tables.

Avoiding data inconsistencies


You can create problems in tree views if you mismatch the data used for ordering and the data used for display. In the preceding example, the following Type Sort and Type values are always paired:
Type Sort 1 2 Type Problem Defect

Suppose that a request is submitted with Type Sort = 1 and Type = Defect:

240

Form and Application Objects Guide

Tree view tables

This error creates two branches in the tree for the Defect type:

To avoid similar problems, design your data model carefully.

Compatibility with earlier releases


In pre-7.5.00 releases, tree levels marked as hidden were visible in browsers and in BMC Remedy User. In AR System 7.5.00 and later, tree levels marked as hidden will be hidden in all clients.

IMPORTANT
Check applications based on earlier versions of AR System to verify that all levels in tree view tables that should be visible are visible.

Chapter 7

Working with tables

241

BMC Remedy Action Request System 7.6.04

Selecting requests in list views and tree views


Figure 7-4 compares a list view and a tree view derived from the same source form. The list view columns display the source field names, and its rows display the field data. In the tree view, the field data is all that appears.
Figure 7-4: List view versus tree view
List view

Tree view

When users click a row in a list view, they select only one request. To select multiple requests, they must click multiple rows while pressing the Shift or Ctrl key. In a tree view, a node can represent one or more requests. For example, if a user selects D in the previous example, all the requests under D (x and y) are selected. If more than one request is selected, the first request (in this example, x) is considered the primary request, and the other requests are secondary. Workflow uses the primary request for all field value references except those in table loop guides. In table loop guides, all the requests (primary and secondary) are processed in turn. Be aware of this functionality when creating workflow for tree views (see Workflow considerations for table fields on page 268).

Refreshing tree view tables


Unlike list view table fields, tree view table fields do not include operations such as Refresh or Select All. To display data in a tree view table field when a user opens a form in a mode other than Modify, you must create a Change Field action that refreshes the field when the form is loaded. See the Workflow Objects Guide, Change Field action, page 77. For information about refreshing tree view table data in Modify mode, see Refresh on Entry Change on page 253.

242

Form and Application Objects Guide

Cell-based tables

NULL values in tree view table fields


NULL values are displayed in tree view table fields as follows: When users select a parent node and any of its child nodes have data, all child nodes (including NULL nodes) are displayed. If all child nodes are NULL, the first child node appears, but the rest of the nodes are collapsed. If a parent has only one child and that child is NULL, the child is not displayed. NULL data is represented with the words No Value in brackets ([No Value]) unless you specify a different string for the tree view table fields Display NULL Value As property (see page 251).

Cell-based tables
Use a cell-based table field to display a row of data in a single table cell. For example, as shown in Figure 7-5, a list view table field displays text in a traditional grid format with column headings.
Figure 7-5: Traditional list view table field

In a cell-based table field, all the information from a list view table row is displayed in one cell, as shown in Figure 7-6.

Chapter 7

Working with tables

243

BMC Remedy Action Request System 7.6.04

Figure 7-6: Cell-based table field

NOTE
In a browser and BMC Remedy Developer Studio, cell-based tables have the format shown in Figure 7-6. In BMC Remedy User, however, cell-based tables display a list view table (see page 235) at the top and one cell-based table cell at the bottom. The list view is read-only. If the table has no records or if nothing is selected in the list view portion, the fields in the cell portion are unavailable. When a user selects a row in the list view, the cell displays data for that row. When a user updates information in the cell, the corresponding list view row is updated after the user selects a different row in the list view. You can have multiple cell-based table fields on one form, and they can appear in multiple views. Commands for a cell-based table field, such as Refresh and Select All, are in a context menu.

244

Form and Application Objects Guide

Alert lists

Double-clicking a cell or field in a cell opens the source form linked to the table. The source form displays the record shown in the clicked cell. Cell-based tables support chunking. They also support tabbing as follows:
Table 7-2: Tabbing in tables Use this key Tab In a browser To move focus from . . . Outside the table to the table header Header to the first cell field Field to field in a cell Cell to the table footer Footer to a field outside the table Cell to cell Outside the table to the list view part of the table Selected row in the list view to the cell part of the table Field to field in the cell Cell to a field outside the table Row to row in the list view In BMC Remedy User

Up and down arrow

Templates for cell-based tables


You can bind a template to a view field in a cell-based table and specify fields to provide the template parameters. Workflow is not needed to initialize the table. See Binding a template on page 391 for more detail.*

Editing data in cell fields


If the Table Drill Down property of a cell-based table is set to True, users can change the data in cell-based tables by drilling down to the source request. Users must have access permission for the source form, the fields on the source form, and the table field. See Table Drill Down on page 254. To make a cell field editable, change the columns Display Type property to Editable. To store the modified values, use workflow to push them to the source request (see Workflow considerations for table fields on page 268).

Alert lists
Use an alert list table field to display an alert list in the web view:
Figure 7-7: Alert list table field

Each AR System server installation includes the Alert List form, which includes an alert list table field in a web view. To display an alert list, you can add this form to your web-based applications or use your own form.

Chapter 7

Working with tables

245

BMC Remedy Action Request System 7.6.04

A form can have only one alert list table field. The source form for an alert list is the Alert Events form, but when users drill-down in the table field, they see the request on the form that generated the alert. To support drill-down from the alert list table field, the forms originating the alerts must contain results list table fields. For more information about implementing alert lists in a browser, see the Configuration Guide, Using the alert list in a browser, page 258.

Structure of alert list table fields


In alert list table fields, each column represents a field from the Alert Events form, and each row represents a request from that form. The columns themselves are also fields, and you can specify their properties. For more information, see Creating table fields on page 247.

Editing row data in alert lists


If you give users permission, they can change the data in alert lists by drilling down to the source request. See Table Drill Down on page 254.

Results lists
Forms can display results lists in these formats: Results list paneBy default, forms viewed in BMC Remedy User and in a browser include a results list pane that shows a list of requests returned by a search:

In New mode, the pane is hidden. In Search mode, the pane is visible only after a search. For information about customizing results list panes, see Defining search results on page 178.

246

Form and Application Objects Guide

Creating table fields

Results list table fieldThis type of table field is primarily for legacy support. If a form contains a results list table field: In a browser, the results list pane is hidden, and search results are displayed in the table field. Clicking a request in the table field displays the requests data in the form. In BMC Remedy User, the results list pane is visible, and search results are displayed in both the pane and the table field. Clicking a request in the pane displays the requests data in the form. Clicking a request in the table field, however, does not display the requests data in the form. A form can have only one results list table field; each view of the form, however, can display different columns in the results list table field. To add columns to a results list table field, use the Tree/Table Property dialog box (see Creating table fields on page 247).

NOTE
The columns specified in the Results Lists Fields page of the Form Properties dialog box affect the results list pane, not the results list table field (see Defining search results on page 178).

Editing row data in results lists


Users can display and modify a record in the current form by selecting that record in the results list table field.

Creating table fields


This section explains how to create the following types of table fields:
Table 7-3: Types of table fields Table field List view Tree view Cell-based Alert list Results list
1 1

View in a browser? Yes Yes Yes Yes Yes

View in BMC Remedy User? Yes Yes Yes (format differs) No Yes

Results list table fields are primarily for legacy support. For information about results list panes, see Defining search results on page 178.

Chapter 7

Working with tables

247

BMC Remedy Action Request System 7.6.04

To create a table field, perform these procedures:


Step 1 Adding a table field to a form on page 248 Step 2 Customizing table labels on page 255 Step 3 Setting column properties on page 257 Step 4 Setting sort order and visible levels on page 259 Step 5 (Optional) Setting table colors on page 263 Step 6 (Optional) Defining a context menu on page 267 Step 7 Setting the remaining table properties on page 268

Adding a table field to a form


Use this procedure to add a table field to a form and to configure its basic properties.

To add a table field to a form


1 Open the appropriate form. 2 Right-click the form, and choose Create a New Field > tableField.

tableField can be any of these values: Table - List View Table - Tree View Table - Cell Based Alert List Results List The new field appears on the form.
3 Add columns, levels, or cell fields to the table as follows: a Select the table field. b In the Properties tab, select one of the following properties, and click its ellipsis

button: (List view, tree view, alert list, results list) Tree/Table Property (Cell-based) Remote/Local Fields The Tree/Table Property or Remote/Local Fields dialog box appears.

248

Form and Application Objects Guide

Creating table fields

c (List view, tree view, cell-based, alert list only) In the Data Source field, select the

source of the tables data: SERVERThe table displays data from the server specified in the Server Name field and the form specified in the Form Name field. SAMPLE DATAThe table displays data from a server and form that are dynamically selected at runtime according to values that users or workflow enters in certain fields. See Creating dynamic tables on page 282.
d (List view, tree view, cell-based only) In the Server Name list, select the server

that contains the form that supplies the tables data.


e (List view, tree view, cell-based only) To select the form that supplies the tables

data, click the ellipsis button to the right of the Form Name field, and use the Form Selector dialog box to select the appropriate form.

NOTE
(Deployable applications only) To restrict the table to forms in a particular application, select the appropriate application in the Application list of the Form Selector dialog box.
f (List view, tree view, cell-based, alert list only) To limit the data that appears in

the table, click the ellipsis button to the right of the Qualification field, and use the Expression Editor to create a qualification statement. You can use fields from the current form or from the data source form. You can also use keywords. The way qualifications function in table fields is similar to the way that they are used with the Set Fields action. The character limit for strings in a qualification is 4K. For more information, see the Workflow Objects Guide, Building qualifications and expressions, page 49.

WARNING
If you do not include a qualification, all requests in the data source form appear.
g Select fields in the Fields from Remote Form formName and Local Form

formName list and use the arrow buttons to move them to the Table Columns list. The following types of fields are included in the list: Data fields from the source form Display-only fields from the current form The following types of fields are not in the list and cannot be used as columns: Attachment and diary fields with a data length of more than 255 bytes Display-only fields from the source form View fields You can add up to 256 columns to a table.

Chapter 7

Working with tables

249

BMC Remedy Action Request System 7.6.04

TIP
To display a field from the local form in the table but not on the form, hide the field on the form. For list view tables, you can also add buttons and URLs inside the table. See Adding buttons and URLs to tables on page 275. For cell-based tables, fields in the working cell are called cell fields. You can add these types of cell fields: From the current formButton, character fields whose entry mode is Display, menu item, navigation item, trim, and view. (In BMC Remedy User, button and view fields do not appear in the list view portion of the cell-based table, but they do appear in the cell portion.) From the source formData fields.

IMPORTANT
To change a column database ID (for example, to control the ID for purposes of shared workflow), you must change the ID before saving the table field. See To set column properties on page 257.
h To edit a table column heading, right-click the text in the appropriate Column

Title cell, and enter the text that you want to use as the column heading.
i (List view, alert list, results list only) To change the order in which the columns

appear in the table, select the appropriate item in the Table Columns list, and click the Up or Down button. For tree view tables, the order of the fields in the Table Columns list is ignored. Instead, set the order in the Sort/Levels property. See Setting sort order and visible levels on page 259.
j Click OK to close the Tree/Table Property or Remote/Local Fields dialog box. 4 In the Properties tab, set the following table field properties as necessary and save

the form. Properties that do not apply to the type of table that you are creating do not appear in the Properties tab when that table is selected.
Table 7-4: Properties used for table fields (Sheet 1 of 5) Property Auto Fit Columns Description (List view, cell-based, alert list, results list) To scale column widths proportionally to the width of the table field, set this property to True. This ensures that no horizontal scrolling is necessary to see all columns. When this property is set to False, column widths are not scaled, and a horizontal scroll bar might appear so that users can access all columns. See also the Column Width property on page 257. Background Color Background Image (Cell-based only) Background color of all cells in the cell-based table. (Cell-based only) Background image in all cells in the cell-based table. See Adding background images to fields and form views on page 363.

250

Form and Application Objects Guide

Creating table fields

Table 7-4: Properties used for table fields (Sheet 2 of 5) Property Background Image Horizontal Description (Cell-based only) Position of the image in the cell from side to side. Values are Left Center Fill (stretches image to fill the width of the cell) Right Tile (repeats image across the cell from side to side) See Adding background images to fields and form views on page 363. Background Image Vertical (Cell-based only) Position of the image in the cell from top to bottom. Values are Top Center Fill (stretches image to fill the height of the cell) Bottom Tile (repeats image across the cell from top to bottom) See Adding background images to fields and form views on page 363. Display NULL value As (Tree views only) Specify what appears if a node is a NULL value. You can enter a string up to 255 bytes or 80 characters in this field. If you do not specify a value, [No Value] appears in such nodes. For more information about how NULL values are treated in tree view fields, see Tree view tables on page 236. Display Type (List view, tree view, and cell-based only) Use this property to switch the table format at any time. (Converting to a cell-based table is available only if you are connected to AR System server 7.5.00 or later.) You can switch format of a table in different views. For example, one view of a form might display a list view table, and another view might display the same table in a cell-based form. If a tree view is displayed in pre-7.0.00 BMC Remedy User, the format reverts to a table. Fixed Headers (Browser only) To prevent the table header from disappearing when users scroll down a table, set this property to True. In some browsers, editable drop-down list fields in a table might not appear correctly when this property is set to True. Horizontal Space Initial Row Selection (Cell-based only) Width of the space between columns of cells. Specify in points. Specify what happens the first time the table field is displayed: Select First, Fire WorkflowThe first row or child node is selected, and enabled workflow is executed. Select First, No WorkflowThe first row or child node is selected, and no workflow is executed. No SelectionNo item is selected. Layout Style (Cell-based only) Specifies how fields are laid out in each cell. See Panel layout styles on page 329.

Chapter 7

Working with tables

251

BMC Remedy Action Request System 7.6.04

Table 7-4: Properties used for table fields (Sheet 3 of 5) Property Margin Bottom Description (Cell-based only) Space between the bottom of the cell-based table field and the last row of cells. Specify in points. Margin Left (Cell-based only) Space between the left side of the cell-based table field and the first column of cells. Specify in points. Margin Right (Cell-based only) Space between the right side of the cell-based table field and the last column of cells. Specify in points. Margin Top (Cell-based only) Space between the top of the cell-based table field and the first row of cells. Specify in points. Max Rows Enter the maximum number of records that can be returned by a search. The default is 0, which means that the number of records is unlimited unless the Limit Number of Items Returned user preference is selected.
Note: Because users can override the Max Rows setting by selecting Refresh All in

BMC Remedy User, also use an appropriate qualification to control the amount of data that can be returned by a search (see step f on page 249). Alternatively, use chunking to return all records while limiting the number of records displayed at one time. If you enable chunking, this setting is ignored. See the Size of Chunk property in this table. Next Label If chunking is enabled, specify the label that users click to proceed to the next chunk. This label does not appear if the current chunk is the last chunk. See the Size of Chunk property in this table. Panel Border Color Panel Border Thickness Panel Height Panel Width Previous Label (Cell-based only) Color of lines surrounding the cells. (Cell-based only) Dimension of lines surrounding the cells. Specify in points. (Cell-based only) Size of cells from top to bottom. Specify in points. (Cell-based only) Size of cells from left side to right side. Specify in points. (List view, cell-based, results list) If chunking is enabled, specify the label that users click to return to the previous chunk. This label does not appear if the current chunk is the first chunk. See the Size of Chunk property in this table.

252

Form and Application Objects Guide

Creating table fields

Table 7-4: Properties used for table fields (Sheet 4 of 5) Property Refresh on Entry Change Description (Modify mode only) Specifies if table data is refreshed in these situations: A user opens the form containing the table in Modify mode. After opening the form, a user selects a different request in the results list. If users must see the contents of the table in these situations, set this property to True. To reduce performance impact, limit the use of this feature (each refresh requires a database search). When this property is set to False, users can manually refresh table data as follows: (BMC Remedy User) Clicking the table field (BMC Remedy User) Right-clicking the table field and choosing Refresh Table (Browsers) Clicking the Refresh button if the developer supplies it (see Customizing table labels on page 255) To use workflow to refresh a table field, select the Table Refresh check box when defining a Change Field active link action. See also Refreshing table fields on page 297. Refresh Row Selection Specify what happens when a table is refreshed: Retain Selection, Fire WorkflowThe current selection is retained, and enabled workflow is executed. Retain Selection, No WorkflowThe current selection is retained, and no workflow is executed. Select First, Fire WorkflowThe first row or child node is selected and enabled workflow is executed. Select First, No WorkflowThe first row or child node is selected and no workflow is executed. No SelectionNo item is selected. Row Selection Specify how users can select rows in a table: MultipleUsers with selection capability can select multiple rows at the same time. This is the default. SingleUsers with selection capability can select only one row at a time. NoneRow selection is not allowed. In this situation, users cannot Trigger active links Delete a row item Users can Scroll Sort Drill down Create a report

Chapter 7

Working with tables

253

BMC Remedy Action Request System 7.6.04

Table 7-4: Properties used for table fields (Sheet 5 of 5) Property Size of Chunk Description (List view, cell-based, results list only) Use this property to return requests in groups by specifying the size of data chunks (the number of records) that can be displayed in the table: If the value is 0, chunking is disabled. To limit the number of records displayed, see the Max Rows property in this table. If the value is greater than 0, the specified number of records is displayed. For example, if you set Size of Chunk to 5, up to 5 requests are initially displayed. The Max Rows setting is ignored. To customize the labels that users click to navigate from chunk to chunk, modify the table fields Next Label and Previous Label properties.
Note: To set the chunk size of server-side tables for the entire server, use the

Configuration tab in the AR System Administration: Server Information form. See the Configuration Guide, Server InformationConfiguration tab, page 128.
Warning: For tree views, you cannot set chunking in BMC Remedy Developer Studio.

If you set chunking through the AR System configuration file (ar.conf or ar.cfg), users see only the first chunk in the tree, and they cannot display the next chunk. See the Configuration Guide, Server-Side-Table-Chunk-Size, page 390. Table Drill Down Specifies if the source request can be displayed. When this property is set to True, users can double-click the table row in BMC Remedy User or a browser to open the rows source request in Modify mode. For tree views, users must double-click a node. See also Row Header on page 256. Vertical Space Visible Columns (Cell-based only) Width of the space between rows of cells. Specify in points. (Cell-based only) Number of cells displayed horizontally in the cell-based table field. If the Layout Style property of the cell-based table is set to Fill and the table is resized in a browser, the number of visible cells can change dynamically.

254

Form and Application Objects Guide

Creating table fields

Customizing table labels


This procedure explains how to customize the text for hyperlinks, buttons, and informational strings displayed in tables.

To customize table labels NOTE


Tree views do not use label properties.
1 Select the appropriate table field. 2 In the Properties tab, set the following label properties.

Properties that do not apply to the type of table that you are creating do not appear in the Properties tab. You can write strings in different languages for localized form views. To remove a button, function, or message string, clear the appropriate label value.
Table 7-5: Label properties (Sheet 1 of 2) Property Auto Refresh String Location Header Description The message that appears when the Alert Refresh Interval in the Web tab of the AR System User Preference form is set to a value greater than 0. This is an informational message only. The presence of this string does not enable or disable auto refresh. For more information, see the Configuration Guide, Setting user preferences, page 81. Delete Button Footer The label for the alert delete button.
Note: Available only in a browser. In BMC Remedy User, users open the

Alert Events form or use the View Alerts option. Deselect All Footer The label of the hyperlink used to cancel all row selections. To use a select/cancel all check-box column in the table instead of the Select All and Deselect All buttons, see Adding a select/cancel all check-box column to tables on page 278. Number of Entries Returned Header The message that appears when data is loaded into the table. In forms viewed in a browser, the message is displayed in the table header. In BMC Remedy User (where there is no table header), the message appears in the status bar. You can pass these parameters to this string: {0} Starting row number {1} Ending row number {2} Total number of rows returned {3} Maximum number of rows that can be returned If chunking is not enabled, this field defaults to {2} entries returned - {3} entries matched. If chunking is enabled, this field defaults to Showing {0} - {1} of {3}.

Chapter 7

Working with tables

255

BMC Remedy Action Request System 7.6.04

Table 7-5: Label properties (Sheet 2 of 2) Property Preferences Location Header Description When a value is entered in this field, a context menu is added to the table field in BMC Remedy User, and a button is added to the table header in a browser. The value becomes the label for the menu or the button. The default value is Preferences. To disable table column preferences, clear the Preferences field. When this field does not have a value, no preference menu or button appears in the table field, and users cannot set preferences for the table. See Enabling users to customize columns on page 295. Read Button Footer The label for the button used to mark an alert as read.
Note: Available only in a browser. In BMC Remedy User, users open the

Alert Events form or use the View Alerts option. Refresh Button Header The label for the refresh button. In mid tier 6.3.00 and later, the refresh button appears above the table to the right instead of in the footer as in previous versions. Report Button Row Header Footer Body The label for the report button. AR System 7.5.00This property enables developers to specify a column that uniquely identifies the data in a row when a table is displayed in a browser. User assistive technology tools read out the content of the cells in the specified column to provide context for the other data in each row.
Tip: For the best results, specify the first column in the table.

AR System 6.3.007.1.00This property is not supported. In those releases, tables in a browser behave as they do in BMC Remedy User. If users double-click a row, the selected record appears in the new window. Select All Footer The label of the hyperlink used to select all rows. To use a select/cancel all check-box column in the table instead of the Select All and Deselect All buttons, see Adding a select/cancel all check-box column to tables on page 278. Select Column Label Body (Internet Explorer only) The column header that appears above the selection column in Accessibility mode. For all other browsers not in Accessibility mode, this property is ignored at runtime. Table Not Loaded String Unread Header Footer The message that appears when a table is initially displayed. The label for the button used to mark an alert as unread.
Note: Available only in a browser. In BMC Remedy User, users open the

Alert Events form or use the View Alerts option. 3 Right-click the form, and choose Save.

256

Form and Application Objects Guide

Creating table fields

Setting column properties


This procedure explains how to set properties for table columns. (In tree views, columns appear as levels. In cell-based tables, columns appear as cell fields.)

NOTE
In cell-based tables, fields in the working cell are called cell fields. Each cell field is linked to a field on the local or remote form. Initially, all the display properties of a cell field match the display properties of the form field to which it is linked except the bounding area properties, which automatically change to reflect the cell fields position in the working cell. The cell fields Help text also matches the form fields Help text. After creating a cell field, you can change these types of field properties: display, color, font, highlight, permissions, and Help text. You cannot modify other properties, such as the data type or default value.

To set column properties


1 To display column properties in the Properties tab, click the appropriate column

heading, tree level, or cell field.

NOTE
In cell-based tables, only the top-left cell, called the working cell, is editable. Changes made to this cell are immediately replicated in the other visible cells. The working cell is not a separate or child field; it is an integral part of the cell-based table field.
2 In the Properties tab, set the following column properties. Table 7-6: Column properties (Sheet 1 of 2) Property Column Width Description Specify the width of the column in pixels. See also the Auto Fit Columns property on page 250.
Note: Unlike in BMC Remedy User, column size in a browser is not exact. The mid tier

tries to fit columns into the specified table width. If a columns heading and data are narrow and its specified width is wide, the mid tier might shrink the column width to accommodate other columns so that all columns can be seen. Tree views do not use this property. Column Alignment Horizontal alignment: By default, all numeric fields are right-aligned. All other fields are left-aligned. Vertical alignment: By default, all cells default to center vertical alignment.

Chapter 7

Working with tables

257

BMC Remedy Action Request System 7.6.04

Table 7-6: Column properties (Sheet 2 of 2) Property Display Type Description List view, tree view, alert list, results list Select one of these options: Read OnlyUsers cannot change the field value. EditableUsers can change the value in column cells. Editing cells in a table does not affect data in the source form. On refresh or sort, changes that users make are lost, and the data displayed in the table is from the source form. Editing a table also does not affect the modify flag of the form, nor does it affect row colors. Tree views ignore this option. Read Only-HTMLUsers cannot change the field value. In a browser, data in the cell is displayed as HTML. For example, if a cell contains <b>my cell</b>, it is displayed as my cell, but in BMC Remedy User, it is displayed as <b>my cell</b>. Tree views ignore this option. If the column references a display-only field, you can specify the initial value of the column in the Initial Value field (see the following property). For more information about display-only fields, see Entry Mode on page 510. Cell-based Display Type options match the options of the external field to which the cell field is linked. Initial Value (List view, tree view, cell-based, results list) For columns, levels, and cell fields that reference display-only fields, specify the initial value, which can have up to 255 bytes. If the column, level, or cell field has a display type of Editable or Read Only, its initial value can be either text or the value from another column in the same table. If the column, level, or cell field has a display type of Read Only-HTML, its initial value can be a combination of text and column references. If Default Value is a column reference, such as $Column2$, the value in the displayonly column, level, or cell field is set to the corresponding value in that column. If the column reference is invalid, the reference is displayed as text. To specify an initial value, do one or both of the following, depending on the fields display type: Enter text into the Initial Value propertys Value cell. Select the Initial Value property, click its ellipsis button, and use the Field Selector dialog box to specify column references. Alert lists do not use this property. Name To change the column, level, or cell field database name, edit the value of this property.
Note: To change the column database ID (for example, to control the ID for purposes

of shared workflow), you must change the ID after adding the column and before saving the table field. See To add a table field to a form on page 248. Wrap Text To wrap two or more lines of data in table column fields and to allow carriage returns in row data, set this property to True. This property does not apply to tree views. Visible To hide the column, set the Visible property to False. See also Setting sort order and visible levels on page 259.

258

Form and Application Objects Guide

Creating table fields

3 For display-only fields, optionally specify a default value in the Default Value

field. See Appendix D, Field properties.


4 (Cell-based only) If necessary, reconfigure the display properties of the working

cell to accommodate the cell fields. For example, you can change the cells width and height by dragging its borders.

NOTE
The working cell is part of the cell-based table field; it is not a separate field. When the working cell is selected, however, the Properties view shows only the table field properties that apply to the working cell.
5 To hide the table header or footer, right-click the table, and choose Hide Header or

Hide Footer. To redisplay the header or footer, right-click the table, and choose Show Header or Show Footer.

NOTE
The default header and footer contain buttons and menus that enable users to perform table operations such as Refresh and Select All. If you hide the default header and footer, you can use the PERFORM-ACTION-TABLE-* commands to provide these table operations through custom controls. See the Workflow Objects Guide , Using Run Process and $PROCESS$ commands, page 257.
6 Set the remaining properties as necessary.

See Appendix D, Field properties.


7 Right-click the form, and choose Save.

Setting sort order and visible levels


Use the Sort/Levels or Sort property to specify the following: The order in which data appears when a table is refreshedthat is, the primary sort column, the following sort columns, and columns that do not participate in the sort. For example, if you sort first by Assembly Manager and then by Part Number, requests appear alphabetically by Assembly Manager in list views. In tree views, Assembly Manager values are higher in the tree hierarchy (further to the left in the tree display) than Part Number values. The default sort direction (ascending or descending) for each column. Users can click a column heading to re-sort data in the opposite direction. (Tree view) The visible tree levels. If you do not define a sort order for a list view, results list, or alert list, requests appear in ascending order based on the Request ID. If you do not define a sort order for tree views, AR System sorts the tree by the column at the top of the Table Columns list in the Tree/Table Property dialog box.
Chapter 7 Working with tables 259

BMC Remedy Action Request System 7.6.04

NOTE
In BMC Remedy User, you can sort on columns that reference display-only fields, but you cannot do so in a browser.

To set sort order and visible levels


1 Select the appropriate table field. 2 In the Properties tab, select one of the following properties, and click its ellipsis

button: (List view, tree view, alert list, results list tables) Sort/Levels (Cell-based tables) Sort
3 In the Available Columns list of the dialog box, select the columns by which you

want to sort the table data. Table columns associated with character fields whose input length is more than 255 bytes do not appear in the Available Columns list.
4 Click the arrow button to move the selected columns to one of these lists:

(List view, tree view, alert list, results list tables) Sort Order/Tree Levels (Cell-based tables) Sort Order Columns that are not included in the sort order do not appear in tree view tables at runtime. They can still, however, be used in workflow.
5 Use the Up and Down buttons to set the sort order of the columns or levels.

The field that appears at the top of the list has the highest precedence.
6 To change the sort direction of a column, click its Sort Direction cell.

Clicking the cell switches the sort direction between ascending and descending. Ascending order for numeric fields means that values such as lower ID numbers or earlier dates appear at the top of the table list. Ascending order for character fields means that requests are sorted alphabetically from A to Z.
7 (Tree view only) To create hidden sort levels, select each column that you want to

hide, and click its Visibility cell. The Visibility value changes from Visible to Hidden. See Arranging nodes in tree views on page 238.
8 Click OK. 9 Right-click the form, and choose Save.

260

Form and Application Objects Guide

Creating table fields

Sorting tables in browsers versus BMC Remedy User


Table column data is sorted differently in browsers and BMC Remedy User: BrowsersRequests to sort data in table columns are sent to the AR System server, which sorts the underlying data in the database. Hence, display-only columns cannot be sorted in browsers because their data is not stored in the database. In addition, if users change column data in the browser but the change is not pushed to the form, the changed data is not included in the sort because it is not in the database. BMC Remedy UserColumn data is sorted locally, so display-only columns and changes that were not pushed to the form are included in the sort.

Grouping rows in tables and adding a row count


For forms that users view in a browser, you can group table rows in list view tables. Users can expand these logical groups (or folders) to view a subset of table rows. The groups are created from the data entered into the field. For example, if you select the Status field by which to organize groups, the rows of the table are grouped by each status option (for example, Draft, Open, Rejected, and so on) as shown in Figure 7-8. Additionally, you can include a count, which displays how many rows are included in the section.
Figure 7-8: Example of groups in a table

Click to expand or collapse a folder.

Number of rows in the section.

If a user clicks a column to sort the table, the rows within the groups are sorted.

NOTE
When you group rows in list view tables, you can set any workflow, except workflow related to table labels and workflow related to collapsing and expanding folders.

Chapter 7

Working with tables

261

BMC Remedy Action Request System 7.6.04

To create a table that groups rows and displays a count


1 Create a list view table, as described in Adding a table field to a form on

page 248.
2 In the Properties tab, select Sort/Levels property, and click its ellipsis button. 3 In the Available Columns list of the dialog box, select the columns by which you

want to sort the table data. Table columns associated with character fields whose input length is more than 255 bytes do not appear in the Available Columns list.
4 Click the arrow button to move the selected columns to the Sort Order/Tree Levels

list.
5 Use the Up and Down buttons to set the sort order of the columns or levels.

The field that appears at the top of the list has the highest precedence.
6 To change the sort direction of a column, click its Sort Direction cell.

Clicking the cell switches the sort direction between ascending and descending. Ascending order for numeric fields means that values such as lower ID numbers or earlier dates appear at the top of the table list. Ascending order for character fields means that requests are sorted alphabetically from A to Z.
7 To group the tables rows by the data entered in a field: a If the field is not at the top of the Sort Order/Tree Levels list, move the field to

the top.
b For the field you want to use to group rows, click the check box in the Group

column. The field you select appears as a column in the table in BMC Remedy Developer Studio, but when the user opens the form in a browser, the fields data become headings for the grouped rows. For the field by which data is grouped, the following column properties are available but are ignored: Column Color Editable properties Enable Sort Visibility (must be Visible) Width Wrap Text Additionally, the following table properties are not supported for the field by which data is grouped: Checkbox Column Results Color

262

Form and Application Objects Guide

Creating table fields

c To display a count for each group in the table, click the check box in the Count

column. The count appears in the group headings row.


8 Click OK. 9 Right-click the form, and choose Save.

Setting table colors


You can specify colors for the following table elements:
Table type Text List view Tree view Cell-based
1.

Table row Background + +1 + + +

Table cell background +

In cell-based tables, an entire row appears in one cell. To set the background color of that cell, you specify a background color for the row.

Cell background color overrides row background color. The color that indicates a row is selected overrides cell and row background color. Best practice is to limit the use of row and cell color. Too much color defeats the purpose of this feature, which is to draw attention quickly to a noteworthy item. To set row colors, see Setting row colors on page 263. To set cell colors, see Setting cell background colors in list view tables on page 266.

Setting row colors


This section explains how to set the colors of individual rows in a table. The colors are based on the value of one of the selection fields (see page 376) in the table. You can set row text colors in list view, tree view, and cell-based tables. You can set row background colors in list view and cell-based tables.

Chapter 7

Working with tables

263

BMC Remedy Action Request System 7.6.04

For example, you might make the background of all New requests red and the background of all Assigned requests green, as shown in Figure 7-9.
Figure 7-9: Example of row background color in a list view table

Or, as shown in Figure 7-10, you might set the text of engine parts whose status is Backordered in red to alert the assembly manager.
Figure 7-10: Example of row text color in a list view table

Using color in tree view tables


For tree view table fields, only the text of leaf nodes can be colored. If the visible leaf nodes are actually parent nodes associated with multiple child request nodes, the color of a parent leaf nodes is based on the first hidden child request under that parent. For example, the color selection in Figure 7-11 on page 265 is linked to the Priority values in level 6: Urgent (red), High (orange), Medium (blue), and Low (green). In the first and second trees, the leaf nodes represent individual requests and their colors are meaningful. But in the third table, the leaf nodes can represent multiple requests with different priorities; hence, the priority of the first request under each leaf controls the color of the leaf.

264

Form and Application Objects Guide

Creating table fields

Figure 7-11: Colored nodes in tree views

To set row text and background colors


1 In BMC Remedy Developer Studio, select the appropriate table field. 2 In the Properties tab, select the Results Color property, and click its ellipsis button. 3 In the Results Color dialog box, click the ellipsis button to the right of the Selection

Field field.
4 In the Available Fields list of the Field Selector dialog box, double-click the name

of the selection field whose value will determine the row color. A list of all the fields selection values appears in the Results Color dialog box.
5 Specify the text color for one or more selection values: a Click the Color cell of the value, and select Custom from the drop-down list. b Choose a color from the color palette, and click OK.

The selected color is displayed in the color cell.


6 (List view, cell-based only) Specify the background color for one or more selection

values:
a Click the values Background cell, and select Custom from the drop-down list. b Choose a color from the color palette, and click OK.

The selected color is displayed in the Background cell.

Chapter 7

Working with tables

265

BMC Remedy Action Request System 7.6.04

7 When you finish setting results colors for the selection field, click OK. 8 Right-click the form, and choose Save.

Setting cell background colors in list view tables


This section explains how to set the background color of individual cells in a list view table. For example, in Figure 7-12, cell colors help users see at a glance whether the score of a vendors customer satisfaction survey improved or worsened from 2008 (fourth column) to 2009 (last column)that is, moved up or down the color scale from dark red (the lowest) to dark green (the highest).
Figure 7-12: Example of cell background color in a list view table

You can define cell background color for any column in a list view table. The color is based on the value of an associated selection field (drop-down list, radio button, or check box). For example, you might base the color of cells in a Request ID column on the forms Status field. If you set the Status selection value Rejected to red, the cells of all rejected Request IDs will be red. You can use different sets of cell background colors in each form view. If a field value changes at runtime, the table must be refreshed to update the background color.

To set cell background colors in list view tables


1 In BMC Remedy Developer Studio, select the appropriate list view table field. 2 Select the column for which you want to define cell colors. 3 In the Properties tab, select the Column Color property, and click its ellipsis button. 4 In the Column Color dialog box, click the ellipsis button to the right of the Selection

Field field.
5 In the Available Fields list of the Field Selector dialog box, double-click the name

of the selection field whose value will determine the cell background color. A list of all the fields selection values appears in the Column Color dialog box.

266

Form and Application Objects Guide

Creating table fields

6 Specify the background color for one or more selection values: a Click the Color cell of the value, and select Custom from the drop-down list. b Select a color from the color palette, and click OK.

The selected color is displayed in the Color cell.


7 When you finish setting column colors for the selection field, click OK. 8 Save your changes.

Defining a context menu


A context menu contains menu and sub-level menu items, for individual AR System table objects including list view tables, tree view tables, and cell-based tables. For more information about tables, see Chapter 7, Working with tables. You can define and customize a context menu. You can change the order of the menu items and its labels through Developer Studio. You can define workflow to execute upon the selection of the menu item. You can also use workflow to enable or disable menu items or to hide or show menu items. For more information on workflows, see Workflow considerations for table fields on page 268. For more information on creating sub-menus, see Creating character menus on page 301.

To create a context menu


1 Open the form to which you want to add the context menu. 2 Add the required table fields to the form. For more information, see Adding a

table field to a form on page 248.


3 Right click on the table to display the context menu editor. 4 Choose Edit Menu/Navigation Items.

The Edit Menu Bar dialog box is displayed.

NOTE
Alternatively, you can also select the table field and click on Form > Edit Menu/ Navigation Items to display the Edit Menu Bar dialog box.
5 In the Edit Menu Bar dialog box, use the Add Menu, Add Item, and Add Separator

buttons to create menus for the field. These menu items are appended to the default context menu items.

NOTE
To remove the default context menu items from the context menu, set the labels to "" in BMC Remedy Developer Studio.
6 Decide the labels, hierarchy, and order of items in the context menu. 7 Right-click the form, and choose Save.

Chapter 7

Working with tables

267

BMC Remedy Action Request System 7.6.04

Setting the remaining table properties


This procedure explains how to set the remaining table properties.

To set the remaining table properties


1 Select the appropriate table or column. 2 In the Properties tab, set the remaining field properties as needed.

See Appendix D, Field properties.


3 Select the table field, drag it to a position in the form, and adjust its size.

See Arranging fields in a form view on page 412. In a browser, all tables except tree views have space allocated at the top and bottom for buttons such as Refresh and Select All, so make the table field tall enough in BMC Remedy Developer Studio to leave room for the buttons.
4 Right-click the form, and choose Save.

Workflow considerations for table fields


You can use active links and filters to modify data in the source form of a table field as follows:
1 Create a Set Fields action to pull request data from a row into a set of fields.

Users can then modify the values in the set of fields.


2 Create a Push Fields action to push the new values into the request on the source

form.
3 Create a Change Field action to refresh the table.

You can create active link and filter guides that loop through rows in a table. A guide selects each row in a table field (without highlighting) and performs a series of workflow actions on the row. For more information, see the Workflow Objects Guide, Using a filter guide to loop through a table field, page 160. You can also select rows and create statistics on columns such as sums, averages, maximum and minimum values, and total number of rows or total number of nonNULL values in a column. For more information about functions you can use with table fields, see the Workflow Objects Guide, Controlling row selection in a table field, page 300.

Workflow in tree view tables


In a tree view, a node can represent one or more requests. If a node representing multiple requests is selected, the first request listed under the node is considered the primary request, and the other requests are secondary. Workflow uses the primary request for all field value references except those in table loop guides. In table loop guides, all the requests (primary and secondary) are processed in turn. See Selecting requests in list views and tree views on page 242.
268 Form and Application Objects Guide

Displaying images in tables

Workflow in cell-based tables


Workflow in cell-based tablesfor example, firing active links on row selection or setting the current row by using an active link Set Field actionworks the same as it does in other table types, such as list view. Workflow in cell fields works the same as it does in list view table column fields. Clicking a button fires workflow that executes on a Button/Menu Field selection for the cell field. Workflow associated with the control field to which the cell field is linked, however, does not fire. No other field-based workflow execution options, including gain focus and lose focus, are supported for cell fields.

Displaying images in tables


You can display images in list view and tree view tables as shown in Figure 7-13 and Figure 7-14. The images are based on shared image objects stored in the AR System server (see Chapter 10, Working with images). They are displayed by reference.
Figure 7-13: Images in a tree view table

Chapter 7

Working with tables

269

BMC Remedy Action Request System 7.6.04

Figure 7-14: Images in a list view table

In each table node or cell, the images can appear with or without text. When images appear with text, the images and text do not need to have a one-toone relationship. Likewise, the same text can appear with different images (see Emily in Figure 7-13 and Figure 7-14). In standard left-to-right format, images are displayed to the left of the text. In rightto-left format, images are displayed to the right of the text. You cannot change these default positions. Images are always optional. Images can be decorative, or they can convey important information (see the second level/column in Figure 7-13 and Figure 7-14). Images and their alternative text are stored with a form view, so they can be localized.

270

Form and Application Objects Guide

Displaying images in tables

Image size
Best design practice is to make all images in list view and tree view tables the same size. The recommended size is 16 X 16 pixels. Images in list view tables can be any size. AR System uses them as is. Images in tree view tables must be no larger than 16 X 16 pixels. If you use other sizes, they are treated as follows: In browsers, AR System scales larger images down proportionally. For example, a 32 x 25 pixel image is scaled to 16 x 12.5 pixels. If both the height and width of an image are less than 16 pixels, AR System leaves the image as is. BMC Remedy User also scales larger images down, but the scaling is not proportional. For example, a 32 x 25 pixel image is scaled to 16 x 16 pixels. If both the height and width of an image are less than 16 pixels, BMC Remedy User leaves the image as is. Application developers must ensure that their table columns are wide enough to contain the specified images, textual data, or both. In list view tables, row height automatically adjusts to fit the tallest image. The font size, however, does not adjust to accommodate large images.

Image type
You can use BMP, JPEG, JPG, GIF, and PNG image types in both list view and tree view tables. When tree view tables with image types other than BMP are displayed in BMC Remedy User, their images are converted to BMPs. Thus, because BMPs cannot be transparent, tree view tables do not support transparent images in BMC Remedy User.

Image limitations
Images in tables can be associated only with the values in selection fields (dropdown list, radio button, and check box). For example, in a table on a default regular form, images can be linked only to the value of the Status field no matter which column they appear in. Alert lists, results lists, and cell-based tables do not support images displayed by reference. You can, however, display images in cell-based tables by adding a view field to the cell and using a template to display the image inside the view field (see Creating view fields on page 201).

NOTE
Although reserved field ID 1020 acts like a results list in web applications, it does support referenced images. You cannot configure images in tables through AR System skins.
Chapter 7 Working with tables 271

BMC Remedy Action Request System 7.6.04

A column cannot contain both referenced images and buttons, and you cannot use the images in tables feature to display different images on buttons in the same column. For information about adding buttons that contain images to tables, see Adding buttons and URLs to tables on page 275.

Column display types and images


The value of a columns Display Type property affects images as follows:
Value Read Only Editable Description The image appears to the left of the column. The image is not editable. The image appears to the left of the column. The image is not editable. In list view tables in browsers and in all tree view tables, images are displayed in columns based on all types of fields. In list view tables in BMC Remedy User, images are displayed in columns based on all types of fields except selection fields (dropdown list, radio button, and check box). Read Only-HTML In list view tables displayed in browsers, AR System preappends the image to the left of the cell content. The image is not editable.
Note: Tree view tables do not display images in this mode.

Mid-tier performance considerations


By default, images in tables are cached as a form is generated. If you reference lots of images in your tables, consider pre-caching them. This prevents the first user who opens a form from waiting for the images to be cached. Because the images are downloaded to a browser, the larger the image, the slower the download. To improve performance, keep images as small as possible.

Runtime images
If a selection value changes at runtime, you must refresh the table to display the image associated with the new value.

Workflow considerations for images in tables


When the Set Fields action uses the column with images as a source ($columnFieldName$), the value of the column field is always the text, never the image. If the Set Fields action is performed on a table cell that has an image and a text value, the action overwrites the text value. The image is never overwritten. Images are not accessible by workflow because images are decoration, not data. No value is associated with the image.

272

Form and Application Objects Guide

Displaying images in tables

Adding images to tables


This section explains how to perform these tasks: Add images to list view and tree view tables (see the following procedure). Add an image to the root node of a tree view table (see page 274).

To add an image to a list view or tree view table


1 In BMC Remedy Developer Studio, open the form that contains the table. 2 In the table, select the column field in which you want the images to appear. 3 In the Properties tab, select the Column Images property, and click its ellipsis

button. The Column Images dialog box appears.


4 In the Selection Field field, enter the name of the selection field (drop-down list,

radio button, or check box) whose values will determine which images appear in the column selected in step 2. You can enter the name by typing it, by pasting it, or by using the ellipsis button next to the field to display the Field Selector dialog box. When you select a field, the fields selection values automatically appear in the dialog box table.
5 In the table, select the Image cell of a value with which you want to associate an

image, and click its ellipsis button. Images can be associated with the NULL value.
6 In the Image dialog box, click Select. 7 In the Object Selector dialog box, select the appropriate image, and click OK. 8 (Optional) In the corresponding Alternative Text cell, enter a description of the

image to improve usability for vision-impaired users.


9 Repeat step 5 through step 8 for each value that you want to associate an image

with.
10 Click OK. 11 (Tree view tables only) If any levels of the hierarchy contain only images, no text: a Select the table. b On the Properties tab, enter a space in the Value column of the Display NULL

Value As property. Otherwise, the text [No Value] appears next to the images at runtime.
12 To control the sort order of the following types of levels or columns, insert a

hidden sort level or column before such levels or columns: Image-only levels or columns (see the flag level in Figure 7-15) Levels or columns in which images are the only differentiator (see the Emily nodes in Figure 7-15)
Chapter 7 Working with tables 273

BMC Remedy Action Request System 7.6.04

See Arranging nodes in tree views on page 238. (Tree view tables only) If you do not use a hidden sort level in these situations, only the image in the first request in that level appears. For example, see Figure 7-15.
Figure 7-15: Effect of not using hidden sort levels to sort images in tree view tables

To add an image to the root node of a tree view table


1 In BMC Remedy Developer Studio, open the form that contains the tree view table. 2 Select the tree view table. 3 In the Properties tab, enter a label in the Label propertys value cell.

This label appears in the tree view tables root node. For example, in Figure 7-15 on page 274, Bug Fix Priority is the label of the root node.

NOTE
If the Label property does not have a value, the root node does not appear in the table. This is true even when an image is specified for the root node.
4 In the Properties tab, select the Root Node Image value, and click its ellipsis button. 5 In the Root Node Image dialog box, click Select. 6 In the Object Selector dialog box, select the appropriate image, and click OK. 7 Click OK. 8 (Optional) In the Properties tab, enter the appropriate text in the Alternative Text

propertys value cell.


274 Form and Application Objects Guide

Adding buttons and URLs to tables

NOTE
If the tree view table is converted to a list view table, the Label, Root Node Image, and Alternative Text property values are ignored.

Adding buttons and URLs to tables


In pre-7.5.00 versions of AR System, buttons that affected table items had to be outside the tables. To perform actions with the buttons, users first selected a field in a table row and then clicked the button. Now, you can add buttons to columns inside these types of tables: List view Cell-based For example, this table contains three styles of buttons: URL, text, and image:

Image button URL button

Text button

When adding buttons to tables, consider these points: Buttons in tables can have text or images but not both. They can also be displayed as URLs in a browser. For an image button, the Button Label value is used only as a column header. To have no column header, leave this property empty. Row height is determined by the tallest button in the row. Regardless of how high a row is, text in other columns is displayed in a single line without wrapping. If you use the standard button size, rows must be higher than usual, and fewer rows might appear in the tables scrollable area. To preserve standard row height in a browser, use CSS to designate a small font for table button labels (see the BMC Remedy Mid Tier Guide, Customizing AR System style sheets, page 55). Large images on buttons can make table rows difficult to read. After adding an image to a button in a table column, check the result in a browser to make sure that the button and row text are proportional to each other and that a reasonable number of rows appears in the tables scrollable area.
Chapter 7 Working with tables 275

BMC Remedy Action Request System 7.6.04

When users resize rows that contain buttons, the buttons are not scaled. Instead, the buttons are clipped or surrounded by extra white space. Clicking a button causes its row to be selected before any workflow fires. Therefore, the column field values can be used as parameters in workflow because they always refer to the same row in which the button click occurred. In BMC Remedy User, a table can have no more than 64 columns that contain buttons with images. This limitation applies to each view of a form.

Setting workflow for buttons in tables


To execute an active link when users click a button in a table, you must associate the active link with the column field, not with the related button control field that resides on the form. Therefore, in the Execution Options panel for the active link, select the column field, not the control field, in the Field Selector for the Button/Menu Field field:

If you select the control field, the active link will not fire when users click the buttons in the column.

NOTE
You cannot share active links between column and control fields.

276

Form and Application Objects Guide

Adding buttons and URLs to tables

To add a button to a list view table


1 Add the button to the form that contains the table. 2 Select the table. 3 In the Properties tab, select one of the following properties, and click its ellipsis

button: (List view, tree view, alert list, results list) Tree/Table Property (Cell-based) Remote/Local Fields The Tree/Table Property or Remote/Local Fields dialog box appears.
4 In the Fields from Remote Form formName and Local Form formName list, select the

button field.
5 Use the arrow buttons to move the button field to the Table Columns list. 6 Click OK. 7 (Optional) Modify the button column heading: a On the form, select the appropriate column in the table. b In the Properties tab, edit the Label property value. 8 Modify other column properties as necessary.

All standard column properties apply to columns that contain buttons. The values for the Display Type property have these meanings: Read OnlyButton is disabled. EditableButton is enabled. Read Only-HTMLButton is enabled.
9 (Optional) Hide the button that resides on the form.

NOTE
Because rows do not appear in table list views in BMC Remedy Developer Studio, the button is not displayed inside the table at design time. At runtime, however, identical buttons appear in each row of the table.

Chapter 7

Working with tables

277

BMC Remedy Action Request System 7.6.04

To modify a button in a table


1 Select the table. 2 In the Properties tab, select the Tree/Table Property property, and double-click its

ellipsis button.
3 In the Tree/Table Property dialog box, find and note the name of the button field

in the Table Columns list.


4 Close the dialog box. 5 Using the field name found in step 3, find and select the button field that resides

on the form.
6 In the Properties tab, edit the following button properties as necessary:

Alternative text Button Label Display as Flat Image

Image Image Position Label/Text Color

Label Font Maintain Aspect Ratio Scale Image to Fit

Adding a select/cancel all check-box column to tables


By default, table footers contain Select All and Deselect All buttons, which enable users to select all the rows in a table and to cancel all their selections in a table (see Figure 7-16).
Figure 7-16: List view table with Select All and Deselect All buttons

278

Form and Application Objects Guide

Adding a select/cancel all check-box column to tables

When list view and results list tables are displayed in browsers, however, you can replace those buttons with a select/cancel all check-box column (see Figure 7-17).
Figure 7-17: List view table with select/clear all check-box column

TIP
Replacing the buttons with the check-box column reduces clutter in your user interface. When a table has a select/cancel all check-box column, you select rows and cancel your selections as follows: To select all rows or cancel all selections in the table, select or clear the check box in the column header. For example:

To select multiple nonadjacent rows, select each rows check box:

Chapter 7

Working with tables

279

BMC Remedy Action Request System 7.6.04

To select adjacent rows, click anywhere in the first adjacent row, press SHIFT, and then select the check box in the last adjacent row. To select a single row when multiple check boxes are selected, click anywhere in the appropriate row. (The rows check box is not selected, but the row is highlighted and considered selected.) To select a single row when no check box is selected, click anywhere in the appropriate row. (The rows check box is not selected, but the row is highlighted and considered selected.) Whether a table contains the check-box column or not, when multiple rows are selected, the first row selected is the primary selection.

NOTE
If a table contains a significant number of rows, adding a check-box column will degrade performance.

To add a select/cancel all check-box column to a table NOTE


This feature applies only to list view and results list tables in browsers. It is not supported by BMC Remedy User.
1 In BMC Remedy Developer Studio, open the appropriate form, and select the table

field. The table must be a list view or results list table.


2 In the Properties tab, select the Checkbox Column display property. 3 Click the Down arrow. 4 Select True. 5 Right-click the form, and choose Save.

In a browser, the table now contains a check-box column, and the Select All and Deselect All buttons do not appear in the table footer. (In BMC Remedy Developer Studio, the check-box column does not appear in the table, and the Select All and Deselect All buttons are still visible in its footer.)

NOTE
The check-box column is not backward compatible. It will not appear in pre-7.6.03 versions of AR System. Instead, the Select All and Deselect All buttons appear in the table footer.

280

Form and Application Objects Guide

Using drop-down menus in list view tables

Using drop-down menus in list view tables


When the Display Type property of a column in a list view table is set to DropDown Menu, users can change the values in the column at runtime by selecting a new value from a drop-down menu attached to each cell in the column. The column must be based on one of the following field types: Character field with an attached menu Selection field (drop-down list, radio button, or check box)

NOTE
Selection fields whose Display Type is set to Editable behave the same way. The button that users click to display a drop-down menu appears only when a row is selected. For example, see Figure 7-18 and Figure 7-19.
Figure 7-18: Drop-down menu in column based on character field

Figure 7-19: Drop-down menu in column based on radio button selection field

IMPORTANT
If the number of rows exceeds the length of the table, a scroll bar automatically appears on the right side of the table. If the rightmost column contains drop-down menus, the scroll bar covers their access buttons. To avoid this, move the column away from the tables right edge or use the Max Rows or Size of Chunk table properties to prevent the number of rows from exceeding the tables length.

Chapter 7

Working with tables

281

BMC Remedy Action Request System 7.6.04

To add a drop-down menu to a list view table


1 Add a column based on one of the following field types to the table:

Character field with an attached menu The fields Display Type property does not have to be Drop-Down List. To attach a menu to a character field, see Chapter 8, Creating menus. Selection field (drop-down, radio button, and check box) To add columns to tables, see Adding a table field to a form on page 248.
2 Select the new column. 3 In the Properties tab, set the columns Display Type property to Drop-Down

Menu.
4 Save your changes.

Creating dynamic tables


Instead of hard-coding a table data source when you design the table, you can specify that the source server and form be dynamically selected at runtime according to values that a user or workflow enters in specified fields. For example, the Dynamic Table Field form in Figure 7-20 contains two fields (server and form) that can be hidden or display-only. The values entered in these fields (for example, from a Set Fields action) at runtime determine which server and form are used as sources for the table field. Administrators might prefer to hide this functionality from users and use the Window Loaded execution condition instead.
Figure 7-20: Using dynamic table fields

282

Form and Application Objects Guide

Creating dynamic tables

In this example, two requests exist in the Source form on the server cordova. If users open the Dynamic Table Field form in BMC Remedy User, enter cordova as the server and Source as the form, and then refresh the table field, the content of the table is refreshed by the underlying active link workflow. The table field displays the requests from the dynamically specified server and form.

NOTE
You cannot use a dynamic data source in a results list.

To create a dynamic table


1 Select the appropriate table. 2 In the Properties tab, select one of the following properties, and click its ellipsis

button: (List view, tree view, alert list, results list) Tree/Table Property (Cell-based) Remote/Local Fields The Tree/Table Property or Remote/Local Fields dialog box appears.
3 In the Data Source list, select SAMPLE DATA. 4 In the following fields, enter a server and form to use to add sample field

columns to the table: Sample Server Name Sample Form Name The sample server and form are used as temporary references to create the dynamic table field. You can even delete the sample form after saving the table field. What is important is having a sample form from which to select field columns in step 7. At design time, the sample form must contain every field that you are using in the menu. By default, the current server and form are selected. You can select a different server from the drop-down list. To select a different form, click the ellipsis button next to the Sample Form Name field, and use the Form Selector dialog box.

Chapter 7

Working with tables

283

BMC Remedy Action Request System 7.6.04

5 To specify the fields or keywords (for example, $server$) that determine which

server and form are used at runtime, click the ellipsis buttons next to the following fields, and use the Field/Keyword Selector dialog box. Runtime Server Value Runtime Form Value The fields listed in the dialog box come from the sample form. If you select fields, the server and form that a user or workflow enters into those fields at runtime are used as the source server and form whose data the table displays. For the example in Figure 7-20, the Runtime Server Value field would be set to
server, and the Runtime Form Value would be set to form. 6 In the Qualification field, enter a qualification to specify the search criteria that

determines which requests appear in the table. Fields from the sample form can be used in the qualification. Conversion rules do not apply in this case.
7 Select the fields to use as columns in the dynamic table field.

Make sure you select fields that are available on any form that can be dynamically selected at runtime. Otherwise, when users refresh the table, they might receive an error that the field does not exist, and no data will appear in the table. For example, in Figure 7-20, the table includes two columns that are core fields required on every form: Request ID and Short Description.
8 Click OK. 9 Right-click the form, and choose Save.

Dynamically defining table field search criteria


To enable users to define table field search criteria dynamically, use the EXTERNAL() operator. See the Workflow Objects Guide, Operator types, page 216.

Updating tables on-screen only


AR System application developers can create workflow that temporarily adds or deletes rows in list view, tree view, and cell-based tables. This workflow affects onscreen tables only and does not require calls to the server, which improves performance. Both users and workflow can interact with these temporary changes as if they were permanent. To make the changes permanent, developers can create table loop guides to commit the changes to the AR System database.

NOTE
In this topic, row refers to a row in list view tables, a node in tree view tables, and a cell in cell-based tables.

284

Form and Application Objects Guide

Updating tables on-screen only

Results list, alert list, and server-side tables do not support this feature.

NOTE
When you add a temporary table row, the new row does not display any cell background color. For more information, see Setting cell background colors in list view tables on page 266.

To update tables on-screen only


1 Create active links that use the following Run Process commands to add or delete

table rows on-screen.

NOTE
Along with these commands, use existing workflow functionality, such as table loop guides, to create logic that can determine the row index at which to add or delete rows based on existing table data and on data to be added to the table. PERFORM-ACTION-TABLE-ADD-ROWThis command inserts an empty row at the specified position on-screen and sets the row state to New in memory. Both users and workflow can see and select the row. The new row does not display any cell background color (see Setting cell background colors in list view tables on page 266). This command does not commit the row to the database. For example, suppose this command is executed for row index 3 on a table containing the following records:

When the command runs, an empty row is added to list view, tree view, and cell-based table as shown in the following figures.
Figure 7-21: List view table with an empty row inserted at index 3

Chapter 7

Working with tables

285

BMC Remedy Action Request System 7.6.04

Figure 7-22: Tree view table with an empty node inserted at index 3

Figure 7-23: Cell-based table with an empty cell inserted at index 3

PERFORM-ACTION-TABLE-DELETE-ROW On-screen, this command removes the row at the specified index from view. In memory, this command sets the rows state to Deleted. It does not, however, remove the row from the database. Hence, users cannot see or select the row, but the row is visible to workflow, which can still interact with it. For example, table loop guides can step through the row. PERFORM-ACTION-TABLE-SET-ROWSTATEThis command helps workflow manage on-screen table rows without contacting the database. For example, when a user adds an on-screen row, its ROWSTATE is set to 2 (New) in memory, so workflow designed to commit such rows to the database finds them by searching for ROWSTATE 2. To enable users not to commit such rows to the database, you might provide an Undo button whose workflow uses this command to change the state of specified rows from ROWSTATE 2 to ROWSTATE 0 (Unchanged). They are then bypassed by workflow designed to commit new on-screen rows to the database. Hence, you can undo the table row additions without calling the server and database to refresh the table. PERFORM-ACTION-TABLE-CHANGE-ROW-COL-VISIBILITYOnscreen, this command hides the contents of a column field for the current row. You can use this command for list style tables and cell-based tables only For more information about these commands, see the Workflow Objects Guide , Using Run Process and $PROCESS$ commands, page 257. For an example of how these Run Process commands can be used, see Example: temporarily displaying table rows on-screen on page 291.
286 Form and Application Objects Guide

Updating tables on-screen only

2 If you added an empty row in step 1, use one of the following methods to add data

to the row: If the table columns are editable, instruct users to type or paste the data into the row. Use the Set Fields action in an active link. For information about Set Fields, see the Workflow Objects Guide. For special tree view table considerations, see Using Set Fields with temporary tree nodes on page 288.
3 Provide a mechanism that enables users to commit temporary table changes to the

database. For example, create a table loop guide that is triggered when a user clicks Save. The guide can check for a rows state and then take appropriate action on the row. To discover the state of a row during runtime, the guide can use the $ROWCHANGED$ keyword, which returns one of these states:
Table 7-7: Row states returned by the $ROWCHANGED$ keyword Row state Loaded or Unchanged Modified Value 0 1 Description When a table is refreshed, the state of all its rows is set to Loaded (0). When either of the following actions occurs, a rows state is set to Modified (1): A Set Fields action sets data to a Loaded row. Users type or paste data into an editable column. New (added) Deleted (removed) 2 3 When an empty row is added to a table, its state is set to New (2). When a rows state is set to Deleted (3), it is hidden from users but visible to workflow.

If PERFORM-ACTION-TABLE-DELETE-ROW set the row state to Deleted, you could run an action to delete that record from the database. If PERFORMACTION-TABLE-ADD-ROW set the row state to New, you could run a Push Fields action to add the row to the database.

WARNING
If one of the following actions occurs before the changes are saved, the changes will be lost: The table is refreshed (browsers and BMC Remedy User). The table is re-sorted (browsers only). The form is closed (AR System does not prompt users to save their changes).

Chapter 7

Working with tables

287

BMC Remedy Action Request System 7.6.04

Using Set Fields with temporary tree nodes


This section describes various ways to use the Set Fields action with temporary tree nodes.

Adding the last leaf node


To insert the last leaf node in a selected branch, you need to know the number of leaf nodes represented by the branch. To retrieve this information, use the SELECTEDROWCOUNT function with the Set Fields action. For example, if the Italian node is selected in Figure 7-24, this function returns the number of table rows in the underlying form represented by that branch, which is 2. Hence, to insert a row as the last leaf node in the Italian branch, you would run PERFORM-ACTION-TABLE-ADD-ROW on the Italian branch for a row index that is greater than 2.
Figure 7-24: On Italian branch, SELECTEDROWCOUNT returns 2

For information about using functions with the Set Fields action, see Appendix B, Additional ways to use the Set Fields action, in the Workflow Objects Guide. For information about PERFORM-ACTION-TABLE-ADD-ROW, see the Workflow Objects Guide , Using Run Process and $PROCESS$ commands, page 257.

Adding data to empty nodes


When you use the PERFORM-ACTION-TABLE-ADD-ROW command to add an empty node to a tree view table, the values of the subsequent Set Fields action determine the final position of the node. For example, suppose an empty node is added to index 3 of the tree view table in Figure 7-25.
Figure 7-25: Empty node added to row index 3 of tree view table

288

Form and Application Objects Guide

Updating tables on-screen only

The values in the subsequent Set Fields action might leave the new node in the same place, group it under the preceding parent node, or group it under the following parent node. For example, see Figure 7-26.

NOTE
In each case, before performing the Set Fields action, you must select the empty node.
Figure 7-26: Results of Set Fields action on row index 3

Set Fields does not trigger a re-sort of the underlying data set. Thus, to avoid displaying duplicate tree nodes, design your workflow with care. For example, the duplicate node in Figure 7-27 was created by inserting an empty node at index 1 and setting the node values to [Japanese, Ramen].
Figure 7-27: Duplicate nodes produced by poorly designed workflow

Chapter 7

Working with tables

289

BMC Remedy Action Request System 7.6.04

Selecting a leaf node before running Set Fields


Suppose a Set Fields action is created to set the value of the first column field (corresponding to Italian and Japanese) to French in the tree in Figure 7-28. Before the Set Fields action is performed, the Pizza leaf node is selected (see the Before tree). This selection causes Set Fields to set the value of the first column in row index 2. The After tree illustrates the result.
Figure 7-28: Set Fields action on leaf node

Selecting a parent node before running Set Fields


If a node in a tree view table represents multiple values in the underlying data set, the Set Fields action is triggered on the first value only. Hence, if you perform a Set Fields action to change the value of a parent node, only the first (primary) leaf node under the parent is affected. For example, suppose a Set Fields action is created to set the value of the first column field (corresponding to Italian and Japanese) to French in the tree in Figure 7-29. Before the action is performed, Italian is selected (see the Before tree). This selection causes Set Fields to change the value of only the first leaf node in the Italian branch, not all the leaf nodes in the branch. The After tree illustrates the result.
Figure 7-29: Set Fields action to parent node

290

Form and Application Objects Guide

Updating tables on-screen only

Example: temporarily displaying table rows on-screen


In the following form, users create project teams by moving names from the Available Employees table to the Team Members table.

In AR System 7.5.00 and earlier releases, moving a name between these tables required four calls to the server and database each time a name was moved. The calls performed these tasks: Deleted the name from the underlying form of the Available Employees table. Refreshed the Available Employees table to display its updated list on-screen. Added the name to the underlying form of the Team Members table. Refreshed the Team Members table to display its updated list on-screen. Now, AR System can update the on-screen results each time a name is moved between tables without making any calls to the server and database until the user decides to save her changes. At that point, calls are made only to delete and add rows because the on-screen tables are up-to-date and thus do not need to be refreshed. This reduces client/server interaction by 50 percent.

Chapter 7

Working with tables

291

BMC Remedy Action Request System 7.6.04

For example, to create a team that includes Bob Burke and Fred Fairchild, a user and AR System might perform these steps:
1 UserSelect Fred Fairchild in the Available Employees table, and click the right

arrow button.

2 AR SystemOn button click, execute an active link that performs these actions: a Executes this Run Process command to delete row 6 from the Available

Employees table on-screen:


PERFORM-ACTION-TABLE-DELETE-ROW AvailableEmployeesTableFieldID 6 6 is the index of the row in memory. Although the row is no longer visible onscreen, it is still accessible to workflow. In the database, no change occurs.

IMPORTANT
Row indexes do not change after a PERFORM-ACTION-TABLE-DELETE-ROW action. Thus, after step 2 is performed, no on-screen row in the Available Employees table has the index 6. If you try to delete row 6 again before committing this change to the database, nothing occurs. For information about this Run Process command, see the Workflow Objects Guide , Using Run Process and $PROCESS$ commands, page 257.
b Executes this Run Process command to insert an empty row in the Team

Members table on-screen:


PERFORM-ACTION-TABLE-ADD-ROW TeamMembersTableFieldID 1

On-screen and in memory, the new row becomes row index 1 (currently empty). In the database, no change occurs. For information about this Run Process command, see the Workflow Objects Guide , Using Run Process and $PROCESS$ commands, page 257.

292

Form and Application Objects Guide

Updating tables on-screen only

c Performs a Set Fields action to copy data from row 6 in the Available Employees

table to row 1 (currently empty) in the Team Members table on-screen. For information about the Set Fields action, see the Workflow Objects Guide, Specifying workflow actions, page 63. On-line, the tables now look like this:

3 UserSelect Bob Burke in the Available Employees table, and click the right arrow

button.

Chapter 7

Working with tables

293

BMC Remedy Action Request System 7.6.04

4 AR SystemOn button click, execute an active link that performs these actions: a Executes this Run Process command to delete row 2 from the Available

Employees table:
PERFORM-ACTION-TABLE-DELETE-ROW AvailableEmployeesTableFieldID 2 2 is the index of the row in memory. Although the row is no longer visible onscreen, it is still accessible to workflow. In the database, no changes occur. b Executes this Run Process command to insert an empty row above row 1 in the

Team Members table on-screen:


PERFORM-ACTION-TABLE-ADD-ROW TeamMembersTableFieldID 1

On-screen and in memory, the new row becomes row index 1 (currently empty), and row 1 (Fred Fairchild) becomes row index 2. In the database, no change occurs.
c Performs a Set Fields action to copy data from row 2 in the Available Employees

table to row 1 (currently empty) in the Team Members table on-screen. On-line, the form now looks like this:

5 UserClick OK to save the changes. 6 AR SystemOn button click, execute these table loop guides to commit the table

changes to the database: Table Loop Guide 1 checks the state of each Available Employee table row in memory. For each row marked Deleted (rows 2 and 6 in this example), it calls the server to remove the row from the corresponding table in the database. Table Loop Guide 2 checks the state of each Team Member table row in memory. For each row marked New (rows 1 and 2 in this example), it calls the server to add the row to the corresponding table in the database.

294

Form and Application Objects Guide

Enabling users to customize columns

Enabling users to customize columns


You can enable preferences that let users customize columns in table fields. Users can add and remove columns, resize columns, change the order in which columns appear, and change the order in which data is sorted in tables. When logged in to a preference server, users can save these settings to the preference server, making them available for future logins in both BMC Remedy User and the Web. Users can set preferences for any visible table column except columns (levels) in tree views. To enable preferences, make sure the table fields Preferences property has a value. See the Preferences property on page 256. The following sections describe table column preference options and how they work in a browser and in BMC Remedy User.

Browser table preferences


When column preferences are enabled for a table, a button with the default label Preferences appears in the table heading. (To edit the label, see Customizing table labels on page 255.)
Figure 7-30: Preferences button and menu items in web table header
Preferences button. The label can be edited by the administrator in the table fields Preferences property.

When clicked, the button displays a drop-down menu with these options: Add ColumnDisplays a list of columns that the user can add to the table. The list includes only columns that the administrator made visible and that the user previously hid (such columns have a width of zero).

NOTE
If a tables Auto Fit Columns property is set to True, the width of its columns is adjusted at runtime so that they all appear in the table. As a result, when a previously removed column is re-added to the table, its width might not match the administrator-defined width. Remove ColumnDisplays a list of columns that the user can remove from the table. This list includes only columns that the administrator made visible and whose width is greater than zero. Set Refresh IntervalSets the interval at which a tableincluding the results list paneis automatically refreshed. See Setting refresh intervals on page 297.

Chapter 7

Working with tables

295

BMC Remedy Action Request System 7.6.04

ResetRestores column width, visibility, and sort order to administratordefined values. Sets the refresh interval to 0. SaveSaves the current column settings to the users preference server, making them available from a centralized location for future logins. If the user is not logged in to a preference server, this option is disabled.

BMC Remedy User table preferences


When column preferences are enabled for a table, a menu with the default label Preferences appears when users right-click the table. (To edit the label, see Customizing table labels on page 255.)
Figure 7-31: Menu with table preferences submenu in BMC Remedy User

Table column preferences menu

This menu has a submenu that includes these options: Add ColumnDisplays a list of columns that the user can add to the table. The list includes only columns that the administrator made visible and that the user previously hid (such columns have a width of zero). Remove ColumnDisplays a list of columns that the user can remove from the table. This list includes only columns that the administrator made visible and whose width is greater than zero. Column OrderDisplays a dialog box from which users can change the order in which columns appear in the table. ResetRestores column width, column order, visibility, and sort order to administrator-defined values. SaveSaves the current column settings to the users preference server, making them available from a centralized location for future logins. If the user is not logged in to a preference server, this option is disabled.

NOTE
The standard Save operation for a request does not save table preferences. Users must select Save from the table preferences menu to save their table preferences.

296

Form and Application Objects Guide

Refreshing table fields

Refreshing table fields


When a table field is refreshed, information from the tables source form appears beneath the column headings. If entries are added to the source form, they appear in the table the next time the table is refreshed. You can set the Refresh on Entry Change property (see page 253) to refresh data automatically whenever a request is displayed or to require manual refresh. By default, the table or tree is cleared when users switch from one request to another. See also Refreshing tree view tables on page 242.

Setting refresh intervals


In a browser, users can set the interval at which a tableincluding the results list paneis automatically refreshed by choosing Preferences > Set Refresh Interval in the tables header. Valid values are 099 minutes. If the interval is 0, no automatic refresh occurs. (Choosing Preferences > Reset sets the refresh interval to 0.) If a preference server is specified, the refresh interval is saved as a table preference so that it can be restored the next time the user opens the same form. In BMC Remedy User, only the results list can be automatically refreshed at specified intervals (choose View > Auto Refresh in the menu bar).

Locale-specific refresh
To refresh tables with locale-specific information, set the table fields Use Locale property to True. Now, when the table is refreshed, the system returns only requests related to the users locale.

NOTE
In the Advanced tab of the AR System Administration: Server Information form, the Localize Server option must be selected, and the Locale field (see Locale on page 401 and page 406) must be on the form.

Chapter 7

Working with tables

297

BMC Remedy Action Request System 7.6.04

298

Form and Application Objects Guide

Chapter

Creating menus

This section describes how to create and modify character field menus. The following topics are provided: About character field menus (page 300) Creating character menus (page 301) Creating file menus (page 303) Creating search menus (page 306) Creating SQL menus (page 312) Creating data dictionary menus (page 316) Refreshing menus (page 319) Adding (clear) to drop-down lists (page 319) Automatically completing menu entries (page 320) Recording menu change history (page 323) Creating help text for menus (page 324) Modifying menus (page 324) Copying menus (page 325) Deleting menus (page 325) Before performing the procedures described in this section, familiarize yourself with Chapter 5, Creating AR System forms, and Chapter 11, Types of fields.

Chapter 8 Creating menus

299

BMC Remedy Action Request System 7.6.04

About character field menus


Character field menus provide lists of options for quick and consistent field data entry. You can attach menus to any character field in any form on the server, and you can use the same menu for as many character fields as you want. You can create the following types of character field menus: Character MenuDisplays a static list of items configured in BMC Remedy Developer Studio. See Creating character menus on page 301. File MenuDisplays a formatted character menu by referencing an external plain text file. See Creating file menus on page 303. Search MenuDraws menu labels and values from a specified form. Used to create menus that are automatically updated to reflect your systems current data. See Creating search menus on page 306. SQL MenuUses an SQL command to retrieve menu labels and values from a database table. Used to create menus that are automatically updated to reflect the data in a specified database. See Creating SQL menus on page 312. Field Data Dictionary MenuPulls labels and values from field objects in the AR System data dictionary. See Creating data dictionary menus on page 316. Form Data Dictionary MenuPulls labels and values from form objects in the AR System data dictionary. See Creating data dictionary menus on page 316. In the User Preference form, users can set a preference to determine whether menus are displayed in pop-up style, tree view (list box) style, or a combination of both (smart menus). See the Configuration Guide, General tab, page 99.

NOTE
Do not confuse character field menus with menus in the menu bar used to execute active links (see the Workflow Objects Guide, Using buttons and menu bar items to execute active links, page 165) or menus in drop-down list selection fields (see Selection fields on page 376). Initially, menus appear in the Menus list of the server on which they are created. After you add a menu to a character field on a form (or to a Change Field action) that belongs to an application, the menu appears in the applications Menus list.

300

Form and Application Objects Guide

Creating character menus

Creating character menus


A character menu is a static list of items that can have multiple levels. Plan your menu structure before creating a character menu. Figure 8-1 shows an example of a plan, including parent and child menu items.
Figure 8-1: Design for parent and child menus
First-Level Menu (parent) Second-Level Submenu (child) Third-Level Submenu for Clients (child)
AR System Utilities Clients Remedy User Remedy Import Remedy Alert

To create a character menu


1 In BMC Remedy Developer Studio, choose File > New > Character Menu. 2 Select the server on which to create the menu, and click Finish. 3 In the Menu editor, click Add Menu to create a menu item.

An item is added to the Label/Value list (see Figure 8-2). It has two properties: LabelThe text that appears on the menu. The default label is New Menu 0. ValueThe text that is entered into the character field when users select this menu item. The default value is New Menu 0.
Figure 8-2: New character menu

Chapter 8 Creating menus

301

BMC Remedy Action Request System 7.6.04

4 Double-click the default label, and enter an appropriate label.

The maximum length is 80 characters.


5 Double-click the default value, and enter an appropriate value.

The maximum length is 255 bytes. The Value field applies only to selectable menu items (that is, menu items that are not parents of other menu items).
6 To add another item at the same level as the first item, repeat steps 3 through 5. 7 To create a submenu: a Select an item, and click Add Menu Item.

A subitem (child) is added beneath the selected item (parent), and a minus sign appears to the left of the parent item. The minus sign indicates a menu expanded to show its contents. A plus sign indicates a collapsed menu. Clicking either symbol switches between the two states. You can create as many as 15 menu levels (including the top level), but to enhance usability, use as few levels as possible. This figure shows a two-level menu:

NOTE
If some menu levels appear blank in the Menu editor, increase the width of the Label column until they are visible.
b Edit the subitem label and value.

A parent item can have as many as 99 sub-items.


8 To add more menu items, repeat steps 3 through 7 as necessary.

For example, to create the menu hierarchy shown in Figure 8-1:


a Click Add Menu, and replace the default label and value with BMC Remedy AR System. b Select the BMC Remedy AR System item, click Add Menu Item, and replace the default label and value with Utilities. c Click Add Menu, and replace the default label and value with Clients. d To add the third-level items, select the Clients item, click Add Menu Item, and replace the default label and value with BMC Remedy User.

302

Form and Application Objects Guide

Creating file menus

e Click Add Menu, and replace the default label and value with BMC Remedy Data Import. f Click Add Menu, and replace the default label and value with BMC Remedy Alert. 9 You can also perform these actions:

To modify a menu item, double-click and edit its label or value. To expand or collapse all menu hierarchies, click Open All or Close All. These buttons control your view of the menu definition, not how the menu appears in the UI. (When users open menus, the submenus are hidden.) To delete a menu item, select the item, and click Delete. Child menu items are deleted when you delete the parent menu item. To reorder the menu items, select the item to move, and click Up or Down.
10 (Optional) Modify the menus change history.

See Recording menu change history on page 323.


11 (Optional) Add Help text to the menu.

See Creating help text for menus on page 324.


12 Choose File > Save. 13 In the Save Menu As dialog box, enter a name for the menu, and click OK.

Menu names must be unique on each AR System server. Names can have as many as 80 characters, including spaces. Names can include double-byte characters, but avoid using numbers at the beginning of the name.
14 Attach the menu to any character field in any form.

See Creating data fields on page 184 and Menu Name on page 521.

Creating file menus


A file menu displays a formatted character menu by referencing an external plain text file. The file can reside on the client or the server and can be updated at any time. After you update the file, the changes are automatically applied when the menu is refreshed.

To create a file menu


1 In BMC Remedy Developer Studio, choose File > New > File Menu. 2 Select the server on which to create the menu, and click Finish.

Chapter 8 Creating menus

303

BMC Remedy Action Request System 7.6.04

A new file menu appears as shown in Figure 8-3.


Figure 8-3: New file menu

3 In the Refresh list, select the appropriate refresh mode.

See Refreshing menus on page 319.


4 In the Location list, select the location of the file that contains the menu definition:

ClientFile is on the system where the BMC Remedy User client is running. This location is not supported for a browser. ServerFile is on the computer where the AR System server is running.
5 In the File Name field, enter or browse for the path and name of the plain text file

that contains the menu definition. To format this file, see the following section, Menu file format.
6 (Optional) Modify the menus change history.

See Recording menu change history on page 323.


7 (Optional) Add Help text to the menu.

See Creating help text for menus on page 324.


8 Choose File > Save. 9 In the Save Menu As dialog box, enter a name for the menu, and click OK.

Menu names must be unique on each AR System server. Names can have as many as 80 characters, including spaces. Names can include double-byte characters, but avoid using numbers at the beginning of the name.
10 Attach the menu to any character field in any form.

See Creating data fields on page 184 and Menu Name on page 521.

Creating dynamic file menus


Instead of hard-coding a file menus data source, you can specify that the source be dynamically selected at run time according to values that a user or workflow enters in specified fields.
304 Form and Application Objects Guide

Creating file menus

Unlike a file menu that is created in a text file, a dynamic menu is created in a field.

To create a dynamic file menu


1 In BMC Remedy Developer Studio, choose File > New > File Menu. 2 Select the server on which to create the menu, and click Finish. 3 In the Refresh list, select the On Open refresh mode.

See Refreshing menus on page 319.


4 In the Location list, select Client. 5 In the File Name field, enter the path and field ID of the field where you want to create the dynamic menu. For example: arfield://FieldID. FieldID is the field ID of the field. 6 Go to step 6 in To create a file menu on page 303 and perform the remaining

steps in that procedure.

Menu file format


A menu file is a plain text (.txt) file that contains a formatted menu structure and is used with file menus. You cannot use MS Word (.doc) or Rich Text Format (.rtf) files as menu files. Each line in the file contains a definition of a menu item in this format:
label\value

Where
label is the text that appears on the menu. A label can have a maximum of 80 characters. value is the text that is entered into the character field when users select the menu item. A value can have a maximum of 255 bytes.

To create subitems, use tabs (not spaces). Omit the value for any label that has subitems. This example shows a formatted menu structure with three main items, two of which have subitems:
Consulting Services\Consulting Services Training Administrator\Administrator Training User\User Training Support Standard\Standard Support Priority\Priority Support

You can create as many as 15 levels of menus (including the top level). To enhance usability, use as few levels as possible. A parent item can have as many as 99 sub-items.

Chapter 8 Creating menus

305

BMC Remedy Action Request System 7.6.04

If you insert a pound sign (#) at the beginning of a line of text, the text that follows the pound sign is ignored.

NOTE
A menu file for a Unicode system must use the encoding used by that system. A menu file stored on a Unicode AR System server must be a UTF-8-encoded text file without the byte-order mark. You can prepare a text file with a Unicode text editor and then remove the first three bytes (hexadecimal EF BB BF) using a byte editor.

Creating search menus


A search menu draws menu labels and values from a specified form. Use search menus to create menus that are automatically updated to reflect the current data in your system. For example, you could build a menu that displays the names of everyone who has an open help desk request. To do so, select the Submitter field as both the menu Label and Value, and then build a qualification that searches for requests with a Status that is not Closed ('Status' < "Closed").
Figure 8-4: Search menu example

You can create a hierarchical search menu by defining up to five levels. Permissions are verified at the time of the search, so users can see only the items for which they have permission.

To create a search menu


1 In BMC Remedy Developer Studio, choose File > New > Search Menu. 2 Select the server on which to create the menu, and click Finish.

306

Form and Application Objects Guide

Creating search menus

A new file search appears as shown in Figure 8-5.


Figure 8-5: New search menu

3 In the Refresh list, select the appropriate refresh mode.

See Refreshing menus on page 319.


4 In the Data Source list, select one of these options:

SERVERThe menu displays data from the server specified in the Server field and from the form specified in the Form Name field. SAMPLE DATAThe menu displays data from a server and form that are dynamically selected at runtime according to values that users or workflow enters in certain fields. See Creating dynamic search menus on page 310.
5 In the Server list, select the server that contains the form to search. 6 Click the ellipsis button next to the Form Name field.

Chapter 8 Creating menus

307

BMC Remedy Action Request System 7.6.04

7 In the Form Selector dialog box, select the form to search, and click OK.

To shorten the list of available forms: In the Name field, enter the initial letters of the form name. In the Application field, select the appropriate application. To find a form in the Available Forms list, perform one of these actions: Scroll through the list. In the Locate field, enter the first characters of the form name.
8 Select the fields whose values will be used as menu items: a Click Add. b In the Field Selector dialog box, select one or more fields to use as menu items,

and click OK. To shorten the list of available fields, enter the initial letters of the field name in the Name field. To find a field in the Available Fields list, perform one of these actions: Scroll through the list. In the Locate field, enter the first characters of the field name. The field appears in the Label Fields list.
c To change the position of the fields in the menu hierarchy, select a field in the

Label Fields list, and click Up or Down. The first fields values are the first-level menu items, the second fields values are the second-level menu items, and so on. Only the first 80 characters of each field value are displayed. In multilevel menus, items in all levels (except the last level) that do not have a value appear blank. If the last-level menu item does not have a value, it does not appear. In single-level menus, if the first or last item does not have a value, it does not appear. If items in the middle of the menu do not have values, they appear blank.
9 Click the ellipsis button next to Value Field. 10 In the Field Selector dialog box, select the field that contains the information to

load into the field when users choose a menu time, and click OK. The maximum length of Value Field is 255 bytes, of which one byte is reserved for the terminating NULL (\0) character. Therefore, in case of locales that use singlebyte characters, this field displays 254 characters. In case of locales that use multibyte characters, this field displays the maximum number of characters that fit into 254 bytes. For example, if your locale uses double-byte characters, the View Field menu displays only 127 characters.

308

Form and Application Objects Guide

Creating search menus

11 Select or clear the Sort On Label check box:

SelectedMenu items appear alphabetically. Identical menu items are combined. For example:

Cleared (default)Menu items appear in the order that they are retrieved (that is, the form default sort order). Identical menu items are not combined. For example:

When a search menu has a long character field (CLOB column) as a menu label, make sure that the Sort On Label check box is cleared because the database does not support sorting on CLOB columns.

Chapter 8 Creating menus

309

BMC Remedy Action Request System 7.6.04

12 To limit the requests that are included in the menu, click the ellipsis button to the

right of the Qualification field, and use the Expression Editor to create a qualification statement. Make the qualification as specific as possible to avoid creating a menu with an unmanageable number of items. You can use fields from the form specified in the Form Name or Sample Form Name field. You can also use keywords. When referencing the value of a field in the specified form, you must use the $fieldID$, not the field name. For example:
'Problem Summary' = $8$

NOTE
If the qualification includes a field value from the specified form, you cannot use the character field pattern $MENU$ for any field to which the menu is attached. Because the server cannot resolve the field references, that value is always rejected. For more information about building qualifications, see the Workflow Objects Guide, Building qualifications and expressions, page 49.
13 (Optional) Modify the menus change history.

See Recording menu change history on page 323.


14 (Optional) Add Help text to the menu.

See Creating help text for menus on page 324.


15 Choose File > Save. 16 In the Save Menu As dialog box, enter a name for the menu, and click OK.

Menu names must be unique on each AR System server. Names can have as many as 80 characters, including spaces. Names can include double-byte characters, but avoid using numbers at the beginning of the name.
17 Attach the menu to any character field in any form.

See Creating data fields on page 184 and Menu Name on page 521.

Creating dynamic search menus


Instead of hard-coding a search menus data source, you can specify that the source server and form be dynamically selected at runtime according to values that a users or workflow enters in specified fields. For example, the Dynamic Search Menu form in Figure 8-6 contains two fields (server and form) that can be hidden or display-only. The values entered into these fields (for example, from a Set Fields action) at runtime determine which server and form are used as sources for the search menu. Administrators might prefer to hide this functionality from users and use the Window Loaded execution condition instead.

310

Form and Application Objects Guide

Creating search menus

Figure 8-6: Using dynamic search menus

In this example, two requests exist in the Help Desk Request form on the server cordova. If users open the Dynamic Search Menu form in BMC Remedy User, enter cordova in the server field and Help Desk Request in the form field, and then click the search menu button attached to the Submitter field, the search menu queries the Help Desk Request form on the source server (cordova), and the returned values are used to dynamically add items to the search menu (Joe User and Josephine User).

To create dynamic search menus


1 In BMC Remedy Developer Studio, choose File > New > Search Menu. 2 Select the server on which to create the menu, and click Finish. 3 In the Refresh list, select the appropriate refresh mode.

See Refreshing menus on page 319.


4 In the Data Source list, select SAMPLE DATA. 5 In the following fields, enter a server and form to use to add sample items to the

menu: Sample Server Sample Form Name The sample server and form are used as temporary references to create the dynamic search menu. You can even delete the sample form after saving the menu. What is important is having a sample form from which to select Label and Value fields in step 7. By default, the current server is selected. You can select a different server from the drop-down list.

Chapter 8 Creating menus

311

BMC Remedy Action Request System 7.6.04

To select a form, click the ellipsis button next to the Sample Form Name field, and use the Form Selector dialog box. To shorten the list of available forms in the Form Selector dialog box: In the Name field, enter the initial letters of the form name. In the Application field, select the appropriate application. To find a form in the Available Forms list, perform one of these actions: Scroll through the list. In the Locate field, enter the first characters of the form name.
6 To specify the fields that determine which server and form are used at runtime,

click the ellipsis buttons next to the following fields, and use the Field Selector dialog box. Runtime Server Runtime Form Value The fields listed in the Field Selector dialog box come from the sample form. To shorten the list of available fields, enter the initial letters of the field name in the Name field. To find a field in the Available Fields list, perform one of these actions, scroll through the list or enter the first characters of the field name into the Locate field. At runtime, the server and form that a user or workflow enters into the specified fields are queried to dynamically build the search menu. For the example in Figure 8-6, the Runtime Server field is set to server, and the Runtime Form Value is set to form.
7 Go to step 8 on page 308 in To create a search menu, and perform the remaining

steps in that procedure.

Creating SQL menus


An SQL menu pulls values from a database table by using an SQL query. The database values make up the SQL menu items. By using an SQL query to create a menu, your application can do the following: Select data from databases other than AR System databases. Issue complex queries to the database. This is useful for customers who want to use database features specific to a particular database platform. To use SQL queries effectively, you must understand relational databases in general and your relational database in particular. If an SQL query is databasespecific instead of generic, moving the SQL menu definition to another environment might be difficult. Before creating an SQL menu, determine what information you want to search for in the database and what information your SQL query should return. For example, see Sample SQL menu on page 315.

312

Form and Application Objects Guide

Creating SQL menus

To create an SQL menu


1 In BMC Remedy Developer Studio, choose File > New > SQL Menu. 2 Select the server on which to create the menu, and click Finish.

A new SQL menu appears as shown in Figure 8-7.


Figure 8-7: New SQL menu

3 In the Refresh list, select the appropriate refresh mode.

See Refreshing menus on page 319.


4 In the Server list, select the database server to which the SQL query will be issued. 5 In the Label Index List field, enter the numerical index of the database column that

contains the information to display as menu item labels. To create a hierarchical menu, enter up to five index numbers separated by commas. The first number becomes the first level, the second number the second level, and so on. Only the first 80 characters of each field value are displayed. In multilevel menus, items in all levels (except the last level) that do not have a value appear blank. If the last-level menu item does not have a value, it does not appear. In single-level menus, if the first or last item does not have a value, it does not appear. If items in the middle of the menu do not have values, they appear blank.
6 In the Value Index field, enter the numerical index of the database column that

contains the information to load into the field when users choose a menu item. Only the first 255 bytes of each field value are displayed.

Chapter 8 Creating menus

313

BMC Remedy Action Request System 7.6.04

7 Click the ellipsis button next to the SQL Query field, and use the Expression Editor

to build the SQL query to issue to the database to create the menu. For more information, see the Workflow Objects Guide, Using the expression editor and content assist, page 50. Consider these tips when building the query: You can enter only one query for each menu. You cannot enter two queries separated by a semicolon and have both queries run. To run a set of queries, you must create a stored procedure or function and run that. Because AR System does not verify the validity of your query, run the query directly against the database (as a test) before you enter it into the SQL Query field, and then copy and paste the tested query into the SQL Query field. If the query returns unexpected values or results, turn on SQL logging in the database to debug the SQL syntax. An additional debugging strategy is to start an SQL interpreterfor example, isql for Sybase, SQL*Plus for Oracle, Command Center for DB2, or Query Analyzer or Microsoft ISQL/w for Microsoft SQL Serverand enter the same SQL query directly into the database to see what results are returned. If the SQL operation fails, an AR System error message and the underlying database error message appear. You can greatly affect database performance by the way that you write an SQL query. If a row has many columns, a SELECT * SQL command can have a greater performance impact than if you select specific columns. For more information, see your relational database documentation. See also Database security issues on page 316.

NOTE
If the query includes a field value from the specified form in its WHERE clause, you cannot use the character field pattern $MENU$ for any field to which the menu is attached. Because the server cannot resolve the field references, that value is always rejected.
8 (Optional) Modify the menus change history.

See Recording menu change history on page 323.


9 (Optional) Add Help text to the menu.

See Creating help text for menus on page 324.


10 Choose File > Save. 11 In the Save Menu As dialog box, enter a name for the menu, and click OK.

Menu names must be unique on each AR System server. Names can have as many as 80 characters, including spaces. Names can include double-byte characters, but avoid using numbers at the beginning of the name.
12 Attach the menu to any character field in any form.

See Creating data fields on page 184 and Menu Name on page 521.
314 Form and Application Objects Guide

Creating SQL menus

Sample SQL menu


Suppose your SQL menu uses this query:
SELECT BUG_ID, FIRST_NAME, TECHNCN FROM CUSTOMER_INFO

And the query returns the results shown in Figure 8-8.


Figure 8-8: Results returned from the sample SQL query
SELECT BUG_ID, FIRST_NAME, TECHNCN FROM CUSTMR_INFO

1 BUG_ID 5000 5001 5002

2 FIRST_NAME Mary John Mark

3 TECHNCN Zan Fran Tran

Each column has a corresponding numerical index:


1 corresponds to the BUG_ID column 2 to the FIRST_NAME column 3 to the TECHNCN column

Entering 2 into the Label Index List field creates a menu with the contents of the FIRST_NAME column as its menu items (see Figure 8-9).
Figure 8-9: Menu created by the sample SQL query

Entering 1 into the Value Index field inserts values from the BUG_ID column into the field. For example, if a user chooses John from the menu, the BUG_ID value associated with John is entered into the field (see Figure 8-10).
Figure 8-10: Field value if Value Index is set to 1 in sample SQL menu

Entering 3 into the Value Index field inserts values from the TECHNCN column into the field (see Figure 8-11).
Figure 8-11: Field value if Value Index is set to 3 in sample SQL menu

Chapter 8 Creating menus

315

BMC Remedy Action Request System 7.6.04

Entering 2,3 into the Label Index List field creates a hierarchical menu (see Figure 8-12).
Figure 8-12: Hierarchical SQL menu

Database security issues


To use SQL queries, familiarize yourself with your underlying database. All SQL queries are issued by the following users:
Table 8-1: Users of SQL queries Database DB2 Informix Microsoft SQL Server Oracle Sybase User The user who installs AR System The user who controls the arserverd process ARAdmin ARAdmin ARAdmin

If you run AR System as one of these users without permission to access the database, you cannot issue the SQL query. To access nonAR System databases, use the database name as part of the SQL query syntax. For example, for a Sybase or Microsoft SQL Server database:
databaseName.owner.table acme.ARAdmin.CUSTMR_INFO

Creating data dictionary menus


A data dictionary menu pulls labels and values from field or form objects in the AR System data dictionary.

To create a data dictionary menu


1 In BMC Remedy Developer Studio, choose File > New >

dataDictionaryMenuType, where dataDictionaryMenuType is one of these values: Field Data Dictionary MenuThe menu pulls labels and values from field objects in the data dictionary. Form Data Dictionary MenuThe menu pulls labels and values from form objects in the data dictionary.

316

Form and Application Objects Guide

Creating data dictionary menus

2 Select the server on which to create the menu, and click Finish.

A new data dictionary menu appears as shown in Figure 8-13 and Figure 8-14.
Figure 8-13: New field data dictionary menu

Figure 8-14: New form data dictionary menu

3 In the Refresh list, select the appropriate refresh mode.

See Refreshing menus on page 319.


4 In the Server Name list, select the server from which the objects will be selected.

You must have administrator permissions to the specified server. You can also enter a field ID, such as $fieldID$, so that the value in that field is used as the server name at runtime.
5 In the Label Format list, select a format for menu items:

NameThe name of the object in the database. LabelThe label displayed for the object in the client. IDThe ID of the object.

Chapter 8 Creating menus

317

BMC Remedy Action Request System 7.6.04

6 In the Value Format list, select a format for displaying values in the field to which

the menu is attached. You can specify the value name, label, or ID in various formats, such as plain (Name), or enclosed in single quotation marks (Name) or dollar signs ($Name$). You can specify pairs of values separated by semicolons, for example, ID;Label or ;Name;Label.
7 Select the object type to pull data from.

For field data dictionary menus:


a Click the ellipsis button next to the Form Name field, and use the Form Selector

dialog box to select the form that contains the fields to pull data from. To shorten the list of available forms: In the Name field, enter the initial letters of the form name. In the Application field, select the appropriate application. To find a form in the Available Forms list, perform one of these actions: Scroll through the list. In the Locate field, enter the first characters of the form name.
b In the Field Type area, select one or more field types.

The menu will be constructed from fields that match the selected types. For form data dictionary menus:
a In the Form Type list, select the type of form to pull data from.

The menu will be constructed from fields that match the selected types.
b To display hidden forms matching the form type, select the Show Hidden Forms

check box.
8 (Optional) Modify the menus change history.

See Recording menu change history on page 323.


9 (Optional) Add Help text to the menu.

See Creating help text for menus on page 324.


10 Choose File > Save. 11 In the Save Menu As dialog box, enter a name for the menu, and click OK.

Menu names must be unique on each AR System server. Names can have as many as 80 characters, including spaces. Names can include double-byte characters, but avoid using numbers at the beginning of the name.
12 Attach the menu to any character field in any form.

See Creating data fields on page 184 and Menu Name on page 521.

318

Form and Application Objects Guide

Refreshing menus

Refreshing menus
For all menu types except character menus, you must set a refresh mode: On ConnectRetrieves the menu when the user opens the menu after selecting the form. To update the menu, the user must reopen the form. On OpenRetrieves the menu each time the user opens it. Frequent menu retrieval can slow performance, so select this option only when it is critical that the menu be up-to-date. On 15 Minute IntervalRetrieves the menu when the user first opens it and when 15 minutes have passed since the last retrieval. Balances the need to be current and the expense of constant menu retrieval. For a browser, this option behaves the same as On Open. Refresh modes affect only a menus contents, not its definition. The definitions of all menus are updated every time you reconnect to a form.

NOTE
Character menus are static, so they are not refreshed.

Adding (clear) to drop-down lists


By default, when the Display Type property of a character field with a menu is set to Drop-Down List, the last item on the first-level menu in the drop-down list is (clear). You do not manually add the (clear) item to the menu attached to the field. Instead, the item automatically appears at runtime on the drop-down lists of all typescharacter, file, search, SQL, and data dictionaryof character field menus. When users choose (clear), any previously entered value is removed from the field. If the (clear) item does not appear on a drop-down list, add it as follows.

To add (clear) to character field drop-down lists


1 In BMC Remedy Developer Studio, open the appropriate form. 2 Select the character field whose drop-down list you want to modify. 3 In the Properties tab, set the Enable Clear property to Always (the default). 4 Save your change.

At runtime, the (clear) item will appear on the drop-down list in all modes.

Chapter 8 Creating menus

319

BMC Remedy Action Request System 7.6.04

Removing (clear) from drop-down lists


To prevent users from clearing a drop-down list character field in non-Search modes, such as New and Modify, remove the (clear) item from the drop-down list.

NOTE
You cannot remove (clear) from drop-down lists in Search mode.

To remove (clear) from drop-down lists


1 In BMC Remedy Developer Studio, open the appropriate form. 2 Select the field whose drop-down list you want to modify. 3 In the Properties tab, set the Enable Clear property to Search Only. 4 Save your change.

At runtime, the (clear) item will appear on the drop-down list in Search mode only.

Automatically completing menu entries


For forms viewed in a browser, you can turn on an automatic complete feature for character fields that have a menu attached to them. When this feature is configured for a field and a user begins typing text into the field, a list of values that match the text appears. When multiple values are presented, the user can change the selection with the up and down arrow keys or using the mouse. To select a highlighted option, the user presses Enter or click it with a mouse.

By default, the suggestion list is case-insensitive, and it displays the value of the option, not the label. (You can change the configuration so that the menu's labels are displayed instead of its values.)

NOTE
The results in the suggestion list can differ among databases. For example, for an Oracle database, the results are case sensitive by default. For other databases, the results are case insensitive. This feature applies only to forms viewed in a browser (not BMC Remedy User).

320

Form and Application Objects Guide

Automatically completing menu entries

Remember these tips when configuring workflow with character fields that have the automatic complete feature turned on: The Menu/Row/Level Choice workflow condition executes when auto complete is used to fill in the value. If workflow manipulates values of menu selections, you might want to configure auto-complete to show labels rather than values so that the workflow runs properly. The Return/Table or Level Dbl-Clk workflow condition does not run when the user presses Enter as part of the Auto Complete feature (that is, when the selection list is displayed). At other times, the workflow condition executes normally. For more information, see the Workflow Objects Guide.

To enable or disable auto-complete


1 Create a character field. 2 Attach a menu to it. 3 Select the character field. 4 In the Properties tab, set the following properties: Property Auto Complete Description Determines what types of matches are displayed. The options are: None (the default)Disables auto-complete. Leading MatchLists menu options that begin with the text that the user entered in the field. Anywhere MatchLists menu options that include any text that the user entered in the field. Auto Complete After Keystrokes The number of characters the user must type to trigger auto complete. For example, if you enter 3, auto complete displays the list of matching values after the users enters 3 or more characters. The default is 0.
Note: This property is used only for character

fields with a search menu attached. The property is ignored for all other fields.

Chapter 8 Creating menus

321

BMC Remedy Action Request System 7.6.04

Property Auto Complete Hide Menu Button

Description Determines whether the menu box is displayed (False) or hidden (True). The default is False. For large data sets, set this option to True so that users cannot open a menu. Instead, the menu data is used for auto-completion purposes only.

Auto Complete Match By

Determines whether menu values or labels are displayed. The options are: Value (the default)Menu values are displayed and used for matching while typing, as well as for completion. LabelMenu labels are displayed and used for matching while typing, but the menu value is used for completion. (This option is not normally used unless workflow on menu choice operates on the value, but you want to show the label to the user.)

NOTE
At runtime, users can disable auto-complete by pressing Escape while typing in a character field. Auto-complete remains canceled until the field loses focus; it is reenabled the next time the field gets focus.

To configure auto-complete to match by label


1 Follow the steps in To enable or disable auto-complete to enable Auto Complete

for a character field.


2 Select the character field. 3 In the Properties tab, click Auto Complete Match By, and select one of the

following values: Value (the default)Menu values are displayed and used for matching while typing, as well as for completion. LabelMenu labels are displayed and used for matching while typing, but the menu value is used for completion. (This option is not normally used unless workflow on menu choice operates on the value but you want to show the label to the user.)

322

Form and Application Objects Guide

Recording menu change history

Considerations for search menus with large data sets


Fields with search menus that represent a large data set (for example, over 10,000 entries) can cause performance issues and might not show the complete set of matches if the query limit is exceeded. Additionally, if a menu on the character field has thousands of entries, you might not want to display the menu with the field. To avoid these issues, remember these tips: Make sure that the menu is a search menu whose values are character fields in the target data source. Set the Refresh option for the menu to On Open. Because the data set is large, hide the menu button for the character field. (Set the character fields Auto Complete Hide Menu Button property to True.) This ensures that the menu data is used only for auto-completion purposes. Optionally, enable a limit on the number of characters required to be typed before matching begins. (Enter an integer in the character fields Auto Complete After Keystrokes property.)

Workflow considerations
Remember these tips when configuring workflow with character fields that have the automatic complete feature turned on: The Menu/Row/Level Choice workflow condition executes when auto complete is used to fill in the value. If workflow manipulates values of menu selections, you might want to configure auto-complete to show labels rather than values so that the workflow runs properly. The Return/Table or Level Dbl-Clk workflow condition does not run when the user presses Enter as part of the Auto Complete feature (that is, when the selection list is displayed). At other times, the workflow condition executes normally. For more information about workflow conditions, see the Workflow Objects Guide.

Recording menu change history


AR System automatically records the menu owner, the user who last modified the menu, and the last modification date. When a menu has focus in the editor area of BMC Remedy Developer Studio, this information is displayed in the Properties tab. For more information about change history properties, see Appendix D, Field properties.

Chapter 8 Creating menus

323

BMC Remedy Action Request System 7.6.04

Creating help text for menus


You create help text for menus the same way that you create help text for other objects. See the Introduction to Application Development with BMC Remedy Developer Studio guide, Providing help text, page 54.

Modifying menus
Use this procedure to modify a menu.

To modify a menu
1 In AR System Navigator, expand serverName > All Objects. 2 In the All Objects list, double-click the Menus node. 3 To rename the menu: a In the Menus object list, right-click the menu, and choose Rename. b In the Rename Menu dialog box, enter a new name, and click OK. 4 To change the menu type: a In the Menus object list, right-click the menu, and choose Convert Menu To >

newMenuType. The menu is opened in the menu editor.


b Add any information required by the new menu type. c Save your changes. 5 To modify other menu properties: a In the Menus object list, double-click the menu. b In the editor area, modify the menus fields as needed.

For information about those fields, see one of these sections: Creating character menus on page 301 Creating file menus on page 303 Creating search menus on page 306 Creating SQL menus on page 312 Creating data dictionary menus on page 316
6 Choose File > Save.

324

Form and Application Objects Guide

Copying menus

Copying menus
When you save a menu under a different name, the new menu contains all the properties of the original menu. The only difference is the name.

To copy a menu
1 In AR System Navigator, expand serverName > All Objects. 2 In the All Objects list, double-click the Menus node. 3 In the Menus object list, double-click the appropriate menu.

The menu is displayed in the editor area.


4 Choose File > Save As. 5 In the Save Menu As dialog box, enter a new name, and click OK.

Deleting menus
The delete operation is permanent and cannot be undone. You cannot delete a menu that is open in BMC Remedy Developer Studio.

To delete a menu
1 In AR System Navigator, expand serverName > All Objects. 2 In the All Objects list, double-click the Menus node. 3 In the Menus object list, right-click the menu, and choose Delete. 4 In the confirmation message, click OK.

The menu is deleted from the database and the Menus object list.

Chapter 8 Creating menus

325

BMC Remedy Action Request System 7.6.04

326

Form and Application Objects Guide

Chapter

Working with panels

This section describes how to create and modify panel fields. The following topics are provided: About panel fields (page 328) About panels (page 328) About panel holders (page 328) About floating panels (page 333) Creating panel holders and panels (page 336) Modifying panel holders and panels (page 342) Shared fields in panel holders (page 349) Avoiding scroll bars in panels (page 349) Workflow considerations for panels (page 358)

Chapter 9 Working with panels

327

BMC Remedy Action Request System 7.6.04

About panel fields


Panel fields organize other fields in one or more panels that can be displayed in various formats. Grouping information in panel fields within panel holders can make forms easier to use because users do not have to scroll through long forms to find a particular field.
Figure 9-1: Panel holder with panels

About panels
A panel is a container object that enables an application designer to group fields together on a form. Unlike trim boxes, which provide only visual grouping for fields, panels provide visual grouping and true container functionality.
Figure 9-2: Panel

To style a panel, you can use many field properties: background color, including gradient fill; background image, including tiling and filling; opacity (transparent or opaque); border thickness; border color; and rounded corners (browsers only).

About panel holders


A panel holder can contain one or more panels. You can add panels and arrange the panel order and field layout. You can hide a panel holder border and tabbed panels in tabbed panel holders, and use workflow to display individual panels. When creating panels, you can set properties (including field ID) for the panel holder and for each of the panels in it. In addition, you must provide permissions for each of the following levels: Panel holder Each panel in the holder Each field on each panel
328 Form and Application Objects Guide

About panel holders

Users without permission to the panel holder cannot see the panels or the fields in them. Users with permission to the panel holder but not to a panel cannot see any fields on the panel for which they lack permission. See Panel field permissions properties on page 35. AR System provides several options for configuring the layout and behavior of panel holders and the panels in them: You can configure panel holders so that multiple panels are tabbed, stacked to be visible at the same time (and can be collapsed or expanded), or in an accordion display that shows only one panel at a time. You can create panels with a splitter that can be dragged to control the relative sizes of adjacent panels. Panels can have a header area, in which you can specify a header color and add header text in a specified font. (On some browsers, using a large font for header text will cause the header label to wrap.) A panels contents can be configured to enable its size to be changed dynamically. These display options enable you to make better use of screen space and remove clutter on the screen.

Panel layout styles


Panels and form views can contain other fields of any type. To control the way those fields are positioned, both panels and form views can use either XY layout or fill layout. Panels can also use flow layout.

NOTE
In a browser, a panel is positioned using absolute positioning. For optimal appearance, all fields in a panel should share a common style class to enable simultaneous and consistent styling of the fields when customized Cascading Style Sheets are used.

XY layout (default)
In XY layout, fields have a set location specified by X and Y coordinates, as well as a width and height. In earlier releases, the only way containers could determine where to place fields within them was to use these absolute positions and sizes. This layout style is now the default for each container.

Chapter 9 Working with panels

329

BMC Remedy Action Request System 7.6.04

Fill layout
Fill layout is applicable only to forms viewed in a browser; it is ignored in BMC Remedy User and not displayed at design time in BMC Remedy Developer Studio. At runtime, this style enables The screens layout to be automatically readjusted when the browser window changes its size The contents of panels in a splitter panel holder to re-adjust their layout when a user moves the splitter When fill layout is used, the container ignores the fields XY width and height properties at runtime. Instead, each field takes up the containers entire width. The containers height is equally divided by the number of visible contained fields (for example, if you have three fields, each one gets 33% of the containers height). The first field is placed at the 0,0 location and the remaining fields appear in sequence in a vertical orientation. Typically, you place one field in a container that uses fill layout, and that field gets 100% of the width and height. Using fill layout for a form view enables the screen to dynamically adjust to changes in the browser window size. Typically, the view contains a single panel holder. Setting a panel to fill layout is useful in these situations: The panel contains a nested panel holder. The panel contains a fieldsuch as a list view table, tree view table, form view, or data visualization fieldthat can make good use of resizing. You can select fill layout for a panel either by setting the Layout Style property to Fill or by right-clicking the panel and choosing Apply Fill Layout from the menu. The Apply Fill Layout menu selection is available only for standalone panels or panels in panel holders; it is not available for views. If you use fill layout for a panel that includes a table, set the Auto Fit Columns property to False to enable all columns in the table to be visible with a horizontal scroll bar if the table size is larger than the container size.

NOTE
Because BMC Remedy User ignores the fill layout style, use care when selecting the fill layout style for applications that will run in both BMC Remedy User and a browser. Make sure that the absolute positions and the dynamic behavior work correctly in both clients.

330

Form and Application Objects Guide

About panel holders

Flow layout
Flow layout enables you to left-align fields in a panel, and ensure that the fields are equally spaced vertically. This is helpful when you include rich-text-formatting (RTF) fields to be dynamically resized in panels. As the field expands or contracts as the user enters text, all of the fields move up or down vertically. See Adding rich-text-formatting capabilities to a character field on page 186.

NOTE
If you use flow layout in a tabbed panel, background images are shifted from their specified vertical and horizontal position (for example, top-left) to an incorrect position when the form is displayed in a browser. For more information about tabbed panels, see the following section.

Panel holder display types


The following display types are available for panels in a panel holder.

Tabbed
In a tabbed display, only one panel in the container is visible at a time. To view each panel, users click its tab or press the Tab key. Only the horizontal orientation is available for tabbed panel holders. Tabbed panel holders do not have Border Thickness or Border Color properties.
Figure 9-3: Tabbed panel holder

If a tabbed panel holder has more tabs than fit in one row, BMC Remedy Developer Studio and BMC Remedy User display the tabs in two or more rows. In browsers, multiple rows of tabs are not supported. Instead, if the number of tabs exceeds the width of the panel holder, left and right arrows appear. Users click the arrows to scroll to the tabs that extend beyond the width of the holder. The focus remains on the current panel when scrolling occurs.

Chapter 9 Working with panels

331

BMC Remedy Action Request System 7.6.04

Collapsible (stacked)
In a collapsible display, multiple panels in a panel holder can be viewed at the same time, either horizontally or vertically. By default, if a collapsible panel holder contains space that is not allocated to a panel, the extra space is added to the bottom or right-most expanded panel in the holder. This prevents white space from appearing in the holder itself. In addition, you can control the allocation of extra space by assigning priorities to panels (see Distributing slack to avoid scroll bars on page 350) and by using the Fit to Content property (see Using Fit to Content to dynamically resize panels on page 355). At design time, collapsible panels appear to have a fixed size. But at runtime, as various panels in the holder are expanded and collapsed by users or hidden and unhidden by workflow, the other panels in the holder shrink and expand to accommodate the changing space in the holder. This can create visual differences between panels at design time and runtime.
Figure 9-4: Collapsible (stacked) panel holder

Splitter
In a splitter display, multiple panels in a container can be viewed at the same time, either vertically or horizontally, and can be dynamically resized by dragging a splitter control on either side. By default, if a splitter panel holder has two panels, the first panel gets all the extra space. (For information about allocating space among panels, see Avoiding scroll bars in panels on page 349.)
Figure 9-5: Splitter panel holder

332

Form and Application Objects Guide

About floating panels

Accordion
In an accordion display, the content of only one panel in the panel holder visible at a time. Only the headers for the remaining panels are visible. At runtime, when you click a panel header, that panel is expanded to display its contents. If another panel was open, it is automatically collapsed and only its header is visible.

NOTE
Headers cannot be hidden in accordion displays.
Figure 9-6: Accordion panel holder

About floating panels


You can create a panel or panel holder that overlaps a form. For example, you might want to superimpose a panel on a layout that contains other fields. These panels are called floating panels. Floating panels can be modeless, which means that the panel is part of the form, and users can interact with panel and the base form interchangeably. Floating panels can also be modal, which means that users cannot interact with the base form until they close the panel. You can create the following types of floating panels: Modeless floating panelCan be used as a drawer that can be closed and opened. It might also be used as a pull-down menu that contains custom data. This panel is positioned at X and Y coordinates on the form. Dialog (modal) floating panelCan be used as a wizard to request or configure data. It might also be used in a common framework to load external content within a dialog box (such as a content from data visualization field) without requiring an intermediary form. This panel is centered relative to the view. Tooltip floating panelCan be used to show additional details with options to navigate further. It might also replace a conventional tooltip when rich content (such as table fields) is needed. This panel is located relative to the event that triggered the workflow that opened the panel. Figure 9-7, Figure 9-8, and Figure 9-9 show examples of floating panels.
Chapter 9 Working with panels 333

BMC Remedy Action Request System 7.6.04

Figure 9-7: Example of a modeless floating panel

Figure 9-8: Example of a dialog floating panel

334

Form and Application Objects Guide

About floating panels

Figure 9-9: Example of a tooltip floating panel

Characteristics of floating panels


Table 9-1 lists the characteristics for each type of floating panel.
Table 9-1: Characteristics of floating panels (Sheet 1 of 2) Behavioral aspect Modeless floating panel Dialog floating panel Through a Change Field active link action. Tooltip floating panel Through a Change Field active link action.

How the panel is invoked Through a Change Field active link action. The panel can be made initially visible. How the panel is dismissed Through a Change Field active link action.

The panel must be The panel must be initially hidden (enforced initially hidden (enforced at design time). at design time). Through a Change Field active link action. Through a Change Field active link action or a mouse event outside panel area. Keyboard users can press ESC to dismiss the panel.

Positioning of the panel

Based on the floating panel's XY location at design-time.

Located relative to the event that triggered the workflow. (For example, If one dialog floating if a user clicked a link on panel triggers another dialog floating panel, the the form, and that click subsequent panel will not triggered workflow, the panel would appear just be exactly centered. below the field.) Centered relative to the view.

Chapter 9 Working with panels

335

BMC Remedy Action Request System 7.6.04

Table 9-1: Characteristics of floating panels (Sheet 2 of 2) Behavioral aspect Allowing users to resize the panel Modeless floating panel Users cannot resize the panel. Dialog floating panel Tooltip floating panel

Users cannot resize the To allow users to resize panel. the panel, set the Minimum Height and the Minimum Width properties to an integer greater than 0. (A resize handle appears in the lower-right corner of the panel.) Users can move the panel. Users cannot move the panel. See Moving the panel on page 336. Grayed out Normal

Moving the panel

Users cannot move the panel. Normal Keyboard and mouse events are passed to underlying objects.

Appearance of underlying objects How events are handled

A click mouse event Keyboard and mouse events are blocked outside outside of the panel area dismisses the panel. of the visible area of the panel.

How workflow behaves

Workflow that is invoked Workflow does not pause, Workflow that is invoked does not pause when the and users cannot start does not pause when the panel is displayed. new workflow from the panel is displayed. base layer.
Note: If the base form has

workflow that runs on an interval, that workflow still runs.

Creating panel holders and panels


Use these procedures to create panel holders (previously page holders) and panels (previously page fields).

Creating panel holders


To create a panel holder
1 Open the form to which you want to add the panel holder. 2 From the palette, select a panel holder type, and drag it to the form.

For information about panel holder types, see Panel holder display types on page 331. The new panel holder appears on the form. By default, it contains two panels. To add more panels, see Adding a panel to a panel holder on page 341.

336

Form and Application Objects Guide

Creating panel holders and panels

To set properties for a panel holder


1 Select the panel holder, making sure you select the panel holder and not one of the

panels in it. To select collapsible, splitter, and accordion panel holders, move your mouse over the panel holder, and click the grabber that appears at the top of the holder. To select tabbed panel holders, click the holders dashed frame.
2 Assign permissions for the panel holder by selecting Permissions from the

Properties.

NOTE
To view or change the panels at runtime, users must have permission to access the panel holder. See Panel field permissions properties on page 35.
3 Set other panel holder properties as needed.

NOTE
For tabbed panel holders, if you set the Tabless Borderless property to True, BMC Remedy User displays the panel holder with a border and very small tabs without labels. If any of the panels have rounded corners, the panel border is visible. To enable users to navigate from one tabless panel to another, you must create workflow. See Workflow considerations for panels on page 358.

Creating panels
You can place a panel anywhere on a form outside of a panel holder, or you can add panels to a panel holder.

To create a panel
1 Open the form to which you want to add a panel. 2 In the palette, select Panel, drag to the form, and release the mouse where you want

the panel to appear.

Chapter 9 Working with panels

337

BMC Remedy Action Request System 7.6.04

To set properties for a panel


1 Select the panel. 2 On the Properties tab, edit the Label value if necessary.

NOTE
If you do not save the form after adding a panel, the label value also becomes the fields database name (Name property).
3 To specify a custom database ID, modify the ID property before saving the panel. 4 Set permissions for the panel.

NOTE
Users must have permission to view or change the fields in a panel. See Panel field permissions properties on page 35.
5 Set other panel properties as needed:

Field properties See Appendix D, Field properties. This appendix provides brief descriptions of field properties for all AR System forms. The properties are listed in alphabetical order. Background modeSee Background Mode in panel holders on page 344. Color optionsSee Setting color options for panels and panel headers on page 345. Images in panelsSee Adding an image to a panel on page 346. Rounded cornersSee Applying rounded corners to a panel on page 348. Anchoring fields to the right side of a panelSee Anchoring fields to the right side of a form or panel on page 420.
6 Save the form.

Creating floating panels


The following procedures describe how to create the three types of floating panels: To create a modeless floating panel (a drawer) (page 339) To create a dialog floating panel (page 340) To create a tooltip floating panel (page 341)

338

Form and Application Objects Guide

Creating panel holders and panels

To create a modeless floating panel (a drawer)


1 Create a collapsible horizontal panel holder with fixed-size panels.

For the first panel: Make sure that it is a fixed width that is sufficient for the content (for example, a cell-based table). This is done by setting the Initial Size, Maximum Size, and Minimum Size properties equal to the same value. Set the Slack Distribution Order to 10 (a relatively low priority). Turn off the built-in header. (Set the Header State property to Hidden.) Set the Border Thickness property to 0. Set the Background Color property as needed. For the second panel (which is the side bar): Make sure that it is fixed width. Make sure it contains: Vertically-oriented text trim (optional) A close button (If this is not available to users, they will not be able to close the panel.) An expand button
2 To position the panel holder, set the X property to 0, and set the Y property as

needed. The panel holder can be contained by a panel field (such as a body area) or by the entire view (if the location must be maintained even if the header area of the view changes dynamically).
3 Set the panels Float Style property to Modeless. 4 Create the content of the panel (for example, add a cell-based table or any other

fields). To move an existing field to a panel, select the field, right-click, and choose Move Field To. Then, select the panels name from the dialog box that appears, and click OK.
5 Create workflow to:

Alternately hide and show the correct button (close or expand), depending on the state of the panel. Expand or collapse the first panel when the buttons are clicked. Refresh the content (if the panel includes a table). The workflow can be invoked when the window is loaded, or when the panel is expanded. Using a temporary variable, workflow could be invoked only the first time that the panel is expanded.

Chapter 9 Working with panels

339

BMC Remedy Action Request System 7.6.04

To create a dialog floating panel


1 Create a panel or panel holder that will act as a dialog box. 2 Set the panels Float Style property to Dialog.

The panel is displayed in zoom mode (as shown in Figure 9-10), and the panel does not appear on the form. To return to the form, click Back to View. To work with the panel again, select it from the Outline view.
Figure 9-10: Panel in zoom mode

3 To allow the panel to be resizable, set the Minimum Height and Minimum Width

properties to values greater than 20.


4 Create the content in the panel.

To move an existing field to a panel, select the field, right-click, and choose Move Field To. Then, select the panels name from the dialog box that appears, and click OK.
5 Create buttons for actions in the dialog box (for example, Previous, Next, OK,

Cancel, or Close).
6 Create a Change Field active link action that opens the panel (for example, when a

button or field is clicked).


7 Create workflow for each button in the panel.

340

Form and Application Objects Guide

Creating panel holders and panels

To create a tooltip floating panel


1 Create a panel that will act as a tooltip. 2 Set the panels Float Style property to Tooltip.

The panel is displayed in zoom mode (as shown in Figure 9-10), and the panel does not appear on the form. To return to the form, click Back to View. To work with the panel again, select it from the Outline view.
3 Create the content in the panel.

To move an existing field to a panel, select the field, right-click, and choose Move Field To. Then, select the panels name from the dialog box that appears, and click OK.
4 Create a Change Field active link action that opens the panel (for example, when a

button or field is clicked).


5 (optional) Create workflow that will take users to another form or application. 6 (optional) Create workflow that will close the panel.

For example, you might add a Close button. (Note that any mouse action outside of the tooltip will close it, so a Close button is not necessary.)

How users can move a dialog floating panel


To move a panel holder, users must click and drag within an empty part of the panel (or the first panel of a panel holder). To enable users to move the panel, make sure that: Users have access to the first panel of a panel holder. To do this, you must make sure that the first panel is visible. The panel includes empty space. For example, leave some empty space if you include table fields or data visualization fields in the panel.

Adding a panel to a panel holder


To add a panel to a panel holder
1 Select the panel holder to which you want to add a panel. 2 In the Properties, select Add New Panel, and click the ellipsis button. 3 In the Add New Panel dialog box, enter a unique database name for the new panel. 4 Click OK.

Chapter 9 Working with panels

341

BMC Remedy Action Request System 7.6.04

5 Set permissions for the new panel by selecting Permissions and clicking the ellipsis

button.
6 Set other properties for the new panel as needed by selecting the panel and editing

the relevant properties. For more information, see Appendix D, Field properties.

IMPORTANT
To specify a custom database ID (for example, to control the ID for purposes of shared workflow), change the default ID before saving the panel.

Modifying panel holders and panels


Use the following procedures to rearrange the order in which panels appear in a panel holder, to move a panel to another panel or panel holder, to remove a panel from the current view of a form, or to delete a panel from all views of a form.

To rearrange panels in the current form view


1 Select the panel holder containing the panels that you want to rearrange. 2 In the Panels category on the Properties tab, select the Panels property, and click

its ellipsis button. In the Panels dialog box, the Panels in Current View column lists the order in which panels currently appear in the panel holder.
Figure 9-11: Panels dialog box

3 Select a panel, and click Up or Down to change its order. 4 Click OK.

342

Form and Application Objects Guide

Modifying panel holders and panels

To move a panel to another panel or panel holder


1 Right-click the panel to be moved. 2 In the context menu, choose Move Panel To. Figure 9-12: Move Panel to Other Panel Holder dialog box

3 In the Move Panel to Other Panel Holder dialog box, select the new location for the

panel. If you select a panel holder, the panel becomes the last panel of that holder. If you select another panel or a view, the panel becomes a standalone panel on the selected container.

To remove a panel from only the current form view


1 Select the panel holder containing the panels that you want to remove. 2 In the Panels category on the Properties tab, select the Panels property, and click

its ellipsis button.


3 In the Panels dialog box, select a panel, and click Remove.

The panel is removed only from the current view of the form. If the form has only one view, the panel is deleted.
4 Click OK.

To delete a panel from all views in a form


1 Select the panel you want to delete. 2 Right click, and select Delete from the context menu.

The panel is deleted from all views of the form.

Chapter 9 Working with panels

343

BMC Remedy Action Request System 7.6.04

Background Mode in panel holders


Although a panel holder provides no color controls, the Background Mode setting in a panel holder affects the appearance of panels. These options are available: OpaqueFields on the form behind the panel in the stacking order are not visible. TransparentIn a browser, fields on the form behind the panel holder in the stacking order are visible unless covered by a panel with a Background Color or Background Image set. This setting produces a pane of glass effectthe fields behind the panel are visible, but they cannot be accessed.
Figure 9-13: Panel holder Background Mode set to Transparent

A panel holders Background Mode also applies to any white space areas, which are portions of the panel holder unoccupied by a panel. This white space can include The area created outside the panel borders when margins are set The area of the panel holder that has no panels The area below the last panel in a collapsible panel holder The area that appears when all the panels in a panel holder are collapsed
Figure 9-14: White space created by panel margins

White space created by margins

344

Form and Application Objects Guide

Modifying panel holders and panels

Setting color options for panels and panel headers


Use the following procedures to set a background color, gradient effects, and color opacity for a panel or a panel header. By default, the background color of a panel is the color of the form view.

NOTE
Gradient effects are ignored in BMC Remedy User. In tabbed panel holders, colors selected for panels are not applied to the tabs themselves. The background color of the selected tab is white, unless another color is selected for the tab by using Cascading Style Sheets. You can set a color for the tab label text.

To set a background color without a gradient in a panel or panel header


1 In the panel, select the Background Color property (for the panel itself) or the

Header Background Color (for the panel header).


2 In the drop-down Value list, select Custom. 3 In the Custom Color dialog box, click Color, select a color from the palette, and

click OK.
4 Click OK to close the Custom Color dialog box.

To set a background color with a gradient in a panel or panel header


1 In the panel, select the Background Color property (for the panel itself) or the

Header Background Color (for the panel header).


2 In the drop-down Value list, select Custom. 3 In the Custom Color dialog box, select Gradient.

The gradient options become available in the Custom Color dialog box.
Figure 9-15: Gradient options

By default, the target color is white.

Chapter 9 Working with panels

345

BMC Remedy Action Request System 7.6.04

4 (Optional) To change the target color, click Color in the Target Color field, and

select a different target color.


5 Select a gradient effect:

Linear HorizontalThe gradient effect starts with the primary color at the top and goes to the target color at the bottom of the panel. Linear VerticalThe gradient effect starts with the primary color at the left side and goes to the target color at the right side of the panel. Reflected HorizontalThe gradient effect starts with the primary color at the top and bottom and goes to the target color at the center of the panel. Reflected VerticalThe gradient effect starts with the primary color at the center and goes to the target color at the top and bottom of the panel.
6 Click OK.

To set color opacity for a panel


In the Opacity property, enter an opacity value of 0, 1.0, or any decimal value between 0 and 1. For example: 0Color is fully transparent. 1.0 Color is fully opaque. 0.5Color is semitransparent.

NOTE
BMC Remedy User does not support semitransparent colors. If the setting is 0, the color is fully transparent; if the setting is greater than 0, the color is fully opaque.

Adding an image to a panel


You can use an image as the background of a panel field, of the cells in a cell-based table field, or of a form view. For more information about adding an image to a panel, see Adding background images to fields and form views on page 363.

NOTE
Opacity settings for the panel do not affect the opacity of the image. An images opacity is determined by the settings applied in the tool used to create the image.

346

Form and Application Objects Guide

Modifying panel holders and panels

Applying border colors and thickness to a panel


To apply a color to a panel border
1 Select the panel to which you want to apply a border color. 2 Select the Border Color property. 3 Click the Down arrow. 4 Select Custom. 5 Select a color from the color picker, and click OK.

To change a panel borders thickness NOTE


Border thickness cannot be set for panels in tabbed panel holders.
1 Select a panel. 2 Select the Border Thickness property. 3 Enter a value from 0 (no border) to 9 (maximum thickness).

To create a border with the same number of pixels on all sides, enter a single number of pixels, which will be applied to all borders. To create a border with varying thicknesses, enter the number of pixels for each side in the following order: Top, Right, Bottom, Left. Separate each entry with a comma. Enter 0 to have no border. For example, to create a panel with borders that are 2 pixels thick on the right and left and 5 pixels thick on the top and bottom, enter 5,2,5,2. To create a panel with no borders on the top and bottom and borders that are 3 pixels thick on the right and left, enter 0,3,0,3.

NOTE
You can control individual borders on panels with square corners. For panels with rounded corners, you can set only one border thickness. If you enter a list in the Border Thickness property (for example, 2,5,2,5), the first number is used.

Chapter 9 Working with panels

347

BMC Remedy Action Request System 7.6.04

Applying rounded corners to a panel


Use the following procedures to round one or more corners of a panel.

NOTE
Rounded corners are not displayed in BMC Remedy Developer Studio, in BMC Remedy User, or when a panel has a background image.

To apply the same rounding radius to all corners of the panel


In the Rounded Corners property, enter one number (for example, 25). This rounding radius is applied to all corners of the panel.
Figure 9-16: Panel whose corners have the same rounding radius (Web)

To apply different rounding radii to panel corners


In the Rounded Corners property, enter a number for each corner, separated by commas. To apply no rounding to a corner, enter 0. For example: 15,15,0,0. The values are applied in the following order: Top left Top right Bottom left Bottom right
Figure 9-17: Panel with two rounded corners (browser)

348

Form and Application Objects Guide

Shared fields in panel holders

Shared fields in panel holders


A field is in a panel if you drop it on the panel when you create it, if you move it onto the panel, or if you right-click the panel and choose Create a New Field. BMC Remedy Developer Studio does not support adding shared fields to panels. You can view shared fields in panels if the field was shared using BMC Remedy Administrator.

To view shared fields in a panel holder


1 Select a panel holder. 2 In the Properties tab, select Shared Fields, and click its ellipsis button. 3 The Shared Fields dialog box lists the shared fields for the panel holder.

NOTE
If you remove a shared field from a panel, you cannot make it shared again using BMC Remedy Developer Studio.

Avoiding scroll bars in panels


When the contents of a panel exceed its viewable area, the panel displays a vertical scroll bar. If the panel is in a panel holder whose contents exceed its viewable area, the panel holder also displays a scroll bar (see Figure 9-18). If the panel holder has several panels that need scroll bars, the result can be scroll bar overkill. Multiple scroll bars distract users, require additional time to display contents, and detract from the appearance of the panel holder.

Chapter 9 Working with panels

349

BMC Remedy Action Request System 7.6.04

Figure 9-18: Multiple scroll bars in a panel holder

Even if you enlarge the panel holder to accommodate more content, individual panels still might display scroll bars. The following sections explain how to avoid scroll bars in panels: Distributing slack to avoid scroll bars on page 350 Using Fit to Content to dynamically resize panels on page 355 Avoiding scroll bars in view fields on page 357 Including space for panel elements to avoid scroll bars on page 357

Distributing slack to avoid scroll bars


To avoid scroll bars in panels, you can define the order (priority) in which panels in a panel holder can access the panel holders available white space. This white space is called slack, and the priority by which it is allocated is called slack distribution order. Slack distribution order enables you to allocate slack to the panels that need it most. For example, you might have a panel holder with three panels, one of which contains a table that you want users to scan easily with little or no scrolling. You can give this panel the highest slack distribution order so that it will have first access to the available white space in the panel holder. Slack distribution order applies only to panels in collapsible and splitter panel holders; it does not apply to panels in tabbed and accordion panel holders because they display only one panel at a time.

350

Form and Application Objects Guide

Avoiding scroll bars in panels

NOTE
Slack is available only on forms displayed in a browser. BMC Remedy User ignores slack values. The slack distribution order value is a positive number between zero and 100. The higher the number, the lower the priority for allocation of slack. A value of zero (the default) is the highest slack distribution order.
Figure 9-19: Slack distribution order

The panel with the highest priority gets the slack, up to the maximum size set in the panels properties (Figure 9-19). A panel with a dynamic maximum size gets slack until all of its contents fit in the panel without a scroll bar appearing. Any remaining slack is distributed to the next visible panel in the slack distribution order. Panels in a panel holder with the same slack order have slack allocated or denied in a round-robin fashion until all the panels reach their maximum size.

Chapter 9 Working with panels

351

BMC Remedy Action Request System 7.6.04

Properties that affect slack allocation


Slack allocation is affected by these properties: Maximum SizeSpecifies the maximum allowable size for a panel Minimum SizeSpecifies the minimum allowable size for a panel Fit to Content (collapsible panels only)Determines whether a panel is given slack until its content can be viewed without a scroll bar and with no unused white space: TrueThe panel is given slack until its content is visible without a scroll bar or until the panel reaches its maximum size, whichever is the lesser range. False (default)The panel is given the specified amount of slack until its content can be viewed without a scroll bar. If that amount is more than needed, white space appears in the panel. For more information about this property, see Using Fit to Content to dynamically resize panels on page 355. At runtime, the slack is allocated to the panels based on the specified slack distribution order. If the total size of all panels is less than the panel holders size, the panel has positive slack. If the total size of all panels is greater than the panel holders size, the panel has negative slack, and a scroll bar is required on the panel holder to display all the panels. The following examples illustrate how positive and negative slack allocation are applied to panels.

Example 1Positive slack of 150 pixels


Property Slack distribution order Initial size Maximum size Minimum size Panel 1 0 100 500 25 Panel 2 0 100 275 25 Panel 3 0 100 200 25

In this example All panels are set to the default properties. All panels have the same slack distribution order, so the 150 pixels of available slack is allocated to the last visible panel (for a collapsible panel holder) or the second to last visible panel (for a splitter panel holder).

352

Form and Application Objects Guide

Avoiding scroll bars in panels

Example 2Positive slack of 250 pixels


Property Slack distribution order Initial size Maximum size Minimum size Panel 1 1 100 200 25 Panel 2 2 100 150 25 Panel 3 3 100 200 25

In this example Panel 1 has the highest slack distribution order. Panel 1 is allocated 100 pixels of the available slack to equal its maximum size of 200 pixels. The remaining 150 pixels of slack (250 - 100 = 150) is allocated to panel 2. Panel 2, with a maximum size of 150 pixels, uses 50 pixels of slack. Panel 3, with a maximum size of 200 pixels, is allocated the remaining slack.

Example 3Negative slack of -50 pixels


Property Slack distribution order Initial size Maximum size Minimum size Panel 1 0 100 200 25 Panel 2 1 100 200 25 Panel 3 2 100 200 25

In this example Panel 3 has the lowest slack distribution order, so it is resized to eliminate the negative slack which, in turn, eliminates the scroll bar.

NOTE
A panel is never resized to an amount below its minimum size.

Things to consider when allocating slack


Here are some things to consider when allocating slack to a set of panels: How are the panels going to be displayed in a form? For example, are the panels being used as navigation items in a console? You might want to avoid scroll bars so that users can see all the navigation items easily. How much content will the panels in a panel holder need to hold? For example, if one panel in a panel holder will have more content than the other panels, you might want to allocate more slack to that panel by giving it the highest distribution order. Panels with less content need less slack and could be given a lower slack distribution order (or could be allocated a negative slack value).

Chapter 9 Working with panels

353

BMC Remedy Action Request System 7.6.04

What type of content will the panels hold? For example: If all the panels in a panel holder have the same type of content and the importance of each panels content is equal, you can allocate the same slack order to all the panels. If a panel is used for a list of links, you might want to give that panel more slack and to set the Fit to Content property to True to avoid unneeded white space in the panel and to keep the panels appearance consistent if links are added or removed. If a panel has a table in which you want users to see the content with little or no scrolling, give that panel the highest slack order. Figure 9-20 and Figure 921 show a panel whose scroll bars were eliminated by allocating a high slack distribution order to the panel.
Figure 9-20: Table in a panel with scroll bars

Figure 9-21: Assigning a higher slack order to the panel to remove scroll bars

354

Form and Application Objects Guide

Avoiding scroll bars in panels

Allocating slack to panels


Use the following procedure to allocate slack to each panel in a panel holder.

To assign slack order to each panel


1 Determine the layout and content needs of each panel. 2 In the panel properties, assign an initial, minimum, and maximum size to the

panel, or accept the default values.


3 Assign a slack distribution order by accepting the default value of 0 or by entering

a value between 1 and 100.


4 To avoid unneeded white space for a panel given available slack, set the Fit to

Content value to True, or accept the default value of False.


5 Save the form.

Using Fit to Content to dynamically resize panels


The Fit to Content option in panels, when set to True, enables panels to be resized at runtime based on changes to their content. For example, if a panel includes a table to which rows are added, the panel can be enlarged without having a scroll bar added. This feature extends that capability to view fields that contain AR System forms. The following figures show a panel in a view field. Figure 9-22 shows the appearance of a scroll bar when rows are added.
Figure 9-22: Panel with scroll bar

Chapter 9 Working with panels

355

BMC Remedy Action Request System 7.6.04

Figure 9-23 shows the panel after it was resized, which removed the scroll bar.
Figure 9-23: Panel resized to remove scroll bar

Consider the following points when using the Fit to Content option: It includes hidden fields. It is available only to collapsible panels. It can be used to allocate positive slack.

356

Form and Application Objects Guide

Avoiding scroll bars in panels

Avoiding scroll bars in view fields


Users cannot resize view fields. If a view field is too small to display its entire contents, the value of the Scroll Bar property for the view field determines whether scroll bars appear at the bottom and right side of the field. If a view field is included in a panel, the fields Scroll Bar property value and its content determine whether or not a scroll bar appears in the field. The panel containing the view field is resized to fit content only if the view field contains AR System content in the same domain. The panel is not resized if the view field contains content from a source outside AR System, such as a link to an external web page, an image from an external source, or HTML code text. For content other than AR System forms, such as data visualization fields, use the function signature to indicate the scroll dimensions of the content as follows:
function traverseFields(viewObject, orientation) viewObject represents the view field to inspect and resize. orientation represents the orientation of the collapsible panel holder, either

vertical (to eliminate vertical scroll bars) or horizontal (to eliminate horizontal scroll bars). To enable a panel to be resized to fit to its content, set the Scroll Bar property for the view field to Default. If the setting is Hide, the scroll bars are already hidden. A panel can grow only to its maximum size.

Including space for panel elements to avoid scroll bars


Another way to avoid scroll bars in panels and panel holders is to include sufficient space for the following elements when you design your forms.
Table 9-2: Space requirements for panel and panel holder elements Field type Panel Element Border thickness Header height Panel holder Border thickness Margins Size 09 pixels (adjustable). See To change a panel borders thickness on page 347. 20 pixels (fixed). 1 pixel (fixed). See the Borderless property description in Appendix D, Field properties. 09 pixels (adjustable). See the Margin Bottom, Margin Left, Margin Right, and Margin Top property descriptions in Appendix D, Field properties.

For example, suppose you create a borderless panel holder that has 9-pixel margins on all sides and whose panels cover all its remaining space. If you then make the 1-pixel borders visible, you must change the thickness of all the margins to 8 pixels to prevent scroll bars from appearing in the panel holder.

Chapter 9 Working with panels

357

BMC Remedy Action Request System 7.6.04

Workflow considerations for panels


If the Tabless Borderless property of a tabbed panel holder is set to True, you must create workflow to enable users to change which panel is displayed. For information about removing borders and tabs, see To create a panel holder on page 336. Remember these considerations when building workflow for panels: When active links are executed, a specific panel gains focus when any of these conditions occur: A user clicks a panel. A user tabs to a panel. An active link sets focus to a panel. A panel in a tabbed panel holder loses focus when any user or workflow operation causes the focus to move from a tab. Panel visibility is not always dependent on field focus. You can use the following workflow actions with panel fields: Set FieldsUse this action on a panel holder to bring a panel (by using its database name) to the top of the panel holder without setting focus. Change FieldUse this action to change focus to a panel, to make a panel or panel holder hidden or visible, or to set the panel label color. You can use a panel holder as a data source in workflow. For example, you can use a Run If qualification such as 'PageHolder' = "Page3". If users have access to a table field in a panel or panel holder but they do not have access to the panel or panel holder that contains the table field, active links and active link guides cannot access that table. To work around this issue, give users permissions to the panel holder, and then hide the holder. For more information, see the Workflow Objects Guide.

Using workflow to expand and collapse panels


In addition to letting users expand or collapse panels from the header, you can use Active Link Execute On conditions and Change Field options to expand and collapse panels. You can also use the execute-on conditions On Expand and On Collapse to apply workflow actions when a panel is expanded or collapsed. The Change Field options include an Expand/Collapse panel option, which allows you to expand or collapse a panel on a Change Field action. For more information about these workflow actions, see the Workflow Objects Guide.

358

Form and Application Objects Guide

10

Chapter

Working with images

This section describes how to create and modify image objects. The following topics are provided: About images (page 360) Using backslashes in image object names (page 361) Creating image objects (page 361) Working with image objects (page 362) Adding background images to fields and form views (page 363) Using transparent images (page 365)

Chapter 10

Working with images

359

BMC Remedy Action Request System 7.6.04

About images
An image object is an image stored in the AR System database with information defining the image as an AR System object. The image object type appears in the AR System Navigator pane at the end of the All Objects list (see Figure 10-1).
Figure 10-1: Image objects in BMC Remedy Developer Studio

Image object list in the object list tab group

Image objects in the list of object types

Image object open in the editor area

You can use images as backgrounds for form views and certain field types, including buttons, panels, and cell-based tables. To use the same image in multiple locations, such as the background of related forms, you do not need to store a copy of the image in the display properties of each form view or field that uses the image. Instead, store the image once as an image object, and include it by reference in form view and field display properties. Using an image object, you can also avoid the 4 MB size limit on the field display property. AR System supports the following image types: Windows bitmap (.bmp file extension) Joint Photographic Experts Group format (.jpeg or .jpg file extensions) Graphics Interchange Format (.gif file extension) Portable Network Graphics format (.png file extension)

360

Form and Application Objects Guide

Using backslashes in image object names

NOTE
To convert existing references and image files to shared images, use the ImageExtractor.bat utility. See the Configuration Guide, ImageExtractor.jar (ImageExtractor.bat), page 412.

Using backslashes in image object names


IMPORTANT
Although AR System permits backslashes in image object names, the best practice is not to include them. To prevent attacks on your system, you should exclude unsafe characters from your web server. By default, most web servers do not allow the backslash character (\) in URLs for security reasons. For example, Tomcat does not allow backslashes in URLs unless you set a parameter to permit them. If your system uses such a web server, images whose object name contains backslashes might not appear in your browser. Therefore, if your image object names contain backslashes, check your web server documentation to find out whether you must change the web server default settings to display such images.

Creating image objects


Use this procedure to create an image object.

To create an image object


1 In AR System Navigator, expand serverName > All Objects. 2 Right-click Images, and choose New Image.

A blank image object opens in the editing area.


3 In the Description field, enter a description of the image.

The description appears in the list of images in the Object Selector dialog box when you add an image to a field or form view. Enter up to 255 characters.
4 Click Browse, and navigate to the directory containing the image. 5 To display the available images in the directory, select the various image types

from the Files of Type list.


6 Select the image to store in AR System, and click Open.

The image appears in the preview pane of the image object.


7 Save the image object, assigning a unique name in the Save Image As dialog box.

Images are indexed on the name you assign and by the image ID. Image names can have up to 255 characters.

Chapter 10

Working with images

361

BMC Remedy Action Request System 7.6.04

Working with image objects


To open an image object,
1 In AR System Navigator, expand serverName > All Objects. 2 Double-click Images. 3 From the Images list, double-click the image object to open.

To save an image to a file outside AR System


1 Open the image object, and then click Save to Disk. 2 Navigate to the directory where you want to save the file. 3 Enter an appropriate file name, and then click Save.

To rename an image object


1 In AR System Navigator, expand serverName > All Objects. 2 Double-click Images. 3 Right-click the image to be renamed, and then choose Rename. 4 Enter the new name, and then save the image object.

You cannot rename an open object in BMC Remedy Developer Studio. If a warning indicates the object has an open editor, close the image and repeat these steps.

To delete an image object WARNING


Deleting a shared image object removes it from all form views and fields. You cannot undo this operation in BMC Remedy Developer Studio.
1 In AR System Navigator, expand serverName > All Objects. 2 Double-click Images. 3 Right-click the image to be renamed, and then choose Delete. 4 Confirm the deletion when prompted. 5 In the second confirmation dialog, specify whether to remove references to the

image from the display properties of fields and objects. Click Yes to remove the reference from the listed fields or objects. Click Yes to All to remove all references to the image. Click No to retain the reference in the listed field or object. Click No to All to retain all references to the image. If you retain a reference, the image object name stays in the display property, and you can create another image object with the same name to restore the reference.

362

Form and Application Objects Guide

Adding background images to fields and form views

Adding background images to fields and form views


You can use an image as the background of a panel field, of the cells in a cell-based table field, or of a form view. You can either use a reference to an AR System image object, or you can store the image as an embedded object in the field.

NOTE
To support the Image Reference functionality for panel and cell-based table fields, AR System clients and supporting applications such as BMC Remedy User and the mid tier must be release 7.5.00 or later. When previous clients open a form containing an image reference, the image is converted to embedded format.

To add an image to a panel field or a cell-based table


1 Select the panel field or the working cell of the cell-based table field. 2 In the Properties tab, click the Background Image property, and click its ellipsis

button.
3 In the Background Image dialog box: a If necessary, click Clear Image to delete an existing image. b Browse for the image to display on the button.

You can choose .bmp, .jpeg, .jpg, .gif, and .png files. The chosen image appears in the Preview area.
c To save the image to a different file or folder, click Save to File. d Set the Image Type:

Embedded ImageThe image is stored in the field display properties as an ARByteList. In this case, the image is embedded in the form and is therefore downloaded with the form whenever the form is refreshed by the client. Image ReferenceA reference to a shared image object is stored in the field display properties. In this case, the image is stored as an image object in AR System. When the form is downloaded, the image is cached separately, so the image does not have to be refreshed along with the form. This allows for faster form refresh time.
e Click OK.

Chapter 10

Working with images

363

BMC Remedy Action Request System 7.6.04

4 To position the graphic horizontally in the panel or cell, select the Background

Image Horizontal property, and then select one of the following options: LeftPosition the left edge of the image at the left edge of the panel or cell. CenterPosition the horizontal center of the image at the horizontal center of the panel or cell. FillResize the image horizontally to fit the width of the panel or cell. RightPosition the right edge of the image at the right edge of the panel or cell. TileIf the width of the image is smaller than the width of the panel or cell, tile the image horizontally in the panel or cell. If the width of the image is larger than the width of the panel or cell, Tile has no effect. This property works together with the Background Image Vertical property to control the overall position and dimensions of the image.
5 To position the graphic vertically in the pane or cell, select the Background Image

Vertical property, and then select one of the following options: TopPosition the top edge of the image at the top edge of the panel or cell. CenterPosition the vertical center of the image at the vertical center of the panel or cell. FillResize the image vertically to fit the height of the panel or cell. BottomPosition the bottom edge of the image at the bottom edge of the panel or cell. TileIf the height of the image is smaller than the height of the panel or cell, tile the image vertically in the panel or cell. If the height of the image is larger than the height of the panel or cell, Tile has no effect. This property works together with the Background Image Horizontal property to control the overall position and dimensions of the image.

364

Form and Application Objects Guide

Using transparent images

Using transparent images


In previous versions, AR System supported only .bmp, .dib, .jpeg, .jpg, .targa, and .tiff images. Those image types cannot have transparent backgrounds. In AR System 7.5.00 and later, the following AR System components support .gif and .png images, which can have transparent backgrounds: BMC Remedy Developer Studio BMC Remedy Mid Tier BMC Remedy User

NOTE
PNG images that use alpha transparency are supported by Internet Explorer 7, Firefox, Safari, and BMC Remedy User. They are not supported by Internet Explorer 6. PNG and GIF images that use binary transparency are supported by all AR System 7.5.00compatible browsers and BMC Remedy User. To create graphics with transparent backgrounds that let the surface on which they are placed show through, use .gif and .png images with the Display as Flat Image property. For example, use such images to create borderless buttons. Figure 10-2 shows a .gif coffee cup image with a transparent background on a regular button and on a borderless button.
Figure 10-2: A .gif file with transparent background on regular and borderless buttons

To build toolbars, you can use transparent images on borderless buttons as shown in Figure 10-3.
Figure 10-3: Transparent images as toolbar buttons

TIP
To add decorative graphics to forms, use borderless buttons without workflow.

Chapter 10

Working with images

365

BMC Remedy Action Request System 7.6.04

Most browsers always use a visual aid, such as a dotted outline, to indicate that borderless buttons have focus. Internet Explorer, however, does this only when the form has certain background colors. In BMC Remedy User, a gray area is displayed around a .png image when a button is larger than the image and the Scale Image to Fit property is set to False. In the mid tier, this gray area does not appear. You can use .gif and .png images anywhere that images are supported in AR System, including Backgrounds on form views Backgrounds on standalone panel fields

NOTE
.gif and .png images are not supported for toolbar buttons in BMC Remedy User.

Transparent .gif and .png images are not supported in Internet Explorer 6 for the backgrounds of cell-based tables, forms, and panels.

366

Form and Application Objects Guide

11

Chapter

Types of fields

Fields are objects that enable you to control how information is captured and displayed on a form. Fields have properties that determine their structure within AR System. The following topics are provided: Data fields (page 368) Table fields (page 377) Attachment pools (page 377) View fields (page 380) Data visualization fields (page 382) Application list fields (page 382) Navigation fields (page 383) Button fields (page 384) Panel fields (page 384) Trim fields (page 385) For an alphabetical list of field properties, see Appendix D, Field properties. For information about adding fields to forms, see Chapter 6, Creating and managing fields.

Chapter 11 Types of fields

367

BMC Remedy Action Request System 7.6.04

Data fields
Data fields contain data and can be any one of the following data types: Character Diary Date/Time Date Time Currency Integer Real Decimal Selection (drop-down, radio, check box)

The following sections describe these types of fields. To learn how to add them to forms, see Chapter 6, Creating and managing fields.

Character fields
Character fields are useful when there is significant variation in the field contents or length of the content; for example, descriptive text, names of people, addresses, and keywords. You can attach a menu or a file system browser to character fields or fill them with default text. For information about the expand box that appears next to character fields, see Expand Box on page 511. Depending on the Input Length of a character field and the database, a character field is created either as a varchar or a clob database table column. If the Input Length exceeds the maximum for varchar a given Table 11-1, a clob is used.
Table 11-1: Maximum varchar size Database IBM DB2 Informix Microsoft SQL Server Oracle

Maximum Input Length for varchar 3999 255 7999 3999 255

Sybase

NOTE
To include a tab in the text that you enter into a character field, press Ctrl+Tab.

368

Form and Application Objects Guide

Data fields

Oracle CLOB storage


If an AR System server uses an Oracle database, you can specify the default storage of CLOB (character large object) data by using the Store CLOB In-Row option on the Database tab of the AR System Administration: Server Information form. (See the Configuration Guide, Server InformationDatabase tab, page 142.) For AR System 7.5.00 and later, you can control how CLOB data is stored in individual character fields by using the CLOB Storage field property. See CLOB Storage on page 504.

Diary fields
Diary fields capture the history of a request over time. Whenever users enter comments in the diary field, the new entry is appended to the previous diary entries. Every diary entry is stamped by the AR System server with a time and a user name. After they are saved, diary entries cannot be modified. By default, AR System inserts a diary expand button to the right of each diary field. Users can click the button to open a Diary Editor dialog box. When the diary field contains entries, the icon changes from a blank book to an image of a book containing text. A diary field displays whole words only. To see the text beyond the words displayed in the field, open the Diary Editor dialog box.

NOTE
To include a tab in the text that entered into a character fields dialog box, the user must press Ctrl+Tab. The default maximum size limit of data contained in diary fields varies per database: For Sybase, Microsoft SQL Server, and Informix databases, 2 GB For DB2 databases, 10 MB For Oracle databases, 4 GB

NOTE
To configure a different maximum limit for Oracle, Microsoft SQL Server, and Sybase databases, use the Db-Max-Text-Size option in the ar.conf or ar.cfg files. For more information, see the Configuration Guide, AR System configuration files, page 347. To search a diary field when using Oracle, you must configure ar.conf (ar.cfg) to allow searching on CLOB data types. See the Configuration Guide, ar.conf (ar.cfg), page 348. Consider the effect of searching on system performance. You might want to use FTS to create a search index for diary fields. Note that you cannot search for the time stamp or the name of the user who submitted an entry.

Chapter 11 Types of fields

369

BMC Remedy Action Request System 7.6.04

You cannot use the Indexes form property to create an index for a diary field. However, if you are licensed for full text search, you can use the Index For FTS field property described on page 514 to create a search index for the field. For more information, see the Configuration Guide, Using full text search, page 295.

Date and time fields


There are three types of date and time fields: Date/TimeStores calendar dates and time together. You can set the Display Type property to Just Date or Just Time so that users see only the date or time. AR System stores date/time values as the integer number of seconds since 00:00:00 GMT, January 1, 1970. Dates from January 1, 1970, through January 18, 2038, GMT are valid in date/time fields. If users enter only a time, the current date is assumed. If users enter only a date, the time defaults to 12:00:00 A.M. DateStores date information only as the number of days from the beginning of its range. Use a Date field to compare two dates or to perform calculations based on the date, such as calculating the number of days between two dates. Users can enter dates from January 1, 4713 B.C.E., to January 1, 9999 C.E. TimeStores time information only as the number of seconds from 12:00:00 A.M. Use a time field to compare two times or to perform calculations based on time, such as the number of elapsed seconds. The value in a time field is independent of the time zone. While a date/time field adjusts the displayed value to reflect the users time zone, the time value in a time field remains unchanged when displayed on the client.

WARNING
Because values stored in date/time, date, and time fields are not equivalent, setting, pushing, or merging values among these fields might produce unexpected results. The format for these fields matches the locale specified in the user preferences. If no user preference for locale exists, user environment settings are used (for example, Regional Settings Properties in the Windows Control Panel). For information about workflow considerations for date/time, date, and time fields, see information about keywords and assigning values using function results in the Workflow Objects Guide.

370

Form and Application Objects Guide

Data fields

Currency fields
Currency fields are different from other fields in that they store multiple values when the data is saved. A currency field stores the following data: A user-entered decimal valueDecimal values are displayed according to the users locale. For example, on German systems, thousands are separated by periods. If users do not include a decimal point, the system automatically adds it when the field data is saved. The system also adds zeros after the decimal point based on the precision setting in the fields properties. If a user enters the value in a specific currency and saves the entry, that currency is displayed to whomever views the entry. A currency code, such as EUR (Euro) or USD (US dollar)The codes are usually consistent with ISO 4217. You can override the codes with localized labels (see Step 7: Localizing currency codes on page 593). A currency code can be entered into the field in any of the following ways: Default valueAt runtime, a user can enter the code into the field or choose the code from the menu attached to the field. User preferencesUsers can specify a preferred initial currency type in BMC Remedy User (Tools > Options > Locale tab) or in the AR System User Preference form (Locale tab). When a user opens a new request, the code for the user-preferred currency appears in the currency field unless the codes currency type is not one of the fields allowable currencies (see Allowable and functional currencies on page 372). This user preference overrides the Initial Currency Type field property, but the Default Value field property overrides both the user preference and the Initial Currency Type. Initial currency typeDevelopers can specify an initial currency code in a currency fields Initial Currency Type or Default Value properties. The default value overrides the initial currency type. Primary allowable currencyIf users do not specify a code, the system adds the code of the primary allowable currency when the request is saved. See Creating a currency field on page 192. One or more functional currency valuesGenerated when users save the data that they entered in the currency field. See Allowable and functional currencies on page 372.

NOTE
The first functional currency that is defined is special because it is used in workflow evaluations and in searches. It is critical that you define a currency exchange ratio entry between every currency type in which data can be entered and the first functional currency. See Currency exchange ratios on page 373. Date on which the functional currency values were generated

Chapter 11 Types of fields

371

BMC Remedy Action Request System 7.6.04

After entering data into a currency field and saving the request, users can view the fields functional currency values by clicking the expand button next to the currency field, as shown in Figure 11-1.
Figure 11-1: Viewing functional currencies

In table fields, when users sort on a column that represents a currency field, records are grouped by currency type and then sorted within each group. This allows meaningful comparisons among currencies of the same type. To learn how to add currency fields to forms, see Creating currency fields on page 191.

Allowable and functional currencies


For each currency field, you specify allowable and functional currencies: Allowable currencies are the types of currencies that users can enter in a currency field. Codes for allowable currencies appear in a menu attached to the field. For each currency field, application developers can specify a primary allowable currency to use when users do not specify a currency code. If the developer does not specify a primary currency, the system uses a default. Although the default in BMC Remedy Developer Studio is all allowable currencies, include only what is necessary for your applications. For every allowable currency, you must create a matrix of currency ratio values to support converting every allowable currency to a different functional currency. Functional currencies are the currencies into which the user-entered currency is converted when users save a request. For example, if a user enters 7.00 USD and the fields functional currencies are EUR and JPY, 7.00 USD is converted into the corresponding EUR and JPY values (see Currency exchange ratios on page 373). Applications can use these preconverted values, which are stored with the field, to search, report, and run qualifications without spending additional processing time to convert the user-entered value at runtime. The server uses the first functional currency entered to evaluate workflow comparisons and process workflow actions. For more information about allowable and functional currencies, see Creating currency fields on page 191.

372

Form and Application Objects Guide

Data fields

Currency exchange ratios


To convert allowable currency values into functional currency values, AR System uses currency exchange ratios that you specify in the AR System Currency Ratios form.

IMPORTANT
To ensure that workflow and searches work correctly, you must create a currency exchange ratio for the first functional currency (and others as needed). See Creating currency exchange ratios on page 195.

Keeping currency exchange ratios up to date


To keep your currency exchange ratios up to date, add or modify records in the AR System Currency Ratios form as currency exchange rates change. During currency conversions, AR System uses the value in the Conversion Date field. AR System does not automatically update records in the AR System Currency Ratios form. However, you can use AR System to design your own update mechanism. For example: Create a web service that consumes a currency conversion web service. Use an ARDBC plug-in that interfaces with a rate service. Create an escalation that submits new values. You can specify the interval at which clients query the server for the latest currency exchange ratios. See To set the currency exchange ratio refresh interval on page 196.

Setting currency field information


Set currency field information in these locations:
Table 11-2: Locations for currency information Currency information Default allowable and functional currencies Where to set Currency Types tab of the AR System Administration: Server Information form. See the Configuration Guide, Server InformationCurrency Types tab, page 141. The defaults appear in the Currency Types property dialog box of all new currency fields. Individual field currencies Localized currency labels BMC Remedy Developer Studio. See Creating currency fields on page 191. AR System Currency Label Catalog form. See Step 7: Localizing currency codes on page 593.

Chapter 11 Types of fields

373

BMC Remedy Action Request System 7.6.04

Workflow considerations
You can use currency fields in active link, filter, and escalation actions. Currency fields behave like other fields in workflow actions, with these exceptions: The Change Field active link action cannot access the currency code menu attached to the field. The Set Fields and Push Fields actions allow only the overall value of the field to be set. You can use the overall value or any portion of the value (such as the date) as a data source. The first functional currency entered is the currency that is used in workflow and searches. Currency fields have four functions: CURRCONVERT, CURRSETDATE, CURRSETTYPE, and CURRSETVALUE. For more information, see the Workflow Objects Guide, Specifying arguments that use a comma as a decimal separator, page 252. Because the currency field is a complex type, it has special rules for conversion to and from other data types.
Table 11-3: Conversion from currency Target data type Character or Diary Decimal, Real, or Integer Selection Data conversion rule The decimal value, with the currency code to the right. The decimal value only, dropping the fraction as necessary. The decimal value converts to an integer value.

Date/Time, Date, or Time The decimal value converts to a long date value.

Table 11-4: Conversion to currency Source data type Character or Diary Data conversion rule Parses the string to get a number and symbol. If the currency code is valid, the following rules are applied: If the currency code represents one of the allowable currencies for the field, the currency value and code are used as is. For example, if 100 USD is entered, the data is converted to 100.00 USD. If the currency code does not represent one of the allowable currencies for the field: If a currency ratio exists between the currency code and the primary allowable currency for the field, the value is converted to the primary allowable currency. If no ratio exists between the currency code and the primary allowable currency, the data is set to NULL. If the currency code is invalid, the data is set to NULL. Decimal, Real, or Integer Converts the numeric value to Decimal, and then appends the primary allowable currency code.

374

Form and Application Objects Guide

Data fields

Table 11-4: Conversion to currency Source data type Data conversion rule

Date/Time, Date, or Time Converts the numeric value of the time stamp to Decimal, and then appends the primary allowable currency code. Selection Converts the numeric value to Decimal, and then appends the primary allowable currency code.

Field name considerations


When the ODBC driver accesses a currency fieldfor example, when you run a reportit generates four or more column names for the field by adding these suffixes to the field name:
_Date _Type _Value _functionalCurrencyCode

The driver creates one column for each functional currency defined for the field. If the form contains a field with a name that is the same as one of the generated names, the ODBC driver reports Cannot define field more than once and fails to get the data. To prevent this problem, do not use field names that conflict with the column names generated by the ODBC driver for currency fields.

Integer fields
Integer fields accept integer values between 2147483647 and 2147483647. You can use integer fields to process statistical information in reports.

Real fields
Real fields accept and contain floating-point numbers, which are useful for displaying very small and very large numbers. You can use real fields to process statistical information in reports. For real fields, the representation in the database keeps a maximum of ten digits of data. After ten digits, the number is rounded, and the succeeding digits are ignored. For example, if 12345.090009 is entered, the value after a submit is 12345.090010. But if 1234567.090099 is entered, the value after a submit is 1234567.090000. The last three digits are ignored because the rounded answer comes after the tenth position.

Chapter 11 Types of fields

375

BMC Remedy Action Request System 7.6.04

Decimal fields
Decimal fields accept and contain fixed-point decimal numbers. Real fields and decimal fields differ in the following ways: Real numbers are inherently defined to be approximations, and decimal numbers are defined to be exact. Decimal numbers can have greater precision. The administrator has control over the fractional portion in a decimal field. The total number of values in a decimal field can be as many as 28 places long. This number includes the decimal places (up to 9) that you define in the Precision field. You can control the precision of the number by defining where the decimal point is placed. Decimal fields appear right-justified. Decimal, digit grouping, and negative sign symbols are based on the locale specified in the user preferences. If no user preference for locale exists, user environment settings are used (for example, Regional Settings Properties in the Windows Control Panel). You can use decimal fields to process statistical information in reports.

Selection fields
Selection fields provide users a small number of choices. Selection fields are displayed as one of these types: Drop-Down ListUsers can select from a list of items. Radio ButtonUsers can select only one item. Check BoxUsers can select one or more items from a set of items. Users cannot enter values that are not in the selection field. (This is one difference between selection fields and character fields with menus.) Data for a selection field is stored in the database as an integer that relates to the order of the selection items. AR System can automatically generate item IDs, or you can create a custom ID for each item. If you create the IDs, gaps can exist between the ID numbers, enabling you to insert new IDs later. For example, you might create these IDs:
Table 11-5: Example IDs Selection item Open In Development In QA Closed Custom ID 10 20 35 39

At a later time, you can add a selection item and ID, such as Pending and 15, which is placed between Open and In Development.

376

Form and Application Objects Guide

Table fields

If AR System numbers the IDs for you, do not change the order of existing selection items, or the meaning of data previously entered in the database is changed. For example, in a Status field, if the original items are New, Assigned, and Closed and you add an item labeled Fixed before the Closed item, existing database entries with a status of Closed change to a status of Fixed. If you must add an item to a selection field on an active form, add it only as the last item. For example:
New = 0 Assigned = 1 Closed = 2 Fixed = 3

WARNING
Altering the items in a selection field might require explicit modifications to every request in a form. For check boxes, you can define more than one choice, but users have access only to the first value. You can create searches using the item IDs in the selection field. For example, the search string Status < 2 searches for all New and Assigned requests in the previous example. The search string Check Box = $NULL$ searches for requests in which the check box is not selected. Use selection lists only in cases where you do not expect the options available to users to change over time. For more information, see Creating selection fields on page 196.

Table fields
AR System supports the following types of table fields: List view (see page 235) Tree view (see page 236) Cell based (see page 243) Alert list (see page 245) Results list (see page 246) For more information, see Chapter 7, Working with tables.

Attachment pools
An attachment pool contains attachment fields that enable users to store text, graphics, audio, or video with a request. The attachment data is compressed and stored in the database with each request.
Chapter 11 Types of fields 377

BMC Remedy Action Request System 7.6.04

A form can have any number of attachment pools, and each attachment pool can have any number of attachment fields, subject to database limitations. You set properties for the attachment pool and for its attachment fields in BMC Remedy Developer Studio, including maximum size for each attachment field and permissions. View permission allows users in a group to view attachments. Change permission allows users in a group to add and remove attachments in an attachment pool. Attachment pools do not have labels, but you can use trim text to label them on a form. For more information, see Creating attachment pools on page 198.

Viewing attachments in BMC Remedy User


In BMC Remedy User, attachments can be viewed as large icons, small icons, a list, or a detailed list that contains information such as file size. When creating or modifying requests, users can right-click the following items to open a menu that contains relevant commands:
Table 11-6: Right-click results Right click . . . Attachment pool Attachment field Attached file name To open a menu with commands that . . . Add an attachment Change the view Add an attachment Change the view Replace the file with another file Delete, display, save, or deselect the file Change the view

Users can also add attachments by dragging files into the attachment pool, and users can display attached files by double-clicking them. When users add a file to the attachment pool, the file is added to the next available attachment field. If no empty attachment field is available and if no attached file name is selected, the user is prompted to replace the file in the first attachment field. If an attached file name is selected, the user is prompted to replace the selected file. Attached files are added to or deleted from the database when the request is saved. You can customize both the column headings and the context menu labels in BMC Remedy Developer Studio. See step 6 on page 199. Figure 11-2 shows an attachment pool with its menu in BMC Remedy User.

378

Form and Application Objects Guide

Attachment pools

Figure 11-2: Attachment pool in BMC Remedy User

NOTE
When users perform the Copy to New operation in BMC Remedy User, the new request does not include attachments and diary fields. Users must save attachments to files and then attach them to the new request. In a browser, there is no Copy to New operation.

Viewing attachments in a browser


When creating or modifying requests in a browser, users can click buttons below the pool to add, delete, display, save, and deselect attachments. Users can also right-click an attached file to open a context menu that contains those commands, and users can display attached files by double-clicking them. If users select an attachment field that does not contain an attached file, only the Add and Deselect buttons appear. You can customize both the column headings and the button labels in BMC Remedy Developer Studio. See step 6 on page 199.
Figure 11-3: Attachment pool in a browser

NOTE
If you open an attached file from a form in a browser, the file might be displayed incorrectly. For example, accented characters can become corrupted. To view the file with no display problems, save the file to disk, and then open the file separately from the browser.

Chapter 11 Types of fields

379

BMC Remedy Action Request System 7.6.04

Workflow considerations for attachment pools


Attachment pool and attachment field database names can be used as field references in workflow (see the Name field property on page 522). You can use all attachment pool and attachment field properties in active link, filter, and escalation actions. You can use the actions listed in the following table.
Table 11-7: Workflow actions for attachments Action Change Field active link Message Set Fields and Push Fields Description Shows or hides an attachment pool, and sets focus to it. Displays the name of an attached file in a message. Transfers attachment data from one attachment field to another attachment field. You can also use Set Fields to display an attachment in a view field.

Set Fields and Run Process Adds, saves, opens, or deletes attachments. The following active link Run Process commands are available: PERFORM-ACTION-ADD-ATTACHMENT PERFORM-ACTION-DELETE-ATTACHMENT PERFORM-ACTION-OPEN-ATTACHMENT PERFORM-ACTION-SAVE-ATTACHMENT

For more information, see the Workflow Objects Guide.

View fields
A view field is a display-only field that displays any type of content that a typical browser can display, including the following: Views of AR System forms. HTML templates registered in AR System Resource Definitions with parameters or embedded field references. These can be full HTML documents, or HTML fragments that are included in the main page. Attachment field contents, such as HTML files, image files, and Microsoft Word documents. The common use of view field is to embed multiple forms on the view fields that are present on a container form. Embedded forms can share the user interface and workflow. You can load AR System forms as Inline forms. For more information, see Inline Forms on page 150. You set the initial value of a view field by setting its Text property to bind a URL or a template name. You can also set the initial value using a Set Fields active link action, optionally using the TEMPLATE() function. For more information, see Creating view fields.

380

Form and Application Objects Guide

View fields

You can add multiple view fields to a form to display various pieces of data from different sources. You can also use different initial values for every view of a form, in order to customize the presentation for any language, platform, or user role. You can also create workflow that communicates between the view fields by sending events.

NOTE
For mid tier users, if you have custom content to display on the view fields, verify that the content is displayed correctly on the web browsers. For more information, see Creating view fields on page 201. Users print a document in a view field by performing right-click on the field and choosing Print.

Using view fields


Users cannot resize view fields. If a view field is too small to display its entire contents, the value of the Scroll Bar property (see page 527) determines whether scroll bars appear at the bottom and right side of the field.
Figure 11-4: View field with scroll bars

To print a document in a view field in BMC Remedy User, right-click the field and choose Print. (In a browser, you cannot print the contents of a view field.)

Workflow considerations for view fields


View fields participates in active links and filters as display-only character fields. View fields cannot participate in escalations, and they cannot trigger active links.

Chapter 11 Types of fields

381

BMC Remedy Action Request System 7.6.04

Data visualization fields


Data visualization fields provide a framework and services for graphing solutions based on the BMC Remedy Mid Tier. These fields provide an efficient way to add graphical fields such as Flashboards to AR System forms. To learn how to create a data visualization field on a form, see Creating data visualization fields on page 203. For more information about developing modules for data visualization fields, see the Integration Guide, Data visualization fields, page 167.

Application list fields


Application list fields display a list of entry points. AR System automatically generates the contents of the list, which contains the available applications, forms, and entry point guides on the current server. Any form that contains an application list field can be used as a home page (see Figure 11-5). A form can have only one application list field.
Figure 11-5: Application list field in sample home page

Application list field with entry points

For more information, see these sections: Creating application list fields on page 203 Defining entry points and home pages on page 433

382

Form and Application Objects Guide

Navigation fields

Displaying a subset of a servers applications and entry points


To display only a subset of a servers applications and entry points in an application list field, you can create sophisticated workflow by using a reserved character field ID that lets users see only a subset of entry points. Use a Run Process command (PERFORM-ACTION-HOME-FIELD-REFRESH) to display dynamically a subset of servers and applications.

Navigation fields
Horizontal and vertical navigation fields enable users to navigate to screens quickly and easily. A horizontal navigation field might enable users to move from application to application, and a vertical navigation field might give users access to common functions and application entry points within an application.
Figure 11-6: Horizontal and vertical navigation fields

Horizontal navigation fields can have only one level in their structure. Vertical navigation fields can have unlimited levels. But to keep the navigation of your application simple, limit the number of levels to three. Navigation fields can act as anchors for other menu fields, and you can use multiple navigation fields with menus attached to them. For more information, see To create a navigation field on page 205.

Workflow considerations for navigation fields

Chapter 11 Types of fields

383

BMC Remedy Action Request System 7.6.04

Remember these considerations when building workflow for navigation fields: One navigation field cannot be shared across several forms. To overcome this limitation, create common workflow for the navigation fields on several forms. You can show or hide individual navigation field items or the entire field. You can enable and disable items on a navigation field. You cannot set focus or change the label, color, or font of a navigation field. You can set workflow to fire on a menu item when it is selected, but workflow cannot fire on menus. You can change labels for horizontal and vertical navigation fields by using a change field active link.

Button fields
Button fields are control fields used to execute active links. For more information, see the Workflow Objects Guide, Using buttons and menu bar items to execute active links, page 165.
Figure 11-7: Button field

Buttons can be displayed as URLs and then associated with an Open Window active link action to simulate a hyperlink that opens a new window. See To create a button field on page 210. (To add a real URL that links to a web page, see Adding a URL to a trim text field on page 215.) You can add an image to a button to enhance the look of forms displayed in BMC Remedy User. See Adding images to buttons on page 212.

Panel fields
AR System supports the following types of panel fields: Basic panels (see page 328) Panel holders (see page 328) Tabbed panels (see page 331) Collapsible (stacked) panels (see page 332) Splitter panels (see page 332) Accordion panels (see page 333) For more information, see Chapter 9, Working with panels.

384

Form and Application Objects Guide

Trim fields

Trim fields
Trim fields are horizontal and vertical lines, boxes, and text (including URLs) that enable you to modify the appearance of a form.
Figure 11-8: Trim lines, boxes, and text

Each piece of trim is treated as a field by AR System, meaning that it has a unique field ID, a name, and display information. (No database information is associated with trim.) Because trim is a field, you can do this with it: Address each piece of trim in your workflow. For example, you can use a Change Field active link action to make a box hidden or visible. Change how or whether the trim appears in different form views. Define permissions for the trim to match the permissions of associated fields so that the trim is not visible if the fields are not visible. Add and change trim in the same way that you add and change other fields. Create URLs that link the form or application to the Internet. See Adding a URL to a trim text field on page 215. Although you can group fields visually with a transparent trim box, a panel field is a better choice. A panel fields is more powerful and easier to maintain because the fields are contained in the panel field and positioned within it. For information about creating trim fields, see Creating trim fields on page 214.

Chapter 11 Types of fields

385

BMC Remedy Action Request System 7.6.04

386

Form and Application Objects Guide

12

Chapter

Using templates

Templates are a method of formatting text dynamically for presentation in AR System. A template is suitable for dynamically creating an HTML document to be displayed in a view field or tool tip created by a Message action. When the template is evaluated at runtime, values are substituted for parameters in the template either using workflow or references to fields on the form. The following topics are provided: Resources for templates (page 388) Template content (page 389) Using templates with fields (page 390)

Chapter 12

Using templates

387

BMC Remedy Action Request System 7.6.04

Resources for templates


Templates and resources they use are stored as attachments to requests of the AR System Resource Definitions form. Three types of resources are available: TemplateA text file containing text with parameters. ImageAn image file in any format, including GIF or PNG formats. CustomA file of another type, such as an audio file, that can be presented by a browser. A template is accessed either by using the TEMPLATE function or by binding it to a view field. The template can refer to other resources to include images and other media in the output it produces. Figure 12-1 shows the form used to store templates and other resources.
Figure 12-1: AR System Resource Definition form

388

Form and Application Objects Guide

Template content

This form includes the following information: NameThe name used to references the resource. StatusEither Active or Inactive. Inactive resources cannot be processed by the client. TypeThe type of resource: Template, Image, or Custom. DescriptionA brief description of the template. Mime typeThe Internet media type or MIME (Multipurpose Internet Mail Extension) type of the resource. For Type set to Template, text/html. For Type set to Image, image/gif or image/png. For Type set to Custom, any type entered, for example, audio/mpeg. SubtypeAn optional character value that can identify a more specific type to distinguish resources. LocaleThe locale of the resource. If specified, AR System uses this field to select the resource with a given name that matches the users locale. ApplicationThe name of the application that uses this resource, if any. ResourcesAn attachment field where the actual HTML text, image, or other resource file is stored.

Template content
A template consists of text with parameters that are replaced with values when the template is used for rendering. Usually, the result of processing the template is a complete HTML document, starting and ending with the <html> and <body> tags, or a snippet of HTML to be inserted in a document, such as, a group of table rows.

Parameters in templates
There are two kinds of parameters in templates: Explicit parameters are named. They get their values from parameters of the TEMPLATE function and are represented by ${parameterName}. Implicit parameters are references to fields in a form. They get their values from the referenced fields and are represented by $fieldID$. A parameter can provide text in either the value of an HTML element or the value to an attribute of an HTML element. The value of the HTML tag element can be an expression that consists of more than one parameter, as in the following example:
<td>Full Name:</td> <td style="background:00ffff;${STYLE}"> ${FNAME} ${LNAME} </td>

Where

Chapter 12

Using templates

389

BMC Remedy Action Request System 7.6.04

The first parameter, STYLE, specifies one or more additional style properties and values to control the appearance of the table cell defined by the <td> tag. The additional parameters, FNAME and LNAME, specify the content of the table cell. In the following example, field IDs are used as parameters in the template content for two table rows.
<table> <tr> <td>First Name:</td> <td style=background:00FFFF>$123456789$</td> </tr> <tr> <td>Last Name</td> <td style=background:00FFFF>$234567890$</td> </tr>

In this example, the template is using explicit parameters to specify a background color for the First Name and Last Name fields in a table.
<table> <tr> <td>First Name:</td> <td style="background:00ffff">${FNAME}</td> </tr> <tr> <td>Last Name:</td> <td style="background:00ffff">${LNAME}</td> </tr> <tr> <td>Emp ID:</td> <td style="background:00ffff">${EID}</td> </tr> </table>

Using templates with fields


A template can be used in either of the following ways: By binding the template to a view field. Use this method when you do not need to calculate parameter values in workflow. However, you can always use workflow to update hidden fields that are referenced as implicit parameters and reinitialize the view field. By creating a Set Fields workflow action that uses the TEMPLATE function to place content into a character field or a view field. Use this method when you need to calculate parameter values using workflow.

390

Form and Application Objects Guide

Using templates with fields

Binding a template
To use a template to display in a view field without workflow, set the Text property of the view field to template:templateName. The parameters in a template used this way must reference fields on the form by field ID. An application can create a rich HTML-based data display using a cell-based table with data fields and a view field with a template bound to it. To redisplay a view field with a template bound to it, for example, after one of the referenced fields has its value changed, use workflow to assign the value of the view field to itself or to a value generated by the TEMPLATE function, as describe in the next section.

Evaluating a template with the TEMPLATE function


Use the TEMPLATE function to set the values of a field to the result of evaluating a template. The TEMPLATE function can appear in a field value in a Push Fields, Set Fields, Open Window, or Service action. The TEMPLATE function returns a text string with values for the parameters included in the template. The template name is always the first parameter, followed by name-value pairs for the remaining parameters, as follows:
TEMPLATE("templateName", "parameter", "value", "parameter", "value", ...)

Templates can be nested within templates using either of the following methods: By using workflow to generate content from a template with an HTML snippet and placing it into a hidden field. The value of that hidden field can be passed to another TEMPLATE function. Using the TEMPLATE function as a parameter within another TEMPLATE function. At runtime, when the client (BMC Remedy User or the mid tier) executes the active link where the template is specified, the template is retrieved from the AR System server and processed for the parameters that should be substituted. The resulting information is then rendered either in a view field or as a value in a character field. If the template does not use explicit parameters, it can be evaluated by calling the
TEMPLATE function with only the name of the template.

A message action of the type Tooltip can display the HTML generated by a Set Field action. This is typically done using a Set Fields action (generating content into a hidden field), followed by a message action to display the content of the hidden field. The BMC Remedy Developer Studio Expression Editor includes a mapping tool for setting template parameter values. After you choose the TEMPLATE function, choose a template from the Template Name list. The explicit parameters are listed in the table below. If you select the Value cell and click the ellipsis button, you can open an editor to set the value. See Figure 12-2 on page 392.

Chapter 12

Using templates

391

BMC Remedy Action Request System 7.6.04

Figure 12-2: Entering template information in the Expression Editor

Using auto-complete functionality with the TEMPLATE function


You can also use the auto-complete feature in the text portion of the Expression Editor. When you enter Ctrl+Space over the template name, a list of available templates appears.
Figure 12-3: Using auto-complete for template information

392

Form and Application Objects Guide

13

Chapter

Creating and managing form views


This section covers topics related to managing and defining form views. The following topics are provided: About form views (page 394) Creating and managing form views (page 400) Setting form view properties (page 405) Including and excluding fields from form views (page 411) Arranging fields in a form view (page 412) Rendering forms in right-to-left format (page 423) Setting the tab order of fields in a form view (page 424) Applying skins to form views (page 426) For additional information specific to web views, see the BMC Remedy Mid Tier Guide, Working with applications that will be viewed in a browser, page 65.

Chapter 13

Creating and managing form views

393

BMC Remedy Action Request System 7.6.04

About form views


A form view is what users see when they open a form in BMC Remedy User or in a browser. Form views are versions of an original form and can exist only after the initial creation of a regular form. (For information about creating regular forms, see Creating and managing forms on page 151.) Every form has one default view. As an administrator, you can create additional views of the same form, each defined for a unique purpose, locale, or view type. You specify default views to determine which view of a form opens in BMC Remedy User or in a browser. An administrator might define views for the following environments: Different localeViews for specific languages or regions. Different user rolesCustomized views for requesters, frontline staff, backline staff, or managers. Hardware dependenciesViews that allow for the size of a monitor, such as laptop or desktop. This is useful for legacy systems without scalable fonts. Purposes other than a formViews that are used only when invoked as a dialog box using an active link.

How a form view is selected for the user


To provide each user with the best possible view of a form, AR System uses this order of preference to determine which form view to display:
1 View requested by a user or by workflow. For example, a view can be specified in

an Open Window active link action or a URL for the browser.


2 Actor-based view.

This view represents the function that a user performs in an application. For example, a user might use an application to manage, submit, or audit help desk requests. In AR System, each of those functionsmanager, submitter, auditoris called an actor. Each actor can be associated with a different view. See Configuring actor-based view selection on page 396.

NOTE
An actor is not related to access permission roles.
3 Default view specified in the User Preference form.

For a browser, the system selects a view according to the Prefer Standard/ Windows Views option in the BMC Remedy Mid Tier Configuration Tool.
4 Default view specified in the form.

After using this order of preference to select a base form view, the system selects a version of the base view appropriate for the users locale. If no version exists for that locale, a fallback mechanism finds the closest possible locale to the one requested. The resulting view is then displayed for use.
394 Form and Application Objects Guide

About form views

Figure 13-1 illustrates the AR System form view selection process:


Figure 13-1: Form view selection process

Open form

View label explicitly specified? Yes Use specified view label

No

Actor-based view label found? Yes Use actor view label

No

View label specified in User Preference form? Yes Use preferences view label

No

View extension specified in User Preference form?

Yes

Add extension to label name

Client

No

Server
View exists? No Use default form view label

Yes

Server localized and locale-specific view exists? Yes

No

Open view

Open localized view

Chapter 13

Creating and managing form views

395

BMC Remedy Action Request System 7.6.04

Configuring actor-based view selection


When a user opens a form, AR System can determine which form view to display by matching the user to an actor in the context of the current application and then matching the actor to a view. To enable AR System to perform actor-based view selection, applications must define actors and link them to form views by adding entries to these forms: AR System User Application ActorUse this form to define actors for your system. See Defining actors on page 396. AR System Actor ViewUse this form to link actors to views. See Specifying an actor-based form view on page 398.

Defining actors
To select an actor on which to base view selection, AR System queries the AR System User Application Actor form. To add actors to AR System, applications must define them in this form.

NOTE
Adding a large number of entries to this form might degrade the performance of logging in and opening forms.
Figure 13-2: AR System User Application Actor form

396

Form and Application Objects Guide

About form views

Each entry (actor definition) in the AR System User Application Actor form should contain this information:
Table 13-1: Fields in AR System User Application Action form Field User Name Application Name Actor Group Access Description (Optional) A users AR System login name. To specify all users, leave this field empty. (Optional) Name of an application to limit this actor to. To specify all applications, leave this field empty. (Required) Name of the actor, such as Request Manager, Request Submitter, or Request Auditor. Name of one or more access control groups. By default, this field is set to Public.
Important: This field (ID 112) controls row-level security. If it is set to NULL, no user has

access to the entry, so AR System will not consider the entry when selecting an actor. Order (Optional) Integer that determines which entry to use when multiple entries contain matching User Name and Application Name values. In this situation, the entry with the highest Order value is used. An Order value of NULL is lower than 0.

To select an entry from the query results, AR System uses these criteria:
Table 13-2: Criteria for selecting an entry Entry selection order 1 2 3 4 User Name currentUser currentUser NULL NULL Application Name currentApplication NULL currentApplication NULL Default actor in all applications for this user. Default actor for all users in this application. Default actor for all users in all applications. In previous versions of AR System, the default form view was specified in one of these places: User Preference forms Default Form View field The form itself (Form > Set Default View) In AR System 7.5.00 and later, however, if the AR System User Application Actor form contains this entry, the actor in the entry is always used to determine the forms default view (see Specifying an actor-based form view on page 398). To use the legacy default views, do not include this entry in the AR System User Application Actor form. Notes

If multiple entries meet these criteria, the entry with the appropriate Group Access value and the highest Order value is used. If multiple entries share those criteria, the first entry returned by the query is used. AR System uses the actor specified in the entry to select a view. See Specifying an actor-based form view on page 398. If no entry meets these criteria, AR System uses the default form view specified in the User Preference form or in the form itself. See Figure 13-1 on page 395.

Chapter 13

Creating and managing form views

397

BMC Remedy Action Request System 7.6.04

Specifying an actor-based form view


If AR System finds an actor in the AR System User Application Actor form, it uses the AR System Actor View form to select a view based on that actor.
Figure 13-3: AR System Actor View form

To link actors to form views, applications must add entries to this form.

NOTE
Adding a large number of entries to this form might degrade the performance of logging in and opening forms. Each entry in the AR System Actor View form should contain this information:
Table 13-3: Fields in the AR System Actor View form Field Application Name Form Name Actor View Label Description Name of the application that contains the form. (Optional) Name of the form. If you leave this field empty, the entry is the default for all forms in the specified application. (Optional) Name of the actor. If you leave this field empty, the entry is the default for all actors in the specified application. Name of the view to display. See the views Label property.

NOTE
If you later rename a form or change a view label, AR System will not automatically update the entries in this form.

398

Form and Application Objects Guide

About form views

To select the appropriate entry, AR System uses these criteria:


Table 13-4: Criteria for selecting an entry Entry selection order 1 2 3 4 Application Name currentApplication currentApplication currentApplication currentApplication Form Name currentForm NULL currentForm NULL Actor actorName actorName NULL NULL Notes View for this particular actor for this particular form. Default view for this actor for all forms. Default view for all actors for this form. Default view for all actors for all forms in this application.

If multiple entries meet these selection criteria, the first entry returned by the query is used. If no entry meets these criteria, AR System uses the default form view specified in the User Preference form or in the form itself. See Figure 13-1 on page 395.

How a form view is selected in BMC Remedy Developer Studio


BMC Remedy Developer Studio chooses the form view to display when you open a form based on the default view of the form and the Default Locale you set in the Preferences dialog box in BMC Remedy Developer Studio (choose Window > Preferences). Every form has a default form view. If you do not set it (choose Form > Set Default View), the default form view is the view that is created by when you initially create the form. If you delete the default form view, BMC Remedy Developer Studio chooses another view. If you set the Default Locale, BMC Remedy Developer Studio uses that locale to select the default form view.

To set the default form view for a form


1 Open a form in BMC Remedy Developer Studio. 2 Choose Form > Set Default View. 3 In the dialog box, select the correct view and click OK.

The icon for the form type appears in the view tab at the bottom of the form editor. After you change the default form view, you must reopen the form for BMC Remedy Developer Studio to display the default form view with its tab as the first form view tab at the left bottom of the form editor.

Chapter 13

Creating and managing form views

399

BMC Remedy Action Request System 7.6.04

To set or clear the Default Locale


1 Choose Window > Preferences. 2 Expand BMC Remedy Developer Studio and click Form. 3 Select a locale or blank from the Default Locale list. 4 Click OK.

Creating and managing form views


Use the procedures describe here to create, modify, rename, and delete form views.

Creating form views


Use the following procedure to create a new form view. Although you can create an empty form view, it is usually more convenient to duplicate an existing view. When you duplicate a form view, you get a clone of that view. Only the label and ID of the view are changed in the copy. After the copy is made, you can change view-specific properties without affecting other views. For information about views that are displayed in a browser, see the BMC Remedy Mid Tier Guide, Working with applications that will be viewed in a browser, page 65. To create an alternate view for a group of users that is invoked using active links, append an extension to the view label. This view label extension is then specified in user preferences to identify the extension to be appended to the view label. The primary view must be specified in the active link and use of the alternate view is controlled by user preferences. For more information, see the Configuration Guide, Setting user preferences, page 81.

To duplicate a form view


1 Open a form in BMC Remedy Developer Studio. 2 Select the appropriate form view by clicking its tab at the bottom of the form editor. 3 Choose Form > Duplicate View. 4 In the Copy View dialog box, select the View Type and click OK.

StandardA view that can be displayed in BMC Remedy User and in a browser. Web - AlternateA view that uses fixed field positioning.

400

Form and Application Objects Guide

Creating and managing form views

Web - Alternate views are available for special purposes and for backward compatibility with previous releases. These views are not needed in version 6.3 and later versions. Use them for compatibility with older versions of the mid tier or for a situation where you need to create a view that is different in a browser than in BMC Remedy User. If there is a Web - Alternate, that view is selected first for a browser, unless the Standard view is the default preference set in the BMC Remedy Mid Tier Configuration Tool. For more information, see the BMC Remedy Mid Tier Guide, General settings, page 22.
5 Click the form view tab at the bottom of the form editor to select the new view. 6 In the Properties tab, modify the properties listed in Table 13-5, as appropriate. Table 13-5: Form view initial properties (Sheet 1 of 2) Property View ID Label Description A unique identifier for a form view. This value is automatically generated by AR System and cannot be modified. The label for the view. The Label, Locale, and View Type fields together define a unique identifier for the view. The client uses the label to identify the users preferred view. For more information, see the Configuration Guide, Setting user preferences, page 81. When a view is created, a label is assigned automatically to the new view. You can change the label. There is no enforced convention for specifying labels, but it is helpful to make the name descriptive and indicative of the views function consistently across forms. For example, you might create a Manager view for all forms in an application. Labels can be as many as 80 characters, including spaces. Names can include doublebyte characters, but avoid using numbers at the beginning of the name.
Note: If you want a specific view (other than the default set in BMC Remedy

Developer Studio) to be displayed in a browser by using a URL, make sure the label is unique. Locale Defines the views locale. When a view is created, the Locale field is empty. If left blank, the locale of the users operating system is assumed for the view. To specify a locale for a view, click the cell for the Locale field and select the preferred locale from the list. The Locale field associates a language and country dialect with a view following the format: language_country. Selecting only the language includes all variations of that language. Conversely, selecting fr_CA (French, Canada) defines a view for Canadian French speakers, while selecting fr includes all French speaking countries. For more information about localization, Appendix H, Localizing AR System applications. Different views for different locales should have the same Label, and the correct locale for the user is automatically opened.

Chapter 13

Creating and managing form views

401

BMC Remedy Action Request System 7.6.04

Table 13-5: Form view initial properties (Sheet 2 of 2) Property View Type Description The view type that was selected from the Manage Views - Copy View To dialog box when copying the view. Choices are: Standard (Recommended) Web - Alternate (Fixed) This field cannot be modified. Master View for Server Defines if the view is used for processing to retrieve field labels and selection value Processing aliases (not database values). Certain tools (such as data dictionary menus, active links that display a list, and application commands) query the data in forms and use these labels and aliases. For example, the ODBC driver might use field labels and selection field aliases to generate reports. Similarly, report qualifiers are validated using these labels and aliases. To specify the view that should be used as the master for a particular locale, click the cell for the Master field, and select True from the list. You can set only one view per locale. It is best to specify as Master the view that contains most, if not all, of the fields and aliases required for processing. If no view is specified as the master, the default view is used. If neither a master or default view exist, the system chooses a view at random.

The Label, Locale, and View Type properties do not need to contain unique values, but the combination of the three fields must be unique to each view.
7 To set a default view, click in the form editor and choose Form > Set Default View. 8 In the Choose Default View dialog box, select a view from the View Label list, and

click OK. The default view is the view displayed to a user when a request for a form is made and no user preferences is set. An exception to this rule is seen in a browser; if no user preference is set but the configuration preference is set to a web view, the web view is chosen.
9 To open a view, click its tab at the bottom of the form editor. 10 Choose File > Save to save the form with the new form view created.

NOTE
To create a blank form view with no core fields, choose Form > Create New View instead Form > Duplicate View.

402

Form and Application Objects Guide

Creating and managing form views

Changing which view is displayed


Use the following procedure to change which view is currently displayed.

To change which view is displayed in the form editor


1 Open a form in BMC Remedy Developer Studio.

The default view of the selected form appears in the form editor.
2 Click the form view tab at the bottom of the form editor to select the appropriate

view.

Modifying form views


Use the following procedure to modify existing form views.

To modify a form view


1 Open a form in BMC Remedy Developer Studio. 2 Click the form view tab of the view to modify at the bottom of the form editor.

The form view is displayed in the form editor and its properties are shown in the Properties tab. The following are examples of modifications that you can make to a form view: Modifying view properties. See Setting form view properties on page 405. Adding or modifying fields. See Chapter 11, Types of fields, and Appendix D, Field properties,. Specifying which fields to include or exclude. See Including and excluding fields from form views on page 411. Arranging fields. See Arranging fields in a form view on page 412. Modifying field properties of fields. See Appendix D, Field properties. Localizing the view. For more information, see Appendix H, Localizing AR System applications.
3 Choose File > Save to save the form with the changes to the view.

Chapter 13

Creating and managing form views

403

BMC Remedy Action Request System 7.6.04

Renaming form views


Renaming a form view enables you to change the name of an existing form view without having to create a duplicate under a different name. The renamed view retains all of the settings of the original form view.

To rename a form view


1 Open a form in BMC Remedy Developer Studio. 2 Click the form view tab of the view to modify at the bottom of the form editor.

The form view is displayed in the form editor and its properties are shown in the Properties tab.
3 In the Properties tab, enter the new name in the Name property. 4 To change the views label, enter the new name in the Label property.

NOTE
Avoid characters in a form view label that result in an invalid URL when the form view is accessed through the mid tier. BMC Remedy Developer Studio warns you if you use one of the invalid characters configured in the Form preferences page. By default, the Invalid Characters for Form Name preference is set to /&#%'".?.
5 Choose File > Save to save the form with the changes to the view.

Resizing form views


By default the form editor does not show the actual size of a form view. When you add or move fields, the form view is expanded to include them.

To resize a form view


1 Choose Layout > Show Actual View Size.

A frame shows the actual view size. The form editor displays a grey background outside the form view.
2 Select the form view by clicking in its background or deselecting all the fields.

Resize handles appear on the right and bottom edges and at the bottom right corner of the form view.
3 Drag a resize handle to change the form view size.

The status bar reports the form view size as it changes.

NOTE
When you design form views, you should design them for a particular screen resolution. For example, a form view designed for a 1280 by 1024 screen resolution might look incorrect on a 1024 by 768 screen.

404

Form and Application Objects Guide

Setting form view properties

Deleting form views


You cannot delete all views for a form. Each form must have at least one form view. If the default form view is deleted, the first form view in the set of view tabs is then designated as the default view.

To delete a form view


1 Open a form in BMC Remedy Developer Studio. 2 Click the form view tab of the form view to delete at the bottom of the form editor. 3 Choose Form > Delete View. 4 Confirm the deletion. 5 Choose File > Save to save the form without the deleted view.

Setting form view properties


Set form view in the Properties tab to specify pane layout, create aliases that describe how requests are named, predefine searches that you think users might want, disable user access to selected features, and define the color of rows of a results list pane. The following categories are available in the Properties tab for Standard views: BasicDefines the variable names that uniquely identify a form view. AppearanceDefines how a view appears in BMC Remedy User and on forms viewed in a browser. AliasesDefines how form aliases and entry point labels are displayed in AR System. Defined SearchesDefines common searches for users. Menu AccessAllows you to enable or disable menu items and toolbar items in BMC Remedy User and toolbar buttons on forms viewed in a browser. Results ListDefines the color of selection field items that appear in a results list pane and special results list characteristics for BMC Remedy User.

To define form view properties


1 Open a form in BMC Remedy Developer Studio. 2 Click the form view tab of the appropriate view at the bottom of the form editor.

NOTE
If you select a field in a form view, either by clicking in the form view or in the Outline tab, the Property tab shows the properties for the field. To display the properties for the form view, click the view background or deselect the field by holding down Ctrl and click it in the form editor or its name in the Outline tab.

Chapter 13

Creating and managing form views

405

BMC Remedy Action Request System 7.6.04

3 Set the properties in the Properties tab as described in the Introduction to

Application Development with BMC Remedy Developer Studio guide, Modifying object properties, page 51.
Table 13-6: Form view properties - Basic category Name Label Description Defines the label for the view. When a view is created, a label is automatically assigned for the new view. The assigned label can be changed. There is no enforced convention for specifying labels, but it is helpful to make the label descriptive, indicative of the views function, and consistent across forms. Labels can be as many as 80 characters, including spaces. Labels can include doublebyte characters, but do not use digits at the beginning of the label.
Note: If you want a specific view (other than the default set in BMC Remedy

Developer Studio) to be displayed in a browser by using a URL, make sure the label is unique. Locale Localize Defines the views locale. When a view is created, the Locale field is empty. If left blank, the locale of the users operating system is assumed for the view. Specifies if the text in a view must be translated. By default, this property is set to True, and attribute 287 in the view definition is set to 1. To ascertain which views must be translated, localizers can search .def files for the display-instance setting 287\6\1, where 287 is the ID of the localization indicator attribute. 6 is the data type for the attribute and can be ignored. 1 is the attribute value that indicates localization is required. Master View for Server If set to True, this view is used for processing to retrieve field labels and selection Processing value aliases (not database values). For more information, see the description for Master View for Server Processing on page 402. Name View ID View Type Defines a unique identifier for a form view. This value is initially generated by AR System, but you can modify it. This number is a unique ID generated by AR System and stored in the database, and you cannot change it. Defines the type of view associated with the selected view. You choose the view type when you create the view, and you cannot change it.

406

Form and Application Objects Guide

Setting form view properties

Table 13-7: Form view properties - Appearance category (Sheet 1 of 2) Name Description

App-specific Image Use the App-specific Image Path for Mid-Tier View property for forms viewed Path for Mid-Tier View through applications in a browser. Set this property to the relative path from an application's Support Files top directory to the background image. If the file is not found in the application resource files, the path in this field is ignored. See the BMC Remedy Mid Tier Guide, Managing resource files, page 74. Background Color Background Image The color of the view background where there are no fields. The default is white. A background image (.gif, .png, .jpeg, .jpg, .bmp, or .dib format) for the view. Use the Background Image dialog box to select an image file that is saved with the form or a reference to an image object.
Note: Avoid using uncompressed .bmp and .dib bitmap files. Use images files with

lossless compression, such as .gif and .png, for images that do not use continuous tones. Use .jpg for continuous-tone images, such as photographs and graphics with gradients. Avoid using a large image file. Although view definitions are cached when initially loaded, images associated with a view must first be downloaded. Changes to a form also force the image to be downloaded again, increasing response time. If you need a large image, create an image object that is downloaded and cached separately. See Chapter 10, Working with images. Background Image Horizontal Background Image Vertical Details Pane Banner Layout Layout Editable by User HiddenDoes not appear when BMC Remedy User is opened. VisibleAppears when BMC Remedy User is opened. The position of the results and details panes in the view. This property is enforced only when the Layout Editable by User property is False. Enables users to define the position of panes and banners in their view. If this property is true, the layout selected in the Windows User Tool is applied. If this property is False, the positions are locked, and the corresponding menu items in BMC Remedy User are disabled. XY or Fill. See Panel layout styles on page 329. Position the graphic in the view and control whether it is stretched to fill the view, tiled, or neither.

Layout Style

Maximize Window On Controls whether a view is maximized automatically when opened. For larger forms, Open the maximized view can free the user from having to scroll when viewing a forms contents. This option applies to a specific view of a form; each view of a form has its own maximize value. This option is ignored when the form is opened in Dialog mode. Prompt Bar Position Results Banner Right To Left The position of the prompt bar, at the top or bottom of the window. HiddenDoes not appear when BMC Remedy User is opened. VisibleAppears when BMC Remedy User is opened. Defines whether the text direction of a form view is displayed from left to right (False) or right to left (True). The default is False. For more information, see Rendering forms in right-to-left format on page 423.

Chapter 13

Creating and managing form views

407

BMC Remedy Action Request System 7.6.04

Table 13-7: Form view properties - Appearance category (Sheet 2 of 2) Name Title Bar Icon Description An icon image (.gif, .png, .jpeg, .jpg, .bmp, or .dib format) for the title bar of the form view. Use the Title Bar Icon dialog box to select an image file that is saved with the form or a reference to an image object. Images larger than 16x16 pixels are cropped. HTML code to include in the footer of a Web - Alternate (Fixed) view. For more information, see the BMC Remedy Mid Tier Guide, Editing web header and footer content, page 68. HTML code to include in the header of a Web - Alternate (Fixed) view. For more information, see the BMC Remedy Mid Tier Guide, Editing web header and footer content, page 68. HiddenDoes not appear in a form opened in a browser. VisibleAppears in a form opened in a browser.

Web Footer Content

Web Header Content

Web Toolbar

Table 13-8: Form view properties - Aliases category Name Plural Request Identifier Description Defines the aliases that appear in the Results and Details banners in Search mode and the Open dialog box in BMC Remedy User and the title bar of the window. Allows a descriptive request name such as current inventory to appear instead of asset 565. The Request Identifier can be any field except diary and long character fields. The Request Identifier replaces the Request ID in the Details pane banner and the most recently used requests in the File menu in BMC Remedy User. Short Plural Defines the shortened version of the plural alias that appears when the title does not fit in the Results and Details banners. The Short Plural alias is not used in the title bar of the window. Defines the shortened version of the singular alias that appears when the title does not fit in the Details banner. The Short Singular alias is not used in the title bar of the window. The web does not use the short alias and precedence is as follows: If long and short aliases are defined, the title bar displays the long alias. If only the short alias is defined or if no aliases are defined, the title bar displays the form name. Singular Defines the alias that appears in the Details banner and the title bar of the window.

Short Singular

For each view, use the Defined Searches category to define the searches that appear in the Search menu list on the Details banner and in the Actions > Defined Searches menu in BMC Remedy User. Use this feature to create predefined searches that you think might be helpful to your users; for example, finding all open requests or entries. You can define as many as 18 searches.

408

Form and Application Objects Guide

Setting form view properties

Click the ellipsis button in the Defined Searches property to open the Defined Searches dialog box.
Table 13-9: Form view properties - Defined Searches dialog box Name Name Description If you do not enter a Description, defines the name of the predefined search that users see in the Search menu in BMC Remedy User. This name appears in the Results pane banner after users perform a search.
Note: You can create parameterized searches for users who use a browser, but these

searches return an error in BMC Remedy User. To avoid this error, create parameterized searches only for the web view of the form and not the BMC Remedy User view. For more information, see the BMC Remedy Mid Tier Guide, Including parameters in saved or defined searches, page 91. Description Defines the name of the predefined search that users see in the Search menu in BMC Remedy User. If you do not enter a Description, the text in the Name field is used. For example, if you enter Open Requests in the Name field and Search for open requests in the Description field, users see Search for open requests when they view the list of Defined Searches. Qualification Creates search criteria that you want users to access from the Search menu. Use it for any search that your users frequently perform; for example, 'Status' < "Closed by QA", to find all requests that are not closed. Click in the Qualification cell and click the ellipsis button that appears to open the expression editor for help in building the qualification. For information about building qualifications, see the Workflow Objects Guide, Creating and managing form views, page 393. Table 13-10: Form view properties - Labels category Name Entry Point, New Mode Entry Point, Search Mode Description Defines the label of a new (submit) entry point that appears in an application list field. For more information, see Chapter 14, Defining entry points and home pages.
Note: You enable the entry point in the forms Form Properties.

Defines the label of a search (query) entry point that appears in an application list field. For more information, see Chapter 14, Defining entry points and home pages.
Note: You enable the entry point in the forms Form Properties.

For each view, use the Menu Access category to control which menu and toolbar items users can access in BMC Remedy User and which buttons appear in the toolbar of a form viewed in a browser. For example, if you do not want users to have Modify All capability, you can disable it.

Chapter 13

Creating and managing form views

409

BMC Remedy Action Request System 7.6.04

In the Menu Access category, select the Accessible Menu Items property and click the ellipsis button to open the dialog box.
Table 13-11: Form view properties - Menu Access Items dialog box (Sheet 1 of 2) Name Description BMC Remedy User menu item Browser toolbar button +

Advanced Search

If set to False, the Advanced Search capability is disabled. If workflow shows or hides an Advanced Query bar form action field (ID 1005), the toolbar button should toggle 1005 to the opposite state. (In such a case, you should remove the Advanced Search button from the toolbar for that view.)

Auto Refresh

If set to False, all user actions to invoke AutoRefresh (polling refresh) of the results list are disabled. If set to False, Clear and Clear All are disabled. If set to False, Delete is disabled. If set to False, help is disabled. If set to True and a user clicks the button in a browser, the help opens in a new window.

Clear All Delete Help

+ + +

+ + +

Home

If set to False, the menu, button, and keyboard actions for opening the home page are disabled. If set to True and a user clicks the button in a browser, the home page opens in a new window.

Logout Modify All New Request New Search Options Print

If set to False, Logout is disabled. If set to False, Modify All is disabled. If set to False, New Request is disabled. If set to False, New Search is disabled. If set to False, Options is disabled. If set to False, the ability to print the entry is disabled. This includes disabling the print option of table and results list fields on a form. If set to False, the ability to generate a report on data in this form is disabled. This includes disabling the report option of table and results list fields on a form. If set to False, the menu, button, and keyboard actions for saving a request are disabled. This is useful when users do not need to save a form, such as in control panels. This option can also force the user to save by using a button you create on your form. If set to False, Saved Searches is disabled. + + + + +

+ + + +

Reporting

Save

Saved Searches

410

Form and Application Objects Guide

Including and excluding fields from form views

Table 13-11: Form view properties - Menu Access Items dialog box (Sheet 2 of 2) Name Description BMC Remedy User menu item + Browser toolbar button +

Search

If set to False, the menu and button actions for searching for requests are disabled. This is useful when users do not need to search a form, such as in control panels. This option can also force the user to search by using a button you create on your form. If set to False, Set to Defaults is disabled. If set to False, Status History is disabled. If set to True, when the user clicks the button in a form viewed in a browser, the status history opens in a new window.

Set to Default Status History

+ +

+ +

Table 13-12: Form view properties - Results category Name Initial Row Selection Description Defines the item you want selected when the results list is loaded. Select First, Fire WorkflowThe first item is shown selected and any workflow defined is activated. This is the default setting. No SelectionNo item is selected. Results Color Controls the color of requests that appear in the results list pane after a search in BMC Remedy User. In the Results Color dialog box, select a Selection Field and a color for each value. For example, you can choose to color all New requests red and all Assigned requests green. Defines how many rows of data to return at one time (or chunk) if a search yields a long list of requests in the BMC Remedy User results list pane. Buttons are provided for displaying previous and next chunks. A value greater than zero in this field enables the chunking feature. The default value is 0.

Size of Chunk

Including and excluding fields from form views


Use the Add/Remove Fields in View dialog box to specify which fields appear in a form view the Views field property to specify the form views in which a field appears. Include only fields relevant to the users of the form view. Exclude fields used for internal workflow. Fields that are not on a form view are still available for workflow.

NOTE
Any field not in the current view does not affect the change flag, even if the Disable Change Flag field property is not selected. Associate a SET-CHANGE-FLAG Run Process action with a field not in the view to set the change flag as needed. For more information, see Disable Change Flag on page 506 and the Workflow Objects Guide, Using Run Process and $PROCESS$ commands, page 257.

Chapter 13

Creating and managing form views

411

BMC Remedy Action Request System 7.6.04

To add and remove fields in a form view


1 Open a form in BMC Remedy Developer Studio. 2 Click the form view tab of the appropriate view at the bottom of the form editor. 3 Choose Form > Add/Remove Fields On View. 4 In the Add/Remove Fields in View dialog box, select fields in one list and click the

arrow buttons to move them to the other list, or click the double-arrow buttons to move all the field to one of the lists.
5 Click OK to close the dialog box. 6 Choose File > Save to save your changes.

To add or remove a field from form views:


1 Open the appropriate form, and select the field. 2 In the Properties tab, select the Views value, and then click its ellipsis button.

In the Views dialog box, all views defined for the form appear in the Not In Views list and the In Views lists.
3 Use the Add and Remove buttons to move the views to the appropriate list. 4 Click OK.

NOTE
You cannot use the Views dialog box to remove a field from the current form view. To do that, see Including and excluding fields from form views on page 411.

Arranging fields in a form view


Use layout commands to arrange fields in a form view. You can specify the amount and type of spacing for fields in a form view. Carefully arranging fields can help improve the appearance and usability of a form view by providing greater consistency.

NOTE
When you design form views, you should design them for a particular screen resolution. For example, a form view designed for a 1280 by 1024 screen resolution might look incorrect on a 1024 by 768 screen.

412

Form and Application Objects Guide

Arranging fields in a form view

Selecting multiple fields


Select a field in a form view by clicking it in the form editor or by clicking its name in the Outline tab. The Layout operations apply to two or more fields. The last field you select is the alignment field. The alignment field has filled square handles. The other selected fields have empty squares as handles.
Figure 13-4: Alignment field

Alignment field

Use any combination of the following three methods to select multiple fields.

To select multiple fields in the form editor


1 Click a field to select the first field. 2 Hold down SHIFT and click a field to add it to the selection. 3 Hold down CONTROL and click a fields to add it to or remove it from the

selection.

To select multiple fields using the marquee


1 With the mouse on the form view background, hold down the right mouse button.

The mouse pointer changes to a cross.


2 Drag a rectangle to enclose fields to create a selection with those fields. 3 Hold down SHIFT and drag a rectangle to enclose fields to add to the selection the

enclosed fields.
4 Hold down CONTROL and drag a rectangle to enclose fields to add to or remove

from the selection the enclosed fields.

NOTE
To use the marquee in a container field, select the Marquee tool from the Palette. The mouse pointer remains a cross until you select another tool from the Palette or close the editor.

Chapter 13

Creating and managing form views

413

BMC Remedy Action Request System 7.6.04

To select multiple fields in the Outline tab


1 Click a field name to select the first field. 2 Hold down SHIFT and click another field name to add to the selection all the fields

between the last field selected and that field.


3 Hold down CONTROL and click a field name to add it to or remove it from the

selection.

NOTE
Due to a technical limitation, selecting a field in the Outline tab does not change the alignment field.

Sizing fields
Use field handles, arrow keys, field properties, or command on the Layout menu to set the size of field labels and values.

To resize a selected field


Using the field resize handles, drag the left or right resize handle to increase or decrease the size or drag the center resize handle to set the sizes of the label and value parts. If you move the center resize handle to make the label area too small for the label, the mouse pointer becomes a circle-with-slash prohibited symbol. Using the field properties, set the Data Length and Width properties in the Properties tab. Using the arrow keys, press the period until the double-arrow resize mouse pointer shown in Figure 13-5 appears on the appropriate resize handle, press the left and right arrow keys until the field is the correct size, and then press period or Enter to complete the resize or Escape to cancel it.
Figure 13-5: Resize mouse pointer

To resize two or more fields


1 Select two or more fields. 2 Use the mouse or the arrow keys to move one of the resize handles on one of the

fields. All the selected fields are resized relative to the field you operate on.

414

Form and Application Objects Guide

Arranging fields in a form view

To make fields the same size using commands


1 Select two or more fields.

The other fields size are set to the size of last field you select, the alignment field.
2 To make the size of the other fields labels the same as the size of the alignment

fields label, choose Layout > Size Fields > Size Label.
3 To make the size of the other fields values the same as the size of the alignment

fields value, choose Layout > Size Fields > Size Value.

To make fields the same size using field properties


1 Select two or more fields. 2 In the Properties tab, set the Data Length, Label Width, and Width to the correct

values. The values are changed for all fields. This is an example of setting common field properties.

NOTE
Use this method to set other common field properties that apply only to the current form view. Among these are, Label Alignment, Label Justification, and Label Location.

Aligning fields using the grid


Use a grid to align fields precisely along a network of lines. Use commands on the Layout menu to set up and display the grid and enable grid alignment. Displaying the grid and enabling grid alignment are independent operations. You can use grid alignment with no grid visible or show the grid without using it for alignment. Grid alignment is only active when you drag fields to position them in the form view. It is not active when you use the alignment commands or the other methods described in Positioning fields on page 416.

To set up the alignment grid


1 To set the spacing of the grid lines, choose Layout > Grid Size, and enter the

horizontal and vertical space in pixels between grid lines in the Set Grid Size dialog box. Valid values are 2 to 100 pixels. The default value is 25 pixels.
2 To display or hide the grid, choose Layout > Show Grid.

The grid spacing and visibility are saved in the workspace when you exit and restored when you start BMC Remedy Developer Studio.

Chapter 13

Creating and managing form views

415

BMC Remedy Action Request System 7.6.04

To enable or disable grid alignment


1 To enable horizontal grid alignment, choose one of the following options from the

Layout > Align to Grid menu: NoneDisable grid alignment. LeftAlign the left edge of the field label with a vertical grid line. Value LeftAlign the left edge of the field data entry region with a vertical grid line. RightAlign the right edge of any button associated with the field with a vertical grid line. If there is no button, align the right edge of the field data entry region. Value RightAlign the right edge of the field data entry region with a vertical grid line.
2 To enable Vertical grid alignment, choose one of the following options from the

Layout > Align to Grid menu: TopAlign the top edge of the field with a horizontal grid line. BottomAlign the bottom edge of the field with a horizontal grid line.
3 To disable grid alignment, choose Layout > Align to Grid > None.

The state of grid alignment is saved in the workspace when you exit and restored when you start BMC Remedy Developer Studio.

To align fields to the grid


Drag selected fields to the correct position in the form view. The alignment field is aligned to the grid according to the selected options. If other fields are selected, they move with the alignment field and keep their positions relative to it. They are not necessarily aligned to the grid.

Positioning fields
Position fields in a form view by dragging them, by using the arrow keys, or by setting their position properties. You might want to zoom the display to help you position fields precisely.

To zoom the display of the form view


To display the fields larger, choose Layout > Zoom In. To display the fields smaller, choose Layout > Zoom Out.

416

Form and Application Objects Guide

Arranging fields in a form view

To position one field by dragging


Drag the field to appropriate position in the form view. To move the field only horizontally or only vertically, hold down SHIFT and drag. If grid alignment is enabled, the field snaps to the grid.

To position fields by dragging


1 Select two or more fields. 2 Drag the fields to appropriate position in the form view.

To move the fields only horizontally or only vertically, hold down SHIFT and drag. If grid alignment is enabled, the alignment field snaps to the grid. The other fields move with the alignment field and keep their positions relative to it.

To position fields using the arrow keys


1 Select the fields to move. 2 Press and release the period key once.

The mouse pointer changes to a four-way arrow resize mouse pointer shown in Figure 13-6.
3 Press the arrow keys to move the fields. 4 Press and release the period or Enter to complete the move, or press Escape to

cancel the move.


Figure 13-6: Move mouse pointer

To control how far the fields move for each press of an arrow key
1 Choose Window > Preferences. 2 Expand BMC Remedy Developer Studio and click Form. 3 Type the number of pixels for the fields to move for each press of an arrow key in

the Keyboard Move Step Size field.


4 Click OK.

Chapter 13

Creating and managing form views

417

BMC Remedy Action Request System 7.6.04

To get help aligning field when you position them


1 Choose Layout > Snap to Geometry. 2 Start to position fields by dragging or using the arrow keys.

As the fields move in relationship to other fields in the form view, blue lines appear when edges or centers of the fields align.
3 Position the fields when the lines indicate the relationship you want.

If both the grid alignment and Snap to Geometry are enabled, you can drag fields to field geometry positions that are not aligned with the grid lines.
4 Choose Layout > Snap to Geometry again to exit Snap to Geometry mode.

To move all fields in a form view proportionally


1 Choose Layout > Expand. 2 In the Expand dialog box, type the percentage to change the horizontal and vertical

positions of the fields.


3 Click OK

All the fields are moved with respect to the left edge and top edge of the form view by the factors you specified. A percentage less than 100 moves the fields closer together and to the left or up. A percentage greater than 100 moves the fields farther apart and to the right or down.

To position fields by setting properties


1 Select the fields to move. 2 In the Properties tab, set the X or Y property to the correct values.

The values are changed for all fields. If you set both X and Y, the fields are positioned stacked in the same location in the form view. This is an example of setting common field properties.

418

Form and Application Objects Guide

Arranging fields in a form view

Aligning fields using commands


Use Layout > Align Fields commands to align fields in a form view to the alignment field horizontally or vertically.

To align fields horizontally


1 Select two or more fields.

The other fields size are aligned to the last field you select, the alignment field.
2 Choose the appropriate command from the Layout > Align Fields menu:

Align LeftMoves the other fields so their left edges are aligned with the left edge of the alignment field. Align RightMoves the other fields so their right edges are aligned with the right edge of the alignment field. Align Value LeftMoves the other fields so the left edges of their data entry regions are aligned with the left edge of the data entry region of the alignment field. Align Value RightMoves the other fields so the right edges of their data entry regions are aligned with the right edge of the data entry region of the alignment field.

To align fields vertically


1 Select two or more fields.

The other fields size are aligned to the last field you select, the alignment field.
2 Choose the appropriate command from the Layout > Align Fields menu:

Align TopMoves the other fields so their top edges are aligned with the top edge of the alignment field. Align MiddleMoves the other fields so their horizontal midlines are aligned with the horizontal midline of the alignment field. Align BottomMoves the other fields so their bottom edges are aligned with the bottom edge of the alignment field.

Chapter 13

Creating and managing form views

419

BMC Remedy Action Request System 7.6.04

Anchoring fields to the right side of a form or panel


By default, the horizontal position of a field in a form or panel is based on its distance from the left side of its container. This distance remains the same regardless of the size of the container. The fields distance from the right side of the container, however, varies depending on the size of the container. For example, the logo in the following figure appears in the top-right corner of the form:

But when the browser window is enlarged, the logo no longer appears in the topright corner because its horizontal position is set relative to the left side of the form:

To prevent the distance between a field and the right side of a form from changing, you must anchor the field to the right side of the form instead of to the left side:

420

Form and Application Objects Guide

Arranging fields in a form view

This feature is available only in the mid tier, not in BMC Remedy User.

NOTE
When a container has fields anchored to both its left and right sides, those fields might overlap if users substantially reduce the width of the browser in which the container is displayed. In most browsers, the distance between the field and the side of the container to which it is anchored remains the same as the browser shrinks, and the field moves off-screen on its unanchored side. In a Firefox browser, however, right-anchored fields eventually stop moving left and disappear under the right side of the browser. Keep this in mind when designing such containers.

To anchor a field to the right side of a form or panel


1 Open the appropriate form in BMC Remedy Developer Studio. 2 Set the Layout Style property of the form or panel to XY. 3 Select the field that you want to anchor. 4 Set the fields Alignment property to Right. 5 Use one of these methods to position the field:

Enter the appropriate number of pixels in the fields X (distance from right side) and Y (distance from top) properties. Drag the field to the appropriate position. The fields X and Y properties are automatically updated.
6 Save the form.

The current distance between the field and the right side of its container will be maintained when the container is displayed in a browser regardless of the width of the browser window.

Tips for aligning and resizing fields


Use the following tips for aligning and resizing fields in a form: Use the grid. Setting the grid width and height to 10 should allow you enough control to align the fields in your form precisely. Keep the grid on for accurate alignment of your fields. Align the field labels before you align the data entry regions, as shown in Figure 13-7. To help with alignment, set the Align to Grid option to Left. If you select multiple fields, the fields are grouped and cannot be modified individually. After you align the field labels, click anywhere in the form. Then select the field and resize its data region individually. After selecting a field, the resize handles appear for the field, as shown in Figure 13-7. Select the resize handle for the data region and stretch it to the appropriate alignment and size. For example, you can stretch data regions so that the fields align. Then you can stretch the data region again so that the menu boxes align.

Chapter 13

Creating and managing form views

421

BMC Remedy Action Request System 7.6.04

Figure 13-7: Aligning data regions


Align here. Align here.

Stretch data region here to align under Short Description field.

Then, stretch data region to align the end of the field and the menu boxes.

Spacing fields
Use Layout commands to distribute three or more fields with even spacing in a form view. You can distribute the fields evenly between the top and bottom fields or the leftmost and rightmost fields or by specifying the space between the fields.

To distribute fields evenly between two fields


1 Move the top and bottom or leftmost and rightmost fields to their final positions. 2 Select all the fields to distribute. 3 Choose the appropriate command from the Layout > Space Fields menu:

Evenly HorizontallyMoves the interior fields so there is an equal amount of space between the right edge of each field and the left edge of the field on its right. Evenly VerticallyMoves the interior fields there is an equal amount of space between the bottom edge of each field and the top edge of the field below it.

To position fields with the same spacing between them


1 Move the top or leftmost field to its final positions. 2 Select all the fields to space. 3 Type the number of pixels of spacing between the fields in the toolbar edit box.

The spacing value must be a positive integer.


4 Choose the appropriate command from the Layout > Space Fields menu:

By Length HorizontallyMoves the fields to the right of the leftmost field so the amount of space between the right edge of each field and the left edge of the field on its right is equal to the spacing value. By Length VerticallyMoves the fields below the top field so the amount of space between the bottom edge of each field and the top edge of the field below it is equal to the spacing value.

422

Form and Application Objects Guide

Rendering forms in right-to-left format

Stacking fields
You can position two or more fields in a form view so they overlap. Use the staking order commands to control which fields covers the others.

To bring fields to the front


1 Select one or more fields.

At least one of the fields must overlap a field that is not selected.
2 Choose Layout > Bring to Front.

The fields move to the top of the stacking order, covering all fields they overlap.

To send fields to the back


1 Select one or more fields.

At least one of the fields must overlap a field that is not selected.
2 Choose Layout > Send to Back.

The fields move to the bottom of the stacking order and are covered by all fields they overlap.

Rendering forms in right-to-left format


The text direction of languages such as Arabic and Hebrew flows from right to left (RTL) instead of the Western left to right (LTR). With BMC Remedy Developer Studio, you can create form views with a RTL flow that display an RTL flow in an Internet Explorer version 6 or later browser. Other browsers, such as Mozilla Firefox and Apple Safari browser, are not supported. (The form view does not appear or function properly in these browsers.) BMC Remedy User cannot display RTL flows. The current version of BMC Remedy Flashboards does not support RTL. For more information, see the Integration Guide, Configuring right-to-left format in a data visualization field (DVF), page 182.

Chapter 13

Creating and managing form views

423

BMC Remedy Action Request System 7.6.04

To change a form views to right-to-left display


1 In BMC Remedy Developer Studio, open the form view. 2 Click in an empty area of the form so that the view properties appear in the

Properties tab.
3 Set the value for the Right To Left property to True.

The current version BMC Remedy Developer Studio does not support what-yousee-is-what-you-get (WYSIWYG) editing for RTL.
4 Save the form. 5 To see the form view displayed with a RTL flow, open the form view in Internet

Explorer version 6 or later.

Setting the tab order of fields in a form view


The field tab order determines which the order the fields in the form view get the input focus when the user presses the TAB key in BMC Remedy User or in a browser. If you do not define the tab order for a form view, the default tab order is based on the X and Y positions of the field in the form view and moves from left to right, then down (as you would read the form). By default, a field added to the top of a form view receives the input focus before a field added to the bottom of a form view, regardless of the order in which they were added to the form. Use the Layout > Tab Order commands to set any tab order regardless of the position of a field in the form view. For example, if the form view has columns of fields, you can set the tab order to go down the columns, top to bottom and then left to right. Or you can define a tab order that starts with all required fields, and then goes to the optional fields. Also, because different views of the same form can have different tab orders, you can define tab orders so that different groups of users are taken first to the fields that are the most important to them. You cannot use tab order control to make tabbing move from a field in one form view to a field in a different form or view. You also cannot use tab order to make tabbing move on to, off of, or between panels.

424

Form and Application Objects Guide

Setting the tab order of fields in a form view

To set the tab order by editing the form view


1 Choose Layout > Tab Order > Select and Edit to enter the Select and Edit mode.

A box with the tab sequence number appears on each field in the form editor. The sequence numbers begin with zero.
2 Select a field, click a tab sequence number box, type the new number, and press

ENTER or click the outside the field. The tab sequence numbers of the other fields are adjusted.
3 Repeat step 2 until you have set the tab order. 4 Choose Layout > Tab Order > Select and Edit again to exit the Select and Edit

mode. The boxes with the tab sequence numbers are removed from the fields.

To set the tab order by clicking fields


1 Choose Layout > Tab Order > Increment on Click to enter the Increment on Click

mode. A box with the tab sequence number appears on each field in the form editor. The sequence numbers begin with zero.
2 Click the first field whose the tab order you need to change until the tab sequence

number is correct. Click once to make the field the first field (number zero), twice to make the second, and so on. The tab sequence numbers of the other fields are adjusted as you click.
3 Click the next field whose the tab order you need to change until the tab sequence

number is correct. Click once to make the field the next in the tab order, twice to make the next plus one, and so on. The tab sequence numbers of the other fields are adjusted as you click.
4 Repeat step 3 until you have set the tab order. 5 Choose Layout > Tab Order > Increment on Click again to exit the Increment on

Click mode. The boxes with the tab sequence numbers are removed from the fields. To use Increment on Click mode to set the tab order for the initial fields in the order (or all fields), click each field once in order. You can switch between Select and Edit mode and Increment on Click mode without exiting both modes by choosing the appropriate Layout > Tab Order command.

Chapter 13

Creating and managing form views

425

BMC Remedy Action Request System 7.6.04

To set the tab order to the default


Choose Layout > Tab Order > Set Default. You can set the tab order to the default when you are in either of the tab order editing modes or in neither mode.

NOTE
Fields that are on panels appear as nested under the panel on the Set Tab Order window. Shared fields on panels appear under each panel on which it is shared. You can set the tab order differently on different panels. See Shared fields in panel holders on page 349.

Applying skins to form views


Although views provide a good way to customize the look of forms for differing audiences and purposes, maintaining views can become complicated in situations where copies of all views must be provided for multiple sets of users (for example, multiple companies). Another way to provide a customized look and feel of components in a form for different groups is through the use of skins. Skin is a term commonly used to describe the appearance and layout of pages in a website. Skins are also called themes in some environments. In AR System, skin refers to the ability to change the appearance of components (such as panels, character fields, or tables) on a view of an AR System form without having to modify any form or view definitions. By being able to change skin properties for a form view, the same view of that form can appear differently to different groups of users, based on the permissions specified for the skin. For example, for user group A, a form view might have panels with a blue background in the header (Figure 13-8); for user group B, those same panel headers might have a green background (Figure 13-9).
Figure 13-8: Using skins to distinguish views for user group A

426

Form and Application Objects Guide

Applying skins to form views

Figure 13-9: Using skins to distinguish views for user group B

Properties to which skins can be applied


The following table outlines the types of object properties to which skins can be applied. Skins are supported primarily for images, colors, and backgrounds; they are not used for positioning, visibility, or dimensions.

NOTE
Although the Skin Selector field property is listed for other fields types (such as character and other data fields), entering a value for this property does not affect those fields. Only the fields listed in the following table support skins.
Object View Panel (not the panel holder) Properties that support skins Background Image Background Color Header Background Color Header Label Color Background Image Background Color Border Color Image URL Color (for buttons displayed as URLs) Label Text Color Background Color URL Color Label Text Color Background Color Line Color

Control (button)

Trim Text

Trim Box

Chapter 13

Creating and managing form views

427

BMC Remedy Action Request System 7.6.04

Object Line Vertical Navigation

Properties that support skins Line color Top level background color Top level background gradient Sub level background color Top level text color Sub level text color

Types of skins
AR System provides the following types of skins. Each skin type has a priority level by which it is applied, with 1 being the highest:
1 View Name + Form Name 2 View Name Only 3 View Label + Form Name 4 View Label Only 5 Form 6 Application 7 Server

How skin priorities are applied


Higher priority skin types take precedence over lower priority types. The skin type View Name takes precedence over the type View Label; which takes precedence over Skin Selector, and so on. For example, if you have a View Name skin with a blue background and a Form level skin with a green background, the blue background is displayed because the View Name skin has the higher priority. If you have multiple skins with the same priority level and the same properties in an application, the skin that was created most recently takes precedence. For example, suppose that View Name Skin A is created at 08:30 on 02/07/10 and View Name Skin B is created at 10:30 on 02/07/10, and both skins define a panel header color. Skin B takes precedence and overwrites Skin A. If the two skins define different properties (for example, if Skin A defines a panel header color and Skin B defines a background color), Skin B does not overwrite Skin A.

428

Form and Application Objects Guide

Applying skins to form views

How field display property priorities are applied


Before rendering the HTML for the form, the mid tier server uses the display properties defined for the skin to override the field display properties stored as part of the form definition. These properties have the following priority levels:
1 Field ID 2 Field Skin Selector 3 Field Type

Properties for a field skin selector take precedence over properties for a field type. Properties for a field ID take precedence over properties for a field skin selector.

Skins and permissions


Each defined skin is associated with a set of permissions. Those permissions determine which groups of users can see a form or view with a particular skin. For example, a skin with administrator permissions might have some trim text or panel headers set to one color, while the Public group might see these same components set to another color.

Skins and localized views


For localized applications, you can have a form view across multiple locales sharing the same skin. For example, you can specify a skin based on the view label such as Request Console.

Chapter 13

Creating and managing form views

429

BMC Remedy Action Request System 7.6.04

Defining skins
Administrators can define skins by using the AR System Skins form (Figure 13-10), which is installed with AR System. Entries in this form specify the properties and the permissions for each skin that you want to define. Each skin you define is an entry in the form.
Figure 13-10: AR System Skins form

To define a skin
1 Open the AR System Skins form: http://<serverName>/arsys/forms/<serverName>/AR+System+Skins 2 Enter the following information:

DescriptionEnter a brief description of the skin. StateSelect Enabled to make the skin available, or Disabled to disable it temporarily. TypeSelect a skin type. Type identifierEnter additional information about the skin type being defined. GroupsSelect the groups and roles to have access permissions for this skin.
3 Click the plus sign to the right of the Skin Properties banner to open the AR System

Skins Properties dialog box (Figure 13-11).

430

Form and Application Objects Guide

Applying skins to form views

Figure 13-11: Skins Properties dialog box

4 Enter the following additional property information:

TypeSelect Field ID, Field Skin Selector, or Field Type. For more information, see How skin priorities are applied on page 428. Type identifierEnter a description that identifies the property type. PropertyEnter the object type (for example, panel) and the type of property being applied (for example, background color).

NOTE
The fields in the AR System Skins Properties dialog box are not validated, so if you enter Field Type in the Type field, select a property from the same type that you entered in the Type Identifier field. Otherwise, the skin property might not be applied. (Consequently, fields of different types can sometimes share the same property ID, in which case that skin property may be applied). Property ValueEnter the value for the specified property. For example, if the property is a background color of blue, the value must be the hexadecimal value for the shade of blue being applied. If the property is an image, the value must be the name of the server image object. To specify colors, you can either enter a hexadecimal value for the color, or click the down arrow to select a color from the color picker.
5 Click OK to close the AR System Skins Properties dialog box.

The information you entered appears in the Skins Properties list in the AR System Skins form (Figure 13-12).
Figure 13-12: Skins properties list

Chapter 13

Creating and managing form views

431

BMC Remedy Action Request System 7.6.04

After a skin is defined, it can be applied to these scenarios: All forms and views on a server All forms and views in an application All views in a form A specific view of a form

Activating skins through the mid tier


To activate the display of skins, complete the following procedure.

To activate skins through the mid tier


1 Select the Enable Skins option in the General Settings page of the Mid Tier

Configuration Tool. (See the BMC Remedy Mid Tier Guide , General settings, page 22.)
2 Flush the mid tier cache. (See the BMC Remedy Mid Tier Guide, Cache settings,

page 29.)
3 Flush the browser cache. 4 If the form view was cached: a Stop and restart the mid tier. b Delete the viewStats.dat file in midTierInstallDir\midtier\WEBINF\classes. 5 Restart the web server.

432

Form and Application Objects Guide

14

Chapter

Defining entry points and home pages


This section describes how to use BMC Remedy Developer Studio to configure a home page and entry points. The following topics are provided: Overview of home pages and entry points (page 434) Using a home page (page 434) Using entry points (page 437) Using the AR System Customizable Home Page (page 443) Using the Home Page form (page 450) Creating a home page form (page 451) Using style sheets with application list and navigation fields (page 452) Viewing a subset of entry points (page 454) Home page navigation aids (page 456) Configuring home page preferences (page 457)

Chapter 14

Defining entry points and home pages

433

BMC Remedy Action Request System 7.6.04

Overview of home pages and entry points


A home page is a form that provides a single point of access for users into AR System. Although users can locate applications and forms by using the Object List, a home page form makes access to AR System much less complicated by presenting only the necessary entry points for the most common tasks. Users do not need to scroll through a long list to find a form and do not need to know which server and form to open to perform a given task. A home page has the following characteristics: It is any form that contains an Application List field. Two preconfigured home page forms are installed with AR System. It appears automatically when users log in to AR System. In a browser, the URL http://hostName/arsys/home automatically opens the configured home page. It is identified for the server by server and mid tier configuration settings, and optionally for specific users by a user preference setting. It contains a list of entry points in the Application List field. Entry points are links that users click to open forms and applications, such as a search window for a Help Desk application. Entry points are associated with forms and active link guides, allowing application designers to package common starting points that all users can easily access. When an entry point exists, it automatically appears in the Application List field on the home page. Administrators control the appearance of the home page and determine which form appears as the home page when a user logs in. Mid tier administrators must identify the server that hosts the home page in the Mid Tier Configuration Tool. If the AR System Customizable Home Page is used, administrators can define different home page layouts according to access control groups. You can also suppress the home page for specific users by setting a user preference in the User Preference form or in the BMC Remedy User options. The AR System home page supports opening a form on the existing open window or opening a form on a new window. When you click an entry point on the Application List field, the form opens on the same window, replacing the existing content. When you perform a Shift+Click procedure (press the Shift key on the keyboard and click the left mouse button) on an entry point present in the Application List field, the form opens on a new window. Depending on the browser, the form opens on a new window or a new tab.

Using a home page


The administrator specifies the default home page for a server by setting the Default Home Page option in the Configuration tab of the Server Information form. If a mid tier serves more than one AR System server, you must also configure the mid tier to use a specific server as the home page server. See Configuring home page preferences on page 457.
434 Form and Application Objects Guide

Using a home page

Two preconfigured home page forms are installed with AR System. You can use either of these forms as a starting point when designing a home page: AR System Customizable Home PageThis display-only form works together with the AR System Home Page Layout and AR System Home Page Descriptor forms. The customizable home page is customizable by users, within constraints defined by the administrator. The administrator defines the default layout and the form views that appear at login according to the users group permissions. You can define different default home pages for different groups. See Using the AR System Customizable Home Page on page 443. Home PageThe traditional AR System home page. Entry points appear as links, or you can configure the Application List field to look like a navigation bar with entry points appearing as flyout menu items. Figure 14-1 illustrates a sample customizable home page. It contains an Application List field with multiple entry points. One of the customizable panels is shown, containing a view of the User form. Up to four panels can appear by default. The user can minimize each panel, delete it, or select another form to appear in the panel from a list of available views. Each user can save one customized home page, and can return to the default home page if necessary. The Application List field is collapsible, and is formatted to look like a vertical navigation bar. Entry points appear as flyout menu items, as shown in Figure 14-2.
Figure 14-1: Example AR System Customizable Home Page with application list

Figure 14-2: Sample AR System Customizable Home Page with entry points in flyout menu

Chapter 14

Defining entry points and home pages

435

BMC Remedy Action Request System 7.6.04

Figure 14-3 illustrates the traditional Home Page form containing multiple entry points and fixed form contents.
Figure 14-3: Example Home Page form with application list
System-generated heading that lists the user logged in to AR System.

Password management entry point Deployable application label Search window entry point New window entry point

The home page forms contain the following components: System-generated headingShows the home page banner heading, page title and the name of the user logged in to AR System. Application list field, which includes of the following items: Application headingWhen you create a deployable application and include any forms with entry points, the application name appears as the heading in the home page by default. If you add a label to your application, the label appears as its heading. Entry points In the properties for a form, you can specify an entry point that opens the form in New or Search mode. Entry points for forms that are not part of a deployable application appear in the Quick Links section. Entry point guidesWhen you create an active link guide, you can specify an entry point that opens the guide. In this case, the guide functions exclusively as an entry point. Make the labels for entry points task-specific and easily identifiable, for example,
Generate a New Request or New Employee Setup. The following table outlines

where labels for each item in the application list are derived from.
Table 14-1: Labels in an application list Label on application list Applications heading Form entry points Where the label is derived from The label of the application (deployable applications only) The following form view properties in the Properties tab: Entry Point, New Mode Entry Point, Search Mode Entry point guides The label of the active link guide

436

Form and Application Objects Guide

Using entry points

Using entry points


Entry points make access to tasks easier to control and maintain. Application designers and administrators must work together to manage the links that appear on the home page. Application designers are responsible for: Designing the application. Defining the entry points used to interact with the application. Setting the correct permissions within the application so that the appropriate users see the appropriate entry points. Performing localization tasks, if any. Application designers do not need to have knowledge of the actual home page form where the entry points will appear. Administrators are responsible for: Installing the application. Configuring the server and mid tier to use the correct home page form. (Optional) Designing the home page form. Depending on which form is designated as the default home page for the server, this can include: Defining layouts for the AR System Customizable Home Page. Modifying the Home Page form Creating a separate form to use as the home page. (Optional) Changing the Home Page settings in the mid tier Configuration Tool or the Configuration tab of the AR System Administration: Server Information form to specify the server and form for the home page. (Optional) Specifying a home page form for each user in the User Preferences form. (Optional) Helping users specify BMC Remedy User options to behave correctly for each user.

TIP
You do not need to make entry points for every starting point, only for those most frequently used. If you have a large number of entry points (for example, over 30), consider using the subset mechanism (see Viewing a subset of entry points on page 454) to limit the number of entry points displayed.

Chapter 14

Defining entry points and home pages

437

BMC Remedy Action Request System 7.6.04

Types of entry points


AR System provides three types of entry points: Default new entry points to open a form in New mode. Default search entry points to open a form in Search mode. Entry point active link guides that allow you to use all the functionality of a guide. For example, you can use an entry point guide to run reports or Modify or Display windows, or to run AR System workflow. This guide functionality is hidden from users. They do not know the entry point is a guide; they simply see this advanced functionality as another entry point. Detailed procedures for creating entry points are described in Creating form entry points on page 439 and Creating entry point guides on page 440. BMC Remedy User and the mid tier differ slightly in how entry point guides behave: In BMC Remedy User, you can access an application without knowing which form performs which task, but you must know which servers to log in to. In a browser, you can access an application without having to log in to a particular server, or without knowing which form performs which task.

NOTE
Initially, the browser displays entry points differently than BMC Remedy User does. For more information, see Understanding how a home page appears in a browser on page 459. Entry points are designed to hide underlying forms, applications, and guides and give users one point of access. In BMC Remedy User, the home page functions like a control panel and opens automatically after you log in (unless you disable it). In BMC Remedy User, you can still access the classic Open dialog box by choosing File > Open > Object List. In addition, BMC Remedy User lists the most recently accessed entry points by choosing File > Recent Entry Points. For more information, see Understanding how a home page appears in BMC Remedy User on page 461. Finally, you can localize entry points just like other AR System components. For more information, see Appendix H, Localizing AR System applications.

438

Form and Application Objects Guide

Using entry points

Creating form entry points


This section describes how application designers define a form entry point. These steps are the minimum for displaying entry points in the home page to open New or Search windows. You can mix and match entry points on your form as needed. For example, you might need only a Search entry point but not a New entry point. To create form entry points, enable entry points for the form, and then create custom labels for each view of the form, as described in the following procedures.

NOTE
Based on user preferences for locale and default view, different views of a form might be selected as entry points for each user login. For more information about how views are selected for users, see How a form view is selected for the user on page 394.

To create form entry points


1 Create a form (for example, Customer Order Form). 2 Choose Form > Form Properties. 3 In the Form Properties dialog box, select the Entry Points page. 4 Enable the modes for the entry points:

For a New Mode entry point, select Enable Entry Point. For a Search Mode entry point, select the Enable Entry Point check box.
5 In the Application List Display Order field for each mode you selected, enter a

value to order the mode entry point in the application list. The value must be greater than or equal to 1. It determines the order of entries in the application list. For example, an entry point with a value of 101 appears in the list after an entry point with value of 100. If the entry point orders are the same for multiple entry points, the order they appear in the Application List field is random. Plan the order of your entry points carefully. You can have gaps in the numbering.
6 Click OK, and save the form. 7 Make sure that your form and its fields have adequate permissions for users to

view the correct information. Users see only the entry points that they have permission to access.
8 (Optional) Add a Home Page form action button to your forms so that users can

easily return to the home page with one click. See Home page navigation aids on page 456.

Chapter 14

Defining entry points and home pages

439

BMC Remedy Action Request System 7.6.04

To configure custom view labels for entry points


1 Select a view of the form. 2 Click in an empty area on the form so that the Properties tab displays the form

views properties.
3 In the Properties tab, set the following values to define the label that you want to

appear for the forms entry points in the application list: Entry Point, New Mode Entry Point, Search Mode
4 Repeat step 1 and step 3 for each view of the form.

If you do not define a label string, the Application List field displays the entry points by their form name.

Creating entry point guides


The following section describes how to define entry point active link guides. Use entry point guides to run complex workflow, for example, to open an application console. An entry point guide is an active link guide that belongs to the form being opened and the starting active link that opens the form. If you do not plan your active links carefully, unexpected behavior might occur. For other considerations when creating workflow, see Workflow issues with active links and entry point guides on page 441.

To create an entry point guide


1 Create an Open Window active link that will open the entry points form and start

the entry point guide. You can include additional actions, but you must create at least one Open Window action to open the forms window from your entry point. For information about creating active links and active link guides, see the Workflow Objects Guide.
2 Create an active link guide. a Specify the information required in the Associated Forms, Display, and Entry

Point panels. Here you specify the active link that opens the form (which you created in step 1). In the Application List Label field, enter a descriptive label; otherwise, the home page displays the guide name.
b Define your permissions.

Permissions are crucial for determining what groups of users can access your guide.

440

Form and Application Objects Guide

Using entry points

c Add any other active links you want to use that run after the form is opened

with the Open Window action you created in step 1. These active links run in the window you are opening with the starting active link. Therefore, these active links in their Form Name list must contain all the names of the forms that can be opened in the starting active link action.

Workflow issues with active links and entry point guides


Be aware of the following issues regarding how active links run inside entry point guides: When you specify the starting active link inside the entry point guide, remember that both the Run If qualification and the If and Else actions of the active link are run inside the home page form. You might not expect this behavior in the active link. To test this, create an active link that sets a field value to use inside the guide (for example, setting the Short Description field with Hello World!). Also, make the Short Description field visible on the home page form. After you run the entry point guide, you see that Hello World! appears in the home page form, not the primary form that owns the active link. As a result, while you can use any type of active link action inside the starting active link, not all operations make sense. Also, make sure your active link guide Run If qualification is valid inside every home page form that it can be run in. After the starting active link is run on the home page, the active links specified in the entry point guide are run automatically for you. As a result, you do not need to create a Call Guide action to run these active links. The active links run as defined in the context of the form opened in the starting active link of the guide. To avoid unexpected behavior, define the starting active link only with an Open Window action. Then, add other active links in the Active Links and Labels panel of the entry point guide. Alternatively, you can design your application to perform tasks like opening a URL. For example, you can create a starting active link with a Run Process action, as in the following example:
PERFORM-ACTION-OPEN-URL http://www.google.com

This active link opens the Google search engine after the user clicks the link in the Application List field.

Chapter 14

Defining entry points and home pages

441

BMC Remedy Action Request System 7.6.04

Using entry points in applications


When you create entry points in applications, plan all your permissions carefully. The entry points that a user can see in an application depend on the following factors: The Application List field displays only those applications to which a user has a license. The Application List field displays only those deployable applications to which a user has state permissions. You should also factor in the permissions associated with Groups/Roles. If users have permissions to the application but not to its underlying objects (for example, a form), they do not see the entry points. For more information about permissions, see Chapter 1, Defining access control.

To create application entry points


1 Create form entry points and entry point active link guides for the application. 2 Create an application that requires entry points, or open an existing application.

See Building deployable applications on page 91.


a (Optional) In the General panel, enter a descriptive header in the Label field.

For deployable applications, this label text appears in the home page as the application heading for your entry points. Otherwise, the application name appears by default as the heading.
Descriptive heading created from Label field.

You do not need to create a deployable application for the entry points of an application to appear in the home page. However, putting your forms into a deployable application lets you include a descriptive heading to categorize the entry points. For local applications, no headings appear. Only the list of entry points is displayed in the application list.
b On the Forms panel, add your forms to the application.

For deployable applications, make sure you use the Standard form view, unless you have must use a web view, for example, backward-compatibility with old applications and forms. See Chapter 13, Creating and managing form views.
3 Create as many applications with their forms and entry points as needed.

Applications appear in the home page in alphabetic order.

442

Form and Application Objects Guide

Using the AR System Customizable Home Page

Using the AR System Customizable Home Page


The AR System Customizable Home Page can contain up to four panels that present views of other forms, as shown in Figure 14-4. The default page layout is defined by entries in the AR System Home Page Layout form, and the forms that appear in each panel are identified by entries in the AR System Home Page Descriptor form.

NOTE
The AR System Customizable Home Page is not supported in BMC Remedy User. If you choose the AR System Customizable Home Page form as the default home page, users running BMC Remedy User will instead be directed to the old Home Page form. If you are upgrading from a earlier release and have configured a different form as the home page, and you still want to use that form as home page in BMC Remedy User, you must edit the CHG:redirect WUT active link after installation to redirect BMC Remedy User users to the form that you are using as the home page. Figure 14-4: Customizable home page with four-panel layout

Predefined panel descriptors are installed with many BMC applications. In addition, administrators can define different default layouts for different access control groups. If a user belongs to two or more groups that each have a default layout defined, the default home page that appears is determined by a priority ranking set in the layout form entries.

Chapter 14

Defining entry points and home pages

443

BMC Remedy Action Request System 7.6.04

Users can expand and collapse the panels in the customizable home page. They can also remove and add panels, and can select from the available descriptors to control which forms appear in the panels of their home page. Users can save one customized home page layout. Customized user layouts are also stored in the AR System Home Page Layout form. If the user saves a custom layout, it overrides the Default layout for that user, but the user can return to the Default layout at any time.

Defining forms, descriptors, and layouts for the home page


This section describes the tasks and procedures an administrator must complete to configure the AR System Customizable Home Page for use. The steps include:
Step 1 Create each form that will appear in a panel in the home page. See Defining form

views for the customizable home page on page 444.


Step 2 Create an entry in the AR System Home Page Descriptor form for each form view

that can appear in a home page panel. See Defining form descriptors on page 445.
Step 3 Create a default layout, and assign up to four Descriptor entries, one per possible

panel. See Defining default layouts on page 448.


Step 4 Test the configured home page. Step 5 Set the Default Home Page for the server to the AR System Customizable Home

Page form. See Specifying a home page on the server on page 458.

Defining form views for the customizable home page


Forms that will appear in panels in the customizable home page must be designed to behave correctly when the browser window is resized and to optimize performance when the home page is loaded or refreshed. Use the following best-practice guidelines when you design a form view for use in a home page panel: Use a display-only form designed for this purpose. To optimize performance when the home page loads, avoid using a new view of a large and complex existing form. For performance reasons, minimize the form size, using as few fields and workflow definitions as possible. Add a single field to hold the data that will appear in the home page panel. For example, add a table field to display records from another form, or a data visualization field to display a flashboard. Use chunking for table fields. Use field types that respond well to resizing. These include table fields, tree fields, view fields, data visualization fields, and panel holder fields.

444

Form and Application Objects Guide

Using the AR System Customizable Home Page

In the Appearance properties for the form view, set the Layout Style property to Fill. This allows the field contents to expand and shrink as the panel changes size. If the field is a panel holder, make sure that the Layout Style property for the panel showing the main data content of the form is also set to Fill. In the view properties, set the Results Banner and Web Toolbar properties to Hidden. Avoid creating forms for the customizable home page that support user data editing. The panel display size is variable, and pop up editors can be clipped by the panel that is hosting the form. Avoid using workflow that fires on window open, load, or display. Doing so can cause unneeded queries to the AR System server. If multiple items of data are needed to render the form, use a Service workflow action call to combine these queries into a single call to the server. Use workflow to automatically populate data in the display-only form. Alternatively, add a Refresh button to the form to allow the user to update the data manually.

Defining form descriptors


For each form that will be available to appear in a home page panel, you must create an entry in the AR System Home Page Descriptor form, shown in Figure 14-5. The entries in the descriptor form supply two sets of menus: When the user needs to change the form that appears in a panel on the customizable home page, a menu of the available descriptors appears. When you define a default layout in the layout form, a menu appears in each panel, allowing you to select the descriptor for each form that will appear by default.

Chapter 14

Defining entry points and home pages

445

BMC Remedy Action Request System 7.6.04

Figure 14-5: The AR System Home Page Descriptor form

To create a home page descriptor


1 Open the AR System Home Page Descriptor form in New mode. 2 Complete the fields in the form as described in Table 14-2.

446

Form and Application Objects Guide

Using the AR System Customizable Home Page

3 Save the descriptor. Table 14-2: Administrator-defined fields in the AR System Home Page Descriptor form Field name Content ID Description Enter a unique name for this descriptor. This name appears in the Layout form when you are selecting the descriptors for a default layout. The best practice is to use a locale-independent Content ID. To do this, enter the same Content ID for all descriptors that represent the same content, with unique values in the Locale field. This allows AR System to localize the descriptors based on the Locale field entry in the descriptor form. Category Type or select the category for this descriptor. Categories that you have entered in other Descriptor form records appear on this dropdown menu. Categories provide a level of organization for the descriptor menus. For example, Help Desk form descriptors might be grouped together in a category. Label Enter a label for the descriptor. The label appears in the results list when you search the descriptor form, and in the panel selection menu on the layout form. Enter a title for the descriptor. The title appears in the form selection menu in the customizable home page panel. This is the title that users will see when selecting a form to appear in the panel, so use a name that will clearly identify for the user the information that will appear in the home page panel. Type or select the form name associated with this descriptor. This is the form that will appear in the home page panel. (Optional) Type the name of the form view to use in the home page panel, if not the Default Admin View. Select all groups that have permission to use this descriptor in a home page panel. The value in this field should match the locales of the localized views and data supported by any applications installed on the server. If the descriptor is to be used with the default locale of the server, leave this field blank. If the descriptor is to be used in another locale, enter the twocharacter locale value, such as fr for French. For locales where country-specific locales are supported for the same language, and these are supported consistently across the applications installed, enter the full locale specifier. For example, enter pt_BR for Brazilian Portuguese. Status Select the current status for this descriptor: ActiveThe descriptor can be used in a home page panel InactiveThe descriptor is not available for use in a home page panel PendingThe descriptor is not available for use in a home page panel and is pending review.

Title

Form View Groups Locale

Chapter 14

Defining entry points and home pages

447

BMC Remedy Action Request System 7.6.04

Defining default layouts


This section describes how the administrator defines Default layouts. To define the layout and identify which forms will appear in the home page panels by default, you must create at least one entry in the AR System Home Page Layout form. The AR System Home Page Layout form can contain two types of entries, defined by the Type field: DefaultAll layouts defined by the administrator are of this type. Each administrator-defined Default layout is the default for a given group and priority assignment. For all Default type layouts, the User field value is Any. In other words, AR System ignores this field when the layout type is Default. CustomWhen a user modifies the layout of his or her home page and saves the modified layout, it is saved as a Custom type entry in the form. The user is identified in the User field. Each user can have only one Custom layout. Do not attempt to create or modify Custom entries in the Layout form. These entries are managed by workflow. If you delete a Custom entry, the users layout returns to the Default for that user. You can define different Default layouts to be used by different access control groups. When any user logs in, the home page layout that appears is controlled by the users group membership. If a user is a member of more than one group with a defined layout, the conflict is resolved by the priority setting.

To create a default layout


1 Open the AR System Home Page Layout form in New mode. 2 Complete the fields in the form as described in Table 14-3. 3 Save the layout. Table 14-3: Administrator-defined fields in the AR System Home Page Layout form Field name Banner Title Page Title Priority Description Enter the title that appears in the upper-left corner of the home page. (Optional) Enter a subtitle for the home page, if any. It appears just below the banner title. Enter the priority for this Default layout. Priority is used to resolve conflicts when a user belongs to groups that have different default layouts. In this case, the layout with the lower value in the Priority field is used. See Assigning group and priority settings to layouts on page 449. Select the groups that will use this Default home page layout. Permission to layouts is controlled by row level access on the layout form.

Groups

448

Form and Application Objects Guide

Using the AR System Customizable Home Page

Field name Locale

Description (Optional) Use this field only to localize the Banner Title and Page Title for the layout. If you create separate versions of the layout for each locale, you must make sure the layout definitions are consistent and complete, following these guidelines: You must create a separate layouts for every locale If the layout is to be used with the default locale of the server, leave this field blank. If the layout is to be used in another locale, enter the twocharacter locale value, such as fr for French. For locales where country-specific locales are supported for the same language, and these are supported consistently across the applications installed, enter the full locale specifier. For example, enter pt_BR for Brazilian Portuguese. Alternatively, to perform all localization based on the descriptor form entries, leave this field blank in the Layout form and use the same Content ID for descriptors that represent the same content, as described in Table 14-2 on page 447. In this case, you cannot localize the Banner Title and Page Title for the layout.

Layout Application List Initial State

For each panel in the home page, select a descriptor to identify the form that will appear in the panel for the Default layout. Select whether or not the application list on the home page is expanded when the user opens the home page. ExpandedThe application list appears as a navigation bar on the left side of the home page. CollapsedThe application list is hidden, but can be expanded by the user.

Assigning group and priority settings to layouts


The Default layout that appears for a user at login time is controlled by group membership. For example, you might create one home page layout for the group HelpDesk and a different home page layout for the group Infrastructure. However, if a user belongs to both of these groups, AR System must determine which Default home page layout to use when the user logs in. This is the purpose of the Priority field. In case of a group conflict, the layout with the lowest value in the Priority field is used. For example, if the Default layout assigned to the HelpDesk group has priority 3, and the Default layout assigned to the Infrastructure group has priority 4, a user belonging to both groups will see the layout for the HelpDesk group. If more than one Default layout exists for the same group at the same priority level, either home page layout might appear. As a best practice, configure a Default layout with a high number in the Priority field (such as 10), with Group permission assigned to Public. This layout acts as a true default home page for any users that dont belong to groups with specified Default layouts.

Chapter 14

Defining entry points and home pages

449

BMC Remedy Action Request System 7.6.04

Another good practice is to use 1 as the lowest value for layouts assigned to groups. This reserves the priority setting of 0 for use by the administrator, so you can test a layout before making it available. To test a layout, enter the Administrator group in the Groups field for the layout being tested, and set the priority to 0. In this case, only members of the Administrator group will see this layout, and it will have highest priority when a member of Administrator logs in.

Laying out the panels


In the Layout area of the AR System Home Page Layout form, shown in Figure 14-6, you control how many panels appear on the home page, and which form descriptors appear by default. The user can select other forms to display in a panel from the list of descriptors, but cannot add panel areas to the home page.
Figure 14-6: The Layout area of the AR System Home Page Layout form

By assigning descriptors to the panels, you determine which panels are used on the home page: A single panel expands to fill the home page panel area. Two panels can appear horizontally or vertically. If you assign descriptors as shown in Figure 14-6, the two panels will be tiled horizontally on the home page. If you assign descriptors to the two top panels, they will be tiled vertically. For three panels, you can have one panel on the left and two on the right, or viceversa. There is no layout using one panel above and two below, or two above and one below.

Using the Home Page form


The Home Page form is also installed with AR System. You can use it instead of the AR System Customizable Home Page if appropriate. You can modify the Home Page form or create you own form to use as a home page.

To modify the Home Page form


1 Open the default Home Page form. 2 Select the Application List field. 450 Form and Application Objects Guide

Creating a home page form

3 In the Properties tab, set the values to define how you want the Application Field

to appear, for example, if you want a border or scroll bars to be displayed.


4 In the Properties tab, set the Permissions value to define which groups should have

access to the Home Page form.


5 Choose Form > Form Properties, and change the permissions of the Home Page

form as needed.
6 Save your changes.

Creating a home page form


To create a home page form
1 Open or create the form you want to use as your alternate home page form. 2 Add an Application List field to display your entry points.

You can include an Application List field in any AR System form.


3 Set your preferences to configure which entry points appear in the Application List

field on your home page form.


a Open the AR System User Preference form in a browser or BMC Remedy User,

and click the Home Page tab. You can also use define BMC Remedy User settings by choosing Tools > Options to open the Options dialog box.
b Specify the server that the home page form resides on. c Specify the default Home Page form. d (For BMC Remedy User only) In the Object List field, select how you want users

to interact with the home page. For example, if you select Disable, the Object List menu item and icon is disabled, and users must use the Home Page to access forms and applications. For more information, see: Understanding how a home page appears in BMC Remedy User on page 461 Understanding how a home page appears in a browser on page 459
4 Display the home page.

For BMC Remedy User, log out and log back in. To display the home page after you close it, choose File > Open > Home. In a browser, enter the following URL:
http://hostName/arsys/home

For example:
http://server1/arsys/home

Chapter 14

Defining entry points and home pages

451

BMC Remedy Action Request System 7.6.04

Using style sheets with application list and navigation fields


You can use style sheets to customize the appearance of the Application List and navigation fields in a browser or BMC Remedy User. A style sheet named arsystem.css is located in the BMC Remedy User installation folder. Each user using that installation folder has the styles in the style sheet. For the Web, another arsystem.css style sheet determines the appearance of all fields (not only the Application List and navigation fields). This file is in the midTierInstallDir\resources\ folder.

NOTE
You should be familiar with HTML and Cascading Style Sheet (CSS) files before editing style sheets. An excellent background resource is the MSDN Library website (http://msdn.microsoft.com/en-us/library/default.aspx). See especially the sections on HTML, Dynamic HTML, and CSS Attributes. Although browser attributes are similar, they are not exactly the same. Not all attributes work with every browser.

Using style sheets with BMC Remedy User


Users can edit the arsystem.css style sheet in their installation folder to change fonts, colors, attributes, and other properties of the Application List field.

NOTE
The arsystem.css file replaced the appfield.css (or ARSystemApplist.css) file, which was used before version 7.0.00. If you customized the appfield.css file, copy the customizations to the arsystem.css file after you upgrade BMC Remedy User. After users save their changes to the style sheet, they do not see changes to the Application List field immediately because it is generated at runtime. The next time they open the home page, the edited style sheet is applied to the Application List field. Users do not have to log out and log back in to see the change.

NOTE
Do not rename the style sheet. BMC Remedy User expects the arsystem.css file to be present in the installation folder. The style sheet is updated with every installation of BMC Remedy User. If you customize the file, you must reapply your changes after an upgrade of BMC Remedy User. The installer creates a backup of your previous style sheet, so the customizations are not lost.

452

Form and Application Objects Guide

Using style sheets with application list and navigation fields

To use style sheets in BMC Remedy User


1 Open the home page in BMC Remedy User to view the default settings of the style

sheet.
2 Open the arsystem.css style sheet in a text editor.

The arsystem.css file for each user is located in your BMC Remedy User installation directory folder.
3 Edit any of the attributes as needed.

You must use the defined style classes (for example, .HomeListAppFirstStyle). You can add any available style to these classes. Make sure you use the correct syntax, adding semicolons after an attribute, valid font families, correct color or RGB settings, and so on. Edit the font family, font size, and add a color to the style, for example:
.HomeListAppFirstStyle {font-family:Century Gothic; fontsize:10pt; font-weight:bold; color: red;} 4 Save your changes. 5 Close your home page (or the form containing the Application List field). 6 Open the home page.

The new attributes you defined appear in the Application List field.

Using style sheets with a browser


Most of the common styles displayed in the browser are defined in
midTierInstallDir\resources\standard\stylesheets\ARSystem.css. AR System provides individual arsystem.css style sheets for the MS Internet Explorer (..\resources\stylesheets\resources\ie\stylesheets) and Mozilla (..\resources\stylesheets\resources\moz\stylesheets) browsers if there are browser-specific styles to define. When you edit these style sheets, you are making changes to the entire mid tier, not only to a particular application.

When you open the home page in a browser, the browser automatically applies the appropriate style sheet. Users can then edit this style sheet to change fonts, colors, attributes, and so on. For more information about ARSystem.css for the mid tier, see the BMC Remedy Mid Tier Guide, Default style sheets provided with AR System, page 58.

Chapter 14

Defining entry points and home pages

453

BMC Remedy Action Request System 7.6.04

To use style sheets with application list fields for a browser


1 Open the home page in your browser. 2 Open the ARSystem.css style sheet for browsers in a text editor. 3 Edit any of the attributes as needed.

You must use the defined style classes (for example, td.FIRSTAPPNAME). You can add any available style to these classes. Make sure you use the correct syntax, adding a semicolon after an attribute, valid font families, correct color or RGB settings, and so on. Edit the font family, font size, and add a color to the style, for example:
td.FIRSTAPPNAME { font-family:'Century Gothic'; font-size:10pt; font-weight:bold; color:deeppink; } 4 Save your changes. 5 Refresh your home page in the browser.

The new attributes you defined appear in the Application List field.

Viewing a subset of entry points


For deployable applications, you can display a subset of applications and entry points to users by creating workflow that uses a reserved field ID.

NOTE
In the default Home Page form installed with AR System, there is a hidden reserved field named AppSubset (field ID 1576). You only need to add the necessary workflow to use it. You might want to hide the reserved field on most form views. If you set its field values with the Window Loaded execute condition, the Application List field is populated automatically with the subset of entry points when the window becomes loaded. The following procedure adds a special character field (the reserved field used to configure the list of entry points) and a button to a form. It then uses Run Process workflow to dynamically display a subset of servers and applications. To test this functionality, create multiple applications and entry points, or use multiple AR System servers.

NOTE
If you use multiple servers on the Web, add servers using the BMC Remedy Mid Tier Configuration Tool. See Specifying a server for the mid tier on page 458.

454

Form and Application Objects Guide

Viewing a subset of entry points

To create sample workflow to view a subset of entry points


1 Add a character field to your home page and name it AppSubSet. 2 In the Properties tab, enter 1576 as the value for the ID property.

This value creates a special reserved field ID. If this field contains a value, only the entry points for these applications and servers are displayed. Most likely, you will want to set this value dynamically through workflow.
3 Add a button field to your form and name it Show All Entry Points. 4 Save your changes to the form. 5 Create an active link with the following conditions:

Associated Forms panel: Add your home page form. Execute Options panel: Enter Show All Entry Points in the Button/Menu field.
6 Create a Run Process If action with the following Run Process syntax: PERFORM-ACTION-HOME-FIELD-REFRESH 7 Save your active link. 8 Display your home page form.

All the entry points in the Application List field are displayed. But when you enter a value into the Configuration Field and click the Show All Entry Points button, you see a subset of entry points. For this example, two servers were used (polycarp and mirepoix). The Application List field on this sample home page contains a list of all the entry points this user can see that are available on these two servers.
Figure 14-7: Complete list of entry points

9 Enter the following syntax into the AppSubSet field to display a subset of servers

and applications. Separate applications and servers by commas.


serverName.applicationName, serverName.applicationName

Chapter 14

Defining entry points and home pages

455

BMC Remedy Action Request System 7.6.04

Enter a backslash (\) escape sequence in the syntax if the application name uses a comma or period. For example, if the application is named Help.Desk on server polycarp, the escape sequence is as follows:
polycarp.Help\.Desk

Enter serverName to display all the entry points and applications that the user has permissions to access on serverName. Or, enter serverName.applicationName to display a subset of applications on a specific server. For example, if you entered the following text and clicked Show All Entry Points:
polycarp.MusicManager Application

The Application List field is redisplayed with only the entry points from the MusicManager application on the server polycarp.
Figure 14-8: Subset of entry points

Home page navigation aids


You can use the following functionality to allows users to navigate their way back to their home page: Add a home page form action field to the form Create run process workflow that returns to the home page

BMC Remedy Useradding a home page form action field to a form


The easiest way to navigate users back to the home page from a form is by adding a Home Page form action button to the form. Forms displayed in a browser include the Home button as a required form action field in the toolbar. (For more information, see the BMC Remedy Mid Tier Guide, Adding form action fields to a form, page 70.) When a user clicks the home page button in BMC Remedy User, the home page window is brought to the front if that window is already open. In a browser, the home page always opens in a new window.

456

Form and Application Objects Guide

Configuring home page preferences

To add a Home Page form action field to a form


1 Open the form in BMC Remedy Developer Studio. 2 Choose Form > Add Form Action Fields. 3 From the list of Form Action Fields, select Home Page.

The Home button appears on your form.


4 Position the Home button as needed. 5 Save the form.

Creating run process workflow that returns to the home page


Adding a Run Process command to workflow provides more flexibility than simply adding a Home Page form action button to a form. For example, you can create an entry point guide that opens a form and lets users perform specific tasks. The last action in the guide can be a Run Process action that returns the user to the home page. The following procedure illustrates the Run Process workflow by creating your own home button.

To create run process workflow that returns to the home page


1 Add a button field to your form and name it Go Home. 2 Save the form. 3 Create an active link that executes on the Go Home button. 4 Create a Run Process If action with the following Run Process syntax: PERFORM-ACTION-GO-HOME 5 Save the active link.

For more information about workflow, see the Workflow Objects Guide.

Configuring home page preferences


The following sections describe configuration settings for using a home page. This information is important to understanding which form is displayed as a home page.

TIP
Both BMC Remedy User and the mid tier use a hierarchy of values to resolve which home page form to open on what server. The particular settings specified in the AR System User Preference form override the global server and configuration settings.

Chapter 14

Defining entry points and home pages

457

BMC Remedy Action Request System 7.6.04

Specifying a home page on the server


The Default Home Page setting lets you specify which form to display as home page. The server containing the form must also be specified as the home page server in the Mid Tier configuration tool. If a different server is designated as the home page server, for example, in user preferences, this setting is ignored. This setting allows you to define a home page form for particular groups of users, and customize the content and look of the form. For example, you can add a character field that displays the applications and servers in the Application List field.

To specify a home page in the AR System Administration: Server Information form


1 From the BMC Remedy AR System Administration Console, open the AR System

Administration: Server Information form.


2 Select the Configuration tab. 3 In the Default Home Page field, select the home page that you want to use system-

wide. Select the AR System Customizable Home Page form to allow users to customize the forms that appear in panels on home page. Select the Home Page form to use the traditional AR System home page. Select a form that you designed. The form must include an Application List field. See Using entry points in applications on page 442.
4 Click OK.

For more information about configuring a home page server, see the Configuration Guide, Server InformationConfiguration tab, page 128.

Specifying a server for the mid tier


If you are using a home page in a browser, this global setting lets administrators configure the mid tier with the AR System server that contains the home page form.

To specify a server for the mid tier


1 Open the BMC Remedy Mid Tier Configuration Tool from the following URL: http://hostName/arsys/shared/config/config.jsp 2 Click the General Settings link. 3 From the Homepage Server menu, select the AR System server that you want to

run against the mid tier.

458

Form and Application Objects Guide

Configuring home page preferences

4 If you use the subset reserved field (ID 1576) in your workflow and you use a

combination of fully qualified domain names and relative host names, add all the variations of server names to AR Server Settings. For example, add the server names arserver, arserver.staff.acme.com, arserver.acme.com, and arserver.acme2.com. For more information about the subset field, see Viewing a subset of entry points on page 454.
5 Save your changes.

Understanding how a home page appears in a browser


When you enter the home page URL (http://hostName/arsys/home) and then log in to AR System, the mid tier uses the following sequence to determine which home page form is displayed in the browser. Remember that on the Web, the mid tier can be configured to have multiple preference servers. Suppose that the AR System User Preference form is configured to use the server1 server and the HelpDesk form as the home page form.
Step 1 The mid tier checks the home page server that is defined on the Home Page tab of

the AR System User Preference form. If you defined a home page server in user preferences, the mid tier uses this setting to search for a home page form. For more information, see Specifying a server and home page in the AR System User Preference form on page 462.

NOTE
If you do not create an entry in the AR System User Preference form, the mid tier creates a default record for you, but it does not populate the fields relevant to the home page settings. These are left blank by default.
Step 2 If no user preference is defined, the mid tier checks the home page server setting

in the Configuration Tool. If there is no configuration setting, the mid tier displays an error. In this example, the mid tier found the server server1 in step 1. The mid tier then checks for available home page forms. You define preference servers by clicking Home Page Settings in the Configuration Tool. For more information, see Specifying a server for the mid tier on page 458.
Step 3 If the mid tier locates a home page form defined in your user preferences, the

browser displays it as your home page. In this example, the user preference was not the default Home Page form installed with AR System, but HelpDesk, an alternate home page form. The browser opens and display HelpDesk as the home page.

Chapter 14

Defining entry points and home pages

459

BMC Remedy Action Request System 7.6.04

Step 4 If you did not specify a home page in your user preferences, the mid tier searches

for a home page form on the server defined in step 1 and step 2. When a home page is found and opened, the mid tier has compiled a list of entry points from all the servers listed in the AR Server Settings in the Configuration Tool and displays them in the home pages Application List field. If two applications have the same name, the mid tier displays their server name as well, as shown in Figure 14-9.
Figure 14-9: Application list field displaying applications with same name

If such a form cannot be found, the mid tier displays an error and no form is opened in the browser.

NOTE
The entry point labels that appear in the application list field are also determined by the form views. You must set the correct view label to expose, for example, a web view of the forms entry points. Otherwise, you might define an entry point that is not displayed properly in your web view. The system displays views based first on the view label and then the locale. For more information, see How a form view is selected for the user on page 394. For more information about configuring home page servers, see the Configuration Guide, Home Page tab, page 104.

460

Form and Application Objects Guide

Configuring home page preferences

Understanding how a home page appears in BMC Remedy User


When you log in to AR System, BMC Remedy User uses the following sequence to determine which home page form is displayed. Suppose that the AR System User Preference form is configured to use the server1 server and the HelpDesk form as the home page form.
Step 1 If you are accessing BMC Remedy User with a preference server, BMC Remedy

User checks the server that is defined as a user preference on the Home Page tab of the AR System User Preference form. If you are using a preference server and you configured a home page server, BMC Remedy User uses this setting to search for a home page form. With BMC Remedy User, the user preference is optional. For more information, see Specifying a server and home page in the AR System User Preference form on page 462.
Step 2 If you did not define any user preferences, BMC Remedy User checks for the home

page options defined in the Options dialog box (Tools > Options).
Step 3 If no options are defined in the Options dialog box, BMC Remedy User checks for

the preference server specified in the Login dialog box.


Step 4 If no preference server is defined, BMC Remedy User uses the first server in the

login list as an alternative. In this example, suppose the server found server1 in step 1. The server then checks server1 for available home page forms.
Step 5 If the server locates a home page form defined in your user preferences,

BMC Remedy User opens and displays it as your home page. In this example, the user preference was not the default Home Page form installed with AR System, but HelpDesk, an alternate home page form. BMC Remedy User opens and displays HelpDesk as your home page.
Step 6 If you did not specify a home page in your user preferences, BMC Remedy User

uses the Default Home Form defined on the Configuration tab in the AR System Administration: Server Information form. For more information, see Specifying a home page on the server on page 458.
Step 7 If you did not configure a home page form on your server, BMC Remedy User

searches for the first form it can find that has an Application List field.
Step 8 If such a form cannot be found, BMC Remedy User checks the next server in your

login list and then repeats step 6 and step 7.


Step 9 If BMC Remedy User checks all the servers in your login list and cannot find any

home page form, no form is opened in BMC Remedy User and a warning is returned (ARWARN 1898).
Chapter 14 Defining entry points and home pages 461

BMC Remedy Action Request System 7.6.04

For BMC Remedy User, the server compiles a list of entry points from all the servers in your login list and displays them in the home pages Application List field. If two applications have the same name, BMC Remedy User displays their server name as well, as shown in Figure 14-9.
Figure 14-10: Application list field displaying applications with same name

Specifying a server and home page in the AR System User Preference form
Although a default Home Page form is installed with the AR System, you can define a different home page. Your user preferences override both the global server settings and mid tier configuration options. These user preferences allow you to define a customized home page form for particular groups of users (for example, Marketing and Engineering). You can also specify one home page for each user. For example, people working primarily in Marketing can see one home page. But if they communicate frequently with Engineering, they can have access to engineering applications, and the home page they see can be appropriately customized.

NOTE
With BMC Remedy User, user preferences are optional. With the mid tier, if you do not set any user preferences for your users, default values are not returned from the server or form. However, use the BMC Remedy Mid Tier Configuration Tool to define a mid-tier server and set the home page form for the server. For more information, see Specifying a server for the mid tier on page 458.

462

Form and Application Objects Guide

Configuring home page preferences

To specify a server and home page in the AR System User Preference form
1 Open the AR System User Preference form in BMC Remedy User or a browser.

NOTE
You can also define these preference settings through the Options dialog box. Choose Tools > Options, and click the Home Page tab.
2 Click the Home Page tab. 3 Specify the server the home page form resides on. 4 Specify the default Home Page form. 5 Select how you want users to interact with the home page.

For example, selecting Disable in the Object List field hides the menu item to access the Object List. For backward compatibility, the Object List familiar to those who know BMC Remedy User is still available (choose File > Open > Object List). You can also choose to show or hide this dialog box through these user preference settings.
6 Click Save.

Suppressing automatic opening of home pages in BMC Remedy User


You can suppress the home page automatically opening in BMC Remedy User in two different ways: Using the AR System User Preference form Using the Options dialog box If you use the Options dialog box, these changes are automatically saved in an entry in the AR System User Preference form.

To suppress home pages through user preferences


1 Log in to BMC Remedy User. 2 Open the AR System User Preference form. 3 Perform a search for the preference entry of a login name. 4 Click the Home Page tab. 5 In the Open Home Page Automatically field, click No to disable the home page.

The default setting is Yes.


6 Save your changes.

You must log in again to see your changes take effect. The server on which the AR System User Preference form resides must be specified as the preference server when you log in.

Chapter 14

Defining entry points and home pages

463

BMC Remedy Action Request System 7.6.04

To suppress home pages through the Options dialog box


1 Log in to BMC Remedy User.

Observe how the home page automatically opens.


2 Open the Options dialog box. 3 Click the Home Page tab. 4 In the Open Home Page Automatically field, clear the Open Home Page

Automatically check box. The default setting is Yes.


5 Save your changes.

You must log in again to see your changes take effect.

464

Form and Application Objects Guide

15

Chapter

Defining packing lists

A packing list is a container of objects that acts as a list. A developer can use a packing list to organize objects during the development phase. For example, if you add all forms and workflow that together perform a function into a packing list, it is easy to find all the related objects later when you need to add or revise the functionality. The following topics are provided: Using packing lists (page 466) Creating packing lists (page 466) Saving packing lists as XML import/export command files (page 469)

Chapter 15

Defining packing lists

465

BMC Remedy Action Request System 7.6.04

Using packing lists


You can construct a packing list to create and apply external utilities, such as installation utilities or external object browsers. In addition, you can use packing lists to gather information about specified objects and manipulate those objects.

NOTE
If you use the Distributed Server Option (DSO), you cannot track DSO mappings that were renamed. Packing lists can track only server objects with database IDs. DSO mappings are not server objects, so they are not tracked by their database ID, but by their actual names. Therefore, if you change a DSO mappings name and then open a packing list that contained that mapping, the DSO mapping is missing from the packing list.

Creating packing lists


Use the following procedure to create a packing list.

To create packing lists


1 In AR System Navigator, expand serverName > Packing Lists. 2 Right-click Packing Lists, and choose New Packing List.

A new packing list opens.


Figure 15-1: Packing List

3 Enter a Label and Description for the packing list.

You cannot enter more than 255 characters in the Label field or more than 2000 characters in the Description field.

466

Form and Application Objects Guide

Creating packing lists

4 Add the packing list objects. a Click Add. b In the Add Items dialog box, select the objects you want to add.

To view from more than one object category, click Select All in the Filtering Options area. Use the CTRL and SHIFT keys to select more than one item from the Available Objects list.
Figure 15-2: Adding items to a packing list

c From the Add Items with Related Property list, select the appropriate option for

your packing list: Object OnlyAdd only the selected objects (and not their related objects). Directly Related ObjectsLimits the scope of server objects when shared workflow is added to the packing list. See the table in Table 15-1 on page 468. All Related ObjectsAdds all selected objects and their related objects.
d Click OK.

Chapter 15

Defining packing lists

467

BMC Remedy Action Request System 7.6.04

5 In the Properties tab, set the values for the following properties, as needed:

Help Text New Description (a description for Change History) Owner Permissions Subadministrator Permissions
6 Choose File > Save. 7 In the Save Packing List As dialog box, enter a name.

Packing list names must be unique on each AR System server. Although there are no naming conventions, create names that provide meaningful descriptions of the packing list. Names can be a maximum of 80 characters, including spaces. Names can include double-byte characters, but avoid using numbers at the beginning of the name. Names are shared across packing lists, active link guides, filter guides, web services, and applications, so each name must be unique.

Directly related objects that are added to a packing lists


If you select Directly Related Objects when adding objects to a packing list, the packing list includes related objects as described in the following table.
Table 15-1: Related objects in a packing list (Sheet 1 of 2) For: Forms Packing list includes: All related menus, active links, filters, escalations, active link guides, filter guides, web services, and distributed mapping definitions. In addition, menus from the Change Field action of the active links are included. Any other forms referenced in workflow actions, guides, and menus are not associated as related objects. All forms that were used to create these join forms as well as their related items (as defined in the operations included in the Forms above). All menus that are referenced in the Change Field actions, and all guides that are referenced in the Call Guide action. The guides should see the same form to which the active link refers. The active links that are referenced in the guide also fall within the same scope; therefore, the associated objects of those active links are included. This cycle continues until it reaches a form. All filter guides referenced in a Call Guide action and all DSO mapping definitions referenced in a DSO action. Filters that are referenced in the guide also fall within the same scope; therefore, the associated objects of those filters are included. The guides should see the same form to which the filter refers. Escalations do not have any of the above actions, so there are no associations for escalations. All active links referenced in the guide as well as all associated objects for those active links.

Join forms

Active links

Filters

Active link guides

468

Form and Application Objects Guide

Saving packing lists as XML import/export command files

Table 15-1: Related objects in a packing list (Sheet 2 of 2) For: Filter guides Applications Web Services Menus Groups Flashboards Images Packing list includes: All filters referenced in the guide as well as all associated objects for those filters. All associated forms and the list of related objects associated with those forms. Included as an independent object. No related items included. Included as an independent object. Included as an independent object. Included as an independent object.

Saving packing lists as XML import/export command files


In addition to exporting a packing list like any AR System server object, you can save a packing list to an XML import/export command file. You can use the XML file with the import and export command line interfaces to import or export the objects in the packing list.

To save a packing list as import/export commands


1 In the Packing Lists branch of the server branch in the AR System Navigator, right-

click the name of the list and choose Save as Import/Export Commands
2 In the Save as Import/Export Commands dialog box, select or enter a file to write

the import/export commands.


3 Click Save to create the file.

For information about the import/export CLIs and the use of this XML file, see the Integration Guide, Exporting and importing data and definitions, page 233.

Chapter 15

Defining packing lists

469

BMC Remedy Action Request System 7.6.04

470

Form and Application Objects Guide

Appendix

Core fields

This section describes the AR System core fields and their uses. The following topic is provided: Core fields (page 472)

Appendix A Core fields

471

BMC Remedy Action Request System 7.6.04

Core fields
AR System core fields are a set of fields that every regular form must have. You can include these fields in other forms; if present, the fields follow the same rules and have the same meanings. The commonality gained by such a convention is useful for conceptual consistency, sharing definitions, and exchanging and merging databases. Additional limits are placed on the core fields, including the fact that some fields are required, others are maintained by the system, and others have fixed or maximum sizes. Core fields generally appear on every regular form to make sure that all forms share a common set of concepts. AR System automatically includes core fields on all regular forms. Because display-only forms and joins do not directly store data in the database, core fields are not required for these types of forms. Core fields are also not required for view and vendor forms because they map to external data sources, which might not have these fields. Core fields help provide consistency when merging and sharing data. Core fields significantly aid in the construction of solutions based on AR System. You cannot delete core fields from regular forms although you can modify their appearance by altering labels, adding or changing menus, altering the display type, altering their location, or hiding them from view. The following table lists the AR System core fields.
Table A-1: AR System core fields (Sheet 1 of 2) ID 1 Field name Request ID Description A unique identification value for each request in the system. Groups that have neither Change nor View access to the Request ID field do not have access to any other form information, regardless of the permission settings of the other fields. Data Type: Character Length: 515 For join forms, there is no limit to the number of layers of joins that AR System supports, so the Request ID field of a join form contains more than 15 characters. See Joining three or more forms on page 165 for more information.
Note: Do not change the QBE Match setting to Equal for the Request

ID field. Because AR System adds a prefix and a series of zeros to Request IDs before it begins a search, users cannot run valid QBE searches against Request ID numbers if you set the QBE Match setting to Equal or Leading.

472

Form and Application Objects Guide

Core fields

Table A-1: AR System core fields (Sheet 2 of 2) ID 2 Field name Submitter Description The name of the AR System user who was logged in and submitted the request. This field is tied to the Submitter group when defining row-level security. For more information about row-level security, see Controlling access by using implicit groupsRow-level security on page 38. Submitter is a required field. Data Type: Character Length: 254 3 Create Date The date and time at which the request was created in the system. The AR System server sets this field, and it cannot be modified. Data Type: Timestamp 4 Assigned To The user who is assigned responsibility for the request. This field is tied to the Assignee group when defining row-level security. For more information, see Controlling access by using implicit groupsRow-level security on page 38. Data Type: Character Length: 254 5 Last Modified The name of the user who last altered the request. AR System sets By this field to the login name of the user who last changed the request. It cannot be modified. Data Type: Character Length: 254 6 Modified Date The date the field was last modified. The AR System server sets this field to the time the last change to this request was made. It cannot be modified. Data Type: Timestamp 7 Status Indicates the current state of the request. Users have control over this field. It must have a value at all times; there must be a default value in the event that the user does not specify a value when the request is created. The actual names and values of the status field can be customized. Status is a required field. Data Type: Selection 8 Short Description A brief description of the request. A size limit forces the submitter to be concise. Short Description is a required field. Data Type: Character Maximum Length: 254 15 Status History The user who last made a change, and the time the change was made to each of the states identified by the Status field. AR System sets and maintains this field, and it cannot be modified. If status history recording and reporting is disabled, the status history is cleared and not updated. Data Type: Character

Appendix A Core fields

473

BMC Remedy Action Request System 7.6.04

Core field characteristics


The following core fields have special characteristics that you should consider when defining a new form.

Request ID field
AR System uses the Request ID field (Field ID 1) to provide a unique identification value for each request entering the system. It is created and maintained by the system. To improve the usability of the Request ID field, you can add a prefix to the field to make it more descriptive to your users. For example, in a distributed server environment where you transfer requests from Los Angeles to Chicago, the system can add the prefix LA to requests generated on the Los Angeles server and CHI to requests from Chicago. For more information, see the Configuration Guide, Changing the Request ID field length or prefix, page 336. The Request ID field is fundamental to access control in AR System. Without access to this field, users have no access to the request, even if they belong to groups with access to other fields on the form. Groups that have neither Change nor View access to the Request ID field do not have access to any other form information, regardless of the permission settings of the other fields. For more information, see Using the Request ID field with implicit groups on page 40.

Submitter field
The Submitter field (field ID 2) defines which user created a request. The user who create a request is automatically a member to the Submitter implicit group. See Submitter and Assignee access on page 39. For information about preventing changes to this field, see the Configuration Guide, Enabling submitters to modify requests, page 65.

Short Description field


The Short Description field (field ID 8) provides a common place for users to summarize a request. By default, the Short Description field contents appear in the results pane of a form whenever a search is performed. You might want to include a menu of possible problem and request types for the Short Description field to make request submissions easier and reporting more efficient. For more information, see Chapter 8, Creating menus.

474

Form and Application Objects Guide

Core fields

Status field
Your application can use the Status field (field ID 7) to track the different states a request moves through in its life cycle. The meaning of each individual state helps define the workflow process and you can define any number of states. In addition to keeping track of each state of a request, AR System keeps additional information with the Status field called status history. Status history includes the user name of the person who last changed the state of the request and the date and time that the change occurred. If status history recording and reporting is disabled, the status history is cleared and not updated. Define states carefully. The Status field is the key field that represents the problem resolution process. The states must capture the important steps in the process, although not all states might be used during the life cycle of a single request. A good process is often represented by four or five states. It is difficult to modify the Status field choices after users have begun to use the form, because the data for a selection field is stored in the database as an integer that relates to the order of the choices. For more information about selection fields, see Selection fields on page 376.

Assigned To field
The Assigned To field (field ID 4) enables ownership of each request to be tracked. If requests are designed to pass ownership from one user to another, create workflow that uses the Assigned To field. Users who are assigned ownership to a request are automatically assigned membership in the Assignee group. For more information about the role of the Assignee group in AR System, see Special groups in AR System on page 23.

Appendix A Core fields

475

BMC Remedy Action Request System 7.6.04

476

Form and Application Objects Guide

Appendix

Reserved fields

AR System reserved fields are special-purpose data fields. Some of these fields are used in the User or Group forms. Others are used for assignee group access, the Distributed Server Option, web applications, or localization. You can use certain reserved fields in your forms. When these fields are used in your forms, they retain the special meaning and use as defined in this section. AR System contains fields that are reserved for system use. If you create fields with these IDs, certain actions automatically take place.

WARNING
When a form contains one of a number of combinations of reserved fields, the AR System server identifies it as a key form. For example, a form that contains fields with IDs 101, 102, and 103 is identified as the User form. You must avoid these special combinations of reserved fields to make sure the server does not identify a form incorrectly. For details, go to the Support page on the BMC website at http://www.bmc.com/ support and see Knowledge Base Self Help Document ID 20003599. This section lists the ranges of reserved fields and a description of the fields. The following topics are provided: Reserved field ranges (page 478) Reserved IDs used as placeholders in definitions (page 479) Reserved fields in access control (page 480) Localization reserved field (page 483) DSO reserved fields (page 484) Form action reserved fields (page 486)

Appendix B

Reserved fields

477

BMC Remedy Action Request System 7.6.04

Reserved field ranges


AR System has special ranges of field IDs. Numbers 199 are reserved for core fields. Numbers 100536868911 are reserved for registered fields. The following table lists reserved field ranges that forms and applications use in AR System.
Table B-1: Reserved field ranges ID range 199 101149 150159 200399 450469 600699 700750 800810 820880 900999 10001100 11011399 1500-1525 17001799 20002299 23002699 1000014999 1500015999 1700017399 1800019999 2000039999 4000040499 6000060999 10000001999999 30000003999999 Type of fields, forms, or applications that use the field IDs Core fields Access control fields AR System Message Catalog Distributed Server Option forms Audit fields Business Time forms Alert forms Server Events form Business Time forms Server Statistics form Form Action fields Application Statistics forms Currency forms Roles form Application States Business Time forms Approval Server Option Enterprise Integration Engine Reporting forms Email Engine Preference forms Flashboards Dynamic group fields Global fields (Customers should use 1000000 - 1699999; BMC applications use 1700000 - 1999999.) Window-scoped global fields

478

Form and Application Objects Guide

Reserved IDs used as placeholders in definitions

IMPORTANT
In the Best Practice Customization mode, a warning is displayed when you create or copy fields in the BMC reserved range on an overlay form. This warning states that creating or copying fields may cause a failure in future application upgrades, if the created field conflicts with a similar field introduced during an upgrade. However, this warning is not displayed when you create or copy fields in the BMC reserved range on a custom form. In the Base Development mode, a warning is displayed when you create fields using the field ranges that are outside the BMC reserved range on a base or overlaid form.

Reserved IDs used as placeholders in definitions


Many workflow definitions reference field IDs. In several places, a special reserved ID is used to request a special operation. These fields are described in the following table.
Table B-2: Reserved IDs for special operations ID 97 Field name Description

Set to Defaults Used in Open Windows action to indicate that fields on the opened form should be set to their default settings. Data type: Not applicable Like ID Used in Push Fields and Set Fields actions to indicate mapping of like IDs. Data type: Character Number between 1 and 100 indicating the quality of a match. The closer to 100, the better the match. Data type: Integer Used to display a subset of entry points. This field is hidden on the default Home Page form installed with the AR System. Create this field as necessary on your own home page form. Data type: Character

98

99

Weight

1576

AppSubset

Appendix B

Reserved fields

479

BMC Remedy Action Request System 7.6.04

Reserved fields in access control


The User, Group, and Roles forms contain the reserved fields shown in the following table. These fields are involved in access control. The table lists the form on which the field is defined, but you can add these fields to any form by creating the field and specifying its reserved ID. See Chapter 1, Defining access control, for more information about access control.
Table B-3: Reserved fields for access control (Sheet 1 of 4) ID 101 Field name Login Name Form User Description The name the user enters in the User Name field of the Login dialog box when logging in to the system. Data type: Character Length: 254 102 Password User The password that the user enters when logging in to the system. When a user enters information into this field, the text appears as asterisks (*). Data type: Character Length: 30 (Note that if a 28-character password is entered in the Password field, an error will occur during authentication.) 103 Email Address User The email address of the user. Data type: Character Maximum length: 255 104 Group List User The list of access control groups to which the user belongs. Group names are separated by spaces. Although you make entries to the Group list by using the alias (name for a group), the group IDs are stored as integer values separated by semicolons. Data type: Character Maximum length: 4000 105 Group Name Group The alias by which the access control group is known. This is the name used in the Group list field of the User form and in the Group Permissions list of each form field. Data type: Character Length: 30 106 Group ID Group The ID of the group named in the Group name field. This ID should be greater than 10 for groups that you create. Data type: Integer Range: 0100 (can be expanded)

480

Form and Application Objects Guide

Reserved fields in access control

Table B-3: Reserved fields for access control (Sheet 2 of 4) ID 107 Field name Group Type Form Group Description The maximum permission type intended for the group named in the Group name field. Data type: Selection (None, View, Change) 108 Default Notification Mechanism License Type Full Text License Type User The notification method used if the user specifies the default mechanism. Data type: Selection (None, Alert, Email) User User The type of license that the user has. Data type: Selection (Read, Fixed, Floating) 110 The type of full text search license that the user has. Data type: Selection (None, Fixed, Floating) 112 Assignee Group any The groups or users assigned responsibility for the request. This field is tied to the Assignee Group group when defining rowlevel security. For more information about this type of security, see Controlling access by using implicit groupsRow-level security on page 38. Data type: Character Maximum length: 255 115 Write License Pool User The license pool from which floating write licenses are taken. Data type: Character Maximum length: 30 116 FTS License Pool User The license pool from which floating full text search licenses are taken. Data type: Character Maximum length: 30 117 Authentication Login Name User This field is used for external authentication under certain conditions. For more information, see the Configuration Guide, Setting up an authentication alias, page 76. Data type: Character Maximum length: 254 118 Authentication String User This field is used for external authentication under certain conditions. For more information, see the Configuration Guide, Setting up an authentication alias, page 76. Data type: Character Maximum length: 255 119 Computed Group List User After a search, displays the computed groups the user is associated with. Data type: Character Maximum length: 255 Appendix B Reserved fields 481

109

BMC Remedy Action Request System 7.6.04

Table B-3: Reserved fields for access control (Sheet 3 of 4) ID 120 Field name Form Description The group category, such as Regular, Dynamic, or Computed. Data type: Selection 121 Computed Group Definition Group Boolean statement that defines a computed group. For information about computed groups, see Groups you createRegular, computed, and dynamic on page 25. Data type: Character 122 Application License User For users of licensed applications, the name of the application and the type of license. For more information about licensing applications, see the Integration Guide, Making applications licensable for integration system vendors, page 323. Data type: Character 123 Encrypted String any This field encrypts input text. The resulting encrypted string is 120 characters long. Data type: Character Minimum length: 120 179 Unique Identifier User and Group This field is used internally by applications installed on top of AR System. It replaces field ID 490000000 (Instance ID) in version 6.x. See your product documentation for more information. Data type: Character Maximum length: 38 1700 Application Name Roles Name of the application for which the role is defined. Data type: Character Maximum length: 250 1701 Role Name Roles Name by which the role is known. Data type: Character Maximum length: 255 1702 Role ID Roles Integer ID that is the recognized identity of the role. The ID must be a negative number, such as -10001. Data type: Integer 2001 Test Roles The regular or computed group to which you want to map the role for the Test application state. Data type: Character Maximum length: 255

Group Category Group

482

Form and Application Objects Guide

Localization reserved field

Table B-3: Reserved fields for access control (Sheet 4 of 4) ID 2002 Field name Production Form Roles Description The regular or computed group to which you want to map the role for the Production application state. Data type: Character Maximum length: 255 60000 60999 Dynamic groups any The roles, groups, or users assigned responsibility for the request. This field is tied to a dynamic group when defining row-level security. For more information about this type of security, see Controlling access by using implicit groupsRow-level security on page 38. Data type: Character Maximum length: 255
Note: The ITSM suite of applications uses field

ID 60900 to control multitenancy in certain ITSM forms. Do not use ID 60900 for customizing the ITSM applications. 490000000 Instance ID User and Group Replaced by field ID 179 (Unique Identifier) in version 6.x. This field is used internally by applications installed on top of AR System. See your product documentation for more information. Data type: Character Maximum length: 38 490000100 Object ID User and Group This field is used internally by applications installed on top of AR System. See your product documentation for more information. Data type: Character Maximum length: 38

Localization reserved field


The following reserved field is used for localization.
Table B-4: Localization reserved field ID 160 Field name Locale Description Add this field to a form to localize search menus. The system uses this field to search for requests matching the users locale. For more information, see Appendix H, Localizing AR System applications. Data type: Character Length: 255

Appendix B

Reserved fields

483

BMC Remedy Action Request System 7.6.04

DSO reserved fields


Distributed Server Option can add one or more of the reserved fields shown in the following table.
Table B-5: DSO reserved fields (Sheet 1 of 3) ID 300 Field name To Mapping Description The name of the mapping to use when transferring a request. Data type: Character Length: 254 301 Transfer Status The status of a distributed transfer operation. Data type: Selection (Success, Retry, Failure, Timeout, Canceled) 302 Update Status The status of a distributed update or return operation. Data type: Selection (Success, Waiting, Retry, Failure, Timeout, Canceled) 303 Master Flag A flag indicating whether a request holds ownership (that is, is the master copy). Data type: Selection (No, Yes) 304 Current Form The form in which the master copy of the request resides. Data type: Character Length: 254 305 Current Server The server on which the form with the master copy of the request resides. Data type: Character Maximum length: 64 306 From Mapping The name of the mapping used to transfer this request. Data type: Character Length: 254 307 From Request ID The ID of the request from which this copy was transferred. Data type: Character Length: 15 308 To Request ID The ID of the request to which the data was transferred. Data type: Character Length: 15 309 Mapping History Transfer history informationthe date and time of transfer, source request ID, source form, source server, and the name of the specific mapping used (created at transfer time). Data type: Character Length: Unlimited 310 From Form The form from which a request was transferred. Data type: Character Length: 254

484

Form and Application Objects Guide

DSO reserved fields

Table B-5: DSO reserved fields (Sheet 2 of 3) ID 311 Field name From Server Description The server from which a request was transferred. Data type: Character Length: 64 312 To Form The form to which a request should be transferred. Data type: Character Length: 254 313 To Server The server to which a request should be transferred. Data type: Character Length: 64 314 When to Update The frequency with which to update the original request if a transferred copy is updated. Data type: Selection (Daily, Hourly, Immediately, No Update, On Return) 315 Transfer Mode The type of transfer to perform. Data type: Selection (Copy + Delete, Data + Ownership, Data Only, Independent Copy) 316 Duplicate Entry ID Action The action that occurs if you transfer a request and a request with the same ID already exists in the form specified in the To Form field. Data type: Selection (Create New, Error, Overwrite) 317 Max Time to Retry From Pool The maximum time (in seconds) that the system should retry a distributed operation before canceling the operation. Data type: Integer 318 DSO pool on the source server that processed the distributed operation. Data type: Character Length: 254 319 Enforce Pattern Matching Require Required Fields Flag indicating whether to enforce patterns defined in fields on the target form during distributed operations. Date Type: Selection (No, Yes) 320 Flag indicating whether to require values in fields defined as required fields on the target form. Use this field to enable transfer of an entry with a NULL value in a required field. Date Type: Selection (No, Yes)

Appendix B

Reserved fields

485

BMC Remedy Action Request System 7.6.04

Table B-5: DSO reserved fields (Sheet 3 of 3) ID 321 Field name Matching Qualification Description The qualification used to match a source request with a request in the target form. Data Type: Character Length: 0 322 DSOUniqueID A reserved field (ARDS_RESERV_DISTRIB_UNIQUE_ID) that has characteristics similar to field ID 112. Field ID 322 enables DSO to perform distributed operations on join forms. For more information, see the BMC Remedy Distributed Server Option Guide, Performing distributed operations on join forms, page 81. Data Type: Display-only character Length: Undefined

Form action reserved fields


The following fields are used in web applications to help users perform actions. For more information about form action fields, see the BMC Remedy Mid Tier Guide, Adding form action fields to a form, page 70.
Table B-6: Form action reserved fields (Sheet 1 of 2) ID 706 1001 1002 1003 1004 Field name Alert List Submit Search Modify Modify All Description Displays the alert list. Data type: Table Performs a save operation in New mode to create a record. Data type: Button Performs a search operation. Data type: Button Performs a save operation in Modify mode to save a record. Data type: Button Performs a save operation in Modify mode to save all selected records. Data type: Button 1005 Query Bar Contains the contents of the Advanced Search Bar. Data type: Character Length: Unlimited 1006 1007 Clear Set to Default Clears all data in fields on the screen. Data type: Button Sets the form to the default settings. Data type: Button

486

Form and Application Objects Guide

Form action reserved fields

Table B-6: Form action reserved fields (Sheet 2 of 2) ID 1008 1009 1010 1011 1012 1020 Field name Help New Search New Request Show Status History Home Results List Description Opens help for the form. Data type: Button Changes the form to Search mode. Data type: Button Changes the form to Create mode. Data type: Button Displays the progress made on an AR System request. Data type: Button Displays the form you have configured as your home page. Data type: Button Displays results of a search. Data type: Button

Appendix B

Reserved fields

487

BMC Remedy Action Request System 7.6.04

488

Form and Application Objects Guide

Appendix

Special forms

This section describes the system-defined forms that are loaded during AR System installation. Some of these forms are required for baseline AR System functionality. The following topic is provided: AR System installed forms (page 490) For more information, see the Installation Guide, Locating BMC Remedy AR System files and forms, page 185.

Appendix C

Special forms

489

BMC Remedy Action Request System 7.6.04

AR System installed forms


The following table describes forms loaded as part of the installation of the AR System server. Those forms that have web views are saved with the locale of en_US. If you need a web view of the form in another locale, open the web view of the form on a computer set to the locale you require, and save it. Some of these forms, called system forms, that are required for baseline AR System functionality are maintained by the AR System server. If a system form does not exist when the server starts, it restores the form from a file. System forms are marked in the table.
Table C-1: AR System installed forms (Sheet 1 of 10) Form name Application forms: Application Pending
+

System Description Used for queuing processes and requests. This form works with the Dispatcher thread, which routes requests to the appropriate queues. The Dispatcher wakes up the process that the Application Pending request indicates requires execution. For more information about the Dispatcher thread, see the Configuration Guide, Threads, page 29. Used to monitor and analyze the performance of your deployable applications and forms. For deployable applications, logs entry, filter, and escalation statistics for all forms participating in the application statistics. Also logs application licensing statistics. For forms, logs entry, filter, and escalation statistics. For more information, see the Optimizing and Troubleshooting Guide, Logging application and form statistics, page 17.

Application Statistics

Application Statistics Configuration

Verifies or changes application and form statistics logging settings. For more information, see the Optimizing and Troubleshooting Guide, Logging application and form statistics, page 17.

490

Form and Application Objects Guide

AR System installed forms

Table C-1: AR System installed forms (Sheet 2 of 10) Form name Application forms (continued): AR System Application State + Defines the development state (such as Test or Production) for a deployable application. You can edit the entries in this form in the user client or create workflow that acts on this form to change the applications state. Changing the state changes the access permissions to the application (and to objects owned by the application) according to the role-group mappings defined for each state in the Roles form. See Working with deployable application states on page 97 for more information about application states. SHARE:Application_Interface
+

System Description

Required by the following applications (and their previous versions) to load their systems, sub-systems, and help: ITSM 7.0 suite (AM, CM, IM, PM and DSL) SLM 7.0 Approval Server 7.0.00 Assignment Engine 7.0.00 (Assignment Engine has a load dependency order on other applications that load this form.) Also required by the following applications: Customer Support 6.0 Quality Management applications.

SHARE:Application_ Properties

Required by applications to register their versions and other necessary information, and get the unique identification (GUID) on that server at the time of installation. This information is used by other applications for communication. Enables you to view and modify the AR System server information. For more information, see the Configuration Guide, Configuring AR System servers, page 122.

AR System Administration Console and related forms

AR System Message Catalog

Enables administrators to provide localized versions of error messages, help text, menus, and other text strings displayed to users in applications that are customized by locale. The use of this form can be enabled or disabled. See Appendix H, Localizing AR System applications, for how to use this form.

Appendix C

Special forms

491

BMC Remedy Action Request System 7.6.04

Table C-1: AR System installed forms (Sheet 3 of 10) Form name AR System Object Relationships System Description
+

View forms providing access to the object relationship data recorded when Record Object Relationship is selected on the Configuration tab of the AR System Administration: Server Information form. For more information, see the Configuration Guide, Server InformationConfiguration tab, page 128.

AR System Orchestrator Configuration

Used by administrators to configure the integration between AR System and BMC Atrium Orchestrator. For more information, see the Integration Guide, The AR System Orchestrator Configuration form, page 226.

AR System Resource Definitions AR System Searches Preference

Used to define templates. For more information, see Resources for templates on page 388. Stores searches that users can create and save for a form. Each search is an entry in this form. For more information, see the BMC Remedy Mid Tier Guide, Setting up searches for your end users, page 90.

AR System Server Group Operation Ranking

Stores the ranking of servers for operation ownership within a server group. This form is loaded only when the AR System server is configured to be a member of a server group. .

Assignment Engine forms: ASE:Assignment Association ASE:ProcessRuleForm Assignment Engine Administration Assignment Forms Assignment Processes Assignment Rules Search Rules BMC Atrium Web Services Registry integration forms: AR System Web Services Registry AR System Web Services Registry Pending Delete
+ +

Used to run the Assignment Engine. For more information, see the Configuration Guide, Using the Assignment Engine, page 265.

Used by the integration between AR System and the BMC Atrium Web Services Registry. For more information, see the Integration Guide, Registering a web service, page 80.

492

Form and Application Objects Guide

AR System installed forms

Table C-1: AR System installed forms (Sheet 4 of 10) Form name BMC Remedy Alert forms: Alert